litopencode 0.0.0 → 0.0.1

package/README.md

@@ -24,12 +24,28 @@
 - **Two-agent OpenCode surface** -- Keep the visible agent switcher focused on <code>lit-plan</code> and <code>lit-loop</code>.
 - **Durable goal ledger** -- Persist resumable progress under <code>.litopencode/litgoal/lit-loop/ledger.jsonl</code>.
 - **OpenCode-native plugin hooks** -- Register config, tools, command activation, tool guards, and dispose lifecycle hooks.
-- **Installer/doctor CLI** -- Inspect package, config, and runtime state with safe dry-run install output.
+- **npx installer/doctor CLI** -- Install the plugin into OpenCode with a branded terminal flow, or preview the exact config patch with dry-run.
 - **Role aliases and specialists** -- Keep deeper planning, implementation, verification, QA, review, research, and specialist roles available without crowding the default UI.
 - **Release guardrails** -- Verify scanner, lockstep, packed payload, source gates, and dry-pack behavior before publication.
 
 ## Quick Start
 
+### Install Into OpenCode
+
+    npx litopencode install
+
+Then restart OpenCode. The agent switcher should show <code>lit-plan</code> and <code>lit-loop</code>.
+
+For a preview without writing <code>opencode.json</code>:
+
+    npx litopencode install --dry-run
+
+For health checks:
+
+    npx litopencode doctor
+
+By default, the installer targets <code>~/.config/opencode/opencode.json</code>, or <code>$XDG_CONFIG_HOME/opencode/opencode.json</code> when <code>XDG_CONFIG_HOME</code> is set. Use <code>--root &lt;dir&gt;</code> for a custom OpenCode config directory.
+
 ### Local Source Probe
 
     npm install
@@ -41,12 +57,6 @@
     node bin/litopencode doctor --root .
     node bin/litopencode install --dry-run --root .
 
-### OpenCode Plugin Install Preview
-
-    node bin/litopencode install --dry-run --root ~/.config/opencode
-
-<code>install --dry-run</code> prints the exact <code>opencode.json</code> plugin mutation without writing files. <code>doctor</code> reports package, config, and runtime path status without creating runtime state.
-
 ## Package Surface
 
 | Surface | Value |

package/dist/cli/args.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedArgs } from "./types.ts";
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function helpText(): string;

package/dist/cli/args.js

@@ -0,0 +1,58 @@
+import os from "node:os";
+import path from "node:path";
+function defaultOpenCodeRoot() {
+    const configHome = process.env.XDG_CONFIG_HOME;
+    if (configHome && configHome.length > 0)
+        return path.join(configHome, "opencode");
+    return path.join(os.homedir(), ".config", "opencode");
+}
+export function parseArgs(argv) {
+    let command = argv[0];
+    let root = defaultOpenCodeRoot();
+    let dryRun = false;
+    if (command === "--help" || command === "-h") {
+        command = "help";
+    }
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--root" || arg === "--workdir") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error(`${arg} requires a value`);
+            root = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            command = "help";
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return { command, root, dryRun };
+}
+export function helpText() {
+    return [
+        "litopencode",
+        "",
+        "Install LitOpenCode into OpenCode with a polished npx flow.",
+        "",
+        "Quick start:",
+        "  npx litopencode install",
+        "",
+        "Usage:",
+        "  litopencode install [--dry-run] [--root <dir>]",
+        "  litopencode doctor [--root <dir>]",
+        "",
+        "Commands:",
+        "  install       Add litopencode to opencode.json with a branded installer UI.",
+        "  doctor        Report package, config, and runtime path status without writing files.",
+        "",
+        "Default root:",
+        "  ~/.config/opencode, or $XDG_CONFIG_HOME/opencode when XDG_CONFIG_HOME is set."
+    ].join("\n");
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { CliResult } from "./types.ts";
+export declare function doctor(root: string): Promise<CliResult>;

package/dist/cli/doctor.js

@@ -0,0 +1,34 @@
+import fs from "node:fs/promises";
+import { loadConfig } from "../config.js";
+import { readPackageMetadata } from "./json.js";
+export async function doctor(root) {
+    const metadata = await readPackageMetadata();
+    const loaded = await loadConfig(root);
+    const runtimeExists = await fs
+        .stat(loaded.paths.runtimeDir)
+        .then(() => true)
+        .catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return false;
+        throw error;
+    });
+    return {
+        exitCode: 0,
+        stdout: JSON.stringify({
+            package: metadata,
+            config: {
+                source: loaded.source,
+                path: loaded.paths.configFile,
+                enabled: loaded.config.enabled,
+                logLevel: loaded.config.logLevel
+            },
+            state: {
+                runtimeDir: loaded.paths.runtimeDir,
+                runtimeExists,
+                stateFile: loaded.paths.stateFile,
+                logFile: loaded.paths.logFile,
+                ledgerFile: loaded.paths.ledgerFile
+            }
+        }, null, 2)
+    };
+}

