@interf/compiler 0.9.5 → 0.13.0

package/dist/cli/commands/compile.js

@@ -1,367 +1,82 @@
+/**
+ * `interf compile <prep-id>` — start a compile run for a preparation.
+ *
+ *   interf compile bristol
+ *   interf compile bristol --quiet      # only the locator on stdout (scripting)
+ *   interf compile bristol --watch      # stream events
+ *
+ * Requires an active connection. Hits POST /v1/preparations/<id>/compile-runs.
+ */
 import chalk from "chalk";
-import * as p from "@clack/prompts";
-import { detectInterf, readInterfConfig, resolveSourceControlPath, } from "../../packages/project-model/interf.js";
-import { loadCompiledPreparationConfig, sourcePreparationConfigFromInterfConfig, resolvePreparationCompileMaxAttempts, resolvePreparationCompileMaxLoops, } from "../../packages/project-model/source-config.js";
-import { portableContextPath, } from "../../packages/project-model/project-paths.js";
-import { choosePreparationConfig, } from "./preparation-picker.js";
-import { resolveConfiguredPreparationSelection } from "./preparation-selection.js";
-import { promptCompileLoopSelection, } from "./source-config-wizard.js";
-import { submitCompileRunToLocalService, waitForLocalCompileRun, } from "../../packages/local-service/index.js";
-import { resolveCommandControlPath } from "./control-path.js";
-import { resolveMethodId } from "../../packages/methods/method-resolution.js";
-export const compileCommand = {
-    command: "compile",
-    describe: "Prepare files and write Portable Context agents can use",
-    builder: (yargs) => yargs.option("preparation", {
-        type: "string",
-        describe: "Preparation id to compile when this Source Folder has more than one Preparation",
-    }).option("max-attempts", {
-        type: "number",
-        describe: "Retry the prepare run and run saved readiness checks with the same Method until the Preparation is ready or reaches this total attempt limit",
-    }).option("max-loops", {
-        type: "number",
-        describe: "After retries fail, let Interf edit the Method and run saved readiness checks on new Method variations for this Preparation up to this loop limit",
-    }).option("keep-stage-shells", {
-        type: "boolean",
-        default: false,
-        describe: "Keep every executed stage shell under .interf/runtime/execution-shells for review instead of pruning successful shells",
-    }),
-    handler: async (argv) => {
-        await runCompileCommand(argv);
-    },
-};
-const defaultCompileCommandDeps = {
-    choosePreparationConfig,
-    confirm: p.confirm,
-    detectInterf,
-    resolveInteractiveCompileLoopOverrides,
-};
-function readHintedSourcePath(argv) {
-    return typeof argv.sourcePath === "string" && argv.sourcePath.trim().length > 0
-        ? argv.sourcePath.trim()
-        : null;
-}
-function readRequestedPreparationName(argv) {
-    const raw = argv.preparation;
-    return typeof raw === "string" && raw.trim().length > 0
-        ? raw.trim()
-        : null;
-}
-function shouldSkipCompileConfirm(argv) {
-    return argv.skipConfirm === true;
-}
-function shouldSkipPreparationBanner(argv) {
-    return argv.skipPreparationBanner === true;
-}
-function compileRunTests(options) {
-    const checks = options.compiledConfig?.checks ?? [];
-    if (checks.length === 0)
-        return false;
-    const configuredMaxAttempts = resolvePreparationCompileMaxAttempts(options.compiledConfig ?? { max_attempts: undefined }, options.maxAttemptsOverride);
-    const maxLoops = resolvePreparationCompileMaxLoops(options.compiledConfig ?? { max_loops: undefined }, options.maxLoopsOverride);
-    const maxAttempts = configuredMaxAttempts ?? (maxLoops != null ? 1 : null);
-    return maxAttempts != null;
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
 }
