@ai-substrate/engineering-harness 0.2.0-canary.45

package/harness/cli/dist/services/extensions/contract.d.ts

@@ -0,0 +1,138 @@
+/**
+ * PUBLIC verb contract — the types an extension author imports.
+ *
+ * Authors `import type { HarnessVerb } from '@ai-substrate/engineering-harness/contract'`
+ * (resolved by the `exports["./contract"]` map added in T023). Everything here is
+ * **types only**, so it is erased at runtime — even a plain `.js` extension can
+ * reference these via JSDoc with no runtime dependency on the core (plan D4).
+ *
+ * The core provides the implementation: it discovers + loads each extension's
+ * default export (a {@link HarnessVerb} or array), registers one commander
+ * subcommand per verb, builds the {@link VerbContext}, and finalizes the
+ * returned {@link VerbResult} into a canonical Envelope (adding `command` +
+ * `timestamp` and mapping `status` → exit code). Authors return intent; the
+ * kernel stays the sole owner of `command`/`timestamp`/exit/`process.exit`.
+ */
+import type { ExecResult } from '../../adapters/exec/exec-port.js';
+import type { Evidence } from '../../output/envelope.js';
+import type { HarnessRecordType } from '../record/contract.js';
+export type { ExecResult } from '../../adapters/exec/exec-port.js';
+export type { Evidence } from '../../output/envelope.js';
+export type { HarnessRecordType } from '../record/contract.js';
+/** The four states a verb can report — mirrors the kernel's Envelope statuses. */
+export type VerbStatus = 'ok' | 'degraded' | 'unconfigured' | 'error';
+export interface VerbOption {
+    /** commander-style flags, e.g. '--name <name>' or '-f, --force'. */
+    flags: string;
+    description: string;
+    defaultValue?: string | boolean;
+}
+export interface VerbArg {
+    /** commander-style, e.g. '<target>' (required) or '[target]' (optional). */
+    name: string;
+    description: string;
+}
+/**
+ * What a handler RETURNS. The core finalizes it into a full Envelope (adds
+ * `command` = the verb name + `timestamp` from the clock, maps status → exit).
+ * `next_action` is REQUIRED by the core for any non-`ok` status (P5).
+ */
+export interface VerbResult {
+    status: VerbStatus;
+    data?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    evidence?: Evidence[];
+    next_action?: string;
+}
+/**
+ * Injected per-invocation by the core from its ports. Authors never build this.
+ * The shapes are inlined (not adapter imports) so the published contract is
+ * self-contained.
+ */
+export interface VerbContext {
+    /** The developer-repo cwd discovery resolved against. */
+    cwd: string;
+    /** Parsed positional args, by arg name. */
+    args: Record<string, string | undefined>;
+    /** Parsed flags, by camelCased name. */
+    options: Record<string, unknown>;
+    /** Run a REAL repo command (P8 — "wrap, don't rebuild"). cwd defaults to ctx.cwd. */
+    exec(command: string, args?: string[], opts?: {
+        cwd?: string;
+    }): Promise<ExecResult>;
+    fs: {
+        exists(path: string): boolean;
+        readText(path: string): string | null;
+        readdir(path: string): string[];
+    };
+    env: {
+        get(name: string): string | undefined;
+    };
+    git: {
+        isRepo(): boolean;
+        currentBranch(): string | null;
+    };
+    clock: {
+        nowIso(): string;
+    };
+    ok<T>(data: T, opts?: {
+        evidence?: Evidence[];
+        next_action?: string;
+    }): VerbResult;
+    degraded<T>(data: T, next_action: string, opts?: {
+        evidence?: Evidence[];
+    }): VerbResult;
+    unconfigured(next_action: string, opts?: {
+        data?: unknown;
+    }): VerbResult;
+    error(code: string, message: string, opts?: {
+        details?: unknown;
+        next_action?: string;
+    }): VerbResult;
+}
+/** The verb an extension declares. */
+export interface HarnessVerb {
+    /**
+     * Discriminator — distinguishes a verb export from a {@link HarnessRecordType}.
+     * OPTIONAL and defaults to `'verb'` when absent, so every existing verb
+     * extension (which never set it) keeps working unchanged.
+     */
+    kind?: 'verb';
+    /** e.g. 'build' → `harness build`. */
+    name: string;
+    /** One line — shown in `help`'s list + `doctor`. */
+    summary: string;
+    /** Longer body shown by `harness <verb> --help`. */
+    description?: string;
+    options?: VerbOption[];
+    args?: VerbArg[];
+    run(ctx: VerbContext): VerbResult | Promise<VerbResult>;
+}
+/** A `.harness/extensions/*` entry's DEFAULT export (verb-only — kept for back-compat). */
+export type ExtensionExport = HarnessVerb | HarnessVerb[];
+/**
+ * The widened default-export union: a `.harness/extensions/*` file may declare a
+ * verb, a record type, or an array mixing both. The loader routes each by `kind`
+ * (`kind:'record'` → record registry; absent/`'verb'` → verb registry).
+ */
+export type HarnessExtensionExport = HarnessVerb | HarnessRecordType | Array<HarnessVerb | HarnessRecordType>;
+/** What `doctor` enumerates per discovered extension file (P7). */
+export interface ExtensionRecord {
+    /** Resolved absolute path. */
+    entryPath: string;
+    status: 'loaded' | 'failed' | 'conflict';
+    /** Declared verbs accepted from this file (empty when `failed` or record-only). */
+    verbs: HarnessVerb[];
+    /** Declared record types accepted from this file (present only when non-empty). */
+    recordTypes?: HarnessRecordType[];
+    /** Load/validation message (present when status !== 'loaded'). */
+    error?: string;
+    /** For 'conflict': the VERB name(s) shadowed by a core command or earlier extension. */
+    shadows?: string[];
+    /** For 'conflict': the RECORD-TYPE name(s) shadowed by a core type or earlier extension. */
+    recordShadows?: string[];
+}