package/dist/cli/install.d.ts

@@ -0,0 +1,2 @@
+import type { CliResult } from "./types.ts";
+export declare function install(root: string, dryRun: boolean): Promise<CliResult>;

package/dist/cli/install.js

@@ -0,0 +1,85 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRuntimePaths } from "../state.js";
+import { readJsonObjectIfPresent, readPackageMetadata } from "./json.js";
+const pluginId = "litopencode";
+function describePluginMutation(config) {
+    const pluginValue = config?.plugin;
+    const pluginIsArray = Array.isArray(pluginValue);
+    const alreadyPresent = pluginIsArray && pluginValue.includes(pluginId);
+    const currentCount = pluginIsArray ? pluginValue.length : 0;
+    if (alreadyPresent) {
+        return {
+            changed: false,
+            plugin: { alreadyPresent: true, currentCount, resultCount: currentCount, add: [] },
+            patch: []
+        };
+    }
+    const add = [pluginId];
+    if (pluginIsArray) {
+        return {
+            changed: true,
+            plugin: { alreadyPresent: false, currentCount, resultCount: currentCount + 1, add },
+            patch: [{ op: "add", path: "/plugin/-", value: pluginId }]
+        };
+    }
+    const op = config !== null && Object.hasOwn(config, "plugin") ? "replace" : "add";
+    return {
+        changed: true,
+        plugin: { alreadyPresent: false, currentCount, resultCount: 1, add },
+        patch: [{ op, path: "/plugin", value: [pluginId] }]
+    };
+}
+function applyPluginMutation(config, mutation) {
+    const next = config === null ? { "$schema": "https://opencode.ai/config.json" } : { ...config };
+    if (!mutation.changed)
+        return next;
+    const pluginValue = next.plugin;
+    if (Array.isArray(pluginValue)) {
+        next.plugin = [...pluginValue, pluginId];
+        return next;
+    }
+    next.plugin = [pluginId];
+    return next;
+}
+function renderInstallReport(report) {
+    const status = report.changed ? "Complete" : "Already installed";
+    const action = report.changed ? "Added litopencode to plugin[]" : "No config change needed";
+    return [
+        "LitOpenCode Installer",
+        "=====================",
+        "",
+        "[-] Resolving package      " + `${report.package.name}@${report.package.version}`,
+        "[\\] Reading OpenCode config " + report.path,
+        "[|] Planning plugin patch " + `${report.plugin.currentCount} -> ${report.plugin.resultCount}`,
+        "[/] Writing config        " + action,
+        "",
+        status,
+        "",
+        "Next:",
+        "  Restart OpenCode and press tab to switch between lit-plan and lit-loop."
+    ].join("\n");
+}
+export async function install(root, dryRun) {
+    const metadata = await readPackageMetadata();
+    const paths = createRuntimePaths(root);
+    const before = await readJsonObjectIfPresent(paths.opencodeConfigFile);
+    const mutation = describePluginMutation(before);
+    const report = {
+        dryRun,
+        path: paths.opencodeConfigFile,
+        plugin: mutation.plugin,
+        patch: mutation.patch,
+        changed: mutation.changed,
+        package: metadata
+    };
+    if (dryRun) {
+        return { exitCode: 0, stdout: JSON.stringify(report, null, 2) };
+    }
+    if (mutation.changed) {
+        const next = applyPluginMutation(before, mutation);
+        await fs.mkdir(path.dirname(paths.opencodeConfigFile), { recursive: true });
+        await fs.writeFile(paths.opencodeConfigFile, JSON.stringify(next, null, 2) + "\n");
+    }
+    return { exitCode: 0, stdout: renderInstallReport(report) };
+}

package/dist/cli/json.d.ts

@@ -0,0 +1,4 @@
+import type { PackageMetadata } from "./types.ts";
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function readPackageMetadata(): Promise<PackageMetadata>;
+export declare function readJsonObjectIfPresent(filePath: string): Promise<Record<string, unknown> | null>;

