@nanonets/graft 0.23.1 → 0.24.1

package/dist/skills/types.d.ts

@@ -0,0 +1,422 @@
+/**
+ * The shapes of learned skills: the SKILL.md metadata, compiled and parsed
+ * skills, their state and ledger lines, offers, receipts, the person's
+ * settings, and what a skills hook part hands back to the hook that writes.
+ *
+ * Types only.
+ */
+import type { GatedKind, JobClass, OfferChannel } from '../trace/types.js';
+export type Scope = 'personal' | 'repo' | 'team';
+export type SkillStatus = 'candidate' | 'active' | 'needs-fix' | 'retired';
+export type SkillFrom = 'init' | 'repeated' | 'repaired' | 'asked';
+/** Flat quoted strings under `metadata:` in SKILL.md. Key names are the YAML keys. */
+export interface SkillMeta {
+    trail: string;
+    scope: Scope;
+    applies?: string;
+    job?: JobClass;
+    asks: string;
+    'status-asks'?: string;
+    params?: string;
+    needs?: string;
+    ready?: string;
+    'check-first'?: string;
+    /** D116 item 5: ' | '-separated things the person does first (a login whose keystrokes the run fed, dropped from the steps). */
+    'before-you-start'?: string;
+    'confirm-before'?: string;
+    check?: string;
+    'check-shows'?: string;
+    /** D59b: the check is a deploy status tool the agent calls (e.g. 'get_deployment'); `check` then says what to read, not a command. */
+    'check-tool'?: string;
+    version: string;
+}
+export interface ParamDef {
+    name: string;
+    shape: 'version' | 'sha' | 'pr' | 'port' | 'branch' | 'date' | 'varied';
+    /** A literal, or a `$(...)` command for sha and date. */
+    default?: string;
+    /** Values seen in the run(s) it came from. Shapes only; never secret-flagged. */
+    seen: string[];
+}
+export interface SkillStep {
+    n: number;
+    cmd: string;
+    gated: GatedKind | null;
+    bg: boolean;
+    wait: boolean;
+    /** compile only: the tool_use ids it was copied from (the gate re-reads each, 4.9). */
+    from?: string[];
+}
+export interface CompiledSkill {
+    name: string;
+    title: string;
+    description: string;
+    meta: SkillMeta;
+    steps: SkillStep[];
+    check: string;
+    checkShows: string | null;
+    /** tests and query families: the check is also the last Run step (4.5 step 3). */
+    checkIsStep: boolean;
+    ifFails: string[];
+    dontUse: string;
+    params: ParamDef[];
+    helpers: Array<{
+        file: string;
+        from: string;
+        content: string;
+    }>;
+    leftOut: {
+        failed: number;
+        lookOnly: number;
+        duplicates: number;
+        plumbing: number;
+        work: number;
+    };
+    /** D58 b: steps that ran outside the repo, left out; shown in the draft with where they ran ("in api", "outside any repo"). */
+    elsewhere?: Array<{
+        cmd: string;
+        where: string;
+    }>;
+    /** D59a: the run a compaction cut, joined: how many compactions, when its first part began, the steps from before the last one. */
+    carried?: {
+        compactions: number;
+        startedAt: string;
+        steps: number[];
+    };
+    /** The run it was copied from, for the Stop use line (3.5 step 5) and `trail skills`. */
+    source: {
+        runId: string;
+        commands: number;
+        failed: number;
+        at: string;
+    };
+}
+export interface ParsedSkill {
+    name: string;
+    description: string;
+    meta: SkillMeta;
+    steps: SkillStep[];
+    check: string | null;
+    checkShows: string | null;
+    ifFails: string[];
+    dontUse: string;
+    params: ParamDef[];
+    hash: string;
+}
+export interface SkillRef {
+    id: string;
+    name: string;
+    scope: Scope;
+    applies: string | null;
+    dir: string;
+    file: string;
+}
+export interface SkillState {
+    name: string;
+    scope: Scope;
+    status: SkillStatus;
+    from: SkillFrom;
+    runId: string | null;
+    addedAt: string;
+    lastWorked: string | null;
+    lastUsedAt: string | null;
+    lastUsedRepo: string | null;
+    uses: number;
+    checkedUses: number;
+    hash: string;
+    source: {
+        commands: number;
+        failed: number;
+        at: string;
+    } | null;
+    /** The failed step of the last two uses, newest last; [] when the last use had no failed step (4.8). */
+    lastFails: Array<{
+        step: number;
+        at: string;
+    }>;
+    /** Why it is needs-fix, in words: 'step 4 failed on Nov 2 and Nov 4'. */
+    statusWhy?: string;
+    prevStatus?: SkillStatus;
+    /** D65: the SKILL.md hash when it was marked needs-fix. Only an edit after that mark (a hash other than this) brings it back. */
+    fixHash?: string;
+    promoteOffers: {
+        repo?: string;
+        team?: string;
+    };
+}
+export interface SkillsStateFile {
+    v: 1;
+    skills: Record<string, SkillState>;
+}
+export type Answer = 'yes' | 'no' | 'show' | 'none' | 'withdrawn';
+export interface OfferLine {
+    id: string;
+    at: string;
+    /** 1b: 'closed' lines come only from init (moment 'init', answer 'no', 4.20). */
+    event: 'shown' | 'answer' | 'not-shown' | 'closed';
+    repo: string;
+    key: string;
+    /** Phase 2: 'update', 'drift' and 'retire' (2.4); widened here because a field's type can't be widened by merging. */
+    moment: 'repeated' | 'repaired' | 'correction' | 'init' | 'update' | 'drift' | 'retire';
+    runId: string;
+    name: string;
+    channel: OfferChannel;
+    answer?: Answer;
+}
+/** Phase 2: cue 'run' (c10's `trail run` only), and the fidelity facts in LedgerUseFacts (2.3). */
+export type LedgerUse = {
+    at: string;
+    event: 'use';
+    useId: string;
+    skill: string;
+    v: string;
+    host: string;
+    cue: 'job' | 'name' | 'compact' | 'run';
+    repo: string;
+    stepsRan: number[];
+    failedStep: number | null;
+    readyFailed: string[];
+    check: 'passed' | 'failed' | 'none';
+    calls: number;
+    failed: number;
+} & LedgerUseFacts;
+export type LedgerLine = {
+    at: string;
+    event: 'saved';
+    skill: string;
+    v: string;
+    from: SkillFrom;
+    scope: Scope;
+    receipt: {
+        consent: 'offer-yes' | 'asked' | 'init';
+        stepsVerified: number;
+        stepsTotal: number;
+    };
+} | LedgerUse | LedgerLesson | LedgerCue | LedgerChanged | {
+    at: string;
+    event: 'corrected';
+    skill: string;
+    useId: string;
+} | {
+    at: string;
+    event: 'status';
+    skill: string;
+    from: SkillStatus;
+    to: SkillStatus;
+    /** Phase 2: 'retire-offer', the retire proposal's or drift's retire (2.3). */
+    reason: 'checked-use' | 'failed-twice' | 'forget' | 'restore' | 'retire-offer';
+};
+export interface TrailSkillSettings {
+    v: 1;
+    skills: 'on' | 'off';
+    onSince: string | null;
+    offers: 'on' | 'off';
+    offersOffAt: string | null;
+    offRepos: string[];
+    pausedUntil: Record<string, string>;
+    skillsOff: string[];
+    /** Cache of the governor window (4.13); offers.jsonl stays the truth. */
+    lastNine: Array<'yes' | 'no' | 'none'>;
+    governorSaidAt: string | null;
+}
+export interface Receipt {
+    v: 1;
+    session: string;
+    transcriptPath: string;
+    toolUseId: string;
+    runId: string;
+    name: string;
+    at: string;
+    host: string;
+    tier: 'A' | 'B' | 'C' | 'D';
+    consent: 'offer-yes' | 'asked' | 'none';
+    offerId: string | null;
+    /** The person's typed line that gave consent: its byte offset and the sha256 of the whole line. */
+    typed: {
+        offset: number;
+        lineSha: string;
+    } | null;
+    typedYes: boolean;
+    typedSave: boolean;
+    /** What the person's save request said about scope (asked saves only), for the CLI's line (D27). */
+    asked: 'this repo' | 'every repo' | 'repo' | 'team' | null;
+    stepsTotal: number;
+    stepsVerified: number;
+    verdict: 'live' | 'held';
+    heldWhy?: 'no-yes' | 'host';
+    /** D93: the checkout the PreToolUse half compiled the run in ('' for none); the CLI half uses it, never its own cwd. */
+    checkout?: string;
+    /** Set by the CLI when it acts on the receipt; a used receipt never counts again. */
+    usedAt: string | null;
+}
+/** What a skills hook part hands its caller, which writes one JSON object (0.2 `emitHook`). */
+export interface HookOut {
+    /** additionalContext: the agent reads it. */
+    context?: string;
+    /** systemMessage: the person sees it, the agent doesn't. */
+    notice?: string;
+    /** decision "block" with this reason (UserPromptSubmit: the prompt goes no further; Stop: the agent continues). */
+    block?: string;
+}
+/** A lesson kept on a skill (moment 4) or tied to a wall (moment 3). */
+export type LedgerLesson = {
+    at: string;
+    event: 'lesson';
+    skill: string;
+    lessonId: string;
+    src: 'correction' | 'repair';
+    consent: 'offer-yes';
+};
+/** An asks phrase that kept missing was dropped from the cue (4.19). The phrase is never written, only its sha (R30). */
+export type LedgerCue = {
+    at: string;
+    event: 'cue';
+    skill: string;
+    phraseSha: string;
+    change: 'dropped';
+};
+export interface SkillState {
+    /** phraseSha -> misses in a row (4.19, R30). Absent reads as {}. */
+    cueMisses?: Record<string, number>;
+    /** When skill_stale{unused} was sent. */
+    unusedSaidAt?: string | null;
+    /** When skill_stale{missing} was last sent (once a day, 4.18). */
+    missingSaidAt?: string | null;
+}
+/** receipts/<session-id>.keep.json: the PreToolUse half of a `trail keep` (4.9). */
+export interface KeepReceipt {
+    v: 1;
+    kind: 'keep';
+    session: string;
+    /** The very file the hooks read for this session (receiptTranscriptRead, D82). */
+    transcriptPath: string;
+    toolUseId: string;
+    /** Where the list was: the tool_result of a `trail init` call (its offset), or the handover the record names. */
+    list: {
+        offset: number;
+        initRunId: string;
+        via: 'init-call' | 'handover';
+    };
+    /** The first typed line after the list. */
+    typed: {
+        offset: number;
+        lineSha: string;
+    };
+    /** sha256 of the agent text between the list and the typed line, which named every item (4.9 step 3, R22). */
+    replySha: string;
+    /** What the command asked for. */
+    numbers: number[] | 'none' | 'all';
+    at: string;
+    verdict: 'live' | 'held';
+    heldWhy?: 'no-answer' | 'numbers' | 'not-shown' | 'host';
+    usedAt: string | null;
+}
+/** receipts/<session-id>.lesson.json: the PreToolUse half of a lesson save (4.15). */
+export interface LessonReceipt {
+    v: 1;
+    kind: 'lesson';
+    session: string;
+    transcriptPath: string;
+    toolUseId: string;
+    offerId: string;
+    /** null for a moment-3 lesson (tied to a wall, no skill). */
+    skill: string | null;
+    /** The yes. */
+    typed: {
+        offset: number;
+        lineSha: string;
+    };
+    lessonSha: string;
+    at: string;
+    verdict: 'live' | 'held';
+    heldWhy?: 'no-yes' | 'changed' | 'host';
+    usedAt: string | null;
+}
+/** One block that came in for a job and was settled (4.9): followed when a step of it ran. Last 10, oldest first. */
+export interface Firing {
+    at: string;
+    followed: boolean;
+}
+/** What a fold changes (4.2): a step, steps added, or steps kept as their own skill. */
+export type FoldOp = 'update' | 'extend' | 'split';
+/** A write of the file Trail wrote (4.5): one ledger `changed` line each. A split is a save; a retire is a status line. */
+export type ChangeOp = 'update' | 'extend' | 'replace' | 'adopted' | 'restore-version';
+/** 4.1: what the next run did against the skill. Counts only. */
+export interface FidelityCounts {
+    ran: number;
+    missing: number;
+    extra: number;
+    changed: number;
+}
+export interface SkillState {
+    /** 4.9: settled job and name cue blocks, last 10, oldest first. Reset when the skill changes version. */
+    firings?: Firing[];
+    /** 4.6: the proposal Trail wrote beside a hand-edited file; adopted when the file becomes byte-equal to it. */
+    proposed?: {
+        hash: string;
+        version: number;
+        op: FoldOp | 'replace';
+        at: string;
+    } | null;
+    /** When Trail last changed the file (fold, replace, adopt, restore by version). */
+    changedAt?: string | null;
+    /** 4.5 (R8): a write in progress, so a crash between the file and the state is finished, not taken for a hand edit. */
+    pendingWrite?: {
+        hash: string;
+        from: number;
+        at: string;
+    } | null;
+}
+/** 2.3: the use line's fidelity facts, absent before phase 2. A 1b reader ignores them. */
+export interface LedgerUseFacts {
+    /** 4.1: counts only. */
+    fid?: FidelityCounts;
+    /** 8-hex shas of the compiled text of passing steps the skill lacks (`extraKey`), at most 4. Never the text. */
+    extraShas?: string[];
+    /** Steps that failed and were then done another way that passed, at most 4. */
+    changedSteps?: number[];
+    /** D137: gated steps this session couldn't ask for, handed to the person to run (counted in stepsRan). */
+    handed?: number[];
+}
+/** A change to the file Trail wrote, one per write (4.5, 2.3). */
+export type LedgerChanged = {
+    at: string;
+    event: 'changed';
+    skill: string;
+    op: ChangeOp;
+    from: number;
+    to: number;
+    offerId: string | null;
+    lessonIds?: string[];
+};
+export interface OfferLine {
+    /** 2.4: on an answer line, what the yes chose: a fold op, drift's 'replace', or 'retire' (drift's or the retire proposal's). */
+    op?: FoldOp | 'replace' | 'retire';
+}
+/** receipts/<session-id>.update.json: the PreToolUse half of `trail skills update` (4.11). No step text, only the two hashes. */
+export interface UpdateReceipt {
+    v: 1;
+    kind: 'update';
+    session: string;
+    /** The very file the hooks read for this session (receiptTranscriptRead, D82). */
+    transcriptPath: string;
+    toolUseId: string;
+    host: string;
+    offerId: string;
+    skillId: string;
+    name: string;
+    runId: string;
+    op: FoldOp | 'replace';
+    /** The SKILL.md hash the plan was computed from. */
+    baseHash: string;
+    /** 4.11: sha256 of the proposed file text, 16 hex. */
+    proposalSha: string;
+    /** The yes. */
+    typed: {
+        offset: number;
+        lineSha: string;
+    };
+    at: string;
+    usedAt: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/skills/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":""}

package/dist/skills/validate.d.ts

@@ -0,0 +1,11 @@
+/** The top-level keys the spec allows. */
+export declare const SPEC_KEYS: readonly string[];
+export declare const NAME_MAX = 64;
+export declare const DESCRIPTION_MAX = 1024;
+export declare const COMPATIBILITY_MAX = 500;
+/**
+ * Every way `text` (a SKILL.md) breaks the spec, for a skill in the folder
+ * `folderName`. Empty when it is valid.
+ */
+export declare function skillProblems(text: string, folderName: string): string[];
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/skills/validate.ts"],"names":[],"mappings":"AAkBA,0CAA0C;AAC1C,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAAqF,CAAC;AAE7H,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAgCrC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAwCxE"}

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"}