@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/apply.d.ts

@@ -0,0 +1,16 @@
+import type { SkillLedgerEntry, SkillProposal } from "./types.js";
+export interface SkillMutationOptions {
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly now?: () => Date;
+    readonly id?: () => string;
+}
+export interface SkillMutationResult {
+    readonly proposal: SkillProposal;
+    readonly ledger: SkillLedgerEntry;
+}
+export declare function applyProposal(workspaceRoot: string, proposalId: string, options?: SkillMutationOptions): SkillMutationResult;
+export declare function rejectProposal(workspaceRoot: string, proposalId: string, options?: SkillMutationOptions): SkillMutationResult;
+export declare function rollbackMutation(workspaceRoot: string, entryId: string, options?: SkillMutationOptions): {
+    readonly proposal?: SkillProposal;
+    readonly ledger: SkillLedgerEntry;
+};

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/apply.js

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { decodeSkillItem, snapshotIsAgentOwned, stampMarker } from "./ownership.js";
+import { skillLoopPaths } from "./paths.js";
+import { appendLedgerEntry, assertTargetNotPinned, readLedger, readProposalRecord, readUsage, snapshotSkill, snapshotsEqual, storeBlob, withAgentMutationLock, withSkillLoopLock, writeProposalRecord, } from "./store.js";
+import { recoverMutationJournalWhileLocked, writeMutationJournal } from "./transaction.js";
+import { SkillLoopError } from "./types.js";
+import { nextAppliedUsage } from "./usage.js";
+function now(options) {
+    return (options.now ?? (() => new Date()))().toISOString();
+}
+function ledgerId(options) {
+    return (options.id ?? (() => `ledger-${randomUUID()}`))();
+}
+function snapshotMap(snapshot) {
+    return new Map(snapshot.map((item) => [item.file, item]));
+}
+function assertOwned(paths, snapshot) {
+    if (!snapshotIsAgentOwned(paths, snapshot)) {
+        throw new SkillLoopError("TARGET_NOT_AGENT_OWNED", "the existing skill lacks the agent ownership marker");
+    }
+}
+function desiredSnapshot(paths, proposal, before) {
+    const items = snapshotMap(before);
+    if (proposal.action === "create") {
+        if (before.length > 0)
+            throw new SkillLoopError("TARGET_NOT_AGENT_OWNED", "create refuses an existing skill");
+        const files = proposal.createSpec?.files ?? [];
+        if (!files.some((file) => file.file === "SKILL.md")) {
+            throw new SkillLoopError("PROPOSAL_SCHEMA_INVALID", "create requires SKILL.md");
+        }
+        for (const file of files) {
+            const content = file.file === "SKILL.md" ? stampMarker(file.content, proposal.targetSkill) : file.content;
+            items.set(file.file, { file: file.file, blob: storeBlob(paths, Buffer.from(content, "utf8")) });
+        }
+    }
+    else {
+        if (before.length === 0)
+            throw new SkillLoopError("TARGET_NOT_AGENT_OWNED", "the target skill does not exist");
+        assertOwned(paths, before);
+        if (proposal.action === "patch") {
+            const patch = proposal.patch;
+            if (patch === undefined)
+                throw new SkillLoopError("PROPOSAL_SCHEMA_INVALID", "the patch is missing");
+            const current = items.get(patch.file);
+            if (current === undefined)
+                throw new SkillLoopError("PATCH_FILE_MISSING", "the patch file does not exist");
+            const content = decodeSkillItem(paths, current);
+            const first = content.indexOf(patch.oldString);
+            if (first < 0 || content.indexOf(patch.oldString, first + patch.oldString.length) >= 0) {
+                throw new SkillLoopError("PATCH_AMBIGUOUS", "the patch oldString must match exactly once");
+            }
+            const updated = `${content.slice(0, first)}${patch.newString}${content.slice(first + patch.oldString.length)}`;
+            items.set(patch.file, { file: patch.file, blob: storeBlob(paths, Buffer.from(updated, "utf8")) });
+        }
+        else if (proposal.action === "add-reference") {
+            for (const file of proposal.createSpec?.files ?? []) {
+                if (items.has(file.file))
+                    throw new SkillLoopError("TARGET_FILE_EXISTS", "add-reference refuses an existing file");
+                items.set(file.file, { file: file.file, blob: storeBlob(paths, Buffer.from(file.content, "utf8")) });
+            }
+        }
+        else if (proposal.action === "archive") {
+            return [];
+        }
+    }
+    const desired = [...items.values()].sort((left, right) => left.file.localeCompare(right.file));
+    if (!snapshotIsAgentOwned(paths, desired)) {
+        throw new SkillLoopError("TARGET_MARKER_INVALID", "the mutation postimage must preserve direct ownership");
+    }
+    return desired;
+}
+export function applyProposal(workspaceRoot, proposalId, options = {}) {
+    const paths = skillLoopPaths(workspaceRoot, options.env);
+    return withSkillLoopLock(paths, () => withAgentMutationLock(paths, () => {
+        const recoveredJournal = recoverMutationJournalWhileLocked(workspaceRoot, options.env, {
+            operation: "apply",
+            proposalId,
+        });
+        if (recoveredJournal?.operation === "apply" && recoveredJournal.ledger.proposalId === proposalId) {
+            const recoveredProposal = recoveredJournal.proposalAfter;
+            if (recoveredProposal === undefined) {
+                throw new SkillLoopError("TRANSACTION_INVALID", "the recovered apply proposal is missing");
+            }
+            return { proposal: recoveredProposal, ledger: recoveredJournal.ledger };
+        }
+        let proposal = readProposalRecord(paths, proposalId);
+        assertTargetNotPinned(paths, proposal.targetSkill);
+        if (proposal.status !== "pending" && proposal.status !== "approved") {
+            throw new SkillLoopError("PROPOSAL_STATUS_INVALID", "only pending or approved proposals may be applied");
+        }
+        if (proposal.status === "pending") {
+            proposal = { ...proposal, status: "approved" };
+            writeProposalRecord(paths, proposal);
+        }
+        const current = snapshotSkill(paths, proposal.targetSkill);
+        let before = current;
+        let desired;
+        if (proposal.action === "create" && current.length > 0) {
+            const expected = desiredSnapshot(paths, proposal, []);
+            const conflictingLedger = readLedger(workspaceRoot, { env: options.env }).some((entry) => entry.proposalId === proposal.id);
+            const usage = readUsage(paths);
+            if (!snapshotsEqual(current, expected) ||
+                conflictingLedger ||
+                usage?.skills[proposal.targetSkill] !== undefined) {
+                throw new SkillLoopError("TRANSACTION_RECONCILIATION_REFUSED", "an interrupted create postimage could not be reconciled exactly");
+            }
+            before = [];
+            desired = expected;
+        }
+        else {
+            desired = desiredSnapshot(paths, proposal, before);
+        }
+        const timestamp = now(options);
+        const ledger = {
+            schema: "litfamily.skill-ledger/v1",
+            id: ledgerId(options),
+            createdAt: timestamp,
+            proposalId: proposal.id,
+            actor: "user",
+            operation: "apply",
+            targetSkill: proposal.targetSkill,
+            targetRoot: paths.agentRoot,
+            before,
+            after: desired,
+        };
+        const applied = { ...proposal, status: "applied", ledgerEntryId: ledger.id };
+        writeMutationJournal(workspaceRoot, {
+            schema: "litcodex.skill-transaction/v1",
+            operation: "apply",
+            ledger,
+            proposalAfter: applied,
+            usageAfter: nextAppliedUsage(paths, proposal.targetSkill, timestamp),
+            copies: [],
+        }, options.env);
+        recoverMutationJournalWhileLocked(workspaceRoot, options.env, { operation: "apply", proposalId });
+        return { proposal: applied, ledger };
+    }));
+}
+export function rejectProposal(workspaceRoot, proposalId, options = {}) {
+    const paths = skillLoopPaths(workspaceRoot, options.env);
+    return withSkillLoopLock(paths, () => {
+        const proposal = readProposalRecord(paths, proposalId);
+        const committed = readLedger(workspaceRoot, { env: options.env }).find((entry) => entry.operation === "reject" && entry.proposalId === proposal.id);
+        if (committed !== undefined && proposal.status === "pending") {
+            const recovered = { ...proposal, status: "rejected", ledgerEntryId: committed.id };
+            writeProposalRecord(paths, recovered);
+            return { proposal: recovered, ledger: committed };
+        }
+        if (proposal.status !== "pending") {
+            throw new SkillLoopError("PROPOSAL_STATUS_INVALID", "only a pending proposal may be rejected");
+        }
+        const ledger = {
+            schema: "litfamily.skill-ledger/v1",
+            id: ledgerId(options),
+            createdAt: now(options),
+            proposalId: proposal.id,
+            actor: "user",
+            operation: "reject",
+            targetSkill: proposal.targetSkill,
+            targetRoot: paths.agentRoot,
+            before: [],
+            after: [],
+            reason: "explicit user rejection",
+        };
+        appendLedgerEntry(paths, ledger);
+        const rejected = { ...proposal, status: "rejected", ledgerEntryId: ledger.id };
+        writeProposalRecord(paths, rejected);
+        return { proposal: rejected, ledger };
+    });
+}
+export function rollbackMutation(workspaceRoot, entryId, options = {}) {
+    const paths = skillLoopPaths(workspaceRoot, options.env);
+    return withSkillLoopLock(paths, () => withAgentMutationLock(paths, () => {
+        const recoveredJournal = recoverMutationJournalWhileLocked(workspaceRoot, options.env, {
+            operation: "rollback",
+            restoresLedgerEntryId: entryId,
+        });
+        if (recoveredJournal?.operation === "rollback" && recoveredJournal.ledger.restoresLedgerEntryId === entryId) {
+            return recoveredJournal.proposalAfter === undefined
+                ? { ledger: recoveredJournal.ledger }
+                : { proposal: recoveredJournal.proposalAfter, ledger: recoveredJournal.ledger };
+        }
+        const source = readLedger(workspaceRoot, { env: options.env }).find((entry) => entry.id === entryId);
+        if (source === undefined ||
+            !["apply", "curator-transition", "rollback"].includes(source.operation)) {
+            throw new SkillLoopError("ROLLBACK_SOURCE_INVALID", "the rollback source is not eligible");
+        }
+        if (resolve(source.targetRoot) !== paths.agentRoot) {
+            throw new SkillLoopError("ROLLBACK_SOURCE_INVALID", "the rollback source target root mismatched");
+        }
+        const current = snapshotSkill(paths, source.targetSkill);
+        if (!snapshotsEqual(current, source.after)) {
+            throw new SkillLoopError("ROLLBACK_CAS_MISMATCH", "the target changed after the source mutation");
+        }
+        const ledger = {
+            schema: "litfamily.skill-ledger/v1",
+            id: ledgerId(options),
+            createdAt: now(options),
+            proposalId: source.proposalId,
+            actor: "user",
+            operation: "rollback",
+            targetSkill: source.targetSkill,
+            targetRoot: paths.agentRoot,
+            before: current,
+            after: source.before,
+            restoresLedgerEntryId: source.id,
+        };
+        let proposal;
+        if (source.proposalId !== null) {
+            const currentProposal = readProposalRecord(paths, source.proposalId);
+            proposal = { ...currentProposal, status: "rolled-back", ledgerEntryId: ledger.id };
+        }
+        writeMutationJournal(workspaceRoot, {
+            schema: "litcodex.skill-transaction/v1",
+            operation: "rollback",
+            ledger,
+            ...(proposal === undefined ? {} : { proposalAfter: proposal }),
+            copies: [],
+        }, options.env);
+        recoverMutationJournalWhileLocked(workspaceRoot, options.env, {
+            operation: "rollback",
+            restoresLedgerEntryId: entryId,
+        });
+        return proposal === undefined ? { ledger } : { proposal, ledger };
+    }));
+}

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/config.d.ts