package/dist/cli/json.js

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export async function readPackageMetadata() {
+    const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+    const parsed = JSON.parse(await fs.readFile(packagePath, "utf8"));
+    if (!isRecord(parsed) || typeof parsed.name !== "string" || typeof parsed.version !== "string") {
+        throw new Error(`Malformed package metadata at ${packagePath}`);
+    }
+    return { name: parsed.name, version: parsed.version };
+}
+export async function readJsonObjectIfPresent(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error(`Malformed JSON at ${filePath}: expected an object.`);
+    }
+    return parsed;
+}

package/dist/cli/types.d.ts

@@ -0,0 +1,45 @@
+export type CliResult = {
+    readonly exitCode: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+};
+export type PackageMetadata = {
+    readonly name: string;
+    readonly version: string;
+};
+export type ParsedArgs = {
+    readonly command?: string;
+    readonly root: string;
+    readonly dryRun: boolean;
+};
+export type JsonPatchOperation = {
+    readonly op: "add";
+    readonly path: "/plugin";
+    readonly value: readonly ["litopencode"];
+} | {
+    readonly op: "replace";
+    readonly path: "/plugin";
+    readonly value: readonly ["litopencode"];
+} | {
+    readonly op: "add";
+    readonly path: "/plugin/-";
+    readonly value: "litopencode";
+};
+export type PluginMutation = {
+    readonly changed: boolean;
+    readonly plugin: {
+        readonly alreadyPresent: boolean;
+        readonly currentCount: number;
+        readonly resultCount: number;
+        readonly add: readonly string[];
+    };
+    readonly patch: readonly JsonPatchOperation[];
+};
+export type InstallReport = {
+    readonly dryRun: boolean;
+    readonly path: string;
+    readonly plugin: PluginMutation["plugin"];
+    readonly patch: readonly JsonPatchOperation[];
+    readonly changed: boolean;
+    readonly package: PackageMetadata;
+};

package/dist/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -1,8 +1,3 @@
-type CliResult = {
-    exitCode: number;
-    stdout?: string;
-    stderr?: string;
-};
+import type { CliResult } from "./cli/types.ts";
 export declare function runCli(argv?: readonly string[]): Promise<CliResult>;
 export declare function main(argv?: readonly string[]): Promise<void>;
-export {};

package/dist/cli.js

