usesteady 0.1.0-alpha.1

package/dist/src/skills/loader.js

@@ -0,0 +1,220 @@
+/**
+ * UseSteady Skills v1 — loader/scanner (file 4 of 8).
+ *
+ * Single responsibility: discover all SKILL.md files under a base directory,
+ * pipe each through the parser → validator chain, and return a sorted registry
+ * of accepted skills alongside a full list of structured rejections.
+ *
+ * Design rules:
+ *   - A broken skill produces a rejection entry and is skipped. It never
+ *     prevents other skills from loading (partial-failure guarantee).
+ *   - Accepted skills are sorted deterministically:
+ *       1. by kind (interpretation → workflow_generation → recovery)
+ *       2. then ascending priority (lower number = evaluated first)
+ *       3. then source path as a stable alphabetical tie-break
+ *   - Each rejection carries its file path, the pipeline stage that failed
+ *     (parser or validator), and the full structured issue list.
+ *   - No invocation logic, no audit writes, no side effects beyond I/O.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseSkillFile } from './parser.js';
+import { validateSkill } from './validator.js';
+import { SkillLoadError, ValidationError, } from './types.js';
+// ---------------------------------------------------------------------------
+// Directory traversal — manual recursive walk
+// ---------------------------------------------------------------------------
+/**
+ * Recursively collect the absolute paths of all files named exactly SKILL.md
+ * under `dir`. Results are sorted alphabetically so that the order passed to
+ * the parser/validator chain is deterministic before the priority sort.
+ *
+ * Uses a manual walk rather than readdir({ recursive: true }) to stay
+ * compatible across @types/node versions and keep the traversal explicit.
+ * Throws the raw fs error for the caller to wrap as SkillLoadError(SCAN_FAILED).
+ */
+async function findSkillFiles(dir) {
+    const results = [];
+    async function walk(current) {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile() && entry.name === 'SKILL.md') {
+                results.push(fullPath);
+            }
+        }
+    }
+    await walk(dir);
+    results.sort(); // deterministic baseline before priority ordering
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Sort helpers
+// ---------------------------------------------------------------------------
+/**
+ * Numeric order for each SkillKind.
+ * interpretation fires first (after parser null), recovery fires last.
+ * Implemented as an exhaustive switch rather than a Record lookup to avoid
+ * noUncheckedIndexedAccess issues.
+ */
+function kindOrder(kind) {
+    switch (kind) {
+        case 'interpretation': return 0;
+        case 'workflow_generation': return 1;
+        case 'recovery': return 2;
+    }
+}
+/**
+ * Comparator for the sorted registry.
+ * Tie-breaks at each level before falling through:
+ *   1. Kind order (integer, exhaustive)
+ *   2. Ascending priority (lower number = evaluated first within a kind)
+ *   3. Source path (stable locale-insensitive alphabetical)
+ */
+function compareSkills(a, b) {
+    const kindDiff = kindOrder(a.metadata.kind) - kindOrder(b.metadata.kind);
+    if (kindDiff !== 0)
+        return kindDiff;
+    const priorityDiff = a.metadata.priority - b.metadata.priority;
+    if (priorityDiff !== 0)
+        return priorityDiff;
+    return a.sourcePath.localeCompare(b.sourcePath, 'en', { sensitivity: 'base' });
+}
+// ---------------------------------------------------------------------------
+// Registry builder (exported — listed in spec's required functions)
+// ---------------------------------------------------------------------------
+/**
+ * Build a LoadedSkillRegistry from a list of accepted Skill objects.
+ *
+ * Skills are sorted once via compareSkills, then distributed into per-kind
+ * buckets using an exhaustive switch (no index-signature access, safe under
+ * noUncheckedIndexedAccess).
+ *
+ * The `loadedAt` timestamp is recorded here so that callers can compare
+ * registry age against source change timestamps if needed.
+ */
+export function buildRegistry(accepted) {
+    const sorted = [...accepted].sort(compareSkills);
+    const interpretationSkills = [];
+    const workflowSkills = [];
+    const recoverySkills = [];
+    for (const skill of sorted) {
+        switch (skill.metadata.kind) {
+            case 'interpretation':
+                interpretationSkills.push(skill);
+                break;
+            case 'workflow_generation':
+                workflowSkills.push(skill);
+                break;
+            case 'recovery':
+                recoverySkills.push(skill);
+                break;
+        }
+    }
+    return {
+        byKind: {
+            interpretation: interpretationSkills,
+            workflow_generation: workflowSkills,
+            recovery: recoverySkills,
+        },
+        all: sorted,
+        loadedAt: new Date(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Rejection factory
+// ---------------------------------------------------------------------------
+/**
+ * Convert any error thrown by parseSkillFile into a structured SkillRejection.
+ *
+ * ValidationError → the parser's own issue list is preserved as-is.
+ * SkillLoadError  → wrapped as a single unknown_error issue (file unreadable).
+ * Anything else   → wrapped as unknown_error (defensive catch-all).
+ */
+function makeParserRejection(filePath, err) {
+    if (err instanceof ValidationError) {
+        return {
+            sourcePath: filePath,
+            stage: 'parser',
+            issues: err.issues,
+        };
+    }
+    const message = err instanceof Error
+        ? err.message
+        : `Unexpected error during parse: ${String(err)}`;
+    return {
+        sourcePath: filePath,
+        stage: 'parser',
+        issues: [{ type: 'unknown_error', message }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Scan `baseDir` recursively for SKILL.md files, parse and validate each one,
+ * and return a sorted registry of accepted skills alongside a full rejection list.
+ *
+ * Partial-failure guarantee
+ * ─────────────────────────
+ * Each file is processed independently inside a try/catch. A parse failure,
+ * validation failure, or unexpected error for one file produces a SkillRejection
+ * and is skipped. Other files continue to load normally.
+ *
+ * The one unrecoverable case is if the directory itself cannot be read (ENOENT,
+ * EACCES, etc.) — that throws SkillLoadError(SCAN_FAILED) because there is
+ * nothing meaningful to return.
+ *
+ * @param baseDir Absolute path to the skills root directory.
+ *
+ * @throws SkillLoadError(SCAN_FAILED) if baseDir cannot be read.
+ */
+export async function scanSkillsDirectory(baseDir) {
+    // ── Discover SKILL.md files ────────────────────────────────────────────────
+    let skillFiles;
+    try {
+        skillFiles = await findSkillFiles(baseDir);
+    }
+    catch (cause) {
+        throw new SkillLoadError('SCAN_FAILED', baseDir, cause instanceof Error ? cause.message : String(cause));
+    }
+    // ── Process each file independently ───────────────────────────────────────
+    const accepted = [];
+    const rejections = [];
+    for (const filePath of skillFiles) {
+        // Parse stage — ValidationError and SkillLoadError are both rejections.
+        let parsed;
+        try {
+            parsed = await parseSkillFile(filePath);
+        }
+        catch (err) {
+            rejections.push(makeParserRejection(filePath, err));
+            continue;
+        }
+        // Validate stage — returns a discriminated result, never throws.
+        const result = validateSkill(parsed, filePath);
+        if (result.valid) {
+            accepted.push({
+                metadata: result.metadata,
+                body: parsed.body,
+                sourcePath: filePath,
+            });
+        }
+        else {
+            rejections.push({
+                sourcePath: filePath,
+                stage: 'validator',
+                issues: result.issues,
+            });
+        }
+    }
+    // ── Assemble result ────────────────────────────────────────────────────────
+    return {
+        registry: buildRegistry(accepted),
+        rejections,
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/skills/loader.js.map

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

package/dist/src/skills/local-recovery-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * UseSteady Skills v1 — local deterministic recovery adapter.
+ *
+ * ── Purpose ────────────────────────────────────────────────────────────────────
+ *
+ *   Implements SkillModelAdapter for the recovery skill kind WITHOUT calling
+ *   an LLM. Uses keyword detection and simple name extraction to produce
+ *   conservative, specific suggestions.
+ *
+ * ── Authority ──────────────────────────────────────────────────────────────────
+ *
+ *   Zero. This adapter:
+ *     - never executes anything
+ *     - never calls tools
+ *     - never bypasses approval or policy
+ *     - may only return suggestions that the deterministic parser can validate
+ *
+ * ── Design rules ───────────────────────────────────────────────────────────────
+ *
+ *   1. Every `input` in a suggestion MUST be parseable by normalizeIntent().
+ *      Do not suggest phrases the parser cannot handle.
+ *   2. Return `suggestions: []` when the input is too vague or no safe
+ *      suggestion exists. Never fabricate plausible-sounding but unsupported inputs.
+ *   3. This adapter only handles `usesteady.recovery_suggestions.v1` output.
+ *      For other skill output schemas it returns null (declined).
+ *   4. No LLM — all logic is deterministic regex/keyword matching.
+ *      A real LLM adapter can replace this when a model is available.
+ *
+ * ── Replacement plan ───────────────────────────────────────────────────────────
+ *
+ *   When an LLM is available, create an LlmRecoveryAdapter that also implements
+ *   SkillModelAdapter. Swap it in at server startup. This adapter stays as the
+ *   fallback for offline / zero-API-key environments.
+ */
+import type { Skill, SkillOutput } from './types.js';
+import type { SkillModelAdapter } from './invocation.js';
+/**
+ * LocalRecoveryAdapter — deterministic SkillModelAdapter for the recovery kind.
+ *
+ * Returns a RecoverySuggestionsOutput built from keyword analysis.
+ * Returns null (declined) for non-recovery skill output schemas.
+ *
+ * This adapter satisfies SkillModelAdapter and can be replaced by an
+ * LLM-backed adapter without changing any call sites.
+ */
+export declare class LocalRecoveryAdapter implements SkillModelAdapter {
+    invoke(skill: Skill, rawInput: string): Promise<SkillOutput | null>;
+}
+//# sourceMappingURL=local-recovery-adapter.d.ts.map

package/dist/src/skills/local-recovery-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-recovery-adapter.d.ts","sourceRoot":"","sources":["../../../src/skills/local-recovery-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAO,iBAAiB,CAAC;AAiJ1D;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;IACtD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAe1E"}

package/dist/src/skills/local-recovery-adapter.js

@@ -0,0 +1,184 @@
+/**
+ * UseSteady Skills v1 — local deterministic recovery adapter.
+ *
+ * ── Purpose ────────────────────────────────────────────────────────────────────
+ *
+ *   Implements SkillModelAdapter for the recovery skill kind WITHOUT calling
+ *   an LLM. Uses keyword detection and simple name extraction to produce
+ *   conservative, specific suggestions.
+ *
+ * ── Authority ──────────────────────────────────────────────────────────────────
+ *
+ *   Zero. This adapter:
+ *     - never executes anything
+ *     - never calls tools
+ *     - never bypasses approval or policy
+ *     - may only return suggestions that the deterministic parser can validate
+ *
+ * ── Design rules ───────────────────────────────────────────────────────────────
+ *
+ *   1. Every `input` in a suggestion MUST be parseable by normalizeIntent().
+ *      Do not suggest phrases the parser cannot handle.
+ *   2. Return `suggestions: []` when the input is too vague or no safe
+ *      suggestion exists. Never fabricate plausible-sounding but unsupported inputs.
+ *   3. This adapter only handles `usesteady.recovery_suggestions.v1` output.
+ *      For other skill output schemas it returns null (declined).
+ *   4. No LLM — all logic is deterministic regex/keyword matching.
+ *      A real LLM adapter can replace this when a model is available.
+ *
+ * ── Replacement plan ───────────────────────────────────────────────────────────
+ *
+ *   When an LLM is available, create an LlmRecoveryAdapter that also implements
+ *   SkillModelAdapter. Swap it in at server startup. This adapter stays as the
+ *   fallback for offline / zero-API-key environments.
+ */
+// ─── Noise / stop words stripped from name extraction ────────────────────────
+/**
+ * Words that are NOT candidate names. These are operation verbs, articles,
+ * structural prepositions, and type nouns (folder, file) that should not
+ * become part of a suggested path.
+ */
+const NOISE_WORDS = new Set([
+    // Operation verbs
+    'create', 'make', 'add', 'new', 'build', 'generate', 'set', 'up', 'setup',
+    'delete', 'remove', 'rm', 'erase', 'destroy', 'purge',
+    'rename', 'move', 'mv',
+    // Structural type nouns
+    'folder', 'directory', 'dir', 'file',
+    // Articles / determiners
+    'a', 'an', 'the', 'my', 'our', 'your', 'some', 'this', 'that',
+    // Prepositions / connectors
+    'for', 'to', 'in', 'at', 'on', 'from', 'into', 'of', 'with',
+    // Common filler
+    'it', 'one', 'please',
+]);
+/**
+ * Vague meta-words that must NOT become path suggestions.
+ * Returning them would fabricate invalid/harmful inputs.
+ */
+const VAGUE_NAMES = new Set([
+    'everything', 'all', 'files', 'stuff', 'things', 'anything', 'something',
+    'nothing', 'them', 'those', 'these', 'here', 'there', 'data', 'code',
+    'project', 'app', 'repo', 'repository', 'codebase',
+]);
+// ─── Name extraction ──────────────────────────────────────────────────────────
+/**
+ * Extract the most likely intended name/path from a raw input string.
+ *
+ * Strategy:
+ *   1. Strip common polite prefixes ("please", "can you", etc.).
+ *   2. If "called <X>" or "named <X>" anchor is present, use X (most reliable).
+ *   3. Remove all NOISE_WORDS.
+ *   4. Take the last remaining word (usually the specific identifier).
+ *   5. Return null if the result is a VAGUE_NAME or nothing is left.
+ *
+ * Returns null to signal "no safe name found — do not suggest".
+ */
+function extractLikelyName(rawInput) {
+    const lower = rawInput.toLowerCase().trim();
+    // Step 1 — strip polite prefix
+    const stripped = lower
+        .replace(/^(please\s+|can\s+you\s+|could\s+you\s+|i\s+(?:want\s+(?:to\s+)?|need\s+(?:to\s+)?)?)/, '')
+        .trim();
+    // Step 2 — "called/named X" anchor
+    const calledMatch = /\b(?:called|named)\s+(\S+)/.exec(stripped);
+    if (calledMatch?.[1]) {
+        const candidate = calledMatch[1];
+        return VAGUE_NAMES.has(candidate) ? null : candidate;
+    }
+    // Step 3+4 — remove noise, take last word
+    const words = stripped
+        .split(/\s+/)
+        .map(w => w.replace(/[^a-z0-9._/-]/g, '')) // keep path chars
+        .filter(w => w.length > 0 && !NOISE_WORDS.has(w));
+    if (words.length === 0)
+        return null;
+    const name = words[words.length - 1];
+    // Step 5 — reject vague names
+    return VAGUE_NAMES.has(name) ? null : name;
+}
+/**
+ * Analyse a raw input and produce 0–2 safe recovery suggestions.
+ *
+ * Returns [] (empty) when:
+ *   - no recognisable operation keyword is found
+ *   - the extracted name is vague or absent
+ *   - the operation is fundamentally unsupported
+ *
+ * All returned `input` values are parseable by the deterministic parser.
+ */
+function buildSuggestions(rawInput) {
+    const lower = rawInput.toLowerCase().trim();
+    if (!lower)
+        return [];
+    const isCreate = /\b(create|make|add|new|build|generate|set\s+up|setup)\b/.test(lower);
+    const isDelete = /\b(delete|remove|rm|erase)\b/.test(lower);
+    const isRename = /\b(rename|move|mv)\b/.test(lower);
+    const isDir = /\b(folder|directory|dir)\b/.test(lower);
+    const isFile = /\b(file)\b/.test(lower);
+    const name = extractLikelyName(rawInput);
+    // ── Creation ──────────────────────────────────────────────────────────────
+    if (isCreate) {
+        if (!name)
+            return []; // can't suggest without a name
+        if (isDir && !isFile) {
+            return [{ input: `create folder ${name}`, reason: 'Supported form for folder creation' }];
+        }
+        if (isFile && !isDir) {
+            return [{ input: `create file ${name}`, reason: 'Supported form for file creation' }];
+        }
+        // Ambiguous: suggest both (folder first — usually what natural language implies)
+        return [
+            { input: `create folder ${name}`, reason: 'If this should be a directory' },
+            { input: `create file ${name}`, reason: 'If this should be a file' },
+        ];
+    }
+    // ── Deletion ──────────────────────────────────────────────────────────────
+    if (isDelete) {
+        if (!name)
+            return [];
+        return [
+            { input: `delete file ${name}`, reason: 'If this is a file' },
+            { input: `delete folder ${name}`, reason: 'If this is a directory' },
+        ];
+    }
+    // ── Rename / move ─────────────────────────────────────────────────────────
+    if (isRename) {
+        if (!name)
+            return [];
+        return [
+            {
+                input: `rename ${name} to <new-name>`,
+                reason: 'Fill in the destination path to complete the rename',
+            },
+        ];
+    }
+    // Unrecognised operation — don't fabricate
+    return [];
+}
+// ─── Adapter implementation ───────────────────────────────────────────────────
+/**
+ * LocalRecoveryAdapter — deterministic SkillModelAdapter for the recovery kind.
+ *
+ * Returns a RecoverySuggestionsOutput built from keyword analysis.
+ * Returns null (declined) for non-recovery skill output schemas.
+ *
+ * This adapter satisfies SkillModelAdapter and can be replaced by an
+ * LLM-backed adapter without changing any call sites.
+ */
+export class LocalRecoveryAdapter {
+    async invoke(skill, rawInput) {
+        // Decline gracefully for non-recovery schemas.
+        // The invocation helper will record this as a rejection with reason "declined".
+        if (skill.metadata.output_schema !== 'usesteady.recovery_suggestions.v1') {
+            return null;
+        }
+        const suggestions = buildSuggestions(rawInput);
+        return {
+            schema: 'usesteady.recovery_suggestions.v1',
+            skill: { name: skill.metadata.name, version: skill.metadata.version },
+            suggestions,
+        };
+    }
+}
+//# sourceMappingURL=local-recovery-adapter.js.map

package/dist/src/skills/local-recovery-adapter.js.map

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

package/dist/src/skills/parser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * UseSteady Skills v1 — parser (file 2 of 8).
+ *
+ * Single responsibility: read a SKILL.md file from disk, split it into a YAML
+ * frontmatter block and a markdown body, parse the YAML with a zero-dependency
+ * minimal parser, and locate the five required body sections.
+ *
+ * This file does NOT validate. It only:
+ *   - extracts and structures content
+ *   - reports syntax errors (malformed YAML, missing delimiters)
+ *
+ * Type checking, spec compliance, and guardrail enforcement live in validator.ts.
+ *
+ * Throws:
+ *   SkillLoadError  (FILE_NOT_FOUND)    — file cannot be read from disk
+ *   ValidationError (invalid_markdown)  — frontmatter delimiters missing/malformed
+ *   ValidationError (invalid_yaml)      — YAML block cannot be parsed
+ */
+/**
+ * Extracted content for the five required body sections.
+ * Keys are absent (not undefined) when a section is not found in the body.
+ * The validator is responsible for treating absent sections as errors.
+ */
+export interface ParsedSections {
+    readonly purpose?: string;
+    readonly whenToUse?: string;
+    readonly outputContract?: string;
+    readonly guardrails?: string;
+    readonly examples?: string;
+}
+/**
+ * The structured output of a successful parse pass.
+ * `frontmatter` is deliberately typed as `unknown` — it is still untrusted raw
+ * data at this stage. The validator will narrow and enforce types.
+ */
+export interface ParsedSkillFile {
+    readonly frontmatter: unknown;
+    readonly body: string;
+    readonly sections: ParsedSections;
+}
+/**
+ * Read and parse a single SKILL.md file.
+ *
+ * Returns a `ParsedSkillFile` whose `frontmatter` field is an untyped object —
+ * all type checking and spec validation are deferred to the validator.
+ *
+ * Throws:
+ *   SkillLoadError  (FILE_NOT_FOUND)    — path cannot be read
+ *   ValidationError (invalid_markdown)  — delimiter syntax errors
+ *   ValidationError (invalid_yaml)      — YAML parse errors
+ */
+export declare function parseSkillFile(filePath: string): Promise<ParsedSkillFile>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/src/skills/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/skills/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAaH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAuWD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAuB/E"}