modelrig 0.1.0 → 0.3.0

package/dist/init/finder.js

@@ -15,10 +15,53 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SKIP_DIRS = void 0;
+exports.compileScope = compileScope;
+exports.matchesScope = matchesScope;
 exports.readObjectLiteral = readObjectLiteral;
 exports.findCallSitesInText = findCallSitesInText;
 exports.scanRepoForCallSites = scanRepoForCallSites;
 const signatures_1 = require("./signatures");
+/** Compile one scope pattern into a matcher over repo-relative POSIX paths.
+ * Bare paths (no glob metachar) match the file itself or anything beneath it,
+ * so `--scope src/pipeline` onboards one pipeline directory without ceremony. */
+function compileScope(pattern) {
+    const trimmed = pattern.replace(/\/+$/, "");
+    if (!/[*?[\]]/.test(trimmed)) {
+        return (relPath) => relPath === trimmed || relPath.startsWith(`${trimmed}/`);
+    }
+    // Glob → RegExp. `**` spans path segments; a lone `*` stops at one. Every
+    // other regex metacharacter is escaped so a literal `.` stays literal.
+    let re = "";
+    for (let i = 0; i < trimmed.length; i += 1) {
+        const ch = trimmed[i];
+        if (ch === "*") {
+            if (trimmed[i + 1] === "*") {
+                re += ".*";
+                i += 1;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            re += "[^/]";
+        }
+        else if ("\\^$.|+()[]{}".includes(ch)) {
+            re += `\\${ch}`;
+        }
+        else {
+            re += ch;
+        }
+    }
+    const compiled = new RegExp(`^${re}$`);
+    return (relPath) => compiled.test(relPath);
+}
+/** True when `relPath` matches ANY scope (or no scope is set). */
+function matchesScope(relPath, scope) {
+    if (scope === undefined || scope.length === 0)
+        return true;
+    return scope.some((pattern) => compileScope(pattern)(relPath));
+}
 exports.DEFAULT_SKIP_DIRS = [
     "node_modules",
     "dist",
@@ -278,6 +321,9 @@ function scanRepoForCallSites(root, fs, path, options = {}) {
             const isTest = /\.(test|spec)\.[jt]sx?$/.test(entry.name) || full.includes("__tests__") || full.includes("__mocks__");
             if (isTest && options.includeTests !== true)
                 continue;
+            // F-4: a file outside every --scope is never read (not counted scanned).
+            if (!matchesScope(path.relative(root, full), options.scope))
+                continue;
             try {
                 if (fs.statSync(full).size > maxBytes) {
                     skipped.push(path.relative(root, full));

package/dist/init/init-cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `modelrig init` command runner — lives here (not cli.ts) for the LOC cap
+ * (P1), beside the scaffold it drives (same split as observe-cli.ts and
+ * verify/cli-run.ts). Scans a repo for provider call sites and drafts a route
+ * bundle per site plus a MIGRATION.md map. It writes ONLY under
+ * <routes-dir>/drafts/; the target's source is never edited.
+ */
+import type { ObserveFlags } from "./observe-cli";
+export declare function cmdInit(flags: ObserveFlags): number;
+//# sourceMappingURL=init-cli.d.ts.map

package/dist/init/init-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-cli.d.ts","sourceRoot":"","sources":["../../src/init/init-cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAwFnD"}

package/dist/init/init-cli.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * `modelrig init` command runner — lives here (not cli.ts) for the LOC cap
+ * (P1), beside the scaffold it drives (same split as observe-cli.ts and
+ * verify/cli-run.ts). Scans a repo for provider call sites and drafts a route
+ * bundle per site plus a MIGRATION.md map. It writes ONLY under
+ * <routes-dir>/drafts/; the target's source is never edited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdInit = cmdInit;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+const rows_1 = require("../registry/rows");
+const observe_cli_1 = require("./observe-cli");
+const run_1 = require("./run");
+function cmdInit(flags) {
+    // `init --observe` is the observe-first (T0/T1) alias for `modelrig observe`.
+    if (flags.bare.has("observe"))
+        return (0, observe_cli_1.cmdObserve)(flags);
+    const root = (0, node_path_1.resolve)(flags.positional[0] ?? ".");
+    const config = (0, config_1.loadConfigFromEnv)();
+    const draftsDir = flags.named.get("out") ?? (0, node_path_1.join)(config.routesDir, "drafts");
+    const scope = (0, observe_cli_1.scopeFrom)(flags);
+    // Registry rows seed the challenger candidates. A missing/unbuilt registry
+    // is not fatal — drafts then carry the incumbent alone, and say so.
+    let registryRows = [];
+    try {
+        registryRows = (0, rows_1.loadRegistryRows)(config.registryPath);
+    }
+    catch {
+        registryRows = [];
+    }
+    const result = (0, run_1.runInit)({
+        root,
+        draftsDir,
+        fs: { readdirSync: node_fs_1.readdirSync, readFileSync: node_fs_1.readFileSync, statSync: node_fs_1.statSync, existsSync: node_fs_1.existsSync, mkdirSync: node_fs_1.mkdirSync, writeFileSync: node_fs_1.writeFileSync },
+        path: { join: node_path_1.join, relative: node_path_1.relative, dirname: node_path_1.dirname, basename: node_path_1.basename },
+    }, {
+        registryRows,
+        ...(flags.bare.has("dry-run") ? { dryRun: true } : {}),
+        ...(flags.bare.has("include-tests") ? { includeTests: true } : {}),
+        ...(scope !== undefined ? { scope } : {}),
+    });
+    if (flags.bare.has("json")) {
+        console.log(JSON.stringify({
+            sitesFound: result.sitesFound,
+            filesScanned: result.filesScanned,
+            filesSkipped: result.filesSkipped,
+            routes: result.drafts.map((d) => ({
+                route: d.route,
+                file: d.site.file,
+                line: d.site.line,
+                provider: d.site.provider,
+                model: d.site.model,
+                notes: d.site.notes,
+            })),
+            written: result.written,
+            skipped: result.skipped,
+        }, null, 2));
+        return 0;
+    }
+    console.log(`modelrig init — scanned ${result.filesScanned} file(s) under ${root}` +
+        (scope !== undefined ? ` (scoped to ${scope.join(", ")})` : "") +
+        `\nfound ${result.sitesFound} provider call site(s)`);
+    if (result.sitesFound === 0) {
+        console.log("\nNothing to draft. If you know there are model calls here, they may sit behind a helper\n" +
+            "that hides the SDK — point init at the file that actually calls the provider.");
+        return 0;
+    }
+    for (const draft of result.drafts) {
+        console.log(`  ${draft.site.file}:${draft.site.line} (${draft.site.provider}` +
+            `${draft.site.model !== null ? ` ${draft.site.model}` : ""}) → ${draft.route}`);
+    }
+    if (result.filesSkipped.length > 0) {
+        console.log(`\n${result.filesSkipped.length} file(s) skipped (too large or unreadable).`);
+    }
+    if (flags.bare.has("dry-run")) {
+        console.log("\n--dry-run: nothing written.");
+        return 0;
+    }
+    console.log(`\nwrote ${result.written.length} file(s) to ${draftsDir}` +
+        (result.skipped.length > 0 ? ` (${result.skipped.length} left alone — already there)` : "") +
+        `\nread ${(0, node_path_1.join)(draftsDir, "MIGRATION.md")} next. Your source was not touched.`);
+    return 0;
+}

package/dist/init/observe-cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `modelrig observe` command runner — lives here (not cli.ts) for the LOC cap
+ * (P1), beside the scaffold it drives (same split as verify/cli-run.ts and
+ * bakeoff/report.ts). Closes onboarding-test run-1's headline gap (F-1: the
+ * only observe on-ramp was a hand-wired SDK seam with no CLI). Like `init`, it
+ * NEVER edits the target's source — it writes only under its out dir.
+ */
+/** Structural view of the CLI's parsed flags — declared here so this module
+ * never imports cli.ts (which imports us), keeping the dependency one-way. */
+export interface ObserveFlags {
+    readonly positional: readonly string[];
+    readonly named: ReadonlyMap<string, string>;
+    readonly bare: ReadonlySet<string>;
+}
+/** `--scope a,b` → the finder's scope narrowing (F-4). Comma-separated globs
+ * or path prefixes; absent = scan everything. Shared with `modelrig init`. */
+export declare function scopeFrom(flags: ObserveFlags): readonly string[] | undefined;
+export declare function cmdObserve(flags: ObserveFlags): number;
+//# sourceMappingURL=observe-cli.d.ts.map

package/dist/init/observe-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-cli.d.ts","sourceRoot":"","sources":["../../src/init/observe-cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;8EAC8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;8EAC8E;AAC9E,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAK5E;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAgEtD"}

package/dist/init/observe-cli.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * `modelrig observe` command runner — lives here (not cli.ts) for the LOC cap
+ * (P1), beside the scaffold it drives (same split as verify/cli-run.ts and
+ * bakeoff/report.ts). Closes onboarding-test run-1's headline gap (F-1: the
+ * only observe on-ramp was a hand-wired SDK seam with no CLI). Like `init`, it
+ * NEVER edits the target's source — it writes only under its out dir.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopeFrom = scopeFrom;
+exports.cmdObserve = cmdObserve;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+const observe_1 = require("./observe");
+/** `--scope a,b` → the finder's scope narrowing (F-4). Comma-separated globs
+ * or path prefixes; absent = scan everything. Shared with `modelrig init`. */
+function scopeFrom(flags) {
+    const raw = flags.named.get("scope");
+    if (raw === undefined)
+        return undefined;
+    const scope = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+    return scope.length > 0 ? scope : undefined;
+}
+function cmdObserve(flags) {
+    const root = (0, node_path_1.resolve)(flags.positional[0] ?? ".");
+    const config = (0, config_1.loadConfigFromEnv)();
+    // Sibling of the routes dir: <repo>/modelrig/observe by default.
+    const outDir = flags.named.get("out") ?? (0, node_path_1.join)((0, node_path_1.dirname)(config.routesDir), "observe");
+    const scope = scopeFrom(flags);
+    const result = (0, observe_1.runObserve)({
+        root,
+        outDir,
+        fs: { readdirSync: node_fs_1.readdirSync, readFileSync: node_fs_1.readFileSync, statSync: node_fs_1.statSync, existsSync: node_fs_1.existsSync, mkdirSync: node_fs_1.mkdirSync, writeFileSync: node_fs_1.writeFileSync },
+        path: { join: node_path_1.join, relative: node_path_1.relative, dirname: node_path_1.dirname, basename: node_path_1.basename },
+    }, {
+        ...(flags.bare.has("dry-run") ? { dryRun: true } : {}),
+        ...(flags.bare.has("include-tests") ? { includeTests: true } : {}),
+        ...(scope !== undefined ? { scope } : {}),
+    });
+    if (flags.bare.has("json")) {
+        console.log(JSON.stringify({
+            sitesFound: result.sitesFound,
+            filesScanned: result.filesScanned,
+            filesSkipped: result.filesSkipped,
+            steps: result.plans.map((p) => ({
+                stepKey: p.stepKey,
+                file: p.site.file,
+                line: p.site.line,
+                provider: p.site.provider,
+                model: p.site.model,
+            })),
+            written: result.written,
+            skipped: result.skipped,
+        }, null, 2));
+        return 0;
+    }
+    console.log(`modelrig observe — scanned ${result.filesScanned} file(s) under ${root}` +
+        (scope !== undefined ? ` (scoped to ${scope.join(", ")})` : "") +
+        `\nfound ${result.sitesFound} model call site(s) → ${result.sitesFound} proposed step(s)`);
+    for (const plan of result.plans) {
+        console.log(`  ${plan.site.file}:${plan.site.line} → step "${plan.stepKey}"`);
+    }
+    if (flags.bare.has("dry-run")) {
+        console.log("\n--dry-run: nothing written.");
+        return 0;
+    }
+    console.log(`\nwrote ${result.written.length} file(s) to ${outDir}` +
+        (result.skipped.length > 0 ? ` (${result.skipped.length} left alone — already there)` : "") +
+        `\nread ${(0, node_path_1.join)(outDir, "OBSERVE.md")} next — apply the wiring diffs one step at a time.` +
+        "\nObserve changes no behaviour; with MODELRIG_ARTIFACTS off your pipeline is byte-for-byte the same.");
+    return 0;
+}

package/dist/init/observe.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `modelrig observe` — the observe-first (T0/T1) scaffold.
+ *
+ * Onboarding-test run-1's headline finding (F-1): the ONLY documented observe
+ * on-ramp (`instrumentation.md`) is a hand-wired SDK seam with NO CLI. Every
+ * customer-facing surface points a migrating customer at `modelrig init`, which
+ * is route extraction (T2) — so "just show me my runs first" had no CLI
+ * affordance at all. This command closes that gap.
+ *
+ * It does for OBSERVE what `init` does for MIGRATE, and obeys the same hard
+ * rule: it NEVER edits the target's source. It writes exactly two things under
+ * `modelrig/observe/` — a self-contained `record-step` seam (generated fresh,
+ * per the doc's "write your own; do not resurrect a deleted one" rule) and an
+ * `OBSERVE.md` plan whose per-call-site wiring is emitted as a `diff` for the
+ * agent (or human) to apply with judgment, one step at a time.
+ *
+ * Observe is deliberately NOT migration: it drafts no routes, reroutes no
+ * model calls, and changes no behaviour. With `MODELRIG_ARTIFACTS` off the
+ * pipeline is byte-for-byte identical (instrumentation.md).
+ */
+import type { CallSite, FileSystemLike } from "./finder";
+import type { FinderOptions } from "./finder";
+/** One instrumented step the scaffold proposes: a detected model call site
+ * becomes a step boundary whose work products (prompt, raw, parsed) are saved. */
+export interface ObservePlan {
+    readonly site: CallSite;
+    /** Stable, human-legible step key used in `recordStep(...)` and the console. */
+    readonly stepKey: string;
+    /** The `recordStep(...)` line proposed at this site. */
+    readonly snippet: string;
+}
+export interface ObserveResult {
+    readonly plans: readonly ObservePlan[];
+    readonly sitesFound: number;
+    readonly filesScanned: number;
+    readonly filesSkipped: readonly string[];
+    /** Where the generated seam helper lives (repo-relative). */
+    readonly seamPath: string;
+    /** The generated, self-contained seam helper source. */
+    readonly seamContent: string;
+    /** The OBSERVE.md plan (wiring diffs + the human key-mint handoff). */
+    readonly scaffoldMarkdown: string;
+    readonly written: readonly string[];
+    readonly skipped: readonly string[];
+}
+export interface ObserveOptions extends FinderOptions {
+    /** Plan without writing (`--dry-run`). */
+    readonly dryRun?: boolean;
+}
+export interface ObserveDeps {
+    readonly root: string;
+    /** Directory the scaffold writes into (repo-relative), e.g. modelrig/observe. */
+    readonly outDir: string;
+    readonly fs: FileSystemLike & {
+        existsSync: (p: string) => boolean;
+        mkdirSync: (p: string, o: {
+            recursive: boolean;
+        }) => void;
+        writeFileSync: (p: string, c: string, e: "utf8") => void;
+    };
+    readonly path: {
+        join: (...parts: string[]) => string;
+        relative: (from: string, to: string) => string;
+        dirname: (p: string) => string;
+        basename: (p: string, ext?: string) => string;
+    };
+}
+/** A stable step key from a call site: `<dir>_<file>_<line>`, deduped so two
+ * sites never collide. Deterministic, so a second run proposes the same keys. */
+export declare function stepKeyFor(site: CallSite, used: Set<string>): string;
+/** The generated seam. Self-contained and fresh (never resurrected from git
+ * history — that is the point of onboarding-test run-2). Mirrors the reference
+ * `recordStep` in instrumentation.md, plus a `withRun` boundary wrapper. */
+export declare function seamContent(): string;
+export declare function buildObserveMarkdown(plans: readonly ObservePlan[], seamPath: string, result: {
+    sitesFound: number;
+    filesScanned: number;
+    filesSkipped: readonly string[];
+}, path: ObserveDeps["path"]): string;
+export declare function runObserve(deps: ObserveDeps, options?: ObserveOptions): ObserveResult;
+//# sourceMappingURL=observe.d.ts.map

package/dist/init/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/init/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;kFACkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,cAAc,GAAG;QAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QACnC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,KAAK,IAAI,CAAC;QAC1D,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1D,CAAC;IACF,QAAQ,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;QACrC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/C,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;KAC/C,CAAC;CACH;AAKD;iFACiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAQpE;AAED;;4EAE4E;AAC5E,wBAAgB,WAAW,IAAI,MAAM,CA6DpC;AAoCD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EACrF,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,MAAM,CA+GR;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CA6DzF"}

package/dist/init/observe.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * `modelrig observe` — the observe-first (T0/T1) scaffold.
+ *
+ * Onboarding-test run-1's headline finding (F-1): the ONLY documented observe
+ * on-ramp (`instrumentation.md`) is a hand-wired SDK seam with NO CLI. Every
+ * customer-facing surface points a migrating customer at `modelrig init`, which
+ * is route extraction (T2) — so "just show me my runs first" had no CLI
+ * affordance at all. This command closes that gap.
+ *
+ * It does for OBSERVE what `init` does for MIGRATE, and obeys the same hard
+ * rule: it NEVER edits the target's source. It writes exactly two things under
+ * `modelrig/observe/` — a self-contained `record-step` seam (generated fresh,
+ * per the doc's "write your own; do not resurrect a deleted one" rule) and an
+ * `OBSERVE.md` plan whose per-call-site wiring is emitted as a `diff` for the
+ * agent (or human) to apply with judgment, one step at a time.
+ *
+ * Observe is deliberately NOT migration: it drafts no routes, reroutes no
+ * model calls, and changes no behaviour. With `MODELRIG_ARTIFACTS` off the
+ * pipeline is byte-for-byte identical (instrumentation.md).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepKeyFor = stepKeyFor;
+exports.seamContent = seamContent;
+exports.buildObserveMarkdown = buildObserveMarkdown;
+exports.runObserve = runObserve;
+const finder_1 = require("./finder");
+const normalize = (s) => s.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "").toLowerCase();
+/** A stable step key from a call site: `<dir>_<file>_<line>`, deduped so two
+ * sites never collide. Deterministic, so a second run proposes the same keys. */
+function stepKeyFor(site, used) {
+    const parts = site.file.split("/").filter((p) => p !== "" && p !== "." && p !== "src");
+    const fileStem = (parts[parts.length - 1] ?? "step").replace(/\.[jt]sx?$/, "");
+    const dir = parts.length > 1 ? parts[parts.length - 2] : "app";
+    let key = `${normalize(dir)}_${normalize(fileStem)}_${site.line}`;
+    while (used.has(key))
+        key = `${key}_x`;
+    used.add(key);
+    return key;
+}
+/** The generated seam. Self-contained and fresh (never resurrected from git
+ * history — that is the point of onboarding-test run-2). Mirrors the reference
+ * `recordStep` in instrumentation.md, plus a `withRun` boundary wrapper. */
+function seamContent() {
+    return `/**
+ * ModelRig observe seam — generated by \`modelrig observe\`.
+ *
+ * This is YOURS to keep and edit; it is generated fresh (not copied from any
+ * deleted seam) so it always matches the current SDK. It records each pipeline
+ * run as a run -> step -> artifact chain you click through in the console.
+ *
+ * Observe-only: no routes move, no model calls are rerouted. With
+ * MODELRIG_ARTIFACTS off (or no control plane configured) every call here is
+ * inert and your pipeline behaves byte-for-byte as before. Nothing here ever
+ * throws into your pipeline — a telemetry write that fails is logged and
+ * dropped (instrumentation.md, "Never throws into your pipeline").
+ *
+ * Docs: https://modelrig.dev/instrumentation.html
+ */
+
+import { createRig, loadConfigFromEnv, type Rig } from "modelrig";
+
+const rig: Rig = createRig(loadConfigFromEnv());
+
+/** Open a run context around a whole pipeline, close it on success/failure.
+ * \`episodeKey\` is a grouping key (a natural choice: your per-run attempt id),
+ * not a unique id. Pass \`environment\` (e.g. your NODE_ENV) to tag the run.
+ * Use \`rig.artifacts.run.scope(...)\` instead for concurrent runs in one
+ * process. */
+export async function withRun<T>(
+  opts: { pipeline: string; episodeKey: string; environment?: string },
+  body: () => Promise<T>,
+): Promise<T> {
+  const run = rig.artifacts.run.start({
+    pipeline: opts.pipeline,
+    episodeKey: opts.episodeKey,
+    ...(opts.environment !== undefined ? { environment: opts.environment } : {}),
+  });
+  try {
+    const out = await body();
+    run.end("succeeded");
+    return out;
+  } catch (err) {
+    run.end("failed");
+    throw err;
+  }
+}
+
+/** Save prompt + raw + parsed for one step, link lineage, flag conformance.
+ * A stage whose model call does NOT go through the rig still produces
+ * artifacts (with \`stepKey\` set and no step row) — correct and honest; the
+ * console renders "cost n/a" rather than inventing a number. */
+export function recordStep(
+  stepKey: string,
+  work: { prompt: string; rawText: string; json: unknown; conforms: boolean },
+): void {
+  const p = rig.artifacts.artifact.save(work.prompt, { name: \`\${stepKey}.prompt\`, type: "prompt", stepKey });
+  const raw = rig.artifacts.artifact.save(work.rawText, { name: \`\${stepKey}.raw\`, type: "raw_response", stepKey });
+  const parsed = rig.artifacts.artifact.save(work.json, { name: \`\${stepKey}.output\`, type: "step_output", task: stepKey, stepKey });
+  if (p && parsed) rig.artifacts.artifact.link(parsed, p, "derived_from");
+  if (raw && parsed) rig.artifacts.artifact.link(parsed, raw, "derived_from");
+  if (parsed) rig.artifacts.artifact.evaluate(parsed, { evaluator: "schema-check", kind: "deterministic", passed: work.conforms });
+}
+`;
+}
+/** The import specifier a source file uses to reach the seam. Best-effort
+ * relative path; a coding agent adjusts it to the project's alias if needed. */
+function importSpecifier(fromFile, seamPath, path) {
+    const noExt = seamPath.replace(/\.[jt]sx?$/, "");
+    const rel = path.relative(path.dirname(fromFile), noExt);
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function recordStepSnippet(stepKey) {
+    return (`recordStep(${JSON.stringify(stepKey)}, {\n` +
+        `  prompt,          // the assembled prompt string\n` +
+        `  rawText,         // the model's raw text, pre-parse\n` +
+        `  json: parsed,    // your parsed/validated output\n` +
+        `  conforms,        // did it satisfy your schema?\n` +
+        `});`);
+}
+/** The run boundary is most likely the shallowest detected file (the entry
+ * that drives the pipeline). A heuristic, flagged as such — never asserted. */
+function runBoundaryFile(plans) {
+    let best = null;
+    let bestDepth = Number.POSITIVE_INFINITY;
+    for (const plan of plans) {
+        const depth = plan.site.file.split("/").length;
+        if (depth < bestDepth) {
+            bestDepth = depth;
+            best = plan.site.file;
+        }
+    }
+    return best;
+}
+function buildObserveMarkdown(plans, seamPath, result, path) {
+    const lines = [
+        "# ModelRig observe — wire up run/step/artifact telemetry",
+        "",
+        "**Nothing in your source has changed.** `modelrig observe` generated one seam helper",
+        `(\`${seamPath}\`) and this plan. Observe is **not migration**: no routes were drafted, no`,
+        "model calls rerouted. Applying the wiring below records each run as a run → step →",
+        "artifact chain you click through in the console — and with the flag off, your pipeline",
+        "behaves **byte-for-byte** as before.",
+        "",
+        `Detected **${result.sitesFound} model call site(s)** across ${result.filesScanned} scanned file(s);`,
+        "each is proposed as one instrumented **step**. Apply the diffs one step at a time — a step",
+        "you do not understand yet is a step you can leave for later.",
+        "",
+        "## 1. Turn the namespace on",
+        "",
+        "```bash",
+        "export MODELRIG_ARTIFACTS=1                 # enable the artifact namespace",
+        "# export MODELRIG_ARTIFACT_STEPS=step_a,step_b   # optional: instrument a subset",
+        "```",
+        "",
+        "> **Human handoff (one step, once).** Seeing these runs **in the console** needs a free",
+        "> account + an API key minted at <https://app.modelrig.ai> (`/keys`) — a console login a",
+        "> coding agent cannot perform. Set `MODELRIG_API_KEY=<key>` once a human provides it; the",
+        "> default ingest host (`https://api.modelrig.ai`) needs no other config. Everything else",
+        "> below an agent can do now — plan the handoff, do not stall on it.",
+        "",
+    ];
+    if (plans.length === 0) {
+        lines.push("## No model call sites found", "", "Nothing matched in the scanned files. If you know there are model calls here, they may sit", "behind a helper that hides the SDK — point `modelrig observe` at the file that actually", "calls the provider, or wire `withRun` / `recordStep` by hand from the seam helper above.", "");
+        return `${lines.join("\n")}\n`;
+    }
+    const boundary = runBoundaryFile(plans);
+    const seamNoExt = seamPath.replace(/\.[jt]sx?$/, "");
+    const boundaryImport = boundary === null ? seamNoExt : importSpecifier(boundary, seamPath, path);
+    lines.push("## 2. Open a run context around the pipeline", "", boundary === null
+        ? "Wrap your pipeline's entry point in `withRun(...)` from the seam helper:"
+        : `Your pipeline entry looks like \`${boundary}\` (the shallowest detected call site — a` +
+            " heuristic; move this if your real entry is elsewhere). Wrap it in `withRun(...)`:", "", "```diff", `+ import { withRun } from "${boundaryImport}";`, "", "- export async function runPipeline(input) {", "-   /* ... your steps ... */", "- }", "+ export async function runPipeline(input) {", "+   return withRun(", '+     { pipeline: "my-pipeline", episodeKey: input.attemptId },', "+     async () => {", "+       /* ... your steps ... */", "+     },", "+   );", "+ }", "```", "", "## 3. Record each step's work products", "", "Each detected model call is one step. After the call parses its output, add a `recordStep`", "(the diffs below quote the call line so you can find it):", "");
+    // Group the per-site wiring diffs by file so each file gets one import line.
+    const byFile = new Map();
+    for (const plan of plans) {
+        const list = byFile.get(plan.site.file) ?? [];
+        list.push(plan);
+        byFile.set(plan.site.file, list);
+    }
+    for (const [file, filePlans] of byFile) {
+        lines.push(`### \`${file}\``, "", "```diff", `+ import { recordStep } from "${importSpecifier(file, seamPath, path)}";`, "");
+        for (const plan of filePlans) {
+            lines.push(`  // line ${plan.site.line}: ${plan.site.provider}` +
+                `${plan.site.model !== null ? ` ${plan.site.model}` : ""} call — save its work products`, ...plan.snippet.split("\n").map((l) => `+ ${l}`), "");
+        }
+        lines.push("```", "");
+    }
+    lines.push("## 4. See it", "", "Run your pipeline once, then open the console: **Runs** lists the run, `/runs/[id]` renders", "the semantic chain (artifacts grouped by step, with hashes and evaluation badges), and", "`/artifacts/[id]` shows one artifact's lineage. Un-routed steps show **cost n/a** — correct", "for observe-only; nothing routes through the rig yet.", "", "## When you are ready to migrate (later, optional)", "", "Observe answers *what is my pipeline doing?* When you want to *change what serves a step*,", "that is route extraction (T2) — a separate, behaviour-affecting move behind its own review:", "`modelrig init --scope <this pipeline>`. Observe first is the safer order.", "");
+    return `${lines.join("\n")}\n`;
+}
+function runObserve(deps, options = {}) {
+    const scan = (0, finder_1.scanRepoForCallSites)(deps.root, deps.fs, deps.path, options);
+    const used = new Set();
+    const plans = scan.sites.map((site) => {
+        const stepKey = stepKeyFor(site, used);
+        return { site, stepKey, snippet: recordStepSnippet(stepKey) };
+    });
+    const seamPath = deps.path.join(deps.outDir, "record-step.ts");
+    // Import specifiers and prose are computed root-relative — call sites come
+    // back relative to `root`, so the seam must be expressed the same way for
+    // `path.relative` to yield a sane `../../modelrig/observe/...` specifier.
+    const seamRel = deps.path.relative(deps.root, seamPath);
+    const content = seamContent();
+    const scaffoldMarkdown = buildObserveMarkdown(plans, seamRel, { sitesFound: scan.sites.length, filesScanned: scan.filesScanned, filesSkipped: scan.filesSkipped }, deps.path);
+    if (options.dryRun === true) {
+        return {
+            plans,
+            sitesFound: scan.sites.length,
+            filesScanned: scan.filesScanned,
+            filesSkipped: scan.filesSkipped,
+            seamPath,
+            seamContent: content,
+            scaffoldMarkdown,
+            written: [],
+            skipped: [],
+        };
+    }
+    deps.fs.mkdirSync(deps.outDir, { recursive: true });
+    const written = [];
+    const skipped = [];
+    // The seam is the customer's to edit — never clobber an existing one.
+    if (deps.fs.existsSync(seamPath)) {
+        skipped.push(seamPath);
+    }
+    else {
+        deps.fs.writeFileSync(seamPath, content, "utf8");
+        written.push(seamPath);
+    }
+    // OBSERVE.md is a regenerated report, not a hand-edited draft — always rewrite.
+    const planPath = deps.path.join(deps.outDir, "OBSERVE.md");
+    deps.fs.writeFileSync(planPath, scaffoldMarkdown, "utf8");
+    written.push(planPath);
+    return {
+        plans,
+        sitesFound: scan.sites.length,
+        filesScanned: scan.filesScanned,
+        filesSkipped: scan.filesSkipped,
+        seamPath,
+        seamContent: content,
+        scaffoldMarkdown,
+        written,
+        skipped,
+    };
+}