@kontourai/flow-agents 0.1.1

package/build/src/cli/flow-kit.js

@@ -0,0 +1,138 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseArgs, flagBool, flagString } from "../lib/args.js";
+import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
+import { assertKitRepository } from "../flow-kit/validate.js";
+import { activateCodexLocal } from "../runtime-adapters.js";
+const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
+const REPOSITORIES_REL = path.join("kits", "local", "repositories");
+function registryPath(dest) { return path.join(dest, REGISTRY_REL); }
+function installedPath(dest, kitId) { return path.join(dest, REPOSITORIES_REL, kitId); }
+function loadRegistry(dest) {
+    const file = registryPath(dest);
+    if (!fs.existsSync(file))
+        return { schema_version: "1.0", kits: [] };
+    const data = readJson(file);
+    return { schema_version: data.schema_version ?? "1.0", kits: Array.isArray(data.kits) ? data.kits.filter((item) => typeof item === "object" && item !== null) : [] };
+}
+function contentHash(root) {
+    const hash = crypto.createHash("sha256");
+    for (const file of walkFiles(root)) {
+        const rel = path.relative(root, file).split(path.sep).join("/");
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(fs.readFileSync(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+function installLocal(argv) {
+    const args = parseArgs(argv);
+    const source = path.resolve(args.positionals[0] ?? "");
+    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    let manifest;
+    try {
+        manifest = assertKitRepository(source);
+    }
+    catch (error) {
+        console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
+        console.log("Flow Kit repository validation failed:");
+        for (const diagnostic of (error.diagnostics ?? [error.message]))
+            console.log(` - ${diagnostic}`);
+        return 1;
+    }
+    console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
+    const kitId = String(manifest.id);
+    const hash = contentHash(source);
+    const registry = loadRegistry(dest);
+    const existing = registry.kits.find((entry) => entry.id === kitId);
+    const target = installedPath(dest, kitId);
+    assertPathContained(dest, target);
+    const sourceText = source;
+    if (existing && existing.source !== sourceText && !flagBool(args.flags, "update")) {
+        console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
+        return 2;
+    }
+    if (existing && existing.source === sourceText && existing.hash === hash && fs.existsSync(target) && !flagBool(args.flags, "force")) {
+        console.log(`kit '${kitId}' is already installed from ${sourceText}`);
+        return 0;
+    }
+    copyDir(source, target);
+    const entry = {
+        id: kitId,
+        source: sourceText,
+        hash,
+        installed_at: existing && existing.source === sourceText && !flagBool(args.flags, "update") ? existing.installed_at : isoNow(),
+        installed_path: target,
+        state: "installed",
+    };
+    if (typeof manifest.version === "string" && manifest.version)
+        entry.version = manifest.version;
+    registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
+    writeJson(registryPath(dest), registry);
+    console.log(`${existing ? "updated" : "installed"} local kit '${kitId}' at ${target}`);
+    return 0;
+}
+function list(argv) {
+    const args = parseArgs(argv);
+    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const entries = loadRegistry(dest).kits;
+    if (!entries.length) {
+        console.log("No local Flow Kits installed.");
+        return 0;
+    }
+    for (const entry of entries.sort((a, b) => String(a.id ?? "").localeCompare(String(b.id ?? "")))) {
+        console.log(`${entry.id} | source=${entry.source} | hash=${entry.hash} | installed_at=${entry.installed_at} | path=${entry.installed_path} | state=${entry.state ?? "unknown"}`);
+    }
+    return 0;
+}
+function status(argv) {
+    const args = parseArgs(argv);
+    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    let entries = loadRegistry(dest).kits;
+    const kitId = args.positionals[0];
+    if (kitId) {
+        entries = entries.filter((entry) => entry.id === kitId);
+        if (!entries.length) {
+            console.log(`local Flow Kit '${kitId}' is not installed`);
+            return 1;
+        }
+    }
+    if (!entries.length) {
+        console.log("No local Flow Kits installed.");
+        return 0;
+    }
+    for (const entry of entries.sort((a, b) => String(a.id ?? "").localeCompare(String(b.id ?? "")))) {
+        console.log(JSON.stringify({ ...entry, state: fs.existsSync(String(entry.installed_path ?? "")) ? "installed" : "missing" }, null, 2));
+    }
+    return 0;
+}
+function activate(argv) {
+    const args = parseArgs(argv);
+    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
+    const adapter = flagString(args.flags, "adapter");
+    if (adapter && adapter !== "codex-local") {
+        console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+        return 2;
+    }
+    const result = activateCodexLocal(sourceRoot, dest);
+    console.log(JSON.stringify(result, null, 2));
+    return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
+}
+export function main(argv = process.argv.slice(2)) {
+    const [command, ...rest] = argv;
+    if (command === "install-local")
+        return installLocal(rest);
+    if (command === "list")
+        return list(rest);
+    if (command === "status")
+        return status(rest);
+    if (command === "activate")
+        return activate(rest);
+    console.error("usage: flow-kit <install-local|list|status|activate> ...");
+    return 2;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/import-bookmarks.js

@@ -0,0 +1,50 @@
+import * as fs from "node:fs";
+const SKIP = [/mail\.google\.com/i, /outlook\.(office|live)\.com/i, /calendar\.google\.com/i, /linkedin\.com\/in\//i, /slack\.com\/archives/i, /zoom\.us\/j\//i, /teams\.microsoft\.com/i];
+const TAGS = [[/github\.com|gitlab\.com|codecommit|code\.amazon/i, "repo"], [/docs\.|documentation|\/docs\/|readme|userguide|developer-guide/i, "docs"], [/wiki\.|\/wiki\/|confluence|runbook/i, "wiki"], [/dashboard|console\.|portal|admin\.|grafana|cloudwatch/i, "tool"], [/learn\.|training\.|course|certification|workshop|tutorial/i, "training"], [/template|boilerplate|starter|scaffold/i, "template"], [/spec\.|standard|architecture|rfc|design-doc/i, "reference"]];
+function inferTag(url) {
+    return TAGS.find(([pattern]) => pattern.test(url))?.[1] ?? "external";
+}
+function existingUrls(file) {
+    if (!fs.existsSync(file))
+        return new Set();
+    return new Set(Array.from(fs.readFileSync(file, "utf8").matchAll(/-->\s*(https?:\/\/\S+)|—\s+(https?:\/\/\S+)/g), (match) => match[1] ?? match[2]));
+}
+export function main(argv = process.argv.slice(2)) {
+    if (argv.length < 2) {
+        console.log("Usage: import-bookmarks <bookmarks.html> <bookmarks.md>");
+        return 1;
+    }
+    const [htmlPath, mdPath] = argv;
+    if (!fs.existsSync(htmlPath)) {
+        console.log(`Error: ${htmlPath} not found`);
+        return 1;
+    }
+    const html = fs.readFileSync(htmlPath, "utf8");
+    const bookmarks = Array.from(html.matchAll(/<A\b[^>]*HREF=["']([^"']+)["'][^>]*>(.*?)<\/A>/gi), (match) => ({ url: match[1], title: match[2].replace(/<[^>]+>/g, "").trim() }));
+    console.log(`Found ${bookmarks.length} bookmarks in HTML`);
+    const seen = existingUrls(mdPath);
+    console.log(`Found ${seen.size} existing entries in bookmarks.md`);
+    const today = new Date().toISOString().slice(0, 10);
+    const entries = [];
+    let skipped = 0;
+    let preserved = 0;
+    for (const bookmark of bookmarks) {
+        if (!/^https?:\/\//.test(bookmark.url) || SKIP.some((pattern) => pattern.test(bookmark.url))) {
+            skipped += 1;
+            continue;
+        }
+        if (seen.has(bookmark.url)) {
+            preserved += 1;
+            continue;
+        }
+        entries.push(`- **${today}** [${inferTag(bookmark.url)}]: ${bookmark.title} — ${bookmark.url} — (imported from browser)`);
+    }
+    if (entries.length)
+        fs.appendFileSync(mdPath, `${fs.existsSync(mdPath) ? "\n" : ""}${entries.join("\n")}\n`, "utf8");
+    console.log(`Added ${entries.length} new bookmarks`);
+    console.log(`Preserved ${preserved} existing bookmarks`);
+    console.log(`Skipped ${skipped} routine/non-http bookmarks`);
+    return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/init.js

@@ -0,0 +1,239 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
+import { activateCodexLocal } from "../runtime-adapters.js";
+import { main as buildBundles } from "../tools/build-universal-bundles.js";
+import { root } from "../tools/common.js";
+const runtimeBundles = {
+    base: "base",
+    codex: "codex",
+    "claude-code": "claude-code",
+    kiro: "kiro",
+};
+function usage() {
+    console.error(`usage: flow-agents init [options]
+
+Options:
+  --runtime base|codex|claude-code|kiro
+  --dest PATH
+  --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
+  --console-url URL
+  --console-endpoint URL
+  --console-token-file PATH
+  --console-tenant ID
+  --packs LIST
+  --activate-kits
+  --yes, --headless
+`);
+}
+function normalizeRuntime(value) {
+    if (!value)
+        return undefined;
+    if (value === "claude")
+        return "claude-code";
+    if (value === "base" || value === "codex" || value === "claude-code" || value === "kiro")
+        return value;
+    throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, or kiro`);
+}
+function normalizeTelemetrySink(value) {
+    if (value === "local-files" || value === "local-kontour-console" || value === "kontour-hosted-console" || value === "user-hosted-console" || value === "kontour-cloud" || value === "hosted-kontour-console")
+        return value;
+    throw new Error(`unknown telemetry sink '${value}'`);
+}
+function telemetrySinksFromValues(values) {
+    const sinks = values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean).map(normalizeTelemetrySink);
+    return sinks.length ? Array.from(new Set(sinks)) : ["local-files"];
+}
+function telemetrySinksFromFlags(flags) {
+    return telemetrySinksFromValues(flagList(flags, "telemetry-sink").concat(flagList(flags, "telemetry-sinks")));
+}
+function needsConsoleCredentials(sinks) {
+    return sinks.some((sink) => sink !== "local-files");
+}
+async function questionHidden(prompt) {
+    if (!process.stdin.isTTY)
+        return "";
+    return await new Promise((resolve) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        const wasRaw = stdin.isRaw;
+        stdout.write(prompt);
+        stdin.setRawMode(true);
+        stdin.resume();
+        let value = "";
+        const onData = (buffer) => {
+            const text = buffer.toString("utf8");
+            if (text === "\u0003") {
+                stdout.write("\n");
+                process.exit(130);
+            }
+            if (text === "\r" || text === "\n") {
+                stdout.write("\n");
+                stdin.setRawMode(wasRaw);
+                stdin.off("data", onData);
+                resolve(value);
+                return;
+            }
+            if (text === "\u007f") {
+                value = value.slice(0, -1);
+                return;
+            }
+            value += text;
+        };
+        stdin.on("data", onData);
+    });
+}
+function defaultDest(runtime) {
+    if (runtime === "kiro")
+        return path.join(os.homedir(), ".flow-agents");
+    return process.cwd();
+}
+function parseYesNo(value, fallback) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return fallback;
+    if (["y", "yes", "true", "1"].includes(normalized))
+        return true;
+    if (["n", "no", "false", "0"].includes(normalized))
+        return false;
+    return fallback;
+}
+async function interactiveOptions(argv) {
+    const args = parseArgs(argv);
+    const rl = createInterface({ input, output });
+    try {
+        const runtimeDefault = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
+        const runtimeAnswer = flagString(args.flags, "runtime") ?? await rl.question(`Runtime [${runtimeDefault}]: `);
+        const runtime = normalizeRuntime(runtimeAnswer.trim() || runtimeDefault) ?? runtimeDefault;
+        const destDefault = flagString(args.flags, "dest", defaultDest(runtime)) ?? defaultDest(runtime);
+        const destAnswer = flagString(args.flags, "dest") ?? await rl.question(`Install destination [${destDefault}]: `);
+        const sinkDefault = telemetrySinksFromFlags(args.flags);
+        const sinkAnswer = flagList(args.flags, "telemetry-sink").length || flagList(args.flags, "telemetry-sinks").length
+            ? sinkDefault.join(",")
+            : await rl.question(`Telemetry sinks [${sinkDefault.join(",")}]: `);
+        const telemetrySinks = telemetrySinksFromValues([sinkAnswer || sinkDefault.join(",")]);
+        const needsUserHostedUrl = telemetrySinks.includes("user-hosted-console") || telemetrySinks.includes("hosted-kontour-console");
+        const consoleUrl = flagString(args.flags, "console-url") ?? (needsUserHostedUrl ? await rl.question("User-hosted Console URL: ") : undefined);
+        const consoleEndpoint = flagString(args.flags, "console-endpoint") ?? flagString(args.flags, "console-endpoint-url");
+        const consoleTokenFile = flagString(args.flags, "console-token-file");
+        const consoleTokenValue = consoleTokenFile ? undefined : (needsConsoleCredentials(telemetrySinks) ? await questionHidden("Console telemetry token (blank to skip): ") : undefined);
+        const consoleTenant = flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id") ?? (needsConsoleCredentials(telemetrySinks) ? await rl.question("Console tenant ID (blank to skip): ") : undefined);
+        const activateDefault = false;
+        const activateAnswer = flagBool(args.flags, "activate-kits")
+            ? "yes"
+            : runtime === "codex"
+                ? await rl.question(`Activate local Builder Kit runtime assets [${activateDefault ? "Y/n" : "y/N"}]: `)
+                : "no";
+        return {
+            runtime,
+            dest: path.resolve(destAnswer.trim() || destDefault),
+            consoleUrl: consoleUrl?.trim() || undefined,
+            consoleEndpoint: consoleEndpoint?.trim() || undefined,
+            consoleTokenFile: consoleTokenFile?.trim() || undefined,
+            consoleTokenValue: consoleTokenValue?.trim() || undefined,
+            consoleTenant: consoleTenant?.trim() || undefined,
+            telemetrySinks,
+            packs: flagString(args.flags, "packs"),
+            activateKits: runtime === "codex" && parseYesNo(activateAnswer, activateDefault),
+        };
+    }
+    finally {
+        rl.close();
+    }
+}
+function headlessOptions(argv) {
+    const args = parseArgs(argv);
+    const runtime = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
+    return {
+        runtime,
+        dest: path.resolve(flagString(args.flags, "dest", defaultDest(runtime)) ?? defaultDest(runtime)),
+        consoleUrl: flagString(args.flags, "console-url"),
+        consoleEndpoint: flagString(args.flags, "console-endpoint") ?? flagString(args.flags, "console-endpoint-url"),
+        consoleTokenFile: flagString(args.flags, "console-token-file"),
+        consoleTenant: flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id"),
+        telemetrySinks: telemetrySinksFromFlags(args.flags),
+        packs: flagString(args.flags, "packs"),
+        activateKits: runtime === "codex" && flagBool(args.flags, "activate-kits"),
+    };
+}
+function ensureBundle(runtime) {
+    const bundle = path.join(root, "dist", runtimeBundles[runtime]);
+    if (!fs.existsSync(path.join(bundle, "install.sh"))) {
+        const rc = buildBundles();
+        if (rc !== 0)
+            throw new Error(`bundle build failed with exit code ${rc}`);
+    }
+    if (!fs.existsSync(path.join(bundle, "install.sh")))
+        throw new Error(`bundle installer missing: ${bundle}`);
+    return bundle;
+}
+function installBundle(bundle, options) {
+    const args = ["install.sh", options.dest];
+    for (const sink of options.telemetrySinks)
+        args.push("--telemetry-sink", sink);
+    if (options.consoleUrl)
+        args.push("--console-url", options.consoleUrl);
+    if (options.consoleEndpoint)
+        args.push("--console-endpoint", options.consoleEndpoint);
+    let tempTokenFile;
+    const consoleTokenFile = options.consoleTokenFile ?? (() => {
+        if (!options.consoleTokenValue)
+            return undefined;
+        const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-token-")), "console-token");
+        fs.writeFileSync(file, options.consoleTokenValue, { encoding: "utf8", mode: 0o600 });
+        tempTokenFile = file;
+        return file;
+    })();
+    if (consoleTokenFile)
+        args.push("--console-token-file", consoleTokenFile);
+    if (options.consoleTenant)
+        args.push("--console-tenant", options.consoleTenant);
+    const env = { ...process.env };
+    if (options.packs)
+        env.FLOW_AGENTS_PACKS = options.packs;
+    const result = spawnSync("bash", args, { cwd: bundle, env, encoding: "utf8", stdio: "inherit" });
+    if (tempTokenFile)
+        fs.rmSync(path.dirname(tempTokenFile), { recursive: true, force: true });
+    if (result.error) {
+        console.error(`flow-agents init: unable to run bundle installer: ${result.error.message}`);
+        return 1;
+    }
+    return result.status ?? 1;
+}
+function activateKits(options) {
+    if (!options.activateKits)
+        return 0;
+    const result = activateCodexLocal(options.dest, options.dest);
+    if (Array.isArray(result.errors) && result.errors.length > 0) {
+        console.error(JSON.stringify(result, null, 2));
+        return 1;
+    }
+    const generated = Array.isArray(result.generated_runtime_files) ? result.generated_runtime_files : [];
+    console.log(`Activated ${generated.length} Codex local runtime asset(s)`);
+    return 0;
+}
+export async function main(argv = process.argv.slice(2)) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        usage();
+        return 0;
+    }
+    const headless = argv.includes("--yes") || argv.includes("--headless") || !process.stdin.isTTY;
+    try {
+        const options = headless ? headlessOptions(argv) : await interactiveOptions(argv);
+        const bundle = ensureBundle(options.runtime);
+        const installed = installBundle(bundle, options);
+        if (installed !== 0)
+            return installed;
+        return activateKits(options);
+    }
+    catch (error) {
+        console.error(`flow-agents init: ${error.message}`);
+        return 2;
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(await main());

package/build/src/cli/instinct-cli.js

@@ -0,0 +1,93 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const SOUL_PATH = process.env.SOUL_PATH ?? path.join(os.homedir(), ".soul");
+const INSTINCTS_DIR = path.join(SOUL_PATH, "knowledge", "instincts");
+function parse(file) {
+    const text = fs.readFileSync(file, "utf8");
+    if (!text.startsWith("---"))
+        return null;
+    const [, fm, body] = text.split("---", 3);
+    const meta = {};
+    for (const line of fm.trim().split(/\r?\n/)) {
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        const raw = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+        meta[key] = key === "confidence" ? Number(raw) : key === "observation_count" ? Number.parseInt(raw, 10) : raw;
+    }
+    meta._body = body.trim();
+    meta._path = file;
+    return meta;
+}
+function files() {
+    const roots = [path.join(INSTINCTS_DIR, "global"), path.join(INSTINCTS_DIR, "projects")];
+    const out = [];
+    for (const root of roots) {
+        if (!fs.existsSync(root))
+            continue;
+        const stack = [root];
+        while (stack.length) {
+            const dir = stack.pop();
+            for (const name of fs.readdirSync(dir)) {
+                const file = path.join(dir, name);
+                if (fs.statSync(file).isDirectory())
+                    stack.push(file);
+                else if (file.endsWith(".md"))
+                    out.push(file);
+            }
+        }
+    }
+    return out;
+}
+function write(inst, file) {
+    const body = String(inst._body ?? "");
+    const lines = ["---"];
+    for (const [key, value] of Object.entries(inst))
+        if (!key.startsWith("_"))
+            lines.push(`${key}: ${typeof value === "number" ? value : String(value)}`);
+    lines.push("---", "", body);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${lines.join("\n").trimEnd()}\n`, "utf8");
+}
+export function main(argv = process.argv.slice(2)) {
+    const [command, ...rest] = argv;
+    const instincts = files().map(parse).filter((item) => Boolean(item));
+    if (command === "status") {
+        const global = instincts.filter((item) => item.scope === "global").length;
+        console.log(`Total instincts: ${instincts.length}`);
+        console.log(`  Global: ${global}, Project: ${instincts.length - global}`);
+        return 0;
+    }
+    if (command === "list") {
+        for (const inst of instincts)
+            console.log(`  [${Number(inst.confidence ?? 0).toFixed(2)}] ${inst.id ?? "?"} - ${inst.trigger ?? "?"} (${inst.scope ?? "?"})`);
+        return 0;
+    }
+    if (command === "show") {
+        const found = instincts.find((item) => item.id === rest[0]);
+        if (!found) {
+            console.error(`Instinct '${rest[0]}' not found.`);
+            return 1;
+        }
+        console.log(fs.readFileSync(String(found._path), "utf8"));
+        return 0;
+    }
+    if (command === "create") {
+        const id = rest[rest.indexOf("--id") + 1];
+        const trigger = rest[rest.indexOf("--trigger") + 1];
+        const domain = rest[rest.indexOf("--domain") + 1];
+        const scope = rest.includes("--scope") ? rest[rest.indexOf("--scope") + 1] : "project";
+        if (!id || !trigger || !domain)
+            return 2;
+        const file = scope === "global" ? path.join(INSTINCTS_DIR, "global", `${id}.md`) : path.join(INSTINCTS_DIR, "projects", rest[rest.indexOf("--project-id") + 1] ?? "default", "instincts", `${id}.md`);
+        write({ id, trigger, confidence: 0.3, domain, source: "session-observation", scope, created: new Date().toISOString().slice(0, 10), last_observed: new Date().toISOString().slice(0, 10), observation_count: 1, _body: `# ${id}\n\n## Action\nTBD` }, file);
+        console.log(`Created ${file}`);
+        return 0;
+    }
+    console.error("usage: instinct-cli <status|list|show|create>");
+    return 2;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/promote-workflow-artifact.js

@@ -0,0 +1,63 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseArgs, flagString } from "../lib/args.js";
+import { isoNow, relPath } from "../lib/fs.js";
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "delivery";
+}
+function repoRootFor(file) {
+    let current = path.dirname(path.resolve(file));
+    for (let i = 0; i < 40; i += 1) {
+        if (fs.existsSync(path.join(current, ".git")) || fs.existsSync(path.join(current, "AGENTS.md")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return process.cwd();
+}
+function firstHeading(text) {
+    return text.split(/\r?\n/).find((line) => line.startsWith("# "))?.slice(2).trim() || "Delivery";
+}
+function field(text, name) {
+    return text.match(new RegExp(`^${name}:\\s*(.+)$`, "m"))?.[1].trim() ?? "";
+}
+function section(text, heading) {
+    const match = new RegExp(`^##\\s+${heading}\\s*$`, "m").exec(text);
+    if (!match)
+        return "";
+    const start = match.index + match[0].length;
+    const rest = text.slice(start);
+    const next = /^##\s+/m.exec(rest);
+    return rest.slice(0, next ? next.index : undefined).trim();
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    const artifact = path.resolve(args.positionals[0] ?? "");
+    if (!artifact || !fs.existsSync(artifact))
+        throw new Error(`artifact not found: ${artifact}`);
+    const root = repoRootFor(artifact);
+    const text = fs.readFileSync(artifact, "utf8");
+    const title = flagString(args.flags, "title") ?? firstHeading(text);
+    const docsDir = path.resolve(root, flagString(args.flags, "docs-dir", "docs/delivery") ?? "docs/delivery");
+    const date = isoNow().slice(0, 10);
+    const archiveBase = flagString(args.flags, "archive-dir") ? path.resolve(root, flagString(args.flags, "archive-dir") ?? "") : path.join(path.dirname(artifact), "archive");
+    const archive = path.join(archiveBase, date, path.basename(artifact));
+    const doc = path.join(docsDir, `${slugify(title)}.md`);
+    fs.mkdirSync(path.dirname(archive), { recursive: true });
+    fs.mkdirSync(path.dirname(doc), { recursive: true });
+    fs.copyFileSync(artifact, archive);
+    const pieces = ["---", `title: "${title}"`, `created: ${isoNow()}`, `source_artifact: ${relPath(root, artifact)}`, `archived_artifact: ${relPath(root, archive)}`, `delivery_status: ${field(text, "status") || "unknown"}`, "---", "", `# ${title}`, "", "This document was promoted from a delivery artifact after final acceptance.", "", "## Source", "", `- Working artifact: \`${relPath(root, artifact)}\``, `- Archived artifact: \`${relPath(root, archive)}\``, `- Status at promotion: \`${field(text, "status") || "unknown"}\``, ""];
+    for (const heading of ["Definition Of Done", "Plan", "Verification Report", "Goal Fit Gate", "Final Acceptance", "History"]) {
+        const body = section(text, heading);
+        if (body)
+            pieces.push(`## ${heading}`, "", body, "");
+    }
+    fs.writeFileSync(doc, `${pieces.join("\n").trimEnd()}\n`, "utf8");
+    console.log(`promoted_doc=${doc}`);
+    console.log(`archived_artifact=${archive}`);
+    return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());