@tommy-ca/lazypi 0.10.1 → 0.10.3

package/README.md

@@ -13,17 +13,43 @@ LazyPi will:
 1. Install `pi` for you if it isn't installed yet.
 2. Ask if you want to install all the packages or choose which to install.
 
-That setup is the harness core — isolated sub-agents, a structured ask gate, skill visibility, $ skill mention, a long-objective gate, side chat, context budgeting, code simplification review, web research, FFF search, a workflow engine for sub-agent fan-out, and ponytail discipline review. A five-package optional tier (targeted LSP diagnostics, interactive shell overlays, autonomous research loops, structured todo tracking, markdown-backed memory) installs on request with `--only optional`. Other extras (skill arguments, MCP, ralph-wiggum, themes) install on demand with `pi install`.
+That setup is the 12-package harness core. `--yes` installs those 12. On a TTY, Install everything installs all 17. Packages LazyPi dropped stay installable with `pi install`. LazyPi does not manage them. See the Catalog table and `docs/docs/philosophy.html`.
 
 That's it.  Once done - run `pi` and experience a feature rich coding agent experience.
 
 Install is **idempotent** — LazyPi reads your Pi settings and skips any package that is already installed, so re-running is safe.
 
+## Catalog
+
+`--yes` installs 12 core packages. TTY Install everything installs all 17.
+
+| id | category | why |
+| --- | --- | --- |
+| subagents | core | Isolated specialists instead of one bloated agent |
+| pi-ask-user | core | Stop and ask instead of guessing |
+| pi-skillful | core | Keep 4 to 6 skills visible. Hide the rest |
+| mention-skill | core | `$` mention is the one way to reach hidden skills |
+| goal | core | Long-objective gate. Not a checkbox list |
+| btw | core | Side chat that does not pollute history |
+| context-usage | core | See what is burning the window |
+| simplify | core | Review diffs for clarity after implementation |
+| web-access | core | Search and fetch instead of stale training data |
+| fff | core | Paged fuzzy search so grep does not flood the transcript |
+| dynamic-workflows | core | Fan work out across subagents |
+| ponytail | core | Stdlib-first discipline. Lean catalog as a habit |
+| lsp | optional | Targeted diagnostics. Cataloged, not default |
+| interactive-shell | optional | TUI overlays. Chrome, not control plane |
+| autoresearch | optional | Experiment loops. Convenience, not core |
+| todos | optional | Structured tracker. Optional because core forbids checkbox todos as default |
+| memory | optional | Git-backed memory. Infrastructure, not control plane |
+
+Dropped packages are outside this table. `pi install` still works. LazyPi does not manage them.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `npx @tommy-ca/lazypi` | Install all or selected catalog (interactive picker by default) |
+| `npx @tommy-ca/lazypi` | TTY Install everything is 17. `--yes` is the 12 core packages. Picker otherwise. |
 | `npx @tommy-ca/lazypi remove <id>` | Remove a catalog package by id (or pass a raw pi source) |
 | `npx @tommy-ca/lazypi status` | Show which catalog packages are installed, missing, or extra |
 | `npx @tommy-ca/lazypi update` | Run `pi update` for installed Pi packages |
@@ -71,7 +97,7 @@ specs behave the same way, so `cd` out of the checkout first.
 
 ## Site / docs
 
