clementine-agent 1.18.107 → 1.18.109

package/dist/agent/skill-store.d.ts

@@ -1,57 +1,63 @@
 /**
- * Skill store — Phase A (read-only) of the Skills-First redesign.
+ * Skill store — Phase A / A.5 of the Skills-First redesign.
  *
- * Discovers skill .md files from two locations and parses their
- * frontmatter into the Skill type. Phase A surfaces what's already on
- * disk; Phase B adds editing + testing; Phase C wires runtime invocation.
+ * Anthropic-compatible skill loader. Walks two skill directories and
+ * accepts both layouts:
  *
- * Discovery order:
- *   1. ~/.clementine/vault/00-System/skills/<name>.md  (global)
- *   2. <work_dir>/.clementine/skills/<name>.md         (per-project)
+ *   1. **Folder form** (Anthropic spec): <dir>/<skill-name>/SKILL.md
+ *      A capital-S SKILL.md is the entry point. Sibling .md files and
+ *      a scripts/ subdirectory are surfaced as bundled files.
  *
- * Per-project files win on name collision — they override global skills
- * for that project. The dashboard surfaces both pools and tags each
- * skill with its scope so the user can see which one will resolve.
+ *   2. **Flat form** (Clementine legacy): <dir>/<skill-name>.md
+ *      A single .md file with frontmatter + body. Bundled files
+ *      unsupported. Used by the 12 pre-redesign skill files we already
+ *      have on disk.
  *
- * Schema detection: a file is `v1` when its frontmatter declares any of
- * inputs / tools.allow / tools.deny / dataSources / stateKeys / success.
- * Otherwise (only legacy fields like title / triggers / toolsUsed) it's
- * `legacy` and the dashboard shows a migration badge.
+ * Discovery directories (per-project wins on name collision):
+ *   - global:      $CLEMENTINE_HOME/vault/00-System/skills/
+ *   - per-project: <work_dir>/.clementine/skills/
  *
- * Used-by join: Phase A reads the `skills:` array on CronJobDefinition
- * (the existing field) to populate Skill.usedByTriggers. Phase C will
- * extend this to read the new top-level `skill:` field on the trigger.
+ * Phase A is read-only. Phase B adds editing + a "Test this skill"
+ * runner. Phase C wires runtime invocation. Phase E migrates legacy
+ * crons → folder-form skills.
  */
-import type { Skill, SkillScope, CronJobDefinition } from '../types.js';
+import type { Skill, SkillScope, SkillValidationWarning, CronJobDefinition } from '../types.js';
+/** Run Anthropic-spec validations on a parsed skill. Errors are spec
+ *  violations (skill would be rejected by the Anthropic API); warnings
+ *  are best-practice hints (still loadable). Findings render in the
+ *  dashboard's detail pane. */
+export declare function validateSkill(skill: Skill): SkillValidationWarning[];
 interface ParseResult {
     skill: Skill;
     /** Set when the file existed but couldn't be parsed (bad YAML, etc.).
-     *  We still surface the file with a fallback frontmatter so the user
-     *  can see which one needs fixing. */
+     *  We still surface the skill with synthesized frontmatter so the
+     *  dashboard can render the offending file with an error banner. */
     parseError?: string;
 }
-/** Parse a single skill file. Returns a Skill record even when the
- *  frontmatter is malformed — the dashboard renders the parse error
- *  in-pane so the user can fix it without leaving the UI. */
+/** Parse a flat-form skill file (single .md). */
 export declare function parseSkillFile(filePath: string, scope: SkillScope): ParseResult;
+/** Parse a folder-form skill (Anthropic spec: <name>/SKILL.md plus optional
+ *  bundled files). The folder name is the canonical skill identifier. */
+export declare function parseSkillFolder(folderPath: string, scope: SkillScope): ParseResult;
 export interface ListSkillsOptions {
-    /** Optional per-project work_dir to also scan. Per-project skills
-     *  override global skills with the same filename. */
+    /** Optional per-project work_dir to scan. Per-project skills shadow
+     *  global ones with the same identifier. */
     projectWorkDir?: string;
-    /** Optional cron jobs list — when provided, the loader populates the
-     *  usedByTriggers field on each skill via the existing skills[] array
-     *  on CronJobDefinition (Phase A's join). */
+    /** Optional cron jobs for the usedByTriggers join (via skills[]). */
     jobs?: CronJobDefinition[];
 }
-/** Top-level discovery API. Returns the merged list of skills across
- *  global + per-project pools, with per-project taking precedence on
- *  name collision. usedByTriggers is populated when jobs are passed in. */
+/** Top-level discovery API. Merges global + per-project pools, with
+ *  per-project taking precedence. Populates usedByTriggers when jobs
+ *  are passed. Returned list is sorted alphabetically by name. */
 export declare function listSkills(opts?: ListSkillsOptions): Skill[];
-/** Get a single skill by name, with the same global/project precedence
- *  as listSkills. Returns null if neither pool has the skill. */
+/** Get one skill by name, applying per-project precedence. Returns
+ *  null when neither pool has the skill. */
 export declare function getSkill(name: string, opts?: ListSkillsOptions): Skill | null;
-/** Test-only: where the loader looked. Useful in unit tests + the
- *  dashboard's diagnostics surface. */
+/** Read one bundled file's contents — used by Phase B's preview pane.
+ *  Defends against directory traversal: rejects paths that escape the
+ *  skill folder. */
+export declare function readBundledFile(skill: Skill, relPath: string): string | null;
+/** Diagnostics for the dashboard — expose where the loader looked. */
 export declare function _skillDirsForDiagnostics(workDir?: string): {
     global: string;
     project: string | null;