cueline 0.2.2 → 0.3.0

package/dist/src/diagnostics/upgrade-preflight.js

@@ -0,0 +1,182 @@
+import { lstat } from "node:fs/promises";
+import { listCueLineRuns, routingConfigPath } from "../api.js";
+import { loadRoutingConfig } from "../router/config-loader.js";
+import { defaultCueLineHome } from "../state/paths.js";
+import { CUELINE_VERSION } from "../version.js";
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function parseStableVersion(value) {
+    const match = STABLE_SEMVER.exec(value);
+    if (match === null)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+function compareVersion(left, right) {
+    return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function collectUpgradePreflight(options) {
+    const environment = options.environment ?? process.env;
+    const nodeVersion = options.nodeVersion ?? process.versions.node;
+    const targetVersion = options.targetVersion;
+    const configPath = routingConfigPath(environment);
+    const home = defaultCueLineHome(environment);
+    const findings = [];
+    const current = parseStableVersion(CUELINE_VERSION);
+    const target = parseStableVersion(targetVersion);
+    if (target === undefined) {
+        findings.push({
+            code: "TARGET_VERSION_INVALID",
+            severity: "blocker",
+            surface: "version",
+            message: "Target version must be a stable semantic version such as 1.0.0.",
+        });
+    }
+    else if (current !== undefined && compareVersion(target, current) < 0) {
+        findings.push({
+            code: "TARGET_VERSION_DOWNGRADE",
+            severity: "blocker",
+            surface: "version",
+            message: "Upgrade preflight does not authorize a downgrade.",
+        });
+    }
+    else if (current !== undefined && compareVersion(target, current) === 0) {
+        findings.push({
+            code: "TARGET_VERSION_NOT_NEWER",
+            severity: "warning",
+            surface: "version",
+            message: "Target version is already installed.",
+        });
+    }
+    const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+    const nodeOk = Number.isSafeInteger(nodeMajor) && nodeMajor >= 22;
+    if (!nodeOk) {
+        findings.push({
+            code: "NODE_VERSION_UNSUPPORTED",
+            severity: "blocker",
+            surface: "node",
+            message: "Node.js 22 or newer is required before upgrading CueLine.",
+        });
+    }
+    let configValid = true;
+    try {
+        await loadRoutingConfig(configPath);
+    }
+    catch {
+        configValid = false;
+        findings.push({
+            code: "ROUTING_CONFIG_INVALID",
+            severity: "blocker",
+            surface: "config",
+            message: "The active routing configuration cannot be loaded by this version.",
+        });
+    }
+    let stateKind = "missing";
+    let statePrivate = null;
+    try {
+        const state = await lstat(home);
+        if (state.isSymbolicLink()) {
+            stateKind = "symlink";
+            findings.push({
+                code: "STATE_HOME_SYMLINK_UNSAFE",
+                severity: "blocker",
+                surface: "state",
+                message: "CueLine state home is a symbolic link; resolve it explicitly before upgrading.",
+            });
+        }
+        else if (state.isDirectory()) {
+            stateKind = "directory";
+            statePrivate = (state.mode & 0o077) === 0;
+            if (!statePrivate) {
+                findings.push({
+                    code: "STATE_HOME_PERMISSIONS_UNSAFE",
+                    severity: "blocker",
+                    surface: "state",
+                    message: "CueLine state home grants group or other permissions.",
+                });
+            }
+        }
+        else {
+            stateKind = "other";
+            findings.push({
+                code: "STATE_HOME_NOT_DIRECTORY",
+                severity: "blocker",
+                surface: "state",
+                message: "CueLine state home exists but is not a directory.",
+            });
+        }
+    }
+    catch (error) {
+        if (!isNotFound(error)) {
+            stateKind = "other";
+            findings.push({
+                code: "STATE_HOME_UNREADABLE",
+                severity: "blocker",
+                surface: "state",
+                message: "CueLine state home metadata cannot be read.",
+            });
+        }
+    }
+    let totalRuns = 0;
+    let nonTerminalRuns = 0;
+    let unreadableRuns = 0;
+    if (stateKind === "missing" || (stateKind === "directory" && statePrivate === true)) {
+        try {
+            const runs = await listCueLineRuns({ home, environment });
+            totalRuns = runs.length;
+            unreadableRuns = runs.filter((run) => !run.readable).length;
+            nonTerminalRuns = runs.filter((run) => run.readable &&
+                run.status !== "complete" &&
+                run.status !== "blocked" &&
+                run.status !== "cancelled").length;
+            if (unreadableRuns > 0) {
+                findings.push({
+                    code: "RUN_EVIDENCE_UNREADABLE",
+                    severity: "blocker",
+                    surface: "runs",
+                    message: "At least one persisted run cannot be read safely.",
+                });
+            }
+            if (nonTerminalRuns > 0) {
+                findings.push({
+                    code: "NON_TERMINAL_RUNS_PRESENT",
+                    severity: "blocker",
+                    surface: "runs",
+                    message: "Finish, block, or cancel every persisted run before upgrading.",
+                });
+            }
+        }
+        catch {
+            findings.push({
+                code: "RUN_STORE_UNREADABLE",
+                severity: "blocker",
+                surface: "runs",
+                message: "The persisted run store cannot be inspected safely.",
+            });
+        }
+    }
+    return {
+        schema: "cueline-upgrade-preflight/1",
+        version: CUELINE_VERSION,
+        targetVersion,
+        status: findings.some((finding) => finding.severity === "blocker")
+            ? "blocked"
+            : "ready",
+        checks: {
+            node: { version: nodeVersion, requirement: ">=22", ok: nodeOk },
+            config: { path: configPath, valid: configValid },
+            stateHome: { path: home, kind: stateKind, private: statePrivate },
+            runs: { total: totalRuns, nonTerminal: nonTerminalRuns, unreadable: unreadableRuns },
+        },
+        findings,
+    };
+}
+//# sourceMappingURL=upgrade-preflight.js.map

package/dist/src/diagnostics/upgrade-preflight.js.map

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

package/dist/src/observation/run-bundle.d.ts

@@ -0,0 +1,27 @@
+import type { CueLineRunVerificationReport, CueLineRuntimeOptions } from "../api-contracts.js";
+import { safeCueLineRunStatus } from "../cli/run-status-view.js";
+import { type CueLineRunDiagnosis } from "../diagnostics/run-doctor.js";
+import { type CueLineRunTimeline } from "./run-timeline.js";
+export declare const RUN_BUNDLE_PROTOCOL = "cueline-run-bundle/0.1";
+export interface CueLineRunSupportBundle {
+    schema: "cueline-run-export/1";
+    protocol: typeof RUN_BUNDLE_PROTOCOL;
+    version: string;
+    generatedAt: string;
+    runId: string;
+    status: ReturnType<typeof safeCueLineRunStatus>;
+    verification: CueLineRunVerificationReport;
+    diagnosis: CueLineRunDiagnosis;
+    timeline: CueLineRunTimeline;
+}
+export interface CueLineRunSupportBundleOptions extends Pick<CueLineRuntimeOptions, "home" | "environment" | "now"> {
+    timelineLimit?: number;
+}
+/**
+ * One sanitized JSON document for bug reports and cross-machine support:
+ * metadata-only status, content-free verification, doctor diagnosis, and the
+ * hashed audit timeline. Every section reuses an existing sanitized surface;
+ * this module adds no new evidence projection of its own, so it cannot leak
+ * more than the surfaces it composes.
+ */
+export declare function buildCueLineRunSupportBundle(runId: string, options?: CueLineRunSupportBundleOptions): Promise<CueLineRunSupportBundle>;

package/dist/src/observation/run-bundle.js

@@ -0,0 +1,55 @@
+import { loadCueLineRunStatus } from "../api-runtime-lifecycle.js";
+import { verifyCueLineRun } from "../api-run-verification.js";
+import { safeCueLineRunStatus } from "../cli/run-status-view.js";
+import { CueLineError } from "../core/errors.js";
+import { runtimeEnvironment } from "../core/runtime.js";
+import { diagnoseCueLineRunStatus, } from "../diagnostics/run-doctor.js";
+import { defaultCueLineHome } from "../state/paths.js";
+import { CUELINE_VERSION } from "../version.js";
+import { loadCueLineRunTimeline } from "./run-timeline.js";
+export const RUN_BUNDLE_PROTOCOL = "cueline-run-bundle/0.1";
+/**
+ * One sanitized JSON document for bug reports and cross-machine support:
+ * metadata-only status, content-free verification, doctor diagnosis, and the
+ * hashed audit timeline. Every section reuses an existing sanitized surface;
+ * this module adds no new evidence projection of its own, so it cannot leak
+ * more than the surfaces it composes.
+ */
+export async function buildCueLineRunSupportBundle(runId, options = {}) {
+    const timelineLimit = options.timelineLimit ?? 1000;
+    if (!Number.isSafeInteger(timelineLimit) ||
+        timelineLimit < 1 ||
+        timelineLimit > 1000) {
+        throw new CueLineError("RUN_BUNDLE_LIMIT_INVALID", "timelineLimit must be an integer between 1 and 1000.");
+    }
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const shared = {
+        home,
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+    };
+    const status = await loadCueLineRunStatus(runId, {
+        ...shared,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    const [verification, timeline] = await Promise.all([
+        verifyCueLineRun(runId, {
+            ...shared,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        }),
+        loadCueLineRunTimeline(runId, { ...shared, limit: timelineLimit }),
+    ]);
+    const generatedAt = (options.now === undefined ? new Date() : options.now()).toISOString();
+    return {
+        schema: "cueline-run-export/1",
+        protocol: RUN_BUNDLE_PROTOCOL,
+        version: CUELINE_VERSION,
+        generatedAt,
+        runId,
+        status: safeCueLineRunStatus(status),
+        verification,
+        diagnosis: diagnoseCueLineRunStatus(status),
+        timeline,
+    };
+}
+//# sourceMappingURL=run-bundle.js.map

package/dist/src/observation/run-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-bundle.js","sourceRoot":"","sources":["../../../src/observation/run-bundle.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,wBAAwB,GAEzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAA2B,MAAM,mBAAmB,CAAC;AAEpF,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAmB5D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,KAAa,EACb,OAAO,GAAmC,EAAE;IAE5C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;IACpD,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC;QACpC,aAAa,GAAG,CAAC;QACjB,aAAa,GAAG,IAAI,EACpB,CAAC;QACD,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,sDAAsD,CACvD,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,EAAE,CAAC;IAChE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG;QACb,IAAI;QACJ,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;KACnF,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,KAAK,EAAE;QAC/C,GAAG,MAAM;QACT,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KAC3D,CAAC,CAAC;IACH,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjD,gBAAgB,CAAC,KAAK,EAAE;YACtB,GAAG,MAAM;YACT,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;SAC3D,CAAC;QACF,sBAAsB,CAAC,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;KACnE,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3F,OAAO;QACL,MAAM,EAAE,sBAAsB;QAC9B,QAAQ,EAAE,mBAAmB;QAC7B,OAAO,EAAE,eAAe;QACxB,WAAW;QACX,KAAK;QACL,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC;QACpC,YAAY;QACZ,SAAS,EAAE,wBAAwB,CAAC,MAAM,CAAC;QAC3C,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const CUELINE_VERSION = "0.2.2";
+export declare const CUELINE_VERSION = "0.3.0";

package/dist/src/version.js

@@ -1,2 +1,2 @@
-export const CUELINE_VERSION = "0.2.2";
+export const CUELINE_VERSION = "0.3.0";
 //# sourceMappingURL=version.js.map

package/docs/1.0/ideas/machine-output-contracts.md

@@ -0,0 +1,47 @@
+# Machine-output contracts experiment
+
+## Hypothesis and user value
+
+Automation that consumes CueLine health output needs versioned, executable
+contracts so a release cannot silently change field names, types, redaction or
+nested structure.
+
+## Change boundary
+
+- Adds explicit schema identifiers to `doctor --json` and `routing --json`;
+  preserves the existing `routing explain --json` identifier.
+- Publishes strict JSON Schema 2020-12 contracts for those three outputs.
+- Adds a real CLI contract validator to CI and a development-only Ajv
+  dependency; CueLine runtime dependencies remain empty.
+- Does not change human output, routing decisions, browser behavior, provider
+  calls or durable state.
+
+## Acceptance and adversarial cases
+
+1. Real doctor, routing and routing-explain JSON validate against their schemas.
+2. Every public object uses `additionalProperties: false`.
+3. A secret-like top-level field is rejected.
+4. A runner `argv` field is rejected.
+5. Missing required fields and wrong schema versions are rejected.
+6. Valid and invalid routing configuration variants retain parseable output.
+
+## Verified evidence
+
+- Targeted contract and CLI tests: 67 passed, 0 failed, including all three
+  degraded invalid-config variants.
+- Contract validation command: 3 passed, 0 failed.
+- Full test suite: 494 passed, 0 failed after updating four authoritative
+  machine-output snapshots for the new schema identifiers.
+- TypeScript build: passed.
+- Plugin validation: passed.
+- `npm pack --dry-run`: passed; all three schema files and the validator are in
+  the package, while Ajv remains development-only.
+
+## Rollback
+
+Revert this branch's commit. It owns the three schemas, validator, tests, Ajv
+development dependency, CI step, schema identifiers and updated snapshots.
+
+This experiment remains isolated on `codex/idea-machine-output-contract`. It
+must not be merged into `main`; Vincent decides whether it is selected or
+integrated.

package/docs/1.0/ideas/node26-contract.md

@@ -0,0 +1,50 @@
+# Node 26 support contract experiment
+
+## Hypothesis and user value
+
+CueLine should preserve Node 22 as its minimum while proving current even-LTS
+compatibility through one synchronized engines, CI and documentation contract.
+
+## Change boundary
+
+- Expands the existing Ubuntu/macOS CI matrix from Node 22/24 to 22/24/26.
+- Keeps `engines.node` at `>=22`.
+- Synchronizes all five README development sections and the compatibility
+  matrix.
+- Adds a read-only contract validator; it does not install, download or switch
+  Node versions.
+- Does not change runtime behavior, browser control, routing, state or provider
+  access.
+
+## Acceptance and adversarial cases
+
+1. Engine requirement is exactly `>=22`.
+2. CI Node majors are exactly 22, 24 and 26 on Ubuntu and macOS.
+3. All localized README files and compatibility docs name the tested majors.
+4. Removing Node 26, leaving one README stale or changing engines makes the
+   validator fail.
+5. The current Node 26 runtime passes the complete local release-facing checks.
+
+## Verified evidence
+
+- Node support validator: passed on Node 26.3.0.
+- Targeted contract tests: 4 passed, 0 failed.
+- Full test suite on Node 26.3.0: 494 passed, 0 failed.
+- Fake smoke on Node 26.3.0: 6 passed, 0 failed.
+- Shell install/reinstall/uninstall/foreign-file preservation: passed.
+- npm tarball global install, skill install, doctor and uninstall: passed.
+- TypeScript build, plugin validation and `npm pack --dry-run`: passed.
+
+## Remaining external verification
+
+The workflow now requests Node 26 on both Ubuntu and macOS, but this isolated
+branch has not been pushed. Therefore GitHub-hosted Node 26 results remain
+unverified until Vincent selects and explicitly authorizes remote integration.
+
+## Rollback
+
+Revert this branch's commit. It owns the CI matrix addition, support validator,
+tests, documentation synchronization and this experiment record.
+
+This experiment remains isolated on `codex/idea-node26-contract`. It must not be
+merged into `main`; Vincent decides whether it is selected or integrated.

package/docs/1.0/ideas/offline-self-test.md

@@ -0,0 +1,52 @@
+# Offline self-test experiment
+
+## Hypothesis and user value
+
+An installed CueLine package should be able to prove that its controller loop,
+process routing, durable state, final delivery, and run verifier work together
+without opening a browser, contacting a provider, or touching the user's real
+CueLine state.
+
+## Change boundary
+
+- Adds `cueline self-test [--json]`.
+- Uses an in-memory deterministic controller and the current Node executable.
+- Creates two private temporary directories for run state and workspace, then
+  removes only those exact directories before returning.
+- Does not read or write the configured `CUELINE_HOME` or `CUELINE_CONFIG`.
+- Does not open a browser, use credentials, contact a provider, or make a
+  network request.
+- Does not relax production controller provenance checks. The in-memory
+  adapter supplies fixed synthetic Pro-shaped evidence solely to exercise the
+  existing verifier; the report is explicitly marked `offline: true`.
+
+## Acceptance and adversarial cases
+
+1. The isolated controller completes exactly two rounds.
+2. One required local process job completes.
+3. The expected final delivery is recorded.
+4. `verifyCueLineRun` returns `verified` for the temporary run.
+5. A pre-existing `CUELINE_DEPTH` fails closed with
+   `NESTED_ROUTING_REJECTED` before temporary state is created.
+6. Unknown CLI arguments return exit code 2.
+7. JSON output contains neither temporary paths nor worker task content.
+8. Temporary-directory counts are unchanged across a real CLI invocation.
+
+## Verified evidence
+
+- Targeted integration tests: 4 passed, 0 failed.
+- Full test suite: 494 passed, 0 failed.
+- TypeScript build: passed.
+- Plugin validation: passed.
+- Real `./bin/cueline self-test --json`: status `ok`; two controller rounds,
+  one completed job, final delivery true, durable verification true.
+- Temporary cleanup check: 0 matching directories before and after.
+
+## Rollback
+
+Revert this branch's commit. The feature owns only
+`src/diagnostics/offline-self-test.ts`, its integration test and documentation,
+plus the focused command/help additions in `src/cli/main.ts`.
+
+This experiment remains isolated on `codex/idea-offline-self-test`. It must not
+be merged into `main`; Vincent decides whether it is selected or integrated.

package/docs/1.0/ideas/upgrade-preflight.md

@@ -0,0 +1,46 @@
+# Upgrade preflight experiment
+
+## Hypothesis and user value
+
+Before replacing an installed CueLine version, operators need one read-only
+command that proves the target is a valid forward upgrade and that local
+configuration and durable state are safe to carry forward.
+
+## Change boundary
+
+- Adds `cueline upgrade preflight --to <version> [--json]`.
+- Reads the current Node version, active routing configuration, state-home file
+  type and permissions, and sanitized persisted run summaries.
+- Never creates a state home, follows a state-home symlink, changes permissions,
+  migrates files, cancels runs, launches a browser, or contacts a provider.
+- Accepts stable semantic target versions only; it does not authorize downgrade
+  or prerelease migration policy.
+
+## Blocking conditions
+
+- Invalid or older target version.
+- Node older than 22.
+- Routing configuration unreadable by the installed version.
+- State home is a symlink, non-directory, unreadable, or grants group/other
+  permissions.
+- Any run is non-terminal or has unreadable durable evidence.
+
+## Verified evidence
+
+- Targeted integration tests: 5 passed, 0 failed.
+- Full test suite: 495 passed, 0 failed.
+- TypeScript build: passed.
+- Plugin validation: passed.
+- Real `./bin/cueline upgrade preflight --to 1.0.0 --json`: status `ready`
+  with a missing isolated state home.
+- The real CLI check verified that the missing state home remained absent.
+- A persisted non-terminal run retained the exact event-log size and mtime
+  across preflight.
+
+## Rollback
+
+Revert this branch's commit. It owns the preflight diagnostic, its tests and
+documentation, plus focused health-command and help entries.
+
+This experiment remains isolated on `codex/idea-upgrade-preflight`. It must not
+be merged into `main`; Vincent decides whether it is selected or integrated.

package/docs/compatibility.md

@@ -2,9 +2,9 @@
 
 ## Runtime matrix
 
-| Surface | v0.1 status | Notes |
+| Surface | Current status | Notes |
 |---|---|---|
-| Node.js 22+ ESM | Supported | Core protocol, state, router, runners, fake browser tests |
+| Node.js 22+ ESM | Supported | CI: 22, 24, 26 on Ubuntu and macOS; core protocol, state, router, runners, fake browser tests |
 | Codex Node REPL + built-in Browser (IAB) | Required for live control | Provides the imported API with the authenticated ChatGPT tab/browser client |
 | Current Codex caller | Default local executor | Performs caller `advise`; caller `work` requires durable claim/start/heartbeat/result proof |
 | `codex` CLI | Required only by bundled process route | Double authorization plus `--ignore-user-config`; auth remains under `CODEX_HOME`, user MCP config is not loaded |
@@ -19,9 +19,9 @@ The npm package has no runtime dependencies. Development requires TypeScript and
 
 CueLine is designed for a conversation already authenticated by the user at `chatgpt.com`. CueLine neither handles credentials nor verifies plan entitlement. Before each controller turn it may switch the composer to `Pro`; that is its only automatic model switch. It also requires Pro evidence on the completed response.
 
-The v0.1 adapter relies on accessible textbox/button roles, attachment chips, and assistant-message markup in the current ChatGPT web UI. ChatGPT's automatic conversion of a long filled prompt into an attachment is supported. Deliberate file upload is not. UI changes can cause explicit `COMPOSER_MISSING`, `SEND_BUTTON_MISSING`, or response-timeout errors. A fake adapter test cannot prove that the current live page still matches.
+The browser adapter relies on accessible textbox/button roles, attachment chips, and assistant-message markup in the current ChatGPT web UI. ChatGPT's automatic conversion of a long filled prompt into an attachment is supported. Deliberate file upload is not. UI changes can cause explicit `COMPOSER_MISSING`, `SEND_BUTTON_MISSING`, or response-timeout errors. A fake adapter test cannot prove that the current live page still matches.
 
-## Supported in v0.1
+## Supported contract
 
 - one ChatGPT conversation per run
 - text controller observations and commands
@@ -40,7 +40,7 @@ The v0.1 adapter relies on accessible textbox/button roles, attachment chips, an
 - process status with resolved runner, PID, phase, last progress, and safely observed model/provider
 - injected fake browser/runner for offline tests
 
-## Not supported in v0.1
+## Not supported
 
 - model switching other than CueLine selecting `Pro`
 - images, screenshots as controller input, audio, or binary payloads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A ChatGPT web conversation directs; CueLine validates each command and hands durable advice or explicitly claimed work to the current Codex.",
   "keywords": [
     "chatgpt",
@@ -66,10 +66,20 @@
     "test:unit": "npm run build && node --test dist/test/unit/*.test.js",
     "test:integration": "npm run build && node --test dist/test/integration/*.test.js",
     "smoke:fake": "npm run build && node --test dist/test/smoke/fake-smoke.test.js",
-    "validate:plugin": "node scripts/validate-plugin.mjs"
+    "validate:node-support": "node scripts/validate-node-support.mjs --json",
+    "validate:cli-contracts": "npm run build && node scripts/validate-cli-contracts.mjs",
+    "validate:plugin": "node scripts/validate-plugin.mjs",
+    "validate:docs": "node scripts/validate-doc-versions.mjs",
+    "test:docs": "node --test test/release/doc-version-guard.test.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "test:release-check": "node --test test/release/release-check.test.mjs",
+    "artifact:build": "node scripts/artifact-integrity.mjs build",
+    "artifact:verify": "node scripts/artifact-integrity.mjs verify",
+    "test:artifact": "node --test test/release/artifact-integrity.test.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
+    "ajv": "^8.20.0",
     "typescript": "^7.0.2"
   }
 }

package/schemas/cli-doctor.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-doctor.schema.json",
+  "title": "CueLine doctor machine output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "version", "status", "node", "config", "home", "caller", "process", "findings"],
+  "properties": {
+    "schema": { "const": "cueline-doctor/1" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "status": { "enum": ["ok", "degraded"] },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "ok", "requirement"],
+      "properties": {
+        "version": { "type": "string", "minLength": 1 },
+        "ok": { "type": "boolean" },
+        "requirement": { "const": ">=22" }
+      }
+    },
+    "config": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "valid", "errorCode"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "valid": { "const": false },
+            "errorCode": { "const": "ROUTING_CONFIG_INVALID" }
+          }
+        }
+      ]
+    },
+    "home": { "type": "string", "minLength": 1 },
+    "caller": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ready", "enabledLanes"],
+      "properties": {
+        "ready": { "type": "boolean" },
+        "enabledLanes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "process": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["availableLanes"],
+      "properties": {
+        "availableLanes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "surface", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "surface": { "enum": ["node", "config", "caller"] },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}