@opensip-cli/external-tool-adapter 0.1.15

package/dist/artifact-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Pure scanner-artifact path composition (ADR-0091, Phase-0
+ * decision 1).
+ *
+ * `ProjectPaths.artifactDir(tool)` (host-owned) = `<artifacts>/<tool>`. The
+ * RUN segment is substrate-side: `resolveScannerArtifactPath` composes
+ * `<artifactDir(tool)>/<runId>/<name>`. So the immediate children of
+ * `artifactDir(tool)` are the per-run dirs the host's `pruneArtifactRetention`
+ * treats as retention units — host and substrate agree on the boundary without a
+ * 3-arg `ProjectPaths` method.
+ */
+/** The minimal path scope the resolver needs (a `ProjectPaths` satisfies it). */
+export interface ArtifactPathScope {
+    /** `<artifacts>/<tool>` (host-owned path family, ADR-0091). */
+    readonly artifactDir: (tool: string) => string;
+    /** This invocation's run id — the per-run artifact segment. */
+    readonly runId: string;
+}
+/**
+ * Compose the host-owned artifact path for a scanner output file:
+ * `<artifactDir(tool)>/<runId>/<name>`. Pure — no IO. The bytes are persisted
+ * through `cli.writeArtifact(path, bytes)` (the host seam, ADR-0080), never a
+ * raw `fs` write.
+ */
+export declare function resolveScannerArtifactPath(scope: ArtifactPathScope, tool: string, name: string): string;
+//# sourceMappingURL=artifact-path.d.ts.map

package/dist/artifact-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-path.d.ts","sourceRoot":"","sources":["../src/artifact-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAER"}

package/dist/artifact-path.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Pure scanner-artifact path composition (ADR-0091, Phase-0
+ * decision 1).
+ *
+ * `ProjectPaths.artifactDir(tool)` (host-owned) = `<artifacts>/<tool>`. The
+ * RUN segment is substrate-side: `resolveScannerArtifactPath` composes
+ * `<artifactDir(tool)>/<runId>/<name>`. So the immediate children of
+ * `artifactDir(tool)` are the per-run dirs the host's `pruneArtifactRetention`
+ * treats as retention units — host and substrate agree on the boundary without a
+ * 3-arg `ProjectPaths` method.
+ */
+import { join } from 'node:path';
+/**
+ * Compose the host-owned artifact path for a scanner output file:
+ * `<artifactDir(tool)>/<runId>/<name>`. Pure — no IO. The bytes are persisted
+ * through `cli.writeArtifact(path, bytes)` (the host seam, ADR-0080), never a
+ * raw `fs` write.
+ */
+export function resolveScannerArtifactPath(scope, tool, name) {
+    return join(scope.artifactDir(tool), scope.runId, name);
+}
+//# sourceMappingURL=artifact-path.js.map

package/dist/artifact-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-path.js","sourceRoot":"","sources":["../src/artifact-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAUjC;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAwB,EACxB,IAAY,EACZ,IAAY;IAEZ,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAC1D,CAAC"}

