mcp-memory-bucket 0.1.0

package/dist/src/shared/relocate.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isValidSkillName } from '../store/skill-name.js';
+const TICKET_PATTERN = /([A-Z]{2,10}-\d+)/i;
+/**
+ * Infers key/doc_type/description from a filename following the existing
+ * plan/spec naming convention, e.g.
+ * "2026-08-12-pde-433-partner-configuration-management-v3.md" under a
+ * "plans/" folder → { key: "PDE-433", doc_type: "plan", description: "partner configuration management v3" }.
+ * Returns null on a weak/ambiguous match — caller must not guess or partially move.
+ */
+export function inferMemoryFrontmatter(filePath) {
+    const base = path.basename(filePath, path.extname(filePath));
+    const ticketMatch = base.match(TICKET_PATTERN);
+    if (!ticketMatch)
+        return null;
+    const key = ticketMatch[1].toUpperCase();
+    const parentDir = path.basename(path.dirname(filePath)).toLowerCase();
+    const ext = path.extname(filePath).toLowerCase();
+    let docType = 'other';
+    if (ext === '.sql')
+        docType = 'sql';
+    else if (parentDir.includes('plan'))
+        docType = 'plan';
+    else if (parentDir.includes('spec') || parentDir.includes('design'))
+        docType = 'spec';
+    else if (parentDir.includes('test'))
+        docType = 'testing-todo';
+    // Remainder of the slug after the date prefix and ticket token, de-hyphenated.
+    const withoutDate = base.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+    const withoutTicket = withoutDate.replace(new RegExp(ticketMatch[1], 'i'), '');
+    const description = withoutTicket
+        .replace(/^-+|-+$/g, '')
+        .replace(/-+/g, ' ')
+        .trim();
+    if (!description)
+        return null; // nothing left to distinguish this doc — ambiguous
+    return { key, key_type: 'ticket', doc_type: docType, description };
+}
+export function relocate(opts, skillRepo, memoryRepo) {
+    if (!fs.existsSync(opts.path) || !fs.statSync(opts.path).isFile()) {
+        return { moved: false, reason: `file not found or not readable: ${opts.path}` };
+    }
+    const body = fs.readFileSync(opts.path, 'utf-8').trim();
+    if (opts.target === 'skill') {
+        const name = opts.overrides?.name ?? slugFromFilename(opts.path);
+        const description = opts.overrides?.description;
+        // The spec requires description to state what the skill does AND when to
+        // use it — that can't be responsibly guessed from a filename, unlike a
+        // slug-derived name. Require it explicitly rather than writing a filler
+        // description that would never trigger discovery correctly.
+        if (!name || !isValidSkillName(name)) {
+            return { moved: false, reason: `could not infer a valid skill name from filename — provide overrides.name (lowercase, hyphenated, <=64 chars)` };
+        }
+        if (!description) {
+            return { moved: false, reason: 'skill description cannot be inferred from a filename — provide overrides.description (what it does and when to use it)' };
+        }
+        const doc = skillRepo.create({
+            name,
+            description,
+            owner: null,
+            status: opts.overrides?.status ?? 'unreviewed',
+            tags: opts.overrides?.tags ?? [],
+            trigger_phrases: [],
+            extends: null,
+        }, body, opts.overrides?.folder);
+        if (!opts.keep_original)
+            fs.unlinkSync(opts.path);
+        return { moved: true, id: doc.name, target: 'skill' };
+    }
+    // target === 'memory'
+    const inferred = inferMemoryFrontmatter(opts.path);
+    const key = opts.overrides?.key ?? inferred?.key;
+    const description = opts.overrides?.description ?? inferred?.description;
+    const docType = opts.overrides?.doc_type ?? inferred?.doc_type ?? 'other';
+    const keyType = opts.overrides?.key_type ?? inferred?.key_type ?? 'freeform';
+    if (!key || !description) {
+        return {
+            moved: false,
+            reason: `filename does not clearly match the ticket-key naming pattern — ask the user for an explicit key and description, then retry with overrides.key/overrides.description`,
+        };
+    }
+    const already = memoryRepo.getByKey(key, docType).find((d) => d.description === description);
+    if (already) {
+        return { moved: false, reason: `already relocated as memory doc "${already.id}"`, id: already.id, target: 'memory' };
+    }
+    const doc = memoryRepo.create({
+        key,
+        key_type: keyType,
+        doc_type: docType,
+        description,
+        body,
+        tags: opts.overrides?.tags,
+        folder: opts.overrides?.folder,
+    });
+    if (!opts.keep_original)
+        fs.unlinkSync(opts.path);
+    return { moved: true, id: doc.id, target: 'memory' };
+}
+function slugFromFilename(filePath) {
+    return path
+        .basename(filePath, path.extname(filePath))
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}