package/harness/cli/dist/services/extensions/contract.js

@@ -0,0 +1,17 @@
+/**
+ * PUBLIC verb contract — the types an extension author imports.
+ *
+ * Authors `import type { HarnessVerb } from '@ai-substrate/engineering-harness/contract'`
+ * (resolved by the `exports["./contract"]` map added in T023). Everything here is
+ * **types only**, so it is erased at runtime — even a plain `.js` extension can
+ * reference these via JSDoc with no runtime dependency on the core (plan D4).
+ *
+ * The core provides the implementation: it discovers + loads each extension's
+ * default export (a {@link HarnessVerb} or array), registers one commander
+ * subcommand per verb, builds the {@link VerbContext}, and finalizes the
+ * returned {@link VerbResult} into a canonical Envelope (adding `command` +
+ * `timestamp` and mapping `status` → exit code). Authors return intent; the
+ * kernel stays the sole owner of `command`/`timestamp`/exit/`process.exit`.
+ */
+export {};
+//# sourceMappingURL=contract.js.map

package/harness/cli/dist/services/extensions/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/services/extensions/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/harness/cli/dist/services/extensions/discovery.d.ts

@@ -0,0 +1,53 @@
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { ProcessPort } from '../../adapters/process/process-port.js';
+/** A directory entry discovery refused, with the reason doctor should surface. */
+export interface RejectedExtension {
+    /** Resolved absolute path of the refused entry. */
+    path: string;
+    /** Human-actionable reason (becomes the E143 record detail). */
+    reason: string;
+}
+/** What one discovery pass yields: loadable entry paths + refused entries (plan 014 D1). */
+export interface DiscoveryResult {
+    /** Sorted, deduped entry-file paths the loader should import. */
+    candidates: string[];
+    /** Entries refused with a reason (e.g. unsupported flat layout) — never loaded. */
+    rejected: RejectedExtension[];
+}
+/**
+ * Scan `<cwd>/.harness/extensions/` ONE level and resolve each entry to the
+ * extension entry file the loader should import (WS-A Decision 4; folder-only
+ * since plan 014). Pure of direct Node I/O — the directory listing comes from
+ * `FsPort.readdir`, the cwd from `ProcessPort.cwd`, so the whole thing is
+ * unit-testable with fakes.
+ *
+ * Rules (plan 014 AC-6 / D1):
+ * - An extension is a FOLDER (a little package). Per folder, the first hit of
+ *   `package.json` `harness.extensions[]` manifest → `extension.ts` →
+ *   `extension.js` → `index.ts` → `index.js` is the entry. `.tsx`/`.mjs`/`.cjs`
+ *   entries are reachable only via the manifest.
+ * - A direct `*.ts|*.tsx|*.mjs|*.cjs|*.js` file is the retired flat layout →
+ *   `rejected[]` with reason `unsupported flat layout — move to <name>/extension.ts`
+ *   (the registry turns each into a `failed` E143 record for doctor).
+ * - Other direct files (`README`, `*.md`, …) and unresolvable folders are
+ *   silently ignored, as before.
+ * - Manifest entries that resolve OUTSIDE their own subdir are dropped (no
+ *   `../escape.ts` path traversal — lexical containment only; see the realpath
+ *   note below for symlinks).
+ * - Entries are processed in **sorted** name order (stable "first wins").
+ * - Candidates are **deduped** by POSIX-normalized logical path (first
+ *   occurrence kept; case-folded on win32 — see `dedupeKey`).
+ * - Absent / empty dir → empty result (never an error).
+ *
+ * Discovery is the SINGLE POSIX ORIGIN for extension paths (plan 017): the cwd
+ * is converted via `toPosix` at the boundary and every emitted `entryPath` /
+ * `folder` / rejected `path` is a logical POSIX path, so downstream consumers
+ * (doctor, instructions, registry) never re-normalize per site.
+ *
+ * NOTE: dedup + containment are lexical in POSIX space (posix-path helper —
+ * never `resolve`, which corrupts drive-letter paths); symlink-following (true
+ * realpath) is deferred — it would need a new `FsPort.realpath` capability, so
+ * the `../escape` guard is lexical and does NOT stop a symlink inside the
+ * subdir from pointing elsewhere.
+ */
+export declare function discoverExtensions(fs: FsPort, proc: ProcessPort): DiscoveryResult;

