@percepta/create 3.4.3 → 3.5.1

package/README.md

@@ -26,6 +26,7 @@ The bare command above is the canonical UX. The flags below exist for tests and
 ## Subcommands
 
 - `create` (default) — scaffold a new Mosaic package
+- `add` — add a webapp or library to the current monorepo
 - `status` — show template sync status for the current app
 - `sync` — generate downstream sync context (template → app)
 - `upstream` — generate upstream context (app → template)
@@ -38,6 +39,18 @@ The bare command above is the canonical UX. The flags below exist for tests and
 - **Outside a monorepo** — you're asked "Initialize with a webapp?" (Y/n, default Y), then for the repo name. Picking the webapp option also asks for the webapp name and scaffolds it inside `packages/<webapp-name>/`. Declining gives you an empty monorepo.
 - **Inside a monorepo** — pick `Webapp` (default) or `Library` to add a new package under the workspace pattern.
 
+Generated monorepos include a root `.mosaic-workspace.json` and a pinned
+`pnpm mosaic` script. Prefer the workspace-owned command when adding packages:
+
+```bash
+pnpm mosaic add webapp my-app
+pnpm mosaic add library my-lib
+```
+
+That command uses the create package version and template compatibility versions
+the monorepo was created with, so a newly added app does not silently drift to a
+newer scaffold.
+
 ## Happy-path: zero-friction webapp
 
 When you scaffold a webapp (the default flow), `create` automatically runs:

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { program } from "commander";
-import { execFile, execSync, spawn } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
 import path from "node:path";
 import chalk from "chalk";
 import fs from "fs-extra";
@@ -10,7 +10,6 @@ import { parse } from "yaml";
 import { randomBytes } from "node:crypto";
 import inquirer from "inquirer";
 import validateNpmPackageName from "validate-npm-package-name";