package/dist/src/skills/builtin/memory-bucket-authoring/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: "memory-bucket-authoring"
+description: "Explains how to author and use skills and memory docs through the memory-bucket MCP server's skill_*/memory_*/relocate tools — the skill.md frontmatter schema (agentskills.io standard), the memory frontmatter schema, and when to use each. Use whenever a memory-bucket MCP server is connected and you need to create, update, or decide between a skill and a memory doc, or when the user asks to save a plan/spec/session summary or to record a reusable pattern."
+tags: ["memory-bucket", "meta", "authoring"]
+trigger_phrases: ["save this as a skill", "save this to memory", "remember this plan", "create a skill", "memory-bucket"]
+metadata:
+  owner: "company"
+  status: "stable"
+---
+
+## Two namespaces, two different jobs
+
+If a `memory-bucket` MCP server is connected, it exposes two tool
+families backed by markdown+frontmatter files:
+
+- **`skill_*`** — reusable, evergreen coding patterns. Found by keyword
+  search. Use for: a convention, a component pattern, an idiom you'd want
+  to reuse across many unrelated pieces of work.
+- **`memory_*`** — point-in-time working context (plans, specs, SQL,
+  testing notes, session summaries) attached to a key (usually a ticket
+  ID, sometimes a free-form name like "Spot Chart Design"). Found by
+  exact key lookup, not search. Use for: anything tied to one specific
+  piece of work that won't be relevant once that work ships.
+
+If you're unsure which one applies: would this be useful on a totally
+different ticket next month with no connection to today's task? Skill.
+Is it specific to what's happening right now? Memory.
+
+## Authoring a skill
+
+A skill is a **folder** containing a `SKILL.md` file, per the
+[agentskills.io](https://agentskills.io) open standard — the same format
+Claude Code, Cursor, and other agents read directly off disk, independent
+of this MCP server. `skill_create` writes exactly this shape for you; you
+don't need to construct the file yourself.
+
+Required frontmatter:
+
+```yaml
+---
+name: "lit-dropdown-component"   # 1-64 chars, lowercase letters/numbers/hyphens only,
+                                   # no leading/trailing/consecutive hyphens.
+                                   # This becomes the containing folder's name.
+description: "Builds a dropdown component in Lit with keyboard navigation and ARIA roles. Use when the user asks for a dropdown, select, or combobox component in a Lit-based frontend."
+---
+```
+
+**`description` is the single most important field.** It's the only
+thing loaded into context at discovery time (along with `name`) — an
+agent scans it to decide whether the skill is relevant *before* ever
+reading the body. Write it to cover both what the skill does and when to
+use it, in the same sentence or two. "Helps with dropdowns" is too vague
+to trigger reliably; "Builds a dropdown component in Lit with keyboard
+navigation... use when the user asks for a dropdown, select, or combobox
+component" gives an agent something to pattern-match against.
+
+**Always write the description in third person** — "Processes X" or
+"Builds Y", never "I can help you..." or "You can use this to...". It's
+injected into the system prompt alongside every other skill's
+description, and an inconsistent point of view degrades discovery.
+
+**Naming**: prefer gerund form (`processing-pdfs`, `writing-tests`) or a
+plain noun phrase (`pdf-processing`, `lit-dropdown-component`) — both are
+fine, pick whichever reads more naturally for the pattern. Avoid vague or
+generic names a skill list can't be scanned by: `helper`, `utils`,
+`tools`, `data`, `files`.
+
+Optional frontmatter this project also supports:
+
+- `license`, `compatibility` — standard fields, rarely needed.
+- `tags`, `trigger_phrases` — arrays of extra keywords `skill_list`'s
+  keyword search matches against, beyond `description` itself.
+- `owner`, `status` (`stable`/`beta`/`unreviewed`), `extends` — stored
+  under `metadata` in the frontmatter (a string-keyed map the standard
+  reserves for exactly this kind of client-specific extension). `status`
+  defaults to `unreviewed` if omitted, so low-trust content doesn't read
+  as equivalent to a reviewed pattern.
+
+Call `skill_create(name, description, body, ...)`. Pass `folder` to place
+it under a subdirectory (e.g. `folder: "frontend"`) if the skill source
+tree is organized that way — check `skill_list()` or ask the user if
+you're not sure of the convention in this repo.
+
+### Writing the body
+
+The agent reading a skill is already capable — don't explain things it
+already knows (what a PDF is, how a for-loop works). Before adding a
+sentence, ask "does this justify its token cost?" A concise 3-line code
+snippet beats a paragraph of preamble around it.
+
+Match how prescriptive you are to how fragile the task is:
+
+- **High freedom** (numbered steps, heuristics) — when multiple valid
+  approaches exist and judgment matters, e.g. "review this code for
+  bugs."
+- **Medium freedom** (a template or parameterized snippet) — when a
+  preferred pattern exists but some variation is fine.
+- **Low freedom** (an exact command, "do not modify this") — when the
+  operation is fragile or must run in an exact sequence, e.g. a
+  migration script.
+
+Other things that reliably improve a skill:
+
+- Use one term for one concept throughout (always "field", never a mix
+  of "field"/"box"/"control") — inconsistent vocabulary makes the
+  instructions harder to follow.
+- Avoid time-sensitive claims ("before/after March 2026, use X") since
+  they silently rot; if a pattern is genuinely deprecated, name the
+  current approach first and fold the old one into a clearly-labeled
+  "legacy" aside instead of a date-gated branch.
+- Don't enumerate every possible library/approach — give one good
+  default plus, if truly needed, a named escape hatch for the exception
+  case. "You can use pypdf, or pdfplumber, or PyMuPDF, or..." is worse
+  than just picking one.
+- If the body instructs calling another MCP server's tool, use the fully
+  qualified `ServerName:tool_name` form so it isn't ambiguous which
+  server owns it.
+
+### Keeping SKILL.md small (progressive disclosure)
+
+Keep the `SKILL.md` body itself under ~500 lines; it's loaded in full
+once the skill is activated, so move anything long (detailed reference
+tables, big code samples) into files the body links to, if the host
+environment supports bundling extra files alongside `SKILL.md`.
+
+When you do split content out:
+
+- **Link only one level deep from `SKILL.md` itself.** A reference file
+  that links to another reference file risks a shallow partial read (the
+  agent may `head` it instead of reading in full) and losing information.
+  Put every reference file's link directly in `SKILL.md`, even if that
+  means `SKILL.md` links to several files.
+- If a linked-out reference file runs past ~100 lines, put a short table
+  of contents at its top so a partial read still reveals what's there.
+
+## Authoring a memory doc
+
+Every memory doc needs a `key` (the lookup handle) and a `description`
+(what distinguishes it from other docs sharing that key):
+
+```yaml
+---
+key: "RMXS-14"                # normalized on write: uppercase, hyphenated
+key_type: "ticket"            # "ticket" for a real ticket ID, "freeform" for names like "Spot Chart Design"
+doc_type: "plan"              # plan | spec | sql | testing-todo | discovery | session-summary | other
+description: "Bulk edit plan for product boost"
+---
+```
+
+Call `memory_create(key, key_type, doc_type, description, body, ...)`.
+One key commonly accumulates several docs over time — a plan, then a
+spec, then SQL from a debugging session, then a session summary — all
+retrievable together via `memory_get(key)`, or narrowed with
+`memory_get(key, doc_type)`.
+
+**Never infer the key from environment state** (branch name, current
+directory, etc.) — always get it from what the user actually said in
+conversation, or ask if it's genuinely unclear.
+
+### Saving a session
+
+If the user asks to save the current conversation/session as memory, use
+`memory_save_session(summary, key, description, tags?)` — pass a
+**summary**, not a raw transcript. If `key` or `description` weren't
+given, ask for both before calling it; don't guess a key from context.
+
+## relocate: pulling in an existing file
+
+If there's already a local markdown file that should become a skill or
+memory doc — the user says something like "save this file as memory" or
+"turn this into a skill" — use `relocate(path, target, overrides?)`
+instead of reading the file yourself and calling `*_create`. It infers
+what it can from the filename and moves (not copies, by default) the
+file into place.
+
+- For `target: "memory"`, it tries to infer `key`/`doc_type`/`description`
+  from filenames like `2026-08-12-pde-433-partner-configuration-v3.md`
+  (date + ticket + slug), and does **nothing** — no partial move, no
+  guess — if the filename doesn't clearly match. If that happens, ask the
+  user for the key and description, then retry with
+  `overrides.key`/`overrides.description`.
+- For `target: "skill"`, the name can usually be inferred from the
+  filename, but `overrides.description` is required — a good description
+  needs real content a filename can't provide, so don't try to invent one
+  yourself either; ask the user what the skill does and when to use it.
+- Safe to re-run on the same file/target: if a matching doc already
+  exists, it reports that instead of duplicating.

package/dist/src/skills/repository.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeMarkdownFile } from '../store/markdown-file.js';
+import { assertValidSkillName } from '../store/skill-name.js';
+import { resolveWithinBase } from '../store/safe-path.js';
+import { upsertFile, removeFile, skillSyncSpec } from '../store/sync.js';
+function rowToDoc(row) {
+    return {
+        name: row.id,
+        description: row.description,
+        tags: JSON.parse(row.tags),
+        trigger_phrases: JSON.parse(row.trigger_phrases),
+        metadata: { owner: row.owner, status: row.status, extends: row.extends },
+        source_path: row.source_path,
+        body: row.body,
+    };
+}
+export class SkillRepository {
+    db;
+    sourceDir;
+    syncSpec;
+    constructor(db, sourceDir) {
+        this.db = db;
+        this.sourceDir = sourceDir;
+        this.syncSpec = skillSyncSpec([sourceDir]);
+    }
+    list(query) {
+        const rows = this.db
+            .prepare(`SELECT id, description, owner, status, tags, trigger_phrases FROM skills`)
+            .all();
+        const needle = query?.trim().toLowerCase();
+        const items = rows.map((r) => ({
+            name: r.id,
+            description: r.description,
+            owner: r.owner,
+            status: r.status,
+            tags: JSON.parse(r.tags),
+            triggerPhrases: JSON.parse(r.trigger_phrases),
+        }));
+        const filtered = needle
+            ? items.filter((item) => item.description.toLowerCase().includes(needle) ||
+                item.tags.some((t) => t.toLowerCase().includes(needle)) ||
+                item.triggerPhrases.some((t) => t.toLowerCase().includes(needle)))
+            : items;
+        return filtered.map(({ triggerPhrases: _tp, ...rest }) => rest);
+    }
+    get(name) {
+        const row = this.db.prepare(`SELECT * FROM skills WHERE id = ?`).get(name);
+        return row ? rowToDoc(row) : null;
+    }
+    /**
+     * Creates <sourceDir>/[folder/]<name>/SKILL.md — folder-per-skill, per the
+     * agentskills.io spec (`name` must equal the containing folder's name).
+     */
+    create(frontmatter, body, folder) {
+        assertValidSkillName(frontmatter.name);
+        if (this.get(frontmatter.name)) {
+            throw new Error(`skill with name "${frontmatter.name}" already exists`);
+        }
+        const skillDir = resolveWithinBase(this.sourceDir, folder, frontmatter.name);
+        if (fs.existsSync(skillDir)) {
+            throw new Error(`skill directory already exists at ${skillDir}`);
+        }
+        fs.mkdirSync(skillDir, { recursive: true });
+        const filePath = path.join(skillDir, 'SKILL.md');
+        const fm = {
+            name: frontmatter.name,
+            description: frontmatter.description,
+            license: frontmatter.license,
+            compatibility: frontmatter.compatibility,
+            tags: frontmatter.tags ?? [],
+            trigger_phrases: frontmatter.trigger_phrases ?? [],
+            metadata: {
+                owner: frontmatter.owner ?? null,
+                status: frontmatter.status ?? 'unreviewed',
+                extends: frontmatter.extends ?? null,
+            },
+            source_path: filePath,
+        };
+        writeMarkdownFile(filePath, stripSourcePath(fm), body);
+        upsertFile(this.db, this.syncSpec, filePath);
+        return { ...fm, body };
+    }
+    update(name, frontmatter, body) {
+        const existing = this.get(name);
+        if (!existing)
+            throw new Error(`skill with name "${name}" not found`);
+        const merged = {
+            ...existing,
+            ...frontmatter,
+            name: existing.name, // name is immutable post-creation (it's also the folder name)
+            metadata: {
+                ...existing.metadata,
+                owner: frontmatter?.owner !== undefined ? frontmatter.owner : existing.metadata.owner,
+                status: frontmatter?.status ?? existing.metadata.status,
+                extends: frontmatter?.extends !== undefined ? frontmatter.extends : existing.metadata.extends,
+            },
+        };
+        const newBody = body ?? existing.body;
+        writeMarkdownFile(existing.source_path, stripSourcePath(merged), newBody);
+        upsertFile(this.db, this.syncSpec, existing.source_path);
+        return { ...merged, body: newBody };
+    }
+    /**
+     * Renames a skill: moves <sourceDir>/[folder/]<oldName>/ to .../<newName>/ (keeping any
+     * scripts/references/assets alongside SKILL.md) and updates the `name` frontmatter field to match.
+     */
+    rename(name, newName) {
+        assertValidSkillName(newName);
+        const existing = this.get(name);
+        if (!existing)
+            throw new Error(`skill with name "${name}" not found`);
+        if (newName === name)
+            return existing;
+        if (this.get(newName)) {
+            throw new Error(`skill with name "${newName}" already exists`);
+        }
+        const oldDir = path.dirname(existing.source_path);
+        const newDir = path.join(path.dirname(oldDir), newName);
+        if (fs.existsSync(newDir)) {
+            throw new Error(`skill directory already exists at ${newDir}`);
+        }
+        fs.renameSync(oldDir, newDir);
+        const newFilePath = path.join(newDir, 'SKILL.md');
+        const merged = { ...existing, name: newName };
+        writeMarkdownFile(newFilePath, stripSourcePath(merged), existing.body);
+        removeFile(this.db, 'skills', existing.source_path);
+        upsertFile(this.db, this.syncSpec, newFilePath);
+        return { ...merged, body: existing.body };
+    }
+    /** Removes the whole skill directory, including any scripts/references/assets alongside SKILL.md. */
+    delete(name) {
+        const existing = this.get(name);
+        if (!existing)
+            throw new Error(`skill with name "${name}" not found`);
+        const skillDir = path.dirname(existing.source_path);
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        removeFile(this.db, 'skills', existing.source_path);
+    }
+}
+function stripSourcePath(fm) {
+    const { source_path: _sp, ...rest } = fm;
+    return rest;
+}