-export async function runCompileCommand(argv = {}, deps = {}) {
-    const helpers = {
-        ...defaultCompileCommandDeps,
-        ...deps,
-    };
-    let compiledPath = null;
-    const hintedSourcePath = readHintedSourcePath(argv);
-    const detected = hintedSourcePath ? null : helpers.detectInterf(process.cwd());
-    let sourcePath = hintedSourcePath ?? resolveCommandControlPath();
-    let compiledConfig = null;
-    const requestedPreparationName = readRequestedPreparationName(argv);
-    const hintedPreparationConfig = (argv.preparationConfig ?? null);
-    const skipConfirm = shouldSkipCompileConfirm(argv);
-    const skipPreparationBanner = shouldSkipPreparationBanner(argv);
-    if (detected) {
-        compiledPath = detected.path;
-        sourcePath = resolveSourceControlPath(detected.path);
-        compiledConfig = loadCompiledPreparationConfig(detected.path)
-            ?? sourcePreparationConfigFromInterfConfig(detected.config);
-        if (!skipConfirm && process.stdin.isTTY && process.stdout.isTTY) {
-            const confirmed = await helpers.confirm({
-                message: `Prepare files for Preparation "${detected.config.name}" now?`,
-                initialValue: true,
-            });
-            if (p.isCancel(confirmed) || !confirmed)
-                return null;
+async function callJson(url, token, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    if (init.body && !headers.has("content-type"))
+        headers.set("content-type", "application/json");
+    const response = await fetch(url, { ...init, headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw.length > 0) {
+        try {
+            body = JSON.parse(raw);
         }
-    }
-    else {
-        const selectedCompiled = requestedPreparationName || hintedPreparationConfig
-            ? resolveConfiguredPreparationSelection({
-                sourcePath,
-                requestedPreparationName,
-                hintedPreparationConfig,
-            })
-            : await helpers.choosePreparationConfig({
-                sourcePath,
-                selectMessage: "Which saved Preparation do you want to compile?",
-            });
-        if (selectedCompiled === undefined)
-            return null;
-        if (!selectedCompiled) {
-            process.exitCode = 1;
-            if (requestedPreparationName) {
-                console.log(chalk.red(`  Preparation "${requestedPreparationName}" is not saved in this Source Folder.`));
-                console.log(chalk.dim("  Run `interf list` to see the saved Preparations."));
-            }
-            else {
-                console.log(chalk.red("  No saved Preparations are configured for this Source Folder yet."));
-                console.log(chalk.dim("  Start with `interf` or `interf init` to set up this folder."));
-            }
-            return null;
+        catch {
+            body = null;
         }
-        if (!skipConfirm && process.stdin.isTTY && process.stdout.isTTY) {
-            const confirmed = await helpers.confirm({
-                message: `Prepare files for Preparation "${selectedCompiled.name}" now?`,
-                initialValue: true,
-            });
-            if (p.isCancel(confirmed) || !confirmed)
-                return null;
+    }
+    return { status: response.status, body, raw };
+}
+export const compileCommand = {
+    command: "compile <prep-id>",
+    describe: "Start a compile run for a preparation",
+    builder: (yargs) => yargs
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("watch", { type: "boolean", default: false, describe: "Stream run events" })
+        .option("quiet", { type: "boolean", default: false, describe: "Print only the portable-context locator on success" })
+        .option("idempotency-key", { type: "string", describe: "Client-supplied dedupe key" })
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" }),
+    handler: async (args) => {
+        const { url, token } = resolveConnection(args);
+        const headers = {};
+        if (args.idempotencyKey)
+            headers["x-interf-idempotency-key"] = args.idempotencyKey;
+        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/compile-runs`, token, { method: "POST", headers, body: JSON.stringify({}) });
+        if (status !== 201 && status !== 200 && status !== 202) {
+            console.error(chalk.red(`Failed to start compile run for ${args.prepId} (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
         }
-        compiledConfig = selectedCompiled;
-        compiledPath = portableContextPath(sourcePath, selectedCompiled.name);
-        if (!skipPreparationBanner) {
-            console.log(chalk.dim(`  Preparation: ${selectedCompiled.name}`));
+        const run = body?.run;
+        const runId = run?.run_id ?? "(unknown run)";
+        const locator = run?.portable_context_path ?? "(no locator)";
+        if (args.quiet) {
+            console.log(locator);
+            return;
         }
-    }
-    let maxAttemptsOverride = null;
-    let maxLoopsOverride = null;
-    try {
-        maxAttemptsOverride = readCompileMaxAttemptsOverride(argv);
-        maxLoopsOverride = readCompileMaxLoopsOverride(argv);
-    }
-    catch (error) {
-        process.exitCode = 1;
-        console.log(chalk.red(error instanceof Error ? error.message : String(error)));
-        return null;
-    }
-    const interactiveOverrides = await helpers.resolveInteractiveCompileLoopOverrides({
-        compiledPath,
-        compiledConfig,
-        maxAttemptsOverride,
-        maxLoopsOverride,
-    });
-    if (!interactiveOverrides)
-        return null;
-    compiledConfig = interactiveOverrides.compiledConfig;
-    maxAttemptsOverride = interactiveOverrides.maxAttemptsOverride;
-    maxLoopsOverride = interactiveOverrides.maxLoopsOverride;
-    const testedDuringCompile = compileRunTests({
-        compiledConfig,
-        maxAttemptsOverride,
-        maxLoopsOverride,
-    });
-    if (compiledConfig) {
-        const submitted = await submitCompileRunToLocalService({
-            projectPath: sourcePath,
-            request: {
-                preparation: compiledConfig.name,
-                ...(compiledConfig.method ? { method: compiledConfig.method } : {}),
-                ...(maxAttemptsOverride != null ? { max_attempts: maxAttemptsOverride } : {}),
-                ...(maxLoopsOverride != null ? { max_loops: maxLoopsOverride } : {}),
-                preserve_stage_shells: readStageShellRetentionMode(argv),
-            },
-        });
-        if (submitted) {
-            console.log(chalk.dim(`  Visible in Interf: ${submitted.serviceUrl}/`));
-            let lastStatus = "";
-            let lastStage = "";
-            const completed = await waitForLocalCompileRun({
-                serviceUrl: submitted.serviceUrl,
-                runId: submitted.resource.run.run_id,
-                onUpdate(resource) {
-                    const activeStage = resource.run.stages.find((stage) => stage.status === "running")
-                        ?? [...resource.run.stages].reverse().find((stage) => stage.status === "succeeded" || stage.status === "failed")
-                        ?? null;
-                    const statusKey = `${resource.run.status}:${activeStage?.stage_id ?? ""}:${activeStage?.status ?? ""}`;
-                    if (statusKey === `${lastStatus}:${lastStage}`)
-                        return;
-                    lastStatus = resource.run.status;
-                    lastStage = `${activeStage?.stage_id ?? ""}:${activeStage?.status ?? ""}`;
-                    if (activeStage) {
-                        console.log(chalk.dim(`  ${activeStage.stage_label ?? activeStage.stage_id}: ${activeStage.status}`));
-                    }
-                    else {
-                        console.log(chalk.dim(`  Prepare run: ${resource.run.status}`));
-                    }
-                },
-            });
-            if (completed.run.status !== "succeeded") {
-                process.exitCode = 1;
-                const failure = completed.run.stages.find((stage) => stage.status === "failed");
-                console.log(chalk.red(`  Prepare run ${completed.run.status}.`));
-                if (failure?.failure)
-                    console.log(chalk.red(`  ${failure.failure}`));
-                return null;
-            }
-            console.log(chalk.green("  Portable Context ready."));
-            return {
-                compiledPath: completed.run.portable_context_path,
-                testedDuringCompile,
-            };
+        console.log();
+        console.log(`  Run ${chalk.bold(runId)} ${chalk.dim(`(${run?.status ?? "started"})`)}`);
+        console.log(`  Portable context: ${locator}`);
+        if (run?.status === "succeeded" || run?.finished_at) {
+            const prepResp = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}`, token);
+            const readiness = prepResp.body?.readiness?.status;
+            if (readiness)
+                console.log(`  Readiness: ${readiness}`);
         }
-        process.exitCode = 1;
-        console.log(chalk.red("  Interf local service is not running for this Workspace."));
-        console.log(chalk.dim("  Start it with `interf web`, then rerun `interf compile` so the prepare run is visible in Interf."));
-        return null;
-    }
-    process.exitCode = 1;
-    console.log(chalk.red("  Interf could not resolve a saved Preparation for this prepare run."));
-    console.log(chalk.dim("  Run `interf list` to inspect saved Preparations, then rerun `interf compile --preparation <id>`."));
-    return null;
-}
-export async function resolveInteractiveCompileLoopOverrides(options) {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        return {
-            compiledConfig: options.compiledConfig,
-            maxAttemptsOverride: options.maxAttemptsOverride,
-            maxLoopsOverride: options.maxLoopsOverride,
-        };
-    }
-    if (options.maxAttemptsOverride != null || options.maxLoopsOverride != null) {
-        return {
-            compiledConfig: options.compiledConfig,
-            maxAttemptsOverride: options.maxAttemptsOverride,
-            maxLoopsOverride: options.maxLoopsOverride,
-        };
-    }
-    const currentConfig = readInterfConfig(options.compiledPath);
-    const checks = options.compiledConfig?.checks.length
-        ? options.compiledConfig.checks
-        : (currentConfig?.checks ?? []);
-    if (checks.length === 0) {
-        return {
-            compiledConfig: options.compiledConfig,
-            maxAttemptsOverride: options.maxAttemptsOverride,
-            maxLoopsOverride: options.maxLoopsOverride,
-        };
-    }
-    const savedCompiledConfig = options.compiledConfig
-        ?? (currentConfig
-            ? (loadCompiledPreparationConfig(options.compiledPath)
-                ?? sourcePreparationConfigFromInterfConfig(currentConfig))
-            : null);
-    if (!savedCompiledConfig) {
-        return {
-            compiledConfig: options.compiledConfig,
-            maxAttemptsOverride: options.maxAttemptsOverride,
-            maxLoopsOverride: options.maxLoopsOverride,
-        };
-    }
-    const hasSavedPolicy = typeof savedCompiledConfig.max_attempts === "number" ||
-        typeof savedCompiledConfig.max_loops === "number";
-    if (!hasSavedPolicy) {
-        const overrideSelection = await promptCompileLoopSelection({
-            hasChecks: true,
-            initialMaxAttempts: savedCompiledConfig.max_attempts,
-            initialMaxLoops: savedCompiledConfig.max_loops,
-            intro: [
-                `Method: ${resolveMethodId(savedCompiledConfig, resolveMethodId(currentConfig))}`,
-                "This selection applies to this prepare run only. It does not change the saved Preparation.",
-            ],
-            message: "How should this prepare run work?",
-        });
-        if (overrideSelection === null)
-            return null;
-        return {
-            compiledConfig: {
-                ...savedCompiledConfig,
-                max_attempts: undefined,
-                max_loops: undefined,
-            },
-            maxAttemptsOverride: overrideSelection.max_attempts ?? null,
-            maxLoopsOverride: overrideSelection.max_loops ?? null,
-        };
-    }
-    const savedMode = await p.select({
-        message: "Which prepare mode should this run use?",
-        options: [
-            {
-                value: "saved",
-                label: "Use saved prepare mode (Recommended)",
-                hint: `${savedCompiledConfig.max_loops ? "Self-improving" : savedCompiledConfig.max_attempts && savedCompiledConfig.max_attempts > 1 ? "Retry" : "Single attempt"} · ${formatCompileModeHint(savedCompiledConfig)}`,
-            },
-            {
-                value: "override",
-                label: "Change it for this run only",
-                hint: "Keep the saved Preparation unchanged",
-            },
-        ],
-    });
-    if (p.isCancel(savedMode))
-        return null;
-    if (savedMode === "saved") {
-        return {
-            compiledConfig: savedCompiledConfig,
-            maxAttemptsOverride: null,
-            maxLoopsOverride: null,
-        };
-    }
-    const selection = await promptCompileLoopSelection({
-        hasChecks: true,
-        initialMaxAttempts: savedCompiledConfig.max_attempts,
-        initialMaxLoops: savedCompiledConfig.max_loops,
-        intro: [
-            `Method: ${resolveMethodId(savedCompiledConfig, resolveMethodId(currentConfig))}`,
-            "This applies to this prepare run only. It does not change the saved Preparation.",
-        ],
-        message: "Override the prepare mode for this run",
-    });
-    if (selection === null)
-        return null;
-    return {
-        ...savedCompiledConfig,
-        compiledConfig: {
-            ...savedCompiledConfig,
-            max_attempts: undefined,
-            max_loops: undefined,
-        },
-        maxAttemptsOverride: selection.max_attempts ?? null,
-        maxLoopsOverride: selection.max_loops ?? null,
-    };
-}
-function formatCompileModeHint(compiledConfig) {
-    if (typeof compiledConfig.max_loops === "number" && compiledConfig.max_loops > 0) {
-        const attempts = compiledConfig.max_attempts ?? 1;
-        return `${attempts} attempt${attempts === 1 ? "" : "s"} per variation, ${compiledConfig.max_loops} loop${compiledConfig.max_loops === 1 ? "" : "s"}`;
-    }
-    if (typeof compiledConfig.max_attempts === "number" && compiledConfig.max_attempts > 1) {
-        return `${compiledConfig.max_attempts} attempts`;
-    }
-    return "1 attempt";
-}
-function readCompileMaxAttemptsOverride(argv) {
-    const raw = argv["max-attempts"] ??
-        argv.maxAttempts ??
-        argv["max-retries"] ??
-        argv.maxRetries;
-    if (raw == null)
-        return null;
-    const parsed = Number.parseInt(String(raw), 10);
-    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 5) {
-        throw new Error("`--max-attempts` must be a whole number from 1 to 5.");
-    }
-    return parsed;
-}
-function readStageShellRetentionMode(argv) {
-    const enabled = argv["keep-stage-shells"] ??
-        argv.keepStageShells ??
-        false;
-    return enabled ? "always" : "on-failure";
-}
-function readCompileMaxLoopsOverride(argv) {
-    const raw = argv["max-loops"] ??
-        argv.maxLoops;
-    if (raw == null)
-        return null;
-    const parsed = Number.parseInt(String(raw), 10);
-    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 3) {
-        throw new Error("`--max-loops` must be a whole number from 1 to 3.");
-    }
-    return parsed;
-}
+        console.log();
+    },
+};

package/dist/cli/commands/doctor.js

@@ -97,7 +97,7 @@ export const doctorCommand = {
                 id: "live",
                 label: "Live executor preflight",
                 status: "skipped",
-                message: "Skipped. Run `interf doctor --live` to exercise the real local agent before drafting readiness checks, Method authoring, a readiness check, or a prepare run.",
+                message: "Skipped. Run `interf doctor --live` to exercise the real local agent before drafting readiness checks, Method authoring, a readiness check, or a compile run.",
             });
         }
         const ok = checks.every((check) => check.status !== "fail");

package/dist/cli/commands/login.d.ts

@@ -0,0 +1,7 @@
+import type { CommandModule } from "yargs";
+interface LoginArgs {
+    url: string;
+    token?: string;
+}
+export declare const loginCommand: CommandModule<unknown, LoginArgs>;
+export {};

package/dist/cli/commands/login.js

@@ -0,0 +1,39 @@
+/**
+ * `interf login` — set the active connection record.
+ *
+ *   interf login --url <url> [--token <token>]
+ *
+ * Writes `~/.interf/connection.json` so subsequent CLI commands target the
+ * remote (or alternate local) URL. There is no remote backend in 0.13 — this
+ * is the on-disk config layer that the cloud product will consume. Equivalent
+ * to running `interf web` (which writes a local connection record on
+ * startup).
+ */
+import chalk from "chalk";
+import { ConnectionRecordSchema, writeConnection, } from "../../packages/local-service/connection-config.js";
+export const loginCommand = {
+    command: "login",
+    describe: "Set the active Interf instance connection (URL + optional bearer token)",
+    builder: (yargs) => yargs
+        .option("url", {
+        type: "string",
+        demandOption: true,
+        describe: "Engine URL, e.g. https://api.interf.cloud or http://127.0.0.1:4873",
+    })
+        .option("token", {
+        type: "string",
+        describe: "Bearer token for non-loopback connections",
+    }),
+    handler: (args) => {
+        const url = args.url.trim();
+        const token = args.token?.trim();
+        const record = ConnectionRecordSchema.parse({
+            url,
+            auth_token: token && token.length > 0 ? token : null,
+        });
+        writeConnection(record);
+        console.log(chalk.green(`Connection saved.`));
+        console.log(chalk.dim(`  url: ${record.url}`));
+        console.log(chalk.dim(`  auth: ${record.auth_token ? "(token set)" : "(loopback / no token)"}`));
+    },
+};

package/dist/cli/commands/logout.d.ts

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const logoutCommand: CommandModule;

package/dist/cli/commands/logout.js

@@ -0,0 +1,16 @@
+/**
+ * `interf logout` — clear the active connection record.
+ *
+ * Removes `~/.interf/connection.json`. Subsequent CLI commands will exit
+ * non-zero with the connect-or-error hint until a new connection is set.
+ */
+import chalk from "chalk";
+import { clearConnection } from "../../packages/local-service/connection-config.js";
+export const logoutCommand = {
+    command: "logout",
+    describe: "Clear the active Interf instance connection",
+    handler: () => {
+        clearConnection();
+        console.log(chalk.green("Connection cleared."));
+    },
+};

package/dist/cli/commands/method.d.ts

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const methodCommand: CommandModule;

package/dist/cli/commands/method.js

@@ -0,0 +1,113 @@
+/**
+ * `interf method` — manage methods on the connected instance.
+ *
+ *   interf method ls                          # list methods (instance-wide)
+ *   interf method install <path>              # install a method package
+ *   interf method draft <prep-id>             # start a method-authoring run
+ *   interf method improve <prep-id>           # start a method-improvement run
+ */
+import chalk from "chalk";
+import { resolve } from "node:path";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
+}
+async function callJson(url, token, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    if (init.body && !headers.has("content-type"))
+        headers.set("content-type", "application/json");
+    const response = await fetch(url, { ...init, headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = null;
+        }
+    }
+    return { status: response.status, body, raw };
+}
+export const methodCommand = {
+    command: "method <subcommand>",
+    describe: "Manage methods on the connected instance",
+    builder: (yargs) => yargs
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .command("ls", "List methods on the instance", (y) => y, async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/methods`, token);
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to list methods (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const methods = body?.methods ?? [];
+        if (methods.length === 0) {
+            console.log(chalk.dim("  No methods on this instance."));
+            return;
+        }
+        console.log();
+        for (const m of methods) {
+            const id = m.method_id ?? m.id ?? "(?)";
+            const label = m.label ? ` ${chalk.dim(m.label)}` : "";
+            const kind = m.source_kind ? chalk.dim(`[${m.source_kind}]`) : "";
+            console.log(`  ${chalk.bold(id)} ${kind}${label}`);
+            if (m.active_for_preparations?.length) {
+                console.log(chalk.dim(`    used by: ${m.active_for_preparations.join(", ")}`));
+            }
+        }
+        console.log();
+    })
+        .command("install <path>", "Install a method package from a local folder", (y) => y.positional("path", { type: "string", demandOption: true, describe: "Path to the method package" }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const absolute = resolve(process.cwd(), args.path);
+        const { status, raw } = await callJson(`${url}/v1/methods`, token, { method: "POST", body: JSON.stringify({ source_path: absolute }) });
+        if (status !== 201 && status !== 200) {
+            console.error(chalk.red(`Failed to install method (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`Installed method from ${absolute}.`));
+    })
+        .command("draft <prep-id>", "Start a method-authoring run for a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/method-authoring-runs`, token, { method: "POST", body: JSON.stringify({}) });
+        if (status !== 201 && status !== 200) {
+            console.error(chalk.red(`Failed to start method-authoring run (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`Method-authoring run ${chalk.bold(body?.run_id ?? "(?)")} started.`));
+    })
+        .command("improve <prep-id>", "Start a method-improvement run for a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/method-improvement-runs`, token, { method: "POST", body: JSON.stringify({}) });
+        if (status !== 201 && status !== 200) {
+            console.error(chalk.red(`Failed to start method-improvement run (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`Method-improvement run ${chalk.bold(body?.run_id ?? "(?)")} started.`));
+    })
+        .demandCommand(1)
+        .strict(),
+    handler: () => {
+        /* yargs subcommand handlers do the work */
+    },
+};

package/dist/cli/commands/prep.d.ts

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const prepCommand: CommandModule;