picopilot 0.0.0 → 0.1.1

package/dist/commands/init.js

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { z } from 'incur';
+import { scaffoldFiles } from '../engine/scaffold/index.js';
+import { installSkills, } from '../engine/skills/index.js';
+/**
+ * Registers `picopilot init`, the scaffolder that turns a fresh folder into an
+ * agent-ready PICO-8 cart (US #1, #2).
+ *
+ * INSTRUCT-not-mutate (US #2): by default `init` writes ONLY inside the target
+ * cart folder, the `main.p8` (`__lua__` = `#include main.lua`), the editable
+ * `main.lua`, the curated `AGENTS.md` reference, and `picopilot.json`. It does
+ * NOT run `git init` and does NOT write to shared agent skill dirs; it PRINTS a
+ * skills-discovery tip and a `git init` tip instead. The global skills install
+ * is the opt-in `init --install-skills`, a SEPARATE task, so the default is a
+ * good citizen of `~/.claude` / agent dirs and of the user's VCS choice.
+ *
+ * The opt-in `init --install-skills` (US #2, #20) IS the shared write: it runs
+ * incur's skills install (which defaults to a GLOBAL write into `~/.agents/skills`
+ * + detected agent dirs) so the discipline skills are auto-discovered. It is the
+ * only picopilot path that touches a shared location, so the installer is an
+ * injected seam and its target is fully redirectable for isolation-testing.
+ *
+ * @param installer injects the skills installer (defaults to the real global
+ *   install); tests pass one that redirects the target to a temp dir.
+ */
+export function registerInit(cli, installer = installSkills) {
+    cli.command('init', {
+        description: 'Scaffold an agent-ready PICO-8 cart (main.p8 + main.lua + AGENTS.md + picopilot.json).',
+        args: z.object({
+            dir: z
+                .string()
+                .default('.')
+                .describe('Target cart folder (created if missing). Defaults to the current directory.'),
+        }),
+        options: z.object({
+            installSkills: z
+                .boolean()
+                .default(false)
+                .describe("Opt in to INSTALLING picopilot's skills into your agent's skill dirs (a GLOBAL write). Default off: init only PRINTS how to discover them."),
+            global: z
+                .boolean()
+                .default(true)
+                .describe('With --install-skills, install GLOBALLY (default). Pass --no-global to install into THIS project (./.agents/skills) instead.'),
+        }),
+        output: z.object({
+            dir: z
+                .string()
+                .describe('The absolute path of the scaffolded cart folder.'),
+            files: z
+                .array(z.string())
+                .describe('The cart-relative names of the files written.'),
+            tips: z
+                .array(z.string())
+                .describe('One-line next-step tips (skills discovery + git init). NOT actions init took.'),
+            installedSkills: z
+                .array(z.string())
+                .optional()
+                .describe('Skills installed by --install-skills (absent unless the flag was passed).'),
+            wiredAgents: z
+                .array(z.string())
+                .optional()
+                .describe('Agents whose skill dirs --install-skills wired up (absent unless flagged).'),
+        }),
+        examples: [
+            { description: 'Scaffold in the current folder' },
+            { description: 'Scaffold into a new folder', args: { dir: 'my-game' } },
+            {
+                description: "Scaffold and install picopilot's skills globally",
+                options: { installSkills: true },
+            },
+        ],
+        async run({ args, options, error }) {
+            const targetDir = isAbsolute(args.dir)
+                ? args.dir
+                : resolve(process.cwd(), args.dir);
+            const files = scaffoldFiles();
+            // Refuse rather than clobber: `init` is for a fresh cart. Overwriting an
+            // existing main.p8/main.lua would silently destroy the agent's work, so a
+            // pre-existing scaffold file is a structured refusal, not a surprise write.
+            const clash = files.find((f) => existsSync(join(targetDir, f.name)));
+            if (clash !== undefined) {
+                return error({
+                    code: 'already-initialised',
+                    message: `refusing to overwrite existing ${clash.name} in ${targetDir}; init is for a fresh cart folder`,
+                    exitCode: 1,
+                });
+            }
+            mkdirSync(targetDir, { recursive: true });
+            for (const f of files) {
+                writeFileSync(join(targetDir, f.name), f.content);
+            }
+            // INSTRUCT, do not mutate: these are printed tips, not actions init took.
+            const tips = [
+                "Skills: make your agent discover picopilot's skills with `npx picopilot skills add` (or symlink them yourself); run `picopilot init --install-skills` to install them globally.",
+                'Version control: this folder is not a git repo. Run `git init` yourself if you want one. `init` deliberately does not touch VCS.',
+            ];
+            // Default init is INSTRUCT-not-mutate: it never touches a shared dir. Only
+            // the explicit --install-skills opt-in performs the shared write.
+            if (!options.installSkills) {
+                return {
+                    dir: targetDir,
+                    files: files.map((f) => f.name),
+                    tips,
+                };
+            }
+            // The one shared write: install picopilot's skills. A project install
+            // (--no-global) lands under this cart folder; a global install lands in
+            // the real agent skill dirs. Failures surface structured, not as a crash,
+            // so the scaffold that already succeeded is not masked by an install slip.
+            let install;
+            try {
+                install = await installer({
+                    cli,
+                    global: options.global,
+                    cwd: options.global ? undefined : targetDir,
+                });
+            }
+            catch (e) {
+                return error({
+                    code: 'install-skills-failed',
+                    message: `scaffold succeeded in ${targetDir}, but installing skills failed: ${e instanceof Error ? e.message : String(e)}. Discover them manually instead: run \`picopilot skills add\` or symlink the skills yourself.`,
+                    exitCode: 1,
+                });
+            }
+            // Printed-instructions fallback (US #2): if no known non-universal agent
+            // was detected, the canonical `.agents/skills` install still happened (the
+            // universal-agent path), but a specific agent may not read it, so tell the
+            // user how to wire it manually rather than pretending every agent is set.
+            // Dedup: incur's install.agents has one entry per (skill, agent) symlink
+            // (see work/notes/observations/incur-install-agents-duplicated-per-skill.md),
+            // so N skills x M agents yields N*M entries. wiredAgents is the SET of
+            // agent names, so collapse duplicates here (order-preserving).
+            const wiredAgents = [...new Set(install.agents.map((a) => a.agent))];
+            const fallbackTip = wiredAgents.length === 0
+                ? `Installed to ${install.paths[0] ?? '.agents/skills'}. No known agent skill dir was detected to wire directly; if your agent does not auto-discover .agents/skills, symlink these skills into its skills dir.`
+                : `Wired agents: ${wiredAgents.join(', ')}.`;
+            return {
+                dir: targetDir,
+                files: files.map((f) => f.name),
+                tips: [
+                    ...tips,
+                    `Skills installed: ${install.skills.join(', ')}. ${fallbackTip}`,
+                ],
+                installedSkills: install.skills,
+                wiredAgents,
+            };
+        },
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/lint.d.ts

@@ -0,0 +1,20 @@
+import { type Cli } from 'incur';
+import { type ShrinkoAdapter } from '../engine/shrinko/index.js';
+/** See {@link import('./tokens.js').ShrinkoAdapterFactory}: lint reuses the same seam. */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+/**
+ * Registers `picopilot lint` (US #4): surface PICO-8-specific issues (undefined
+ * globals, unused/duplicate locals, and, via the parsed findings, the classic
+ * gotchas) as STRUCTURED findings via shrinko8 `--lint`, so an agent catches
+ * them before running. Findings are DATA: a cart WITH warnings is a successful
+ * lint that reports them (exit 0), not a failure exit; only a broken cart or a
+ * missing dependency is an error.
+ *
+ * shrinko-backed: absent shrinko returns the structured `shrinko-not-found`
+ * error + nonzero exit (ADR-0002), mirroring `tokens`.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export declare function registerLint(cli: Cli.Cli, adapterFactory?: ShrinkoAdapterFactory): void;
+//# sourceMappingURL=lint.d.ts.map

package/dist/commands/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAClC,OAAO,EACN,KAAK,cAAc,EAEnB,MAAM,4BAA4B,CAAC;AAEpC,0FAA0F;AAC1F,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,cAAc,CAAC;AAK/E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,qBAA6C,GAC3D,IAAI,CAqFN"}

package/dist/commands/lint.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { z } from 'incur';
+import { ShellShrinkoAdapter, } from '../engine/shrinko/index.js';
+const defaultAdapterFactory = (env) => new ShellShrinkoAdapter({ env });
+/**
+ * Registers `picopilot lint` (US #4): surface PICO-8-specific issues (undefined
+ * globals, unused/duplicate locals, and, via the parsed findings, the classic
+ * gotchas) as STRUCTURED findings via shrinko8 `--lint`, so an agent catches
+ * them before running. Findings are DATA: a cart WITH warnings is a successful
+ * lint that reports them (exit 0), not a failure exit; only a broken cart or a
+ * missing dependency is an error.
+ *
+ * shrinko-backed: absent shrinko returns the structured `shrinko-not-found`
+ * error + nonzero exit (ADR-0002), mirroring `tokens`.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerLint(cli, adapterFactory = defaultAdapterFactory) {
+    cli.command('lint', {
+        description: 'Surface PICO-8 lint findings (undefined globals, unused/duplicate locals) via shrinko8. Requires shrinko.',
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to lint. Defaults to main.p8 in the current folder.'),
+        }),
+        env: z.object({
+            PATH: z
+                .string()
+                .optional()
+                .describe('Used to locate shrinko8 in the child process.'),
+        }),
+        output: z.object({
+            findings: z
+                .array(z.object({
+                line: z.number().describe('1-based line in the cart.'),
+                col: z.number().describe('1-based column.'),
+                message: z.string().describe('The lint warning text.'),
+            }))
+                .describe('Every lint warning shrinko reported (empty when the cart is clean).'),
+            clean: z.boolean().describe('True when there are no findings.'),
+            count: z.number().describe('Number of findings.'),
+        }),
+        examples: [
+            { description: 'Lint main.p8' },
+            { description: 'Lint a specific cart', args: { cart: 'game.p8' } },
+        ],
+        async run({ args, env, error, ok }) {
+            const cartPath = isAbsolute(args.cart)
+                ? args.cart
+                : resolve(process.cwd(), args.cart);
+            if (!existsSync(cartPath)) {
+                return error({
+                    code: 'cart-not-found',
+                    message: `no cart at ${cartPath}`,
+                    exitCode: 1,
+                });
+            }
+            const adapter = adapterFactory(env);
+            const result = await adapter.lint(cartPath);
+            if (!result.ok) {
+                return error({
+                    code: result.reason,
+                    message: `shrinko is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+                    exitCode: 1,
+                });
+            }
+            const { findings } = result.value;
+            const clean = findings.length === 0;
+            // Findings are DATA, not a failure exit (an agent reads them and fixes the
+            // code). When there ARE findings, CTA toward the run/verify loop.
+            const cta = clean
+                ? undefined
+                : {
+                    description: `${findings.length} lint finding(s). Fix them, then re-check:`,
+                    commands: [
+                        { command: 'lint', description: 'Re-lint after fixing.' },
+                        {
+                            command: 'verify',
+                            description: 'Run the static gate before running.',
+                        },
+                    ],
+                };
+            return ok({ findings: [...findings], clean, count: findings.length }, cta === undefined ? undefined : { cta });
+        },
+    });
+}
+//# sourceMappingURL=lint.js.map

package/dist/commands/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"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"}

package/dist/commands/minify.d.ts

@@ -0,0 +1,20 @@
+import { type Cli } from 'incur';
+import { type ShrinkoAdapter } from '../engine/shrinko/index.js';
+/** See {@link import('./tokens.js').ShrinkoAdapterFactory}: minify reuses the same seam. */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+/**
+ * Registers `picopilot minify` (US #5, ADR-0007): run shrinko8's SAFE
+ * minification and write the result to a SEPARATE artifact (`<name>.min.p8` by
+ * default), reporting the before/after token delta. It is COMPILER-STYLE: the
+ * user's authored source (`main.p8` / the `#include`d `main.lua`) is NEVER
+ * touched, and it refuses to clobber an existing output unless `--force`.
+ *
+ * Safe-only by default (never aggressive-minify silently). shrinko-backed:
+ * absent shrinko returns the structured `shrinko-not-found` error + nonzero
+ * exit, mirroring `tokens`/`lint`.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export declare function registerMinify(cli: Cli.Cli, adapterFactory?: ShrinkoAdapterFactory): void;
+//# sourceMappingURL=minify.d.ts.map

package/dist/commands/minify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minify.d.ts","sourceRoot":"","sources":["../../src/commands/minify.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAClC,OAAO,EACN,KAAK,cAAc,EAEnB,MAAM,4BAA4B,CAAC;AAEpC,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,cAAc,CAAC;AAoB/E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,qBAA6C,GAC3D,IAAI,CA6GN"}

package/dist/commands/minify.js

@@ -0,0 +1,129 @@
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { z } from 'incur';
+import { ShellShrinkoAdapter, } from '../engine/shrinko/index.js';
+const defaultAdapterFactory = (env) => new ShellShrinkoAdapter({ env });
+/**
+ * Derives the default output path `<name>.min.p8` next to the source cart:
+ * `main.p8` -> `main.min.p8`, `game.p8.png` -> `game.min.p8.png` is NOT the
+ * case (we only special-case the final `.p8`); a plain `<name>.p8` becomes
+ * `<name>.min.p8`. Anything without a `.p8` suffix just gets `.min.p8` appended.
+ */
+function defaultOutPath(cartPath) {
+    const dir = dirname(cartPath);
+    const base = cartPath.slice(dir.length + 1);
+    const out = base.endsWith('.p8')
+        ? `${base.slice(0, -'.p8'.length)}.min.p8`
+        : `${base}.min.p8`;
+    return join(dir, out);
+}
+/**
+ * Registers `picopilot minify` (US #5, ADR-0007): run shrinko8's SAFE
+ * minification and write the result to a SEPARATE artifact (`<name>.min.p8` by
+ * default), reporting the before/after token delta. It is COMPILER-STYLE: the
+ * user's authored source (`main.p8` / the `#include`d `main.lua`) is NEVER
+ * touched, and it refuses to clobber an existing output unless `--force`.
+ *
+ * Safe-only by default (never aggressive-minify silently). shrinko-backed:
+ * absent shrinko returns the structured `shrinko-not-found` error + nonzero
+ * exit, mirroring `tokens`/`lint`.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerMinify(cli, adapterFactory = defaultAdapterFactory) {
+    cli.command('minify', {
+        description: 'Safe-minify a cart to a SEPARATE artifact (<name>.min.p8), reporting the token delta. Source untouched. Requires shrinko.',
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to minify. Defaults to main.p8 in the current folder.'),
+        }),
+        options: z.object({
+            out: z
+                .string()
+                .optional()
+                .describe('Output cart path. Defaults to <name>.min.p8 next to the source.'),
+            force: z
+                .boolean()
+                .default(false)
+                .describe('Overwrite an existing output cart. Default off (no-clobber).'),
+        }),
+        env: z.object({
+            PATH: z
+                .string()
+                .optional()
+                .describe('Used to locate shrinko8 in the child process.'),
+        }),
+        output: z.object({
+            outPath: z
+                .string()
+                .describe('Absolute path of the minified cart written.'),
+            beforeTokens: z.number().describe('Tokens in the source cart.'),
+            afterTokens: z.number().describe('Tokens in the minified cart.'),
+            saved: z.number().describe('Tokens reclaimed (before - after).'),
+        }),
+        examples: [
+            { description: 'Minify main.p8 to main.min.p8' },
+            {
+                description: 'Minify to a chosen path',
+                args: { cart: 'game.p8' },
+                options: { out: 'dist/game.p8' },
+            },
+        ],
+        async run({ args, options, env, error, ok }) {
+            const cartPath = isAbsolute(args.cart)
+                ? args.cart
+                : resolve(process.cwd(), args.cart);
+            if (!existsSync(cartPath)) {
+                return error({
+                    code: 'cart-not-found',
+                    message: `no cart at ${cartPath}`,
+                    exitCode: 1,
+                });
+            }
+            const outPath = options.out !== undefined
+                ? isAbsolute(options.out)
+                    ? options.out
+                    : resolve(process.cwd(), options.out)
+                : defaultOutPath(cartPath);
+            // Guard the source FIRST: never let --out point AT the source cart (that
+            // would be in-place mutation, which ADR-0007 forbids). Checked before the
+            // no-clobber guard so it wins even though the source obviously exists.
+            if (outPath === cartPath) {
+                return error({
+                    code: 'output-is-source',
+                    message: `--out must differ from the source cart (${cartPath}); minify never mutates the source`,
+                    exitCode: 1,
+                });
+            }
+            // No-clobber (ADR-0007, mirrors init): refuse to overwrite an existing
+            // artifact unless --force, so a minify never silently destroys a prior one.
+            if (existsSync(outPath) && !options.force) {
+                return error({
+                    code: 'output-exists',
+                    message: `refusing to overwrite existing ${outPath}; pass --force to overwrite`,
+                    exitCode: 1,
+                });
+            }
+            const adapter = adapterFactory(env);
+            const result = await adapter.minify(cartPath, outPath);
+            if (!result.ok) {
+                return error({
+                    code: result.reason,
+                    message: `shrinko is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+                    exitCode: 1,
+                });
+            }
+            const { beforeTokens, afterTokens } = result.value;
+            return ok({
+                outPath,
+                beforeTokens,
+                afterTokens,
+                saved: beforeTokens - afterTokens,
+            });
+        },
+    });
+}
+//# sourceMappingURL=minify.js.map

package/dist/commands/minify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minify.js","sourceRoot":"","sources":["../../src/commands/minify.ts"],"names":[],"mappings":"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"}

package/dist/commands/music.d.ts

@@ -0,0 +1,13 @@
+import { Cli } from 'incur';
+/**
+ * Registers the `music` command group (`music from-patterns`) on the root CLI.
+ *
+ * `music` is a shrinko-FREE and PICO-8-FREE command group: it assembles a
+ * structural pattern list into `__music__` and merges it through the cart model
+ * entirely in TS, so it works with both absent and never spawns a child process.
+ * Music is STRUCTURAL (ADR-0005 + the audio spike finding A.5/B.6): a pattern
+ * list of SFX references, NOT a notation. "Off" (bit6) is distinct from "sfx 0",
+ * and pattern length is inherited from the referenced SFX (stored nowhere here).
+ */
+export declare function registerMusic(cli: Cli.Cli): void;
+//# sourceMappingURL=music.d.ts.map

package/dist/commands/music.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.d.ts","sourceRoot":"","sources":["../../src/commands/music.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAiR7B;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAEhD"}