package/harness/cli/dist/services/extensions/discovery.js

@@ -0,0 +1,116 @@
+import { dedupeKey, isWithin, posixJoin, toPosix } from '../shared/posix-path.js';
+const EXTENSIONS_DIR = ['.harness', 'extensions'];
+const CODE_FILE = /\.(ts|tsx|mjs|cjs|js)$/;
+/** Per-folder convention chain, probed in order after the manifest (plan 014 AC-6). */
+const ENTRY_CHAIN = ['extension.ts', 'extension.js', 'index.ts', 'index.js'];
+/**
+ * Scan `<cwd>/.harness/extensions/` ONE level and resolve each entry to the
+ * extension entry file the loader should import (WS-A Decision 4; folder-only
+ * since plan 014). Pure of direct Node I/O — the directory listing comes from
+ * `FsPort.readdir`, the cwd from `ProcessPort.cwd`, so the whole thing is
+ * unit-testable with fakes.
+ *
+ * Rules (plan 014 AC-6 / D1):
+ * - An extension is a FOLDER (a little package). Per folder, the first hit of
+ *   `package.json` `harness.extensions[]` manifest → `extension.ts` →
+ *   `extension.js` → `index.ts` → `index.js` is the entry. `.tsx`/`.mjs`/`.cjs`
+ *   entries are reachable only via the manifest.
+ * - A direct `*.ts|*.tsx|*.mjs|*.cjs|*.js` file is the retired flat layout →
+ *   `rejected[]` with reason `unsupported flat layout — move to <name>/extension.ts`
+ *   (the registry turns each into a `failed` E143 record for doctor).
+ * - Other direct files (`README`, `*.md`, …) and unresolvable folders are
+ *   silently ignored, as before.
+ * - Manifest entries that resolve OUTSIDE their own subdir are dropped (no
+ *   `../escape.ts` path traversal — lexical containment only; see the realpath
+ *   note below for symlinks).
+ * - Entries are processed in **sorted** name order (stable "first wins").
+ * - Candidates are **deduped** by POSIX-normalized logical path (first
+ *   occurrence kept; case-folded on win32 — see `dedupeKey`).
+ * - Absent / empty dir → empty result (never an error).
+ *
+ * Discovery is the SINGLE POSIX ORIGIN for extension paths (plan 017): the cwd
+ * is converted via `toPosix` at the boundary and every emitted `entryPath` /
+ * `folder` / rejected `path` is a logical POSIX path, so downstream consumers
+ * (doctor, instructions, registry) never re-normalize per site.
+ *
+ * NOTE: dedup + containment are lexical in POSIX space (posix-path helper —
+ * never `resolve`, which corrupts drive-letter paths); symlink-following (true
+ * realpath) is deferred — it would need a new `FsPort.realpath` capability, so
+ * the `../escape` guard is lexical and does NOT stop a symlink inside the
+ * subdir from pointing elsewhere.
+ */
+export function discoverExtensions(fs, proc) {
+    const base = posixJoin(toPosix(proc.cwd()), ...EXTENSIONS_DIR);
+    const entries = fs.readdir(base);
+    if (entries.length === 0) {
+        return { candidates: [], rejected: [] };
+    }
+    const candidates = [];
+    const rejected = [];
+    for (const entry of [...entries].sort()) {
+        const entryPath = posixJoin(base, entry);
+        if (CODE_FILE.test(entry)) {
+            const name = entry.replace(CODE_FILE, '');
+            rejected.push({
+                path: entryPath,
+                reason: `unsupported flat layout — move to ${name}/extension.ts`,
+            });
+            continue;
+        }
+        candidates.push(...resolveSubdir(fs, entryPath));
+    }
+    return { candidates: dedupeByAbsolutePath(candidates), rejected };
+}
+/** Resolve a sub-directory to its entry file(s): manifest → extension.ts → extension.js → index.ts → index.js → none. */
+function resolveSubdir(fs, dir) {
+    const manifestPaths = readManifest(fs, dir);
+    if (manifestPaths.length > 0) {
+        return manifestPaths;
+    }
+    for (const entry of ENTRY_CHAIN) {
+        const entryPath = posixJoin(dir, entry);
+        if (fs.exists(entryPath)) {
+            return [entryPath];
+        }
+    }
+    return [];
+}
+/** Read `<dir>/package.json` and return resolved `harness.extensions[]` paths, or []. */
+function readManifest(fs, dir) {
+    const pkgPath = posixJoin(dir, 'package.json');
+    if (!fs.exists(pkgPath)) {
+        return [];
+    }
+    const raw = fs.readText(pkgPath);
+    if (raw === null) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const list = parsed.harness?.extensions;
+        if (!Array.isArray(list)) {
+            return [];
+        }
+        return list
+            .filter((entry) => typeof entry === 'string')
+            .map((rel) => posixJoin(dir, rel))
+            .filter((candidate) => isWithin(dir, candidate));
+    }
+    catch {
+        return [];
+    }
+}
+/** Keep the first occurrence of each logical path (POSIX-normalized `dedupeKey`; preserves order). */
+function dedupeByAbsolutePath(paths) {
+    const seen = new Set();
+    const result = [];
+    for (const path of paths) {
+        const key = dedupeKey(path);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(path);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=discovery.js.map

package/harness/cli/dist/services/extensions/discovery.js.map

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

package/harness/cli/dist/services/extensions/registry.d.ts

@@ -0,0 +1,63 @@
+import type { ModuleLoaderPort } from '../../adapters/loader/module-loader-port.js';
+import { type ExtensionRecordType } from '../record/registry.js';
+import type { ExtensionRecord, HarnessVerb } from './contract.js';
+/** The assembled verb surface + the per-extension provenance `doctor` enumerates. */
+export interface VerbRegistry {
+    /** Verbs accepted into the command surface (deduped, core names excluded). */
+    verbs: HarnessVerb[];
+    /** One record per discovered extension file: loaded / failed / conflict. */
+    records: ExtensionRecord[];
+}
+/** The full extension surface from ONE discovery pass: verbs + record types + provenance. */
+export interface ExtensionRegistry {
+    /** Verbs accepted into the command surface (deduped, reserved/claimed excluded). */
+    verbs: HarnessVerb[];
+    /** Record types accepted from extensions, paired with their discovery path (de-conflicted). */
+    recordTypes: ExtensionRecordType[];
+    /** One record per discovered extension file: loaded / failed / conflict. */
+    records: ExtensionRecord[];
+}
+/** Options for the single-pass loader: which verb names + record-type names are reserved. */
+export interface ExtensionRegistryOptions {
+    /** Verb names an extension may NOT claim (core commands). Defaults to {@link RESERVED_NAMES}. */
+    reservedVerbs?: ReadonlySet<string>;
+    /** Record-type names an extension may NOT claim (core types). Defaults to empty. */
+    reservedRecordTypes?: ReadonlySet<string>;
+    /**
+     * Entries discovery refused (e.g. unsupported flat layout). Each becomes a
+     * synthesized `failed` record (E143) with NO load attempt, so doctor surfaces
+     * it through the existing record rendering (plan 014 D1).
+     */
+    rejected?: readonly {
+        path: string;
+        reason: string;
+    }[];
+}
+/**
+ * Core command names an extension may NOT shadow. `help`/`doctor`/`new`/`docs`/
+ * `skills`/`record`/`instructions`/`observe`/`init` are all reserved core
+ * commands (`instructions` reserved since plan 014 — the agent-briefing act;
+ * `observe` since plan 015 — the friction-capture act; `init` since plan 008
+ * FX001 — the governance-doc inception writer).
+ */
+export declare const RESERVED_NAMES: ReadonlySet<string>;
+/**
+ * Build the full extension registry from discovered candidate paths in ONE load
+ * pass (already sorted by discovery, so "first wins" is deterministic). Each file
+ * is loaded in isolation: a load throw or malformed default export becomes a
+ * `failed` record (`E140`) and never breaks the others. Each declared export is
+ * routed by its `kind`:
+ *   - `kind:'record'` → a {@link HarnessRecordType} candidate for the record registry;
+ *   - absent/`'verb'`  → a {@link HarnessVerb} candidate for the command surface.
+ * A verb name claimed by a reserved core command / earlier extension, or a record
+ * type claimed by a reserved core type / earlier extension, is a `conflict`
+ * (`E142`); ALL shadowed duplicates are recorded (verb shadows in `shadows`,
+ * record-type shadows in `recordShadows`) and none of them are registered.
+ */
+export declare function buildExtensionRegistry(candidates: string[], loader: ModuleLoaderPort, options?: ExtensionRegistryOptions): Promise<ExtensionRegistry>;
+/**
+ * Verb-only projection of {@link buildExtensionRegistry} — the historical surface
+ * many call sites + tests use. Record-kinded exports (if any) are routed away and
+ * never registered as verbs; the per-file provenance is preserved.
+ */
+export declare function buildVerbRegistry(candidates: string[], loader: ModuleLoaderPort, reserved?: ReadonlySet<string>): Promise<VerbRegistry>;

package/harness/cli/dist/services/extensions/registry.js

@@ -0,0 +1,165 @@
+import { ErrorCodes } from '../../output/error-codes.js';
+import { verbShapeIssues } from '../config/load-config.js';
+import { recordTypeShapeIssues } from '../record/registry.js';
+/**
+ * Core command names an extension may NOT shadow. `help`/`doctor`/`new`/`docs`/
+ * `skills`/`record`/`instructions`/`observe`/`init` are all reserved core
+ * commands (`instructions` reserved since plan 014 — the agent-briefing act;
+ * `observe` since plan 015 — the friction-capture act; `init` since plan 008
+ * FX001 — the governance-doc inception writer).
+ */
+export const RESERVED_NAMES = new Set([
+    'help',
+    'doctor',
+    'new',
+    'docs',
+    'skills',
+    'record',
+    'instructions',
+    'observe',
+    'init',
+]);
+/**
+ * Build the full extension registry from discovered candidate paths in ONE load
+ * pass (already sorted by discovery, so "first wins" is deterministic). Each file
+ * is loaded in isolation: a load throw or malformed default export becomes a
+ * `failed` record (`E140`) and never breaks the others. Each declared export is
+ * routed by its `kind`:
+ *   - `kind:'record'` → a {@link HarnessRecordType} candidate for the record registry;
+ *   - absent/`'verb'`  → a {@link HarnessVerb} candidate for the command surface.
+ * A verb name claimed by a reserved core command / earlier extension, or a record
+ * type claimed by a reserved core type / earlier extension, is a `conflict`
+ * (`E142`); ALL shadowed duplicates are recorded (verb shadows in `shadows`,
+ * record-type shadows in `recordShadows`) and none of them are registered.
+ */
+export async function buildExtensionRegistry(candidates, loader, options = {}) {
+    const reservedVerbs = options.reservedVerbs ?? RESERVED_NAMES;
+    const reservedRecordTypes = options.reservedRecordTypes ?? new Set();
+    const records = (options.rejected ?? []).map((entry) => failed(entry.path, entry.reason, ErrorCodes.EXTENSION_FLAT_LAYOUT));
+    const verbs = [];
+    const recordTypes = [];
+    const claimedVerbs = new Set();
+    const claimedRecordTypes = new Set();
+    for (const entryPath of candidates) {
+        let mod;
+        try {
+            mod = await loader.load(entryPath);
+        }
+        catch (err) {
+            records.push(failed(entryPath, errorMessage(err)));
+            continue;
+        }
+        const declared = coerceExports(mod);
+        if (declared === null) {
+            records.push(failed(entryPath, 'default export is not a HarnessVerb/HarnessRecordType (or array of them)'));
+            continue;
+        }
+        // Route each declared export by `kind`.
+        const verbDecls = [];
+        const recordDecls = [];
+        for (const entry of declared) {
+            if (isRecordKind(entry)) {
+                recordDecls.push(entry);
+            }
+            else {
+                verbDecls.push(entry);
+            }
+        }
+        // File-level shape validation (one bad export fails the whole file, like verbs always did).
+        const shapeProblems = [
+            ...verbDecls.flatMap(verbShapeIssues),
+            ...recordDecls.flatMap(recordTypeShapeIssues),
+        ];
+        if (shapeProblems.length > 0) {
+            records.push(failed(entryPath, shapeProblems.join('; ')));
+            continue;
+        }
+        // Acceptance + conflict collection (reserved/claimed → shadowed, never registered).
+        const acceptedVerbs = [];
+        const acceptedRecords = [];
+        const verbShadows = [];
+        const recordShadows = [];
+        for (const verb of verbDecls) {
+            if (reservedVerbs.has(verb.name) || claimedVerbs.has(verb.name)) {
+                verbShadows.push(verb.name);
+                continue;
+            }
+            claimedVerbs.add(verb.name);
+            acceptedVerbs.push(verb);
+            verbs.push(verb);
+        }
+        for (const rt of recordDecls) {
+            if (reservedRecordTypes.has(rt.type) || claimedRecordTypes.has(rt.type)) {
+                recordShadows.push(rt.type);
+                continue;
+            }
+            claimedRecordTypes.add(rt.type);
+            acceptedRecords.push(rt);
+            recordTypes.push({ recordType: rt, entryPath });
+        }
+        const hasShadow = verbShadows.length > 0 || recordShadows.length > 0;
+        records.push(hasShadow
+            ? {
+                entryPath,
+                status: 'conflict',
+                verbs: acceptedVerbs,
+                ...(acceptedRecords.length > 0 && { recordTypes: acceptedRecords }),
+                ...(verbShadows.length > 0 && { shadows: verbShadows }),
+                ...(recordShadows.length > 0 && { recordShadows }),
+                error: conflictError(verbShadows, recordShadows),
+            }
+            : {
+                entryPath,
+                status: 'loaded',
+                verbs: acceptedVerbs,
+                ...(acceptedRecords.length > 0 && { recordTypes: acceptedRecords }),
+            });
+    }
+    return { verbs, recordTypes, records };
+}
+/**
+ * Verb-only projection of {@link buildExtensionRegistry} — the historical surface
+ * many call sites + tests use. Record-kinded exports (if any) are routed away and
+ * never registered as verbs; the per-file provenance is preserved.
+ */
+export async function buildVerbRegistry(candidates, loader, reserved = RESERVED_NAMES) {
+    const registry = await buildExtensionRegistry(candidates, loader, { reservedVerbs: reserved });
+    return { verbs: registry.verbs, records: registry.records };
+}
+/** True when a declared export is a record type (`kind:'record'`). */
+function isRecordKind(entry) {
+    return entry.kind === 'record';
+}
+/** Normalise a default export to a list of declared exports, or null if it can't be one. */
+function coerceExports(mod) {
+    const list = Array.isArray(mod) ? mod : [mod];
+    if (list.length === 0) {
+        return null;
+    }
+    if (list.some((entry) => entry === null || typeof entry !== 'object')) {
+        return null;
+    }
+    return list;
+}
+function conflictError(verbShadows, recordShadows) {
+    const parts = [];
+    if (verbShadows.length > 0) {
+        parts.push(`verb(s) '${verbShadows.join("', '")}'`);
+    }
+    if (recordShadows.length > 0) {
+        parts.push(`record type(s) '${recordShadows.join("', '")}'`);
+    }
+    return `${ErrorCodes.EXTENSION_VERB_CONFLICT}: ${parts.join(' and ')} already provided (core command/type or earlier extension); duplicate(s) ignored.`;
+}
+function failed(entryPath, reason, code = ErrorCodes.EXTENSION_LOAD_FAILED) {
+    return {
+        entryPath,
+        status: 'failed',
+        verbs: [],
+        error: `${code}: ${reason}`,
+    };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=registry.js.map

package/harness/cli/dist/services/extensions/registry.js.map

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

package/harness/cli/dist/services/extensions/verb-context.d.ts

@@ -0,0 +1,44 @@
+import type { Clock } from '../../adapters/clock/clock-port.js';
+import type { EnvPort } from '../../adapters/env/env-port.js';
+import type { ExecPort } from '../../adapters/exec/exec-port.js';
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { GitPort } from '../../adapters/git/git-port.js';
+import { type Envelope } from '../../output/envelope.js';
+import type { HarnessVerb, VerbContext, VerbResult } from './contract.js';
+/** The ports the composition root injects to build a per-invocation `VerbContext`. */
+export interface VerbContextDeps {
+    exec: ExecPort;
+    fs: FsPort;
+    env: EnvPort;
+    git: GitPort;
+    clock: Clock;
+}
+/** The parsed invocation a verb is called with. */
+export interface VerbInvocation {
+    cwd: string;
+    args: Record<string, string | undefined>;
+    options: Record<string, unknown>;
+}
+/**
+ * Build the `VerbContext` an author's handler receives. Surfaces the injected
+ * ports (read-mostly) + envelope-helper closures so a verb never imports the
+ * kernel. `ctx.exec` adapts the author-facing signature (optional args + cwd) to
+ * `ExecPort.run`, defaulting cwd to the invocation cwd (WS-A Decision 3).
+ */
+export declare function buildVerbContext(deps: VerbContextDeps, invocation: VerbInvocation): VerbContext;
+/**
+ * Finalize what a handler RETURNED into a canonical Envelope: the kernel adds
+ * `command` (the verb name) + `timestamp` (from the clock) and maps status →
+ * the right constructor, guaranteeing a non-blank `next_action` on every non-`ok`
+ * status (P5) even if the author returned a raw object without one — a blank or
+ * whitespace-only `next_action` is treated as missing. A JS extension that returns
+ * an unknown `status` (outside the typed union) is mapped to an `E141` error
+ * Envelope rather than falling through to `undefined`.
+ */
+export declare function finalizeVerbResult(result: VerbResult, name: string, clock: Clock): Envelope;
+/**
+ * Invoke a verb's handler with isolation: a returned `VerbResult` is finalized;
+ * a thrown error becomes an `E141` error Envelope surfacing the message (never a
+ * raw stack trace — honesty, AC-style). Awaits async handlers.
+ */
+export declare function runVerb(verb: HarnessVerb, ctx: VerbContext, clock: Clock): Promise<Envelope>;