@nanonets/graft 0.24.0 → 0.24.1

package/dist/skills/validate.js

@@ -0,0 +1,112 @@
+/**
+ * What keeps a SKILL.md from being a valid Agent Skills file, in plain words.
+ *
+ * The rules are the spec's (agentskills.io/specification), as its reference
+ * validator (`skills-ref`) checks them, with one tightening: a name is ASCII
+ * only (a-z, 0-9 and single hyphens), since it is also a folder name on every
+ * machine that clones the repo. Its YAML reader (strictyaml) refuses a
+ * byte-order mark, flow style (`{ … }`, `[ … ]`), tags (`!!str`), anchors and
+ * aliases, so those are problems here too. Only `name`, `description`, `license`,
+ * `compatibility`, `allowed-tools` and `metadata` may sit at the top level;
+ * Trail keeps everything of its own, `version` included, under `metadata`, as
+ * flat strings.
+ *
+ * Pure: no I/O. CI also runs the reference validator over the fixtures in
+ * `test/fixtures/skills/`, which a test keeps equal to what Trail writes.
+ */
+import { matter } from "../util/front-matter.js";
+/** The top-level keys the spec allows. */
+export const SPEC_KEYS = ["name", "description", "license", "compatibility", "allowed-tools", "metadata"];
+export const NAME_MAX = 64;
+export const DESCRIPTION_MAX = 1024;
+export const COMPATIBILITY_MAX = 500;
+/** a-z and 0-9 in words joined by single hyphens. */
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A value in flow style or with a tag, after `key:` or `- `: text like `[draft]` mid-line, quoted, or on a folded line is not one. */
+const FLOW_OR_TAG = /^\s*(?:-\s+|[^\s'"#][^:'"]*:\s+)([[{!])/;
+/** The front matter between the opening `---` line and the closing one, or null when there isn't both. */
+function frontMatterBlock(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trimEnd() !== "---")
+        return null;
+    const close = lines.findIndex((l, i) => i > 0 && l.trimEnd() === "---");
+    return close === -1 ? null : lines.slice(1, close).join("\n");
+}
+function isMap(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
+}
+function nameProblems(name, folderName) {
+    if (typeof name !== "string" || !name.trim())
+        return ["`name` is missing: it must be text, the skill's folder name"];
+    const out = [];
+    if (name.length > NAME_MAX)
+        out.push(`\`name\` is ${name.length} characters: at most ${NAME_MAX}`);
+    if (name !== name.toLowerCase())
+        out.push("`name` must be lowercase");
+    if (name.startsWith("-") || name.endsWith("-"))
+        out.push("`name` can't start or end with a hyphen");
+    if (name.includes("--"))
+        out.push("`name` can't have two hyphens in a row");
+    if (!NAME.test(name) && /[^a-z0-9-]/.test(name.toLowerCase()))
+        out.push("`name` may hold only a-z, 0-9 and hyphens");
+    if (name !== folderName)
+        out.push(`\`name\` is "${name}" but its folder is "${folderName}": they must match`);
+    return out;
+}
+/**
+ * Every way `text` (a SKILL.md) breaks the spec, for a skill in the folder
+ * `folderName`. Empty when it is valid.
+ */
+export function skillProblems(text, folderName) {
+    if (text.startsWith("\uFEFF"))
+        return ["SKILL.md starts with a byte-order mark, which the reference validator reads as text before the opening `---`"];
+    const block = frontMatterBlock(text);
+    if (block === null)
+        return ["SKILL.md must open with YAML front matter between two `---` lines"];
+    // The reference validator splits the file on its first two `---`, wherever they are.
+    if (block.includes("---"))
+        return ["the front matter holds `---`, which ends it early for some readers"];
+    let data;
+    try {
+        const parsed = matter(text);
+        if (parsed.refused)
+            return [`the front matter isn't read: ${parsed.refused}`];
+        data = parsed.data;
+    }
+    catch {
+        return ["the front matter isn't valid YAML"];
+    }
+    if (!isMap(data))
+        return ["the front matter must be a YAML map"];
+    const odd = block.split("\n").map((l) => FLOW_OR_TAG.exec(l)?.[1]).find(Boolean);
+    if (odd)
+        return [odd === "!" ? "the front matter has a YAML tag (`!`): write the value as plain text" : "the front matter uses flow style (`{ … }` or `[ … ]`): write maps and lists as blocks, one item per line"];
+    const out = [];
+    const extra = Object.keys(data).filter((k) => !SPEC_KEYS.includes(k));
+    if (extra.length)
+        out.push(`only ${SPEC_KEYS.join(", ")} may sit at the top level; move ${extra.sort().join(", ")} under metadata`);
+    out.push(...nameProblems(data.name, folderName));
+    const description = data.description;
+    if (typeof description !== "string" || !description.trim())
+        out.push("`description` is missing: it must be text, what the skill does and when to use it");
+    else if (description.length > DESCRIPTION_MAX)
+        out.push(`\`description\` is ${description.length} characters: at most ${DESCRIPTION_MAX}`);
+    if ("compatibility" in data) {
+        const c = data.compatibility;
+        if (typeof c !== "string")
+            out.push("`compatibility` must be text");
+        else if (c.length > COMPATIBILITY_MAX)
+            out.push(`\`compatibility\` is ${c.length} characters: at most ${COMPATIBILITY_MAX}`);
+    }
+    if ("metadata" in data) {
+        const m = data.metadata;
+        if (!isMap(m))
+            out.push("`metadata` must be a map of names to quoted strings");
+        else
+            for (const [k, v] of Object.entries(m))
+                if (typeof v !== "string")
+                    out.push(`\`metadata.${k}\` must be a quoted string`);
+    }
+    return out;
+}
+//# sourceMappingURL=validate.js.map

package/dist/skills/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/skills/validate.ts"],"names":[],"mappings":"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"}

package/dist/skills/versions-fs.d.ts

@@ -0,0 +1,45 @@
+import { type Stats } from 'node:fs';
+import type { CompiledSkill, SkillRef } from './types.js';
+export declare const V_DIR: RegExp;
+export declare function versionsDir(ref: SkillRef): string;
+export declare const lst: (p: string) => Stats | null;
+/** The text of a regular file of at most 64 KB, never through a link; null otherwise (a FIFO is never opened). */
+export declare function regularText(path: string): string | null;
+/** A new file, written and synced (O_EXCL: never over something there). */
+export declare function writeSynced(path: string, data: string, mode?: number): void;
+export declare function syncDir(dir: string): void;
+/** A folder of ours, made 0700; a link or a file in its place refuses (throws). */
+export declare function ownDir(dir: string): void;
+export declare class LinkError extends Error {
+}
+/** The plain files of `from` (scripts/, lessons/) copied into a new folder `to`; links and folders inside are left out. */
+export declare function copyFlat(from: string, to: string, mode: number, only?: (name: string) => boolean): number;
+export declare const tmpName: (dir: string, tag: string) => string;
+/**
+ * `.versions/<name>/` holding `text` as SKILL.md (and `scripts` copied when given): written in a temp folder, synced,
+ * renamed into place. A folder already there with the same SKILL.md is reused; with other bytes, 'changed'.
+ */
+export declare function keepFolder(ref: SkillRef, name: string, text: string, scripts: string | null): 'kept' | 'same' | 'changed';
+/** The person's edited file kept as `hand-<date>` (`-2`, `-3` the same day; the same bytes reuse it), the last 3 kept. */
+export declare function keepHand(ref: SkillRef, text: string, now: Date): string;
+/** Removes the oldest folders matching `re` past `keep` (by version number, else by name), never `spare`. */
+export declare function prune(ref: SkillRef, re: RegExp, keep: number, spare?: string): void;
+export interface LessonFile {
+    name: string;
+    id: string;
+    guardrail: boolean;
+}
+/** The top-level lesson files of a skill folder, with the id and kind readLessons gives them. */
+export declare function lessonFiles(dir: string): LessonFile[];
+/** Moves lesson files into `to` (made 0700); a move that fails leaves the lesson riding the block, which is harmless. */
+export declare function moveLessons(dir: string, files: LessonFile[], to: string): void;
+export interface Swap {
+    undo: () => void;
+    done: () => void;
+}
+/** scripts/ replaced by the files in `from` (a folder) or `helpers`; `undo` puts the old ones back, `done` drops them. */
+export declare function swapScripts(ref: SkillRef, src: {
+    from?: string;
+    helpers?: CompiledSkill['helpers'];
+}): Swap;
+//# sourceMappingURL=versions-fs.d.ts.map

package/dist/skills/versions-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions-fs.d.ts","sourceRoot":"","sources":["../../src/skills/versions-fs.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkH,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAErJ,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAO1D,eAAO,MAAM,KAAK,QAAsB,CAAC;AAEzC,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,KAAK,GAAG,IAMvC,CAAC;AAGF,kHAAkH;AAClH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQvD;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAQ,GAAG,IAAI,CAS1E;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKzC;AAED,mFAAmF;AACnF,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIxC;AACD,qBAAa,SAAU,SAAQ,KAAK;CAAG;AAEvC,2HAA2H;AAC3H,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,CAYzG;AAED,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,WAA+D,CAAC;AAEhH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAkBzH;AAED,0HAA0H;AAC1H,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAWvE;AAED,6GAA6G;AAC7G,wBAAgB,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAWnF;AAKD,MAAM,WAAW,UAAU;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE;AAE5E,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAkBrD;AAED,yHAAyH;AACzH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAU9E;AAED,MAAM,WAAW,IAAI;IAAG,IAAI,EAAE,MAAM,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE;AAE5D,0HAA0H;AAC1H,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAAE,GAAG,IAAI,CAoC3G"}

package/dist/skills/versions-fs.js

@@ -0,0 +1,234 @@
+/**
+ * The file side of kept versions (versions.ts): plain reads that never
+ * follow a link or open a FIFO, synced writes, folders kept whole by temp
+ * folder and rename, pruning, lesson files by id and kind, and swapping a
+ * skill's scripts/ with a way back. Nothing here decides whether to write.
+ */
+import { randomBytes } from 'node:crypto';
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { MAX_SKILL_BYTES } from './store-fs.js';
+import { localDate } from './settings.js';
+import { matter } from '../util/front-matter.js';
+import { isGuardrailLesson } from './lessons.js';
+const HAND_KEPT = 3;
+export const V_DIR = /^v([1-9]\d{0,5})$/;
+export function versionsDir(ref) {
+    return join(ref.dir, '.versions');
+}
+export const lst = (p) => {
+    try {
+        return lstatSync(p);
+    }
+    catch {
+        return null;
+    }
+};
+/** The text of a regular file of at most 64 KB, never through a link; null otherwise (a FIFO is never opened). */
+export function regularText(path) {
+    const s = lst(path);
+    if (!s?.isFile() || s.size > MAX_SKILL_BYTES)
+        return null;
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** A new file, written and synced (O_EXCL: never over something there). */
+export function writeSynced(path, data, mode = 0o600) {
+    const fd = openSync(path, 'wx', mode);
+    try {
+        const buf = Buffer.from(data, 'utf8');
+        for (let off = 0; off < buf.length;)
+            off += writeSync(fd, buf, off, buf.length - off);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function syncDir(dir) {
+    try {
+        const fd = openSync(dir, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch { /* not every platform syncs a folder */ }
+}
+/** A folder of ours, made 0700; a link or a file in its place refuses (throws). */
+export function ownDir(dir) {
+    const s = lst(dir);
+    if (s && !s.isDirectory())
+        throw new LinkError(dir);
+    if (!s)
+        mkdirSync(dir, { mode: 0o700 });
+}
+export class LinkError extends Error {
+}
+/** The plain files of `from` (scripts/, lessons/) copied into a new folder `to`; links and folders inside are left out. */
+export function copyFlat(from, to, mode, only) {
+    if (!lst(from)?.isDirectory())
+        return 0;
+    let n = 0;
+    for (const name of readdirSync(from)) {
+        if (name.startsWith('.') || (only && !only(name)))
+            continue;
+        const s = lst(join(from, name));
+        if (!s?.isFile() || s.size > MAX_SKILL_BYTES)
+            continue;
+        if (!n)
+            mkdirSync(to, { mode: 0o700 });
+        writeSynced(join(to, name), readFileSync(join(from, name), 'utf8'), mode);
+        n++;
+    }
+    return n;
+}
+export const tmpName = (dir, tag) => join(dir, `.${tag}.tmp-${randomBytes(4).toString('hex')}`);
+/**
+ * `.versions/<name>/` holding `text` as SKILL.md (and `scripts` copied when given): written in a temp folder, synced,
+ * renamed into place. A folder already there with the same SKILL.md is reused; with other bytes, 'changed'.
+ */
+export function keepFolder(ref, name, text, scripts) {
+    const vdir = versionsDir(ref);
+    ownDir(vdir);
+    const at = join(vdir, name);
+    if (lst(at))
+        return regularText(join(at, 'SKILL.md')) === text && lst(at).isDirectory() ? 'same' : 'changed';
+    const tmp = tmpName(vdir, name);
+    mkdirSync(tmp, { mode: 0o700 });
+    try {
+        writeSynced(join(tmp, 'SKILL.md'), text);
+        if (scripts)
+            copyFlat(scripts, join(tmp, 'scripts'), 0o700);
+        syncDir(tmp);
+        renameSync(tmp, at);
+        syncDir(vdir);
+        return 'kept';
+    }
+    catch (e) {
+        rmSync(tmp, { recursive: true, force: true });
+        throw e;
+    }
+}
+/** The person's edited file kept as `hand-<date>` (`-2`, `-3` the same day; the same bytes reuse it), the last 3 kept. */
+export function keepHand(ref, text, now) {
+    const base = `hand-${localDate(now)}`;
+    for (let k = 1; k < 100; k++) {
+        const name = k === 1 ? base : `${base}-${k}`;
+        const r = keepFolder(ref, name, text, null);
+        if (r !== 'changed') {
+            prune(ref, /^hand-\d{4}-\d{2}-\d{2}(?:-\d+)?$/, HAND_KEPT, name);
+            return name;
+        }
+    }
+    throw new Error('trail: too many kept copies of this skill today');
+}
+/** Removes the oldest folders matching `re` past `keep` (by version number, else by name), never `spare`. */
+export function prune(ref, re, keep, spare) {
+    let names;
+    try {
+        names = readdirSync(versionsDir(ref)).filter((n) => re.test(n) && n !== spare && lst(join(versionsDir(ref), n))?.isDirectory());
+    }
+    catch {
+        return;
+    }
+    const key = (n) => V_DIR.exec(n)?.[1] ?? n;
+    names.sort((a, b) => key(a).localeCompare(key(b), 'en', { numeric: true }));
+    const extra = names.length + (spare ? 1 : 0) - keep;
+    for (const n of names.slice(0, Math.max(0, extra)))
+        rmSync(join(versionsDir(ref), n), { recursive: true, force: true });
+}
+/** The top-level lesson files of a skill folder, with the id and kind readLessons gives them. */
+export function lessonFiles(dir) {
+    let names;
+    try {
+        if (!lst(join(dir, 'lessons'))?.isDirectory())
+            return [];
+        names = readdirSync(join(dir, 'lessons')).filter((n) => n.endsWith('.md') && !n.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((name) => {
+        const text = regularText(join(dir, 'lessons', name));
+        if (text === null)
+            return [];
+        const fm = matter(text, { scalars: ['id', 'kind', 'skill', 'src', 'at', 'wall'] });
+        if (fm.refused)
+            return [];
+        const d = fm.data;
+        const id = typeof d.id === 'string' ? d.id : '';
+        const lesson = { text: String(fm.content ?? ''), kind: d.kind === 'guardrail' ? 'guardrail' : 'lesson' };
+        return [{ name, id, guardrail: isGuardrailLesson(lesson) }];
+    });
+}
+/** Moves lesson files into `to` (made 0700); a move that fails leaves the lesson riding the block, which is harmless. */
+export function moveLessons(dir, files, to) {
+    if (!files.length)
+        return;
+    try {
+        ownDir(to);
+    }
+    catch {
+        return;
+    }
+    for (const f of files) {
+        try {
+            renameSync(join(dir, 'lessons', f.name), join(to, f.name));
+        }
+        catch { /* stays where it was */ }
+    }
+}
+/** scripts/ replaced by the files in `from` (a folder) or `helpers`; `undo` puts the old ones back, `done` drops them. */
+export function swapScripts(ref, src) {
+    const scripts = join(ref.dir, 'scripts');
+    const s = lst(scripts);
+    if (s && !s.isDirectory())
+        throw new LinkError(scripts);
+    const tmp = tmpName(ref.dir, 'scripts');
+    mkdirSync(tmp, { mode: 0o700 });
+    try {
+        if (src.from)
+            copyFlat(src.from, join(tmp, 'new'), 0o700);
+        else {
+            mkdirSync(join(tmp, 'new'), { mode: 0o700 });
+            for (const h of src.helpers ?? []) {
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(h.file))
+                    throw new Error('trail: a helper script needs a plain file name');
+                writeSynced(join(tmp, 'new', h.file), h.content, 0o700);
+            }
+        }
+        if (!lst(join(tmp, 'new')))
+            mkdirSync(join(tmp, 'new'), { mode: 0o700 });
+        if (s)
+            renameSync(scripts, join(tmp, 'old'));
+        renameSync(join(tmp, 'new'), scripts);
+    }
+    catch (e) {
+        if (!lst(scripts) && lst(join(tmp, 'old')))
+            renameSync(join(tmp, 'old'), scripts);
+        rmSync(tmp, { recursive: true, force: true });
+        throw e;
+    }
+    return {
+        undo: () => {
+            try {
+                if (lst(join(tmp, 'old'))) {
+                    rmSync(scripts, { recursive: true, force: true });
+                    renameSync(join(tmp, 'old'), scripts);
+                }
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        },
+        done: () => rmSync(tmp, { recursive: true, force: true }),
+    };
+}
+//# sourceMappingURL=versions-fs.js.map

package/dist/skills/versions-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions-fs.js","sourceRoot":"","sources":["../../src/skills/versions-fs.ts"],"names":[],"mappings":"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"}

package/dist/skills/versions.d.ts

@@ -0,0 +1,56 @@
+import type { ChangeOp, CompiledSkill, FoldOp, SkillRef, SkillState } from './types.js';
+export { versionsDir } from './versions-fs.js';
+export declare const VERSIONS_KEPT = 10;
+export type VersionWhy = 'busy' | 'changed' | 'link' | 'io';
+/** Test seam: runs right before the write's state update (step 4), so a test can hold the state lock. */
+export declare const VERSION_SEAMS: {
+    beforeState?: () => void;
+};
+/** Kept version numbers, ascending: `v<n>` folders only (links and files skipped). */
+export declare function listVersions(ref: SkillRef): number[];
+/** The number the next written version gets: one past both the file's own and every kept one. */
+export declare function nextVersion(ref: SkillRef, current: number): number;
+/**
+ * 4.5: keeps the current file, writes `next` as the next version, updates state and the ledger. `next.meta.version`
+ * must be that next number (`nextVersion`), or nothing is written: the bytes written are the bytes shown.
+ */
+export declare function writeNewVersion(ref: SkillRef, next: CompiledSkill, o: {
+    op: ChangeOp;
+    offerId: string | null;
+    baseHash: string;
+    lessonIds?: string[];
+    env?: NodeJS.ProcessEnv;
+    now?: Date;
+}): {
+    ok: true;
+    version: number;
+} | {
+    ok: false;
+    why: 'busy' | 'changed' | 'link' | 'io';
+};
+/** 4.6: the proposal beside a hand-edited file, the person's file kept as hand-<date>. Never touches SKILL.md. */
+export declare function writeProposal(ref: SkillRef, next: CompiledSkill, op: FoldOp | 'replace', env?: NodeJS.ProcessEnv, now?: Date): {
+    path: string;
+    diff: string;
+    hand: string;
+    version: number;
+} | null;
+/**
+ * 4.6 and R8, from a read of the file (`candidatesHere`): a file equal to an unfinished write's hash finishes it; one
+ * equal to the state's hash clears a stale marker; one equal to the proposal is taken as Trail's own (adopted). True
+ * when the file was adopted. One compare when nothing is pending; the locks only on a match.
+ */
+export declare function adoptIfCopied(ref: SkillRef, st: SkillState | null, fileHash: string, env?: NodeJS.ProcessEnv, now?: Date): boolean;
+/**
+ * 4.12, person only (the CLI checks the terminal; the agent guard denies `restore-version`): `.versions/v<n>/` back
+ * as a new version. The current file is kept first (a hand-edited one as hand-<date>, R6). The restored file's
+ * `version` is rewritten to the new number through the round trip; one that doesn't round-trip goes back as it is.
+ */
+export declare function restoreVersion(ref: SkillRef, version: number, env?: NodeJS.ProcessEnv, now?: Date): {
+    ok: true;
+    version: number;
+} | {
+    ok: false;
+    why: 'unknown' | 'busy' | 'link' | 'io';
+};
+//# sourceMappingURL=versions.d.ts.map

package/dist/skills/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/skills/versions.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAaxF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAE5D,yGAAyG;AACzG,eAAO,MAAM,aAAa,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,CAAC;AAE9D,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,EAAE,CAYpD;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAoJD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAC9H,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,CASrJ;AAID,kHAAkH;AAClH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GACvI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAyBrE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CA+C9I;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,CAgBtM"}