package/dist/binary-resolver.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Layered, deterministic binary resolution (ADR-0090 §4.3).
+ *
+ * First hit wins: an operator pin (the `OPENSIP_<TOOL>_BIN` env var, then the
+ * `binaries.<tool>.path` config) always beats the system `PATH`. A pin that is
+ * non-absolute or missing is a HARD miss — the substrate does NOT silently fall
+ * back to `PATH` (the operator asked for a specific binary). A `PATH` miss yields
+ * a not-found result (the caller raises a `ConfigurationError` pointing at
+ * `doctor`); resolution NEVER fetches a binary.
+ *
+ * Pure given its {@link BinaryResolveDeps} (existence check + PATH lookup) — the
+ * real deps live in `process-exec.ts` (the IO boundary). Returns data, never
+ * throws.
+ */
+import type { BinaryResolutionLayer } from './types.js';
+/** The IO deps `resolveBinary` is parameterized over (real impls in `process-exec.ts`). */
+export interface BinaryResolveDeps {
+    readonly existsSync: (path: string) => boolean;
+    readonly which: (command: string, platform: NodeJS.Platform) => string | undefined;
+}
+/** The inputs to {@link resolveBinary}: the lookup name plus the optional operator pins. */
+export interface ResolveBinaryInput {
+    /** The PATH lookup name (`'gitleaks'`). */
+    readonly command: string;
+    /** An operator-pinned absolute path from the namespaced config (`binaries.<tool>.path`). */
+    readonly configuredPath?: string;
+    /** An operator-pinned absolute path from `OPENSIP_<TOOL>_BIN`. */
+    readonly envPath?: string;
+    /** The host platform (defaults to `process.platform`). */
+    readonly platform?: NodeJS.Platform;
+}
+/** The outcome of {@link resolveBinary}. */
+export type BinaryResolution = {
+    readonly found: true;
+    readonly path: string;
+    readonly layer: BinaryResolutionLayer;
+} | {
+    readonly found: false;
+    readonly command: string;
+    readonly reason: string;
+    readonly searched: readonly string[];
+};
+/**
+ * Resolve the scanner binary by the layered order env-pin → config-pin → `PATH`.
+ * An operator pin (env or config) wins and never falls through to `PATH`; a
+ * broken pin is a hard miss with a reason.
+ */
+export declare function resolveBinary(input: ResolveBinaryInput, deps: BinaryResolveDeps): BinaryResolution;
+/** Derive the default env-var name that pins a tool's binary: `OPENSIP_<TOOL>_BIN`. */
+export declare function defaultBinaryEnvVar(tool: string): string;
+//# sourceMappingURL=binary-resolver.d.ts.map

package/dist/binary-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-resolver.d.ts","sourceRoot":"","sources":["../src/binary-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC;CACpF;AAED,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAED,4CAA4C;AAC5C,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GACtF;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AA2BN;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE,iBAAiB,GACtB,gBAAgB,CAsBlB;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/binary-resolver.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Layered, deterministic binary resolution (ADR-0090 §4.3).
+ *
+ * First hit wins: an operator pin (the `OPENSIP_<TOOL>_BIN` env var, then the
+ * `binaries.<tool>.path` config) always beats the system `PATH`. A pin that is
+ * non-absolute or missing is a HARD miss — the substrate does NOT silently fall
+ * back to `PATH` (the operator asked for a specific binary). A `PATH` miss yields
+ * a not-found result (the caller raises a `ConfigurationError` pointing at
+ * `doctor`); resolution NEVER fetches a binary.
+ *
+ * Pure given its {@link BinaryResolveDeps} (existence check + PATH lookup) — the
+ * real deps live in `process-exec.ts` (the IO boundary). Returns data, never
+ * throws.
+ */
+import { isAbsolute } from 'node:path';
+/** Validate one operator-pinned path (absolute + exists). Returns the resolution or a miss reason. */
+function resolvePin(path, layer, deps) {
+    if (!isAbsolute(path)) {
+        return {
+            found: false,
+            command: path,
+            reason: `${layer} binary path must be absolute: ${path}`,
+            searched: [path],
+        };
+    }
+    if (!deps.existsSync(path)) {
+        return {
+            found: false,
+            command: path,
+            reason: `${layer} binary path does not exist: ${path}`,
+            searched: [path],
+        };
+    }
+    return { found: true, path, layer };
+}
+/**
+ * Resolve the scanner binary by the layered order env-pin → config-pin → `PATH`.
+ * An operator pin (env or config) wins and never falls through to `PATH`; a
+ * broken pin is a hard miss with a reason.
+ */
+export function resolveBinary(input, deps) {
+    const envPath = input.envPath?.trim();
+    if (envPath !== undefined && envPath.length > 0) {
+        return resolvePin(envPath, 'env', deps);
+    }
+    const configuredPath = input.configuredPath?.trim();
+    if (configuredPath !== undefined && configuredPath.length > 0) {
+        return resolvePin(configuredPath, 'config', deps);
+    }
+    const platform = input.platform ?? process.platform;
+    const onPath = deps.which(input.command, platform);
+    if (onPath !== undefined && onPath.length > 0) {
+        return { found: true, path: onPath, layer: 'path' };
+    }
+    return {
+        found: false,
+        command: input.command,
+        reason: `'${input.command}' was not found on PATH`,
+        searched: [`PATH:${input.command}`],
+    };
+}
+/** Derive the default env-var name that pins a tool's binary: `OPENSIP_<TOOL>_BIN`. */
+export function defaultBinaryEnvVar(tool) {
+    return `OPENSIP_${tool.replaceAll('-', '_').toUpperCase()}_BIN`;
+}
+//# sourceMappingURL=binary-resolver.js.map

