@ai-substrate/engineering-harness 0.2.0

package/harness/cli/dist/acts/new.js

@@ -0,0 +1,66 @@
+import { formatError, formatOk } from '../output/envelope.js';
+import { exitWithEnvelope } from '../output/exit.js';
+import { createOutputPort } from '../output/output-port.js';
+import { scaffoldExtension } from '../services/scaffold/scaffold-service.js';
+/**
+ * Variant-aware "what next". A `--wrap` scaffold already has a working `run()`,
+ * so telling the author to "implement run()" is misleading (MH-003) — point them
+ * at running/reviewing it instead. A minimal stub genuinely needs implementing.
+ */
+function nextActionFor(variant, path, verb) {
+    if (variant === 'record-ts') {
+        return `Edit the template body in ${path}, then run \`harness record ${verb}\`. \`harness doctor\` confirms it loaded.`;
+    }
+    const isWrap = variant.startsWith('wrap');
+    return isWrap
+        ? `Run \`harness ${verb}\` to try it (run() already wraps your command); edit ${path} to tweak. \`harness doctor\` confirms it loaded.`
+        : `Edit ${path} to implement run(), then run \`harness ${verb}\`. \`harness doctor\` confirms it loaded.`;
+}
+/**
+ * Register the `new` command — scaffolds a fresh, loadable extension into the
+ * repo's `.harness/extensions/`. A CORE command (reserved, like `help`/`doctor`,
+ * runs even in `--no-extensions` mode); it owns no business logic — the
+ * `scaffold-service` validates + writes, and this act maps the outcome onto the
+ * Envelope + exit code (ok → 0, error → 1).
+ */
+export function registerNewAct(program, io, deps) {
+    program
+        .command('new')
+        .description('Scaffold a new extension package into .harness/extensions/<name>/ (entry + instructions.md)')
+        .argument('<name>', 'verb name (lowercase, hyphenated — becomes `harness <name>`)')
+        .option('--wrap <command>', 'wrap a real repo command, e.g. --wrap "npm test"')
+        .option('--js', 'emit a plain .js starter (JSDoc contract, no TypeScript)')
+        .option('--record', 'scaffold a record-type extension (`harness record <name>`) instead of a verb')
+        .option('--force', 'overwrite an existing extension file')
+        .action((name, opts) => {
+        const outcome = scaffoldExtension({ name, wrap: opts.wrap, js: opts.js, record: opts.record, force: opts.force }, { fs: deps.fs, proc: deps.proc });
+        const envelope = outcome.ok
+            ? formatOk('new', {
+                path: outcome.path,
+                instructionsPath: outcome.instructionsPath,
+                verb: outcome.verb,
+                variant: outcome.variant,
+            }, deps.clock, { next_action: nextActionFor(outcome.variant, outcome.path, outcome.verb) })
+            : formatError('new', outcome.code, outcome.message, deps.clock, {
+                next_action: outcome.next_action,
+            });
+        const port = io.mode === 'json'
+            ? createOutputPort('json', io.writers)
+            : {
+                emit: (e) => {
+                    if (e.status === 'ok' && outcome.ok) {
+                        io.writers.out(`Created ${outcome.path}\n`);
+                        io.writers.out(`Created ${outcome.instructionsPath} (author the agent briefing)\n`);
+                    }
+                    else {
+                        io.writers.err(`harness new: ${e.error?.message ?? 'failed'}\n`);
+                        if (e.next_action)
+                            io.writers.err(`  → ${e.next_action}\n`);
+                    }
+                    io.writers.out(`new: ${e.status}\n`);
+                },
+            };
+        exitWithEnvelope(envelope, port);
+    });
+}
+//# sourceMappingURL=new.js.map

