@litfamily/litopencode 1.0.0

package/dist/cli/vendor-path-migration.d.ts

@@ -0,0 +1,9 @@
+export declare const legacyVendorPaths: readonly [{
+    readonly legacy: "022_handoff";
+    readonly canonical: "handoff";
+}, {
+    readonly legacy: "045_scientific-visualization";
+    readonly canonical: "scientific-visualization";
+}];
+/** Move only pristine, manifest-owned numbered vendor roots to their canonical names. */
+export declare function migrateLegacyVendorPaths(sourceRoot: string, targetRoot: string): Promise<void>;

package/dist/cli/vendor-path-migration.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertContained, assertPathComponentsSafe } from "./native-skill-tree.js";
+export const legacyVendorPaths = [
+    { legacy: "022_handoff", canonical: "handoff" },
+    { legacy: "045_scientific-visualization", canonical: "scientific-visualization" },
+];
+/** Move only pristine, manifest-owned numbered vendor roots to their canonical names. */
+export async function migrateLegacyVendorPaths(sourceRoot, targetRoot) {
+    await requireDirectory(sourceRoot, "Vendor migration source");
+    await requireDirectory(targetRoot, "Vendor migration target");
+    const source = path.resolve(sourceRoot);
+    const target = path.resolve(targetRoot);
+    const moves = [];
+    for (const { legacy, canonical } of legacyVendorPaths) {
+        const sourcePath = path.join(source, canonical);
+        const legacyPath = path.join(target, legacy);
+        const canonicalPath = path.join(target, canonical);
+        await assertPathComponentsSafe(source, sourcePath, `Vendor source ${canonical}`);
+        await assertPathComponentsSafe(target, legacyPath, `Legacy vendor ${legacy}`);
+        await assertPathComponentsSafe(target, canonicalPath, `Canonical vendor ${canonical}`);
+        const sourceStat = await lstatIfPresent(sourcePath);
+        if (sourceStat === null || sourceStat.isSymbolicLink() || !sourceStat.isDirectory()) {
+            throw new Error(`Unsafe or missing canonical vendor source: ${canonical}`);
+        }
+        const legacyStat = await lstatIfPresent(legacyPath);
+        if (legacyStat === null)
+            continue;
+        if (legacyStat.isSymbolicLink() || !legacyStat.isDirectory()) {
+            throw new Error(`Unsafe legacy vendor path: ${legacy}`);
+        }
+        if (await lstatIfPresent(canonicalPath) !== null) {
+            throw new Error(`Legacy and canonical vendor paths coexist: ${canonical}`);
+        }
+        const expected = await vendorTreeSignature(sourcePath);
+        const actual = await vendorTreeSignature(legacyPath);
+        if (!sameSignature(expected, actual)) {
+            throw new Error(`Legacy vendor path is modified, foreign, or incomplete: ${legacy}`);
+        }
+        moves.push([legacyPath, canonicalPath]);
+    }
+    for (const [legacyPath, canonicalPath] of moves)
+        await fs.rename(legacyPath, canonicalPath);
+}
+async function requireDirectory(directory, label) {
+    const stat = await fs.lstat(directory).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (stat === null || stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`${label} is unsafe`);
+}
+async function lstatIfPresent(filePath) {
+    try {
+        return await fs.lstat(filePath);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function vendorTreeSignature(root) {
+    const entries = [];
+    const visit = async (directory, relativePath) => {
+        const directoryStat = await fs.lstat(directory);
+        if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+            throw new Error(`Unsupported vendor entry: ${relativePath || "."}`);
+        }
+        for (const entry of (await fs.readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+            const child = path.join(directory, entry.name);
+            const childRelative = relativePath === "" ? entry.name : `${relativePath}/${entry.name}`;
+            const stat = await fs.lstat(child);
+            if (stat.isSymbolicLink())
+                throw new Error(`Unsafe vendor symlink: ${childRelative}`);
+            if (stat.isDirectory()) {
+                entries.push(`directory\0${childRelative}\0${stat.mode & 0o7777}`);
+                await visit(child, childRelative);
+            }
+            else if (stat.isFile()) {
+                const digest = createHash("sha256").update(await fs.readFile(child)).digest("hex");
+                entries.push(`file\0${childRelative}\0${digest}\0${stat.mode & 0o7777}`);
+            }
+            else {
+                throw new Error(`Unsupported vendor entry: ${childRelative}`);
+            }
+        }
+    };
+    await visit(root, "");
+    return entries.sort();
+}
+function sameSignature(left, right) {
+    return left.length === right.length && left.every((entry, index) => entry === right[index]);
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+import type { CliResult, InstallProgress } from "./cli/types.ts";
+type RunCliOptions = {
+    readonly installProgress?: InstallProgress;
+};
+export declare function runCli(argv?: readonly string[], options?: RunCliOptions): Promise<CliResult>;
+export declare function main(argv?: readonly string[]): Promise<void>;
+export {};

package/dist/cli.js

@@ -0,0 +1,250 @@
+import { isLoopCommand, parseArgs } from "./cli/args.js";
+import { runLoopCommand } from "./cli/loop.js";
+import { doctor } from "./cli/doctor.js";
+import { install } from "./cli/install.js";
+import { createInstallTui, renderLitOpenCodeWordmark, shouldRenderInstallTui } from "./cli/install-tui.js";
+import { runUpdateNotifier } from "./cli/update-notifier.js";
+import { autoUpdateDiagnostic, canContinueAfterAutoUpdate, runInteractiveAutoUpdate } from "./cli/auto-update.js";
+import { LitOpenCodeConfigError } from "./config.js";
+import { fetchPublicSource } from "./lit-fetch.js";
+import { runSkillCuratorCli, runSkillLoopCli } from "./cli/skill-loop.js";
+import { readPackageMetadata } from "./cli/json.js";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+function helpText() {
+    return [
+        "litopencode",
+        "",
+        "Install LitOpenCode into OpenCode with an explicit npm package.",
+        "",
+        "Quick start:",
+        "  npm exec --package @litfamily/litopencode -- litopencode install",
+        "  npm exec --package @litfamily/litopencode -- litopencode fetch-public https://example.com --json",
+        "  npm exec --package @litfamily/litopencode -- litopencode install --permission-prompt",
+        "  npm exec --package @litfamily/litopencode -- litopencode install --permission-mode balanced",
+        "  npm exec --package @litfamily/litopencode -- litopencode install --yolo",
+        "  npm exec --package @litfamily/litopencode -- litopencode install --provider openai --model gpt-6-astra --effort xhigh",
+        "  npm exec --package @litfamily/litopencode -- litopencode install --provider openai --model gpt-5.6-luna --effort max",
+        "  npm exec --package @litfamily/litopencode -- litopencode install --provider openai --model gpt-5.6-luna --effort high",
+        "",
+        "Usage:",
+        "  litopencode install [--dry-run] [--root <dir>] --provider <openai|xai> --model <id> [--effort <e>] [--subagent-model <provider/id>] [--subagent-effort <e>] [--yolo]",
+        "  litopencode install [--model-prompt | --no-model-prompt | --yes]",
+        "  litopencode install [--permission-prompt | --no-permission-prompt] [--permission-mode <safe|balanced|yolo>]",
+        "  litopencode install|doctor [--no-auto-update]",
+        "  litopencode doctor [--json] [--root <dir>]",
+        "  litopencode fetch-public <url> [--json] [--timeout <ms>] [--max-bytes <n>]",
+        "  litopencode fetch-public <local-url> --json --allow-private-network  # trusted fixtures only",
+        "  litopencode skill-loop propose <file>|list|apply <id>|reject <id>|rollback <ledger-id>|review",
+        "  litopencode skill-curator run|status",
+        "  OpenCode /start-work init|resume|cancel|complete|status <schema-3 JSON>",
+        "",
+        "Isolated skill review (POSIX hosts only):",
+        "  LITOPENCODE_REVIEW_HOST=/absolute/path/to/opencode selects a pinned trusted host executable.",
+        "  LITOPENCODE_REVIEW_CREDENTIAL_ENV=NAME[,NAME...] forwards only named variables to the final tool-less review.",
+        "  Review never reads auth files; Windows review/mutation/curator returns WINDOWS_SKILL_LOOP_UNSUPPORTED.",
+        "",
+        "Evidence loop (all accept [--project <dir>] [--json]; default project is the current directory):",
+        "  litopencode create-goals --session-id <id> --objective <text> [--title <t>] [--criterion <scenario>]... [--force]",
+        "  litopencode status",
+        "  litopencode record-evidence --criterion-id <id> --kind <red|green|scenario|cleanup|note> --ref <ref> [--detail <t>] [--status <s>]",
+        "  litopencode record-observation --signal <correction|repetition|coverage-gap> --skill-id <id> --observed <t> --proposal <t>",
+        "  litopencode list-observations",
+        "  litopencode checkpoint --summary <text> [--criterion-id <id>]",
+        "  litopencode steer --directive <text> [--kind <redirect|add_criterion|narrow_scope|reprioritize|annotate>]",
+        "  litopencode record-review-blockers --detail <text> [--needs-user-decision]",
+        "  litopencode record-review-blockers --resolve <id>",
+        "  litopencode complete-goals",
+        "",
+        "Commands:",
+        "  install       Register litopencode with OpenCode using a branded installer UI.",
+        "  doctor        Report package, config, and runtime path status without writing files.",
+        "  fetch-public  Fetch a public URL with SSRF guards, verdicts, and trace output.",
+        "                --allow-private-network is opt-in for reviewed local fixtures or trusted internal tests.",
+        "",
+        "Evidence ledger:",
+        "  State lives in .litopencode/litgoal/lit-loop: goals.json is the machine state, brief.md is the",
+        "  human-readable rendering, and ledger.jsonl stays the append-only audit trail. status is read-only and writes no files.",
+        "  Mutating verbs write goals.json and brief.md, then append one ledger.jsonl audit event under the local mutation lock.",
+        "  Criterion status: pending, in_progress, blocked, pass, fail. Evidence kinds: red, green, scenario, cleanup, note.",
+        "  Goal status: active, blocked, review_blocked, needs_user_decision, complete.",
+        "  A fresh --session-id opens new state beside the old; --force is required only to overwrite recorded evidence.",
+        "  complete-goals refuses unless every criterion passes with green and scenario evidence and no blocker is open.",
+        "  steer --kind add_criterion appends a pending criterion with the next safe C-number; it must pass before completion.",
+        "  Other steering can redirect or annotate a goal; a directive that would weaken the completion gate is refused.",
+        "",
+        "Bounded authority:",
+        "  /start-work owns a schema-3 bounded-authority lifecycle with CAS revisions and durable compaction.",
+        "  Resume is accepted only from an exact trusted user route with the matching pending boundary grant.",
+        "  Agent-callable tools cannot use resume as a generic authority bypass.",
+        "",
+        "Project-local knowledge:",
+        "  The Wikify tool captures only structured fact, decision, failure, risk, rule, or checkpoint events.",
+        "  New claims start review-needed in .litopencode/knowledge/claims.jsonl; save or review changes state.",
+        "  Set knowledge.capture to false in .litopencode/config.json to disable capture. Query stays local and read-only.",
+        "",
+        "Native offline skills:",
+        "  frontend-ui-ux provides deterministic design-contract retrieval from a packaged MIT corpus,",
+        "                 plus fifteen shipped reference documents routed from its SKILL.md.",
+        "  visual-qa validates evidence, PNGs, terminal layouts, and independent review receipts,",
+        "            ships a per-channel capture playbook, and keeps blocked codes separate from fail codes.",
+        "  Each skill resolves its own helpers inside its own installed tree; neither adds command,",
+        "  browser, MCP, tool, agent, authentication, or write authority.",
+        "",
+        "Model routing:",
+        "  Interactive terminal installs ask provider (openai | xai), LEAD model (planning/review) and HELPER model (execution/research),",
+        "  preselecting the current managed route; --yes and --no-model-prompt keep the current non-picker behavior.",
+        "  openai rows: gpt-6-astra·xhigh (low/medium/high/xhigh/max), gpt-5.6-sol·xhigh, gpt-5.6-luna·max, gpt-5.6·high, gpt-5.6-terra·xhigh.",
+        "  The legacy GPT-5.6 rows retain their <id>-fast aliases; gpt-6-astra-fast is not a model alias.",
+        "  xai rows: reasoning-capable Grok models from the host catalog, grok-4.6 first; XAI_API_KEY is warned about, never required.",
+        "  --provider <p> --model <id> [--effort <e>] writes the lead route; --subagent-model <provider/id> [--subagent-effort <e>] the helper route.",
+        "  Astra accepts low, medium, high, xhigh, or max and uses native reasoning effort; LUNA accepts high or max and rejects xhigh.",
+        "  Without flags/reset, planning and review (including lit-loop) use Astra/xhigh; execution and research helpers use LUNA/max.",
+        "  --model-prompt forces the picker on any existing route (managed keys only); --no-model-prompt and --yes keep current model routes.",
+        "",
+        "Permission behavior:",
+        "  Terminal installs can ask whether LitOpenCode should stay safe, use balanced automation, or use YOLO.",
+        "  --permission-prompt forces the permission picker; --no-permission-prompt keeps safe defaults.",
+        "  --permission-mode <safe|balanced|yolo> writes the selected permission behavior explicitly.",
+        "  --yolo is shorthand for --permission-mode yolo and also allows external_directory; lit-plan stays deny-only.",
+        "",
+        "Automatic updates:",
+        "  Packaged plugin startup and successful interactive install/doctor use a bounded exact-version foreground update barrier.",
+        "  The transaction uses a separate lock, private backup, journal, receipt, and post-install doctor rollback.",
+        "  --no-auto-update or LITOPENCODE_NO_AUTO_UPDATE=1 disables the barrier; NO_UPDATE_NOTIFIER and LITOPENCODE_NO_UPDATE_CHECK also disable it.",
+        "  The detached update notice remains cache-refresh-only and never installs.",
+        "",
+        "Default root:",
+        "  ~/.config/opencode, or $XDG_CONFIG_HOME/opencode when XDG_CONFIG_HOME is set."
+    ].join("\n");
+}
+export async function runCli(argv = process.argv.slice(2), options = {}) {
+    if (argv[0] === "skill-loop")
+        return runSkillLoopCli(argv.slice(1));
+    if (argv[0] === "skill-curator")
+        return runSkillCuratorCli(argv.slice(1));
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stderr: message };
+    }
+    try {
+        if (!parsed.command || parsed.command === "help") {
+            return { exitCode: 0, stdout: helpText() };
+        }
+        if (isLoopCommand(parsed.command))
+            return await runLoopCommand(parsed.command, parsed.loop);
+        if (parsed.command === "doctor")
+            return await doctor(parsed.root);
+        if (parsed.command === "fetch-public") {
+            if (!parsed.fetchPublicUrl)
+                return { exitCode: 2, stderr: "fetch-public requires a URL" };
+            const output = await fetchPublicSource(parsed.fetchPublicUrl, {
+                allowPrivateNetwork: parsed.fetchPublicAllowPrivateNetwork,
+                timeoutMs: parsed.fetchPublicTimeoutMs,
+                maxBytes: parsed.fetchPublicMaxBytes
+            });
+            if (parsed.fetchPublicJson)
+                return { exitCode: output.ok ? 0 : 1, stdout: JSON.stringify(output, null, 2) };
+            return { exitCode: output.ok ? 0 : 1, stdout: renderFetchPublicText(output) };
+        }
+        if (parsed.command === "install") {
+            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt);
+        }
+        return { exitCode: 2, stderr: `Unknown command: ${parsed.command}` };
+    }
+    catch (error) {
+        await options.installProgress?.fail("Installer stopped before completion.");
+        const prefix = error instanceof LitOpenCodeConfigError ? "CONFIG_ERROR" : "ERROR";
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 1, stderr: `${prefix}: ${message}` };
+    }
+}
+function renderFetchPublicText(output) {
+    return [
+        `verdict: ${output.verdict}`,
+        `ok: ${String(output.ok)}`,
+        output.finalUrl ? `finalUrl: ${output.finalUrl}` : undefined,
+        output.status ? `status: ${output.status}` : undefined,
+        output.reason ? `reason: ${output.reason}` : undefined,
+        output.content ? "" : undefined,
+        output.content
+    ].filter((line) => line !== undefined).join("\n");
+}
+function shouldPrintCommandWordmark(argv) {
+    if (argv.includes("--json"))
+        return false;
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.command === "install" || parsed.command === "doctor")
+            return false;
+        return parsed.command === "help" || parsed.command === "fetch-public" || isLoopCommand(parsed.command);
+    }
+    catch {
+        return false;
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const result = await runCli(argv, { installProgress: shouldRenderInstallTui(argv) ? createInstallTui() : undefined });
+    if (shouldPrintCommandWordmark(argv)) {
+        const metadata = await readPackageMetadata();
+        const colorEnabled = process.stdout.isTTY === true && process.env.CI === undefined && process.env.NO_COLOR === undefined;
+        process.stdout.write(`${renderLitOpenCodeWordmark(metadata.name + "@" + metadata.version, colorEnabled)}\n`);
+    }
+    // Doctor's stdout is JSON even without --json; keep its interactive mark on stderr.
+    if (argv[0] === "doctor" && !argv.some((arg) => arg === "--json" || arg === "--help" || arg === "-h") && process.stderr.isTTY === true && process.env.CI === undefined) {
+        const metadata = await readPackageMetadata();
+        process.stderr.write(`${renderLitOpenCodeWordmark(metadata.name + "@" + metadata.version)}\n`);
+    }
+    if (result.stdout)
+        process.stdout.write(`${result.stdout}\n`);
+    if (result.stderr)
+        process.stderr.write(`${result.stderr}\n`);
+    let autoUpdateResult;
+    try {
+        autoUpdateResult = await runInteractiveAutoUpdate({
+            argv,
+            exitCode: result.exitCode,
+            env: process.env,
+            stdinIsTTY: process.stdin.isTTY,
+            stdoutIsTTY: process.stdout.isTTY,
+            stderrIsTTY: process.stderr.isTTY,
+            configRoot: (() => {
+                try {
+                    return parseArgs(argv).root;
+                }
+                catch {
+                    return undefined;
+                }
+            })()
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Automatic update stopped before verification: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!canContinueAfterAutoUpdate(autoUpdateResult)) {
+        process.stderr.write(`${autoUpdateDiagnostic(autoUpdateResult)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    await runUpdateNotifier({
+        argv,
+        exitCode: result.exitCode,
+        env: process.env,
+        stdinIsTTY: process.stdin.isTTY,
+        stdoutIsTTY: process.stdout.isTTY,
+        stderrIsTTY: process.stderr.isTTY
+    });
+    process.exitCode = result.exitCode;
+}
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    void main().catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}