@@ -0,0 +1,13 @@
+export interface SkillLoopConfig {
+    readonly autoApply: false;
+    readonly nudgeInterval: number;
+    readonly curator: {
+        readonly intervalDays: number;
+        readonly minimumIdleHours: number;
+        readonly staleAfterDays: number;
+        readonly archiveAfterDays: number;
+        readonly delete: false;
+        readonly consolidation: false;
+    };
+}
+export declare const DEFAULT_SKILL_LOOP_CONFIG: SkillLoopConfig;

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/config.js

@@ -0,0 +1,12 @@
+export const DEFAULT_SKILL_LOOP_CONFIG = Object.freeze({
+    autoApply: false,
+    nudgeInterval: 10,
+    curator: Object.freeze({
+        intervalDays: 7,
+        minimumIdleHours: 2,
+        staleAfterDays: 30,
+        archiveAfterDays: 90,
+        delete: false,
+        consolidation: false,
+    }),
+});

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/curator.d.ts

@@ -0,0 +1,14 @@
+export interface CuratorOptions {
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly now?: () => Date;
+    readonly lastActivityAt?: Date;
+    readonly id?: () => string;
+}
+export interface CuratorResult {
+    readonly stale: readonly string[];
+    readonly archived: readonly string[];
+    readonly skipped: readonly string[];
+    readonly ledgerIds: readonly string[];
+}
+export declare function runCurator(workspaceRoot: string, options?: CuratorOptions): CuratorResult;
+export declare function assertCuratorNeverDeletes(): false;

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/curator.js

