litopencode 0.0.0

package/dist/cli.js

@@ -0,0 +1,204 @@
+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)
+    };
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    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 (parsed.command === "doctor")
+            return await doctor(parsed.root);
+        if (parsed.command === "install")
+            return await install(parsed.root, parsed.dryRun);
+        return { exitCode: 2, stderr: `Unknown command: ${parsed.command}` };
+    }
+    catch (error) {
+        const prefix = error instanceof LitOpenCodeConfigError ? "CONFIG_ERROR" : "ERROR";
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 1, stderr: `${prefix}: ${message}` };
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const result = await runCli(argv);
+    if (result.stdout)
+        process.stdout.write(`${result.stdout}\n`);
+    if (result.stderr)
+        process.stderr.write(`${result.stderr}\n`);
+    process.exitCode = result.exitCode;
+}

package/dist/commands.d.ts

@@ -0,0 +1,30 @@
+import type { Hooks } from "@opencode-ai/plugin";
+export type LitOpenCodeCommandId = "lit" | "litwork";
+export type LitOpenCodeCommand = {
+    readonly id: LitOpenCodeCommandId;
+    readonly slash: string;
+    readonly title: string;
+    readonly description: string;
+    readonly banner: string;
+    readonly activationText: string;
+};
+type CommandExecuteBeforeHook = NonNullable<Hooks["command.execute.before"]>;
+export declare const litActivationBanner = "LITWORK ACTIVE: LitOpenCode durable goal loop is ready under .litopencode/litgoal.";
+export declare const litOpenCodeCommands: readonly ({
+    id: "lit";
+    slash: string;
+    title: string;
+    description: string;
+    banner: string;
+    activationText: string;
+} | {
+    id: "litwork";
+    slash: string;
+    title: string;
+    description: string;
+    banner: string;
+    activationText: string;
+})[];
+export declare function findLitOpenCodeCommand(command: string): LitOpenCodeCommand | undefined;
+export declare function createCommandActivationHook(projectRoot: string): CommandExecuteBeforeHook;
+export {};

package/dist/commands.js

