litopencode 0.0.1 → 0.0.3

package/README.md

@@ -34,7 +34,7 @@
 
     npx litopencode install
 
-Then restart OpenCode. The agent switcher should show <code>lit-plan</code> and <code>lit-loop</code>.
+The installer delegates the default install path to OpenCode's own plugin installer and registers a version-pinned entry such as <code>litopencode@0.0.3</code>. 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>:
 
@@ -72,7 +72,7 @@ By default, the installer targets <code>~/.config/opencode/opencode.json</code>,
 
 ## OpenCode Plugin
 
-The default export is an OpenCode <code>PluginModule</code>. The packed artifact exports compiled JavaScript from <code>dist/index.js</code>, so installed npm consumers do not rely on Node's TypeScript stripping behavior for files under <code>node_modules</code>.
+The default export is an OpenCode plugin function, and <code>litopencode/server</code> points at the same compiled server entrypoint for OpenCode's plugin installer. The packed artifact exports compiled JavaScript from <code>dist/index.js</code>, so installed npm consumers do not rely on Node's TypeScript stripping behavior for files under <code>node_modules</code>.
 
 The server surface registers:
 

package/dist/cli/install.js

@@ -1,12 +1,63 @@
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
+import { promisify } from "node:util";
 import { createRuntimePaths } from "../state.js";
 import { readJsonObjectIfPresent, readPackageMetadata } from "./json.js";
-const pluginId = "litopencode";
-function describePluginMutation(config) {
+const pluginName = "litopencode";
+const reset = "\u001b[0m";
+const execFileAsync = promisify(execFile);
+function useColor() {
+    return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+}
+function tint(value, code) {
+    if (!useColor())
+        return value;
+    return code + value + reset;
+}
+function padLabel(label) {
+    return label.padEnd(24, " ");
+}
+function headerLine(value, code) {
+    return "| " + tint(value.padEnd(58, " "), code) + " |";
+}
+function pluginSpec(metadata) {
+    return metadata.name + "@" + metadata.version;
+}
+function isLitOpenCodeEntry(value) {
+    return typeof value === "string" && (value === pluginName || value.startsWith(pluginName + "@"));
+}
+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");
+}
+function shouldUseOpenCodeInstaller(root) {
+    return path.resolve(root) === path.resolve(defaultOpenCodeRoot());
+}
+async function installWithOpenCode(target) {
+    try {
+        await execFileAsync("opencode", ["plugin", target, "--global", "--force"], {
+            timeout: 120_000,
+            maxBuffer: 1024 * 1024 * 4
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error && "stderr" in error && typeof error.stderr === "string"
+            ? error.stderr.trim()
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        throw new Error("OpenCode plugin install failed for " + target + (detail ? ":\n" + detail : ""));
+    }
+}
+function describePluginMutation(config, target) {
     const pluginValue = config?.plugin;
     const pluginIsArray = Array.isArray(pluginValue);
-    const alreadyPresent = pluginIsArray && pluginValue.includes(pluginId);
+    const existingIndex = pluginIsArray ? pluginValue.findIndex(isLitOpenCodeEntry) : -1;
+    const alreadyPresent = pluginIsArray && pluginValue.includes(target);
     const currentCount = pluginIsArray ? pluginValue.length : 0;
     if (alreadyPresent) {
         return {
@@ -15,56 +66,78 @@ function describePluginMutation(config) {
             patch: []
         };
     }
-    const add = [pluginId];
+    const add = [target];
     if (pluginIsArray) {
+        if (existingIndex >= 0) {
+            return {
+                changed: true,
+                plugin: { alreadyPresent: true, currentCount, resultCount: currentCount, add },
+                patch: [{ op: "replace", path: `/plugin/${existingIndex}`, value: target }]
+            };
+        }
         return {
             changed: true,
             plugin: { alreadyPresent: false, currentCount, resultCount: currentCount + 1, add },
-            patch: [{ op: "add", path: "/plugin/-", value: pluginId }]
+            patch: [{ op: "add", path: "/plugin/-", value: target }]
         };
     }
     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] }]
+        patch: [{ op, path: "/plugin", value: [target] }]
     };
 }
-function applyPluginMutation(config, mutation) {
+function applyPluginMutation(config, mutation, target) {
     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];
+        const existingIndex = pluginValue.findIndex(isLitOpenCodeEntry);
+        if (existingIndex >= 0) {
+            next.plugin = pluginValue.map((value, index) => (index === existingIndex ? target : value));
+            return next;
+        }
+        next.plugin = [...pluginValue, target];
         return next;
     }
