@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/core/repl/store/types.js

@@ -0,0 +1,44 @@
+/**
+ * Persistent REPL session store — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * Public types consumed by the REPL session module + the `pugi sessions`
+ * / `pugi resume` dispatchers. Wire format is stable:
+ *
+ *   - `SessionRow` mirrors the SQLite `sessions` table one-to-one and is
+ *     also the JSON shape returned by `pugi sessions --json`. Field names
+ *     are camelCase (PascalCase types, camelCase fields per CLAUDE.md
+ *     conventions). The SQL columns themselves stay snake_case because
+ *     they originate from raw SQL.
+ *
+ *   - `SessionEvent` is the on-disk shape of one line in
+ *     `events.<n>.jsonl`. `kind` is a closed union; `payload` is an
+ *     opaque JSON value so the producer can attach whatever fields the
+ *     event type requires without forcing the store to change.
+ *
+ *   - `SessionListOptions` / `SessionLoadEventsOptions` /
+ *     `SessionSearchOptions` are inputs the store accepts. Defaults are
+ *     spec'd inline so the test plan can pin them without reading the
+ *     implementation.
+ *
+ * The blob store + `pugi undo` + named checkpoints are α6.4b follow-ups
+ * — out of scope for THIS PR per spec. The types here intentionally do
+ * NOT model blob refs so a future blob-store landing can extend without
+ * a wire break.
+ */
+/**
+ * Concrete shape of the lock detection error so the caller can branch
+ * on `error.code === 'EBUSY_SESSION_LOCK'` rather than parsing the
+ * message. The store is the only thrower of this error.
+ */
+export class SessionLockBusyError extends Error {
+    code = 'EBUSY_SESSION_LOCK';
+    holderPid;
+    lockPath;
+    constructor(holderPid, lockPath) {
+        super(`Another pugi process (pid ${holderPid}) holds the session lock at ${lockPath}.`);
+        this.name = 'SessionLockBusyError';
+        this.holderPid = holderPid;
+        this.lockPath = lockPath;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/core/repl/store/uuid-v7.js

@@ -0,0 +1,68 @@
+/**
+ * UUID v7 generator — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * uuid v7 (RFC 9562 draft) is a time-sortable 128-bit identifier whose
+ * first 48 bits are the unix-epoch milliseconds, the next 4 bits are
+ * the version (0b0111), the next 12 bits are sub-millisecond random
+ * entropy, the next 2 bits are the IETF variant (0b10), and the last
+ * 62 bits are random.
+ *
+ * Why v7 and not v4 (random) or v6 (gregorian time):
+ *
+ *   - The session id IS the primary key of the SQLite table. We want
+ *     inserts to land at the end of the b-tree to keep page fanout
+ *     small. v4 fragments the tree (uniformly random keys); v7 sorts
+ *     in time order so inserts are append-only.
+ *   - `pugi sessions` sorts by `updated_at DESC` for display, but the
+ *     pagination cursor uses the session id directly — a v7 id IS the
+ *     creation timestamp, so the cursor is a single column compare
+ *     instead of (updated_at, id) tuple.
+ *   - Operators see ids in `/resume` picker; v7 prefix is monotonically
+ *     increasing so the most recent session lands at the bottom of an
+ *     id sort, matching the human expectation of "newest last".
+ *
+ * Node 22 does not ship a v7 generator (`crypto.randomUUID()` is v4
+ * only). We implement it inline with `crypto.randomBytes(10)` for the
+ * entropy bits — 10 bytes covers the 12-bit random + 62-bit random
+ * fields with one syscall.
+ *
+ * Format: `xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx` where `y` is 8/9/a/b.
+ */
+import { randomBytes } from 'node:crypto';
+/**
+ * Mint a fresh uuid v7. The `now` parameter is injectable for tests so
+ * the generated id is deterministic when the test fixes the clock.
+ * Production callers pass `Date.now`.
+ */
+export function uuidV7(now = Date.now) {
+    const ms = Math.floor(now());
+    // 48-bit timestamp (6 bytes).
+    const tsHex = ms.toString(16).padStart(12, '0');
+    // 10 bytes of entropy: 12 random bits go into octet 6 (after the 4
+    // version bits), 2 variant bits go into octet 8 (high nibble 8/9/a/b),
+    // the remaining 62 bits fill octets 9..15.
+    const rand = randomBytes(10);
+    // Set version (high nibble of octet 6) to 7.
+    rand[0] = ((rand[0] ?? 0) & 0x0f) | 0x70;
+    // Set IETF variant (high two bits of octet 8) to 0b10.
+    rand[2] = ((rand[2] ?? 0) & 0x3f) | 0x80;
+    const hex = Array.from(rand, (b) => b.toString(16).padStart(2, '0')).join('');
+    // Assemble: 8-4-4-4-12.
+    return (`${tsHex.slice(0, 8)}-${tsHex.slice(8, 12)}-${hex.slice(0, 4)}-`
+        + `${hex.slice(4, 8)}-${hex.slice(8, 20)}`);
+}
+/**
+ * Extract the unix-ms timestamp from a uuid v7. Returns null when the
+ * input is not a v7 id (wrong version nibble, wrong shape). Used by
+ * `pugi sessions` to render "created N seconds ago" without reading
+ * the SQLite row.
+ */
+export function uuidV7Timestamp(id) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+        .test(id)) {
+        return null;
+    }
+    const hex = id.slice(0, 8) + id.slice(9, 13);
+    return Number.parseInt(hex, 16);
+}
+//# sourceMappingURL=uuid-v7.js.map