package/dist/src/skills/tools.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+const SKILL_STATUS = ['stable', 'beta', 'unreviewed'];
+const SKILL_NAME_DESCRIPTION = 'stable id, must be 1-64 chars, lowercase letters/numbers/hyphens only, no leading/trailing/consecutive hyphens — this becomes the skill\'s folder name (agentskills.io spec requirement)';
+const AUTHORING_SKILL_HINT = "Before your first call in a session, run skill_get(\"memory-bucket-authoring\") to learn the exact frontmatter schema and conventions — don't guess the shape.";
+export function registerSkillTools(mcp, repo) {
+    mcp.tool('skill_list', 'Lists skills (reusable coding patterns, one SKILL.md per folder per the agentskills.io open standard), optionally filtered by a keyword matched against description/tags/trigger phrases.', { query: z.string().optional() }, async ({ query }) => {
+        const items = repo.list(query);
+        return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
+    });
+    mcp.tool('skill_get', 'Fetches a single skill by name, including its full markdown body.', { name: z.string() }, async ({ name }) => {
+        const doc = repo.get(name);
+        if (!doc) {
+            return { content: [{ type: 'text', text: `No skill found with name "${name}"` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+    });
+    mcp.tool('skill_create', `Creates a new skill as <sourceDir>/[folder/]<name>/SKILL.md, per the agentskills.io open standard — a folder containing SKILL.md, optionally alongside scripts/references/assets subfolders you create separately on disk. ${AUTHORING_SKILL_HINT}`, {
+        name: z.string().describe(SKILL_NAME_DESCRIPTION),
+        description: z
+            .string()
+            .max(1024)
+            .describe('required by spec: what the skill does AND when to use it — this is what agents scan to decide relevance, so be specific'),
+        body: z.string().describe('markdown body of SKILL.md — the instructions, loaded only once the skill is activated'),
+        license: z.string().optional(),
+        compatibility: z.string().max(500).optional().describe('only needed if the skill has specific environment requirements'),
+        owner: z.string().optional().describe('squad or "company" — stored in frontmatter.metadata, unused for resolution in V0'),
+        status: z.enum(SKILL_STATUS).optional().describe('defaults to "unreviewed"; stored in frontmatter.metadata'),
+        tags: z.array(z.string()).optional(),
+        trigger_phrases: z.array(z.string()).optional(),
+        extends: z.string().optional().describe('reserved for a future overlay mechanism — stored in frontmatter.metadata'),
+        folder: z.string().optional().describe('optional subdirectory under the skill source dir, e.g. "frontend"'),
+    }, async ({ name, description, body, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId, folder }) => {
+        try {
+            const doc = repo.create({ name, description, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId }, body, folder);
+            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('skill_update', `Edits an existing skill in place — frontmatter fields and/or body. Only provided fields change. Use skill_rename to change the name/folder. ${AUTHORING_SKILL_HINT}`, {
+        name: z.string(),
+        description: z.string().max(1024).optional(),
+        body: z.string().optional(),
+        license: z.string().optional(),
+        compatibility: z.string().max(500).optional(),
+        owner: z.string().optional(),
+        status: z.enum(SKILL_STATUS).optional(),
+        tags: z.array(z.string()).optional(),
+        trigger_phrases: z.array(z.string()).optional(),
+        extends: z.string().optional(),
+    }, async ({ name, body, ...frontmatterFields }) => {
+        try {
+            const doc = repo.update(name, frontmatterFields, body);
+            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('skill_rename', 'Renames a skill: moves its folder to the new name and updates the frontmatter `name` field to match, preserving any scripts/references/assets alongside SKILL.md.', {
+        name: z.string().describe('current skill name'),
+        new_name: z.string().describe(SKILL_NAME_DESCRIPTION),
+    }, async ({ name, new_name }) => {
+        try {
+            const doc = repo.rename(name, new_name);
+            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('skill_delete', 'Hard-deletes a skill by name — removes the whole skill folder (SKILL.md plus any scripts/references/assets), no tombstone.', { name: z.string() }, async ({ name }) => {
+        try {
+            repo.delete(name);
+            return { content: [{ type: 'text', text: `Deleted skill "${name}"` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+}

package/dist/src/store/db.js

@@ -0,0 +1,74 @@
+import Database from 'better-sqlite3';
+export function openCache(dbPath) {
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS skills (
+      id TEXT PRIMARY KEY,            -- == SKILL.md "name" field == parent folder name
+      description TEXT NOT NULL,      -- required by the agentskills.io spec
+      owner TEXT,
+      status TEXT NOT NULL,
+      tags TEXT NOT NULL,             -- JSON array
+      trigger_phrases TEXT NOT NULL,  -- JSON array
+      extends TEXT,
+      source_path TEXT NOT NULL UNIQUE, -- path to SKILL.md
+      body TEXT NOT NULL,
+      mtime_ms INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS memory_docs (
+      id TEXT PRIMARY KEY,
+      key TEXT NOT NULL,
+      key_type TEXT NOT NULL,
+      description TEXT NOT NULL,
+      doc_type TEXT NOT NULL,
+      tags TEXT NOT NULL,             -- JSON array
+      status TEXT NOT NULL,
+      related_to TEXT,
+      source_path TEXT NOT NULL UNIQUE,
+      body TEXT NOT NULL,
+      mtime_ms INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_memory_docs_key ON memory_docs(key);
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
+      ref_table UNINDEXED,
+      ref_id UNINDEXED,
+      description,
+      body,
+      tags,
+      tokenize = 'porter unicode61'
+    );
+  `);
+    backfillSearchIndex(db);
+    return db;
+}
+/** One-time backfill for existing rows the first time search_index is introduced into a cache file. */
+function backfillSearchIndex(db) {
+    const { count: indexed } = db.prepare(`SELECT COUNT(*) as count FROM search_index`).get();
+    if (indexed > 0)
+        return;
+    const skillRows = db.prepare(`SELECT id, description, body, tags FROM skills`).all();
+    const memoryRows = db.prepare(`SELECT id, description, body, tags FROM memory_docs`).all();
+    if (skillRows.length === 0 && memoryRows.length === 0)
+        return;
+    const insert = db.prepare(`INSERT INTO search_index (ref_table, ref_id, description, body, tags) VALUES (?, ?, ?, ?, ?)`);
+    const insertAll = db.transaction(() => {
+        for (const row of skillRows) {
+            insert.run('skills', row.id, row.description, row.body, flattenTags(row.tags));
+        }
+        for (const row of memoryRows) {
+            insert.run('memory_docs', row.id, row.description, row.body, flattenTags(row.tags));
+        }
+    });
+    insertAll();
+}
+export function flattenTags(tagsJson) {
+    try {
+        return JSON.parse(tagsJson).join(' ');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/src/store/markdown-file.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import matter from 'gray-matter';
+export function readMarkdownFile(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    const stat = fs.statSync(filePath);
+    return {
+        frontmatter: parsed.data,
+        body: parsed.content.trim(),
+        mtimeMs: stat.mtimeMs,
+    };
+}
+export function writeMarkdownFile(filePath, frontmatter, body) {
+    // js-yaml throws on `undefined` values rather than omitting them, so strip
+    // optional-but-unset fields (e.g. skill license/compatibility) before dump.
+    const cleaned = Object.fromEntries(Object.entries(frontmatter).filter(([, v]) => v !== undefined));
+    const content = matter.stringify(`${body}\n`, cleaned);
+    fs.writeFileSync(filePath, content, 'utf-8');
+}

package/dist/src/store/safe-path.js

@@ -0,0 +1,11 @@
+import path from 'node:path';
+/** Joins `baseDir` with an optional caller-supplied subfolder, rejecting any attempt to escape baseDir. */
+export function resolveWithinBase(baseDir, folder, fileName) {
+    const target = folder ? path.join(baseDir, folder, fileName) : path.join(baseDir, fileName);
+    const resolvedBase = path.resolve(baseDir);
+    const resolvedTarget = path.resolve(target);
+    if (resolvedTarget !== resolvedBase && !resolvedTarget.startsWith(resolvedBase + path.sep)) {
+        throw new Error(`folder "${folder}" escapes the source directory`);
+    }
+    return resolvedTarget;
+}

package/dist/src/store/skill-name.js

@@ -0,0 +1,11 @@
+// Per the agentskills.io spec: 1-64 chars, lowercase alphanumeric + hyphens,
+// no leading/trailing hyphen, no consecutive hyphens.
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function isValidSkillName(name) {
+    return name.length >= 1 && name.length <= 64 && SKILL_NAME_PATTERN.test(name);
+}
+export function assertValidSkillName(name) {
+    if (!isValidSkillName(name)) {
+        throw new Error(`invalid skill name "${name}": must be 1-64 chars, lowercase letters/numbers/hyphens only, no leading/trailing/consecutive hyphens`);
+    }
+}

package/dist/src/store/slug.js

@@ -0,0 +1,7 @@
+export function slugify(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}