-    next.plugin = [pluginId];
+    next.plugin = [target];
     return next;
 }
 function renderInstallReport(report) {
     const status = report.changed ? "Complete" : "Already installed";
-    const action = report.changed ? "Added litopencode to plugin[]" : "No config change needed";
+    const action = report.changed ? "plugin[] updated" : "no write needed";
+    const ok = tint("ok", "\u001b[38;5;82m");
     return [
-        "LitOpenCode Installer",
-        "=====================",
+        "+------------------------------------------------------------+",
+        headerLine("LitOpenCode", "\u001b[1;38;5;81m"),
+        headerLine("OpenCode plugin installer", "\u001b[38;5;245m"),
+        "+------------------------------------------------------------+",
+        "",
+        "  " + padLabel("Package") + " " + report.package.name + "@" + report.package.version,
+        "  " + padLabel("Config") + " " + report.path,
+        "  " + padLabel("Plugin entries") + " " + report.plugin.currentCount + " -> " + report.plugin.resultCount,
         "",
-        "[-] 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,
+        "  [1/4] " + padLabel("Resolve package") + " " + ok,
+        "  [2/4] " + padLabel("Read OpenCode config") + " " + ok,
+        "  [3/4] " + padLabel("Register plugin") + " " + ok,
+        "  [4/4] " + padLabel("Verify install") + " " + ok,
         "",
-        status,
+        "  Status   " + status,
+        "  Result   " + action,
         "",
-        "Next:",
-        "  Restart OpenCode and press tab to switch between lit-plan and lit-loop."
+        "  Next",
+        "  Restart OpenCode, then press Tab.",
+        "  Agents: lit-plan / 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 target = pluginSpec(metadata);
+    const mutation = describePluginMutation(before, target);
     const report = {
         dryRun,
         path: paths.opencodeConfigFile,
@@ -76,8 +149,11 @@ export async function install(root, dryRun) {
     if (dryRun) {
         return { exitCode: 0, stdout: JSON.stringify(report, null, 2) };
     }
-    if (mutation.changed) {
-        const next = applyPluginMutation(before, mutation);
+    if (shouldUseOpenCodeInstaller(root)) {
+        await installWithOpenCode(target);
+    }
+    else if (mutation.changed) {
+        const next = applyPluginMutation(before, mutation, target);
         await fs.mkdir(path.dirname(paths.opencodeConfigFile), { recursive: true });
         await fs.writeFile(paths.opencodeConfigFile, JSON.stringify(next, null, 2) + "\n");
     }

package/dist/cli/types.d.ts

@@ -15,15 +15,19 @@ export type ParsedArgs = {
 export type JsonPatchOperation = {
     readonly op: "add";
     readonly path: "/plugin";
-    readonly value: readonly ["litopencode"];
+    readonly value: readonly string[];
 } | {
     readonly op: "replace";
     readonly path: "/plugin";
-    readonly value: readonly ["litopencode"];
+    readonly value: readonly string[];
 } | {
     readonly op: "add";
     readonly path: "/plugin/-";
-    readonly value: "litopencode";
+    readonly value: string;
+} | {
+    readonly op: "replace";
+    readonly path: `/plugin/${number}`;
+    readonly value: string;
 };
 export type PluginMutation = {
     readonly changed: boolean;

package/dist/cli.js

@@ -2,6 +2,32 @@ import { helpText, parseArgs } from "./cli/args.js";
 import { doctor } from "./cli/doctor.js";
 import { install } from "./cli/install.js";
 import { LitOpenCodeConfigError } from "./config.js";
+const installFrames = [
+    { bar: "[##........]", label: "resolving litopencode package" },
+    { bar: "[####......]", label: "opening OpenCode config" },
+    { bar: "[######....]", label: "patching plugin registry" },
+    { bar: "[########..]", label: "checking lit-plan / lit-loop" },
+    { bar: "[##########]", label: "sealing installer state" }
+];
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function shouldAnimateInstall(argv, result) {
+    return (process.stdout.isTTY === true &&
+        process.env.CI === undefined &&
+        argv[0] === "install" &&
+        !argv.includes("--dry-run") &&
+        result.exitCode === 0 &&
+        result.stdout !== undefined);
+}
+async function renderInstallEffect() {
+    process.stdout.write("\n");
+    for (const frame of installFrames) {
+        process.stdout.write("\r\u001b[2K  " + frame.bar + " " + frame.label);
+        await sleep(95);
+    }
+    process.stdout.write("\r\u001b[2K");
+}
 export async function runCli(argv = process.argv.slice(2)) {
     let parsed;
     try {
@@ -29,6 +55,8 @@ export async function runCli(argv = process.argv.slice(2)) {
 }
 export async function main(argv = process.argv.slice(2)) {
     const result = await runCli(argv);
+    if (shouldAnimateInstall(argv, result))
+        await renderInstallEffect();
     if (result.stdout)
         process.stdout.write(`${result.stdout}\n`);
     if (result.stderr)

package/dist/features.js

@@ -124,7 +124,7 @@ export const litOpenCodeFeatures = Object.freeze([
                 kind: "cli",
                 id: "npx litopencode install",
                 surface: "litopencode CLI install command",
-                description: "Adds litopencode to opencode.json with branded progress output; --dry-run prints the mutation only."
+                description: "Delegates default setup to OpenCode's plugin installer, or adds a version-pinned litopencode entry for custom roots; --dry-run prints the mutation only."
             }
         ],
         verification: ["node --test test/cli.test.mjs", "node --test test/config-state.test.mjs"]

package/dist/index.d.ts

@@ -7,9 +7,9 @@ export { litOpenCodeTools, litTool, litworkTool } from "./tools.ts";
 export { findLitOpenCodeFeature, litOpenCodeFeatures, type LitOpenCodeBindingKind, type LitOpenCodeFeature, type LitOpenCodeFeatureBinding, type LitOpenCodeFeatureId } from "./features.ts";
 export { findLitOpenCodeRuntimeSkill, litOpenCodeRuntimeSkills, type LitOpenCodeRuntimeSkill, type LitOpenCodeRuntimeSkillId } from "./skills.ts";
 export declare const pluginId = "litopencode";
-export declare const server: (input?: PluginInput) => Promise<Hooks>;
-declare const pluginModule: {
+declare const litOpenCodePlugin: (input?: PluginInput) => Promise<Hooks>;
+export declare const pluginModule: {
     id: string;
     server: (input?: PluginInput) => Promise<Hooks>;
 };
-export default pluginModule;
+export default litOpenCodePlugin;

package/dist/index.js

@@ -12,7 +12,7 @@ export { litOpenCodeTools, litTool, litworkTool } from "./tools.js";
 export { findLitOpenCodeFeature, litOpenCodeFeatures } from "./features.js";
 export { findLitOpenCodeRuntimeSkill, litOpenCodeRuntimeSkills } from "./skills.js";
 export const pluginId = "litopencode";
-export const server = async (input) => {
+const litOpenCodePlugin = async (input) => {
     const root = input?.worktree ?? input?.directory ?? ".";
     const loaded = await loadConfig(root);
     const logger = createLogger(loaded.paths);
@@ -38,8 +38,8 @@ export const server = async (input) => {
     });
     return hooks;
 };
-const pluginModule = {
+export const pluginModule = {
     id: pluginId,
-    server
+    server: litOpenCodePlugin
 };
-export default pluginModule;
+export default litOpenCodePlugin;

package/dist/skills.js

@@ -39,7 +39,7 @@ export const litOpenCodeRuntimeSkills = Object.freeze([
         featureIds: ["doctor-install"],
         discovery: "Run npx litopencode install, litopencode doctor, or litopencode install --dry-run.",
         safety: [
-            "Default installation writes only the OpenCode opencode.json plugin entry.",
+            "Default installation delegates to the OpenCode plugin installer; custom roots write only the version-pinned opencode.json plugin entry.",
             "Malformed config fails closed with a typed config error."
         ]
     },

package/docs/migration.md

@@ -13,7 +13,7 @@ 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 `npx litopencode install` to delegate default setup to `opencode plugin litopencode@0.0.3 --global --force` and register the version-pinned plugin entry.
 - 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 without writing files.
 

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.1.tgz -C "$tmp"
+tar -xzf "$tmp"/litopencode-0.0.3.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,7 +73,7 @@ mkdir "$tmp/consumer"
 (
   cd "$tmp/consumer"
   npm init -y
-  npm install "$tmp"/litopencode-0.0.1.tgz
+  npm install "$tmp"/litopencode-0.0.3.tgz
   npm ls litopencode --all
   node --input-type=module -e "import('litopencode').then((m) => console.log(m.default.id))"
   node_modules/.bin/litopencode --help
@@ -94,7 +94,7 @@ Expected results:
 
 ## OpenCode Host Probe
 
-Use the installed temp-project package, not the source tree, to import `litopencode`, call the default plugin module\'s `server()` function, invoke the config hook, command hook, `lit` and `litwork` tools, and before/after tool guard hooks. Expected results:
+Use the installed temp-project package, not the source tree, to import `litopencode`, import `litopencode/server`, call the plugin function, invoke the config hook, command hook, `lit` and `litwork` tools, and before/after tool guard hooks. Expected results:
 
 - `server()` exposes config, tool, command activation, dispose, and non-enumerable tool guard hooks
 - config registers the LitOpenCode agent roster

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litopencode",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "LitOpenCode OpenCode plugin bootstrap package.",
   "type": "module",
   "bin": {
@@ -8,7 +8,14 @@
   },
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "build": "node tools/run-build.mjs",

package/skills/doctor-installer/SKILL.md

@@ -5,7 +5,7 @@ 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.
-- Install the OpenCode plugin entry with a bounded branded terminal flow.
+- Install or update the version-pinned OpenCode plugin through the OpenCode plugin installer 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.