package/dist/core/repl/workspace-context.js

@@ -29,6 +29,16 @@ import { basename, resolve as resolvePath } from 'node:path';
 import { slugForCwd } from './history.js';
 /** Cap on the PUGI.md head we forward. Mirrors the admin-api clamp. */
 const PUGI_MD_HEAD_LIMIT = 200;
+/**
+ * Workspace label shown when the cwd has no project markers (no .git,
+ * no package.json, no PUGI.md). Per CEO 2026-05-25 dogfood, the
+ * previous behaviour leaked the parent directory basename (e.g.
+ * `codeforge-io`) into the splash as if it were a real workspace,
+ * confusing Mira/Pugi about what repo she was looking at. The
+ * unbound label is a single explicit string so the splash + status bar
+ * read the same warning. (α6.14.2 wave 5.)
+ */
+export const UNBOUND_WORKSPACE_LABEL = '(not bound - run /init OR cd into project)';
 /**
  * Resolve a `ReplWorkspaceContext` from the operator's working directory.
  * Returns a bundle with at least `workspaceCwd` + `workspaceSlug` +
@@ -38,13 +48,74 @@ const PUGI_MD_HEAD_LIMIT = 200;
 export function resolveWorkspaceContext(cwd) {
     const normalised = resolvePath(cwd);
     const slug = slugForCwd(normalised);
-    const summary = readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace';
+    // α6.14.2 wave 5: when the cwd has no project markers, prefer the
+    // explicit "not bound" summary so admin-api's prompt builder knows
+    // not to fabricate a workspace context for Mira/Pugi. The cwd +
+    // slug still travel so the server can record where the operator
+    // launched from for telemetry, but the summary no longer leaks a
+    // stray parent-dir basename as if it were a real workspace.
+    const summary = isBoundWorkspace(normalised)
+        ? (readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace')
+        : UNBOUND_WORKSPACE_LABEL;
     return {
         workspaceCwd: normalised,
         workspaceSlug: slug,
         workspaceSummary: summary,
     };
 }
+/**
+ * Project-marker probe used by the REPL splash + status bar to decide
+ * whether the cwd is a real workspace or a stray parent dir the
+ * operator wandered into. The probe is intentionally cheap — three
+ * `existsSync` calls — and the order matches the brand convention:
+ *
+ *   1. `.git`              — any clone of a real repo
+ *   2. `package.json`      — JS/TS workspace root
+ *   3. `PUGI.md`           — a Pugi-initialised workspace (root or
+ *                            `.pugi/PUGI.md`)
+ *
+ * Hitting any one of these counts the cwd as "bound" — the operator
+ * intentionally landed in a project. Hitting none means they ran
+ * `pugi` from `$HOME` or from the parent of a checkout; in that case
+ * the splash surfaces an explicit "not bound" label instead of leaking
+ * the parent-dir basename as if it were a workspace. The check
+ * mirrors the Claude Code "no CLAUDE.md → silent context" rule —
+ * never fake-bind. (α6.14.2 wave 5 — CEO dogfood fix.)
+ */
+export function isBoundWorkspace(cwd) {
+    const normalised = resolvePath(cwd);
+    // Case-sensitive checks; the resolver lower-cases PUGI.md when it
+    // reads the head, but the existence probe stays strict so a stray
+    // `pugi.md` does not accidentally pass without `pugi init` having
+    // run.
+    if (existsSync(resolvePath(normalised, '.git')))
+        return true;
+    if (existsSync(resolvePath(normalised, 'package.json')))
+        return true;
+    if (existsSync(resolvePath(normalised, 'PUGI.md')))
+        return true;
+    if (existsSync(resolvePath(normalised, '.pugi', 'PUGI.md')))
+        return true;
+    return false;
+}
+/**
+ * Resolve the workspace label shown on the splash + the REPL header.
+ * When the cwd has project markers, returns the directory basename;
+ * otherwise returns the explicit "not bound" warning so the operator
+ * understands no real workspace was detected. The label is the only
+ * string the splash and status bar agree on, so we centralise the
+ * decision here instead of re-deriving in two places.
+ * (α6.14.2 wave 5.)
+ */
+export function resolveWorkspaceLabel(cwd) {
+    if (!isBoundWorkspace(cwd))
+        return UNBOUND_WORKSPACE_LABEL;
+    const normalised = resolvePath(cwd);
+    const segment = basename(normalised);
+    if (!segment || segment.length === 0)
+        return 'workspace';
+    return segment;
+}
 /**
  * Read the first ~200 chars of `.pugi/PUGI.md` if the file exists. The
  * project's own description is the highest-signal one-line summary we

package/dist/core/skills/loader.js

@@ -0,0 +1,454 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+const FRONTMATTER_DELIM = '---';
+/**
+ * Parse a markdown file with YAML frontmatter into a structured form.
+ *
+ * Throws when:
+ *   - no frontmatter delimiter pair is present
+ *   - frontmatter does not parse as the minimal YAML grammar
+ *   - required keys `name`, `description`, `metadata.type` are missing
+ *
+ * Frontmatter `tools` accepts either flow array (`[a, b, c]`) or block
+ * array (newline + `  - a` lines). Strings are unquoted, single, or
+ * double quoted. Multi-line scalar values are NOT supported (no `>` or
+ * `|` folding) — Skills do not need them.
+ */
+export function parseSkillMarkdown(source) {
+    const trimmed = source.replace(/^/, '');
+    if (!trimmed.startsWith(`${FRONTMATTER_DELIM}\n`) && !trimmed.startsWith(`${FRONTMATTER_DELIM}\r\n`)) {
+        throw new Error('SKILL_PARSE: missing opening "---" frontmatter delimiter on line 1');
+    }
+    const newlineAfterOpen = trimmed.indexOf('\n');
+    const rest = trimmed.slice(newlineAfterOpen + 1);
+    const closeIdx = findClosingDelimiter(rest);
+    if (closeIdx < 0) {
+        throw new Error('SKILL_PARSE: missing closing "---" frontmatter delimiter');
+    }
+    const frontmatterRaw = rest.slice(0, closeIdx);
+    const body = rest.slice(closeIdx + FRONTMATTER_DELIM.length).replace(/^\r?\n/, '');
+    const parsed = parseFrontmatter(frontmatterRaw);
+    const validated = validateFrontmatter(parsed);
+    return { frontmatter: validated, body, source };
+}
+function findClosingDelimiter(text) {
+    // Walk line-by-line so we never match `---` that appears inside a
+    // body separator or table row.
+    const lines = text.split('\n');
+    let offset = 0;
+    for (const line of lines) {
+        if (line.trimEnd() === FRONTMATTER_DELIM) {
+            return offset;
+        }
+        offset += line.length + 1; // +1 for the newline we split on
+    }
+    return -1;
+}
+/**
+ * Parse the minimal YAML grammar described in the file header into a
+ * shallow node tree. Two levels of nesting cover every real skill /
+ * agent we have inspected; deeper nesting throws a clear error so the
+ * operator knows the parser is the gap.
+ */
+function parseFrontmatter(raw) {
+    const lines = raw.split('\n');
+    const root = {};
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            i++;
+            continue;
+        }
+        if (/^\s/.test(line)) {
+            throw new Error(`SKILL_PARSE: unexpected indented line at root scope: "${line}"`);
+        }
+        const colonIdx = line.indexOf(':');
+        if (colonIdx < 0) {
+            throw new Error(`SKILL_PARSE: expected "key: value" on line "${line}"`);
+        }
+        const key = line.slice(0, colonIdx).trim();
+        const rest = line.slice(colonIdx + 1).trim();
+        if (rest === '') {
+            // Two follow-up shapes: block object (indented `key: value`) OR
+            // block array (indented `- item`). Decide by inspecting the next
+            // non-blank line.
+            const peek = peekNextNonBlank(lines, i + 1);
+            if (peek === null) {
+                root[key] = { kind: 'object', value: {} };
+                i++;
+                continue;
+            }
+            const peekTrim = peek.line.trimStart();
+            if (peekTrim.startsWith('- ')) {
+                const { items, consumed } = parseBlockArray(lines, i + 1);
+                root[key] = { kind: 'array', value: items };
+                i += consumed + 1;
+                continue;
+            }
+            const { obj, consumed } = parseBlockObject(lines, i + 1);
+            root[key] = { kind: 'object', value: obj };
+            i += consumed + 1;
+            continue;
+        }
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+            root[key] = { kind: 'array', value: parseFlowArray(rest) };
+            i++;
+            continue;
+        }
+        root[key] = { kind: 'scalar', value: stripQuotes(rest) };
+        i++;
+    }
+    return root;
+}
+function peekNextNonBlank(lines, from) {
+    for (let i = from; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '')
+            continue;
+        if (line.trim().startsWith('#'))
+            continue;
+        return { line, index: i };
+    }
+    return null;
+}
+function parseBlockObject(lines, from) {
+    const obj = {};
+    let i = from;
+    let consumed = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            i++;
+            consumed++;
+            continue;
+        }
+        if (!/^\s/.test(line)) {
+            break;
+        }
+        const trimmed = line.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx < 0) {
+            throw new Error(`SKILL_PARSE: expected "key: value" inside object, got "${line}"`);
+        }
+        const key = trimmed.slice(0, colonIdx).trim();
+        const rest = trimmed.slice(colonIdx + 1).trim();
+        if (rest === '') {
+            // Nested object or block array — peek for shape.
+            const peek = peekNextNonBlank(lines, i + 1);
+            if (peek && peek.line.length > line.length - line.trimStart().length) {
+                const peekTrim = peek.line.trimStart();
+                if (peekTrim.startsWith('- ')) {
+                    const arr = parseBlockArray(lines, i + 1);
+                    obj[key] = { kind: 'array', value: arr.items };
+                    i += arr.consumed + 1;
+                    consumed += arr.consumed + 1;
+                    continue;
+                }
+                // Deeper objects are out of scope for α7.0 — keep frontmatter
+                // shape predictable. Throw with a clear pointer.
+                throw new Error(`SKILL_PARSE: nested objects deeper than 1 level are not supported (key "${key}")`);
+            }
+            obj[key] = { kind: 'object', value: {} };
+            i++;
+            consumed++;
+            continue;
+        }
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+            obj[key] = { kind: 'array', value: parseFlowArray(rest) };
+        }
+        else {
+            obj[key] = { kind: 'scalar', value: stripQuotes(rest) };
+        }
+        i++;
+        consumed++;
+    }
+    return { obj, consumed };
+}
+function parseBlockArray(lines, from) {
+    const items = [];
+    let i = from;
+    let consumed = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            i++;
+            consumed++;
+            continue;
+        }
+        if (!/^\s/.test(line)) {
+            break;
+        }
+        const trimmed = line.trimStart();
+        if (!trimmed.startsWith('- ')) {
+            break;
+        }
+        items.push(stripQuotes(trimmed.slice(2).trim()));
+        i++;
+        consumed++;
+    }
+    return { items, consumed };
+}
+function parseFlowArray(raw) {
+    const inner = raw.slice(1, -1).trim();
+    if (inner === '')
+        return [];
+    return inner.split(',').map((piece) => stripQuotes(piece.trim()));
+}
+function stripQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function validateFrontmatter(raw) {
+    const name = expectScalar(raw, 'name');
+    const description = expectScalar(raw, 'description');
+    // Two frontmatter dialects coexist in the wild:
+    //
+    // 1. Pugi-native — explicit `metadata: { type: skill|agent, ... }`.
+    //    Future Pugi-published skills + agents use this so the kind is
+    //    self-declared at parse time.
+    //
+    // 2. Anthropic Skills — flat top-level keys, no `metadata` block, no
+    //    `type` field. Every file inside `github.com/anthropics/skills`
+    //    follows this shape (e.g. `algorithmic-art`, `pdf`, `pptx`).
+    //
+    // We accept both. When `metadata` is absent we synthesize one with
+    // `type` defaulted to `skill` — the on-disk layout (`SKILL.md` in a
+    // directory) already disambiguates skill vs agent, and the agent
+    // loader explicitly overrides this when the file lives at
+    // `~/.pugi/agents/<slug>.md`.
+    const metadataNode = raw['metadata'];
+    let metadata;
+    if (metadataNode && metadataNode.kind === 'object') {
+        const metaRaw = metadataNode.value;
+        const typeNode = metaRaw['type'];
+        let type = 'skill';
+        if (typeNode) {
+            if (typeNode.kind !== 'scalar') {
+                throw new Error('SKILL_PARSE: metadata.type must be a scalar string');
+            }
+            if (typeNode.value !== 'skill' && typeNode.value !== 'agent') {
+                throw new Error(`SKILL_PARSE: metadata.type must be "skill" or "agent" (got "${typeNode.value}")`);
+            }
+            type = typeNode.value;
+        }
+        metadata = { type };
+        for (const [key, node] of Object.entries(metaRaw)) {
+            if (key === 'type')
+                continue;
+            if (node.kind === 'scalar') {
+                metadata[key] = node.value;
+            }
+            else if (node.kind === 'array') {
+                metadata[key] = node.value;
+            }
+            else {
+                metadata[key] = flattenObject(node.value);
+            }
+        }
+    }
+    else if (metadataNode) {
+        throw new Error('SKILL_PARSE: "metadata" must be an object when present');
+    }
+    else {
+        metadata = { type: 'skill' };
+    }
+    const fm = { name, description, metadata };
+    for (const [key, node] of Object.entries(raw)) {
+        if (key === 'name' || key === 'description' || key === 'metadata')
+            continue;
+        if (node.kind === 'scalar') {
+            fm[key] = node.value;
+            // Anthropic Skills flat dialect — also surface select top-level
+            // keys inside metadata so downstream consumers (Mira system
+            // prompt builder, `skills list` table) have one consistent path.
+            if (key === 'license' || key === 'version' || key === 'model' || key === 'allowed-tools') {
+                const metaKey = key === 'allowed-tools' ? 'tools' : key;
+                const metaBag = metadata;
+                if (metaBag[metaKey] === undefined) {
+                    if (key === 'allowed-tools') {
+                        // allowed-tools is conventionally comma-separated in the flat dialect.
+                        metaBag[metaKey] = node.value.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+                    }
+                    else {
+                        metaBag[metaKey] = node.value;
+                    }
+                }
+            }
+        }
+        else if (node.kind === 'array') {
+            fm[key] = node.value;
+        }
+        else {
+            fm[key] = flattenObject(node.value);
+        }
+    }
+    return fm;
+}
+function flattenObject(obj) {
+    const out = {};
+    for (const [key, node] of Object.entries(obj)) {
+        if (node.kind === 'scalar')
+            out[key] = node.value;
+        else if (node.kind === 'array')
+            out[key] = node.value;
+        else
+            out[key] = flattenObject(node.value);
+    }
+    return out;
+}
+function expectScalar(obj, key) {
+    const node = obj[key.split('.').pop() ?? key];
+    if (!node) {
+        throw new Error(`SKILL_PARSE: required key "${key}" is missing`);
+    }
+    if (node.kind !== 'scalar') {
+        throw new Error(`SKILL_PARSE: key "${key}" must be a scalar string`);
+    }
+    return node.value;
+}
+/* ----------------------------- Slug validation ----------------------------- */
+/**
+ * Slug grammar for skill + agent names. Allowed characters:
+ *   - lowercase ASCII letters, digits, hyphen, underscore, dot
+ *   - 1–64 characters total, must START with [a-z0-9]
+ *
+ * Anything outside this grammar is rejected BEFORE the name reaches a
+ * `path.join` call. Attacker payloads we close here:
+ *   - `../../foo`            (path traversal segment)
+ *   - `/etc/passwd`          (absolute path)
+ *   - `..\\..\\foo`          (Windows traversal)
+ *   - `\0name`               (null-byte truncation)
+ *   - `name\\with\\backslash` (Windows separator)
+ *   - `..` or `.`            (dot-only segments)
+ *   - empty string           (matches existing skill on globbed list)
+ *   - 65+ char strings       (DoS via huge directory names)
+ *   - uppercase / unicode    (collision on case-insensitive filesystems)
+ *
+ * The CLI commands also accept `--as <slug>` so this guard runs on the
+ * operator-supplied override AND on the parsed frontmatter `name`. Both
+ * paths feed the same `path.join` so both need the same gate.
+ */
+const VALID_SLUG = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export function assertValidSlug(name, context) {
+    if (typeof name !== 'string') {
+        throw new Error(`SLUG_INVALID: ${context} name must be a string, got ${typeof name}`);
+    }
+    // Defense in depth: separators, null bytes, dot-only get rejected
+    // ahead of the regex so the error message points at the precise vector
+    // rather than the catch-all "must match" form.
+    if (name.includes('/') || name.includes('\\')) {
+        throw new Error(`SLUG_FORBIDDEN: ${context} name contains a path separator: ${JSON.stringify(name)}`);
+    }
+    if (name.includes('\0')) {
+        throw new Error(`SLUG_FORBIDDEN: ${context} name contains a null byte: ${JSON.stringify(name)}`);
+    }
+    if (/^\.+$/.test(name)) {
+        throw new Error(`SLUG_FORBIDDEN: ${context} name is a dot-only segment: ${JSON.stringify(name)}`);
+    }
+    if (!VALID_SLUG.test(name)) {
+        throw new Error(`SLUG_INVALID: ${context} name ${JSON.stringify(name)} must match ${VALID_SLUG.source} (lowercase letters/digits/._-, 1-64 chars, starting alphanumeric).`);
+    }
+}
+export function globalSkillsDir() {
+    const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return join(home, 'skills');
+}
+export function workspaceSkillsDir(workspaceRoot) {
+    return join(workspaceRoot, '.pugi', 'skills');
+}
+export function globalSkillDir(name) {
+    assertValidSlug(name, 'skill');
+    return join(globalSkillsDir(), name);
+}
+export function workspaceSkillDir(workspaceRoot, name) {
+    assertValidSlug(name, 'skill');
+    return join(workspaceSkillsDir(workspaceRoot), name);
+}
+export function listSkills(scope, workspaceRoot) {
+    const dir = scope === 'global' ? globalSkillsDir() : workspaceSkillsDir(workspaceRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => loadSkill(join(dir, entry.name), scope))
+        .filter((skill) => skill !== null);
+}
+function loadSkill(skillDir, scope) {
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd))
+        return null;
+    try {
+        const source = readFileSync(skillMd, 'utf8');
+        const parsed = parseSkillMarkdown(source);
+        if (parsed.frontmatter.metadata.type !== 'skill') {
+            return null;
+        }
+        // Defense in depth: frontmatter.name is operator-controlled (anyone
+        // can author a SKILL.md). Reject before it can flow into trust
+        // registry keys, log strings, or any path operation downstream.
+        assertValidSlug(parsed.frontmatter.name, 'skill');
+        return {
+            name: parsed.frontmatter.name,
+            scope,
+            dir: skillDir,
+            skillMdPath: skillMd,
+            frontmatter: parsed.frontmatter,
+            body: parsed.body,
+            source,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Copy a fetched skill payload into its install location. Caller is
+ * responsible for trust-prompting + hashing before this is invoked.
+ *
+ * Refuses to install when the payload does not contain a `SKILL.md` at
+ * its root: that file is the contract every consumer (Mira system
+ * prompt, `skills list`, `skills info`) reads from.
+ */
+export function installSkill(input) {
+    // assertValidSlug runs inside globalSkillDir/workspaceSkillDir below,
+    // but we call it explicitly here too so the error surfaces before any
+    // filesystem state changes (cpSync) — fail-closed ordering.
+    assertValidSlug(input.name, 'skill');
+    const skillMd = join(input.payloadDir, 'SKILL.md');
+    if (!existsSync(skillMd)) {
+        throw new Error(`SKILL_INSTALL: payload at ${input.payloadDir} has no SKILL.md at its root`);
+    }
+    const target = input.scope === 'global'
+        ? globalSkillDir(input.name)
+        : workspaceSkillDir(input.workspaceRoot, input.name);
+    mkdirSync(dirname(target), { recursive: true });
+    // Idempotent install — remove any prior install so a re-install does
+    // not leave orphaned files from the previous payload.
+    if (existsSync(target)) {
+        rmSync(target, { recursive: true, force: true });
+    }
+    // verbatimSymlinks: any symlink that slipped through (e.g. via a
+    // legitimately-symlinked local source) is copied as a symlink rather
+    // than followed — so a malicious symlink in the payload cannot exfil
+    // contents from outside the payload root into our install target.
+    cpSync(input.payloadDir, target, { recursive: true, verbatimSymlinks: true });
+    return target;
+}
+export function removeSkill(name, scope, workspaceRoot) {
+    assertValidSlug(name, 'skill');
+    const target = scope === 'global' ? globalSkillDir(name) : workspaceSkillDir(workspaceRoot, name);
+    if (!existsSync(target))
+        return false;
+    rmSync(target, { recursive: true, force: true });
+    return true;
+}
+//# sourceMappingURL=loader.js.map