@@ -1,174 +1,7 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { LitOpenCodeConfigError, loadConfig } from "./config.js";
-import { createRuntimePaths } from "./state.js";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-async function readPackageMetadata() {
-    const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
-    const parsed = JSON.parse(await fs.readFile(packagePath, "utf8"));
-    if (!isRecord(parsed) || typeof parsed.name !== "string" || typeof parsed.version !== "string") {
-        throw new Error(`Malformed package metadata at ${packagePath}`);
-    }
-    return { name: parsed.name, version: parsed.version };
-}
-function parseArgs(argv) {
-    const parsed = {
-        command: argv[0],
-        root: process.cwd(),
-        dryRun: false
-    };
-    if (parsed.command === "--help" || parsed.command === "-h") {
-        parsed.command = "help";
-    }
-    for (let index = 1; index < argv.length; index += 1) {
-        const arg = argv[index];
-        if (arg === "--root" || arg === "--workdir") {
-            const value = argv[index + 1];
-            if (!value)
-                throw new Error(`${arg} requires a value`);
-            parsed.root = value;
-            index += 1;
-            continue;
-        }
-        if (arg === "--dry-run") {
-            parsed.dryRun = true;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h") {
-            parsed.command = "help";
-            continue;
-        }
-        throw new Error(`Unknown argument: ${arg}`);
-    }
-    return parsed;
-}
-function helpText() {
-    return [
-        "litopencode",
-        "",
-        "Usage:",
-        "  litopencode doctor [--root <dir>]",
-        "  litopencode install --dry-run [--root <dir>]",
-        "",
-        "Commands:",
-        "  doctor        Report package, config, and runtime path status without writing files.",
-        "  install       Print the exact opencode.json mutation for adding this plugin."
-    ].join("\n");
-}
-async function readJsonObjectIfPresent(filePath) {
-    let raw;
-    try {
-        raw = await fs.readFile(filePath, "utf8");
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-    const parsed = JSON.parse(raw);
-    if (!isRecord(parsed)) {
-        throw new Error(`Malformed JSON at ${filePath}: expected an object.`);
-    }
-    return parsed;
-}
-function describePluginMutation(config) {
-    const pluginValue = config?.plugin;
-    const pluginIsArray = Array.isArray(pluginValue);
-    const alreadyPresent = pluginIsArray && pluginValue.includes("litopencode");
-    const currentCount = pluginIsArray ? pluginValue.length : 0;
-    if (alreadyPresent) {
-        return {
-            changed: false,
-            plugin: {
-                alreadyPresent: true,
-                currentCount,
-                resultCount: currentCount,
-                add: []
-            },
-            patch: []
-        };
-    }
-    const add = ["litopencode"];
-    const resultCount = currentCount + add.length;
-    if (pluginIsArray) {
-        return {
-            changed: true,
-            plugin: {
-                alreadyPresent: false,
-                currentCount,
-                resultCount,
-                add
-            },
-            patch: [{ op: "add", path: "/plugin/-", value: "litopencode" }]
-        };
-    }
-    const op = config !== null && Object.hasOwn(config, "plugin") ? "replace" : "add";
-    return {
-        changed: true,
-        plugin: {
-            alreadyPresent: false,
-            currentCount,
-            resultCount: 1,
-            add
-        },
-        patch: [{ op, path: "/plugin", value: ["litopencode"] }]
-    };
-}
-async function doctor(root) {
-    const metadata = await readPackageMetadata();
-    const loaded = await loadConfig(root);
-    const runtimeExists = await fs
-        .stat(loaded.paths.runtimeDir)
-        .then(() => true)
-        .catch((error) => {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return false;
-        throw error;
-    });
-    return {
-        exitCode: 0,
-        stdout: JSON.stringify({
-            package: metadata,
-            config: {
-                source: loaded.source,
-                path: loaded.paths.configFile,
-                enabled: loaded.config.enabled,
-                logLevel: loaded.config.logLevel
-            },
-            state: {
-                runtimeDir: loaded.paths.runtimeDir,
-                runtimeExists,
-                stateFile: loaded.paths.stateFile,
-                logFile: loaded.paths.logFile,
-                ledgerFile: loaded.paths.ledgerFile
-            }
-        }, null, 2)
-    };
-}
-async function install(root, dryRun) {
-    if (!dryRun) {
-        return {
-            exitCode: 2,
-            stderr: "litopencode install currently requires --dry-run; no files were written."
-        };
-    }
-    const paths = createRuntimePaths(root);
-    const before = await readJsonObjectIfPresent(paths.opencodeConfigFile);
-    const mutation = describePluginMutation(before);
-    return {
-        exitCode: 0,
-        stdout: JSON.stringify({
-            dryRun: true,
-            path: paths.opencodeConfigFile,
-            plugin: mutation.plugin,
-            patch: mutation.patch,
-            changed: mutation.changed
-        }, null, 2)
-    };
-}
+import { helpText, parseArgs } from "./cli/args.js";
+import { doctor } from "./cli/doctor.js";
+import { install } from "./cli/install.js";
+import { LitOpenCodeConfigError } from "./config.js";
 export async function runCli(argv = process.argv.slice(2)) {
     let parsed;
     try {

package/dist/features.js

@@ -112,7 +112,7 @@ export const litOpenCodeFeatures = Object.freeze([
     {
         id: "doctor-install",
         title: "Doctor And Installer CLI",
-        summary: "Reports package, config, and state health and previews the OpenCode plugin config mutation.",
+        summary: "Reports package, config, and state health and installs or previews the OpenCode plugin config mutation.",
         bindings: [
             {
                 kind: "cli",
@@ -122,9 +122,9 @@ export const litOpenCodeFeatures = Object.freeze([
             },
             {
                 kind: "cli",
-                id: "litopencode install --dry-run",
+                id: "npx litopencode install",
                 surface: "litopencode CLI install command",
-                description: "Prints the opencode.json plugin mutation without modifying the workspace."
+                description: "Adds litopencode to opencode.json with branded progress output; --dry-run prints the mutation only."
             }
         ],
         verification: ["node --test test/cli.test.mjs", "node --test test/config-state.test.mjs"]

package/dist/skills.js

@@ -35,11 +35,11 @@ export const litOpenCodeRuntimeSkills = Object.freeze([
     {
         id: "doctor-installer",
         title: "Doctor Installer",
-        summary: "Use the CLI to inspect health and preview plugin installation without writing files.",
+        summary: "Use the CLI to install the plugin into OpenCode or preview the plugin mutation without writing files.",
         featureIds: ["doctor-install"],
-        discovery: "Run litopencode doctor or litopencode install --dry-run.",
+        discovery: "Run npx litopencode install, litopencode doctor, or litopencode install --dry-run.",
         safety: [
-            "Default installation remains dry-run only.",
+            "Default installation writes only the OpenCode opencode.json plugin entry.",
             "Malformed config fails closed with a typed config error."
         ]
     },

package/docs/migration.md

@@ -13,8 +13,9 @@ This guide describes the supported migration shape for moving an OpenCode workfl
 - Use the `LITOPENCODE_` prefix for LitOpenCode-owned environment variables.
 - Keep OpenCode plugin configuration in `opencode.json`.
 - Keep LitOpenCode runtime config in `.litopencode/config.json` when project-local config is needed.
+- Use `npx litopencode install` to add `litopencode` to the default OpenCode config at `~/.config/opencode/opencode.json`.
 - Use `litopencode doctor --root <workspace>` to inspect package metadata, config source, runtime paths, and ledger location without writing files.
-- Use `litopencode install --dry-run --root <workspace>` to preview the `opencode.json` plugin mutation before applying it manually or through a future write-enabled installer.
+- Use `litopencode install --dry-run --root <workspace>` to preview the `opencode.json` plugin mutation without writing files.
 
 ## Durable State
 

package/docs/release-checklist.md

@@ -41,7 +41,7 @@ After the source gates pass, verify the packed artifact in a temporary directory
 ```sh
 tmp="$(mktemp -d)"
 npm pack --pack-destination "$tmp"
-tar -xzf "$tmp"/litopencode-0.0.0.tgz -C "$tmp"
+tar -xzf "$tmp"/litopencode-0.0.1.tgz -C "$tmp"
 node --input-type=module -e "import('$tmp/package/dist/index.js').then((m) => console.log(m.default?.id ?? m.pluginId))"
 (
   cd "$tmp/package"
@@ -73,21 +73,23 @@ mkdir "$tmp/consumer"
 (
   cd "$tmp/consumer"
   npm init -y
-  npm install "$tmp"/litopencode-0.0.0.tgz
-  npm ls litopencode @opencode-ai/plugin --all
+  npm install "$tmp"/litopencode-0.0.1.tgz
+  npm ls litopencode --all
   node --input-type=module -e "import('litopencode').then((m) => console.log(m.default.id))"
   node_modules/.bin/litopencode --help
   node_modules/.bin/litopencode doctor --root .
   node_modules/.bin/litopencode install --dry-run --root .
+  node_modules/.bin/litopencode install --root .
 )
 rm -rf "$tmp"
 ```
 
 Expected results:
 
-- `@opencode-ai/plugin` is installed as a runtime dependency below `litopencode`
+- `@opencode-ai/plugin` is declared as an optional peer for TypeScript host typings without forcing npx/global installs to pull its transitive runtime tree
 - package import prints `litopencode`
-- CLI help, doctor, and install dry-run exit 0
+- CLI help, doctor, install dry-run, and write-enabled install exit 0
+- write-enabled install creates or updates `opencode.json` without echoing unrelated config secrets
 - temporary project cleanup removes the probe directory
 
 ## OpenCode Host Probe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litopencode",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "LitOpenCode OpenCode plugin bootstrap package.",
   "type": "module",
   "bin": {
@@ -19,10 +19,16 @@
     "test": "node --test",
     "typecheck": "node tools/run-typecheck.mjs"
   },
-  "dependencies": {
+  "peerDependencies": {
     "@opencode-ai/plugin": "^1.17.6"
   },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.6",
     "@types/node": "^24.12.2",
     "typescript": "^5.9.3"
   }

package/skills/doctor-installer/SKILL.md

@@ -5,13 +5,15 @@ Use this LitOpenCode skill when a contributor needs the static CLI health and in
 ## Covers
 
 - Inspect package metadata, config source, runtime paths, and state presence.
-- Preview OpenCode plugin configuration changes without writing files.
+- Install the OpenCode plugin entry with a bounded branded terminal flow.
+- Preview OpenCode plugin configuration changes without writing files when `--dry-run` is set.
 - Keep malformed config handling fail-closed.
 - Keep installer output bounded and avoid leaking existing user config content.
 
 ## OpenCode Surfaces
 
 - CLI: `litopencode doctor`
+- CLI: `npx litopencode install`
 - CLI: `litopencode install --dry-run`
 - Runtime feature id: `doctor-install`
 
@@ -19,4 +21,4 @@ Use this LitOpenCode skill when a contributor needs the static CLI health and in
 
 - This file is static documentation.
 - Do not execute commands from this file automatically.
-- Treat dry-run output as a summary of intended mutation, not as a full config dump.
+- Treat installer output as a bounded summary, not as a full config dump.