@litfamily/litopencode 1.0.0

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

@@ -0,0 +1,31 @@
+import { type SkillLoopLockCapability } from "./storage.ts";
+export type SkillUsageState = "active" | "stale" | "archived";
+export type SkillUsageEntry = {
+    readonly state: SkillUsageState;
+    readonly use_count: number;
+    readonly view_count: number;
+    readonly patch_count: number;
+    readonly created_at: string;
+    readonly created_by: "agent" | "user" | "installed" | "curator" | null;
+    readonly last_used_at: string | null;
+    readonly last_viewed_at: string | null;
+    readonly last_patched_at: string | null;
+    readonly archived_at: string | null;
+    readonly pinned: boolean;
+};
+export type SkillUsageSidecar = {
+    readonly schema: "litfamily.skill-usage/v1";
+    readonly updatedAt: string;
+    readonly skills: Readonly<Record<string, SkillUsageEntry>>;
+};
+export declare function parseUsageSidecar(value: unknown): SkillUsageSidecar;
+export declare function readUsageSidecar(projectRoot: string, now?: string): Promise<SkillUsageSidecar>;
+export declare function writeUsageSidecar(projectRoot: string, value: unknown, options?: {
+    readonly capability?: SkillLoopLockCapability;
+}): Promise<SkillUsageSidecar>;
+export declare function bumpSkillUsage(projectRoot: string, skillId: string, field: "use" | "view" | "patch", now?: string, options?: {
+    readonly capability?: SkillLoopLockCapability;
+}): Promise<SkillUsageSidecar>;
+export declare function setSkillUsageLifecycle(projectRoot: string, skillId: string, state: SkillUsageState, now?: string, options?: {
+    readonly capability?: SkillLoopLockCapability;
+}): Promise<SkillUsageSidecar>;

package/dist/skill-loop/usage.js