@@ -0,0 +1,112 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_SKILL_LOOP_CONFIG } from "./config.js";
+import { snapshotIsAgentOwned } from "./ownership.js";
+import { skillLoopPaths } from "./paths.js";
+import { readUsage, snapshotSkill, withAgentMutationLock, withSkillLoopLock } from "./store.js";
+import { recoverMutationJournalWhileLocked, writeMutationJournal } from "./transaction.js";
+import { SkillLoopError } from "./types.js";
+import { validateUsageSidecar } from "./usage.js";
+const DAY = 24 * 60 * 60 * 1000;
+function mostRecent(entry) {
+    return Math.max(...[entry.created_at, entry.last_used_at, entry.last_viewed_at, entry.last_patched_at, entry.archived_at]
+        .filter((value) => value !== null)
+        .map((value) => Date.parse(value)));
+}
+function nextSidecar(sidecar, skillId, entry, timestamp) {
+    return {
+        schema: "litfamily.skill-usage/v1",
+        updatedAt: timestamp,
+        skills: { ...sidecar.skills, [skillId]: entry },
+    };
+}
+export function runCurator(workspaceRoot, options = {}) {
+    const paths = skillLoopPaths(workspaceRoot, options.env);
+    return withSkillLoopLock(paths, () => withAgentMutationLock(paths, () => {
+        recoverMutationJournalWhileLocked(workspaceRoot, options.env, { operation: "curator-transition" });
+        const rawUsage = readUsage(paths);
+        if (rawUsage === null)
+            return { stale: [], archived: [], skipped: [], ledgerIds: [] };
+        let sidecar = validateUsageSidecar(rawUsage);
+        const instant = (options.now ?? (() => new Date()))();
+        const timestamp = instant.toISOString();
+        const lastActivity = options.lastActivityAt?.getTime() ?? Date.parse(sidecar.updatedAt);
+        if (instant.getTime() - lastActivity < DEFAULT_SKILL_LOOP_CONFIG.curator.minimumIdleHours * 60 * 60 * 1000) {
+            return { stale: [], archived: [], skipped: Object.keys(sidecar.skills).sort(), ledgerIds: [] };
+        }
+        const stale = [];
+        const archived = [];
+        const skipped = [];
+        const ledgerIds = [];
+        for (const skillId of Object.keys(sidecar.skills).sort()) {
+            const entry = sidecar.skills[skillId];
+            if (entry === undefined || entry.pinned || entry.state === "archived") {
+                skipped.push(skillId);
+                continue;
+            }
+            const ageDays = (instant.getTime() - mostRecent(entry)) / DAY;
+            const transition = entry.state === "active" && ageDays >= DEFAULT_SKILL_LOOP_CONFIG.curator.staleAfterDays
+                ? "stale"
+                : entry.state === "stale" && ageDays >= DEFAULT_SKILL_LOOP_CONFIG.curator.archiveAfterDays
+                    ? "archived"
+                    : null;
+            if (transition === null) {
+                skipped.push(skillId);
+                continue;
+            }
+            const before = snapshotSkill(paths, skillId);
+            if (before.length === 0 || !snapshotIsAgentOwned(paths, before)) {
+                skipped.push(skillId);
+                continue;
+            }
+            const runId = `${timestamp.replace(/[:.]/gu, "-")}-${randomUUID()}`;
+            const after = transition === "archived" ? [] : before;
+            const transitioned = {
+                ...entry,
+                state: transition,
+                archived_at: transition === "archived" ? timestamp : null,
+            };
+            const updated = nextSidecar(sidecar, skillId, transitioned, timestamp);
+            const ledger = {
+                schema: "litfamily.skill-ledger/v1",
+                id: (options.id ?? (() => `ledger-${randomUUID()}`))(),
+                createdAt: timestamp,
+                proposalId: null,
+                actor: "curator",
+                operation: "curator-transition",
+                targetSkill: skillId,
+                targetRoot: paths.agentRoot,
+                before,
+                after,
+                reason: transition === "archived"
+                    ? "usage exceeded the archive threshold"
+                    : "usage exceeded the stale threshold",
+            };
+            writeMutationJournal(workspaceRoot, {
+                schema: "litcodex.skill-transaction/v1",
+                operation: "curator-transition",
+                ledger,
+                usageAfter: updated,
+                copies: [
+                    { kind: "backup", relativePath: `${runId}/${skillId}` },
+                    ...(transition === "archived"
+                        ? [{ kind: "archive", relativePath: `${skillId}/${runId}` }]
+                        : []),
+                ],
+            }, options.env);
+            recoverMutationJournalWhileLocked(workspaceRoot, options.env, { operation: "curator-transition" });
+            sidecar = updated;
+            ledgerIds.push(ledger.id);
+            if (transition === "archived")
+                archived.push(skillId);
+            else
+                stale.push(skillId);
+        }
+        return { stale, archived, skipped, ledgerIds };
+    }));
+}
+export function assertCuratorNeverDeletes() {
+    if (DEFAULT_SKILL_LOOP_CONFIG.curator.delete !== false) {
+        throw new SkillLoopError("CURATOR_CONFIG_INVALID", "the curator delete setting must remain false");
+    }
+    return false;
+}

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-loop/hook.d.ts

@@ -0,0 +1,19 @@
+interface PendingOptions {
+    readonly now?: () => Date;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly beforeRead?: ((path: string) => void) | undefined;
+    /** Test-only race seam; production callers leave this unset. */
+    readonly afterEnumerate?: (() => void) | undefined;
+    /** Test-only race seam; production callers leave this unset. */
+    readonly beforeWrite?: ((path: string) => void) | undefined;
+    /** Test-only last-boundary race seam; production callers leave this unset. */
+    readonly afterWriteVerify?: ((path: string) => void) | undefined;
+}
+export declare function markPendingReviews(workspaceRoot: string, input: unknown, options?: PendingOptions): {
+    readonly marked: number;
+    readonly skipped: number;
+};
+export declare function pendingReviewNotice(workspaceRoot: string, options?: PendingOptions): string | null;
+export declare function pendingReviewDirectories(workspaceRoot: string, options?: PendingOptions): string[];
+export declare function markReviewsComplete(workspaceRoot: string, timestamp: string): void;
+export {};