@litfamily/litopencode 1.0.0

package/dist/tool-guards.d.ts

@@ -0,0 +1,34 @@
+import type { SessionLookup } from "./session-lineage.ts";
+export type LitOpenCodeToolId = "lit" | "litwork" | "start-work" | "review-work";
+export type LitOpenCodeToolAction = "activate" | "start" | "review" | "status";
+export type ToolGuardDecision = "allow" | "deny" | "ignore" | "post-processed";
+export type ToolGuardRequest = {
+    readonly tool: string;
+    readonly sessionID: string;
+    readonly callID: string;
+    readonly args?: unknown;
+};
+export type ToolGuardBeforeOutput = {
+    args?: unknown;
+};
+export type ToolGuardAfterOutput = {
+    title: string;
+    output: string;
+    metadata?: Record<string, unknown>;
+};
+export type ToolGuardMarker = {
+    readonly tool: LitOpenCodeToolId;
+    readonly action: LitOpenCodeToolAction | "deny";
+    readonly decision: ToolGuardDecision;
+};
+export declare function applyTaskRecursionGuard(input: ToolGuardRequest, getSession: SessionLookup | undefined): Promise<void>;
+export declare function applyLitOpenCodeToolBeforeHook(input: ToolGuardRequest, output: ToolGuardBeforeOutput): void;
+export type PostEditSkillRoute = {
+    readonly skillId: string;
+    readonly condition: string;
+    readonly line: string;
+};
+export declare function mutatedFilePaths(args: unknown): readonly string[];
+export declare function postEditSkillRoutes(filePaths: readonly string[]): readonly PostEditSkillRoute[];
+export declare function applyLitOpenCodePostEditHook(input: ToolGuardRequest, output: ToolGuardAfterOutput): void;
+export declare function applyLitOpenCodeToolAfterHook(input: ToolGuardRequest, output: ToolGuardAfterOutput): void;

package/dist/tool-guards.js