package/dist/binary-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-resolver.js","sourceRoot":"","sources":["../src/binary-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAgCvC,sGAAsG;AACtG,SAAS,UAAU,CACjB,IAAY,EACZ,KAAuB,EACvB,IAAuB;IAEvB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,GAAG,KAAK,kCAAkC,IAAI,EAAE;YACxD,QAAQ,EAAE,CAAC,IAAI,CAAC;SACjB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,GAAG,KAAK,gCAAgC,IAAI,EAAE;YACtD,QAAQ,EAAE,CAAC,IAAI,CAAC;SACjB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAyB,EACzB,IAAuB;IAEvB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;IACtC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,OAAO,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IACpD,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,OAAO,UAAU,CAAC,cAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACtD,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,IAAI,KAAK,CAAC,OAAO,yBAAyB;QAClD,QAAQ,EAAE,CAAC,QAAQ,KAAK,CAAC,OAAO,EAAE,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,WAAW,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC;AAClE,CAAC"}

package/dist/define-external-tool-adapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview `defineExternalToolAdapter(spec) → Tool` (ADR-0090).
+ *
+ * A thin authoring factory over `defineTool` — an adapter is an ORDINARY `Tool`
+ * (no new plugin kind). It owns: the primary `scan` command (and any additional
+ * scanner verbs), the auto-added nested `doctor`/`version` commands, the
+ * `message-hash` fingerprint default (stamped WORKER-SIDE in the run loop, never
+ * read off the synthetic Tool — `synthesizeExternalTool` drops
+ * `fingerprintStrategy`), and the optional namespaced config block.
+ *
+ * The scan handler runs the run loop and RETURNS a `ToolRunCompletion`
+ * (`{ envelope, session }`) — emission/egress happen INSIDE the loop via
+ * `cli.*` seams (output mode `raw-stream`/`'runtime-render-dispatch'`, like sim:
+ * a runtime-conditional render + egress + session flow no static mode captures).
+ */
+import type { ExternalToolAdapterSpec } from './types.js';
+import type { Tool } from '@opensip-cli/core';
+/**
+ * Build an external-scanner adapter `Tool` from its declarative {@link
+ * ExternalToolAdapterSpec}. The first command is the primary verb
+ * (`opensip <tool>`); any additional scanner commands mount as nested verbs;
+ * `doctor` and `version` are always added.
+ */
+export declare function defineExternalToolAdapter(spec: ExternalToolAdapterSpec): Tool;
+//# sourceMappingURL=define-external-tool-adapter.d.ts.map

package/dist/define-external-tool-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-external-tool-adapter.d.ts","sourceRoot":"","sources":["../src/define-external-tool-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,OAAO,KAAK,EAAuB,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAEV,IAAI,EAKL,MAAM,mBAAmB,CAAC;AA8E3B;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAoE7E"}

