@themoltnet/legreffier 0.30.0 → 0.31.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { statSync } from "node:fs";
 import { parseArgs, parseEnv } from "node:util";
 import { Box, Text, render, useApp, useInput } from "ink";
 import { execFileSync, execSync } from "node:child_process";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { useEffect, useReducer, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import figlet from "figlet";
@@ -13,6 +13,251 @@ import { access, chmod, copyFile, mkdir, readFile, rm, writeFile } from "node:fs
 import { homedir } from "node:os";
 import { parse, stringify } from "smol-toml";
 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
 //#region src/github-token.ts
 var MOLTNET_GITCONFIG_RE = /\.moltnet\/([^/]+)\/gitconfig$/;
 function resolveAgentName(nameFlag, gitConfigGlobal) {
@@ -7514,7 +7759,7 @@ var SKILLS = [
 	},
 	{
 		name: "legreffier-onboarding",
-		files: ["SKILL.md", "references/onboarding-guide.md"]
+		files: ["SKILL.md"]
 	}
 ];
 async function downloadSkillFiles(skill) {
@@ -9043,6 +9288,38 @@ function InitApp({ name, agents: agentsProp, apiUrl, dir = process.cwd(), org })
 	});
 }
 //#endregion
+//#region src/phases/portArgs.ts
+/**
+* Validate the raw `--from` argument passed to `legreffier port` before
+* any filesystem access.
+*
+* `--from` must be:
+*  - non-empty
+*  - an absolute path (no `~`, no relative paths, no bare repo names)
+*
+* The help text for `port` documents this as a hard requirement because
+* the port pipeline rewrites paths embedded in `moltnet.json` and
+* `gitconfig`, and those rewrites only round-trip correctly when the
+* source is an absolute path. Accepting a relative path here silently
+* produces broken output in git worktrees (different CWD than the main
+* worktree root), so we fail fast instead of letting the port run.
+*/
+function validatePortFromArg(fromDir) {
+	if (typeof fromDir !== "string" || fromDir.length === 0) return {
+		ok: false,
+		error: "legreffier port requires --from <repo-root>/.moltnet/<agent>"
+	};
+	if (fromDir.startsWith("~")) return {
+		ok: false,
+		error: `--from "${fromDir}" uses "~" which is not expanded. Pass an absolute path (e.g. "\$HOME/code/other-repo/.moltnet/<agent>").`
+	};
+	if (!isAbsolute(fromDir)) return {
+		ok: false,
+		error: `--from "${fromDir}" must be an absolute path (e.g. /Users/me/code/other-repo/.moltnet/<agent>). Relative paths break inside git worktrees where the CWD differs from the main worktree root.`
+	};
+	return { ok: true };
+}
+//#endregion
 //#region src/phases/portValidate.ts
 /**
 * Validate a source `.moltnet/<agent>/` directory for porting.
@@ -9732,8 +10009,19 @@ 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: process.argv.slice(2),
+	args: rawArgs,
 	allowPositionals: true,
 	options: {
 		name: {
@@ -9775,8 +10063,8 @@ if (subcommand === "github" && positionals[1] === "token") try {
 	process.exit(1);
 }
 if (!name) {
-	const usage = subcommand === "setup" ? "Usage: legreffier setup --name <agent-name> [--agent claude] [--agent codex] [--dir <path>]" : subcommand === "port" ? "Usage: legreffier port --name <agent-name> --from <path/to/source/.moltnet/<agent>> [--agent claude] [--agent codex] [--dir <target-repo>] [--diary new|reuse|skip]" : "Usage: legreffier [init] --name <agent-name> [--agent claude] [--agent codex] [--api-url <url>] [--dir <path>] [--org <github-org>]";
-	process.stderr.write(usage + "\n");
+	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)) {
@@ -9802,10 +10090,12 @@ else if (subcommand === "init") render(/* @__PURE__ */ jsx(InitApp, {
 	org
 }));
 else if (subcommand === "port") {
-	if (!fromDir) {
-		process.stderr.write("Error: legreffier port requires --from <path/to/source/.moltnet/<agent>>\n");
+	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",
@@ -9825,18 +10115,18 @@ else if (subcommand === "port") {
 		process.exit(1);
 	}
 	try {
-		if (!statSync(fromDir).isDirectory()) {
-			process.stderr.write(`Error: --from "${fromDir}" is not a directory\n`);
+		if (!statSync(absoluteFromDir).isDirectory()) {
+			process.stderr.write(`Error: --from "${absoluteFromDir}" is not a directory\n`);
 			process.exit(1);
 		}
 	} catch {
-		process.stderr.write(`Error: --from "${fromDir}" does not exist\n`);
+		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: fromDir,
+		sourceDir: absoluteFromDir,
 		targetRepoDir: dir,
 		diaryMode: resolvedDiaryMode,
 		apiUrl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/legreffier",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "LeGreffier — attribution and measured memory for AI coding agents.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -34,10 +34,10 @@
     "vite": "^8.0.0",
     "vitest": "^3.0.0",
     "@moltnet/api-client": "0.1.0",
-    "@moltnet/crypto-service": "0.1.0",
     "@themoltnet/design-system": "0.4.0",
+    "@themoltnet/github-agent": "0.23.0",
     "@themoltnet/sdk": "0.89.0",
-    "@themoltnet/github-agent": "0.23.0"
+    "@moltnet/crypto-service": "0.1.0"
   },
   "scripts": {
     "dev": "vite build --watch",