@@ -0,0 +1,210 @@
+import path from "node:path";
+import { serializeInertData } from "./inert-data.js";
+import { litOpenCodeRuntimeSkills } from "./skills.js";
+const managedToolIds = ["lit", "litwork", "start-work", "review-work"];
+const allowedActionsByTool = Object.freeze({
+    lit: ["activate", "status"],
+    litwork: ["start", "status"],
+    "start-work": ["start", "status"],
+    "review-work": ["review", "status"]
+});
+const defaultActionByTool = Object.freeze({
+    lit: "activate",
+    litwork: "start",
+    "start-work": "start",
+    "review-work": "review"
+});
+function isManagedTool(tool) {
+    return managedToolIds.some((candidate) => candidate === tool);
+}
+function isNonEmptyText(value) {
+    return value.trim().length > 0;
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readRawArgs(input, output) {
+    if (output.args !== undefined)
+        return output.args;
+    return input.args;
+}
+function actionFor(tool, value) {
+    if (value === undefined)
+        return defaultActionByTool[tool];
+    if (typeof value !== "string")
+        return undefined;
+    return allowedActionsByTool[tool].find((candidate) => candidate === value);
+}
+function deniedArgs(reason) {
+    return {
+        action: "deny",
+        reason
+    };
+}
+function allowedArgs(action) {
+    return { action };
+}
+function parseAfterAction(tool, args) {
+    if (isPlainRecord(args)) {
+        if (args.action === "deny")
+            return "deny";
+        const action = actionFor(tool, args.action);
+        if (action !== undefined)
+            return action;
+    }
+    return defaultActionByTool[tool];
+}
+// Delegation is depth-one by design: only the root session may call the task
+// tool. Config-level denies cover LitOpenCode agents, but this runtime guard is
+// the only layer that also covers host built-in agents and config overrides.
+export async function applyTaskRecursionGuard(input, getSession) {
+    if (input.tool !== "task")
+        return;
+    let lineage;
+    if (getSession === undefined) {
+        lineage = undefined;
+    }
+    else {
+        try {
+            lineage = await getSession(input.sessionID);
+        }
+        catch {
+            lineage = undefined;
+        }
+    }
+    // Fail closed: unknown lineage counts as a child session so a lookup outage
+    // can never reopen recursive delegation.
+    if (lineage === undefined || lineage.parentID !== undefined) {
+        throw new Error("LitOpenCode recursion guard: the task tool is reserved for the root session (depth-one fan-out). Complete this delegated assignment directly instead of spawning further subagents.");
+    }
+}
+export function applyLitOpenCodeToolBeforeHook(input, output) {
+    if (!isManagedTool(input.tool))
+        return;
+    if (!isNonEmptyText(input.sessionID) || !isNonEmptyText(input.callID)) {
+        output.args = deniedArgs("malformed LitOpenCode tool request");
+        return;
+    }
+    const rawArgs = readRawArgs(input, output);
+    if (rawArgs !== undefined && !isPlainRecord(rawArgs)) {
+        output.args = deniedArgs("invalid LitOpenCode tool arguments");
+        return;
+    }
+    const action = actionFor(input.tool, rawArgs?.action);
+    if (action === undefined) {
+        output.args = deniedArgs("invalid LitOpenCode tool action");
+        return;
+    }
+    output.args = allowedArgs(action);
+}
+// Extensions that carry code. Editing one of these is what makes a post-edit skill relevant at all.
+const sourceExtensions = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".rs", ".java", ".kt", ".rb", ".php",
+    ".swift", ".c", ".h", ".cc", ".cpp", ".cs", ".lua", ".sh", ".zig", ".ex", ".exs", ".dart", ".hs", ".jl"
+]);
+// Extensions and path segments that mean an interface surface changed.
+const interfaceExtensions = new Set([".css", ".scss", ".sass", ".less", ".html", ".htm", ".vue", ".svelte", ".astro", ".tsx", ".jsx"]);
+const interfaceSegments = ["/components/", "/ui/", "/styles/", "/pages/", "/app/"];
+// Two names is the ceiling: past that the block reads as boilerplate and gets skipped, which is the
+// exact failure mode a single unconditional post-edit sentence already produced.
+const postEditSkillCap = 2;
+const mutatedPathKeys = ["filePath", "path", "file_path"];
+function isInstalledRuntimeSkill(id) {
+    return litOpenCodeRuntimeSkills.some((skill) => skill.id === id);
+}
+function serializeInertPathData(filePaths) {
+    return filePaths.map(serializeInertData).join(", ");
+}
+export function mutatedFilePaths(args) {
+    if (!isPlainRecord(args))
+        return [];
+    const record = args;
+    for (const key of mutatedPathKeys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            return [value.trim()];
+    }
+    return [];
+}
+// Name only the skills whose trigger condition the edit actually met, and say which condition fired.
+// An edit that matches nothing stays silent: a generic sentence on every edit is what trains a reader
+// to ignore the surface entirely.
+export function postEditSkillRoutes(filePaths) {
+    const routePath = (filePath) => filePath.replaceAll("\\", "/");
+    const sourcePaths = filePaths.filter((filePath) => sourceExtensions.has(path.posix.extname(routePath(filePath)).toLowerCase()));
+    const interfacePaths = filePaths.filter((filePath) => {
+        const normalized = `/${routePath(filePath).toLowerCase()}`;
+        return interfaceExtensions.has(path.posix.extname(normalized)) || interfaceSegments.some((segment) => normalized.includes(segment));
+    });
+    if (sourcePaths.length === 0 && interfacePaths.length === 0)
+        return [];
+    const candidates = [];
+    if (interfacePaths.length > 0) {
+        candidates.push({
+            skillId: "frontend-ui-ux",
+            condition: "interface surface changed",
+            line: `Skill(frontend-ui-ux): an interface surface changed (inert path data: ${serializeInertPathData(interfacePaths)}).`
+        });
+        candidates.push({
+            skillId: "visual-qa",
+            condition: "interface surface changed",
+            line: "Skill(visual-qa): verify the changed interface with captured evidence before claiming it works."
+        });
+    }
+    if (sourcePaths.length > 0) {
+        candidates.push({
+            skillId: "comment-checker",
+            condition: "source file changed",
+            line: `Skill(comment-checker): check the comments added by this edit (inert path data: ${serializeInertPathData(sourcePaths)}).`
+        });
+        // The host edit and write tools mutate one path per call, so the single-file arm is what fires in
+        // practice; the multi-file arm stays reachable through postEditSkillRoutes for callers that batch.
+        candidates.push(sourcePaths.length === 1
+            ? {
+                skillId: "lit-burnoff-file",
+                condition: "exactly one source file changed",
+                line: `Skill(lit-burnoff-file): one source file changed (inert path data: ${serializeInertPathData(sourcePaths)}); clean it against its own diff.`
+            }
+            : {
+                skillId: "lit-burnoff",
+                condition: "several source files changed",
+                line: `Skill(lit-burnoff): ${sourcePaths.length} source files changed; clean them as one pass.`
+            });
+    }
+    // Naming a skill this package does not install is the same false promise as the generic sentence,
+    // so a row whose skill is absent from the runtime catalog stays dormant rather than pointing at
+    // nothing, and goes live automatically once that skill is added.
+    return candidates.filter((route) => isInstalledRuntimeSkill(route.skillId)).slice(0, postEditSkillCap);
+}
+// The only post-edit surface this plugin has: tool.execute.after for the host edit/write tools.
+export function applyLitOpenCodePostEditHook(input, output) {
+    if (input.tool !== "edit" && input.tool !== "write")
+        return;
+    if (!isNonEmptyText(input.sessionID) || !isNonEmptyText(input.callID))
+        return;
+    const routes = postEditSkillRoutes(mutatedFilePaths(input.args));
+    if (routes.length === 0)
+        return;
+    const block = routes.map((route) => route.line).join("\n");
+    output.output = isNonEmptyText(output.output) ? `${output.output}\n\n${block}` : block;
+    output.metadata = {
+        ...output.metadata,
+        litopencodePostEditSkills: routes.map((route) => ({ skillId: route.skillId, condition: route.condition }))
+    };
+}
+export function applyLitOpenCodeToolAfterHook(input, output) {
+    if (!isManagedTool(input.tool))
+        return;
+    if (!isNonEmptyText(input.sessionID) || !isNonEmptyText(input.callID))
+        return;
+    const action = parseAfterAction(input.tool, input.args);
+    const marker = {
+        tool: input.tool,
+        action,
+        decision: "post-processed"
+    };
+    output.metadata = {
+        ...output.metadata,
+        litopencodeToolGuard: marker
+    };
+}