-The site at [lazypi.org](https://lazypi.org) lives in `docs/` and is a Jekyll site compiled by GitHub Pages automatically on push to `master`.
+The Jekyll source lives in `docs/`. This fork does not enable GitHub Pages, and [lazypi.org](https://lazypi.org) still serves the upstream installer.
 
 To preview locally (requires Ruby + Bundler):
 
@@ -106,4 +132,4 @@ before treating releases as automated.
 
 ---
 
-For the full list of included packages and optional extras, see [lazypi.org](https://lazypi.org).
+The catalog table above is the npm list. `docs/docs/philosophy.html` explains membership. Run `npx @tommy-ca/lazypi` to install.

package/bin/lazypi.mjs

@@ -96,6 +96,25 @@ function renderLogo() {
 // ---------------------------------------------------------------------------
 const KNOWN_COMMANDS = new Set(["install", "status", "update", "doctor", "remove"]);
 
+function assignSelector(flags, key, raw) {
+	const list = parseList(raw);
+	if (list.length === 0) {
+		flags.usageError ??= `--${key} requires a non-empty list`;
+		return;
+	}
+	flags[key] = list;
+}
+
+function consumeSelector(args, i, flags, key) {
+	const value = args[i + 1];
+	if (value == null || value.startsWith("-")) {
+		flags.usageError ??= `--${key} requires a non-empty list`;
+		return i;
+	}
+	assignSelector(flags, key, value);
+	return i + 1;
+}
+
 function parseArgs(args) {
 	const flags = {
 		command: "install",
@@ -107,6 +126,7 @@ function parseArgs(args) {
 		only: null,
 		except: null,
 		targets: [],
+		usageError: null,
 	};
 
 	let i = 0;
@@ -121,10 +141,10 @@ function parseArgs(args) {
 		else if (arg === "-y" || arg === "--yes") flags.yes = true;
 		else if (arg === "-V" || arg === "--version") flags.version = true;
 		else if (arg === "-h" || arg === "--help") flags.help = true;
-		else if (arg === "--only") flags.only = parseList(args[++i]);
-		else if (arg.startsWith("--only=")) flags.only = parseList(arg.slice("--only=".length));
-		else if (arg === "--except") flags.except = parseList(args[++i]);
-		else if (arg.startsWith("--except=")) flags.except = parseList(arg.slice("--except=".length));
+		else if (arg === "--only") i = consumeSelector(args, i, flags, "only");
+		else if (arg.startsWith("--only=")) assignSelector(flags, "only", arg.slice("--only=".length));
+		else if (arg === "--except") i = consumeSelector(args, i, flags, "except");
+		else if (arg.startsWith("--except=")) assignSelector(flags, "except", arg.slice("--except=".length));
 		else if (flags.command === "remove" && !arg.startsWith("-")) flags.targets.push(arg);
 		else {
 			console.error(red(`Unknown argument: ${arg}`));
@@ -134,6 +154,10 @@ function parseArgs(args) {
 		}
 	}
 
+	if (flags.only && flags.except) {
+		flags.usageError ??= "Use either --only or --except, not both";
+	}
+
 	return flags;
 }
 
@@ -151,9 +175,10 @@ function validateSelectors(list, label) {
 	if (bad.length > 0) {
 		console.error(red(`Unknown ${label}: ${bad.join(", ")}`));
 		console.error(`Valid categories: ${CATEGORIES.join(", ")}`);
-		console.error(`Valid package ids:  ${[...ids].join(", ")}`);
-		exit(2);
+		console.error(`Valid package ids: ${[...ids].join(", ")}`);
+		return false;
 	}
+	return true;
 }
 
 function matchesSelector(pkg, selectors) {
@@ -162,11 +187,11 @@ function matchesSelector(pkg, selectors) {
 
 function resolveSelection(flags) {
 	if (flags.only) {
-		validateSelectors(flags.only, "--only");
+		if (!validateSelectors(flags.only, "--only")) return null;
 		return new Set(PACKAGES.filter((p) => matchesSelector(p, flags.only)).map((p) => p.id));
 	}
 	if (flags.except) {
-		validateSelectors(flags.except, "--except");
+		if (!validateSelectors(flags.except, "--except")) return null;
 		return new Set(PACKAGES.filter((p) => !matchesSelector(p, flags.except)).map((p) => p.id));
 	}
 	return new Set(PACKAGES.filter((p) => p.category === "core").map((p) => p.id));
@@ -206,8 +231,8 @@ ${bold("Default behaviour:")}
 ${bold("Categories:")}
   core         the harness control plane: sub-agents, workflows, ask gate, skill visibility, $ mention, goal, side chat, context budget, simplify, web research, fff search, ponytail discipline
   optional     only when selected (--only optional, picker, or the everything flow): lsp diagnostics, interactive-shell overlays, autoresearch loops, todo tracking, markdown memory
-  Non-catalog extras (pi install npm:<source>): skill-args, mcp,
-  ralph-wiggum, curated-themes (65 dark themes)
+  (Dropped packages such as skill-args, mcp, ralph-wiggum, curated-themes are
+  outside the catalog — pi install npm:<source> still works for them.)
 
 ${bold("Examples:")}
   npx @tommy-ca/lazypi                              # core catalog (interactive picker on a TTY)
@@ -224,18 +249,13 @@ ${bold("Examples:")}
 // Pi / settings plumbing
 // ---------------------------------------------------------------------------
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-// On Windows, package-manager CLIs and global Node bins are usually `.cmd`
-// shims. Node's child_process docs note that those need to be launched via a
-// shell, so we route spawned commands through the platform shell there while
-// keeping direct execution on Unix.
-export function buildSpawnOptions(options = {}, platformName = platform()) {
-	const resolved = { ...options };
-	if (platformName === "win32" && resolved.shell == null) resolved.shell = true;
-	return resolved;
+export function buildSpawnOptions(options = {}, _platformName = platform()) {
+	return { ...options };
 }
 
 function spawnCommand(command, args = [], options = {}) {
-	return spawnSync(command, args, buildSpawnOptions(options));
+	const resolved = command === "pi" || command === "npm" ? commandPath(command) ?? command : command;
+	return spawnSync(resolved, args, buildSpawnOptions(options));
 }
 
 function hasCmd(name) {
@@ -296,11 +316,19 @@ function writeSettings(local, mutate) {
 	return { ok: true, path: current.path, backup, changed: true };
 }
 
-function writeSubagentOverrides(local) {
+export function writeSubagentOverrides(local) {
 	return writeSettings(local, (settings) => {
-		const overrides = {};
-		for (const name of SUBAGENT_BUILTIN_MODELS) overrides[name] = { model: "" };
-		settings.subagents = { ...(settings.subagents ?? {}), agentOverrides: { ...(settings.subagents?.agentOverrides ?? {}), ...overrides } };
+		const existing = settings.subagents?.agentOverrides ?? {};
+		const overrides = { ...existing };
+		let changed = false;
+		for (const name of SUBAGENT_BUILTIN_MODELS) {
+			const current = overrides[name];
+			if (current && typeof current === "object" && !Array.isArray(current) && current.model === "") continue;
+			overrides[name] = { ...(current && typeof current === "object" && !Array.isArray(current) ? current : {}), model: "" };
+			changed = true;
+		}
+		if (!changed) return false;
+		settings.subagents = { ...(settings.subagents ?? {}), agentOverrides: overrides };
 		return true;
 	});
 }
@@ -325,12 +353,16 @@ function readInstalledSources(local) {
 
 function commandPath(name) {
 	const command = platform() === "win32" ? "where" : "which";
-	const probe = spawnCommand(command, [name], { encoding: "utf8" });
+	const probe = spawnSync(command, [name], buildSpawnOptions({ encoding: "utf8" }));
 	if (probe.status !== 0) return null;
 	const first = String(probe.stdout ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean);
 	return first || null;
 }
 
+function printSettingsParseError(current) {
+	console.error(red(`Could not parse ${current.path} — ${current.error}`));
+}
+
 function legacySourcesForPackage(pkg) {
 	return Array.isArray(pkg.legacySources) ? pkg.legacySources : [];
 }
@@ -499,6 +531,11 @@ async function ensurePi(flags) {
 	if (hasCmd("pi")) return true;
 
 	log.warn("Could not find the `pi` command on PATH.");
+	if (!flags.yes && !isInteractive()) {
+		log.error("Install Pi first (`npm install -g @earendil-works/pi-coding-agent`), then re-run `npx @tommy-ca/lazypi`.");
+		return false;
+	}
+
 	const ok = flags.yes || (await confirm("Install Pi now with `npm install -g @earendil-works/pi-coding-agent`?", true));
 	if (!ok) {
 		log.error("Install Pi first, then re-run `npx @tommy-ca/lazypi`.");
@@ -524,6 +561,7 @@ async function ensurePi(flags) {
 // ---------------------------------------------------------------------------
 async function cmdInstall(flags) {
 	let selectedIds = resolveSelection(flags);
+	if (!selectedIds) return 2;
 
 	const usedSelectionFlag = Boolean(flags.only || flags.except);
 	const interactive = !flags.yes && !usedSelectionFlag && isInteractive();
@@ -532,6 +570,18 @@ async function cmdInstall(flags) {
 		console.log(renderLogo());
 		intro(bold("LazyPi"));
 	}
+
+	const settings = readSettings(flags.local);
+	if (settings.error) {
+		if (interactive) {
+			log.error(`Could not parse ${settings.path} — ${settings.error}`);
+			outro(red("Aborted."));
+		} else {
+			printSettingsParseError(settings);
+		}
+		return 2;
+	}
+
 	if (!(await ensurePi(flags))) return 127;
 
 	if (interactive) {
@@ -550,8 +600,7 @@ async function cmdInstall(flags) {
 		return 0;
 	}
 
-	const { sources: installedSources, error: settingsError } = readInstalledSources(flags.local);
-	if (settingsError) log.warn(`Could not parse ${settingsPath(flags.local)} — ${settingsError}`);
+	const { sources: installedSources } = readInstalledSources(flags.local);
 
 	const toInstall = selected.filter((pkg) => {
 		return !isPackageInstalled(pkg, installedSources);
@@ -706,7 +755,7 @@ function cmdStatus(flags) {
 		console.log(yellow("  (not found — Pi has not written settings yet)"));
 	} else if (error) {
 		console.error(red(`  could not parse: ${error}`));
-		return 1;
+		return 2;
 	}
 
 	const installed = PACKAGES.filter((pkg) => packageInstallStatus(pkg, sources).installed);
@@ -719,7 +768,8 @@ function cmdStatus(flags) {
 	printHeader(`Installed from LazyPi catalog (${installed.length}/${PACKAGES.length}):`);
 	if (installed.length === 0) console.log(dim("  none"));
 	for (const pkg of installed) {
-		console.log(`  ${green("✓")} [${pkg.category}] ${pkg.id.padEnd(20)} ${dim(pkg.source)}`);
+		const installedSource = [...sources].find((src) => sourcesMatch(pkg.source, src)) ?? pkg.source;
+		console.log(`  ${green("✓")} [${pkg.category}] ${pkg.id.padEnd(20)} ${dim(installedSource)}`);
 	}
 
 	printHeader(`Installed with legacy catalog sources (${legacy.length}):`);
@@ -746,14 +796,14 @@ function cmdStatus(flags) {
 // update
 // ---------------------------------------------------------------------------
 async function cmdUpdate(flags) {
-	if (!(await ensurePi(flags))) return 127;
-
 	const settings = readSettings(flags.local);
 	if (settings.error) {
-		console.error(red(`Could not parse ${settingsPath(flags.local)} — ${settings.error}`));
-		return 1;
+		printSettingsParseError(settings);
+		return 2;
 	}
 
+	if (!(await ensurePi(flags))) return 127;
+
 	console.log(bold("pi update"));
 
 	return spawnCommand("pi", flags.local ? ["update", "--extensions"] : ["update"], { stdio: "inherit" }).status ?? 1;
@@ -763,6 +813,12 @@ async function cmdUpdate(flags) {
 // doctor
 // ---------------------------------------------------------------------------
 function cmdDoctor(flags) {
+	const settings = readSettings(flags.local);
+	if (settings.error) {
+		printSettingsParseError(settings);
+		return 2;
+	}
+
 	let problems = 0;
 	let warnings = 0;
 	const pass = (msg) => console.log(`  ${green("✓")} ${msg}`);
@@ -831,12 +887,18 @@ function cmdDoctor(flags) {
 // remove
 // ---------------------------------------------------------------------------
 async function cmdRemove(flags, targets) {
+	const installed = readInstalledSources(flags.local);
+	if (installed.error) {
+		printSettingsParseError(installed);
+		return 2;
+	}
+
 	if (targets.length === 0) {
 		if (!isInteractive()) {
 			console.error(red("Usage: npx @tommy-ca/lazypi remove <id|source> [...]"));
 			return 2;
 		}
-		const { sources } = readInstalledSources(flags.local);
+		const { sources } = installed;
 		const installedPkgs = PACKAGES.filter((p) => isPackagePresent(p, sources));
 		if (installedPkgs.length === 0) {
 			console.log(yellow("No catalog packages are installed."));
@@ -860,10 +922,9 @@ async function cmdRemove(flags, targets) {
 		targets = picked;
 	}
 
-	const { sources: installedSources } = readInstalledSources(flags.local);
+	const { sources: installedSources } = installed;
 	let exitCode = 0;
 	for (const target of targets) {
-		// Resolve a catalog id to its source string, or pass through raw sources
 		const pkg = PACKAGES.find((p) => p.id === target);
 		const source = pkg ? pkg.source : target;
 
@@ -896,6 +957,11 @@ async function main() {
 		console.log(`@tommy-ca/lazypi ${VERSION}`);
 		return 0;
 	}
+	if (flags.usageError) {
+		console.error(red(flags.usageError));
+		printHelp();
+		return 2;
+	}
 	if (flags.help) {
 		printHelp();
 		return flags.badArg ? 2 : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tommy-ca/lazypi",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Opinionated one-shot installer for a full-featured Pi coding agent setup.",
   "license": "MIT",
   "repository": {