@@ -0,0 +1,146 @@
+import { parseStrictJson } from "../strict-json.js";
+import { skillLoopPaths, writeJsonAtomically } from "./config.js";
+import { assertPortableRelativeFile, canonicalRelativeIdentity } from "./proposals.js";
+import { assertSkillLoopLockCapability, readSafeRuntimeFile, withSkillLoopMutationLock } from "./storage.js";
+import { isStrictRfc3339 } from "./time.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function timestamp(value, nullable = false) {
+    if (value === null && nullable)
+        return null;
+    if (!isStrictRfc3339(value))
+        throw new Error("SKILL_USAGE_INVALID");
+    return value;
+}
+function count(value) {
+    if (!Number.isInteger(value) || Number(value) < 0)
+        throw new Error("SKILL_USAGE_INVALID");
+    return Number(value);
+}
+export function parseUsageSidecar(value) {
+    if (!isRecord(value) || value.schema !== "litfamily.skill-usage/v1" || typeof value.updatedAt !== "string" || !isRecord(value.skills) ||
+        Object.keys(value).some((key) => key !== "schema" && key !== "updatedAt" && key !== "skills")) {
+        throw new Error("SKILL_USAGE_INVALID");
+    }
+    const updatedAt = timestamp(value.updatedAt);
+    const updatedMs = Date.parse(updatedAt);
+    const skills = {};
+    const identities = new Set();
+    for (const [id, raw] of Object.entries(value.skills)) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(id) || !isRecord(raw))
+            throw new Error("SKILL_USAGE_INVALID");
+        try {
+            if (assertPortableRelativeFile(id) !== id)
+                throw new Error("invalid");
+        }
+        catch {
+            throw new Error("SKILL_USAGE_INVALID");
+        }
+        const identity = canonicalRelativeIdentity(id);
+        if (identities.has(identity))
+            throw new Error("SKILL_USAGE_INVALID");
+        identities.add(identity);
+        const expected = ["state", "use_count", "view_count", "patch_count", "created_at", "created_by", "last_used_at", "last_viewed_at", "last_patched_at", "archived_at", "pinned"];
+        if (Object.keys(raw).length !== expected.length || Object.keys(raw).some((key) => !expected.includes(key)))
+            throw new Error("SKILL_USAGE_INVALID");
+        if (raw.state !== "active" && raw.state !== "stale" && raw.state !== "archived")
+            throw new Error("SKILL_USAGE_INVALID");
+        if (raw.created_by !== "agent" && raw.created_by !== "user" && raw.created_by !== "installed" && raw.created_by !== "curator" && raw.created_by !== null)
+            throw new Error("SKILL_USAGE_INVALID");
+        if (typeof raw.pinned !== "boolean")
+            throw new Error("SKILL_USAGE_INVALID");
+        const entry = {
+            state: raw.state,
+            use_count: count(raw.use_count),
+            view_count: count(raw.view_count),
+            patch_count: count(raw.patch_count),
+            created_at: timestamp(raw.created_at),
+            created_by: raw.created_by,
+            last_used_at: timestamp(raw.last_used_at, true),
+            last_viewed_at: timestamp(raw.last_viewed_at, true),
+            last_patched_at: timestamp(raw.last_patched_at, true),
+            archived_at: timestamp(raw.archived_at, true),
+            pinned: raw.pinned
+        };
+        if ((entry.use_count > 0) !== (entry.last_used_at !== null) || (entry.view_count > 0) !== (entry.last_viewed_at !== null) ||
+            (entry.patch_count > 0) !== (entry.last_patched_at !== null) || (entry.state === "archived") !== (entry.archived_at !== null)) {
+            throw new Error("SKILL_USAGE_INVALID");
+        }
+        const createdMs = Date.parse(entry.created_at);
+        for (const date of [entry.last_used_at, entry.last_viewed_at, entry.last_patched_at, entry.archived_at]) {
+            if (date !== null && (Date.parse(date) < createdMs || Date.parse(date) > updatedMs))
+                throw new Error("SKILL_USAGE_INVALID");
+        }
+        if (createdMs > updatedMs)
+            throw new Error("SKILL_USAGE_INVALID");
+        skills[id] = Object.freeze(entry);
+    }
+    return Object.freeze({ schema: "litfamily.skill-usage/v1", updatedAt, skills: Object.freeze(skills) });
+}
+export async function readUsageSidecar(projectRoot, now = new Date().toISOString()) {
+    if (!isStrictRfc3339(now))
+        throw new Error("SKILL_USAGE_INVALID");
+    const bytes = await readSafeRuntimeFile(projectRoot, skillLoopPaths(projectRoot).usageFile, { maxBytes: 2 * 1024 * 1024 });
+    return bytes === undefined
+        ? { schema: "litfamily.skill-usage/v1", updatedAt: now, skills: {} }
+        : parseUsageSidecar(parseStrictJson(bytes.toString("utf8")));
+}
+export async function writeUsageSidecar(projectRoot, value, options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => writeUsageSidecar(projectRoot, value, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    const parsed = parseUsageSidecar(value);
+    await writeJsonAtomically(projectRoot, skillLoopPaths(projectRoot).usageFile, parsed, options.capability);
+    return parsed;
+}
+export async function bumpSkillUsage(projectRoot, skillId, field, now = new Date().toISOString(), options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => bumpSkillUsage(projectRoot, skillId, field, now, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    if (!isStrictRfc3339(now))
+        throw new Error("SKILL_USAGE_INVALID");
+    const sidecar = await readUsageSidecar(projectRoot, now);
+    const current = sidecar.skills[skillId] ?? {
+        state: "active",
+        use_count: 0, view_count: 0, patch_count: 0,
+        created_at: now, created_by: "agent",
+        last_used_at: null, last_viewed_at: null, last_patched_at: null,
+        archived_at: null, pinned: false
+    };
+    const next = {
+        ...current,
+        state: current.state === "archived" ? "archived" : "active",
+        use_count: current.use_count + (field === "use" ? 1 : 0),
+        view_count: current.view_count + (field === "view" ? 1 : 0),
+        patch_count: current.patch_count + (field === "patch" ? 1 : 0),
+        last_used_at: field === "use" ? now : current.last_used_at,
+        last_viewed_at: field === "view" ? now : current.last_viewed_at,
+        last_patched_at: field === "patch" ? now : current.last_patched_at
+    };
+    return writeUsageSidecar(projectRoot, { ...sidecar, updatedAt: now, skills: { ...sidecar.skills, [skillId]: next } }, { capability: options.capability });
+}
+export async function setSkillUsageLifecycle(projectRoot, skillId, state, now = new Date().toISOString(), options = {}) {
+    if (options.capability === undefined) {
+        return withSkillLoopMutationLock(projectRoot, (capability) => setSkillUsageLifecycle(projectRoot, skillId, state, now, { capability }));
+    }
+    assertSkillLoopLockCapability(options.capability, projectRoot);
+    if (!isStrictRfc3339(now))
+        throw new Error("SKILL_USAGE_INVALID");
+    const sidecar = await readUsageSidecar(projectRoot, now);
+    const current = sidecar.skills[skillId] ?? {
+        state: "active",
+        use_count: 0, view_count: 0, patch_count: 0,
+        created_at: now, created_by: "agent",
+        last_used_at: null, last_viewed_at: null, last_patched_at: null,
+        archived_at: null, pinned: false
+    };
+    const next = {
+        ...current,
+        state,
+        archived_at: state === "archived" ? now : null
+    };
+    return writeUsageSidecar(projectRoot, { ...sidecar, updatedAt: now, skills: { ...sidecar.skills, [skillId]: next } }, { capability: options.capability });
+}

package/dist/skill-observer.d.ts

@@ -0,0 +1,22 @@
+/** The three signals worth capturing. A fourth needs a contract revision, not a free-text value. */
+export declare const OBSERVER_SIGNALS: readonly ["correction", "repetition", "coverage-gap"];
+export type ObserverSignal = (typeof OBSERVER_SIGNALS)[number];
+export type SkillObservation = {
+    readonly signal: ObserverSignal;
+    readonly skillId: string;
+    readonly observed: string;
+    readonly proposal: string;
+    readonly applied: false;
+};
+export declare const OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED: "OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED";
+export declare const OBSERVER_RECORD_STATE_UNKNOWN: "OBSERVER_RECORD_STATE_UNKNOWN";
+export type SkillObserverErrorCode = "OBSERVER_PATH_UNSAFE" | "OBSERVER_LOG_UNSAFE" | "OBSERVER_LOG_PERMISSIONS_UNSAFE" | "OBSERVER_LOG_MALFORMED" | "OBSERVER_SHAPE_INVALID" | "OBSERVER_FIELD_UNKNOWN" | "OBSERVER_FIELD_MISSING" | "OBSERVER_SIGNAL_UNKNOWN" | "OBSERVER_SKILL_ID_INVALID" | "OBSERVER_TEXT_MISSING" | "OBSERVER_SECRET_REFUSED" | "OBSERVER_TEXT_INVALID" | "OBSERVER_APPLIED_INVALID" | "OBSERVER_LOG_SIZE_EXCEEDED" | "OBSERVER_WRITE_FAILED" | "OBSERVER_RECORD_TOO_LARGE" | "OBSERVER_LOCK_TIMEOUT" | "OBSERVER_LOCK_UNSAFE" | typeof OBSERVER_RECORD_STATE_UNKNOWN | typeof OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED;
+export declare const OBSERVER_LOG_MAX_BYTES = 1048576;
+export declare class SkillObserverError extends Error {
+    readonly code: SkillObserverErrorCode;
+    constructor(code: SkillObserverErrorCode, message: string);
+}
+export declare function observationLogPath(root: string): string;
+export declare function observerLockPath(root: string): string;
+export declare function recordObservation(root: string, observation: unknown): SkillObservation;
+export declare function readObservations(root: string): readonly SkillObservation[];