@themoltnet/legreffier 0.31.0 → 0.32.1

package/README.md

@@ -36,16 +36,19 @@ and across agents.
 
 ```bash
 # Run directly (no install needed)
-npx @themoltnet/legreffier --name my-agent
+npx @themoltnet/legreffier init --name my-agent
 
 # Or install globally
 npm install -g @themoltnet/legreffier
-legreffier --name my-agent
+legreffier init --name my-agent
 ```
 
+Every invocation requires an explicit subcommand (`init`, `setup`, `port`,
+or `github`). Run `legreffier --help` to see them all.
+
 ### Subcommands
 
-#### `legreffier init` (default)
+#### `legreffier init`
 
 Full onboarding: identity, GitHub App, git signing, agent setup.
 

package/dist/index.js

@@ -1,263 +1,18 @@
 #!/usr/bin/env node
-import { statSync } from "node:fs";
-import { parseArgs, parseEnv } from "node:util";
-import { Box, Text, render, useApp, useInput } from "ink";
+import { defineCommand, runMain } from "citty";
 import { execFileSync, execSync } from "node:child_process";
 import { basename, dirname, isAbsolute, join } from "node:path";
+import { Box, Text, render, useApp, useInput } from "ink";
 import { useEffect, useReducer, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-import figlet from "figlet";
 import { createSign } from "node:crypto";
 import { createHash, randomBytes } from "crypto";
 import { access, chmod, copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { parse, stringify } from "smol-toml";
+import { parseEnv } from "node:util";
 import open from "open";
-//#region src/commands/help.ts
-function formatFlag(flag) {
-	const head = flag.short ? `${flag.name}, ${flag.short}` : flag.name;
-	const value = flag.value ? ` ${flag.value}` : "";
-	const suffixParts = [];
-	if (flag.required) suffixParts.push("(required)");
-	if (flag.default !== void 0) suffixParts.push(`default: ${flag.default}`);
-	return `  ${head}${value}${suffixParts.length > 0 ? `  [${suffixParts.join(", ")}]` : ""}\n      ${flag.description}`;
-}
-function printCommandHelp(help) {
-	const lines = [];
-	lines.push(`${help.command} — ${help.summary}`);
-	lines.push("");
-	lines.push(`Usage: ${help.usage}`);
-	lines.push("");
-	lines.push(help.description);
-	if (help.flags.length > 0) {
-		lines.push("");
-		lines.push("Flags:");
-		for (const flag of help.flags) lines.push(formatFlag(flag));
-	}
-	if (help.examples.length > 0) {
-		lines.push("");
-		lines.push("Examples:");
-		for (const ex of help.examples) {
-			lines.push(`  # ${ex.description}`);
-			lines.push(`  ${ex.command}`);
-		}
-	}
-	if (help.notes && help.notes.length > 0) {
-		lines.push("");
-		lines.push("Notes:");
-		for (const note of help.notes) lines.push(`  - ${note}`);
-	}
-	lines.push("");
-	process.stdout.write(lines.join("\n"));
-}
-function printRootHelp(commands) {
-	const lines = [];
-	lines.push("legreffier — LeGreffier CLI");
-	lines.push("");
-	lines.push("Usage: legreffier <command> [flags]");
-	lines.push("");
-	lines.push("Commands:");
-	const pad = Math.max(...commands.map((c) => c.command.length)) + 2;
-	for (const cmd of commands) lines.push(`  ${cmd.command.padEnd(pad)}${cmd.summary}`);
-	lines.push("");
-	lines.push("Run `legreffier <command> --help` for command-specific help.");
-	lines.push("");
-	process.stdout.write(lines.join("\n"));
-}
-var COMMANDS = [
-	{
-		command: "init",
-		summary: "Create a new agent identity and wire it into this repository",
-		usage: "legreffier init --name <agent-name> [flags]",
-		description: "Runs the full 5-phase onboarding: generates an Ed25519 keypair, registers the agent on MoltNet, creates a GitHub App via manifest flow, writes the gitconfig with SSH signing, installs the GitHub App on selected repos, and writes the MCP config for your chosen agent clients.",
-		flags: [
-			{
-				name: "--name",
-				short: "-n",
-				value: "<agent-name>",
-				description: "Agent name (2-39 lowercase alphanumerics/hyphens, e.g. `jobi`)",
-				required: true
-			},
-			{
-				name: "--agent",
-				short: "-a",
-				value: "claude|codex",
-				description: "Agent client to configure (repeatable). Default: no client config written."
-			},
-			{
-				name: "--api-url",
-				value: "<url>",
-				description: "MoltNet API base URL",
-				default: "https://api.themolt.net"
-			},
-			{
-				name: "--dir",
-				value: "<path>",
-				description: "Target repository root",
-				default: "current working directory"
-			},
-			{
-				name: "--org",
-				short: "-o",
-				value: "<github-org>",
-				description: "GitHub organization to install the App on (optional)"
-			}
-		],
-		examples: [{
-			description: "Basic init for a new agent named `jobi`",
-			command: "legreffier init --name jobi --agent claude"
-		}, {
-			description: "Init against a local API",
-			command: "legreffier init --name jobi --agent claude --api-url http://localhost:3000"
-		}]
-	},
-	{
-		command: "setup",
-		summary: "Install LeGreffier skills and MCP config into an existing repo",
-		usage: "legreffier setup --name <agent-name> [flags]",
-		description: "For a repository that already has `.moltnet/<agent-name>/` credentials (e.g. after running `init` elsewhere), `setup` writes the MCP config, downloads skills, and configures your agent clients. Does not touch identity, keys, or GitHub App state.",
-		flags: [
-			{
-				name: "--name",
-				short: "-n",
-				value: "<agent-name>",
-				description: "Agent name (must already exist under `.moltnet/`)",
-				required: true
-			},
-			{
-				name: "--agent",
-				short: "-a",
-				value: "claude|codex",
-				description: "Agent client to configure (repeatable)"
-			},
-			{
-				name: "--dir",
-				value: "<path>",
-				description: "Target repository root",
-				default: "current working directory"
-			}
-		],
-		examples: [{
-			description: "Install skills and MCP config for both Claude and Codex",
-			command: "legreffier setup --name jobi --agent claude --agent codex"
-		}]
-	},
-	{
-		command: "port",
-		summary: "Copy an existing agent from another repository into this one",
-		usage: "legreffier port --name <agent-name> --from <repo-root>/.moltnet/<agent-name> [flags]",
-		description: "Ports an existing agent identity (keypair, moltnet.json, gitconfig, GitHub App credentials) from a source repository into the current one. `--from` is strict: it must point to the exact `<repo-root>/.moltnet/<agent-name>` directory. The source repo is not modified.",
-		flags: [
-			{
-				name: "--name",
-				short: "-n",
-				value: "<agent-name>",
-				description: "Agent name to port (must exist under `--from`)",
-				required: true
-			},
-			{
-				name: "--from",
-				value: "<repo-root>/.moltnet/<agent-name>",
-				description: "Absolute path to the source agent directory. Strict format: must be `<repo-root>/.moltnet/<agent-name>` and contain moltnet.json + gitconfig.",
-				required: true
-			},
-			{
-				name: "--agent",
-				short: "-a",
-				value: "claude|codex",
-				description: "Agent client to configure in the target repo (repeatable)",
-				default: "claude"
-			},
-			{
-				name: "--dir",
-				value: "<path>",
-				description: "Target repository root",
-				default: "current working directory"
-			},
-			{
-				name: "--diary",
-				value: "new|reuse|skip",
-				description: "How to handle the diary in the new repo: `new` creates a fresh diary, `reuse` reuses the source diary ID, `skip` leaves MOLTNET_DIARY_ID unset",
-				default: "new"
-			}
-		],
-		examples: [{
-			description: "Port agent `jobi` from a sibling repo",
-			command: "legreffier port --name jobi --from /Users/me/code/other-repo/.moltnet/jobi"
-		}, {
-			description: "Port and reuse the existing diary",
-			command: "legreffier port --name jobi --from /Users/me/code/other-repo/.moltnet/jobi --diary reuse"
-		}],
-		notes: ["The source repo is read-only; nothing there is modified.", "`--from` does not accept relative paths, `~`, or repo-name shorthands. Provide the full `.moltnet/<agent>` directory path."]
-	}
-];
-//#endregion
-//#region src/commands/resolveCommand.ts
-/**
-* Long-form option names that consume the next argument as a value.
-* Used by `resolveHelpCommand` to skip over option values when scanning
-* for the first positional subcommand.
-*/
-var VALUE_OPTIONS_LONG = new Set([
-	"--name",
-	"--agent",
-	"--api-url",
-	"--dir",
-	"--org",
-	"--from",
-	"--diary"
-]);
-/**
-* Short-form option names that consume the next argument as a value.
-* Kept in sync with `parseArgs` options in index.tsx.
-*/
-var VALUE_OPTIONS_SHORT = new Set([
-	"-n",
-	"-a",
-	"-o"
-]);
-function isValueOption(arg) {
-	if (VALUE_OPTIONS_LONG.has(arg)) return true;
-	if (VALUE_OPTIONS_SHORT.has(arg)) return true;
-	return false;
-}
-/**
-* Resolve which command's help to print for `legreffier <...> --help`.
-*
-* Scans `rawArgs` linearly, skipping option flags and their values, and
-* returns the first positional argument that matches a known command. If
-* no positional is found (or the positional is not a known command),
-* returns `null` so the caller prints root help.
-*
-* Unlike `rawArgs.find((a) => !a.startsWith('-'))`, this correctly handles
-* flags-before-subcommand orderings like:
-*
-*   legreffier --name jobi port --help
-*
-* where the naive scan would return "jobi" instead of "port".
-*
-* Unknown positionals (typos, etc.) fall back to root help rather than
-* silently matching nothing, so users see the full command list.
-*/
-function resolveHelpCommand(rawArgs, commands) {
-	for (let i = 0; i < rawArgs.length; i++) {
-		const arg = rawArgs[i];
-		if (arg === void 0) continue;
-		if (arg === "--help" || arg === "-h") continue;
-		if (arg.startsWith("--") && arg.includes("=")) continue;
-		if (arg.startsWith("--")) {
-			if (isValueOption(arg)) i++;
-			continue;
-		}
-		if (arg.startsWith("-") && arg.length > 1) {
-			if (isValueOption(arg)) i++;
-			continue;
-		}
-		return commands.find((c) => c.command === arg) ?? null;
-	}
-	return null;
-}
-//#endregion
+import { statSync } from "node:fs";
 //#region src/github-token.ts
 var MOLTNET_GITCONFIG_RE = /\.moltnet\/([^/]+)\/gitconfig$/;
 function resolveAgentName(nameFlag, gitConfigGlobal) {
@@ -289,6 +44,146 @@ function printGitHubToken(agentName, dir) {
 	process.stdout.write(token);
 }
 //#endregion
+//#region src/ui/types.ts
+var SUPPORTED_AGENTS = ["claude", "codex"];
+//#endregion
+//#region src/commands/shared.ts
+/**
+* Regex for valid agent names: 2-39 chars, lowercase alphanumerics and
+* hyphens, must start and end with an alphanumeric. Matches the server-side
+* validation so a client-side failure gives immediate feedback rather than
+* a REST 400 after a keypair has been generated.
+*/
+var AGENT_NAME_RE = /^[a-z0-9][a-z0-9-]{0,37}[a-z0-9]$/;
+var DEFAULT_API_URL = "https://api.themolt.net";
+/**
+* Common argument definitions shared across subcommands. Kept as plain
+* objects (not a merged record) so individual commands can pick the flags
+* they actually accept instead of inheriting every flag.
+*/
+var commonArgs = {
+	name: {
+		type: "string",
+		description: "Agent name (2-39 lowercase alphanumerics or hyphens, e.g. `jobi`)",
+		alias: "n",
+		valueHint: "agent-name"
+	},
+	agent: {
+		type: "string",
+		description: "Agent client to configure (repeatable: --agent claude --agent codex). Accepts: claude, codex.",
+		alias: "a",
+		valueHint: "claude|codex"
+	},
+	"api-url": {
+		type: "string",
+		description: "MoltNet API base URL (default: $MOLTNET_API_URL or https://api.themolt.net)",
+		valueHint: "url"
+	},
+	dir: {
+		type: "string",
+		description: "Target repository root (default: current working directory)",
+		valueHint: "path"
+	}
+};
+/**
+* Collect repeated `--agent` / `-a` values from rawArgs.
+*
+* Citty wraps Node's `parseArgs` without `multiple: true`, which means
+* repeating `--agent claude --agent codex` keeps only the last value. The
+* hand-rolled CLI supported repeats and users' docs rely on that shape, so
+* we walk `rawArgs` ourselves to rebuild the full list before validating it
+* against the supported-agent allowlist.
+*/
+function collectAgents(rawArgs) {
+	const out = [];
+	for (let i = 0; i < rawArgs.length; i++) {
+		const token = rawArgs[i];
+		if (token === "--") break;
+		let value;
+		if (token === "--agent" || token === "-a") {
+			value = rawArgs[i + 1];
+			i++;
+		} else if (token.startsWith("--agent=")) value = token.slice(8);
+		else if (token.startsWith("-a=")) value = token.slice(3);
+		if (value === void 0) continue;
+		if (!SUPPORTED_AGENTS.includes(value)) throw new CliValidationError(`Unsupported agent: ${value}. Supported: ${SUPPORTED_AGENTS.join(", ")}`);
+		out.push(value);
+	}
+	return out;
+}
+/**
+* Validate a `--name` arg. Throws with the same user-facing message as the
+* previous hand-rolled CLI so scripts and docs referencing it keep working.
+*/
+function requireAgentName(name) {
+	if (typeof name !== "string" || name.length === 0) throw new CliValidationError("--name is required");
+	if (!AGENT_NAME_RE.test(name)) throw new CliValidationError(`Invalid agent name: "${name}". Must be 2-39 lowercase alphanumeric characters or hyphens, starting and ending with a letter or digit.`);
+	return name;
+}
+/** Resolve the target repo dir, defaulting to CWD. */
+function resolveDir(dir) {
+	if (typeof dir === "string" && dir.length > 0) return dir;
+	return process.cwd();
+}
+/** Resolve the API URL: --api-url flag > $MOLTNET_API_URL > default. */
+function resolveApiUrl(apiUrl) {
+	if (typeof apiUrl === "string" && apiUrl.length > 0) return apiUrl;
+	return process.env["MOLTNET_API_URL"] ?? DEFAULT_API_URL;
+}
+/**
+* Thrown by shared validators (`requireAgentName`, `collectAgents`,
+* `validatePortFromArg` adapters, etc.) when the user passed a bad flag
+* value. `withCleanErrors` catches these and prints a single-line
+* "Error: <msg>" on stderr + exit 1, instead of letting citty dump the
+* full stack via its default `console.error(error, "\n")` handler.
+*/
+var CliValidationError = class extends Error {
+	name = "CliValidationError";
+};
+/**
+* Wrap a command handler so `CliValidationError`s print a single clean
+* line and exit 1. Unexpected errors (bugs, TypeErrors, network failures)
+* still bubble up with their full stack so we can debug them.
+*/
+function withCleanErrors(handler) {
+	return async (ctx) => {
+		try {
+			await handler(ctx);
+		} catch (err) {
+			if (err instanceof CliValidationError) {
+				process.stderr.write(`Error: ${err.message}\n`);
+				process.exit(1);
+			}
+			throw err;
+		}
+	};
+}
+var githubCommand = defineCommand({
+	meta: {
+		name: "github",
+		description: "GitHub-related helpers (token minting)"
+	},
+	subCommands: { token: defineCommand({
+		meta: {
+			name: "token",
+			description: "Print a short-lived installation token for the agent GitHub App (reads .moltnet/<agent>/moltnet.json)."
+		},
+		args: {
+			name: commonArgs.name,
+			dir: commonArgs.dir
+		},
+		run: withCleanErrors(({ args }) => {
+			let agentName;
+			try {
+				agentName = resolveAgentName(typeof args.name === "string" ? args.name : void 0, process.env["GIT_CONFIG_GLOBAL"]);
+			} catch (err) {
+				throw new CliValidationError(err instanceof Error ? err.message : String(err));
+			}
+			printGitHubToken(agentName, resolveDir(args.dir));
+		})
+	}) }
+});
+//#endregion
 //#region ../../libs/design-system/src/tokens.ts
 /**
 * MoltNet Design Tokens
@@ -572,7 +467,7 @@ var QUILL_LINES = [
 	"     ╲───────╲───────╲",
 	"                       ◆"
 ];
-var WORDMARK$1 = [
+var WORDMARK = [
 	" __  __  ___  _  _____  _  _ ___ _____",
 	"|  \\/  |/ _ \\| ||_   _|| \\| | __|_   _|",
 	"| |\\/| | (_) | |__| |  | .` | _|  | |  ",
@@ -619,7 +514,7 @@ function CliHero({ animated = false }) {
 					color: glowColor,
 					children: HALO_TOP
 				}),
-				WORDMARK$1.map((line, i) => /* @__PURE__ */ jsxs(Text, { children: [
+				WORDMARK.map((line, i) => /* @__PURE__ */ jsxs(Text, { children: [
 					/* @__PURE__ */ jsx(Text, {
 						color: glowColor,
 						children: "   ·  ·  │  "
@@ -680,7 +575,6 @@ function CliHero({ animated = false }) {
 		})
 	});
 }
-figlet.textSync("MOLTNET", { font: "slant" });
 //#endregion
 //#region ../../libs/design-system/src/cli/CliSpinner.tsx
 var FRAMES = [
@@ -8189,6 +8083,85 @@ async function writeEnvFile(opts) {
 	}
 	await writeFile(envPath, outputLines.join("\n") + "\n", "utf-8");
 }
+/**
+* Update a single managed key in an existing env file.
+* If the key exists, its value is replaced; otherwise appended.
+*/
+async function updateEnvVar(envDir, key, value) {
+	const envPath = join(envDir, "env");
+	let content;
+	try {
+		content = await readFile(envPath, "utf-8");
+	} catch {
+		content = "";
+	}
+	const line = `${key}=${q(value)}`;
+	const keyPrefix = `${key}=`;
+	const lines = content === "" ? [] : content.split("\n");
+	const index = lines.findIndex((l) => l.startsWith(keyPrefix));
+	if (index !== -1) {
+		lines[index] = line;
+		content = lines.join("\n");
+	} else content = content.endsWith("\n") ? content + line + "\n" : content + "\n" + line + "\n";
+	await writeFile(envPath, content, "utf-8");
+}
+/**
+* Resolve the human operator's git identity from global git config.
+* Must be called BEFORE GIT_CONFIG_GLOBAL is set (so it reads the
+* human's config, not the agent's).
+*
+* Returns `"Name <email>"` or `null` if either is missing.
+*/
+function resolveHumanGitIdentity() {
+	try {
+		const name = execFileSync("git", [
+			"config",
+			"--global",
+			"user.name"
+		], {
+			encoding: "utf-8",
+			env: {
+				...process.env,
+				GIT_CONFIG_GLOBAL: void 0
+			}
+		}).trim();
+		const email = execFileSync("git", [
+			"config",
+			"--global",
+			"user.email"
+		], {
+			encoding: "utf-8",
+			env: {
+				...process.env,
+				GIT_CONFIG_GLOBAL: void 0
+			}
+		}).trim();
+		return name && email ? `${name} <${email}>` : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Append MOLTNET_HUMAN_GIT_IDENTITY and optionally MOLTNET_COMMIT_AUTHORSHIP
+* to an existing env file if not already present.
+* Preserves existing content — only appends new vars.
+*/
+async function appendAuthorshipVars(envDir, humanGitIdentity, commitAuthorship) {
+	const envPath = join(envDir, "env");
+	let existing = "";
+	try {
+		existing = await readFile(envPath, "utf-8");
+	} catch {
+		return;
+	}
+	const lines = [];
+	const hasVar = (content, key) => new RegExp(`^${key}=`, "m").test(content);
+	if (humanGitIdentity && !hasVar(existing, "MOLTNET_HUMAN_GIT_IDENTITY")) lines.push(`MOLTNET_HUMAN_GIT_IDENTITY=${q(humanGitIdentity)}`);
+	if (commitAuthorship && !hasVar(existing, "MOLTNET_COMMIT_AUTHORSHIP")) lines.push(`MOLTNET_COMMIT_AUTHORSHIP=${q(commitAuthorship)}`);
+	if (lines.length === 0) return;
+	const suffix = lines.join("\n") + "\n";
+	await writeFile(envPath, existing.endsWith("\n") ? existing + suffix : existing + "\n" + suffix, "utf-8");
+}
 //#endregion
 //#region src/state.ts
 function getStatePath(configDir) {
@@ -8293,6 +8266,7 @@ async function runAgentSetupPhase(opts) {
 		pemPath,
 		installationId
 	});
+	await appendAuthorshipVars(configDir, opts.humanGitIdentity ?? resolveHumanGitIdentity(), opts.commitAuthorship);
 	await clearState(configDir);
 }
 //#endregion
@@ -8577,10 +8551,41 @@ async function writeTokenCache(cachePath, token, expiresAt) {
 	} catch {}
 }
 /**
-* Exchange a GitHub App JWT for an installation access token.
-* Uses a file-based cache next to the private key to avoid
-* hitting the GitHub API on every call.
+* List all installations of this GitHub App and return the one whose
+* `account.login` matches the given owner (case-insensitive).
+*
+* Uses the App JWT (not an installation token), so it works even when
+* `installation_id` is missing or stale.
 */
+async function findInstallationForOwner(opts) {
+	const privateKeyPem = await readFile(opts.privateKeyPath, "utf-8");
+	const jwt = createAppJWT(opts.appId, privateKeyPem);
+	const ownerLower = opts.owner.toLowerCase();
+	let nextUrl = "https://api.github.com/app/installations?per_page=100";
+	let pageCount = 0;
+	const MAX_PAGES = 10;
+	while (nextUrl && pageCount < MAX_PAGES) {
+		pageCount++;
+		const res = await fetch(nextUrl, { headers: {
+			Authorization: `Bearer ${jwt}`,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28"
+		} });
+		if (!res.ok) throw new Error(`GitHub API error listing installations (${res.status}): ${await res.text()}`);
+		const match = (await res.json()).find((i) => i.account?.login.toLowerCase() === ownerLower);
+		if (match) return { installationId: String(match.id) };
+		const linkHeader = res.headers.get("link");
+		nextUrl = linkHeader ? parseNextLinkHeader(linkHeader) : null;
+	}
+	return null;
+}
+function parseNextLinkHeader(header) {
+	for (const part of header.split(",")) {
+		const match = part.match(/<([^>]+)>\s*;\s*rel="next"/);
+		if (match) return match[1];
+	}
+	return null;
+}
 async function getInstallationToken(opts) {
 	const cachePath = join(dirname(opts.privateKeyPath), "gh-token-cache.json");
 	const cached = await readTokenCache(cachePath);
@@ -8851,9 +8856,6 @@ async function runInstallationPhase(opts) {
 	};
 }
 //#endregion
-//#region src/ui/types.ts
-var SUPPORTED_AGENTS = ["claude", "codex"];
-//#endregion
 //#region src/ui/AgentSelect.tsx
 var AGENTS = [
 	{
@@ -9093,12 +9095,26 @@ function ProgressPhase({ state, name, showManifestFallback, showInstallFallback
 				flexDirection: "column",
 				children: steps.githubApp === "running" ? /* @__PURE__ */ jsxs(Box, {
 					flexDirection: "column",
-					children: [/* @__PURE__ */ jsx(CliSpinner, { label: githubAppSpinnerLabel }), showManifestFallback && manifestFormUrl ? /* @__PURE__ */ jsxs(Text, {
-						color: cliTheme.color.muted,
-						children: ["  → ", /* @__PURE__ */ jsx(Text, {
-							color: cliTheme.color.accent,
-							children: manifestFormUrl
-						})]
+					children: [/* @__PURE__ */ jsx(CliSpinner, { label: githubAppSpinnerLabel }), manifestFormUrl ? /* @__PURE__ */ jsxs(Box, {
+						flexDirection: "column",
+						children: [
+							/* @__PURE__ */ jsxs(Text, {
+								color: cliTheme.color.text,
+								children: ["  ", "Confirm the GitHub App creation in your browser:"]
+							}),
+							/* @__PURE__ */ jsxs(Text, {
+								color: cliTheme.color.accent,
+								children: [
+									"  ",
+									"→ ",
+									manifestFormUrl
+								]
+							}),
+							showManifestFallback ? /* @__PURE__ */ jsxs(Text, {
+								color: cliTheme.color.muted,
+								children: ["  ", "Browser didn't open? Copy the link above."]
+							}) : null
+						]
 					}) : null]
 				}) : /* @__PURE__ */ jsx(CliStatusLine, {
 					label: "Create GitHub App",
@@ -9125,12 +9141,26 @@ function ProgressPhase({ state, name, showManifestFallback, showInstallFallback
 				children: [
 					steps.installation === "running" ? /* @__PURE__ */ jsxs(Box, {
 						flexDirection: "column",
-						children: [/* @__PURE__ */ jsx(CliSpinner, { label: installationSpinnerLabel }), showInstallFallback && installationUrl ? /* @__PURE__ */ jsxs(Text, {
-							color: cliTheme.color.muted,
-							children: ["  → ", /* @__PURE__ */ jsx(Text, {
-								color: cliTheme.color.accent,
-								children: installationUrl
-							})]
+						children: [/* @__PURE__ */ jsx(CliSpinner, { label: installationSpinnerLabel }), installationUrl ? /* @__PURE__ */ jsxs(Box, {
+							flexDirection: "column",
+							children: [
+								/* @__PURE__ */ jsxs(Text, {
+									color: cliTheme.color.text,
+									children: ["  ", "Install the GitHub App on your account/org:"]
+								}),
+								/* @__PURE__ */ jsxs(Text, {
+									color: cliTheme.color.accent,
+									children: [
+										"  ",
+										"→ ",
+										installationUrl
+									]
+								}),
+								showInstallFallback ? /* @__PURE__ */ jsxs(Text, {
+									color: cliTheme.color.muted,
+									children: ["  ", "Browser didn't open? Copy the link above."]
+								}) : null
+							]
 						}) : null]
 					}) : /* @__PURE__ */ jsx(CliStatusLine, {
 						label: "GitHub App installation",
@@ -9288,6 +9318,43 @@ function InitApp({ name, agents: agentsProp, apiUrl, dir = process.cwd(), org })
 	});
 }
 //#endregion
+//#region src/commands/init.tsx
+var initCommand = defineCommand({
+	meta: {
+		name: "init",
+		description: "Create a new agent identity and wire it into this repository"
+	},
+	args: {
+		name: {
+			...commonArgs.name,
+			required: true
+		},
+		agent: commonArgs.agent,
+		"api-url": commonArgs["api-url"],
+		dir: commonArgs.dir,
+		org: {
+			type: "string",
+			description: "GitHub organization to install the App on (optional)",
+			alias: "o",
+			valueHint: "github-org"
+		}
+	},
+	run: withCleanErrors(({ args, rawArgs }) => {
+		const name = requireAgentName(args.name);
+		const agents = collectAgents(rawArgs);
+		const apiUrl = resolveApiUrl(args["api-url"]);
+		const dir = resolveDir(args.dir);
+		const org = typeof args.org === "string" ? args.org : void 0;
+		render(/* @__PURE__ */ jsx(InitApp, {
+			name,
+			agents: agents.length > 0 ? agents : void 0,
+			apiUrl,
+			dir,
+			org
+		}));
+	})
+});
+//#endregion
 //#region src/phases/portArgs.ts
 /**
 * Validate the raw `--from` argument passed to `legreffier port` before
@@ -9540,6 +9607,62 @@ async function runPortDiaryPhase(opts) {
 	};
 }
 //#endregion
+//#region src/phases/portResolveInstallation.ts
+/**
+* Resolve the correct `installation_id` for the target owner.
+*
+* When porting a config across orgs the source `installation_id` is scoped
+* to the original account. This phase uses the App JWT to list all
+* installations and find the one matching the target owner, then updates
+* `moltnet.json` if it differs.
+*/
+async function runPortResolveInstallationPhase(opts) {
+	const { targetDir, config, currentRepo } = opts;
+	if (!currentRepo) return {
+		status: "skipped",
+		message: "unable to determine target repo — skipping installation_id resolution",
+		installationId: config.github?.installation_id ?? ""
+	};
+	if (!config.github?.app_id || !config.github?.private_key_path) return {
+		status: "skipped",
+		message: "github.app_id or private_key_path missing — cannot resolve",
+		installationId: config.github?.installation_id ?? ""
+	};
+	const targetOwner = currentRepo.split("/")[0];
+	let result;
+	try {
+		result = await findInstallationForOwner({
+			appId: config.github.app_id,
+			privateKeyPath: config.github.private_key_path,
+			owner: targetOwner
+		});
+	} catch (err) {
+		return {
+			status: "skipped",
+			message: `could not list app installations: ${err.message}`,
+			installationId: config.github?.installation_id ?? ""
+		};
+	}
+	if (!result) return {
+		status: "not-installed",
+		message: `GitHub App is not installed on ${targetOwner} — install it first`,
+		installationId: config.github?.installation_id ?? ""
+	};
+	const oldId = config.github.installation_id;
+	if (oldId === result.installationId) return {
+		status: "unchanged",
+		message: `installation_id ${oldId} already matches ${targetOwner}`,
+		installationId: oldId
+	};
+	await updateConfigSection("github", { installation_id: result.installationId }, targetDir);
+	if (opts.envPrefix) await updateEnvVar(targetDir, `${opts.envPrefix}_GITHUB_APP_INSTALLATION_ID`, result.installationId);
+	return {
+		status: "updated",
+		message: `installation_id updated: ${oldId || "(empty)"} → ${result.installationId} (${targetOwner})`,
+		installationId: result.installationId
+	};
+}
+//#endregion
 //#region src/phases/portRewrite.ts
 /**
 * Rewrite absolute paths in the ported `moltnet.json` so they point to
@@ -9602,6 +9725,7 @@ async function runPortRewritePhase(opts) {
 		pemPath: newPem,
 		installationId: config.github.installation_id
 	});
+	await appendAuthorshipVars(targetDir, resolveHumanGitIdentity());
 	return {
 		configPath: join(targetDir, "moltnet.json"),
 		rewrittenFields,
@@ -9762,6 +9886,16 @@ function PortApp({ name, agents, sourceDir, targetRepoDir, diaryMode, apiUrl })
 				});
 				filesWritten.push(rewriteResult.gitConfigPath);
 				filesWritten.push(join(targetDir, "env"));
+				setPhase("resolving_installation");
+				const currentRepo = detectCurrentRepo(targetRepoDir);
+				const prefix = toEnvPrefix(name);
+				const resolveResult = await runPortResolveInstallationPhase({
+					targetDir,
+					config: await readConfig(targetDir) ?? config,
+					currentRepo: currentRepo ?? void 0,
+					envPrefix: prefix
+				});
+				if (resolveResult.status === "not-installed" || resolveResult.status === "skipped") warnings.push(resolveResult.message);
 				setPhase("diary");
 				const diaryResult = await runPortDiaryPhase({
 					targetDir,
@@ -9772,14 +9906,14 @@ function PortApp({ name, agents, sourceDir, targetRepoDir, diaryMode, apiUrl })
 				const adapterOpts = {
 					repoDir: targetRepoDir,
 					agentName: name,
-					prefix: toEnvPrefix(name),
+					prefix,
 					mcpUrl: config.endpoints?.mcp ?? apiUrl.replace("://api.", "://mcp.") + "/mcp",
 					clientId: config.oauth2.client_id,
 					clientSecret: config.oauth2.client_secret,
 					appSlug: config.github?.app_slug ?? "",
 					appId: config.github?.app_id ?? "",
 					pemPath: join(targetDir, basename(config.github?.private_key_path ?? "")),
-					installationId: config.github?.installation_id ?? ""
+					installationId: resolveResult.installationId
 				};
 				for (const agentType of agents) {
 					const adapter = adapters[agentType];
@@ -9795,7 +9929,7 @@ function PortApp({ name, agents, sourceDir, targetRepoDir, diaryMode, apiUrl })
 				setPhase("verifying");
 				const verifyResult = await runPortVerifyInstallationPhase({
 					config: await readConfig(targetDir) ?? config,
-					currentRepo: detectCurrentRepo(targetRepoDir) ?? void 0
+					currentRepo: currentRepo ?? void 0
 				});
 				if (verifyResult.status !== "ok") warnings.push(verifyResult.message);
 				setSummary({
@@ -9837,6 +9971,7 @@ function PortApp({ name, agents, sourceDir, targetRepoDir, diaryMode, apiUrl })
 			validating: `Validating source .moltnet/${name}...`,
 			copying: `Copying private material...`,
 			rewriting: `Rewriting paths in moltnet.json...`,
+			resolving_installation: `Resolving GitHub App installation for target org...`,
 			diary: `Configuring diary (${diaryMode})...`,
 			agent_setup: `Installing agent files for ${agents.join(", ")}...`,
 			verifying: `Verifying GitHub App installation scope...`
@@ -9894,6 +10029,68 @@ function PortApp({ name, agents, sourceDir, targetRepoDir, diaryMode, apiUrl })
 	});
 }
 //#endregion
+//#region src/commands/port.tsx
+var DIARY_MODES = [
+	"new",
+	"reuse",
+	"skip"
+];
+function assertDirectory(label, path) {
+	try {
+		if (!statSync(path).isDirectory()) throw new CliValidationError(`${label} "${path}" is not a directory`);
+	} catch (err) {
+		if (err instanceof CliValidationError) throw err;
+		throw new CliValidationError(`${label} "${path}" does not exist`);
+	}
+}
+var portCommand = defineCommand({
+	meta: {
+		name: "port",
+		description: "Copy an existing agent from another repository into this one"
+	},
+	args: {
+		name: {
+			...commonArgs.name,
+			required: true
+		},
+		from: {
+			type: "string",
+			description: "Absolute path to the source agent directory (must be `<repo-root>/.moltnet/<agent-name>` and contain moltnet.json + gitconfig)",
+			required: true,
+			valueHint: "repo-root/.moltnet/agent-name"
+		},
+		agent: commonArgs.agent,
+		"api-url": commonArgs["api-url"],
+		dir: commonArgs.dir,
+		diary: {
+			type: "enum",
+			description: "How to handle the diary in the new repo: `new` creates a fresh diary, `reuse` reuses the source diary ID, `skip` leaves MOLTNET_DIARY_ID unset",
+			options: [...DIARY_MODES],
+			default: "new",
+			valueHint: "new|reuse|skip"
+		}
+	},
+	run: withCleanErrors(({ args, rawArgs }) => {
+		const name = requireAgentName(args.name);
+		const agents = collectAgents(rawArgs);
+		const apiUrl = resolveApiUrl(args["api-url"]);
+		const dir = resolveDir(args.dir);
+		const fromValidation = validatePortFromArg(args.from);
+		if (!fromValidation.ok) throw new CliValidationError(fromValidation.error);
+		const absoluteFromDir = args.from;
+		assertDirectory("--dir", dir);
+		assertDirectory("--from", absoluteFromDir);
+		render(/* @__PURE__ */ jsx(PortApp, {
+			name,
+			agents: agents.length > 0 ? agents : ["claude"],
+			sourceDir: absoluteFromDir,
+			targetRepoDir: dir,
+			diaryMode: args.diary,
+			apiUrl
+		}));
+	})
+});
+//#endregion
 //#region src/SetupApp.tsx
 function SetupApp({ name, agents: agentsProp, apiUrl, dir }) {
 	const { exit } = useApp();
@@ -10009,131 +10206,39 @@ function SetupApp({ name, agents: agentsProp, apiUrl, dir }) {
 }
 //#endregion
 //#region src/index.tsx
-var rawArgs = process.argv.slice(2);
-if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-	const help = resolveHelpCommand(rawArgs, COMMANDS);
-	if (help) printCommandHelp(help);
-	else printRootHelp(COMMANDS);
-	process.exit(0);
-}
-if (rawArgs.length === 0) {
-	printRootHelp(COMMANDS);
-	process.exit(0);
-}
-var { values, positionals } = parseArgs({
-	args: rawArgs,
-	allowPositionals: true,
-	options: {
-		name: {
-			type: "string",
-			short: "n"
-		},
-		agent: {
-			type: "string",
-			short: "a",
-			multiple: true
-		},
-		"api-url": { type: "string" },
-		dir: { type: "string" },
-		org: {
-			type: "string",
-			short: "o"
-		},
-		from: { type: "string" },
-		diary: { type: "string" }
+runMain(defineCommand({
+	meta: {
+		name: "legreffier",
+		description: "LeGreffier — attribution and measured memory for AI coding agents"
+	},
+	subCommands: {
+		init: initCommand,
+		setup: defineCommand({
+			meta: {
+				name: "setup",
+				description: "Install LeGreffier skills and MCP config into an existing repo"
+			},
+			args: {
+				name: {
+					...commonArgs.name,
+					required: true
+				},
+				agent: commonArgs.agent,
+				"api-url": commonArgs["api-url"],
+				dir: commonArgs.dir
+			},
+			run: withCleanErrors(({ args, rawArgs }) => {
+				render(/* @__PURE__ */ jsx(SetupApp, {
+					name: requireAgentName(args.name),
+					agents: collectAgents(rawArgs),
+					apiUrl: resolveApiUrl(args["api-url"]),
+					dir: resolveDir(args.dir)
+				}));
+			})
+		}),
+		port: portCommand,
+		github: githubCommand
 	}
-});
-var subcommand = positionals[0] ?? "init";
-var name = values["name"];
-var agentFlags = values["agent"] ?? [];
-var apiUrl = values["api-url"] ?? process.env.MOLTNET_API_URL ?? "https://api.themolt.net";
-var dir = values["dir"] ?? process.cwd();
-var org = values["org"];
-var fromDir = values["from"];
-var diaryModeArg = values["diary"];
-if (diaryModeArg !== void 0 && subcommand !== "port") {
-	process.stderr.write(`Error: --diary is only valid for \`legreffier port\` (got subcommand "${subcommand}")\n`);
-	process.exit(1);
-}
-if (subcommand === "github" && positionals[1] === "token") try {
-	printGitHubToken(resolveAgentName(name, process.env.GIT_CONFIG_GLOBAL), dir);
-	process.exit(0);
-} catch (err) {
-	process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
-	process.exit(1);
-}
-if (!name) {
-	const help = COMMANDS.find((c) => c.command === subcommand);
-	process.stderr.write(`Error: --name is required.\n\nRun \`legreffier ${help ? help.command : "<command>"} --help\` for details.\n`);
-	process.exit(1);
-}
-if (!/^[a-z0-9][a-z0-9-]{0,37}[a-z0-9]$/.test(name)) {
-	process.stderr.write(`Invalid agent name: "${name}". Must be 2-39 lowercase alphanumeric characters or hyphens, starting and ending with a letter or digit.\n`);
-	process.exit(1);
-}
-for (const a of agentFlags) if (!SUPPORTED_AGENTS.includes(a)) {
-	process.stderr.write(`Unsupported agent: ${a}. Supported: ${SUPPORTED_AGENTS.join(", ")}\n`);
-	process.exit(1);
-}
-var agents = agentFlags;
-if (subcommand === "setup") render(/* @__PURE__ */ jsx(SetupApp, {
-	name,
-	agents,
-	apiUrl,
-	dir
-}));
-else if (subcommand === "init") render(/* @__PURE__ */ jsx(InitApp, {
-	name,
-	agents: agents.length > 0 ? agents : void 0,
-	apiUrl,
-	dir,
-	org
 }));
-else if (subcommand === "port") {
-	const fromValidation = validatePortFromArg(fromDir);
-	if (!fromValidation.ok) {
-		process.stderr.write(`Error: ${fromValidation.error}\n`);
-		process.exit(1);
-	}
-	const absoluteFromDir = fromDir;
-	const resolvedDiaryMode = diaryModeArg ?? "new";
-	if (![
-		"new",
-		"reuse",
-		"skip"
-	].includes(resolvedDiaryMode)) {
-		process.stderr.write(`Error: --diary must be one of: new, reuse, skip (got "${resolvedDiaryMode}")\n`);
-		process.exit(1);
-	}
-	try {
-		if (!statSync(dir).isDirectory()) {
-			process.stderr.write(`Error: --dir "${dir}" is not a directory\n`);
-			process.exit(1);
-		}
-	} catch {
-		process.stderr.write(`Error: --dir "${dir}" does not exist\n`);
-		process.exit(1);
-	}
-	try {
-		if (!statSync(absoluteFromDir).isDirectory()) {
-			process.stderr.write(`Error: --from "${absoluteFromDir}" is not a directory\n`);
-			process.exit(1);
-		}
-	} catch {
-		process.stderr.write(`Error: --from "${absoluteFromDir}" does not exist\n`);
-		process.exit(1);
-	}
-	render(/* @__PURE__ */ jsx(PortApp, {
-		name,
-		agents: agents.length > 0 ? agents : ["claude"],
-		sourceDir: absoluteFromDir,
-		targetRepoDir: dir,
-		diaryMode: resolvedDiaryMode,
-		apiUrl
-	}));
-} else {
-	process.stderr.write(`Unknown subcommand: ${subcommand}. Use "init", "setup", or "port".\n`);
-	process.exit(1);
-}
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/legreffier",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "description": "LeGreffier — attribution and measured memory for AI coding agents.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -20,24 +20,23 @@
     "node": ">=22"
   },
   "dependencies": {
-    "figlet": "^1.8.0",
+    "citty": "^0.2.2",
     "ink": "^6.8.0",
     "open": "^10.1.2",
     "react": "^19.0.0",
     "smol-toml": "^1.6.1"
   },
   "devDependencies": {
-    "@types/figlet": "^1.7.0",
     "@types/node": "^20.11.0",
     "@types/react": "^19.0.0",
     "typescript": "^5.3.3",
     "vite": "^8.0.0",
     "vitest": "^3.0.0",
     "@moltnet/api-client": "0.1.0",
-    "@themoltnet/design-system": "0.4.0",
-    "@themoltnet/github-agent": "0.23.0",
-    "@themoltnet/sdk": "0.89.0",
-    "@moltnet/crypto-service": "0.1.0"
+    "@moltnet/crypto-service": "0.1.0",
+    "@themoltnet/design-system": "0.5.1",
+    "@themoltnet/github-agent": "0.23.1",
+    "@themoltnet/sdk": "0.89.0"
   },
   "scripts": {
     "dev": "vite build --watch",