package/dist/tool-kit.d.ts

@@ -0,0 +1,32 @@
+import type { ToolContext, ToolResult } from "@opencode-ai/plugin";
+type StringSchema = {
+    readonly type: "string";
+    readonly description?: string;
+    describe(description: string): StringSchema;
+    optional(): OptionalStringSchema;
+};
+type OptionalStringSchema = {
+    readonly type: "optional";
+    readonly innerType: StringSchema;
+};
+type ToolFactory = (<Args extends Record<string, unknown>>(input: {
+    readonly description: string;
+    readonly args: Args;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
+}) => {
+    readonly description: string;
+    readonly args: Args;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
+}) & {
+    readonly schema: {
+        string(): StringSchema;
+    };
+};
+export declare const tool: ToolFactory;
+export declare function projectRootFromContext(context: ToolContext): string;
+export declare function summarizeEventTypes(events: readonly {
+    readonly type: string;
+}[]): string;
+export declare function deniedToolResultFromArgs(args: Record<string, unknown>, command: string, allowedActions?: readonly string[]): ToolResult | undefined;
+export declare function actionFromArgs<T extends readonly string[]>(args: Record<string, unknown>, allowed: T, fallback: T[number]): T[number];
+export {};

package/dist/tool-kit.js

@@ -0,0 +1,75 @@
+function createFallbackStringSchema(description) {
+    return {
+        type: "string",
+        ...(description === undefined ? {} : { description }),
+        describe(nextDescription) {
+            return createFallbackStringSchema(nextDescription);
+        },
+        optional() {
+            return {
+                type: "optional",
+                innerType: createFallbackStringSchema(description)
+            };
+        }
+    };
+}
+function createFallbackToolFactory() {
+    const factory = ((input) => input);
+    Object.defineProperty(factory, "schema", {
+        value: {
+            string() {
+                return createFallbackStringSchema();
+            }
+        }
+    });
+    return factory;
+}
+async function loadToolFactory() {
+    try {
+        const plugin = await import("@opencode-ai/plugin");
+        if (typeof plugin.tool === "function") {
+            return plugin.tool;
+        }
+    }
+    catch {
+        // Packed-artifact import probes run before dependencies are installed.
+    }
+    return createFallbackToolFactory();
+}
+export const tool = await loadToolFactory();
+export function projectRootFromContext(context) {
+    const worktree = context.worktree?.trim();
+    if (worktree !== undefined && worktree !== "" && worktree !== "/")
+        return worktree;
+    const directory = context.directory?.trim();
+    if (directory !== undefined && directory !== "")
+        return directory;
+    return ".";
+}
+export function summarizeEventTypes(events) {
+    if (events.length === 0)
+        return "No ledger events recorded yet.";
+    return events.map((event, index) => `${index + 1}. ${event.type}`).join("\n");
+}
+export function deniedToolResultFromArgs(args, command, allowedActions = []) {
+    const explicitInvalidAction = args.action !== undefined && args.action !== "deny" && (typeof args.action !== "string" || !allowedActions.includes(args.action));
+    if (args.action !== "deny" && !explicitInvalidAction)
+        return undefined;
+    const rawReason = typeof args.reason === "string" ? args.reason.trim() : "";
+    const reason = rawReason.length > 0 ? rawReason : "invalid LitOpenCode tool action";
+    return {
+        title: `LitOpenCode ${command} blocked`,
+        output: `BLOCKED: ${reason}`,
+        metadata: {
+            command,
+            action: "deny",
+            blocked: true,
+            reason
+        }
+    };
+}
+export function actionFromArgs(args, allowed, fallback) {
+    if (typeof args.action !== "string")
+        return fallback;
+    return allowed.find((candidate) => candidate === args.action) ?? fallback;
+}

