@simple-auth-kit/cli 1.0.0

package/simple-auth-kit.ts

@@ -0,0 +1,715 @@
+#!/usr/bin/env node
+// Published as @simple-auth-kit/cli — `npx @simple-auth-kit/cli add nestjs-prisma --into .`.
+// Also runnable straight from a monorepo checkout: `pnpm --filter @simple-auth-kit/cli run cli
+// -- add nestjs-prisma --into ../my-app`.
+//
+// A combo ships in variants (see registry/README.md). `add <combo>` emits the default one;
+// `add <combo> --workspaces` emits the workspace variant, composed by copying the combo's
+// `shared/` directory and then `variants/<variant>/` over the top.
+//
+// Combos also carry a `kind` ("api" | "admin" | "mobile", defaults to "api" when absent) and an
+// `installMode` ("merge" | "scaffold", defaults to "merge" for api / "scaffold" otherwise). "api"
+// combos merge a source fragment into an existing project (today's only behavior, unchanged).
+// "admin"/"mobile" combos scaffold a whole standalone app directly into --into, package.json and
+// all. `add` with no combo positional launches a guided, shadcn-CLI-style prompt flow (via
+// `prompts`) asking which kind(s) to generate, which framework per kind, and whether to include
+// workspaces support — or reads the same choices from --kind/--framework/--workspaces for
+// non-interactive/scripted use.
+import { existsSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import prompts from "prompts";
+import { copyDir, copyOneFile, CopyResult, NEVER_COPY, pruneRemovedFiles, SCAFFOLD_NEVER_COPY, sha256, toPosix } from "./lib/copy.js";
+import { reconcileManifest, renameNative, type NativeIdentity } from "./lib/rename-native.js";
+
+const CLI_DIR = dirname(fileURLToPath(import.meta.url));
+// Two contexts, and they disagree about where the registry is:
+//  - published package: registry/ is bundled as a sibling of this file (see
+//    scripts/bundle-registry.mjs, run at `prepack` time — it's never committed to git, only
+//    materialized right before `npm publish`/`npm pack`).
+//  - monorepo dev checkout: this file lives at packages/cli/, so the real registry/ is two
+//    levels up, at the repo root.
+const REGISTRY_ROOT = existsSync(join(CLI_DIR, "registry")) ? join(CLI_DIR, "registry") : resolve(CLI_DIR, "..", "..", "registry");
+const CONFIG_FILENAME = ".simple-auth-kit.json";
+const DEFAULT_VARIANT = "base";
+
+type Kind = "api" | "admin" | "mobile";
+type InstallMode = "merge" | "scaffold";
+
+const KIND_LABELS: Record<Kind, string> = { api: "API (backend)", admin: "Admin console", mobile: "Mobile app" };
+const KIND_FRAMEWORK_NOUN: Record<Kind, string> = { api: "API stack", admin: "admin framework", mobile: "mobile framework" };
+
+/** Flags that take no value. Everything else consumes the next argv entry. */
+const BOOLEAN_FLAGS = new Set(["workspaces", "force", "check", "config-only"]);
+
+interface SimpleAuthKitConfig {
+  path: string;
+  alias: string;
+  /** Paths (relative to the install directory) the CLI must never write or delete. */
+  ignore: string[];
+}
+
+interface ComboEntry {
+  dir: string;
+  sharedDir?: string;
+  variantsDir?: string;
+  variants: string[];
+  peerDependencies: string[];
+  postInstall: string[];
+  variantPostInstall?: Record<string, string[]>;
+  /** Defaults to "api" — every combo predating this field is an api combo. */
+  kind?: Kind;
+  /** Defaults to "merge" for kind "api", "scaffold" otherwise. */
+  installMode?: InstallMode;
+  /** Present only for combos (bare React Native) whose native android/ios scaffolding bakes
+   * in a placeholder app identity that must be re-templated per generated app — see
+   * lib/rename-native.ts. Absent for every other combo (nothing to rename). */
+  nativeIdentity?: NativeIdentity;
+}
+
+interface Registry {
+  core: { dir: string; peerDependencies: string[] };
+  variants: Record<string, { flag: string | null; description: string }>;
+  combos: Record<string, ComboEntry>;
+}
+
+interface AuthLock {
+  combo?: string;
+  variant?: string;
+  installedAt?: string;
+  files?: Record<string, string>;
+}
+
+const DEFAULT_CONFIG: SimpleAuthKitConfig = { path: "src/lib/auth", alias: "@/lib/auth", ignore: [] };
+
+const comboKind = (combo: ComboEntry): Kind => combo.kind ?? "api";
+const comboInstallMode = (combo: ComboEntry): InstallMode => combo.installMode ?? (comboKind(combo) === "api" ? "merge" : "scaffold");
+
+function parseArgs(argv: string[]): { command?: string; positional: string[]; flags: Record<string, string | true> } {
+  const [command, ...rest] = argv;
+  const positional: string[] = [];
+  const flags: Record<string, string | true> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      if (BOOLEAN_FLAGS.has(name)) {
+        flags[name] = true;
+      } else {
+        flags[name] = rest[i + 1];
+        i++;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { command, positional, flags };
+}
+
+const flagString = (value: string | true | undefined): string | undefined => (typeof value === "string" ? value : undefined);
+const flagList = (value: string | true | undefined): string[] | undefined =>
+  typeof value === "string" ? value.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+
+async function loadRegistry(): Promise<Registry> {
+  return JSON.parse(await readFile(join(CLI_DIR, "registry.json"), "utf8"));
+}
+
+async function loadConfig(targetRoot: string): Promise<SimpleAuthKitConfig> {
+  try {
+    const raw = await readFile(join(targetRoot, CONFIG_FILENAME), "utf8");
+    return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+async function loadLock(targetRoot: string): Promise<AuthLock> {
+  try {
+    return JSON.parse(await readFile(join(targetRoot, "auth.lock.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True if `dir` doesn't exist yet, or exists and has nothing in it (dotfiles like `.git`
+ * excepted — a repo you've already `git init`'d shouldn't count as "occupied"). */
+async function isEmptyDir(dir: string): Promise<boolean> {
+  try {
+    const entries = await readdir(dir);
+    return entries.every((name) => name.startsWith("."));
+  } catch {
+    return true; // doesn't exist — mkdir'd on demand by the copy, nothing in the way
+  }
+}
+
+/**
+ * In an interactive session, with neither `--force` nor `--check`: runs `runDry` (expected to be
+ * a dry-run copy pass — nothing written) to find files that would otherwise be silently skipped
+ * as locally modified, and lets the user pick which of those — if any — to overwrite anyway.
+ * shadcn-CLI-style "this file already exists, overwrite?", asked once as a multi-select rather
+ * than one prompt per file. Falls through to the existing non-interactive behavior (silent skip,
+ * reported at the end by printInstallSummary) outside a TTY or under --check, since there's
+ * nothing useful to prompt into either case.
+ */
+async function resolveForcePaths(runDry: () => Promise<{ result: CopyResult }>, flags: Record<string, string | true>): Promise<Set<string>> {
+  if (flags.force === true || flags.check === true || !isTTY()) return new Set();
+
+  const { result } = await runDry();
+  if (!result.skipped.length) return new Set();
+
+  console.log(`\n${result.skipped.length} file(s) have changed locally since the last install:`);
+  const picked = await ask<string[]>({
+    type: "multiselect",
+    name: "paths",
+    message: "Overwrite any of these with the latest version? (unselected ones are left alone)",
+    choices: result.skipped.map((file) => ({ title: file, value: file, selected: false })),
+    instructions: false,
+  });
+  return new Set(picked ?? []);
+}
+
+/**
+ * The fresh-setup entry point: writes .simple-auth-kit.json (so merge-mode combos have an
+ * install path/alias to anchor to), then launches the same guided "what do you need"
+ * kind/framework/workspaces flow as bare `add` (interactive prompts, or --kind/--framework for
+ * non-interactive/scripted use) to actually install something — matching how `shadcn init` is
+ * the fresh-project entry point, not just a config file. Pass --config-only to get the old
+ * behavior back (write the config and stop there, no install).
+ */
+async function cmdInit(targetRoot: string, flags: Record<string, string | true>) {
+  const config: SimpleAuthKitConfig = {
+    path: flagString(flags.path) ?? DEFAULT_CONFIG.path,
+    alias: flagString(flags.alias) ?? DEFAULT_CONFIG.alias,
+    ignore: [],
+  };
+  await writeFile(join(targetRoot, CONFIG_FILENAME), JSON.stringify(config, null, 2) + "\n", "utf8");
+  console.log(`Wrote ${CONFIG_FILENAME} — combos will install into ${config.path} (import alias ${config.alias})`);
+
+  if (flags["config-only"] === true) return;
+
+  console.log("");
+  await cmdCreate(targetRoot, flags);
+}
+
+function resolveVariant(combo: ComboEntry, comboName: string, requested: string): string | null {
+  if (combo.variants.length === 0) {
+    console.error(`Combo "${comboName}" has not been migrated to the variant layout yet (see registry/README.md) — nothing to install.`);
+    return null;
+  }
+  if (!combo.variants.includes(requested)) {
+    console.error(`Combo "${comboName}" has no "${requested}" variant. Available: ${combo.variants.join(", ")}`);
+    return null;
+  }
+  return requested;
+}
+
+function requestedVariant(flags: Record<string, string | true>): string {
+  return flags.workspaces === true ? "workspaces" : (flagString(flags.variant) ?? DEFAULT_VARIANT);
+}
+
+function printInstallSummary(result: CopyResult, pruned: { removed: string[]; keptModified: string[] }) {
+  if (result.updated.length) {
+    console.log(`\nUpdated (new or changed since last install):`);
+    for (const file of result.updated) console.log(`  ${file}`);
+  }
+  if (result.skipped.length) {
+    console.log(`\nLeft alone — modified since the last install (re-run with --force to overwrite):`);
+    for (const file of result.skipped) console.log(`  ${file}`);
+  }
+  if (result.ignored.length) {
+    console.log(`\nLeft alone — on the ignore list in ${CONFIG_FILENAME}:`);
+    for (const file of result.ignored) console.log(`  ${file}`);
+  }
+  if (pruned.removed.length) {
+    console.log(`\nRemoved — no longer part of this install:`);
+    for (const file of pruned.removed) console.log(`  ${file}`);
+  }
+  if (pruned.keptModified.length) {
+    console.log(`\nNo longer part of this install, but modified locally, so kept (delete by hand if you don't want them):`);
+    for (const file of pruned.keptModified) console.log(`  ${file}`);
+  }
+}
+
+function printPostInstallNotes(combo: ComboEntry, variant: string) {
+  const notes = [...combo.postInstall, ...(combo.variantPostInstall?.[variant] ?? [])];
+  if (notes.length) {
+    console.log(`\nNext steps:`);
+    for (const note of notes) console.log(`  - ${note}`);
+  }
+}
+
+/** An ORM combo's config file (shared/) + data directory (variants/<variant>/) that must land at
+ * the *project root* instead of merging into destRoot with everything else — each ORM's own tool
+ * (`npx prisma ...`, `npx drizzle-kit ...`) looks for its config there by default, no `cd` needed.
+ *
+ * `generatedClientImport`: only Prisma has this — its schema's `generator { output }` is relative
+ * to schema.prisma's own location, so moving prisma.config.ts/prisma/ to the project root also
+ * moves the generated client. The registry source's `src/*.ts` files import it as
+ * `"../generated/prisma/client.js"` — correct for the registry's own dev/typecheck loop (where
+ * nothing has moved), but wrong once copied into a real install, so installMerge rewrites that
+ * literal string in every copied file to the new correct relative path. Drizzle has no equivalent
+ * generated artifact to redirect. */
+const ORM_LAYOUTS: { configFile: string; dataDir: string; generatedClientImport?: string }[] = [
+  { configFile: "prisma.config.ts", dataDir: "prisma", generatedClientImport: "../generated/prisma/client.js" },
+  { configFile: "drizzle.config.ts", dataDir: "drizzle" },
+];
+
+/** "merge" install — core + shared + variant merged into an existing project at
+ * <targetRoot>/<installPath>, with the core import alias rewritten. One exception: an ORM combo's
+ * config file and data directory (see ORM_LAYOUTS) land at the *project root* instead — e.g. the
+ * Prisma combos' `prisma.config.ts` + `prisma/`, or the Drizzle combos' `drizzle.config.ts` +
+ * `drizzle/`.
+ *
+ * Both are still copied with `destRoot` (not targetRoot) as the manifest-key root, which makes
+ * `copyOneFile` compute "../"-relative keys for them — deliberate, not an oversight: those keys
+ * can never collide with a real destRoot-relative key, so `pruneRemovedFiles` below correctly
+ * removes an ORM folder a pre-migration install left nested inside destRoot, without disturbing
+ * anything else's keys. */
+async function installMerge(comboName: string, combo: ComboEntry, variant: string, registry: Registry, targetRoot: string, flags: Record<string, string | true>) {
+  const config = await loadConfig(targetRoot);
+  const installPath = flagString(flags.path) ?? config.path;
+  const alias = flagString(flags.alias) ?? config.alias;
+  const destRoot = resolve(targetRoot, installPath);
+
+  const lock = await loadLock(targetRoot);
+  const previous = lock.files ?? {};
+  const force = flags.force === true;
+  const checkOnly = flags.check === true;
+
+  const comboDir = join(REGISTRY_ROOT, combo.dir);
+  const sharedDir = join(comboDir, combo.sharedDir ?? "shared");
+  const variantDir = join(comboDir, combo.variantsDir ?? "variants", variant);
+
+  const orm = await (async () => {
+    for (const layout of ORM_LAYOUTS) {
+      if (await pathExists(join(sharedDir, layout.configFile))) return layout;
+    }
+    return null;
+  })();
+  const skipFromShared = orm ? new Set([...NEVER_COPY, orm.configFile]) : NEVER_COPY;
+  const skipFromVariant = orm ? new Set([...NEVER_COPY, orm.dataDir]) : NEVER_COPY;
+
+  const extraRewrites = orm?.generatedClientImport
+    ? [
+        {
+          from: orm.generatedClientImport,
+          to: toPosix(relative(join(destRoot, "src"), join(targetRoot, "generated", "prisma", "client.js"))),
+        },
+      ]
+    : undefined;
+
+  const runCopy = async (opts: { force: boolean; forcePaths: Set<string>; dryRun: boolean }) => {
+    const result: CopyResult = { manifest: {}, skipped: [], ignored: [], updated: [] };
+    const copyOpts = {
+      aliasFrom: "@/lib/auth/core",
+      aliasTo: `${alias}/core`,
+      extraRewrites,
+      previous,
+      force: opts.force,
+      forcePaths: opts.forcePaths,
+      ignore: config.ignore,
+      neverCopy: NEVER_COPY,
+      dryRun: opts.dryRun,
+    };
+
+    await copyDir(join(REGISTRY_ROOT, registry.core.dir), join(destRoot, "core"), copyOpts, destRoot, result);
+    await copyDir(sharedDir, destRoot, { ...copyOpts, neverCopy: skipFromShared }, destRoot, result);
+    await copyDir(variantDir, destRoot, { ...copyOpts, neverCopy: skipFromVariant }, destRoot, result);
+
+    if (orm) {
+      await copyOneFile(join(sharedDir, orm.configFile), join(targetRoot, orm.configFile), destRoot, copyOpts, result);
+      await copyDir(join(variantDir, orm.dataDir), join(targetRoot, orm.dataDir), copyOpts, destRoot, result);
+    }
+
+    // Switching variants has to remove the old variant's files, or the project ends up with both wired in.
+    const pruned = await pruneRemovedFiles(destRoot, previous, result, { force: opts.force, ignore: config.ignore, dryRun: opts.dryRun });
+    return { result, pruned };
+  };
+
+  if (checkOnly) {
+    const { result, pruned } = await runCopy({ force, forcePaths: new Set(), dryRun: true });
+    console.log(`\nCheck only — nothing written. "${comboName}" (${variant} variant) in ${installPath} (alias ${alias}):`);
+    printInstallSummary(result, pruned);
+    const silent = !result.updated.length && !result.skipped.length && !pruned.removed.length && !pruned.keptModified.length;
+    if (silent) console.log(`\nUp to date — nothing would change.`);
+    return;
+  }
+
+  // Interactive + no --force: find locally-modified conflicts first (a dry run, nothing written),
+  // and let the user pick which — if any — to overwrite anyway, shadcn-"this file already exists"
+  // style, instead of the non-interactive default of silently leaving all of them alone.
+  const forcePaths = await resolveForcePaths(() => runCopy({ force: false, forcePaths: new Set(), dryRun: true }), flags);
+  const { result, pruned } = await runCopy({ force, forcePaths, dryRun: false });
+
+  await writeFile(
+    join(targetRoot, "auth.lock.json"),
+    JSON.stringify({ ...lock, combo: comboName, variant, installedAt: new Date().toISOString(), files: result.manifest }, null, 2) + "\n",
+    "utf8",
+  );
+
+  console.log(`\nInstalled "${comboName}" (${variant} variant) into ${installPath} (alias ${alias})`);
+  printInstallSummary(result, pruned);
+
+  const peerDeps = [...new Set([...registry.core.peerDependencies, ...combo.peerDependencies])];
+  console.log(`\nInstall peer dependencies:\n  npm install ${peerDeps.join(" ")}`);
+  printPostInstallNotes(combo, variant);
+}
+
+/** "scaffold" install — admin/mobile apps materialized as a whole standalone project directly
+ * into targetRoot: no core layer, no alias rewrite, package.json is real content (copied and
+ * name/description-templated), not the registry's own dev wiring. */
+async function installScaffold(comboName: string, combo: ComboEntry, variant: string, targetRoot: string, flags: Record<string, string | true>) {
+  const lock = await loadLock(targetRoot);
+  const previous = lock.files ?? {};
+  const force = flags.force === true;
+
+  // Only enforced on a genuinely fresh install (no auth.lock.json yet) — re-running this on an
+  // already-scaffolded app (an update) is expected and that directory is obviously non-empty.
+  const isFreshInstall = !lock.combo;
+  if (isFreshInstall && !force && !(await isEmptyDir(targetRoot))) {
+    console.error(
+      `${targetRoot} is not empty — "${comboName}" is a scaffold-mode combo (writes a whole new standalone project: package.json, src/, everything) and needs an empty directory. Use a different --into, empty it first, or pass --force to install into it anyway.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const comboDir = join(REGISTRY_ROOT, combo.dir);
+
+  const runCopy = async (opts: { force: boolean; forcePaths: Set<string>; dryRun: boolean }) => {
+    const result: CopyResult = { manifest: {}, skipped: [], ignored: [], updated: [] };
+    const copyOpts = { previous, force: opts.force, forcePaths: opts.forcePaths, neverCopy: SCAFFOLD_NEVER_COPY, dryRun: opts.dryRun };
+    await copyDir(join(comboDir, combo.sharedDir ?? "shared"), targetRoot, copyOpts, targetRoot, result);
+    await copyDir(join(comboDir, combo.variantsDir ?? "variants", variant), targetRoot, copyOpts, targetRoot, result);
+    const pruned = await pruneRemovedFiles(targetRoot, previous, result, { force: opts.force, dryRun: opts.dryRun });
+    return { result, pruned };
+  };
+
+  // Same shadcn-style "this file already exists, overwrite?" prompt as installMerge — see
+  // resolveForcePaths. A no-op dry run on a genuinely fresh install (nothing to conflict with).
+  const forcePaths = await resolveForcePaths(() => runCopy({ force: false, forcePaths: new Set(), dryRun: true }), flags);
+  const { result, pruned } = await runCopy({ force, forcePaths, dryRun: false });
+
+  const appName = flagString(flags.name) ?? basename(targetRoot);
+
+  if (combo.nativeIdentity) {
+    const renamed = await renameNative(targetRoot, combo.nativeIdentity, appName);
+    result.manifest = reconcileManifest(result.manifest, renamed);
+  }
+
+  const pkgPath = join(targetRoot, "package.json");
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    pkg.name = appName;
+    pkg.description = `Generated by simple-auth-kit (${comboName}, ${variant} variant).`;
+    const content = JSON.stringify(pkg, null, 2) + "\n";
+    await writeFile(pkgPath, content, "utf8");
+    result.manifest["package.json"] = sha256(content); // keep the manifest honest post-template
+  } catch {
+    // No package.json in this combo's template — nothing to name.
+  }
+
+  await writeFile(
+    join(targetRoot, "auth.lock.json"),
+    JSON.stringify({ ...lock, combo: comboName, variant, installedAt: new Date().toISOString(), files: result.manifest }, null, 2) + "\n",
+    "utf8",
+  );
+
+  console.log(`\nGenerated "${appName}" (${comboName}, ${variant} variant) into ${targetRoot}`);
+  printInstallSummary(result, pruned);
+  console.log(`\nDependencies are already declared in package.json — run \`npm install\` (or \`pnpm install\`) in ${targetRoot}.`);
+  printPostInstallNotes(combo, variant);
+}
+
+async function installCombo(comboName: string, combo: ComboEntry, variant: string, registry: Registry, targetRoot: string, flags: Record<string, string | true>) {
+  if (comboInstallMode(combo) === "scaffold") {
+    await installScaffold(comboName, combo, variant, targetRoot, flags);
+  } else {
+    await installMerge(comboName, combo, variant, registry, targetRoot, flags);
+  }
+}
+
+async function cmdAdd(comboName: string, targetRoot: string, flags: Record<string, string | true>) {
+  const registry = await loadRegistry();
+  const combo = registry.combos[comboName];
+  if (!combo) {
+    console.error(`Unknown combo "${comboName}". Available: ${Object.keys(registry.combos).join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const variant = resolveVariant(combo, comboName, requestedVariant(flags));
+  if (!variant) {
+    process.exitCode = 1;
+    return;
+  }
+
+  await installCombo(comboName, combo, variant, registry, targetRoot, flags);
+}
+
+function combosByKind(registry: Registry, kind: Kind): Array<[string, ComboEntry]> {
+  return Object.entries(registry.combos).filter(([, combo]) => comboKind(combo) === kind);
+}
+
+const isTTY = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+/** Wraps a single `prompts()` call so a cancel (Ctrl+C) surfaces as `null` instead of `undefined`,
+ * which prompts itself doesn't distinguish from "field asked but left empty". */
+async function ask<T>(question: Parameters<typeof prompts>[0] & { name: string }): Promise<T | null> {
+  const res = await prompts(question as never);
+  const value = (res as Record<string, unknown>)[question.name as string];
+  return value === undefined ? null : (value as T);
+}
+
+/**
+ * Resolves what to generate this run — from --kind/--framework/--workspaces flags where given,
+ * prompting (shadcn-CLI-style) for whatever's missing when stdin/stdout are a TTY. One workspaces
+ * choice applies to every kind picked this run, matching how `variants` is already a single
+ * cross-cutting concept rather than per-combo.
+ */
+async function resolvePlan(registry: Registry, flags: Record<string, string | true>): Promise<Array<{ comboName: string; combo: ComboEntry; variant: string }> | null> {
+  const flagKinds = flagList(flags.kind) as Kind[] | undefined;
+  const flagFrameworks = flagList(flags.framework);
+  const interactive = isTTY();
+
+  let kinds: Kind[];
+  if (flagKinds?.length) {
+    kinds = flagKinds;
+  } else if (interactive) {
+    const picked = await ask<Kind[]>({
+      type: "multiselect",
+      name: "kinds",
+      message: "What would you like to generate?",
+      choices: (Object.keys(KIND_LABELS) as Kind[]).map((value) => ({ title: KIND_LABELS[value], value })),
+      min: 1,
+      instructions: false,
+    });
+    if (!picked || picked.length === 0) {
+      console.log("Cancelled.");
+      return null;
+    }
+    kinds = picked;
+  } else {
+    console.error("Non-interactive session: pass --kind api,admin,mobile (comma-separated), or a specific combo name (simple-auth-kit add <combo>).");
+    return null;
+  }
+
+  if (interactive) {
+    console.log("\nAvailable templates:");
+    for (const kind of kinds) {
+      const names = combosByKind(registry, kind).map(([name]) => name);
+      console.log(`  ${KIND_LABELS[kind]}: ${names.join(", ")}`);
+    }
+    console.log("");
+  }
+
+  const picks: Array<{ comboName: string; combo: ComboEntry }> = [];
+  for (let i = 0; i < kinds.length; i++) {
+    const kind = kinds[i];
+    const available = combosByKind(registry, kind);
+    if (!available.length) {
+      console.error(`No combos registered for kind "${kind}".`);
+      return null;
+    }
+
+    let comboName = flagFrameworks?.[i];
+    if (comboName && !available.some(([name]) => name === comboName)) {
+      const match = available.find(([name]) => name === comboName || name.endsWith(`-${comboName}`));
+      comboName = match?.[0];
+    }
+
+    if (!comboName) {
+      if (available.length === 1) {
+        comboName = available[0][0];
+      } else if (interactive) {
+        const picked = await ask<string>({
+          type: "select",
+          name: "comboName",
+          message: `Which ${KIND_FRAMEWORK_NOUN[kind]}?`,
+          choices: available.map(([name]) => ({ title: name, value: name })),
+        });
+        if (!picked) {
+          console.log("Cancelled.");
+          return null;
+        }
+        comboName = picked;
+      } else {
+        console.error(`Multiple "${kind}" combos available (${available.map(([name]) => name).join(", ")}) — pass --framework to disambiguate.`);
+        return null;
+      }
+    }
+
+    const combo = registry.combos[comboName];
+    if (!combo) {
+      console.error(`Unknown combo "${comboName}".`);
+      return null;
+    }
+    picks.push({ comboName, combo });
+  }
+
+  let wantsWorkspaces: boolean;
+  const requestedVariantFlag = flagString(flags.variant);
+  if (flags.workspaces === true || requestedVariantFlag === "workspaces") {
+    wantsWorkspaces = true;
+  } else if (requestedVariantFlag === "base") {
+    wantsWorkspaces = false;
+  } else if (interactive) {
+    const picked = await ask<boolean>({ type: "confirm", name: "workspaces", message: "Include workspaces support?", initial: false });
+    if (picked === null) {
+      console.log("Cancelled.");
+      return null;
+    }
+    wantsWorkspaces = picked;
+  } else {
+    wantsWorkspaces = false;
+  }
+
+  const selections: Array<{ comboName: string; combo: ComboEntry; variant: string }> = [];
+  for (const pick of picks) {
+    const variant = resolveVariant(pick.combo, pick.comboName, wantsWorkspaces ? "workspaces" : DEFAULT_VARIANT);
+    if (!variant) return null;
+    selections.push({ ...pick, variant });
+  }
+  return selections;
+}
+
+async function cmdCreate(targetRoot: string, flags: Record<string, string | true>) {
+  const registry = await loadRegistry();
+  const selections = await resolvePlan(registry, flags);
+  if (!selections) {
+    process.exitCode = 1;
+    return;
+  }
+  // Two "merge" combos both target <targetRoot>/<installPath> by design (that's how a backend
+  // fragment composes into a host project) — but two "scaffold" combos both writing whole
+  // standalone apps (their own package.json, src/App.tsx, ...) into the *same* directory would
+  // collide outright, and worse, each install's prune step would see the other's files as no
+  // longer part of *its* install and delete them. So whenever more than one kind was picked in
+  // this run, each gets its own <targetRoot>/<comboName> subdirectory — predictable, and safe
+  // regardless of which mix of merge/scaffold combos ended up selected.
+  const namespaced = selections.length > 1;
+  for (const { comboName, combo, variant } of selections) {
+    const installRoot = namespaced ? join(targetRoot, comboName) : targetRoot;
+    if (namespaced) await mkdir(installRoot, { recursive: true });
+    // An explicit --name applies to every selection uniformly — fine for merge-mode combos
+    // (they don't have their own package.json identity), but two scaffold apps both literally
+    // named e.g. "combo-test" would collide if anything ever treats them as sibling packages
+    // (a pnpm/npm workspace, for one). Suffix with the combo name once there's more than one.
+    const installFlags = namespaced && flagString(flags.name) ? { ...flags, name: `${flagString(flags.name)}-${comboName}` } : flags;
+    await installCombo(comboName, combo, variant, registry, installRoot, installFlags);
+  }
+}
+
+/**
+ * Re-installs whatever combo+variant this project already has, read straight from
+ * auth.lock.json — no need to remember or re-type what you originally ran `add` with. Defaults
+ * to the safe (non-`--force`) merge: anything you haven't touched updates automatically, and
+ * anything you have is left alone and reported, exactly like a first install. Pass `--force`
+ * yourself if you really do want to overwrite local edits.
+ */
+async function cmdUpdate(targetRoot: string, flags: Record<string, string | true>) {
+  const lock = await loadLock(targetRoot);
+  if (!lock.combo || !lock.variant) {
+    console.error(`No auth.lock.json (or it's missing combo/variant) in ${targetRoot} — nothing to update. Use "add <combo>" for a first install.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const registry = await loadRegistry();
+  const combo = registry.combos[lock.combo];
+  if (!combo) {
+    console.error(`auth.lock.json names combo "${lock.combo}", which no longer exists in this registry.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const variant = resolveVariant(combo, lock.combo, lock.variant);
+  if (!variant) {
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.check === true && comboInstallMode(combo) === "scaffold") {
+    console.error(`--check isn't supported for "${lock.combo}" (a scaffold-mode combo) — only merge-mode (api) combos support a dry run.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`Updating "${lock.combo}" (${variant} variant) in ${targetRoot}${flags.force === true ? " — --force: local edits will be overwritten" : ""}`);
+  await installCombo(lock.combo, combo, variant, registry, targetRoot, flags);
+}
+
+async function cmdDiff(targetRoot: string) {
+  const lock = await loadLock(targetRoot);
+  if (!lock.files) {
+    console.error(`No auth.lock.json found in ${targetRoot} — nothing installed yet.`);
+    return;
+  }
+  console.log(`diff is not implemented yet (deferred until there's more than one install to maintain) — installed files:`);
+  console.log(`  combo: ${lock.combo}, variant: ${lock.variant ?? DEFAULT_VARIANT}`);
+  for (const file of Object.keys(lock.files)) console.log(`  ${file}`);
+}
+
+async function main() {
+  const { command, positional, flags } = parseArgs(process.argv.slice(2));
+  const targetRoot = resolve(process.cwd(), flagString(flags.into) ?? ".");
+
+  switch (command) {
+    case "init":
+      await cmdInit(targetRoot, flags);
+      break;
+    case "add": {
+      const comboName = positional[0];
+      if (!comboName) {
+        // No combo named — guided multi-kind flow (interactive, or --kind/--framework/--workspaces).
+        await cmdCreate(targetRoot, flags);
+        break;
+      }
+      await cmdAdd(comboName, targetRoot, flags);
+      break;
+    }
+    case "update":
+      await cmdUpdate(targetRoot, flags);
+      break;
+    case "diff":
+      await cmdDiff(targetRoot);
+      break;
+    default: {
+      const registry = await loadRegistry();
+      console.log("Usage: simple-auth-kit <init|add|update|diff> [...]");
+      console.log(`  init [--config-only] [--kind ...] [--into <path>]  (fresh setup: guided "what do you need" picker, like bare "add")`);
+      console.log(`      --config-only: just write .simple-auth-kit.json and stop, no install`);
+      console.log(`  add <combo> [--workspaces] [--force] [--into <path>] [--path <dir>] [--alias <alias>]`);
+      console.log(`  add [--kind api,admin,mobile] [--framework <name>,...] [--workspaces] [--into <path>] [--name <appName>]`);
+      console.log(`      (bare "add", or "add" with --kind but no combo, launches a guided prompt for whatever's missing)`);
+      console.log(`  update [--check] [--force] [--into <path>]  (re-installs whatever combo+variant auth.lock.json already records)`);
+      console.log(`      --check: report what would change, without writing anything (merge-mode combos only)`);
+      console.log(`  In a TTY, without --force or --check: a file changed locally since install prompts to overwrite, per file.`);
+      console.log(`\nAvailable combos:`);
+      for (const kind of ["api", "admin", "mobile"] as Kind[]) {
+        const names = combosByKind(registry, kind).map(([name]) => name);
+        if (names.length) console.log(`  ${KIND_LABELS[kind]}: ${names.join(", ")}`);
+      }
+      console.log(`\nVariants (choose one at install time):`);
+      for (const [name, variant] of Object.entries(registry.variants)) {
+        console.log(`  ${name}${variant.flag ? ` (${variant.flag})` : " (default)"} — ${variant.description}`);
+      }
+      process.exitCode = command ? 1 : 0;
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});