@litfamily/litopencode 1.0.0

package/dist/skill-loop/ledger.js

@@ -0,0 +1,344 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parseStrictJson } from "../strict-json.js";
+import { assertPathComponentsSafe, inventoryTree, lstatIfPresent } from "../cli/native-skill-tree.js";
+import { assertPortableRelativeFile, canonicalRelativeIdentity } from "./proposals.js";
+import { skillLoopPaths } from "./config.js";
+import { assertSafeRuntimeFileForWrite, assertSkillLoopLockCapability, ensureSafeRuntimeDirectory, readSafeRuntimeFile, syncDirectory, withSkillLoopMutationLock, writeSafeRuntimeFile } from "./storage.js";
+import { isStrictRfc3339 } from "./time.js";
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function equalSnapshots(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+async function storeBlob(projectRoot, bytes) {
+    const value = digest(bytes);
+    const dir = skillLoopPaths(projectRoot).blobsDir;
+    const file = path.join(dir, value);
+    await ensureSafeRuntimeDirectory(projectRoot, dir);
+    await assertSafeRuntimeFileForWrite(projectRoot, file);
+    try {
+        await writeSafeRuntimeFile(projectRoot, file, bytes);
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.message === "SKILL_LOOP_CONFLICT"))
+            throw error;
+    }
+    const stored = await readSafeRuntimeFile(projectRoot, file, { allowMissing: false });
+    if (stored === undefined || stored.byteLength !== bytes.byteLength || digest(stored) !== value)
+        throw new Error("LEDGER_BLOB_CORRUPT");
+    return { algorithm: "sha256", digest: value, size: bytes.byteLength };
+}
+export async function snapshotSkill(projectRoot, skillRoot) {
+    const stat = await lstatIfPresent(skillRoot);
+    if (stat === null)
+        return [];
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error("TARGET_PATH_UNSAFE");
+    await assertPathComponentsSafe(path.dirname(skillRoot), skillRoot, "Skill snapshot");
+    const inventory = await inventoryTree(skillRoot);
+    if (inventory.unsafe.length > 0 || inventory.files.length > 256)
+        throw new Error("TARGET_PATH_UNSAFE");
+    const identities = new Set();
+    const snapshot = [];
+    for (const relative of inventory.files) {
+        const file = assertPortableRelativeFile(relative);
+        const identity = canonicalRelativeIdentity(file);
+        if (identities.has(identity))
+            throw new Error("TARGET_PATH_UNSAFE");
+        identities.add(identity);
+        const bytes = await fs.readFile(path.join(skillRoot, ...file.split("/")));
+        snapshot.push({ file, blob: await storeBlob(projectRoot, bytes) });
+    }
+    return Object.freeze(snapshot.sort((a, b) => a.file.localeCompare(b.file)));
+}
+async function blobBytes(projectRoot, item) {
+    const file = path.join(skillLoopPaths(projectRoot).blobsDir, item.blob.digest);
+    let bytes;
+    try {
+        bytes = await readSafeRuntimeFile(projectRoot, file, { allowMissing: false });
+    }
+    catch (error) {
+        if (error instanceof Error && (error.message === "SKILL_LOOP_PATH_UNSAFE" || "code" in error && error.code === "ENOENT")) {
+            throw new Error("LEDGER_BLOB_CORRUPT");
+        }
+        throw error;
+    }
+    if (bytes === undefined)
+        throw new Error("LEDGER_BLOB_CORRUPT");
+    if (bytes.byteLength !== item.blob.size || digest(bytes) !== item.blob.digest)
+        throw new Error("LEDGER_BLOB_CORRUPT");
+    return bytes;
+}
+export async function readSnapshotFile(projectRoot, snapshot, relativeFile) {
+    const identity = canonicalRelativeIdentity(assertPortableRelativeFile(relativeFile));
+    const item = snapshot.find((candidate) => canonicalRelativeIdentity(candidate.file) === identity);
+    return item === undefined ? undefined : blobBytes(projectRoot, item);
+}
+export async function assertSnapshotMatches(projectRoot, skillRoot, expected) {
+    const actual = await snapshotSkill(projectRoot, skillRoot);
+    if (!equalSnapshots(actual, expected))
+        throw new Error("ROLLBACK_STATE_MISMATCH");
+}
+export async function restoreSnapshot(projectRoot, skillRoot, snapshot) {
+    const parent = path.dirname(skillRoot);
+    await fs.mkdir(parent, { recursive: true });
+    await assertPathComponentsSafe(parent, skillRoot, "Skill restore");
+    if (snapshot.length === 0) {
+        await fs.rm(skillRoot, { recursive: true, force: true });
+        return;
+    }
+    const stage = path.join(parent, `.${path.basename(skillRoot)}.${randomUUID()}.stage`);
+    const backup = path.join(parent, `.${path.basename(skillRoot)}.${randomUUID()}.backup`);
+    await fs.mkdir(stage, { mode: 0o700 });
+    try {
+        for (const item of snapshot) {
+            const relative = assertPortableRelativeFile(item.file);
+            const destination = path.join(stage, ...relative.split("/"));
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            await fs.writeFile(destination, await blobBytes(projectRoot, item), { mode: 0o600 });
+        }
+        const current = await lstatIfPresent(skillRoot);
+        if (current !== null)
+            await fs.rename(skillRoot, backup);
+        try {
+            await fs.rename(stage, skillRoot);
+        }
+        catch (error) {
+            if (current !== null)
+                await fs.rename(backup, skillRoot);
+            throw error;
+        }
+        if (current !== null)
+            await fs.rm(backup, { recursive: true, force: true });
+        await syncDirectory(parent);
+    }
+    catch (error) {
+        await fs.rm(stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+function parseLedgerEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("SKILL_LEDGER_INVALID");
+    const record = value;
+    const allowed = new Set(["schema", "id", "createdAt", "proposalId", "actor", "operation", "targetSkill", "targetRoot", "before", "after", "restoresLedgerEntryId", "reason"]);
+    const timestamp = isStrictRfc3339(record.createdAt);
+    const proposalId = record.proposalId;
+    const operation = record.operation;
+    const restores = record.restoresLedgerEntryId;
+    if (Object.keys(record).some((key) => !allowed.has(key)) || record.schema !== "litfamily.skill-ledger/v1" ||
+        typeof record.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(record.id) || !timestamp ||
+        (proposalId !== null && (typeof proposalId !== "string" || proposalId.length < 1 || proposalId.length > 128)) ||
+        (record.actor !== "user" && record.actor !== "curator") ||
+        (operation !== "apply" && operation !== "reject" && operation !== "rollback" && operation !== "curator-transition") ||
+        typeof record.targetSkill !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(record.targetSkill) ||
+        typeof record.targetRoot !== "string" || record.targetRoot.length < 1 || record.targetRoot.length > 2048 ||
+        (record.reason !== undefined && (typeof record.reason !== "string" || record.reason.length > 8192)) ||
+        ((operation === "rollback") !== (typeof restores === "string" && restores.length > 0 && restores.length <= 128)) ||
+        ((operation === "apply" || operation === "reject") && (record.actor !== "user" || proposalId === null)) ||
+        (operation === "rollback" && record.actor !== "user") ||
+        (operation === "curator-transition" && (record.actor !== "curator" || proposalId !== null))) {
+        throw new Error("SKILL_LEDGER_INVALID");
+    }
+    try {
+        if (assertPortableRelativeFile(record.id) !== record.id || assertPortableRelativeFile(record.targetSkill) !== record.targetSkill ||
+            !path.isAbsolute(record.targetRoot) ||
+            (typeof proposalId === "string" && assertPortableRelativeFile(proposalId) !== proposalId) ||
+            (typeof restores === "string" && assertPortableRelativeFile(restores) !== restores)) {
+            throw new Error("invalid");
+        }
+    }
+    catch {
+        throw new Error("SKILL_LEDGER_INVALID");
+    }
+    return Object.freeze({
+        schema: "litfamily.skill-ledger/v1",
+        id: record.id,
+        createdAt: record.createdAt,
+        proposalId: proposalId,
+        actor: record.actor,
+        operation,
+        targetSkill: record.targetSkill,
+        targetRoot: record.targetRoot,
+        before: parseSkillSnapshot(record.before),
+        after: parseSkillSnapshot(record.after),
+        ...(typeof restores === "string" ? { restoresLedgerEntryId: restores } : {}),
+        ...(typeof record.reason === "string" ? { reason: record.reason } : {})
+    });
+}
+export function parseSkillSnapshot(value) {
+    if (!Array.isArray(value) || value.length > 256)
+        throw new Error("SKILL_LEDGER_INVALID");
+    const identities = new Set();
+    const snapshot = value.map((item) => {
+        if (typeof item !== "object" || item === null || Array.isArray(item) ||
+            Object.keys(item).some((key) => key !== "file" && key !== "blob"))
+            throw new Error("SKILL_LEDGER_INVALID");
+        const source = item;
+        let file;
+        try {
+            file = assertPortableRelativeFile(source.file);
+        }
+        catch {
+            throw new Error("SKILL_LEDGER_INVALID");
+        }
+        const identity = canonicalRelativeIdentity(file);
+        if (identities.has(identity))
+            throw new Error("SKILL_LEDGER_INVALID");
+        identities.add(identity);
+        if (typeof source.blob !== "object" || source.blob === null || Array.isArray(source.blob) ||
+            Object.keys(source.blob).some((key) => key !== "algorithm" && key !== "digest" && key !== "size")) {
+            throw new Error("SKILL_LEDGER_INVALID");
+        }
+        const blob = source.blob;
+        if (blob.algorithm !== "sha256" || typeof blob.digest !== "string" || !/^[a-f0-9]{64}$/u.test(blob.digest) ||
+            !Number.isInteger(blob.size) || Number(blob.size) < 0)
+            throw new Error("SKILL_LEDGER_INVALID");
+        return Object.freeze({ file, blob: Object.freeze({ algorithm: "sha256", digest: blob.digest, size: Number(blob.size) }) });
+    });
+    return Object.freeze(snapshot);
+}
+export async function readSkillLedger(projectRoot) {
+    const file = skillLoopPaths(projectRoot).ledgerFile;
+    const bytes = await readSafeRuntimeFile(projectRoot, file, { maxBytes: 16 * 1024 * 1024 });
+    if (bytes === undefined)
+        return [];
+    const raw = bytes.toString("utf8");
+    const entries = raw.split("\n").filter((line) => line !== "").map((line) => parseLedgerEntry(parseStrictJson(line)));
+    const ids = new Set();
+    const restored = new Set();
+    const proposalTransitions = new Set();
+    const entriesById = new Map();
+    for (const entry of entries) {
+        if (ids.has(entry.id))
+            throw new Error("SKILL_LEDGER_INVALID");
+        if (entry.operation === "rollback") {
+            if (entry.restoresLedgerEntryId === undefined || !ids.has(entry.restoresLedgerEntryId) || restored.has(entry.restoresLedgerEntryId)) {
+                throw new Error("SKILL_LEDGER_INVALID");
+            }
+            restored.add(entry.restoresLedgerEntryId);
+            const reference = entriesById.get(entry.restoresLedgerEntryId);
+            if (reference === undefined || (reference.operation !== "apply" && reference.operation !== "curator-transition" && reference.operation !== "rollback") ||
+                canonicalRelativeIdentity(entry.targetSkill) !== canonicalRelativeIdentity(reference.targetSkill) ||
+                path.resolve(entry.targetRoot) !== path.resolve(reference.targetRoot) || entry.proposalId !== reference.proposalId ||
+                !equalSnapshots(entry.before, reference.after) || !equalSnapshots(entry.after, reference.before)) {
+                throw new Error("SKILL_LEDGER_INVALID");
+            }
+        }
+        if ((entry.operation === "apply" || entry.operation === "reject") && entry.proposalId !== null) {
+            if (proposalTransitions.has(entry.proposalId))
+                throw new Error("SKILL_LEDGER_INVALID");
+            proposalTransitions.add(entry.proposalId);
+        }
+        ids.add(entry.id);
+        entriesById.set(entry.id, entry);
+        for (const item of [...entry.before, ...entry.after])
+            await blobBytes(projectRoot, item);
+    }
+    return Object.freeze(entries);
+}
+export function assertProposalLedgerIntegrity(proposals, entries) {
+    const proposalsById = new Map(proposals.map((proposal) => [proposal.id, proposal]));
+    const entriesById = new Map(entries.map((entry) => [entry.id, entry]));
+    for (const entry of entries) {
+        if ((entry.operation === "apply" || entry.operation === "reject") &&
+            (entry.proposalId === null || !proposalsById.has(entry.proposalId)))
+            throw new Error("PROPOSAL_INTEGRITY_INVALID");
+        if ((entry.operation === "apply" || entry.operation === "reject") && entry.proposalId !== null) {
+            const proposal = proposalsById.get(entry.proposalId);
+            if (canonicalRelativeIdentity(entry.targetSkill) !== canonicalRelativeIdentity(proposal.targetSkill) ||
+                path.resolve(entry.targetRoot) !== path.resolve(proposal.targetRoot))
+                throw new Error("PROPOSAL_INTEGRITY_INVALID");
+        }
+    }
+    for (const proposal of proposals) {
+        const related = entries.filter((entry) => entry.proposalId === proposal.id);
+        if (proposal.status === "pending" || proposal.status === "approved") {
+            if (related.length !== 0)
+                throw new Error("PROPOSAL_INTEGRITY_INVALID");
+            continue;
+        }
+        if (proposal.status === "rejected") {
+            if (related.length !== 1 || related[0]?.operation !== "reject")
+                throw new Error("PROPOSAL_INTEGRITY_INVALID");
+            continue;
+        }
+        let terminal = proposal.ledgerEntryId === undefined ? undefined : entriesById.get(proposal.ledgerEntryId);
+        let rollbackDepth = 0;
+        const visited = new Set();
+        while (terminal?.operation === "rollback") {
+            if (terminal.proposalId !== proposal.id || terminal.restoresLedgerEntryId === undefined || visited.has(terminal.id)) {
+                throw new Error("PROPOSAL_INTEGRITY_INVALID");
+            }
+            visited.add(terminal.id);
+            rollbackDepth += 1;
+            terminal = entriesById.get(terminal.restoresLedgerEntryId);
+        }
+        if (terminal?.operation !== "apply" || terminal.proposalId !== proposal.id ||
+            (proposal.status === "applied") !== (rollbackDepth % 2 === 0))
+            throw new Error("PROPOSAL_INTEGRITY_INVALID");
+    }
+}
+export async function appendSkillLedger(projectRoot, entry, now = new Date().toISOString(), options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => appendSkillLedger(projectRoot, entry, now, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    return (await appendSkillLedgerBatch(projectRoot, [entry], now, { capability: options.capability }))[0];
+}
+export async function appendSkillLedgerBatch(projectRoot, entries, now = new Date().toISOString(), options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => appendSkillLedgerBatch(projectRoot, entries, now, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    if (entries.length === 0)
+        return [];
+    const file = skillLoopPaths(projectRoot).ledgerFile;
+    const records = entries.map((entry) => ({
+        schema: "litfamily.skill-ledger/v1",
+        id: `ledger-${randomUUID()}`,
+        createdAt: now,
+        ...entry
+    })).map(parseLedgerEntry);
+    const existing = await readSkillLedger(projectRoot);
+    const ids = new Set(existing.map((candidate) => candidate.id));
+    const byId = new Map(existing.map((candidate) => [candidate.id, candidate]));
+    const proposalIds = new Set(existing.flatMap((candidate) => candidate.proposalId === null ? [] : [candidate.proposalId]));
+    const restored = new Set(existing.flatMap((candidate) => candidate.restoresLedgerEntryId === undefined ? [] : [candidate.restoresLedgerEntryId]));
+    for (const parsed of records) {
+        if (ids.has(parsed.id))
+            throw new Error("SKILL_LEDGER_INVALID");
+        if (parsed.operation === "rollback") {
+            const reference = parsed.restoresLedgerEntryId === undefined ? undefined : byId.get(parsed.restoresLedgerEntryId);
+            if (reference === undefined || restored.has(reference.id) ||
+                (reference.operation !== "apply" && reference.operation !== "curator-transition" && reference.operation !== "rollback") ||
+                canonicalRelativeIdentity(parsed.targetSkill) !== canonicalRelativeIdentity(reference.targetSkill) ||
+                path.resolve(parsed.targetRoot) !== path.resolve(reference.targetRoot) || parsed.proposalId !== reference.proposalId ||
+                !equalSnapshots(parsed.before, reference.after) || !equalSnapshots(parsed.after, reference.before)) {
+                throw new Error("SKILL_LEDGER_INVALID");
+            }
+        }
+        if ((parsed.operation === "apply" || parsed.operation === "reject") && parsed.proposalId !== null && proposalIds.has(parsed.proposalId)) {
+            throw new Error("SKILL_LEDGER_INVALID");
+        }
+        ids.add(parsed.id);
+        byId.set(parsed.id, parsed);
+        if (parsed.restoresLedgerEntryId !== undefined)
+            restored.add(parsed.restoresLedgerEntryId);
+        if (parsed.proposalId !== null)
+            proposalIds.add(parsed.proposalId);
+    }
+    const prior = await readSafeRuntimeFile(projectRoot, file) ?? Buffer.alloc(0);
+    const appended = Buffer.from(records.map((record) => JSON.stringify(record)).join("\n") + "\n", "utf8");
+    await writeSafeRuntimeFile(projectRoot, file, Buffer.concat([prior, appended]));
+    return Object.freeze(records);
+}
+export async function findSkillLedgerEntry(projectRoot, id) {
+    const entry = (await readSkillLedger(projectRoot)).find((candidate) => candidate.id === id);
+    if (entry === undefined)
+        throw new Error("LEDGER_ENTRY_NOT_FOUND");
+    return entry;
+}

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

@@ -0,0 +1,48 @@
+import { type SkillLoopLockCapability } from "./storage.ts";
+export type ProposalStatus = "pending" | "approved" | "applied" | "rejected" | "rolled-back";
+export type ProposalAction = "patch" | "create" | "add-reference" | "archive";
+export type ProposalPatch = {
+    readonly file: string;
+    readonly oldString: string;
+    readonly newString: string;
+};
+export type ProposalCreateSpec = {
+    readonly files: readonly {
+        readonly file: string;
+        readonly content: string;
+    }[];
+};
+export type SkillProposal = {
+    readonly schema: "litfamily.skill-proposal/v1";
+    readonly id: string;
+    readonly createdAt: string;
+    readonly host: "litopencode";
+    readonly sessionRef: string;
+    readonly signal: string;
+    readonly targetSkill: string;
+    readonly targetRoot: string;
+    readonly action: ProposalAction;
+    readonly patch?: ProposalPatch;
+    readonly createSpec?: ProposalCreateSpec;
+    readonly rationale: string;
+    readonly evidenceRefs: readonly string[];
+    readonly status: ProposalStatus;
+    readonly ledgerEntryId?: string;
+};
+export declare class SkillProposalError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export declare const proposalLimit: number;
+export declare function canonicalRelativeIdentity(file: string): string;
+export declare function assertPortableRelativeFile(file: unknown, targetSkill?: string): string;
+export declare function parseSkillProposal(value: unknown, expectedSkillsRoot?: string): SkillProposal;
+export declare function enqueueProposal(value: unknown, projectRoot: string, configRoot?: string, options?: {
+    readonly capability?: SkillLoopLockCapability;
+}): Promise<SkillProposal>;
+export declare function proposeFromFile(file: string, projectRoot: string, configRoot?: string): Promise<SkillProposal>;
+export declare function readProposal(id: string, projectRoot: string, configRoot?: string): Promise<SkillProposal>;
+export declare function listProposals(projectRoot: string, configRoot?: string): Promise<readonly SkillProposal[]>;
+export declare function updateProposal(proposal: SkillProposal, updates: Readonly<Partial<Pick<SkillProposal, "status" | "ledgerEntryId">>>, projectRoot: string, configRoot?: string, options?: {
+    readonly capability?: SkillLoopLockCapability;
+}): Promise<SkillProposal>;