package/dist/tools.d.ts

@@ -0,0 +1,43 @@
+import type { ToolDefinition, ToolResult } from "@opencode-ai/plugin";
+export declare const litTool: ToolDefinition;
+export declare const litworkTool: ToolDefinition;
+export declare const startWorkTool: ToolDefinition;
+export declare const reviewWorkTool: ToolDefinition;
+export declare const wikifyTool: ToolDefinition;
+export declare const litOpenCodeTools: Readonly<{
+    lit: {
+        description: string;
+        args: Readonly<{
+            [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        }>;
+        execute(args: Record<string, unknown>, context: import("@opencode-ai/plugin").ToolContext): Promise<ToolResult>;
+    };
+    litwork: {
+        description: string;
+        args: Readonly<{
+            [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        }>;
+        execute(args: Record<string, unknown>, context: import("@opencode-ai/plugin").ToolContext): Promise<ToolResult>;
+    };
+    "start-work": {
+        description: string;
+        args: Readonly<{
+            [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        }>;
+        execute(args: Record<string, unknown>, context: import("@opencode-ai/plugin").ToolContext): Promise<ToolResult>;
+    };
+    "review-work": {
+        description: string;
+        args: Readonly<{
+            [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        }>;
+        execute(args: Record<string, unknown>, context: import("@opencode-ai/plugin").ToolContext): Promise<ToolResult>;
+    };
+    wikify: {
+        description: string;
+        args: Readonly<{
+            [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        }>;
+        execute(args: Record<string, unknown>, context: import("@opencode-ai/plugin").ToolContext): Promise<ToolResult>;
+    };
+}>;