@dyyz1993/create-agent 2.1.1 → 2.1.3

package/src/cli.ts

@@ -1,19 +1,21 @@
 #!/usr/bin/env bun
 
-import { runCreate } from './commands/create.js';
-import { runList } from './commands/list.js';
-import { runStatus } from './commands/status.js';
-import { runWorkspace } from './commands/workspace.js';
+import { runCreate } from "./commands/create.js";
+import { runList } from "./commands/list.js";
+import { runStatus } from "./commands/status.js";
+import { runWorkspace } from "./commands/workspace.js";
+import { runUpdate } from "./commands/update.js";
 
 const COMMANDS = new Map<string, (args: string[]) => Promise<void>>([
-  ['create', runCreate],
-  ['list', runList],
-  ['status', runStatus],
-  ['workspace', runWorkspace],
+	["create", runCreate],
+	["list", runList],
+	["status", runStatus],
+	["workspace", runWorkspace],
+	["update", runUpdate],
 ]);
 
 function printHelp(): void {
-  console.log(`
+	console.log(`
 Create Agent CLI — project scaffolding tool
 
 Usage:
@@ -24,7 +26,7 @@ Commands:
   list           Show available template types
   status         Show active pi-agent instances
   workspace add <name>  Create isolated workspace for parallel development
-  update         Update project to latest template (coming soon)
+  update         Update project to latest template version
 
 Options:
   -h, --help     Show this help message
@@ -34,32 +36,28 @@ Run "create-agent create --help" for create-specific options.
 }
 
 async function main(): Promise<void> {
-  const args = process.argv.slice(2);
+	const args = process.argv.slice(2);
 
-  const command = args[0];
-  const rest = args.slice(1);
+	const command = args[0];
+	const rest = args.slice(1);
 
-  if (!command || command === '-h' || command === '--help') {
-    printHelp();
-    process.exit(0);
-  }
+	if (!command || command === "-h" || command === "--help") {
+		printHelp();
+		process.exit(0);
+	}
 
-  if (command === 'update') {
-    console.log('Update feature coming soon');
-    return;
-  }
+	const handler = COMMANDS.get(command);
+	if (!handler) {
+		console.error(`Unknown command: "${command}"\n`);
+		printHelp();
+		process.exit(1);
+	}
 
-  const handler = COMMANDS.get(command);
-  if (!handler) {
-    console.error(`Unknown command: "${command}"\n`);
-    printHelp();
-    process.exit(1);
-  }
-
-  await handler(rest);
+	await handler(rest);
 }
 
-main().catch((err) => {
-  console.error(`Error: ${err.message}`);
-  process.exit(1);
+main().catch((err: unknown) => {
+	const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+	console.error(`Error: ${message}`);
+	process.exit(1);
 });

package/src/commands/create.ts

@@ -1,27 +1,8 @@
 import { resolve } from "path";
 import { resolveTemplateDir, getRootDir } from "../lib/templates.js";
-import { copyTemplate } from "../lib/copy.js";
+import { copyTemplate, expandTilde } from "../lib/copy.js";
 
-export async function runCreate(args: string[]): Promise<void> {
-	let templateType = "general";
-	let customDir: string | undefined;
-
-	const positional: string[] = [];
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i]!;
-		if (arg === "--type" && args[i + 1]) {
-			templateType = args[++i]!;
-		} else if (arg === "--dir" && args[i + 1]) {
-			customDir = args[++i]!;
-		} else if (!arg.startsWith("--")) {
-			positional.push(arg);
-		}
-	}
-
-	const projectName = positional[0];
-	const targetArg = customDir || positional[1];
-	if (!projectName) {
-		console.log(`
+const HELP = `
 Usage: create-agent create <name> [--type <type>] [--dir <path>]
 
 Options:
@@ -32,12 +13,90 @@ Examples:
   create-agent create my-app
   create-agent create my-app --type chat
   create-agent create my-app --dir ~/projects/my-app
-`);
+`;
+
+function fail(message: string): never {
+	console.error(message);
+	process.exit(1);
+}
+
+interface ParsedArgs {
+	positional: string[];
+	options: { type?: string; dir?: string };
+	error?: string;
+}
+
+/** Pure arg parser (no process.exit) so it can be unit tested. */
+export function parseArgs(args: string[]): ParsedArgs {
+	const positional: string[] = [];
+	const options: { type?: string; dir?: string } = {};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--") {
+			positional.push(...args.slice(i + 1));
+			break;
+		}
+		if (arg === "-h" || arg === "--help") continue;
+		if (arg.startsWith("--")) {
+			const eq = arg.indexOf("=");
+			const key = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+			let value = eq === -1 ? undefined : arg.slice(eq + 1);
+
+			if (key !== "type" && key !== "dir") {
+				return { positional, options, error: `Unknown option: ${arg}\n${HELP}` };
+			}
+			if (value === undefined) {
+				const next = args[i + 1];
+				if (!next || next.startsWith("--")) {
+					return {
+						positional,
+						options,
+						error: `Option --${key} requires a value.\n${HELP}`,
+					};
+				}
+				value = next;
+				i++;
+			}
+			if (key === "type") options.type = value;
+			else options.dir = value;
+		} else {
+			positional.push(arg);
+		}
+	}
+
+	return { positional, options };
+}
+
+export async function runCreate(args: string[]): Promise<void> {
+	if (args.includes("-h") || args.includes("--help")) {
+		console.log(HELP);
+		process.exit(0);
+	}
+
+	const { positional, options, error } = parseArgs(args);
+	if (error) fail(error);
+	const templateType = options.type ?? "general";
+	const customDir = options.dir;
+
+	const projectNameArg = positional[0];
+	const targetArg = customDir || positional[1];
+	if (!projectNameArg) {
+		console.log(HELP);
 		process.exit(1);
 	}
 
-	const sanitized = projectName.replace(/[^a-zA-Z0-9-_]/g, "-");
-	const targetDir = targetArg ? resolve(targetArg) : resolve(process.cwd(), sanitized);
+	const sanitized = projectNameArg.replace(/[^a-zA-Z0-9-_]/g, "-");
+	// Reject names that sanitize into garbage (e.g. Chinese input -> "----")
+	// instead of silently creating unusable package names / bundle ids.
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(sanitized)) {
+		fail(
+			`Invalid project name: "${projectNameArg}"\n` +
+				"Use a name starting with a letter or digit, containing only letters, digits, '-', '_' (e.g. my-app)."
+		);
+	}
+
+	const targetDir = targetArg ? resolve(expandTilde(targetArg)) : resolve(process.cwd(), sanitized);
 	const rootDir = getRootDir();
 	const templateDir = resolveTemplateDir(rootDir, templateType);
 

package/src/commands/update.ts

@@ -0,0 +1,174 @@
+import { resolve } from "path";
+import { existsSync, readFileSync, readdirSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { spawnSync } from "child_process";
+import { getRootDir, resolveTemplateDir } from "../lib/templates.js";
+import { copyAndReplace, postProcessTemplate, expandTilde } from "../lib/copy.js";
+
+interface TemplateMeta {
+	templateType: string;
+	projectName: string;
+}
+
+/** Detect which template a project was created from (exported for tests). */
+export function detectTemplateMeta(targetDir: string): TemplateMeta | null {
+	const pkgPath = resolve(targetDir, "package.json");
+	if (!existsSync(pkgPath)) return null;
+
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		const projectName = pkg.name || null;
+		if (!projectName) return null;
+
+		const sharedDir = resolve(targetDir, "src", "shared");
+		const modulesDir = existsSync(sharedDir) ? resolve(sharedDir, "modules") : null;
+		if (!modulesDir || !existsSync(modulesDir)) return null;
+
+		const modules = new Set(readdirSync(modulesDir).filter((f) => !f.startsWith(".")));
+
+		if (modules.has("bash") && modules.has("todo") && modules.has("rules")) {
+			return { templateType: "agent", projectName };
+		}
+		if (modules.has("browser")) {
+			return { templateType: "browser-agent", projectName };
+		}
+		if (modules.has("task") && modules.has("context") && modules.has("output")) {
+			return { templateType: "cowork", projectName };
+		}
+		if (modules.has("chat") && !modules.has("file") && !modules.has("git")) {
+			return { templateType: "chat", projectName };
+		}
+		return { templateType: "general", projectName };
+	} catch {
+		return null;
+	}
+}
+
+const DIFF_EXCLUDES = [
+	"node_modules",
+	"dist",
+	"build",
+	".git",
+	".husky",
+	".server-port",
+	"logs",
+	"bun.lock",
+	"pnpm-lock.yaml",
+].flatMap((e) => [`--exclude=${e}`]);
+
+function diffTemplateAgainstProject(
+	templateDir: string,
+	targetDir: string,
+	projectName: string
+): string {
+	// Render the template into a temp dir first so the diff compares what
+	// update --force would actually write, not the raw placeholders.
+	const tmpDir = mkdtempSync(resolve(tmpdir(), "create-agent-update-"));
+	try {
+		copyAndReplace(templateDir, tmpDir, projectName);
+		const result = spawnSync("diff", ["-rq", ...DIFF_EXCLUDES, `${tmpDir}/`, `${targetDir}/`], {
+			encoding: "utf-8",
+			maxBuffer: 10 * 1024 * 1024,
+		});
+		if (result.error) {
+			return `(diff unavailable: ${result.error.message})`;
+		}
+		if (result.status === 2) {
+			return `(diff failed: ${result.stderr.trim()})`;
+		}
+		return result.stdout.replaceAll(`${tmpDir}/`, "<template>/");
+	} finally {
+		rmSync(tmpDir, { recursive: true, force: true });
+	}
+}
+
+export async function runUpdate(args: string[]): Promise<void> {
+	let targetDir = process.cwd();
+	let force = false;
+	let dryRun = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--dir" && args[i + 1]) {
+			targetDir = resolve(expandTilde(args[++i]!));
+		} else if (arg === "--force") {
+			force = true;
+		} else if (arg === "--dry-run") {
+			dryRun = true;
+		} else if (arg === "--help" || arg === "-h") {
+			console.log(`
+Usage: create-agent update [options]
+
+Update project to latest template version.
+
+Options:
+  --dir <path>    Target project directory (default: current directory)
+  --force         Overwrite ALL template files (including src/shared/, modules/, lib/)
+  --dry-run       Show what would change without modifying files
+  -h, --help      Show this help message
+
+Examples:
+  create-agent update
+  create-agent update --dir ~/projects/my-app
+  create-agent update --dry-run
+  create-agent update --force
+`);
+			process.exit(0);
+		}
+	}
+
+	if (!existsSync(targetDir)) {
+		console.error(`Directory does not exist: ${targetDir}`);
+		process.exit(1);
+	}
+
+	const meta = detectTemplateMeta(targetDir);
+	if (!meta) {
+		console.error(
+			"Cannot detect template type. Make sure you're in a pi-agent-template project directory."
+		);
+		process.exit(1);
+	}
+
+	const { templateType, projectName } = meta;
+	console.log(`Detected template: ${templateType}`);
+	console.log(`Project name: ${projectName}`);
+	console.log("");
+
+	const rootDir = getRootDir();
+	const templateDir = resolveTemplateDir(rootDir, templateType);
+
+	if (dryRun) {
+		console.log("Dry run - showing changes:");
+		console.log("");
+		const diffResult = diffTemplateAgainstProject(templateDir, targetDir, projectName);
+		if (!diffResult.trim()) {
+			console.log("No changes detected. Project is up to date!");
+		} else {
+			console.log(diffResult);
+		}
+		return;
+	}
+
+	if (!force) {
+		console.log("This command requires --force to run.");
+		console.log("");
+		console.log("NOTE: --force overwrites ALL template files, including your edits in");
+		console.log("src/shared/handlers/, src/shared/modules/, src/shared/lib/. Commit or");
+		console.log("stash your work first, then review the result with: git diff");
+		console.log("");
+		console.log("Use --dry-run to preview changes before forcing.");
+		return;
+	}
+
+	copyAndReplace(templateDir, targetDir, projectName);
+	postProcessTemplate(targetDir, projectName);
+
+	console.log("");
+	console.log("Template files updated successfully!");
+	console.log("");
+	console.log("Next steps:");
+	console.log("  1. Review the changes with: git diff");
+	console.log("  2. Run: bun install");
+	console.log("  3. Test: bun run dev:web");
+}