-import { promisify } from "node:util";
 //#region src/utils/case-converters.ts
 /** Lowercase, hyphenated, npm-package-name-safe form: "My Cool App" → "my-cool-app". */
 function toKebabCase(str) {
@@ -192,6 +191,24 @@ function resolveMosaicTemplatePath(options) {
 	throw new Error("Mosaic repo path required. Use --mosaic-template-path or set MOSAIC_TEMPLATE_PATH.");
 }
 //#endregion
+//#region src/utils/package-metadata.ts
+const FALLBACK_METADATA = {
+	name: "@percepta/create",
+	version: "0.0.0"
+};
+function readCreatePackageMetadata() {
+	const currentDir = path.dirname(fileURLToPath(import.meta.url));
+	const candidates = [path.resolve(currentDir, "../package.json"), path.resolve(currentDir, "../../package.json")];
+	for (const packageJsonPath of candidates) try {
+		const pkg = fs.readJsonSync(packageJsonPath);
+		if (typeof pkg.name === "string" && typeof pkg.version === "string") return {
+			name: pkg.name,
+			version: pkg.version
+		};
+	} catch {}
+	return FALLBACK_METADATA;
+}
+//#endregion
 //#region src/utils/validate.ts
 function validateProjectName(name) {
 	const result = validateNpmPackageName(name);
@@ -352,7 +369,9 @@ const PLACEHOLDERS = {
 	__APP_NAME_UPPER__: "nameUpper",
 	__APP_NAME_SNAKE__: "nameSnake",
 	__REPO_NAME__: "repoName",
-	__REPO_NAME_SNAKE__: "repoNameSnake"
+	__REPO_NAME_SNAKE__: "repoNameSnake",
+	__CREATE_PACKAGE__: "createPackage",
+	__CREATE_VERSION__: "createVersion"
 };
 const SKIP_DIRS = new Set([
 	"node_modules",
@@ -450,77 +469,6 @@ async function replacePlaceholders(targetDir, config) {
 	return stats;
 }
 //#endregion
-//#region src/utils/resolve-percepta-versions.ts
-const execFileAsync = promisify(execFile);
-const DEPENDENCY_SECTIONS = [
-	"dependencies",
-	"devDependencies",
-	"optionalDependencies",
-	"peerDependencies"
-];
-function getPerceptaPackages(pkg) {
-	const names = /* @__PURE__ */ new Set();
-	for (const section of DEPENDENCY_SECTIONS) {
-		const deps = pkg[section];
-		if (!deps) continue;
-		for (const name of Object.keys(deps)) if (name.startsWith("@percepta/")) names.add(name);
-	}
-	return [...names].sort();
-}
-async function npmViewDistTagLatest(packageName, cwd) {
-	const { stdout } = await execFileAsync("npm", [
-		"view",
-		packageName,
-		"dist-tags.latest",
-		"--silent"
-	], {
-		cwd,
-		encoding: "utf8",
-		timeout: 5e3
-	});
-	const version = stdout.trim();
-	return version.length > 0 ? version : null;
-}
-async function resolvePerceptaVersionsInPackageJson(packageJsonPath, lookupLatest = npmViewDistTagLatest) {
-	const cwd = path.dirname(packageJsonPath);
-	const pkg = await fs.readJson(packageJsonPath);
-	const packageNames = getPerceptaPackages(pkg);
-	const resolved = {};
-	const failed = [];
-	const results = await Promise.all(packageNames.map(async (packageName) => {
-		try {
-			return {
-				packageName,
-				latest: await lookupLatest(packageName, cwd)
-			};
-		} catch {
-			return {
-				packageName,
-				latest: null
-			};
-		}
-	}));
-	for (const { packageName, latest } of results) {
-		if (!latest) {
-			failed.push(packageName);
-			continue;
-		}
-		resolved[packageName] = latest;
-		for (const section of DEPENDENCY_SECTIONS) {
-			const deps = pkg[section];
-			if (deps?.[packageName]) deps[packageName] = latest;
-		}
-	}
-	if (Object.keys(resolved).length > 0) {
-		await fs.writeJson(packageJsonPath, pkg, { spaces: 2 });
-		await fs.appendFile(packageJsonPath, "\n");
-	}
-	return {
-		resolved,
-		failed
-	};
-}
-//#endregion
 //#region src/utils/template-versions.ts
 const FALLBACK_TEMPLATE_VERSION = "1.0.0";
 function readTemplateVersions() {
@@ -536,8 +484,55 @@ function getTemplateVersion(templateType) {
 	return readTemplateVersions()[templateType] ?? FALLBACK_TEMPLATE_VERSION;
 }
 //#endregion
+//#region src/utils/workspace-manifest.ts
+const WORKSPACE_MANIFEST_FILENAME = ".mosaic-workspace.json";
+function getWorkspaceManifestPath(rootDir) {
+	return path.join(rootDir, WORKSPACE_MANIFEST_FILENAME);
+}
+function createWorkspaceManifest(createdAt = (/* @__PURE__ */ new Date()).toISOString()) {
+	const createPackage = readCreatePackageMetadata();
+	return {
+		schemaVersion: 1,
+		createPackage: createPackage.name,
+		createVersion: createPackage.version,
+		monorepoTemplateVersion: getTemplateVersion("monorepo"),
+		compatibleTemplates: {
+			webapp: getTemplateVersion("webapp"),
+			library: getTemplateVersion("library")
+		},
+		createdAt
+	};
+}
+async function readWorkspaceManifest(rootDir) {
+	const manifestPath = getWorkspaceManifestPath(rootDir);
+	if (!await fs.pathExists(manifestPath)) return null;
+	const content = await fs.readFile(manifestPath, "utf-8");
+	try {
+		return JSON.parse(content);
+	} catch (error) {
+		throw new Error(`Invalid JSON in ${WORKSPACE_MANIFEST_FILENAME}: ${error.message}`);
+	}
+}
+async function writeWorkspaceManifest(rootDir, manifest) {
+	const manifestPath = getWorkspaceManifestPath(rootDir);
+	await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+	await fs.appendFile(manifestPath, "\n");
+}
+function getCompatibleTemplateVersion(manifest, templateType) {
+	return manifest?.compatibleTemplates[templateType] ?? getTemplateVersion(templateType);
+}
+//#endregion
 //#region src/commands/create.ts
 const PACKAGE_MANAGER = "pnpm";
+const MAX_INSTALL_OUTPUT_CHARS = 64e3;
+const MAX_INSTALL_OUTPUT_LINES = 80;
+var PackageManagerCommandError = class extends Error {
+	constructor(message, output) {
+		super(message);
+		this.output = output;
+		this.name = "PackageManagerCommandError";
+	}
+};
 /** Paths in copy-paste shell commands (POSIX-style). */
 function shPath(p) {
 	return p.split(path.sep).join("/");
@@ -545,17 +540,42 @@ function shPath(p) {
 /** Non-blocking install so ora can animate (execSync would block timers). */
 function runPackageManagerInstall(packageManager, cwd, args = ["install"]) {
 	return new Promise((resolve, reject) => {
+		let output = "";
+		const appendOutput = (chunk) => {
+			output += chunk.toString();
+			if (output.length > MAX_INSTALL_OUTPUT_CHARS) output = output.slice(-MAX_INSTALL_OUTPUT_CHARS);
+		};
 		const child = spawn(packageManager, args, {
 			cwd,
-			stdio: "ignore"
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		child.stdout?.on("data", appendOutput);
+		child.stderr?.on("data", appendOutput);
+		child.on("error", (error) => {
+			reject(new PackageManagerCommandError(`${packageManager} ${args.join(" ")} failed: ${error.message}`, output));
 		});
-		child.on("error", reject);
 		child.on("close", (code) => {
 			if (code === 0) resolve();
-			else reject(/* @__PURE__ */ new Error(`${packageManager} ${args.join(" ")} exited with code ${code ?? "unknown"}`));
+			else reject(new PackageManagerCommandError(`${packageManager} ${args.join(" ")} exited with code ${code ?? "unknown"}`, output));
 		});
 	});
 }
+function printInstallFailureOutput(error) {
+	if (!(error instanceof PackageManagerCommandError)) return;
+	const output = error.output.trim();
+	if (!output) return;
+	const lines = output.split(/\r?\n/);
+	const omitted = Math.max(0, lines.length - MAX_INSTALL_OUTPUT_LINES);
+	const visibleLines = lines.slice(-MAX_INSTALL_OUTPUT_LINES);
+	console.log();
+	console.log(chalk.bold(`Last ${visibleLines.length} lines from pnpm install:`));
+	if (omitted > 0) console.log(chalk.dim(`... omitted ${omitted} earlier lines ...`));
+	console.log(visibleLines.join("\n"));
+}
 /**
 * Runs the monorepo-root `setup` script (docker + access + db + seed).
 * Uses `pnpm run setup` (not `pnpm setup`) because `pnpm setup` is a pnpm builtin that configures
@@ -696,19 +716,20 @@ async function autoRunWebapp(packageDir, monorepoRoot) {
 	await closed;
 	return true;
 }
-async function writeMosaicFiles(packageDir, config, projectType) {
+async function writeMosaicFiles(packageDir, config, projectType, templateVersion = getTemplateVersion(projectType), templateCommit = "npm") {
 	await writeManifest(packageDir, {
 		templateType: projectType,
-		templateVersion: getTemplateVersion(projectType),
-		templateCommit: "npm",
+		templateVersion,
+		templateCommit,
 		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 		placeholders: derivePlaceholders(config.name, config.title, config.repoName),
-		source: { templatePath: `packages/create-mosaic-module/templates/${projectType}` }
+		source: { templatePath: `packages/blueberry/templates/${projectType}` }
 	});
 	const notesPath = path.join(packageDir, "mosaic-template-notes.md");
 	await fs.writeFile(notesPath, `# Mosaic Divergence Notes\n\nDocument intentional differences from the ${projectType} template here.\nClaude reads this file during sync to preserve your customizations.\n\n## Intentional Divergences\n\n_None yet — freshly created from template._\n`);
 }
 function buildAppConfig(name, title = toTitleCase(name), repoName = name) {
+	const createPackage = readCreatePackageMetadata();
 	return {
 		name,
 		title,
@@ -716,7 +737,9 @@ function buildAppConfig(name, title = toTitleCase(name), repoName = name) {
 		nameUpper: name.toUpperCase(),
 		nameSnake: toSnakeCase(name),
 		repoName,
-		repoNameSnake: toSnakeCase(repoName)
+		repoNameSnake: toSnakeCase(repoName),
+		createPackage: createPackage.name,
+		createVersion: createPackage.version
 	};
 }
 /** Copy the monorepo template into `targetDir` and replace its placeholders. */
@@ -746,7 +769,7 @@ async function scaffoldMonorepo(targetDir, config) {
 * webapp-only post-copy steps (.env.local, workflow relocation) when applicable.
 */
 async function addPackageToMonorepo(args) {
-	const { packageDir, monorepoRoot, projectType, config } = args;
+	const { packageDir, monorepoRoot, projectType, config, templateVersion, templateCommit } = args;
 	const copySpinner = ora("Copying package template...").start();
 	try {
 		await copyTemplate(packageDir, projectType);
@@ -765,27 +788,12 @@ async function addPackageToMonorepo(args) {
 		console.error(error);
 		process.exit(1);
 	}
-	await writeMosaicFiles(packageDir, config, projectType);
+	await writeMosaicFiles(packageDir, config, projectType, templateVersion, templateCommit);
 	if (projectType === "webapp") {
-		await resolvePerceptaPackageVersions(packageDir);
 		await generateEnvLocal(packageDir);
 		await relocateWorkflowsToRoot(packageDir, monorepoRoot, config.name);
 	}
 }
-async function resolvePerceptaPackageVersions(packageDir) {
-	const packageJsonPath = path.join(packageDir, "package.json");
-	if (!await fs.pathExists(packageJsonPath)) return;
-	const spinner = ora("Resolving latest @percepta/* versions...").start();
-	try {
-		const result = await resolvePerceptaVersionsInPackageJson(packageJsonPath);
-		const count = Object.keys(result.resolved).length;
-		if (result.failed.length > 0) spinner.warn(`Resolved ${count} @percepta/* versions; kept existing ranges for ${result.failed.join(", ")}`);
-		else spinner.succeed(`Resolved ${count} @percepta/* versions`);
-	} catch (error) {
-		spinner.warn("Could not resolve latest @percepta/* versions; kept template ranges");
-		console.log(chalk.dim(error.message));
-	}
-}
 /** Initialize a git repo at `targetDir` with an initial commit. Best-effort. */
 function initGitRepo(targetDir) {
 	const gitSpinner = ora("Initializing git repository...").start();
@@ -818,8 +826,9 @@ async function installAtMonorepoRoot(monorepoRoot, installDeps) {
 		await runPackageManagerInstall(PACKAGE_MANAGER, monorepoRoot);
 		spinner.succeed("Installed dependencies");
 		return true;
-	} catch {
+	} catch (error) {
 		spinner.warn(`Failed to install dependencies. Run '${PACKAGE_MANAGER} install' from monorepo root.`);
+		printInstallFailureOutput(error);
 		return false;
 	}
 }
@@ -858,6 +867,23 @@ function requireNpmTokenForWebappInstall(projectType, installDeps) {
 	console.error(chalk.dim("  Or pass --skip-install to scaffold without running install."));
 	process.exit(1);
 }
+function ensureWorkspaceCreateVersionCompatible(workspaceManifest, projectType) {
+	if (!workspaceManifest || projectType === "monorepo") return;
+	const createPackage = readCreatePackageMetadata();
+	if (workspaceManifest.createPackage === createPackage.name && workspaceManifest.createVersion === createPackage.version) return;
+	console.log();
+	console.error(chalk.red(`Error: This workspace is pinned to ${workspaceManifest.createPackage}@${workspaceManifest.createVersion}, but you are running ${createPackage.name}@${createPackage.version}.`));
+	console.error();
+	console.error(chalk.dim("  Run the workspace-owned command so new packages match this monorepo:"));
+	console.error(chalk.cyan(`  pnpm mosaic add ${projectType} <name>`));
+	console.error();
+	console.error(chalk.dim("  To adopt newer templates, upgrade the workspace manifest first."));
+	process.exit(1);
+}
+function getTemplateCommitSource(workspaceManifest) {
+	if (!workspaceManifest) return "npm";
+	return `${workspaceManifest.createPackage}@${workspaceManifest.createVersion}`;
+}
 async function createProject(options) {
 	const cwd = await resolveCreateCwd(options.cwd);
 	if (options.type !== void 0 && !isValidProjectType(options.type)) {
@@ -868,6 +894,10 @@ async function createProject(options) {
 	console.log(chalk.bold("Creating a new Mosaic package..."));
 	console.log();
 	const monorepoContext = await detectMonorepo(cwd);
+	if (options.addOnly && !monorepoContext.found) {
+		console.error(chalk.red("Error: 'create add' must be run inside an existing pnpm monorepo."));
+		process.exit(1);
+	}
 	if (options.type === "monorepo" && monorepoContext.found) {
 		console.error(chalk.red(`Error: Already inside a monorepo at ${monorepoContext.rootDir}. Choose 'webapp' or 'library' to add a package, or run from outside the monorepo.`));
 		process.exit(1);
@@ -875,6 +905,14 @@ async function createProject(options) {
 	if (monorepoContext.found) console.log(chalk.dim("  Detected monorepo at"), chalk.cyan(monorepoContext.rootDir));
 	else console.log(chalk.dim("  No monorepo detected. A new monorepo will be created."));
 	console.log();
+	const workspaceManifest = monorepoContext.found ? await readWorkspaceManifest(monorepoContext.rootDir) : null;
+	if (workspaceManifest) {
+		console.log(chalk.dim("  Workspace create version:"), chalk.cyan(`${workspaceManifest.createPackage}@${workspaceManifest.createVersion}`));
+		console.log();
+	} else if (monorepoContext.found) {
+		console.log(chalk.yellow("!"), "No .mosaic-workspace.json found; using this CLI's bundled templates.");
+		console.log();
+	}
 	const projectName = options.name;
 	const repoName = options.repoName;
 	if (options.yes && !projectName) {
@@ -898,6 +936,7 @@ async function createProject(options) {
 	let answers;
 	if (options.yes) {
 		const projectType = options.type || "webapp";
+		ensureWorkspaceCreateVersionCompatible(workspaceManifest, projectType);
 		requireNpmTokenForWebappInstall(projectType, !options.skipInstall);
 		const kebabName = toKebabCase(projectName);
 		const kebabRepoName = repoName ? toKebabCase(repoName) : kebabName;
@@ -918,7 +957,10 @@ async function createProject(options) {
 			skipInstall: options.skipInstall,
 			monorepoContext,
 			cwd,
-			beforeNamePrompt: (projectType) => requireNpmTokenForWebappInstall(projectType, !options.skipInstall)
+			beforeNamePrompt: (projectType) => {
+				ensureWorkspaceCreateVersionCompatible(workspaceManifest, projectType);
+				requireNpmTokenForWebappInstall(projectType, !options.skipInstall);
+			}
 		});
 		if (monorepoContext.found && monorepoContext.packageDir && !answers.directory) answers.directory = path.join(monorepoContext.packageDir, answers.name);
 	}
@@ -946,7 +988,9 @@ async function createProject(options) {
 			packageDir,
 			monorepoRoot,
 			projectType: answers.projectType,
-			config
+			config,
+			templateVersion: getCompatibleTemplateVersion(workspaceManifest, answers.projectType),
+			templateCommit: getTemplateCommitSource(workspaceManifest)
 		});
 		await warnIfMissingRootNpmrc(monorepoRoot);
 		const installSucceeded = await installAtMonorepoRoot(monorepoRoot, answers.installDeps);
@@ -954,7 +998,7 @@ async function createProject(options) {
 		console.log(chalk.green("✔"), chalk.bold(`Created ${typeLabel} at`), chalk.cyan(path.relative(monorepoRoot, packageDir)));
 		console.log();
 		if (await maybeAutoRunWebapp(packageDir, monorepoRoot, answers.projectType, installSucceeded)) return;
-		printNextStepsExisting(answers, packageDir);
+		printNextStepsExisting(answers, packageDir, !installSucceeded);
 	} else {
 		const isBareMonorepo = answers.projectType === "monorepo";
 		const monorepoRoot = answers.directory;
@@ -981,11 +1025,15 @@ async function createProject(options) {
 			}
 		}
 		await scaffoldMonorepo(monorepoRoot, monorepoConfig);
+		const newWorkspaceManifest = createWorkspaceManifest();
+		await writeWorkspaceManifest(monorepoRoot, newWorkspaceManifest);
 		if (packageDir && answers.projectType !== "monorepo") await addPackageToMonorepo({
 			packageDir,
 			monorepoRoot,
 			projectType: answers.projectType,
-			config
+			config,
+			templateVersion: getCompatibleTemplateVersion(newWorkspaceManifest, answers.projectType),
+			templateCommit: getTemplateCommitSource(newWorkspaceManifest)
 		});
 		initGitRepo(monorepoRoot);
 		const installSucceeded = await installAtMonorepoRoot(monorepoRoot, answers.installDeps);
@@ -994,7 +1042,7 @@ async function createProject(options) {
 		if (!isBareMonorepo) console.log(chalk.green("✔"), chalk.bold(`Created ${typeLabel} at`), chalk.cyan(`packages/${answers.name}/`));
 		console.log();
 		if (await maybeAutoRunWebapp(packageDir, monorepoRoot, answers.projectType, installSucceeded)) return;
-		printNextStepsNew(answers, monorepoRoot);
+		printNextStepsNew(answers, monorepoRoot, !installSucceeded);
 	}
 }
 async function resolveCreateCwd(cwdOption) {
@@ -1013,7 +1061,7 @@ async function resolveCreateCwd(cwdOption) {
 	return cwd;
 }
 function printWebappNextSteps(params) {
-	const { pm, answers, variant, monorepoRelativePath, packageRelativePathFromRoot } = params;
+	const { pm, answers, variant, installNeeded, monorepoRelativePath, packageRelativePathFromRoot } = params;
 	const repoRel = shPath(monorepoRelativePath) || ".";
 	const pkgFromRoot = shPath(packageRelativePathFromRoot ?? `packages/${answers.name}`) || ".";
 	const setupStep = "pnpm run setup";
@@ -1021,7 +1069,7 @@ function printWebappNextSteps(params) {
 	if (variant === "new") {
 		const oneLinerParts = [];
 		if (repoRel !== ".") oneLinerParts.push(`cd ${repoRel}`);
-		if (!answers.installDeps) oneLinerParts.push(`${pm} install`);
+		if (installNeeded) oneLinerParts.push(`${pm} install`);
 		oneLinerParts.push(setupStep);
 		oneLinerParts.push(`cd ${pkgFromRoot}`);
 		oneLinerParts.push(devStep);
@@ -1033,7 +1081,7 @@ function printWebappNextSteps(params) {
 		console.log();
 		let step = 1;
 		if (repoRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${repoRel}`);
-		if (!answers.installDeps) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
+		if (installNeeded) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
 		console.log(chalk.dim(`  ${step++}.`), setupStep);
 		console.log(chalk.dim(`  ${step++}.`), `cd ${pkgFromRoot}`);
 		console.log(chalk.dim(`  ${step++}.`), devStep);
@@ -1041,7 +1089,7 @@ function printWebappNextSteps(params) {
 	}
 	const oneLinerParts = [];
 	if (repoRel !== ".") oneLinerParts.push(`cd ${repoRel}`);
-	if (!answers.installDeps) oneLinerParts.push(`${pm} install`);
+	if (installNeeded) oneLinerParts.push(`${pm} install`);
 	oneLinerParts.push(setupStep, `cd ${pkgFromRoot}`, devStep);
 	console.log(chalk.bold("Copy-paste (from your current directory):"));
 	console.log();
@@ -1051,7 +1099,7 @@ function printWebappNextSteps(params) {
 	console.log();
 	let step = 1;
 	if (repoRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${repoRel}`);
-	if (!answers.installDeps) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
+	if (installNeeded) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
 	console.log(chalk.dim(`  ${step++}.`), setupStep);
 	console.log(chalk.dim(`  ${step++}.`), `cd ${pkgFromRoot}`);
 	console.log(chalk.dim(`  ${step++}.`), devStep);
@@ -1070,7 +1118,7 @@ async function warnIfMissingRootNpmrc(rootDir) {
 	console.log(chalk.cyan("    //registry.npmjs.org/:_authToken=${NPM_TOKEN}"));
 	console.log();
 }
-function printNextStepsNew(answers, targetDir) {
+function printNextStepsNew(answers, targetDir, installNeeded) {
 	const pm = PACKAGE_MANAGER;
 	const relativePath = path.relative(process.cwd(), targetDir) || ".";
 	console.log("Next steps:");
@@ -1080,8 +1128,8 @@ function printNextStepsNew(answers, targetDir) {
 			let step = 1;
 			const repoRel = shPath(relativePath);
 			if (repoRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${repoRel}`);
-			if (!answers.installDeps) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
-			console.log(chalk.dim(`  ${step++}.`), `Add a package: ${chalk.cyan(`npx @percepta/create --type webapp <name>`)}`);
+			if (installNeeded) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
+			console.log(chalk.dim(`  ${step++}.`), `Add a package: ${chalk.cyan(`pnpm mosaic add webapp <name>`)}`);
 			break;
 		}
 		case "webapp":
@@ -1089,6 +1137,7 @@ function printNextStepsNew(answers, targetDir) {
 				pm,
 				answers,
 				variant: "new",
+				installNeeded,
 				monorepoRelativePath: relativePath
 			});
 			break;
@@ -1096,7 +1145,7 @@ function printNextStepsNew(answers, targetDir) {
 			let step = 1;
 			const repoRel = shPath(relativePath);
 			if (repoRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${repoRel}`);
-			if (!answers.installDeps) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
+			if (installNeeded) console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
 			console.log(chalk.dim(`  ${step++}.`), `cd packages/${answers.name}`);
 			console.log(chalk.dim(`  ${step++}.`), `${pm} dev`);
 			console.log(chalk.dim(`  ${step++}.`), `Edit src/index.ts to add your library code`);
@@ -1107,7 +1156,7 @@ function printNextStepsNew(answers, targetDir) {
 	console.log(chalk.dim("For more information, see the README.md in your project."));
 	console.log();
 }
-function printNextStepsExisting(answers, packageDir) {
+function printNextStepsExisting(answers, packageDir, installNeeded) {
 	const pm = PACKAGE_MANAGER;
 	const packageRelativePath = path.relative(process.cwd(), packageDir) || ".";
 	const monorepoRoot = path.dirname(path.dirname(packageDir));
@@ -1121,14 +1170,22 @@ function printNextStepsExisting(answers, packageDir) {
 				pm,
 				answers,
 				variant: "existing",
+				installNeeded,
 				monorepoRelativePath,
 				packageRelativePathFromRoot
 			});
 			break;
 		case "library": {
 			let step = 1;
-			const pkgRel = shPath(packageRelativePath);
-			if (pkgRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${pkgRel}`);
+			if (installNeeded) {
+				const repoRel = shPath(monorepoRelativePath);
+				if (repoRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${repoRel}`);
+				console.log(chalk.dim(`  ${step++}.`), `${pm} install`);
+				console.log(chalk.dim(`  ${step++}.`), `cd ${shPath(packageRelativePathFromRoot)}`);
+			} else {
+				const pkgRel = shPath(packageRelativePath);
+				if (pkgRel !== ".") console.log(chalk.dim(`  ${step++}.`), `cd ${pkgRel}`);
+			}
 			console.log(chalk.dim(`  ${step++}.`), `${pm} dev`);
 			console.log(chalk.dim(`  ${step++}.`), "Edit src/index.ts to add your library code");
 			break;
@@ -1140,11 +1197,27 @@ function printNextStepsExisting(answers, packageDir) {
 }
 //#endregion
 //#region src/index.ts
-program.name("create").description("Scaffold and manage Mosaic packages").version({
-	name: "@percepta/create",
-	version: "1.0.0"
-}.version);
+const packageJson = readCreatePackageMetadata();
+program.name("create").description("Scaffold and manage Mosaic packages").version(packageJson.version);
 program.command("create", { isDefault: true }).description("Scaffold a new Mosaic package").option("-t, --type <type>", "Package type: monorepo, webapp, or library").option("--name <name>", "Package/app name").option("--repo-name <name>", "Repository name when creating a new monorepo").option("--cwd <dir>", "Run create as if started from this directory").option("--skip-install", "Skip dependency installation (also skips the auto-run setup + dev + browser)", false).option("-y, --yes", "Skip all prompts and use defaults", false).action(createProject);
+program.command("add").description("Add a Mosaic package to the current monorepo").argument("[typeOrName]", "Package type (webapp/library) or package name").argument("[name]", "Package/app name").option("-t, --type <type>", "Package type: webapp or library").option("--name <name>", "Package/app name").option("--skip-install", "Skip dependency installation (also skips the auto-run setup + dev + browser)", false).option("-y, --yes", "Skip all prompts and use defaults", false).action(async (typeOrName, name, options) => {
+	let projectType = options.type;
+	let projectName = options.name;
+	if (typeOrName === "webapp" || typeOrName === "library") {
+		projectType = projectType ?? typeOrName;
+		projectName = projectName ?? name;
+	} else if (typeOrName === "monorepo") program.error("error: 'add' only supports webapp or library packages");
+	else if (typeOrName) {
+		if (name) program.error(`error: unknown package type "${typeOrName}". Expected webapp or library.`);
+		projectName = projectName ?? typeOrName;
+	}
+	await createProject({
+		...options,
+		type: projectType,
+		name: projectName,
+		addOnly: true
+	});
+});
 program.command("status").description("Show template sync status for current app").option("--mosaic-template-path <path>", "Path to local mosaic repo checkout").action(async (options) => {
 	const { statusCommand } = await import("./status-CKe4aKso.js");
 	await statusCommand(options);
@@ -1154,11 +1227,11 @@ program.command("sync").description("Generate downstream sync context (template
 	await syncCommand(options);
 });
 program.command("upstream").description("Generate upstream context (app → template)").option("--mosaic-template-path <path>", "Path to local mosaic repo checkout").option("--files <patterns...>", "Specific files to propose upstream").action(async (options) => {
-	const { upstreamCommand } = await import("./upstream-D-LH_1z4.js");
+	const { upstreamCommand } = await import("./upstream-gUHLWSR1.js");
 	await upstreamCommand(options);
 });
 program.command("init").description("Add .mosaic-template.json to an existing app").option("-t, --type <type>", "Template type (e.g., webapp, library)").option("--template-version <version>", "Template version to set").action(async (options) => {
-	const { initCommand } = await import("./init-CtCp7Tv2.js");
+	const { initCommand } = await import("./init-sI9aIrkU.js");
 	await initCommand(options);
 });
 program.parse();