Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

8.0 KB
Raw Blame
/**
 * EXPORT (daemons/LEARNING.md, L2): for plain coding sessions and engines outside Harness, approved skills are
 * also written to the folders the engines read on their own. Opt-in, per destination:
 * `pair.jsonc` `"learn": { "export": ["agents", "claude"] }`.
 *
 *   agents  `~/.agents/skills/<name>/SKILL.md` (Codex, Copilot, Cursor and the others that read Agent Skills)
 *   claude  `~/.claude/skills/<name>/SKILL.md` (`$CLAUDE_CONFIG_DIR/skills` when that is set)
 *
 * Each copy carries `metadata.harness.managed: true`. ONLY a file Harness created is ever updated or removed:
 * the manifest (`export.json` in the lessons folder, not committed) keeps each file's hash, and a file whose
 * content is no longer what Harness wrote — the person edited it — is left alone and forgotten. A folder of
 * that name Harness did not make, a symlink, or a file it did not write is never touched ("taken"). A reverted
 * or archived skill, or a destination taken out of pair.jsonc, is removed the same careful way.
 * `harness pair lessons export --dry-run` says what it would do.
 */
import { createHash } from 'node:crypto'
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import type { ExportDestination } from './types.js'
import { renderSkill, type LessonRecord, type LessonStore } from './store.js'

export interface ExportDirs { agents: string; claude: string }

export interface ExportStep {
  dest: ExportDestination
  name: string
  id: string
  /** write: new; update: ours, changed; keep: ours, current; remove: ours, no longer wanted; skip: not ours. */
  action: 'write' | 'update' | 'keep' | 'remove' | 'skip'
  path: string
  why?: 'taken' | 'edited' | 'symlink' | 'gone'
}

interface ManifestEntry { dest: ExportDestination; name: string; id: string; path: string; hash: string }
interface Manifest { v: 1; entries: ManifestEntry[] }

const sha = (text: string): string => createHash('sha256').update(text).digest('hex')

function isLink(path: string): boolean {
  try { return lstatSync(path).isSymbolicLink() } catch { return false }
}

/** The SKILL.md written into an engine's folder: the lesson's, marked as Harness's. */
export function renderExported(record: LessonRecord): string {
  return renderSkill(record).replace(/^(  harness:\n)/m, '$1    managed: true\n')
}

export interface ExporterDeps {
  store: LessonStore
  dirs: ExportDirs
  /** The destinations pair.jsonc turns on. */
  destinations: () => ExportDestination[]
}

export class LessonExporter {
  constructor(private readonly deps: ExporterDeps) {}

  private get manifestFile(): string { return join(this.deps.store.root, 'export.json') }

  /** What a sync would do, touching nothing. */
  plan(): ExportStep[] {
    const manifest = this.manifest()
    const wanted = new Set(this.deps.destinations())
    const steps: ExportStep[] = []
    const desired = new Set<string>()
    for (const dest of wanted) {
      for (const record of this.deps.store.approved()) {
        if (record.kind !== 'skill') continue
        desired.add(`${dest}:${record.name}`)
        steps.push(this.step(dest, record, manifest))
      }
    }
    for (const entry of manifest.entries) {
      if (desired.has(`${entry.dest}:${entry.name}`)) continue
      const file = entry.path
      if (isLink(file) || isLink(join(file, '..'))) { steps.push({ dest: entry.dest, name: entry.name, id: entry.id, action: 'skip', path: file, why: 'symlink' }); continue }
      if (!existsSync(file)) { steps.push({ dest: entry.dest, name: entry.name, id: entry.id, action: 'skip', path: file, why: 'gone' }); continue }
      const text = this.read(file)
      const ours = text !== null && sha(text) === entry.hash
      steps.push({ dest: entry.dest, name: entry.name, id: entry.id, action: ours ? 'remove' : 'skip', path: file, ...(ours ? {} : { why: 'edited' as const }) })
    }
    return steps
  }

