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

package/dist/core/skills/defaults.js

@@ -1,457 +0,0 @@
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { installSkill, workspaceSkillDir, } from './loader.js';
-import { hashSkillDir, recordTrust } from './trust.js';
-/**
- * Static catalog of the three bundled defaults. Exported so the tests
- * (and any future `pugi skills install --bundled` opt-in path) can
- * iterate over the canonical list without re-listing skill names.
- */
-export const DEFAULT_SKILLS = [
-    {
-        name: 'brand-voice',
-        description: 'Pugi brand voice: English in code/commits, terse in chat, no AI attribution, no emoji slop.',
-        version: '1.0.0',
-        source: 'pugi-original',
-        sourceUrl: 'https://github.com/pugi-io/pugi/blob/main/apps/pugi-cli/src/core/skills/defaults.ts',
-        license: 'MIT',
-        body: [
-            '# Brand voice',
-            '',
-            'Apply this rule set to every commit message, PR body, code comment,',
-            'generated docstring, and chat reply Pugi produces on this workspace.',
-            '',
-            '## Language split',
-            '',
-            '- Code, comments, commit messages, PR titles + bodies, technical docs,',
-            " generated tests, log strings: **English**. Do not switch mid-line.",
-            '- Operator-facing chat replies follow the workspace `settings.json`',
-            ' `workflow.chatLang` (defaults to English when unset).',
-            '',
-            '## No AI attribution',
-            '',
-            '- Never add `Co-Authored-By: Claude` (or Codex, Gemini, Cursor) trailers',
-            ' to commits or PR bodies.',
-            '- Never write "Generated with the upstream tool", "Made with AI", or any',
-            ' variant in PR descriptions, README content, or release notes.',
-            '- Pugi itself is the byline; the underlying model is implementation',
-            ' detail and stays out of customer-visible text.',
-            '',
-            '## No emoji decoration',
-            '',
-            '- Skip decorative emoji in commit messages, PR bodies, code comments,',
-            ' log lines, and chat replies.',
-            '- Functional unicode that carries meaning (math symbols, currency,',
-            ' language scripts) is fine.',
-            '',
-            '## No em dashes',
-            '',
-            '- Prefer regular hyphens or restructure the sentence. The em dash',
-            ' character reads as ChatGPT-flavoured and we keep our voice distinct.',
-            '',
-            '## Verb grammar',
-            '',
-            'Pugi exposes four customer verbs: `idea`, `plan`, `build`, `review`.',
-            'When generating help text, READMEs, or onboarding docs reference these',
-            'exact verbs in this exact order. Do not invent synonyms like "scaffold",',
-            '"draft", "ship", or "execute" for the same surface.',
-            '',
-        ].join('\n'),
-    },
-    {
-        name: 'endpoint-probe',
-        description: 'Verify every URL with a HEAD probe before codegen writes it so Pugi never ships a fabricated endpoint.',
-        version: '1.0.0',
-        source: 'pugi-original',
-        sourceUrl: 'https://github.com/pugi-io/pugi/blob/main/apps/pugi-cli/src/core/skills/defaults.ts',
-        license: 'MIT',
-        body: [
-            '# Endpoint probe',
-            '',
-            'When the model is about to write a URL into source code, configuration,',
-            'documentation, or a generated README, treat that URL as unverified',
-            'until a real HTTP probe confirms it resolves.',
-            '',
-            '## Rule',
-            '',
-            '1. Before any tool call that writes a URL (`write`, `edit`, `patch`),',
-            '  enumerate the URLs the diff introduces.',
-            '2. For each URL whose host is reachable from the workspace, issue a',
-            '  `HEAD` request (or `GET` when the host blocks `HEAD`).',
-            '3. Treat the URL as **valid** only when the response is 2xx, 3xx, or',
-            '  a documented 401/403 (auth-gated endpoint we expect).',
-            '4. Treat the URL as **invalid** on `ENOTFOUND`, `ECONNREFUSED`,',
-            '  timeout, or 4xx/5xx other than the documented auth codes. In that',
-            '  case do not write the URL; ask the operator for the correct one or',
-            '  pull it from `.pugi/settings.json` / `.env`.',
-            '',
-            '## Why this matters',
-            '',
-            'Pugi has historically shipped READMEs with installer URLs that 404,',
-            'API base URLs that point at deprecated tunnels, and "see docs at X"',
-            'links to pages that never existed. Each is a trust event: the next',
-            'operator pastes the URL, hits the 404, and assumes the whole CLI is',
-            'broken. A HEAD probe costs one round-trip and closes that class.',
-            '',
-            '## Skip cases',
-            '',
-            '- Localhost URLs (`http://127.0.0.1:*`, `http://localhost:*`): skip',
-            ' the probe; verify visually that the port matches the workspace dev',
-            ' server config instead.',
-            '- Example URLs in comments explicitly marked `// example:` or',
-            ' `# example:`: skip the probe; the operator has flagged the URL as',
-            ' illustrative.',
-            '',
-        ].join('\n'),
-    },
-    {
-        name: 'readme-sync',
-        description: 'When package.json bin/name/scripts change, cross-check README install + usage so shipped docs never drift from the binary.',
-        version: '1.0.0',
-        source: 'pugi-original',
-        sourceUrl: 'https://github.com/pugi-io/pugi/blob/main/apps/pugi-cli/src/core/skills/defaults.ts',
-        license: 'MIT',
-        body: [
-            '# README sync',
-            '',
-            'Whenever a `build` task renames a package or its binary, the README',
-            'must move with it. Stale install snippets are the most common Pugi',
-            'regression: the binary ships as `@pugi/cli` but the README still',
-            'tells the operator to `npm i -g @pugi/cli`, and the install',
-            "fails before they ever see `pugi --version`.",
-            '',
-            '## Rule',
-            '',
-            'Whenever a diff touches `package.json` and changes any of:',
-            '',
-            ' - `name`',
-            ' - `bin`',
-            ' - `scripts.start` / `scripts.dev`',
-            ' - top-level `homepage` / `repository.url`',
-            '',
-            'then the same diff MUST also update the corresponding sections of the',
-            "package's `README.md` (and, when the package has a docs landing page,",
-            'the install snippet on that landing page too).',
-            '',
-            '## Verification snippet',
-            '',
-            'Before marking a `build` step done, run this check on every touched',
-            'package directory:',
-            '',
-            '```',
-            'pkg_name=$(jq -r .name package.json)',
-            'bin_name=$(jq -r ".bin | if type==\\"string\\" then \\"unknown\\" else keys[0] end" package.json)',
-            'grep -F "npm i -g $pkg_name" README.md || echo "MISMATCH: README missing install for $pkg_name"',
-            'grep -F "$bin_name " README.md || echo "MISMATCH: README missing usage for $bin_name"',
-            '```',
-            '',
-            'When either grep prints `MISMATCH`, fix the README before the commit',
-            'is considered ready for `review`.',
-            '',
-            '## Idempotence',
-            '',
-            'This rule applies to every package in the workspace, not just the',
-            "first one the operator mentions. A monorepo-wide rename (`@pugi/*`",
-            "to `@pugi/*`) has to sync every README, not just the customer-facing",
-            'CLI README.',
-            '',
-        ].join('\n'),
-    },
-    {
-        name: 'zoom-out',
-        description: 'Ask Pugi to zoom out and give broader context or a higher-level perspective. Use when the model is unfamiliar with a section of code or needs to understand how it fits into the bigger picture.',
-        version: '1.0.0',
-        source: 'mattpocock/skills',
-        sourceUrl: 'https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out/SKILL.md',
-        license: 'MIT',
-        body: [
-            '# Zoom out',
-            '',
-            '**Source:** [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out/SKILL.md) - MIT licensed, authored by Matt Pocock. Ported verbatim into the Pugi bundle on.',
-            '',
-            'I do not know this area of code well. Go up a layer of abstraction.',
-            'Give me a map of all the relevant modules and callers, using the',
-            "project's domain glossary vocabulary.",
-            '',
-        ].join('\n'),
-    },
-    {
-        name: 'diagnose',
-        description: 'Disciplined six-phase diagnosis loop for hard bugs and performance regressions: build feedback loop, reproduce, hypothesise, instrument, fix + regression-test, cleanup + post-mortem. Use when the operator reports a bug, a flake, or a perf regression.',
-        version: '1.0.0',
-        source: 'mattpocock/skills',
-        sourceUrl: 'https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose/SKILL.md',
-        license: 'MIT',
-        body: [
-            '# Diagnose',
-            '',
-            '**Source:** [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose/SKILL.md) - MIT licensed, authored by Matt Pocock. Ported into the Pugi bundle on with minor de-namespacing (cross-skill links rewritten, project-glossary references generalised).',
-            '',
-            'A discipline for hard bugs. Skip phases only when explicitly justified.',
-            '',
-            'When exploring the codebase, use the project domain glossary (if one',
-            'exists) to build a clear mental model of the relevant modules, and',
-            'check ADRs in the area you are touching.',
-            '',
-            '## Phase 1 - Build a feedback loop',
-            '',
-            '**This is the skill.** Everything else is mechanical. If you have a',
-            'fast, deterministic, agent-runnable pass/fail signal for the bug, you',
-            'will find the cause - bisection, hypothesis-testing, and instrumentation',
-            'all just consume that signal. If you do not have one, no amount of',
-            'staring at code will save you.',
-            '',
-            'Spend disproportionate effort here. **Be aggressive. Be creative.',
-            'Refuse to give up.**',
-            '',
-            '### Ways to construct one, in roughly this order',
-            '',
-            '1. **Failing test** at whatever seam reaches the bug - unit, integration, e2e.',
-            '2. **Curl / HTTP script** against a running dev server.',
-            '3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.',
-            '4. **Headless browser script** (Playwright / Puppeteer) - drives the UI, asserts on DOM/console/network.',
-            '5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.',
-            '6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.',
-            '7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.',
-            '8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.',
-            '9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.',
-            '10. **HITL bash script.** Last resort. If a human must click, drive _them_ with a templated loop script so the loop is still structured. Captured output feeds back to you.',
-            '',
-            'Build the right feedback loop, and the bug is 90% fixed.',
-            '',
-            '### Iterate on the loop itself',
-            '',
-            'Treat the loop as a product. Once you have _a_ loop, ask:',
-            '',
-            '- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)',
-            '- Can I make the signal sharper? (Assert on the specific symptom, not "did not crash".)',
-            '- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)',
-            '',
-            'A 30-second flaky loop is barely better than no loop. A 2-second',
-            'deterministic loop is a debugging superpower.',
-            '',
-            '### Non-deterministic bugs',
-            '',
-            'The goal is not a clean repro but a **higher reproduction rate**. Loop',
-            'the trigger 100x, parallelise, add stress, narrow timing windows, inject',
-            'sleeps. A 50% flake is debuggable; 1% is not - keep raising the rate',
-            'until it is debuggable.',
-            '',
-            '### When you genuinely cannot build a loop',
-            '',
-            'Stop and say so explicitly. List what you tried. Ask the operator for:',
-            '(a) access to whatever environment reproduces it, (b) a captured artifact',
-            '(HAR file, log dump, core dump, screen recording with timestamps), or',
-            '(c) permission to add temporary production instrumentation. Do **not**',
-            'proceed to hypothesise without a loop.',
-            '',
-            'Do not proceed to Phase 2 until you have a loop you believe in.',
-            '',
-            '## Phase 2 - Reproduce',
-            '',
-            'Run the loop. Watch the bug appear.',
-            '',
-            'Confirm:',
-            '',
-            '- The loop produces the failure mode the **operator** described - not a different failure that happens to be nearby. Wrong bug = wrong fix.',
-            '- The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).',
-            '- You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.',
-            '',
-            'Do not proceed until you reproduce the bug.',
-            '',
-            '## Phase 3 - Hypothesise',
-            '',
-            'Generate **3-5 ranked hypotheses** before testing any of them.',
-            'Single-hypothesis generation anchors on the first plausible idea.',
-            '',
-            'Each hypothesis must be **falsifiable**: state the prediction it makes.',
-            '',
-            '> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."',
-            '',
-            'If you cannot state the prediction, the hypothesis is a vibe - discard',
-            'or sharpen it.',
-            '',
-            '**Show the ranked list to the operator before testing.** They often',
-            'have domain knowledge that re-ranks instantly ("we just deployed a',
-            'change to #3"), or know hypotheses they have already ruled out. Cheap',
-            'checkpoint, big time saver. Do not block on it - proceed with your',
-            'ranking if the operator is AFK.',
-            '',
-            '## Phase 4 - Instrument',
-            '',
-            'Each probe must map to a specific prediction from Phase 3. **Change',
-            'one variable at a time.**',
-            '',
-            'Tool preference:',
-            '',
-            '1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.',
-            '2. **Targeted logs** at the boundaries that distinguish hypotheses.',
-            '3. Never "log everything and grep".',
-            '',
-            '**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`.',
-            'Cleanup at the end becomes a single grep. Untagged logs survive;',
-            'tagged logs die.',
-            '',
-            '**Perf branch.** For performance regressions, logs are usually wrong.',
-            'Instead: establish a baseline measurement (timing harness,',
-            '`performance.now()`, profiler, query plan), then bisect. Measure first,',
-            'fix second.',
-            '',
-            '## Phase 5 - Fix + regression test',
-            '',
-            'Write the regression test **before the fix** - but only if there is a',
-            '**correct seam** for it.',
-            '',
-            'A correct seam is one where the test exercises the **real bug pattern**',
-            'as it occurs at the call site. If the only available seam is too',
-            'shallow (single-caller test when the bug needs multiple callers, unit',
-            'test that cannot replicate the chain that triggered the bug), a',
-            'regression test there gives false confidence.',
-            '',
-            '**If no correct seam exists, that itself is the finding.** Note it. The',
-            'codebase architecture is preventing the bug from being locked down.',
-            'Flag this for the next phase.',
-            '',
-            'If a correct seam exists:',
-            '',
-            '1. Turn the minimised repro into a failing test at that seam.',
-            '2. Watch it fail.',
-            '3. Apply the fix.',
-            '4. Watch it pass.',
-            '5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.',
-            '',
-            '## Phase 6 - Cleanup + post-mortem',
-            '',
-            'Required before declaring done:',
-            '',
-            '- Original repro no longer reproduces (re-run the Phase 1 loop)',
-            '- Regression test passes (or absence of seam is documented)',
-            '- All `[DEBUG-...]` instrumentation removed (`grep` the prefix)',
-            '- Throwaway prototypes deleted (or moved to a clearly-marked debug location)',
-            '- The hypothesis that turned out correct is stated in the commit / PR message - so the next debugger learns',
-            '',
-            '**Then ask: what would have prevented this bug?** If the answer',
-            'involves architectural change (no good test seam, tangled callers,',
-            'hidden coupling) note the specifics for a follow-up refactor. Make the',
-            'recommendation **after** the fix is in, not before - you have more',
-            'information now than when you started.',
-            '',
-        ].join('\n'),
-    },
-    {
-        name: 'grill-me',
-        description: 'Interview the operator relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when the operator wants to stress-test a plan or says "grill me".',
-        version: '1.0.0',
-        source: 'mattpocock/skills',
-        sourceUrl: 'https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md',
-        license: 'MIT',
-        body: [
-            '# Grill me',
-            '',
-            '**Source:** [mattpocock/skills](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) - MIT licensed, authored by Matt Pocock. Ported verbatim into the Pugi bundle on (terminology swap: "user" -> "operator" to match Pugi vocabulary).',
-            '',
-            'Interview the operator relentlessly about every aspect of this plan',
-            'until we reach a shared understanding. Walk down each branch of the',
-            'design tree, resolving dependencies between decisions one-by-one. For',
-            'each question, provide your recommended answer.',
-            '',
-            'Ask the questions one at a time.',
-            '',
-            'If a question can be answered by exploring the codebase, explore the',
-            'codebase instead.',
-            '',
-        ].join('\n'),
-    },
-];
-/**
- * Build the canonical `SKILL.md` text for a bundled default. We hand-roll
- * the frontmatter (instead of going through a YAML library) so the file
- * round-trips byte-identical for the same `DEFAULT_SKILLS` entry. Stable
- * bytes means a stable sha256: re-running `pugi init` against a clean
- * workspace produces the same trust signature.
- */
-function renderSkillMarkdown(spec) {
-    const frontmatter = [
-        '---',
-        `name: ${spec.name}`,
-        `description: ${spec.description}`,
-        'metadata:',
-        ' type: skill',
-        ` version: ${spec.version}`,
-        '---',
-        '',
-    ].join('\n');
-    return `${frontmatter}${spec.body}`;
-}
-/**
- * Install every bundled default skill into the workspace `.pugi/skills/`
- * directory. Idempotent: a skill whose target directory already exists
- * (i.e. operator has customised it) is left untouched.
- *
- * Trust records are written under the workspace scope with
- * `signedBy: pugi-bundled` so `pugi skills list` reports them as
- * `[trusted]` without the operator having to run `pugi skills trust`
- * manually after init.
- */
-export async function installDefaultSkills(input) {
-    const summaries = [];
-    const scope = 'workspace';
-    for (const spec of DEFAULT_SKILLS) {
-        const targetDir = workspaceSkillDir(input.workspaceRoot, spec.name);
-        if (existsSync(targetDir)) {
-            // Idempotent: never overwrite a skill the operator has already
-            // edited. The `init` command is re-runnable by design.
-            summaries.push({ name: spec.name, status: 'skipped-existing', dir: targetDir });
-            input.log?.(`[pugi init] skill "${spec.name}" already present, leaving as-is.\n`);
-            continue;
-        }
-        // Materialise the bundled body in a tmp dir so `installSkill` can copy
-        // it through its standard payload path (includes its own SKILL.md
-        // existence check + symlink hardening via verbatimSymlinks).
-        const payloadDir = mkdtempSync(join(tmpdir(), 'pugi-default-skill-'));
-        try {
-            writeFileSync(join(payloadDir, 'SKILL.md'), renderSkillMarkdown(spec), {
-                encoding: 'utf8',
-                mode: 0o600,
-            });
-            const installedDir = installSkill({
-                payloadDir,
-                name: spec.name,
-                scope,
-                workspaceRoot: input.workspaceRoot,
-            });
-            const sha256 = hashSkillDir(installedDir);
-            await recordTrust({
-                kind: 'skill',
-                scope,
-                name: spec.name,
-                sha256,
-                // Source records the provenance for the trust ledger so a future
-                // `pugi skills info brand-voice` shows where it came from without
-                // pointing at a URL that never existed.
-                source: 'pugi-bundled-default',
-                signedBy: 'pugi-bundled',
-            });
-            summaries.push({ name: spec.name, status: 'installed', dir: installedDir });
-            input.log?.(`[pugi init] installed default skill "${spec.name}" -> ${installedDir}\n`);
-        }
-        finally {
-            rmSync(payloadDir, { recursive: true, force: true });
-        }
-    }
-    return summaries;
-}
-/**
- * Internal helper used by tests to keep parity with the runtime. Exposed
- * so a test fixture can write a SKILL.md byte-for-byte matching what the
- * installer would have produced.
- */
-export function renderDefaultSkillMarkdown(name) {
-    const spec = DEFAULT_SKILLS.find((entry) => entry.name === name);
-    if (!spec) {
-        throw new Error(`renderDefaultSkillMarkdown: no bundled default named "${name}"`);
-    }
-    return renderSkillMarkdown(spec);
-}
-//# sourceMappingURL=defaults.js.map