package/dist/define-external-tool-adapter.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview `defineExternalToolAdapter(spec) → Tool` (ADR-0090).
+ *
+ * A thin authoring factory over `defineTool` — an adapter is an ORDINARY `Tool`
+ * (no new plugin kind). It owns: the primary `scan` command (and any additional
+ * scanner verbs), the auto-added nested `doctor`/`version` commands, the
+ * `message-hash` fingerprint default (stamped WORKER-SIDE in the run loop, never
+ * read off the synthetic Tool — `synthesizeExternalTool` drops
+ * `fingerprintStrategy`), and the optional namespaced config block.
+ *
+ * The scan handler runs the run loop and RETURNS a `ToolRunCompletion`
+ * (`{ envelope, session }`) — emission/egress happen INSIDE the loop via
+ * `cli.*` seams (output mode `raw-stream`/`'runtime-render-dispatch'`, like sim:
+ * a runtime-conditional render + egress + session flow no static mode captures).
+ */
+import { defineNestedCommand, definePrimaryCommand, defineTool, ValidationError, } from '@opensip-cli/core';
+import { defaultAdapterConfig, defaultAdapterConfigManifest } from './adapter-config.js';
+import { buildDoctorCommand } from './doctor-command.js';
+import { resolveFingerprintStrategy } from './fingerprint.js';
+import { runScanLoop } from './run-loop.js';
+import { buildVersionCommand } from './version-command.js';
+const SCAN_COMMON_FLAGS = [
+    'json',
+    'cwd',
+    'quiet',
+    'verbose',
+    'debug',
+    'reportTo',
+    'apiKey',
+    'open',
+];
+/**
+ * The baseline-ratchet flags every scanner verb inherits (ADR-0036). Wired ONCE
+ * here so all adapters get the host gate loop verbatim — `--gate-save` captures
+ * the current fingerprint-stamped findings as the project baseline; `--gate-compare`
+ * diffs against it and (per the reserved `failOnDegraded` key) hard-fails on
+ * net-new findings. Mirrors fit's `--gate-save` / `--gate-compare` descriptions;
+ * the run loop reads them as `opts.gateSave` / `opts.gateCompare`.
+ */
+const SCAN_GATE_OPTIONS = [
+    {
+        flag: '--gate-save',
+        description: 'Architecture-gate: save current findings as baseline in the project SQLite store (mutually exclusive with --gate-compare)',
+        default: false,
+    },
+    {
+        flag: '--gate-compare',
+        description: 'Architecture-gate: compare current findings against the saved baseline; exit 1 on regression',
+        default: false,
+    },
+];
+/** Run one scanner command and shape its result as a `ToolRunCompletion`. */
+async function dispatchScan(cli, spec, command, rawOpts) {
+    const completion = await runScanLoop({
+        cli,
+        tool: spec.identity.name,
+        adapterPackage: spec.metadata.adapterPackage,
+        command,
+        binary: spec.binary,
+        fingerprintStrategy: resolveFingerprintStrategy(spec.fingerprintStrategy),
+        opts: rawOpts,
+    });
+    // `undefined` ⇒ a gate config error the loop already recorded via reportFailure
+    // (the host replays the exit). No envelope/session to persist.
+    if (completion === undefined)
+        return {};
+    return { envelope: completion.envelope, session: completion.session };
+}
+/** Validate the spec at definition time so misconfiguration fails loudly, not at runtime. */
+function assertSpec(spec) {
+    if (spec.commands.length === 0) {
+        throw new ValidationError(`External adapter '${spec.identity.name}' must declare at least one command.`, {
+            code: 'ADAPTER.SPEC.NO_COMMANDS',
+        });
+    }
+    for (const command of spec.commands) {
+        if (command.output.kind !== 'sarif' && command.parse === undefined) {
+            throw new ValidationError(`External adapter '${spec.identity.name}' command '${command.name}' (${command.output.kind}) must declare a 'parse' (only SARIF commands may omit it — the shared ingestSarif handles those).`, { code: 'ADAPTER.SPEC.MISSING_PARSE' });
+        }
+    }
+}
+/**
+ * Build an external-scanner adapter `Tool` from its declarative {@link
+ * ExternalToolAdapterSpec}. The first command is the primary verb
+ * (`opensip <tool>`); any additional scanner commands mount as nested verbs;
+ * `doctor` and `version` are always added.
+ */
+export function defineExternalToolAdapter(spec) {
+    assertSpec(spec);
+    const [primary, ...rest] = spec.commands;
+    // R6 (ADR-0090 §4.3): an adapter that declares no `config` DEFAULTS to claiming
+    // its namespace (`binaries.<tool>.path` operator pin + the reserved verdict-policy
+    // keys) so the resolver/gate keys are configurable AND an operator's `<tool>:`
+    // block never bricks the project. When the adapter uses the DEFAULT config the
+    // substrate can also emit a coarse, serializable manifest descriptor (the host
+    // pre-fork pass needs it — it cannot import the runtime Zod). A custom `spec.config`
+    // keeps the runtime Zod but emits NO descriptor (its validation defers to the
+    // worker deep pass), so `adapterConfigManifest` stays undefined.
+    const config = spec.config ?? defaultAdapterConfig();
+    const configManifest = spec.config === undefined ? defaultAdapterConfigManifest(spec.identity.name) : undefined;
+    const scanPrimary = definePrimaryCommand({
+        description: primary.description ?? spec.metadata.description,
+        commonFlags: [...SCAN_COMMON_FLAGS],
+        options: [...SCAN_GATE_OPTIONS],
+        scope: 'project',
+        output: 'raw-stream',
+        rawStreamReason: 'runtime-render-dispatch',
+        handler: (rawOpts, cli) => dispatchScan(cli, spec, primary, rawOpts),
+    });
+    const nestedScans = rest.map((command) => defineNestedCommand({
+        name: command.name,
+        description: command.description ?? `Run the ${spec.identity.name} ${command.name} scan`,
+        commonFlags: [...SCAN_COMMON_FLAGS],
+        options: [...SCAN_GATE_OPTIONS],
+        scope: 'project',
+        output: 'raw-stream',
+        rawStreamReason: 'runtime-render-dispatch',
+        handler: (rawOpts, cli) => dispatchScan(cli, spec, command, rawOpts),
+    }));
+    const tool = defineTool({
+        identity: spec.identity,
+        metadata: {
+            id: spec.metadata.id,
+            version: spec.metadata.version ?? '0.0.0',
+            description: spec.metadata.description,
+        },
+        commandSpecs: [
+            scanPrimary,
+            ...nestedScans,
+            buildDoctorCommand({ tool: spec.identity.name, network: spec.network, binary: spec.binary }),
+            buildVersionCommand({ tool: spec.identity.name, binary: spec.binary }),
+        ],
+        ...(spec.contractVersion === undefined ? {} : { contractVersion: spec.contractVersion }),
+        extensionPoints: {
+            fingerprintStrategy: resolveFingerprintStrategy(spec.fingerprintStrategy),
+            config,
+        },
+    });
+    // Stamp the adapter-substrate markers the manifest generator + parity gate read
+    // back (`adapter-manifest.ts`): the network posture (→ `requires`) and the coarse
+    // config descriptor (→ `opensipTools.config`). Kept off the core `Tool` contract
+    // — these are adapter concepts, not kernel ones.
+    const markers = {
+        adapterNetwork: spec.network,
+        ...(configManifest === undefined ? {} : { adapterConfigManifest: configManifest }),
+    };
+    return Object.assign(tool, markers);
+}
+//# sourceMappingURL=define-external-tool-adapter.js.map

