@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

package/dist/skills/bundled/skillify.js

@@ -0,0 +1,373 @@
+/**
+ * `pugi skillify` — codify a freeform operator description into a
+ * reusable skill scaffold.
+ *
+ * Bundled skill, batch 2 (backlog). The operator types a short
+ * description ("Write a Pugi skill that scans for `// TODO ASAP` and
+ * fails CI"); this skill asks the engine to produce a canonical
+ * skill scaffold (name + description + mode + allowedTools + prompt
+ * template + example invocation), validates the engine output, and
+ * writes the result к `.pugi/skills/<kebab-name>.md` in the same
+ * frontmatter format the existing bundled skills use.
+ *
+ * # Output shape
+ *
+ * The on-disk file mirrors the stuck / simplify / remember frontmatter
+ * shape — `---name / description / mode---` block followed by markdown
+ * body. The body holds:
+ *
+ *  - Operator-facing usage block.
+ *  - Prompt template that the slash dispatcher injects when the skill
+ *    fires.
+ *  - Example invocation.
+ *
+ * # Safety
+ *
+ * The engine's JSON envelope is validated field-by-field before any
+ * file is touched. A malformed envelope produces an explicit error
+ * with the failing field — we never write a half-baked skill to disk.
+ *
+ * # Provenance
+ *
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
+ */
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+function parseFlags(args) {
+    const flags = {
+        json: false,
+        description: null,
+        outputDir: null,
+        force: false,
+        dryRun: false,
+    };
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (arg === '--force') {
+            flags.force = true;
+            continue;
+        }
+        if (arg === '--dry-run') {
+            flags.dryRun = true;
+            continue;
+        }
+        if (arg === '--output-dir') {
+            const next = args[i + 1];
+            if (next === undefined) {
+                return { flags, error: '--output-dir requires a value' };
+            }
+            flags.outputDir = next;
+            i += 1;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            return { flags, error: 'help' };
+        }
+        if (arg.startsWith('--')) {
+            return { flags, error: `unknown flag: ${arg}` };
+        }
+        positional.push(arg);
+    }
+    if (positional.length > 0) {
+        flags.description = positional.join(' ').trim();
+        if (flags.description === '')
+            flags.description = null;
+    }
+    return { flags, error: null };
+}
+const ALLOWED_TOOL_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Validate + normalise the engine's JSON envelope. Public for direct
+ * test coverage of the boundary contract.
+ */
+export function parseScaffoldEnvelope(raw) {
+    const json = extractJsonBlock(raw);
+    if (json === null) {
+        return { ok: false, error: 'engine output did not contain a JSON object' };
+    }
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `engine JSON parse failed: ${message}` };
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return { ok: false, error: 'engine envelope must be a JSON object' };
+    }
+    const obj = value;
+    const name = obj.name;
+    if (typeof name !== 'string' || !NAME_PATTERN.test(name)) {
+        return {
+            ok: false,
+            error: 'envelope.name must be kebab-case [a-z][a-z0-9-]*',
+        };
+    }
+    const description = obj.description;
+    if (typeof description !== 'string' ||
+        description.length < 8 ||
+        description.length > 500) {
+        return {
+            ok: false,
+            error: 'envelope.description must be a string 8..500 chars',
+        };
+    }
+    const modeRaw = obj.mode;
+    if (modeRaw !== 'read-only' &&
+        modeRaw !== 'read-write' &&
+        modeRaw !== 'agent') {
+        return {
+            ok: false,
+            error: 'envelope.mode must be read-only | read-write | agent',
+        };
+    }
+    const allowedToolsRaw = obj.allowedTools;
+    if (!Array.isArray(allowedToolsRaw)) {
+        return { ok: false, error: 'envelope.allowedTools must be an array' };
+    }
+    const allowedTools = [];
+    for (let i = 0; i < allowedToolsRaw.length; i += 1) {
+        const item = allowedToolsRaw[i];
+        if (typeof item !== 'string' || !ALLOWED_TOOL_PATTERN.test(item)) {
+            return {
+                ok: false,
+                error: `envelope.allowedTools[${i}] must match ${String(ALLOWED_TOOL_PATTERN)}`,
+            };
+        }
+        allowedTools.push(item);
+    }
+    const promptTemplate = obj.promptTemplate;
+    if (typeof promptTemplate !== 'string' ||
+        promptTemplate.length < 16 ||
+        promptTemplate.length > 8000) {
+        return {
+            ok: false,
+            error: 'envelope.promptTemplate must be a string 16..8000 chars',
+        };
+    }
+    const exampleInvocation = obj.exampleInvocation;
+    if (typeof exampleInvocation !== 'string' ||
+        exampleInvocation.length < 4 ||
+        exampleInvocation.length > 500) {
+        return {
+            ok: false,
+            error: 'envelope.exampleInvocation must be a string 4..500 chars',
+        };
+    }
+    return {
+        ok: true,
+        scaffold: {
+            name,
+            description,
+            mode: modeRaw,
+            allowedTools,
+            promptTemplate,
+            exampleInvocation,
+        },
+    };
+}
+/**
+ * Extract a top-level JSON object from a freeform engine response. We
+ * walk the string and balance braces, ignoring brace characters inside
+ * strings. Returns the first balanced `{...}` span or null if none.
+ * Public for direct test coverage; engines sometimes prepend prose to
+ * the envelope and we have to be resilient.
+ */
+export function extractJsonBlock(raw) {
+    const start = raw.indexOf('{');
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = null;
+    let escape = false;
+    for (let i = start; i < raw.length; i += 1) {
+        const ch = raw.charAt(i);
+        if (inString !== null) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escape = true;
+                continue;
+            }
+            if (ch === inString) {
+                inString = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = ch;
+            continue;
+        }
+        if (ch === '{')
+            depth += 1;
+        if (ch === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return raw.slice(start, i + 1);
+            }
+        }
+    }
+    return null;
+}
+function atomicWriteFile(targetPath, body) {
+    const parent = dirname(targetPath);
+    if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
+    try {
+        writeFileSync(tmpPath, body, 'utf8');
+        renameSync(tmpPath, targetPath);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // ignore cleanup
+        }
+        throw err;
+    }
+}
+/**
+ * Render the on-disk skill markdown using the canonical frontmatter
+ * format the existing batch-1 bundled skills follow. Public so the
+ * test suite can assert the rendered text directly.
+ */
+export function renderSkillMarkdown(scaffold) {
+    // The frontmatter description is quoted to keep multi-line summaries
+    // legal YAML without dragging in a real YAML emitter.
+    const allowedToolsLine = scaffold.allowedTools.length === 0
+        ? '[]'
+        : `[${scaffold.allowedTools.map((t) => `"${t}"`).join(', ')}]`;
+    const lines = [];
+    lines.push('---');
+    lines.push(`name: ${scaffold.name}`);
+    lines.push(`description: ${JSON.stringify(scaffold.description)}`);
+    lines.push(`mode: ${scaffold.mode}`);
+    lines.push(`allowedTools: ${allowedToolsLine}`);
+    lines.push('---');
+    lines.push('');
+    lines.push(`# /${scaffold.name}`);
+    lines.push('');
+    lines.push(scaffold.description);
+    lines.push('');
+    lines.push('## Prompt template');
+    lines.push('');
+    lines.push(scaffold.promptTemplate.trim());
+    lines.push('');
+    lines.push('## Example');
+    lines.push('');
+    lines.push('```');
+    lines.push(scaffold.exampleInvocation.trim());
+    lines.push('```');
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+const SCHEMA_HINT = JSON.stringify({
+    name: '<kebab-case>',
+    description: '<8..500 chars>',
+    mode: 'read-only | read-write | agent',
+    allowedTools: ['<tool-name>', '...'],
+    promptTemplate: '<16..8000 chars>',
+    exampleInvocation: '<short usage example>',
+});
+export async function runSkillifyCommand(args, ctx) {
+    const { flags, error } = parseFlags(args);
+    if (error === 'help') {
+        ctx.writeOutput({ ok: true, command: 'skillify', usage: SKILLIFY_USAGE }, SKILLIFY_USAGE);
+        return { scaffold: null, writtenPath: null, exitCode: 0 };
+    }
+    if (error !== null) {
+        ctx.writeOutput({ ok: false, command: 'skillify', error }, `pugi skillify: ${error}`);
+        return { scaffold: null, writtenPath: null, exitCode: 2 };
+    }
+    if (flags.description === null) {
+        const msg = 'description is required';
+        ctx.writeOutput({ ok: false, command: 'skillify', error: msg }, `pugi skillify: ${msg}\n\n${SKILLIFY_USAGE}`);
+        return { scaffold: null, writtenPath: null, exitCode: 2 };
+    }
+    let engineRaw;
+    try {
+        engineRaw = await ctx.engineInvoker({
+            description: flags.description,
+            schemaHint: SCHEMA_HINT,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ ok: false, command: 'skillify', error: `engine failed: ${message}` }, `pugi skillify: engine failed — ${message}`);
+        return { scaffold: null, writtenPath: null, exitCode: 1 };
+    }
+    const parsed = parseScaffoldEnvelope(engineRaw);
+    if (!parsed.ok) {
+        ctx.writeOutput({ ok: false, command: 'skillify', error: parsed.error, raw: engineRaw }, `pugi skillify: engine envelope invalid — ${parsed.error}`);
+        return { scaffold: null, writtenPath: null, exitCode: 1 };
+    }
+    const scaffold = parsed.scaffold;
+    const outputDir = flags.outputDir ?? join(ctx.cwd, '.pugi', 'skills');
+    const writtenPath = join(outputDir, `${scaffold.name}.md`);
+    if (flags.dryRun) {
+        ctx.writeOutput({
+            ok: true,
+            command: 'skillify',
+            scaffold,
+            wouldWrite: writtenPath,
+            body: renderSkillMarkdown(scaffold),
+            dryRun: true,
+        }, `pugi skillify: dry-run — would write ${writtenPath}`);
+        return { scaffold, writtenPath: null, exitCode: 0 };
+    }
+    if (existsSync(writtenPath) && !flags.force) {
+        const msg = `target exists: ${writtenPath} (pass --force to overwrite)`;
+        ctx.writeOutput({ ok: false, command: 'skillify', error: msg, scaffold }, `pugi skillify: ${msg}`);
+        return { scaffold, writtenPath: null, exitCode: 1 };
+    }
+    const body = renderSkillMarkdown(scaffold);
+    try {
+        atomicWriteFile(writtenPath, body);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({
+            ok: false,
+            command: 'skillify',
+            error: `write failed: ${message}`,
+            scaffold,
+        }, `pugi skillify: write failed — ${message}`);
+        return { scaffold, writtenPath: null, exitCode: 1 };
+    }
+    ctx.writeOutput({ ok: true, command: 'skillify', scaffold, writtenPath }, `Wrote ${writtenPath} — invoke via \`/skill-${scaffold.name}\`.`);
+    return { scaffold, writtenPath, exitCode: 0 };
+}
+const SKILLIFY_USAGE = [
+    'pugi skillify — generate a reusable skill scaffold from a freeform description.',
+    '',
+    'Usage:',
+    ' pugi skillify "<description>" [--output-dir <dir>] [--force] [--dry-run] [--json]',
+    '',
+    'Flags:',
+    ' --output-dir <dir>   Destination directory (default: .pugi/skills/).',
+    ' --force              Overwrite an existing file with the same name.',
+    ' --dry-run            Print the rendered markdown without writing it.',
+    ' --json               Emit a JSON envelope instead of human text.',
+    '',
+    'Engine envelope schema:',
+    ' { "name": "kebab", "description": "...", "mode": "read-only|read-write|agent",',
+    '   "allowedTools": ["..."], "promptTemplate": "...", "exampleInvocation": "..." }',
+    '',
+    'Output lands at .pugi/skills/<name>.md in the canonical frontmatter format.',
+].join('\n');
+//# sourceMappingURL=skillify.js.map