package/src/commands/workspace.ts

@@ -1,10 +1,26 @@
 import { resolve } from "path";
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import { existsSync, readFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
 import { createServer } from "net";
 import type { PortEntry } from "../lib/types.js";
 
-const PORT_REGISTRY = resolve(process.env.HOME || "~", ".pi-agent", "ports.json");
+const PORT_REGISTRY = resolve(homedir(), ".pi-agent", "ports.json");
+
+const WORKSPACE_NAME_RE = /^[\w][\w.-]*$/;
+
+/** Returns an error message for invalid names, or null when valid. */
+export function validateWorkspaceName(name: string): string | null {
+	// The name becomes both a directory and a git branch; anything outside
+	// word characters, dots and dashes is rejected rather than escaped.
+	if (!WORKSPACE_NAME_RE.test(name)) {
+		return (
+			`Invalid workspace name "${name}". ` +
+			"Use letters, digits, '.', '_' or '-' (e.g. feature-chat-ui)."
+		);
+	}
+	return null;
+}
 
 function readRegistry(): Record<string, PortEntry> {
 	try {
@@ -83,6 +99,12 @@ Examples:
 		process.exit(1);
 	}
 
+	const nameError = validateWorkspaceName(name);
+	if (nameError) {
+		console.error(`Error: ${nameError}`);
+		process.exit(1);
+	}
+
 	const projectRoot = process.cwd();
 	const workspaceDir = resolve(projectRoot, ".workspace", name);
 
@@ -101,7 +123,7 @@ Examples:
 	mkdirSync(resolve(projectRoot, ".workspace"), { recursive: true });
 
 	try {
-		execSync(`git worktree add "${workspaceDir}" -b ${branchName} ${baseArg}`, {
+		execFileSync("git", ["worktree", "add", workspaceDir, "-b", branchName, baseArg], {
 			cwd: projectRoot,
 			stdio: "pipe",
 		});
@@ -119,7 +141,7 @@ Examples:
 	console.log("");
 	console.log("Installing dependencies...");
 	try {
-		execSync("bun install", { cwd: workspaceDir, stdio: "pipe" });
+		execFileSync("bun", ["install"], { cwd: workspaceDir, stdio: "pipe" });
 	} catch {
 		console.log("(bun install skipped)");
 	}
@@ -131,6 +153,4 @@ Examples:
 	console.log(`  cd .workspace/${name}`);
 	console.log(`  PORT=${ports.backend} VITE_PORT=${ports.vite} bun run dev:web`);
 	console.log("");
-	console.log("Or start from project root:");
-	console.log(`  PORT=${ports.backend} VITE_PORT=${ports.vite} bun run dev:web`);
 }