@@ -0,0 +1,59 @@
+import { createLitGoalOperations } from "./ledger.js";
+export const litActivationBanner = "LITWORK ACTIVE: LitOpenCode durable goal loop is ready under .litopencode/litgoal.";
+export const litOpenCodeCommands = Object.freeze([
+    {
+        id: "lit",
+        slash: "/lit",
+        title: "LitOpenCode",
+        description: "Activate the LitOpenCode workflow banner and durable goal loop.",
+        banner: litActivationBanner,
+        activationText: "LITWORK ACTIVE. Use the durable ledger for goal and loop progress, keep evidence attached to each step, and route implementation through the active LitOpenCode workflow."
+    },
+    {
+        id: "litwork",
+        slash: "/litwork",
+        title: "LitOpenCode Work Loop",
+        description: "Resume a LitOpenCode work loop with durable ledger-backed progress.",
+        banner: litActivationBanner,
+        activationText: "LITWORK RESUME. Continue from the durable ledger, preserve unrelated workspace changes, and verify each completed slice before advancing."
+    }
+]);
+export function findLitOpenCodeCommand(command) {
+    const normalized = command.trim().replace(/^\//, "").toLowerCase();
+    return litOpenCodeCommands.find((candidate) => candidate.id === normalized);
+}
+function summarizeCommandArguments(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return { present: false, redacted: false, length: 0 };
+    }
+    return { present: true, redacted: true, length: value.length };
+}
+export function createCommandActivationHook(projectRoot) {
+    const operations = createLitGoalOperations(projectRoot);
+    return async (input, output) => {
+        const command = findLitOpenCodeCommand(input.command);
+        if (!command)
+            return;
+        await operations.append({
+            type: "command.activated",
+            command: command.id,
+            arguments: summarizeCommandArguments(input.arguments),
+            sessionID: input.sessionID,
+            timestamp: new Date().toISOString()
+        });
+        output.parts.push({
+            id: `litopencode-${command.id}-activation`,
+            sessionID: input.sessionID,
+            messageID: `litopencode-${command.id}-activation`,
+            type: "text",
+            text: command.activationText,
+            synthetic: true,
+            metadata: {
+                litopencode: {
+                    command: command.id,
+                    banner: command.banner
+                }
+            }
+        });
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import { type RuntimePaths } from "./state.ts";
+export type LogLevel = "silent" | "error" | "info" | "debug";
+export type LitOpenCodeConfig = {
+    enabled: boolean;
+    logLevel: LogLevel;
+};
+export type LoadedConfig = {
+    config: LitOpenCodeConfig;
+    paths: RuntimePaths;
+    source: "defaults" | "file";
+};
+export declare class LitOpenCodeConfigError extends Error {
+    constructor(message: string);
+}
+export declare const defaultConfig: LitOpenCodeConfig;
+export declare function loadConfig(projectRoot: string): Promise<LoadedConfig>;

package/dist/config.js

@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import { createRuntimePaths } from "./state.js";
+export class LitOpenCodeConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LitOpenCodeConfigError";
+    }
+}
+export const defaultConfig = Object.freeze({
+    enabled: true,
+    logLevel: "info"
+});
+const logLevels = new Set(["silent", "error", "info", "debug"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseConfig(value, filePath) {
+    if (!isRecord(value)) {
+        throw new LitOpenCodeConfigError(`Malformed LitOpenCode config at ${filePath}: expected a JSON object.`);
+    }
+    const config = { ...defaultConfig };
+    if ("enabled" in value) {
+        if (typeof value.enabled !== "boolean") {
+            throw new LitOpenCodeConfigError(`Malformed LitOpenCode config at ${filePath}: enabled must be boolean.`);
+        }
+        config.enabled = value.enabled;
+    }
+    if ("logLevel" in value) {
+        if (typeof value.logLevel !== "string" || !logLevels.has(value.logLevel)) {
+            throw new LitOpenCodeConfigError(`Malformed LitOpenCode config at ${filePath}: logLevel must be one of silent, error, info, debug.`);
+        }
+        config.logLevel = value.logLevel;
+    }
+    return config;
+}
+export async function loadConfig(projectRoot) {
+    const paths = createRuntimePaths(projectRoot);
+    let raw;
+    try {
+        raw = await fs.readFile(paths.configFile, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return { config: { ...defaultConfig }, paths, source: "defaults" };
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "invalid JSON";
+        throw new LitOpenCodeConfigError(`Malformed LitOpenCode config at ${paths.configFile}: ${reason}`);
+    }
+    return {
+        config: parseConfig(parsed, paths.configFile),
+        paths,
+        source: "file"
+    };
+}

package/dist/features.d.ts

@@ -0,0 +1,108 @@
+export type LitOpenCodeBindingKind = "agent" | "cli" | "command" | "config" | "hook" | "tool";
+export type LitOpenCodeFeatureId = "planning-start-work-loop" | "lit-litwork-activation" | "durable-ledger" | "agent-roster" | "doctor-install" | "guardrails";
+export type LitOpenCodeFeatureBinding = {
+    readonly kind: LitOpenCodeBindingKind;
+    readonly id: string;
+    readonly surface: string;
+    readonly description: string;
+};
+export type LitOpenCodeFeature = {
+    readonly id: LitOpenCodeFeatureId;
+    readonly title: string;
+    readonly summary: string;
+    readonly bindings: readonly LitOpenCodeFeatureBinding[];
+    readonly verification: readonly string[];
+};
+export declare const litOpenCodeFeatures: readonly ({
+    id: "planning-start-work-loop";
+    title: string;
+    summary: string;
+    bindings: ({
+        kind: "command";
+        id: string;
+        surface: string;
+        description: string;
+    } | {
+        kind: "agent";
+        id: string;
+        surface: string;
+        description: string;
+    })[];
+    verification: string[];
+} | {
+    id: "lit-litwork-activation";
+    title: string;
+    summary: string;
+    bindings: ({
+        kind: "command";
+        id: string;
+        surface: string;
+        description: string;
+    } | {
+        kind: "tool";
+        id: string;
+        surface: string;
+        description: string;
+    } | {
+        kind: "hook";
+        id: string;
+        surface: string;
+        description: string;
+    })[];
+    verification: string[];
+} | {
+    id: "durable-ledger";
+    title: string;
+    summary: string;
+    bindings: ({
+        kind: "tool";
+        id: string;
+        surface: string;
+        description: string;
+    } | {
+        kind: "config";
+        id: string;
+        surface: string;
+        description: string;
+    })[];
+    verification: string[];
+} | {
+    id: "agent-roster";
+    title: string;
+    summary: string;
+    bindings: ({
+        kind: "hook";
+        id: string;
+        surface: string;
+        description: string;
+    } | {
+        kind: "agent";
+        id: string;
+        surface: string;
+        description: string;
+    })[];
+    verification: string[];
+} | {
+    id: "doctor-install";
+    title: string;
+    summary: string;
+    bindings: {
+        kind: "cli";
+        id: string;
+        surface: string;
+        description: string;
+    }[];
+    verification: string[];
+} | {
+    id: "guardrails";
+    title: string;
+    summary: string;
+    bindings: {
+        kind: "cli";
+        id: string;
+        surface: string;
+        description: string;
+    }[];
+    verification: string[];
+})[];
+export declare function findLitOpenCodeFeature(id: string): LitOpenCodeFeature | undefined;

package/dist/features.js

@@ -0,0 +1,161 @@
+export const litOpenCodeFeatures = Object.freeze([
+    {
+        id: "planning-start-work-loop",
+        title: "Planning And Work Loop",
+        summary: "Coordinates plan-first work, scoped implementation, independent verification, and evidence-backed progress.",
+        bindings: [
+            {
+                kind: "command",
+                id: "litwork",
+                surface: "OpenCode command /litwork",
+                description: "Resumes the work loop and writes a command activation event to the durable ledger."
+            },
+            {
+                kind: "agent",
+                id: "lit-plan",
+                surface: "OpenCode agent lit-plan",
+                description: "Provides the primary planning surface for executable, verified work slices."
+            },
+            {
+                kind: "agent",
+                id: "lit-loop",
+                surface: "OpenCode agent lit-loop",
+                description: "Provides the primary execution-loop surface for scoped edits and command-backed delivery."
+            }
+        ],
+        verification: ["node --test test/litwork.test.mjs", "node --test test/agent-roster.test.mjs"]
+    },
+    {
+        id: "lit-litwork-activation",
+        title: "Lit Activation Surface",
+        summary: "Exposes LitOpenCode activation through command and tool surfaces backed by observable ledger events.",
+        bindings: [
+            {
+                kind: "command",
+                id: "lit",
+                surface: "OpenCode command /lit",
+                description: "Activates the workflow banner and records command activation."
+            },
+            {
+                kind: "tool",
+                id: "lit",
+                surface: "OpenCode tool lit",
+                description: "Initializes the runtime ledger and reports status."
+            },
+            {
+                kind: "tool",
+                id: "litwork",
+                surface: "OpenCode tool litwork",
+                description: "Starts or inspects the current work loop through durable ledger operations."
+            },
+            {
+                kind: "hook",
+                id: "command.execute.before",
+                surface: "OpenCode hook command.execute.before",
+                description: "Injects activation text before supported slash commands execute."
+            }
+        ],
+        verification: ["node --test test/litwork.test.mjs"]
+    },
+    {
+        id: "durable-ledger",
+        title: "Durable LitGoal Ledger",
+        summary: "Persists loop events under .litopencode/litgoal with atomic writes and temp-file recovery.",
+        bindings: [
+            {
+                kind: "tool",
+                id: "litwork.status",
+                surface: "OpenCode tool litwork action=status",
+                description: "Reads durable ledger events for status output."
+            },
+            {
+                kind: "config",
+                id: ".litopencode/litgoal",
+                surface: "litopencode runtime state path",
+                description: "Owns the durable ledger directory used by commands, tools, and goal operations."
+            }
+        ],
+        verification: ["node --test test/ledger.test.mjs", "node --test test/litwork.test.mjs"]
+    },
+    {
+        id: "agent-roster",
+        title: "Agent Roster",
+        summary: "Registers the two primary LitOpenCode agents, recommended role aliases, and specialist roster as static OpenCode agent definitions.",
+        bindings: [
+            {
+                kind: "hook",
+                id: "config",
+                surface: "OpenCode config hook",
+                description: "Merges LitOpenCode agent definitions into the host config without overwriting existing agents."
+            },
+            {
+                kind: "agent",
+                id: "primary-defaults",
+                surface: "OpenCode agent registry",
+                description: "Provides the lit-plan and lit-loop primary default agents."
+            },
+            {
+                kind: "agent",
+                id: "recommended-roles",
+                surface: "OpenCode agent registry",
+                description: "Provides architect, forge, oracle, prover, sentinel, and librarian role aliases."
+            },
+            {
+                kind: "agent",
+                id: "specialists",
+                surface: "OpenCode agent registry",
+                description: "Provides the adapted specialist set for advanced discovery, review, planning, and persistence."
+            }
+        ],
+        verification: ["node --test test/agent-roster.test.mjs"]
+    },
+    {
+        id: "doctor-install",
+        title: "Doctor And Installer CLI",
+        summary: "Reports package, config, and state health and previews the OpenCode plugin config mutation.",
+        bindings: [
+            {
+                kind: "cli",
+                id: "litopencode doctor",
+                surface: "litopencode CLI doctor command",
+                description: "Reports package metadata, config source, runtime paths, and state presence without writes."
+            },
+            {
+                kind: "cli",
+                id: "litopencode install --dry-run",
+                surface: "litopencode CLI install command",
+                description: "Prints the opencode.json plugin mutation without modifying the workspace."
+            }
+        ],
+        verification: ["node --test test/cli.test.mjs", "node --test test/config-state.test.mjs"]
+    },
+    {
+        id: "guardrails",
+        title: "Release Guardrails",
+        summary: "Keeps release-sensitive checks visible through npm-script and CI gates before package publication work.",
+        bindings: [
+            {
+                kind: "cli",
+                id: "npm run scan:legacy-tokens",
+                surface: "npm guard command",
+                description: "Fails on guarded vocabulary unless an exact line-level exception is documented."
+            },
+            {
+                kind: "cli",
+                id: "npm run check:version",
+                surface: "npm guard command",
+                description: "Verifies package metadata and lockfile version lockstep."
+            },
+            {
+                kind: "cli",
+                id: "npm run check:pack-payload",
+                surface: "npm guard command",
+                description: "Verifies the dry pack manifest excludes local state, evidence, archives, and fixtures."
+            }
+        ],
+        verification: ["npm run scan:legacy-tokens", "npm run check:version", "npm run check:pack-payload"]
+    }
+]);
+export function findLitOpenCodeFeature(id) {
+    return litOpenCodeFeatures.find((feature) => feature.id === id);
+}

package/dist/hooks.d.ts

@@ -0,0 +1,6 @@
+import type { Hooks } from "@opencode-ai/plugin";
+type ToolExecuteBeforeHook = NonNullable<Hooks["tool.execute.before"]>;
+type ToolExecuteAfterHook = NonNullable<Hooks["tool.execute.after"]>;
+export declare function createToolExecuteBeforeHook(): ToolExecuteBeforeHook;
+export declare function createToolExecuteAfterHook(): ToolExecuteAfterHook;
+export {};

package/dist/hooks.js

@@ -0,0 +1,11 @@
+import { applyLitOpenCodeToolAfterHook, applyLitOpenCodeToolBeforeHook } from "./tool-guards.js";
+export function createToolExecuteBeforeHook() {
+    return async (input, output) => {
+        applyLitOpenCodeToolBeforeHook(input, output);
+    };
+}
+export function createToolExecuteAfterHook() {
+    return async (input, output) => {
+        applyLitOpenCodeToolAfterHook(input, output);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+export { appendLedgerEvent, createLitGoalOperations, initializeLitGoal, readLedgerEvents, recoverLedgerTemps, LedgerIoError, LedgerParseError, type JsonValue, type LedgerAppendResult, type LedgerEvent, type LedgerRecoveryReport, type LitGoalInitialization, type LitGoalOperations } from "./ledger.ts";
+export { litActivationBanner, litOpenCodeCommands } from "./commands.ts";
+export { createToolExecuteAfterHook, createToolExecuteBeforeHook } from "./hooks.ts";
+export { applyLitOpenCodeToolAfterHook, applyLitOpenCodeToolBeforeHook, type LitOpenCodeToolAction, type LitOpenCodeToolId, type ToolGuardAfterOutput, type ToolGuardBeforeOutput, type ToolGuardDecision, type ToolGuardMarker, type ToolGuardRequest } from "./tool-guards.ts";
+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: {
+    id: string;
+    server: (input?: PluginInput) => Promise<Hooks>;
+};
+export default pluginModule;