clementine-agent 1.18.109 → 1.18.110

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

@@ -57,6 +57,26 @@ export declare function getSkill(name: string, opts?: ListSkillsOptions): Skill
  *  Defends against directory traversal: rejects paths that escape the
  *  skill folder. */
 export declare function readBundledFile(skill: Skill, relPath: string): string | null;
+export interface MigrationResult {
+    ok: boolean;
+    /** Path to the new SKILL.md created. Undefined when ok=false. */
+    newSkillPath?: string;
+    /** Path the original .md was moved to (.bak). Undefined when ok=false. */
+    backupPath?: string;
+    /** Set when ok=false — what went wrong. */
+    error?: string;
+    /** Set when the loader found nothing to migrate (already folder-form). */
+    alreadyMigrated?: boolean;
+}
+/** Migrate one legacy flat skill to Anthropic-compatible folder form.
+ *  Idempotent: a folder-form skill is reported as alreadyMigrated. */
+export declare function migrateLegacySkill(name: string): MigrationResult;
+/** Migrate every legacy skill in the global pool. Returns per-skill
+ *  results so the dashboard can render a summary banner. */
+export declare function migrateAllLegacySkills(): {
+    migrated: MigrationResult[];
+    skipped: MigrationResult[];
+};
 /** Diagnostics for the dashboard — expose where the loader looked. */
 export declare function _skillDirsForDiagnostics(workDir?: string): {
     global: string;

package/dist/agent/skill-store.js

@@ -21,7 +21,7 @@
  * runner. Phase C wires runtime invocation. Phase E migrates legacy
  * crons → folder-form skills.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import matter from 'gray-matter';
@@ -161,6 +161,17 @@ function coerceClementineExtensions(raw) {
         out.lastUsed = r.lastUsed;
     if (typeof r.lastTestPass === 'string')
         out.lastTestPass = r.lastTestPass;
+    // Legacy Clementine concepts preserved through migration.
+    if (Array.isArray(r.triggers))
+        out.triggers = r.triggers.map(String);
+    if (typeof r.source === 'string')
+        out.source = r.source;
+    if (typeof r.useCount === 'number')
+        out.useCount = r.useCount;
+    if (typeof r.migratedFrom === 'string')
+        out.migratedFrom = r.migratedFrom;
+    if (typeof r.migratedAt === 'string')
+        out.migratedAt = r.migratedAt;
     return Object.keys(out).length > 0 ? out : undefined;
 }
 /** Coerce raw YAML object → SkillFrontmatter. Filename always wins for
@@ -471,6 +482,171 @@ export function readBundledFile(skill, relPath) {
         return null;
     }
 }
+// ── Legacy → folder-form migration ───────────────────────────────────
+//
+// Converts a flat-form legacy skill (`<name>.md` with title/triggers/
+// toolsUsed/useCount frontmatter) into Anthropic-compatible folder form
+// (`<name>/SKILL.md` with name+description top-level + clementine: namespace
+// for the migration metadata).
+//
+// Preserves everything:
+//   - title (legacy display name) → moves to top-level `title` (still readable)
+//   - triggers (NLP phrases) → clementine.triggers (preserved for reference)
+//   - toolsUsed → clementine.tools.allow (informational → enforced allowlist)
+//   - useCount + lastUsed → clementine.useCount + clementine.lastUsed
+//   - source → clementine.source
+//   - body → unchanged, written to <folder>/SKILL.md
+//
+// The original `<name>.md` is renamed to `<name>.md.bak` (kept on disk for
+// rollback). The bak is filtered out by isLoadableSkillFile so the dashboard
+// won't show it twice.
+import { renameSync } from 'node:fs';
+/** Migrate one legacy flat skill to Anthropic-compatible folder form.
+ *  Idempotent: a folder-form skill is reported as alreadyMigrated. */
+export function migrateLegacySkill(name) {
+    if (!name)
+        return { ok: false, error: 'name required' };
+    const dir = globalSkillsDir();
+    const flat = path.join(dir, name + '.md');
+    const folder = path.join(dir, name);
+    // Already folder-form → no-op.
+    if (existsSync(folder) && existsSync(path.join(folder, 'SKILL.md'))) {
+        return { ok: true, alreadyMigrated: true, newSkillPath: path.join(folder, 'SKILL.md') };
+    }
+    // Source file must exist.
+    if (!existsSync(flat))
+        return { ok: false, error: `legacy skill file not found: ${flat}` };
+    // Folder must NOT exist (collides with the rename target).
+    if (existsSync(folder))
+        return { ok: false, error: `target folder already exists: ${folder}` };
+    // Read + parse the legacy file.
+    let raw;
+    try {
+        raw = readFileSync(flat, 'utf-8');
+    }
+    catch (err) {
+        return { ok: false, error: 'failed to read source: ' + String(err) };
+    }
+    let parsed;
+    try {
+        parsed = matter(raw);
+    }
+    catch (err) {
+        return { ok: false, error: 'failed to parse YAML in source: ' + String(err) };
+    }
+    const data = parsed.data;
+    const body = parsed.content || '';
+    // Build the new frontmatter:
+    //   - name (always the filename)
+    //   - description (preserved from legacy)
+    //   - title (preserved as display alias)
+    //   - clementine.* — bucket all the legacy-only fields here
+    const newFm = {
+        name,
+    };
+    if (typeof data.description === 'string' && data.description.trim())
+        newFm.description = data.description;
+    if (typeof data.title === 'string' && data.title.trim() && data.title !== data.description) {
+        newFm.title = data.title;
+    }
+    const clementine = {};
+    if (Array.isArray(data.triggers) && data.triggers.length > 0) {
+        clementine.triggers = data.triggers.map(String);
+    }
+    if (Array.isArray(data.toolsUsed) && data.toolsUsed.length > 0) {
+        // Convert informational toolsUsed → enforced tools.allow. Authors can
+        // tighten by editing in Phase B.
+        clementine.tools = { allow: data.toolsUsed.map(String) };
+    }
+    if (typeof data.source === 'string' && data.source.trim())
+        clementine.source = data.source;
+    if (typeof data.useCount === 'number')
+        clementine.useCount = data.useCount;
+    if (typeof data.lastUsed === 'string')
+        clementine.lastUsed = data.lastUsed;
+    if (typeof data.createdAt === 'string')
+        clementine.createdAt = data.createdAt;
+    if (typeof data.updatedAt === 'string')
+        clementine.updatedAt = data.updatedAt;
+    // Stamp the migration provenance so future tooling can see where this
+    // came from.
+    clementine.migratedFrom = path.basename(flat);
+    clementine.migratedAt = new Date().toISOString();
+    clementine.version = 1;
+    if (Object.keys(clementine).length > 0)
+        newFm.clementine = clementine;
+    // Serialize: gray-matter handles YAML output. matter.stringify takes
+    // (content, data) → returns the full file with frontmatter.
+    const newContent = matter.stringify(body.startsWith('\n') ? body : '\n' + body, newFm);
+    // Create the folder + write SKILL.md.
+    try {
+        mkdirSync(folder, { recursive: true });
+        writeFileSync(path.join(folder, 'SKILL.md'), newContent);
+    }
+    catch (err) {
+        return { ok: false, error: 'failed to write new SKILL.md: ' + String(err) };
+    }
+    // Move the original to .bak so the loader stops surfacing it. We use
+    // <name>.md.bak which isLoadableSkillFile already filters out.
+    const backupPath = flat + '.bak';
+    try {
+        renameSync(flat, backupPath);
+    }
+    catch (err) {
+        // Roll back the folder we just created so we don't leave the user in
+        // a half-migrated state with both shapes for the same name.
+        try {
+            const fs = require('node:fs');
+            fs.unlinkSync(path.join(folder, 'SKILL.md'));
+            fs.rmdirSync(folder);
+        }
+        catch { /* best-effort */ }
+        return { ok: false, error: 'failed to rename original to .bak: ' + String(err) };
+    }
+    return {
+        ok: true,
+        newSkillPath: path.join(folder, 'SKILL.md'),
+        backupPath,
+    };
+}
+/** Migrate every legacy skill in the global pool. Returns per-skill
+ *  results so the dashboard can render a summary banner. */
+export function migrateAllLegacySkills() {
+    // Walk the dir directly so we don't trigger a full parse + validation.
+    const dir = globalSkillsDir();
+    const migrated = [];
+    const skipped = [];
+    if (!existsSync(dir))
+        return { migrated, skipped };
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return { migrated, skipped };
+    }
+    for (const entry of entries) {
+        if (!isLoadableSkillFile(entry))
+            continue;
+        const name = entry.replace(/\.md$/, '');
+        // Quickly check it's actually legacy — avoid migrating an Anthropic-
+        // form flat file that the user explicitly authored without a folder.
+        const filePath = path.join(dir, entry);
+        let isLegacy = false;
+        try {
+            const raw = readFileSync(filePath, 'utf-8');
+            const data = matter(raw).data;
+            isLegacy = ['title', 'triggers', 'toolsUsed', 'useCount', 'source'].some((k) => k in data);
+        }
+        catch { /* leave isLegacy=false */ }
+        if (!isLegacy) {
+            skipped.push({ ok: true, alreadyMigrated: true, newSkillPath: filePath });
+            continue;
+        }
+        migrated.push(migrateLegacySkill(name));
+    }
+    return { migrated, skipped };
+}
 /** Diagnostics for the dashboard — expose where the loader looked. */
 export function _skillDirsForDiagnostics(workDir) {
     return { global: globalSkillsDir(), project: projectSkillsDir(workDir) ?? null };

package/dist/cli/dashboard.js

@@ -4647,6 +4647,49 @@ export async function cmdDashboard(opts) {
             res.status(500).json({ ok: false, error: String(err) });
         }
     });
