@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/core/skills/loader.js

@@ -1,454 +0,0 @@
-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 — 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 (Pugi 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 (Pugi 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