@percepta/create 3.4.2 → 3.5.0

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,6 +484,44 @@ 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";
 /** Paths in copy-paste shell commands (POSIX-style). */
@@ -696,19 +682,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 +703,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 +735,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 +754,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();
@@ -858,6 +832,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 +859,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 +870,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 +901,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 +922,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 +953,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);
@@ -981,11 +990,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);
@@ -1081,7 +1094,7 @@ function printNextStepsNew(answers, targetDir) {
 			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>`)}`);
+			console.log(chalk.dim(`  ${step++}.`), `Add a package: ${chalk.cyan(`pnpm mosaic add webapp <name>`)}`);
 			break;
 		}
 		case "webapp":
@@ -1140,11 +1153,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 +1183,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();