package/harness/cli/dist/acts/new.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"new.js","sourceRoot":"","sources":["../../src/acts/new.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/acts/observe.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+import type { Clock } from '../adapters/clock/clock-port.js';
+import type { EnvPort } from '../adapters/env/env-port.js';
+import type { FsPort } from '../adapters/fs/fs-port.js';
+import type { ProcessPort } from '../adapters/process/process-port.js';
+import { type CliIo } from '../output/output-port.js';
+/** The ports the `observe` act injects into the observe service (a subset of VerbActDeps). */
+export interface ObserveActDeps {
+    fs: FsPort;
+    proc: ProcessPort;
+    clock: Clock;
+    env: EnvPort;
+}
+/**
+ * Register the `observe` command — CLI-owned in-flight friction capture into the
+ * gitignored transient buffer (`.harness/temp/<bucket>/session-buffer.md`), plus
+ * the `--list`/`--clear` drain surface that sweeps ALL buckets by default
+ * (plan 015 D-12). A CORE command (reserved, like `record`/`instructions`). It
+ * owns no business logic — `observe-service` resolves identity, validates,
+ * assigns IDs, and appends; this act maps outcomes onto the Envelope + exit code
+ * (ok → 0, unconfigured → 2, error → 1).
+ */
+export declare function registerObserveAct(program: Command, io: CliIo, deps: ObserveActDeps): void;

package/harness/cli/dist/acts/observe.js

@@ -0,0 +1,129 @@
+import { formatError, formatOk, formatUnconfigured } from '../output/envelope.js';
+import { ErrorCodes } from '../output/error-codes.js';
+import { exitWithEnvelope } from '../output/exit.js';
+import { createOutputPort } from '../output/output-port.js';
+import { OBSERVATION_KINDS, OBSERVATION_SEVERITIES } from '../services/observe/buffer-codec.js';
+import { captureObservation, clearObservations, listObservations, } from '../services/observe/observe-service.js';
+/**
+ * Register the `observe` command — CLI-owned in-flight friction capture into the
+ * gitignored transient buffer (`.harness/temp/<bucket>/session-buffer.md`), plus
+ * the `--list`/`--clear` drain surface that sweeps ALL buckets by default
+ * (plan 015 D-12). A CORE command (reserved, like `record`/`instructions`). It
+ * owns no business logic — `observe-service` resolves identity, validates,
+ * assigns IDs, and appends; this act maps outcomes onto the Envelope + exit code
+ * (ok → 0, unconfigured → 2, error → 1).
+ */
+export function registerObserveAct(program, io, deps) {
+    const kinds = Object.keys(OBSERVATION_KINDS).join(' | ');
+    program
+        .command('observe')
+        .description('Capture one friction observation to the gitignored transient buffer (.harness/temp/)')
+        .argument('[description]', 'what you noticed (>=10 chars); omit with --list/--clear')
+        .option('--kind <kind>', `entry kind: ${kinds}`)
+        .option('--target <target>', 'free-form target, e.g. tooling | project-sensor | skill')
+        .option('--severity <severity>', `severity: ${OBSERVATION_SEVERITIES.join(' | ')}`)
+        .option('--workaround <text>', 'what you did to get past it')
+        .option('--suggested-encoding <text>', 'a hint for the retro drain encoding flow')
+        .option('--agent <slug>', 'bucket override (else HARNESS_AGENT env, else "agent")')
+        .option('--list', 'list pending observations (all buckets by default)')
+        .option('--clear', 'truncate pending observations (all buckets by default; files kept)')
+        .action((description, opts) => {
+        const serviceDeps = deps;
+        if (opts.list) {
+            const outcome = listObservations({ agent: opts.agent }, serviceDeps);
+            if (!outcome.ok) {
+                exitWithEnvelope(failureEnvelope(outcome, deps.clock), portFor(io, 'list'));
+                return;
+            }
+            const envelope = formatOk('observe', {
+                observations: outcome.observations,
+                buckets_scanned: outcome.buckets_scanned,
+                malformed_skipped: outcome.malformed_skipped,
+            }, deps.clock, {
+                next_action: 'Drain: save what matters via `harness record retro`, then `harness observe --clear`.',
+            });
+            const port = io.mode === 'json'
+                ? createOutputPort('json', io.writers)
+                : {
+                    emit: () => {
+                        for (const o of outcome.observations) {
+                            io.writers.out(`[${o.kind}${o.target ? `/${o.target}` : ''}] ${o.bucket}:${o.id} ${o.description}\n`);
+                        }
+                        io.writers.out(`observe: ${outcome.observations.length} pending across ${outcome.buckets_scanned.length} bucket(s)` +
+                            `${outcome.malformed_skipped > 0 ? `, ${outcome.malformed_skipped} malformed skipped` : ''}\n`);
+                    },
+                };
+            exitWithEnvelope(envelope, port);
+            return;
+        }
+        if (opts.clear) {
+            const outcome = clearObservations({ agent: opts.agent }, serviceDeps);
+            if (!outcome.ok) {
+                exitWithEnvelope(failureEnvelope(outcome, deps.clock), portFor(io, 'clear'));
+                return;
+            }
+            const envelope = formatOk('observe', {
+                cleared: outcome.cleared,
+                buckets_scanned: outcome.buckets_scanned,
+                malformed_skipped: outcome.malformed_skipped,
+            }, deps.clock);
+            const port = io.mode === 'json'
+                ? createOutputPort('json', io.writers)
+                : {
+                    emit: () => {
+                        io.writers.out(`observe: cleared ${outcome.cleared} entr(y/ies)\n`);
+                    },
+                };
+            exitWithEnvelope(envelope, port);
+            return;
+        }
+        const outcome = captureObservation({
+            description,
+            kind: opts.kind,
+            target: opts.target,
+            severity: opts.severity,
+            workaround: opts.workaround,
+            suggestedEncoding: opts.suggestedEncoding,
+            agent: opts.agent,
+        }, serviceDeps);
+        if (!outcome.ok) {
+            exitWithEnvelope(failureEnvelope(outcome, deps.clock), portFor(io, 'capture'));
+            return;
+        }
+        const envelope = formatOk('observe', { bucket: outcome.bucket, id: outcome.id, kind: outcome.kind, path: outcome.path }, deps.clock, {
+            evidence: [{ label: 'observation buffer', path: outcome.path }],
+            next_action: 'Keep working — drain at session end with `harness observe --list` then `harness record retro`.',
+        });
+        const port = io.mode === 'json'
+            ? createOutputPort('json', io.writers)
+            : {
+                emit: () => {
+                    io.writers.out(`Captured ${outcome.id} → ${outcome.path}\n`);
+                    io.writers.out('observe: ok\n');
+                },
+            };
+        exitWithEnvelope(envelope, port);
+    });
+}
+/** Map a service failure onto the canonical envelope (unconfigured → 2, error → 1). */
+function failureEnvelope(outcome, clock) {
+    return outcome.status === 'unconfigured'
+        ? formatUnconfigured('observe', outcome.next_action, clock)
+        : formatError('observe', outcome.code ?? ErrorCodes.UNKNOWN, outcome.message, clock, {
+            next_action: outcome.next_action,
+        });
+}
+/** Human-mode failure port (JSON mode uses the standard port). */
+function portFor(io, what) {
+    return io.mode === 'json'
+        ? createOutputPort('json', io.writers)
+        : {
+            emit: (e) => {
+                io.writers.err(`harness observe: ${e.error?.message ?? e.next_action ?? 'failed'}\n`);
+                if (e.next_action)
+                    io.writers.err(`  → ${e.next_action}\n`);
+                io.writers.out(`observe (${what}): ${e.status}\n`);
+            },
+        };
+}
+//# sourceMappingURL=observe.js.map

package/harness/cli/dist/acts/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/acts/observe.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/acts/record.d.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import type { Clock } from '../adapters/clock/clock-port.js';
+import type { FsPort } from '../adapters/fs/fs-port.js';
+import type { ProcessPort } from '../adapters/process/process-port.js';
+import { type CliIo } from '../output/output-port.js';
+import type { RecordRegistry } from '../services/record/registry.js';
+/** The ports the `record` act injects into the record service (a subset of VerbActDeps). */
+export interface RecordActDeps {
+    fs: FsPort;
+    proc: ProcessPort;
+    clock: Clock;
+}
+/**
+ * Register the `record` command — scaffolds a record file from a record type's
+ * template into `.harness/records/<type>/` and returns its path for the calling
+ * agent to fill. A CORE command (reserved, like `help`/`doctor`/`new`/`docs`/
+ * `skills`; runs even in `--no-extensions` mode). It owns no business logic — the
+ * `record-service` resolves the type + path + writes, and this act maps the
+ * outcome onto the Envelope + exit code (ok → 0, error → 1, unconfigured → 2).
+ *
+ * `harness record` (bare) and `harness record --list` both emit the orientation
+ * listing of available types (core ∪ extension), non-blocking, exit 0.
+ */
+export declare function registerRecordAct(program: Command, io: CliIo, deps: RecordActDeps, registry: RecordRegistry): void;

package/harness/cli/dist/acts/record.js

@@ -0,0 +1,93 @@
+import { formatError, formatOk, formatUnconfigured } from '../output/envelope.js';
+import { ErrorCodes } from '../output/error-codes.js';
+import { exitWithEnvelope } from '../output/exit.js';
+import { createOutputPort } from '../output/output-port.js';
+import { createRecord } from '../services/record/record-service.js';
+/**
+ * Register the `record` command — scaffolds a record file from a record type's
+ * template into `.harness/records/<type>/` and returns its path for the calling
+ * agent to fill. A CORE command (reserved, like `help`/`doctor`/`new`/`docs`/
+ * `skills`; runs even in `--no-extensions` mode). It owns no business logic — the
+ * `record-service` resolves the type + path + writes, and this act maps the
+ * outcome onto the Envelope + exit code (ok → 0, error → 1, unconfigured → 2).
+ *
+ * `harness record` (bare) and `harness record --list` both emit the orientation
+ * listing of available types (core ∪ extension), non-blocking, exit 0.
+ */
+export function registerRecordAct(program, io, deps, registry) {
+    program
+        .command('record')
+        .description('Scaffold a record file from a record type into .harness/records/<type>/ (returns its path)')
+        .argument('[type]', 'record type to create; omit (or use --list) to list available types')
+        .option('--slug <slug>', 'optional filename slug (lowercased to [a-z0-9-])')
+        .option('--list', 'list available record types (core ∪ extension)')
+        .action((type, opts) => {
+        if (opts.list || type === undefined) {
+            emitList(io, deps.clock, registry);
+            return;
+        }
+        const outcome = createRecord({ type, slug: opts.slug }, registry, deps);
+        if (outcome.ok) {
+            const envelope = formatOk('record', { type: outcome.type, path: outcome.path, source: outcome.source }, deps.clock, {
+                evidence: [{ label: `${outcome.type} record`, path: outcome.path }],
+                next_action: `Open and fill ${outcome.path}, then save.`,
+            });
+            const port = io.mode === 'json'
+                ? createOutputPort('json', io.writers)
+                : {
+                    emit: () => {
+                        io.writers.out(`Created ${outcome.path}\n`);
+                        io.writers.out('record: ok\n');
+                    },
+                };
+            exitWithEnvelope(envelope, port);
+            return;
+        }
+        const envelope = outcome.status === 'unconfigured'
+            ? formatUnconfigured('record', outcome.next_action, deps.clock)
+            : formatError('record', outcome.code ?? ErrorCodes.UNKNOWN, outcome.message, deps.clock, {
+                next_action: outcome.next_action,
+            });
+        const port = io.mode === 'json'
+            ? createOutputPort('json', io.writers)
+            : {
+                emit: (e) => {
+                    io.writers.err(`harness record: ${e.error?.message ?? e.next_action ?? 'failed'}\n`);
+                    if (e.next_action)
+                        io.writers.err(`  → ${e.next_action}\n`);
+                    io.writers.out(`record: ${e.status}\n`);
+                },
+            };
+        exitWithEnvelope(envelope, port);
+    });
+}
+/** Emit the orientation listing of available record types (core ∪ extension). */
+function emitList(io, clock, registry) {
+    const types = registry.types.map((t) => ({
+        type: t.type,
+        description: t.description,
+        source: t.source,
+        ...(t.entryPath && { entryPath: t.entryPath }),
+    }));
+    const envelope = formatOk('record', { types }, clock, {
+        next_action: 'Create one with `harness record <type> --slug "<name>"`.',
+    });
+    const port = io.mode === 'json'
+        ? createOutputPort('json', io.writers)
+        : { emit: () => io.writers.out(renderListText(registry)) };
+    exitWithEnvelope(envelope, port);
+}
+/** Human-readable listing of record types. */
+function renderListText(registry) {
+    const lines = ['harness record — available types:'];
+    if (registry.types.length === 0) {
+        lines.push('  (none)');
+    }
+    for (const t of registry.types) {
+        const provenance = t.source === 'extension' ? `[extension] ${t.entryPath ?? ''}`.trim() : '[core]';
+        lines.push(`  • ${t.type}\t${t.description}\t${provenance}`);
+    }
+    lines.push('', '  harness record <type> [--slug "<name>"]');
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=record.js.map

package/harness/cli/dist/acts/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/acts/record.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/acts/skills.d.ts

@@ -0,0 +1,32 @@
+import type { Command } from 'commander';
+import type { Clock } from '../adapters/clock/clock-port.js';
+import type { ExecPort } from '../adapters/exec/exec-port.js';
+import type { ProcessPort } from '../adapters/process/process-port.js';
+import { type CliIo } from '../output/output-port.js';
+/** The ports the `skills` act injects — a subset of VerbActDeps (no fs/git/env needed). */
+export interface SkillsActDeps {
+    exec: ExecPort;
+    proc: ProcessPort;
+    clock: Clock;
+}
+/**
+ * Register the `skills` command + its `install` subcommand — a first-class CORE
+ * capability (reserved, like `help`/`doctor`/`new`/`docs`; it ships with the
+ * published CLI so the harness can install its own skills in any repo). It owns
+ * no install logic: it is a transparent PASS-THROUGH to Vercel's `npx skills add`
+ * (Principle 8, wrap-don't-rebuild — that tool already owns the CLI-target × scope
+ * matrix). The act:
+ *   - builds the exact argv with the pure `buildInstallArgv` (always `-y`, so the
+ *     blocking interactive picker never appears);
+ *   - **announces the exact `npx …` command before running it** — to stderr in
+ *     human mode, and inside the envelope (`data.command` + `next_action`) in JSON
+ *     mode, so the `--json` stdout stays a single parseable envelope (Principle 4);
+ *   - shells out ONLY through the injected `ExecPort` (no direct child/shell);
+ *   - maps the result onto an Envelope + exit code (ok → 0, `E170` → 1).
+ *
+ * Targets are flags, not a blocking prompt: the harness CLI is agent-first and
+ * non-blocking, so a missing `--target` returns `E108` with a `next_action` that
+ * enumerates the valid targets. The *skill* (`eng-harness-0-adopt`) is what asks
+ * the user, then runs this with flags.
+ */
+export declare function registerSkillsAct(program: Command, io: CliIo, deps: SkillsActDeps): void;