package/dist/define-external-tool-adapter.js.map

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

package/dist/doctor-command.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview The standardized `doctor` command (ADR-0090 §4.9, Phase-0
+ * decision 3).
+ *
+ * Every adapter gets the SAME auto-generated `doctor` (the author writes none):
+ * it PROBES the wrapped binary (resolve → version → minVersion → posture →
+ * credential-env presence) and reports a plain {@link AdapterDoctorReport} —
+ * NOT a `CommandResult` variant (the union is closed in `contracts`).
+ *
+ * Output mode is `raw-stream`/`'diagnostic-gate'` (not `command-result`): the
+ * handler must produce a STRUCTURED `cli.emitJson(report)` for `--json` AND a
+ * human `cli.render({ type:'text-lines' })`, then set exit 2 when not-ready. The
+ * `command-result` dispatch arm would JSON-stringify a single returned result
+ * (it cannot do both shapes) and rejects a void return — so `raw-stream`, the
+ * host's sanctioned runtime-conditional output escape (same as `fit export`), is
+ * the correct mode. The worker replays the explicit `emitJson`/`render`/
+ * `setExitCode` calls. (See the report's "deviation" note.)
+ *
+ * The probe runs WORKER-SIDE for an installed adapter; readiness drives exit 0
+ * (ready) / 2 (not-ready) so CI can gate on `opensip <tool> doctor`.
+ */
+import type { BinaryResolveDeps } from './binary-resolver.js';
+import type { ProbeVersionInput } from './process-exec.js';
+import type { BinaryResolutionLayer, BinarySpec, NetworkPosture } from './types.js';
+import type { ToolCliContext, ToolCommandSpecInput } from '@opensip-cli/core';
+/** Whether the resolved version satisfies the declared minimum. */
+export type VersionStatus = 'ok' | 'too-old' | 'unknown' | 'not-applicable';
+/** The structured readiness report `doctor` emits (NOT a `CommandResult` variant). */
+export interface AdapterDoctorReport {
+    readonly tool: string;
+    readonly network: NetworkPosture;
+    readonly binary: {
+        readonly found: boolean;
+        readonly command: string;
+        readonly path?: string;
+        readonly layer?: BinaryResolutionLayer;
+    };
+    readonly version: {
+        readonly detected?: string;
+        readonly minVersion?: string;
+        readonly status: VersionStatus;
+    };
+    /** Presence-only (never the value) when the posture needs a credential (ADR-0092/0071). */
+    readonly credentialEnv?: {
+        readonly name: string;
+        readonly present: boolean;
+    };
+    readonly installHint?: string;
+    readonly ready: boolean;
+}
+/** Deps the probe is parameterized over (real impls default; E2E injects fakes). */
+export interface DoctorProbeDeps {
+    readonly binaryDeps: BinaryResolveDeps;
+    readonly probeVersion: (input: ProbeVersionInput) => string | undefined;
+    readonly env: NodeJS.ProcessEnv;
+}
+/** Compare a detected version against a minimum. */
+export declare function compareVersion(detected: string | undefined, min: string | undefined): VersionStatus;
+/** The inputs to {@link probeAdapter}: the tool identity, posture, binary spec, and resolved config. */
+export interface ProbeAdapterInput {
+    readonly tool: string;
+    readonly network: NetworkPosture;
+    readonly binary: BinarySpec;
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/** Probe a binary and build its {@link AdapterDoctorReport}. Pure given deps. */
+export declare function probeAdapter(input: ProbeAdapterInput, deps: DoctorProbeDeps): AdapterDoctorReport;
+/** Render an {@link AdapterDoctorReport} as human display lines. */
+export declare function doctorReportLines(report: AdapterDoctorReport): string[];
+/** The inputs to {@link buildDoctorCommand}: the tool identity, posture, and binary spec. */
+export interface DoctorCommandInput {
+    readonly tool: string;
+    readonly network: NetworkPosture;
+    readonly binary: BinarySpec;
+}
+/**
+ * Build the nested `doctor` command. Probes the binary worker-side, emits the
+ * structured report (`--json`) or human lines, and sets exit 2 when not-ready.
+ */
+export declare function buildDoctorCommand(input: DoctorCommandInput, probeDeps?: DoctorProbeDeps): ToolCommandSpecInput<unknown, ToolCliContext>;
+//# sourceMappingURL=doctor-command.d.ts.map

package/dist/doctor-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-command.d.ts","sourceRoot":"","sources":["../src/doctor-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAI9E,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAE5E,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;KAChC,CAAC;IACF,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,MAAM,GAAG,SAAS,CAAC;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAeD,oDAAoD;AACpD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,aAAa,CAaf;AAED,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAqDjG;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAuBvE;AAED,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,SAAS,CAAC,EAAE,eAAe,GAC1B,oBAAoB,CAAC,OAAO,EAAE,cAAc,CAAC,CAgC/C"}

package/dist/doctor-command.js

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview The standardized `doctor` command (ADR-0090 §4.9, Phase-0
+ * decision 3).
+ *
+ * Every adapter gets the SAME auto-generated `doctor` (the author writes none):
+ * it PROBES the wrapped binary (resolve → version → minVersion → posture →
+ * credential-env presence) and reports a plain {@link AdapterDoctorReport} —
+ * NOT a `CommandResult` variant (the union is closed in `contracts`).
+ *
+ * Output mode is `raw-stream`/`'diagnostic-gate'` (not `command-result`): the
+ * handler must produce a STRUCTURED `cli.emitJson(report)` for `--json` AND a
+ * human `cli.render({ type:'text-lines' })`, then set exit 2 when not-ready. The
+ * `command-result` dispatch arm would JSON-stringify a single returned result
+ * (it cannot do both shapes) and rejects a void return — so `raw-stream`, the
+ * host's sanctioned runtime-conditional output escape (same as `fit export`), is
+ * the correct mode. The worker replays the explicit `emitJson`/`render`/
+ * `setExitCode` calls. (See the report's "deviation" note.)
+ *
+ * The probe runs WORKER-SIDE for an installed adapter; readiness drives exit 0
+ * (ready) / 2 (not-ready) so CI can gate on `opensip <tool> doctor`.
+ */
+import { EXIT_CODES } from '@opensip-cli/contracts';
+import { defineNestedCommand } from '@opensip-cli/core';
+import { defaultBinaryEnvVar, resolveBinary } from './binary-resolver.js';
+import { asObject, getString } from './ingest-json.js';
+import { defaultBinaryDeps, probeBinaryVersion } from './process-exec.js';
+const VERSION_PROBE_TIMEOUT_MS = 15_000;
+const DEFAULT_PROBE_DEPS = {
+    binaryDeps: defaultBinaryDeps,
+    probeVersion: probeBinaryVersion,
+    env: process.env,
+};
+/** Parse a semver-ish string to numeric segments (`'8.18.0'` → `[8,18,0]`). */
+function parseVersion(raw) {
+    const match = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(raw);
+    if (match === null)
+        return undefined;
+    return [Number(match[1] ?? 0), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+/** Compare a detected version against a minimum. */
+export function compareVersion(detected, min) {
+    if (min === undefined)
+        return 'not-applicable';
+    if (detected === undefined)
+        return 'unknown';
+    const a = parseVersion(detected);
+    const b = parseVersion(min);
+    if (a === undefined || b === undefined)
+        return 'unknown';
+    for (let i = 0; i < 3; i++) {
+        const left = a[i] ?? 0;
+        const right = b[i] ?? 0;
+        if (left > right)
+            return 'ok';
+        if (left < right)
+            return 'too-old';
+    }
+    return 'ok';
+}
+/** Probe a binary and build its {@link AdapterDoctorReport}. Pure given deps. */
+export function probeAdapter(input, deps) {
+    const { tool, binary, network } = input;
+    const envVar = binary.envVar ?? defaultBinaryEnvVar(tool);
+    const resolution = resolveBinary({
+        command: binary.command,
+        configuredPath: getString(asObject(input.config.binaries)?.[tool], 'path'),
+        envPath: deps.env[envVar],
+    }, deps.binaryDeps);
+    const detected = resolution.found
+        ? deps.probeVersion({
+            path: resolution.path,
+            versionArgs: binary.versionArgs,
+            parse: binary.versionParse,
+            timeoutMs: VERSION_PROBE_TIMEOUT_MS,
+        })
+        : undefined;
+    const versionStatus = compareVersion(detected, binary.minVersion);
+    const credentialEnv = network === 'auth-required'
+        ? { name: `OPENSIP_${tool.replaceAll('-', '_').toUpperCase()}_TOKEN`, present: false }
+        : undefined;
+    const credential = credentialEnv === undefined
+        ? undefined
+        : { ...credentialEnv, present: (deps.env[credentialEnv.name] ?? '').length > 0 };
+    const ready = resolution.found &&
+        versionStatus !== 'too-old' &&
+        (network !== 'auth-required' || (credential?.present ?? false));
+    return {
+        tool,
+        network,
+        binary: resolution.found
+            ? { found: true, command: binary.command, path: resolution.path, layer: resolution.layer }
+            : { found: false, command: binary.command },
+        version: {
+            ...(detected === undefined ? {} : { detected }),
+            ...(binary.minVersion === undefined ? {} : { minVersion: binary.minVersion }),
+            status: versionStatus,
+        },
+        ...(credential === undefined ? {} : { credentialEnv: credential }),
+        ...(resolution.found || binary.installHint === undefined
+            ? {}
+            : { installHint: binary.installHint }),
+        ready,
+    };
+}
+/** Render an {@link AdapterDoctorReport} as human display lines. */
+export function doctorReportLines(report) {
+    const binaryLine = report.binary.found
+        ? `found (${report.binary.layer ?? ''}) ${report.binary.path ?? ''}`
+        : `NOT FOUND (${report.binary.command})`;
+    const minNote = report.version.minVersion === undefined
+        ? ''
+        : ` (min ${report.version.minVersion}: ${report.version.status})`;
+    const lines = [
+        `binary:  ${binaryLine}`,
+        `version: ${report.version.detected ?? 'unknown'}${minNote}`,
+        `network: ${report.network}`,
+    ];
+    if (report.credentialEnv !== undefined) {
+        lines.push(`credential ${report.credentialEnv.name}: ${report.credentialEnv.present ? 'set' : 'MISSING'}`);
+    }
+    if (!report.binary.found && report.installHint !== undefined) {
+        lines.push(`install: ${report.installHint}`);
+    }
+    lines.push(`ready:   ${report.ready ? 'yes' : 'NO'}`);
+    return lines;
+}
+/**
+ * Build the nested `doctor` command. Probes the binary worker-side, emits the
+ * structured report (`--json`) or human lines, and sets exit 2 when not-ready.
+ */
+export function buildDoctorCommand(input, probeDeps) {
+    const deps = probeDeps ?? DEFAULT_PROBE_DEPS;
+    return defineNestedCommand({
+        name: 'doctor',
+        description: `Check that the ${input.tool} binary is installed and ready`,
+        commonFlags: ['json', 'cwd'],
+        scope: 'none',
+        output: 'raw-stream',
+        rawStreamReason: 'diagnostic-gate',
+        handler: async (rawOpts, cli) => {
+            const opts = rawOpts;
+            const config = (cli.scope.toolConfig?.[input.tool] ?? {});
+            const report = probeAdapter({ tool: input.tool, network: input.network, binary: input.binary, config }, deps);
+            if (opts.json === true) {
+                cli.emitJson(report);
+            }
+            else {
+                await cli.render({
+                    type: 'text-lines',
+                    title: `${input.tool} doctor`,
+                    lines: doctorReportLines(report),
+                });
+            }
+            if (!report.ready) {
+                cli.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+            }
+        },
+    });
+}
+//# sourceMappingURL=doctor-command.js.map

package/dist/doctor-command.js.map

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