@litfamily/litopencode 1.0.0

package/dist/skill-loop/proposals.js

@@ -0,0 +1,290 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { containsIngressSecret } from "../secret-shapes.js";
+import { decodeStrictUtf8, parseStrictJson } from "../strict-json.js";
+import { resolveSkillLoopPaths, skillLoopPaths, writeJsonAtomically } from "./config.js";
+import { assertSafeRuntimeFileForWrite, assertSkillLoopLockCapability, ensureSafeRuntimeDirectory, readSafeRuntimeFile, withSkillLoopMutationLock } from "./storage.js";
+import { isStrictRfc3339 } from "./time.js";
+export class SkillProposalError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.name = "SkillProposalError";
+        this.code = code;
+    }
+}
+export const proposalLimit = 64 * 1024;
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const skillPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const portableDevice = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
+const portableForbidden = /[\\:*?"<>|\u0000-\u001f\u007f-\u009f]/u;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, allowed) {
+    const set = new Set(allowed);
+    if (Object.keys(value).some((key) => !set.has(key)))
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+}
+function requiredString(value, max, pattern) {
+    if (typeof value !== "string" || value.length === 0 || value.length > max || (pattern && !pattern.test(value))) {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    return value;
+}
+function validTimestamp(value) {
+    const text = requiredString(value, 64);
+    if (!isStrictRfc3339(text))
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    return text;
+}
+export function canonicalRelativeIdentity(file) {
+    return file.split("/").map((segment) => segment.normalize("NFKC").toLocaleLowerCase("en-US").replace(/[. ]+$/u, "")).join("/");
+}
+export function assertPortableRelativeFile(file, targetSkill) {
+    const text = requiredString(file, 1024);
+    if (path.posix.isAbsolute(text) || /^[A-Za-z]:/u.test(text) || text.startsWith("//") || portableForbidden.test(text) ||
+        text.includes("//") || text.split("/").some((part) => part === "" || part === "." || part === ".." || /[. ]$/u.test(part) || portableDevice.test(part))) {
+        throw new SkillProposalError("PROPOSAL_PATH_INVALID");
+    }
+    const identity = canonicalRelativeIdentity(text);
+    if (targetSkill !== undefined) {
+        const targetIdentity = canonicalRelativeIdentity(targetSkill);
+        if (identity === targetIdentity || identity.startsWith(`${targetIdentity}/`)) {
+            throw new SkillProposalError("PROPOSAL_PATH_INVALID");
+        }
+    }
+    return text;
+}
+function assertNoSecrets(value) {
+    if (typeof value === "string") {
+        if (containsIngressSecret(value))
+            throw new SkillProposalError("PROPOSAL_SECRET_REFUSED");
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            assertNoSecrets(entry);
+        return;
+    }
+    if (isRecord(value))
+        for (const entry of Object.values(value))
+            assertNoSecrets(entry);
+}
+export function parseSkillProposal(value, expectedSkillsRoot) {
+    if (!isRecord(value))
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    exactKeys(value, ["schema", "id", "createdAt", "host", "sessionRef", "signal", "targetSkill", "targetRoot", "action", "patch", "createSpec", "rationale", "evidenceRefs", "status", "ledgerEntryId"]);
+    assertNoSecrets(value);
+    if (value.schema !== "litfamily.skill-proposal/v1" || value.host !== "litopencode") {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    const targetSkill = requiredString(value.targetSkill, 128, skillPattern);
+    try {
+        if (assertPortableRelativeFile(targetSkill) !== targetSkill || targetSkill.includes("/"))
+            throw new Error("invalid");
+    }
+    catch {
+        throw new SkillProposalError("PROPOSAL_PATH_INVALID");
+    }
+    const status = value.status;
+    if (status !== "pending" && status !== "approved" && status !== "applied" && status !== "rejected" && status !== "rolled-back") {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    const action = value.action;
+    if (action !== "patch" && action !== "create" && action !== "add-reference" && action !== "archive") {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    const targetRootInput = requiredString(value.targetRoot, 2048);
+    const targetRoot = targetRootInput === "$OPENCODE_SKILLS_ROOT" && expectedSkillsRoot !== undefined
+        ? path.resolve(expectedSkillsRoot)
+        : path.resolve(targetRootInput);
+    if (expectedSkillsRoot !== undefined && targetRoot !== path.resolve(expectedSkillsRoot)) {
+        throw new SkillProposalError("PROPOSAL_TARGET_ROOT_MISMATCH");
+    }
+    let patch;
+    let createSpec;
+    if (action === "patch") {
+        if (!isRecord(value.patch) || value.createSpec !== undefined)
+            throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+        exactKeys(value.patch, ["file", "oldString", "newString"]);
+        patch = {
+            file: assertPortableRelativeFile(value.patch.file, targetSkill),
+            oldString: requiredString(value.patch.oldString, 65536),
+            newString: typeof value.patch.newString === "string" && value.patch.newString.length <= 65536
+                ? value.patch.newString
+                : (() => { throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID"); })()
+        };
+    }
+    else if (action === "create" || action === "add-reference") {
+        if (!isRecord(value.createSpec) || value.patch !== undefined)
+            throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+        exactKeys(value.createSpec, ["files"]);
+        if (!Array.isArray(value.createSpec.files) || value.createSpec.files.length < 1 || value.createSpec.files.length > 64) {
+            throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+        }
+        const identities = new Set();
+        const files = value.createSpec.files.map((entry) => {
+            if (!isRecord(entry))
+                throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+            exactKeys(entry, ["file", "content"]);
+            const file = assertPortableRelativeFile(entry.file, targetSkill);
+            const identity = canonicalRelativeIdentity(file);
+            if (identities.has(identity))
+                throw new SkillProposalError("PROPOSAL_PATH_INVALID");
+            identities.add(identity);
+            if (typeof entry.content !== "string" || entry.content.length > 65536)
+                throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+            return { file, content: entry.content };
+        });
+        createSpec = { files };
+    }
+    else if (value.patch !== undefined || value.createSpec !== undefined) {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    const evidenceRefs = value.evidenceRefs;
+    if (!Array.isArray(evidenceRefs) || evidenceRefs.length > 32 || evidenceRefs.some((entry) => typeof entry !== "string" || entry.length < 1 || entry.length > 2048) || new Set(evidenceRefs).size !== evidenceRefs.length) {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    const ledgerEntryId = value.ledgerEntryId;
+    if ((status === "applied" || status === "rolled-back") !== (typeof ledgerEntryId === "string" && ledgerEntryId.length > 0 && ledgerEntryId.length <= 128)) {
+        throw new SkillProposalError("PROPOSAL_SCHEMA_INVALID");
+    }
+    if (typeof ledgerEntryId === "string") {
+        try {
+            if (!idPattern.test(ledgerEntryId) || assertPortableRelativeFile(ledgerEntryId) !== ledgerEntryId)
+                throw new Error("invalid");
+        }
+        catch {
+            throw new SkillProposalError("PROPOSAL_INTEGRITY_INVALID");
+        }
+    }
+    return Object.freeze({
+        schema: "litfamily.skill-proposal/v1",
+        id: (() => {
+            const id = requiredString(value.id, 128, idPattern);
+            try {
+                if (assertPortableRelativeFile(id) !== id || id.includes("/"))
+                    throw new Error("invalid");
+            }
+            catch {
+                throw new SkillProposalError("PROPOSAL_PATH_INVALID");
+            }
+            return id;
+        })(),
+        createdAt: validTimestamp(value.createdAt),
+        host: "litopencode",
+        sessionRef: requiredString(value.sessionRef, 512),
+        signal: requiredString(value.signal, 128),
+        targetSkill,
+        targetRoot,
+        action,
+        ...(patch === undefined ? {} : { patch }),
+        ...(createSpec === undefined ? {} : { createSpec }),
+        rationale: requiredString(value.rationale, 8192),
+        evidenceRefs: Object.freeze([...evidenceRefs]),
+        status,
+        ...(typeof ledgerEntryId === "string" ? { ledgerEntryId } : {})
+    });
+}
+export async function enqueueProposal(value, projectRoot, configRoot, options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => enqueueProposal(value, projectRoot, configRoot, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    const paths = await resolveSkillLoopPaths(projectRoot, configRoot ?? skillLoopPaths(projectRoot).configRoot);
+    const proposal = parseSkillProposal(value, paths.skillsRoot);
+    if (Buffer.byteLength(JSON.stringify(proposal), "utf8") > proposalLimit)
+        throw new SkillProposalError("PROPOSAL_TOO_LARGE");
+    if (proposal.status !== "pending")
+        throw new SkillProposalError("PROPOSAL_STATUS_INVALID");
+    const file = path.join(paths.proposalsDir, `${proposal.id}.json`);
+    await ensureSafeRuntimeDirectory(projectRoot, paths.proposalsDir);
+    await assertSafeRuntimeFileForWrite(projectRoot, file);
+    try {
+        await fs.lstat(file);
+        throw new SkillProposalError("PROPOSAL_ALREADY_EXISTS");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    await writeJsonAtomically(projectRoot, file, proposal, options.capability);
+    return proposal;
+}
+export async function proposeFromFile(file, projectRoot, configRoot) {
+    const bytes = await fs.readFile(path.resolve(file));
+    if (bytes.byteLength > proposalLimit)
+        throw new SkillProposalError("PROPOSAL_TOO_LARGE");
+    return enqueueProposal(parseStrictJson(decodeStrictUtf8(bytes)), projectRoot, configRoot);
+}
+export async function readProposal(id, projectRoot, configRoot) {
+    if (!idPattern.test(id))
+        throw new SkillProposalError("PROPOSAL_ID_INVALID");
+    const paths = await resolveSkillLoopPaths(projectRoot, configRoot ?? skillLoopPaths(projectRoot).configRoot);
+    const bytes = await readSafeRuntimeFile(projectRoot, path.join(paths.proposalsDir, `${id}.json`), { maxBytes: proposalLimit });
+    if (bytes === undefined)
+        throw new SkillProposalError("PROPOSAL_NOT_FOUND");
+    const proposal = parseSkillProposal(parseStrictJson(decodeStrictUtf8(bytes)), paths.skillsRoot);
+    if (proposal.id !== id)
+        throw new SkillProposalError("PROPOSAL_INTEGRITY_INVALID");
+    return proposal;
+}
+async function readProposalDirectory(directory) {
+    return fs.readdir(directory, { withFileTypes: true, encoding: "utf8" });
+}
+export async function listProposals(projectRoot, configRoot) {
+    const paths = await resolveSkillLoopPaths(projectRoot, configRoot ?? skillLoopPaths(projectRoot).configRoot);
+    try {
+        const stat = await fs.lstat(paths.proposalsDir);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new SkillProposalError("PROPOSAL_INTEGRITY_INVALID");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    let entries;
+    try {
+        entries = await readProposalDirectory(paths.proposalsDir);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const records = [];
+    const identities = new Set();
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (entry.isSymbolicLink() || !entry.isFile() || !entry.name.endsWith(".json"))
+            throw new SkillProposalError("PROPOSAL_INTEGRITY_INVALID");
+        const fileId = entry.name.slice(0, -".json".length);
+        const bytes = await readSafeRuntimeFile(projectRoot, path.join(paths.proposalsDir, entry.name), { allowMissing: false, maxBytes: proposalLimit });
+        const record = parseSkillProposal(parseStrictJson(decodeStrictUtf8(bytes)), paths.skillsRoot);
+        if (record.id !== fileId)
+            throw new SkillProposalError("PROPOSAL_INTEGRITY_INVALID");
+        const identity = canonicalRelativeIdentity(record.id);
+        if (identities.has(identity))
+            throw new SkillProposalError("PROPOSAL_INTEGRITY_INVALID");
+        identities.add(identity);
+        records.push(record);
+    }
+    return Object.freeze(records);
+}
+export async function updateProposal(proposal, updates, projectRoot, configRoot, options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => updateProposal(proposal, updates, projectRoot, configRoot, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    const paths = await resolveSkillLoopPaths(projectRoot, configRoot ?? skillLoopPaths(projectRoot).configRoot);
+    const current = await readProposal(proposal.id, projectRoot, configRoot);
+    if (current.status !== proposal.status || current.ledgerEntryId !== proposal.ledgerEntryId)
+        throw new SkillProposalError("PROPOSAL_CONFLICT");
+    const next = { ...proposal, ...updates };
+    if (updates.ledgerEntryId === undefined && Object.hasOwn(updates, "ledgerEntryId"))
+        delete next.ledgerEntryId;
+    const parsed = parseSkillProposal(next, paths.skillsRoot);
+    await writeJsonAtomically(projectRoot, path.join(paths.proposalsDir, `${proposal.id}.json`), parsed, options.capability);
+    return parsed;
+}

package/dist/skill-loop/storage.d.ts

@@ -0,0 +1,72 @@
+declare const capabilityBrand: unique symbol;
+export type PhysicalDirectoryPin = {
+    readonly lexical: string;
+    readonly physical: string;
+    readonly dev: number;
+    readonly ino: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs: number;
+};
+export type PhysicalSkillLoopRoots = {
+    readonly project: PhysicalDirectoryPin;
+    readonly config: PhysicalDirectoryPin;
+    readonly skills: PhysicalDirectoryPin;
+};
+export type SkillLoopLockCapability = {
+    readonly [capabilityBrand]: true;
+};
+export declare function pinPhysicalDirectory(directory: string, create?: boolean): Promise<PhysicalDirectoryPin>;
+export declare function pinPhysicalDirectoryIfPresent(directory: string): Promise<PhysicalDirectoryPin | undefined>;
+export declare function canonicalPhysicalPath(target: string): Promise<string>;
+export declare function assertPhysicalDirectoryPin(pin: PhysicalDirectoryPin): Promise<void>;
+export declare function pinPhysicalSkillLoopRoots(projectRoot: string, configRoot: string): Promise<PhysicalSkillLoopRoots>;
+export declare function ensureSafeRuntimeDirectory(projectRoot: string, directory: string): Promise<void>;
+export declare function assertSafeRuntimeFileForWrite(projectRoot: string, file: string): Promise<void>;
+export declare function readSafeRuntimeFile(projectRoot: string, file: string, options?: {
+    readonly allowMissing?: boolean;
+    readonly maxBytes?: number;
+}): Promise<Buffer | undefined>;
+export declare function writeSafeRuntimeFile(projectRoot: string, file: string, bytes: Uint8Array): Promise<void>;
+export declare function removeSafeRuntimeFile(projectRoot: string, file: string): Promise<void>;
+export declare function syncDirectory(directory: string): Promise<void>;
+export declare function anchoredRenameInSkillsRoot(capability: SkillLoopLockCapability, source: string, destination: string): Promise<void>;
+export declare function anchoredRemoveFromSkillsRoot(capability: SkillLoopLockCapability, target: string): Promise<void>;
+export declare function anchoredCopyIntoSkillsRoot(capability: SkillLoopLockCapability, source: string, destination: string, files: readonly {
+    readonly file: string;
+    readonly blob: {
+        readonly digest: string;
+        readonly size: number;
+    };
+}[]): Promise<void>;
+export declare function anchoredVerifySkillTree(capability: SkillLoopLockCapability, target: string, files: readonly {
+    readonly file: string;
+    readonly blob: {
+        readonly digest: string;
+        readonly size: number;
+    };
+}[]): Promise<void>;
+export declare function anchoredAssertSkillPathAbsent(capability: SkillLoopLockCapability, target: string): Promise<void>;
+export declare function anchoredReadFileFromSkillsRoot(capability: SkillLoopLockCapability, target: string, maxBytes: number): Promise<{
+    readonly bytes: Buffer;
+    readonly dev: number;
+    readonly ino: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs: number;
+} | undefined>;
+export declare function anchoredWriteFileToSkillsRoot(capability: SkillLoopLockCapability, target: string, bytes: Uint8Array, expected: {
+    readonly dev: number;
+    readonly ino: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs: number;
+} | null): Promise<void>;
+type ProcessProbe = (command: string, args: readonly string[]) => {
+    readonly status: number | null;
+    readonly stdout: string;
+};
+export declare function processBirthIdentityForPlatform(pid: number, platform: NodeJS.Platform, probe?: ProcessProbe): string | undefined;
+export declare function assertSkillLoopGlobalBoundarySupported(platform?: NodeJS.Platform): void;
+export declare function assertSkillLoopLockCapability(capability: unknown, projectRoot: string, skillsRoot?: string): asserts capability is SkillLoopLockCapability;
+export declare function assertSkillLoopRootPins(capability: SkillLoopLockCapability): Promise<void>;
+export declare function withSkillLoopMutationLock<T>(projectRoot: string, run: (capability: SkillLoopLockCapability) => Promise<T>): Promise<T>;
+export declare function withSkillRootsMutationLock<T>(projectRoot: string, configRoot: string, run: (capability: SkillLoopLockCapability, roots: PhysicalSkillLoopRoots) => Promise<T>): Promise<T>;
+export {};