  private step(dest: ExportDestination, record: LessonRecord, manifest: Manifest): ExportStep {
    const dir = join(this.deps.dirs[dest], record.name)
    const file = join(dir, 'SKILL.md')
    const base = { dest, name: record.name, id: record.id, path: file }
    if (isLink(dir) || isLink(file)) return { ...base, action: 'skip', why: 'symlink' }
    const want = sha(renderExported(record))
    const entry = manifest.entries.find((e) => e.dest === dest && e.name === record.name)
    if (!existsSync(file)) {
      if (existsSync(dir)) {
        let empty = false
        try { empty = lstatSync(dir).isDirectory() && readdirSync(dir).length === 0 } catch { /* not a folder */ }
        if (!empty) return { ...base, action: 'skip', why: 'taken' }
      }
      return { ...base, action: 'write' }
    }
    const text = this.read(file)
    if (text === null) return { ...base, action: 'skip', why: 'taken' }
    const disk = sha(text)
    if (entry && entry.hash === disk) return { ...base, action: disk === want ? 'keep' : 'update' }
    if (disk === want) return { ...base, action: 'keep' }        // exactly what Harness writes: adopted
    return { ...base, action: 'skip', why: entry ? 'edited' : 'taken' }
  }

  /** Do what the plan says, and keep the manifest. `dryRun`: only say it. */
  sync(opts: { dryRun?: boolean } = {}): { steps: ExportStep[]; dryRun: boolean } {
    const steps = this.plan()
    if (opts.dryRun) return { steps, dryRun: true }
    const manifest = this.manifest()
    const records = new Map(this.deps.store.approved().map((r) => [`${r.name}`, r]))
    const entries: ManifestEntry[] = []
    const done: ExportStep[] = []
    for (const step of steps) {
      try {
        if (step.action === 'write' || step.action === 'update') {
          const record = records.get(step.name)!
          const text = renderExported(record)
          mkdirSync(join(step.path, '..'), { recursive: true })
          const tmp = `${step.path}.harness-tmp`
          writeFileSync(tmp, text, { mode: 0o644 })
          chmodSync(tmp, 0o644)
          renameSync(tmp, step.path)
          entries.push({ dest: step.dest, name: step.name, id: step.id, path: step.path, hash: sha(text) })
        } else if (step.action === 'keep') {
          const text = this.read(step.path)
          if (text !== null) entries.push({ dest: step.dest, name: step.name, id: step.id, path: step.path, hash: sha(text) })
        } else if (step.action === 'remove') {
          rmSync(step.path, { force: true })
          try { rmdirSync(join(step.path, '..')) } catch { /* something else is in it: it stays */ }
        }
        done.push(step)
      } catch {
        done.push({ ...step, action: 'skip', why: 'taken' })
        const kept = manifest.entries.find((e) => e.dest === step.dest && e.name === step.name)
        if (kept && step.action !== 'remove') entries.push(kept)
      }
    }
    if (entries.length || manifest.entries.length) this.save({ v: 1, entries })
    return { steps: done, dryRun: false }
  }

  /** Whether anything is, or should be, exported: a sync has work to look at. */
  active(): boolean {
    return this.deps.destinations().length > 0 || this.manifest().entries.length > 0
  }

  private read(file: string): string | null {
    try {
      const stat = lstatSync(file)
      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024) return null
      return readFileSync(file, 'utf8')
    } catch { return null }
  }

  private manifest(): Manifest {
    try {
      const parsed = JSON.parse(readFileSync(this.manifestFile, 'utf8')) as Partial<Manifest>
      if (parsed?.v !== 1 || !Array.isArray(parsed.entries)) return { v: 1, entries: [] }
      return { v: 1, entries: parsed.entries.filter((e) => e && typeof e.path === 'string' && typeof e.hash === 'string' && (e.dest === 'agents' || e.dest === 'claude') && typeof e.name === 'string') }
    } catch { return { v: 1, entries: [] } }
  }

  private save(manifest: Manifest): void {
    if (!this.deps.store.exists) return
    const tmp = `${this.manifestFile}.tmp`
    writeFileSync(tmp, JSON.stringify(manifest, null, 2), { mode: 0o600 })
    renameSync(tmp, this.manifestFile)
  }
}