+    // ── Skill migration (legacy .md → folder/SKILL.md) ─────────────────
+    // Two endpoints: per-skill and bulk. Both wrap migrateLegacySkill /
+    // migrateAllLegacySkills from skill-store.ts. The original .md is
+    // renamed to .md.bak so the migration is rollback-able by hand.
+    app.post('/api/skills/:name/migrate', async (req, res) => {
+        try {
+            const name = req.params.name;
+            if (!name) {
+                res.status(400).json({ ok: false, error: 'name required' });
+                return;
+            }
+            const { migrateLegacySkill } = await import('../agent/skill-store.js');
+            const result = migrateLegacySkill(name);
+            if (!result.ok) {
+                res.status(409).json(result);
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/skills/migrate-all', async (_req, res) => {
+        try {
+            const { migrateAllLegacySkills } = await import('../agent/skill-store.js');
+            const result = migrateAllLegacySkills();
+            const failed = result.migrated.filter((m) => !m.ok);
+            const succeeded = result.migrated.filter((m) => m.ok && !m.alreadyMigrated);
+            res.json({
+                ok: true,
+                totalChecked: result.migrated.length + result.skipped.length,
+                migratedCount: succeeded.length,
+                failedCount: failed.length,
+                skippedCount: result.skipped.length,
+                migrated: result.migrated,
+                skipped: result.skipped,
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     app.get('/api/cron/drafts', async (_req, res) => {
         try {
             const { listDraftNames } = await import('../agent/draft-store.js');
@@ -26877,6 +26920,44 @@ var _skillsState = {
   query: '',         // search input value
 };
 
+// ── Migration handlers (Phase A.6 / 1.18.110) ────────────────────────
+// migrateOneSkill: per-skill migration from the detail-pane footer.
+// migrateAllLegacySkills: bulk migration from the list-pane banner.
+// Both use POST endpoints in dashboard.ts and refresh the page on success.
+
+async function migrateOneSkill(name) {
+  if (!confirm('Migrate "' + name + '" to folder form? The original .md file will be renamed to .md.bak (preserved for rollback).')) return;
+  try {
+    var r = await apiFetch('/api/skills/' + encodeURIComponent(name) + '/migrate', { method: 'POST' });
+    var d = await r.json().catch(function() { return {}; });
+    if (!r.ok || d.ok === false) {
+      toast(d.error || ('Migration failed (HTTP ' + r.status + ')'), 'error');
+      return;
+    }
+    toast(d.alreadyMigrated ? 'Already in folder form.' : 'Migrated. Folder created at ' + (d.newSkillPath || ''), 'success');
+    // Reload the skills list so the new layout reflects.
+    if (typeof refreshSkillsPage === 'function') await refreshSkillsPage();
+    if (name && typeof showSkillDetail === 'function') showSkillDetail(name);
+  } catch (err) { toast('Migration failed: ' + err, 'error'); }
+}
+
+async function migrateAllLegacySkills() {
+  if (!confirm('Migrate ALL legacy skills to folder form? Each .md file becomes <name>/SKILL.md, originals preserved as .bak.')) return;
+  try {
+    var r = await apiFetch('/api/skills/migrate-all', { method: 'POST' });
+    var d = await r.json().catch(function() { return {}; });
+    if (!r.ok || d.ok === false) {
+      toast(d.error || ('Bulk migration failed (HTTP ' + r.status + ')'), 'error');
+      return;
+    }
+    var msg = 'Migrated ' + d.migratedCount + ' skill' + (d.migratedCount === 1 ? '' : 's')
+      + (d.failedCount > 0 ? ' (' + d.failedCount + ' failed)' : '')
+      + (d.skippedCount > 0 ? ' (' + d.skippedCount + ' already in folder form)' : '');
+    toast(msg, d.failedCount > 0 ? 'error' : 'success');
+    if (typeof refreshSkillsPage === 'function') await refreshSkillsPage();
+  } catch (err) { toast('Bulk migration failed: ' + err, 'error'); }
+}
+
 async function refreshSkillsPage() {
   var listEl = document.getElementById('skills-list');
   var detailEl = document.getElementById('skills-detail');
@@ -26961,6 +27042,21 @@ function renderSkillsList() {
     return;
   }
   var html = '';
+  // PRD § Skills-First Phase A.6 / 1.18.110: legacy migration banner.
+  // Counts how many flat-form legacy skills exist; shows a one-click
+  // "Migrate all" button when ≥1 found. Banner disappears after they
+  // all become folder form. Per-skill migration also lives in the
+  // detail pane footer for individual control.
+  var legacyCount = _skillsState.data.filter(function(s) {
+    return s.layout === 'flat' && s.schemaVersion === 'legacy';
+  }).length;
+  if (legacyCount > 0 && !_skillsState.query) {
+    html += '<div style="padding:12px 14px;background:rgba(245,158,11,0.10);border-bottom:1px solid var(--yellow);font-size:11px;line-height:1.5;color:var(--text-secondary)">'
+      + '<div style="font-weight:600;color:var(--yellow);margin-bottom:6px">' + legacyCount + ' legacy skill' + (legacyCount === 1 ? '' : 's') + ' to migrate</div>'
+      + '<div style="margin-bottom:8px">Convert flat <code>.md</code> files to folder form (<code>name/SKILL.md</code>) so you can bundle templates + scripts + reference docs.</div>'
+      + '<button class="btn-sm btn-primary" onclick="migrateAllLegacySkills()" style="font-size:11px;padding:4px 10px">Migrate all to folder form</button>'
+      + '</div>';
+  }
   for (var i = 0; i < _skillsState.filtered.length; i++) {
     var s = _skillsState.filtered[i];
     var fm = s.frontmatter || {};
@@ -27157,7 +27253,11 @@ function renderSkillDetail(s) {
   if (s.schemaVersion === 'legacy') {
     html += '<div style="margin-top:24px;padding:12px 14px;background:rgba(245,158,11,0.08);border:1px solid var(--yellow);border-radius:6px;font-size:12px;color:var(--text-secondary);line-height:1.5">'
          + '<strong style="color:var(--yellow)">Legacy schema.</strong> '
-         + 'This skill uses the pre-redesign frontmatter shape. Phase B will offer a one-click migration to the Anthropic-compatible format (name + description top-level; cron-tailored fields under <code>clementine:</code>).'
+         + 'This skill uses the pre-redesign frontmatter shape. '
+         + 'Click <strong>Migrate to folder form</strong> below to convert it to <code>' + esc(fm.name) + '/SKILL.md</code> with the cron-tailored fields (triggers, toolsUsed, etc.) moved under a <code>clementine:</code> namespace. The original is preserved as a <code>.bak</code> file for rollback.'
+         + '<div style="margin-top:10px">'
+         +   '<button class="btn-sm btn-primary" onclick="migrateOneSkill(\\x27' + jsStr(fm.name) + '\\x27)" style="font-size:11px;padding:4px 12px">Migrate to folder form →</button>'
+         + '</div>'
          + '</div>';
   } else if (s.schemaVersion === 'anthropic' && s.layout === 'flat') {
     html += '<div style="margin-top:24px;padding:12px 14px;background:rgba(59,130,246,0.06);border:1px solid var(--blue);border-radius:6px;font-size:12px;color:var(--text-secondary);line-height:1.5">'

package/dist/types.d.ts

@@ -383,6 +383,20 @@ export interface ClementineSkillExtensions {
     lastUsed?: string;
     /** Last successful "Test this skill" run (Phase B). */
     lastTestPass?: string;
+    /** Legacy: NLP-style trigger phrases the pre-redesign chat router used
+     *  to match incoming messages against this skill. Preserved for the
+     *  migration UI; not enforced. */
+    triggers?: string[];
+    /** Legacy: 'manual' / 'auto' / 'imported' — provenance label on the
+     *  pre-redesign skills. */
+    source?: string;
+    /** Legacy: incrementing counter of runs that invoked the skill. */
+    useCount?: number;
+    /** Filename the original legacy skill was migrated from. Helps the
+     *  migration UI show what came from where. */
+    migratedFrom?: string;
+    /** ISO timestamp of when the migration ran. */
+    migratedAt?: string;
 }
 /** Parsed frontmatter. Anthropic-canonical fields are top-level; our
  *  extensions live under `clementine`. Legacy fields (title/triggers/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.109",
+  "version": "1.18.110",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",