@simple-auth-kit/cli 1.1.0 → 1.3.0

package/README.md

@@ -22,7 +22,8 @@ npx @simple-auth-kit/cli add <combo> [--workspaces]  # install a specific combo
 npx @simple-auth-kit/cli add                         # guided picker, same flow as init (no config write)
 npx @simple-auth-kit/cli update [--check]             # re-installs whatever add last recorded — no args needed
 npx @simple-auth-kit/cli diff                         # shows the actual content diff for every file that differs from the registry (api combos only)
-npx @simple-auth-kit/cli                              # full command/flag reference + available combos
+npx @simple-auth-kit/cli                              # bare, in a real terminal: same guided picker as `add`
+npx @simple-auth-kit/cli --help                       # full command/flag reference + available combos
 ```
 
 `--into <path>` targets any directory (defaults to the current one). In a real terminal,
@@ -30,20 +31,40 @@ without `--force` or `--check`, a file that's changed locally since install prom
 per file — before it's overwritten; outside a TTY (CI/scripts) it's left alone by default and
 reported at the end, same as `--force` always applying and `--check` never writing anything.
 
-**Dependencies are installed for you**, shadcn-`add`-style — no separate `npm install` step.
-The package manager is auto-detected from a lockfile already in the target directory (npm if
-none found); override it with `--pm <npm|pnpm|yarn|bun>`, or skip the install entirely with
-`--skip-install` if you'd rather review `package.json` first.
+**Dependencies are installed for you**, shadcn-`add`-style — no separate `npm install` step, and
+version-pinned to match what each combo is actually built and tested against (not just bare
+package names left to resolve to "latest"). The package manager is auto-detected from a lockfile
+already in the target directory; with no lockfile to go on (a brand new directory, most
+commonly) a real terminal is asked which one to use. Override either with
+`--pm <npm|pnpm|yarn|bun>`, or skip the install entirely with `--skip-install` if you'd rather
+review `package.json` first.
 
 ## Available combos
 
-| Kind | Combo | Installs as |
-|---|---|---|
-| `api` | `nestjs-prisma`, `nestjs-drizzle`, `express-prisma`, `express-drizzle` | merged into `src/lib/auth` of an existing project (the Prisma/Drizzle config + schema land at the project root instead — see below) |
-| `admin` | `admin-nextjs`, `admin-react` | a whole new standalone app, scaffolded at the target (refuses a non-empty target unless `--force`) |
-| `mobile` | `mobile-expo`, `mobile-bare-rn` | a whole new standalone app, scaffolded at the target (same non-empty-target rule) |
+Add `--workspaces` to any of these for the workspaces variant.
 
-Add `--workspaces` to any `api`/`admin`/`mobile` combo for the workspaces variant.
+**`api`** — merged into `src/lib/auth` of an existing project (the Prisma/Drizzle config +
+schema land at the project root instead — see below):
+```bash
+npx @simple-auth-kit/cli add nestjs-prisma --into .
+npx @simple-auth-kit/cli add nestjs-drizzle --into .
+npx @simple-auth-kit/cli add express-prisma --into .
+npx @simple-auth-kit/cli add express-drizzle --into .
+```
+
+**`admin`** — a whole new standalone app, scaffolded at the target (refuses a non-empty target
+unless `--force`):
+```bash
+npx @simple-auth-kit/cli add admin-nextjs --into ./admin
+npx @simple-auth-kit/cli add admin-react --into ./admin
+```
+
+**`mobile`** — a whole new standalone app, scaffolded at the target (same non-empty-target
+rule):
+```bash
+npx @simple-auth-kit/cli add mobile-expo --into ./mobile
+npx @simple-auth-kit/cli add mobile-bare-rn --into ./mobile
+```
 
 ## Your own database models are safe
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-auth-kit/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "license": "MIT",
   "description": "simple-auth-kit add <combo> — copies registry source (backend combos, admin consoles, mobile apps) into a consumer repo, shadcn-CLI-style. Nothing is ever installed as a runtime dependency of the consumer.",
   "bin": {

package/registry.json

@@ -2,8 +2,8 @@
   "core": {
     "dir": "core",
     "peerDependencies": [
-      "argon2",
-      "jose"
+      "argon2@^0.45.1",
+      "jose@^6.2.8"
     ]
   },
   "variants": {
@@ -26,18 +26,18 @@
         "workspaces"
       ],
       "peerDependencies": [
-        "@nestjs/common",
-        "@nestjs/core",
-        "@nestjs/platform-express",
-        "@nestjs/swagger",
-        "@nestjs/throttler",
-        "reflect-metadata",
-        "rxjs",
-        "express",
-        "@prisma/client",
-        "@prisma/adapter-pg",
-        "prisma",
-        "@casl/ability"
+        "@nestjs/common@^11.1.28",
+        "@nestjs/core@^11.1.28",
+        "@nestjs/platform-express@^11.1.28",
+        "@nestjs/swagger@^11.4.6",
+        "@nestjs/throttler@^6.5.0",
+        "reflect-metadata@^0.2.2",
+        "rxjs@^7.8.2",
+        "express@^5.2.1",
+        "@prisma/client@^7.9.1",
+        "@prisma/adapter-pg@^7.9.1",
+        "prisma@^7.9.1",
+        "@casl/ability@^7.0.1"
       ],
       "postInstall": [
         "Set DATABASE_URL in .env (see .env.example)",
@@ -66,17 +66,17 @@
         "workspaces"
       ],
       "peerDependencies": [
-        "@nestjs/common",
-        "@nestjs/core",
-        "@nestjs/platform-express",
-        "@nestjs/swagger",
-        "reflect-metadata",
-        "rxjs",
-        "express",
-        "drizzle-orm",
-        "pg",
-        "drizzle-kit",
-        "@casl/ability"
+        "@nestjs/common@^11.1.28",
+        "@nestjs/core@^11.1.28",
+        "@nestjs/platform-express@^11.1.28",
+        "@nestjs/swagger@^11.4.6",
+        "reflect-metadata@^0.2.2",
+        "rxjs@^7.8.2",
+        "express@^5.2.1",
+        "drizzle-orm@^0.45.2",
+        "pg@^8.23.0",
+        "drizzle-kit@^0.31.10",
+        "@casl/ability@^7.0.1"
       ],
       "postInstall": [
         "Set DATABASE_URL in .env (see .env.example)",
@@ -104,12 +104,12 @@
         "workspaces"
       ],
       "peerDependencies": [
-        "express",
-        "@prisma/client",
-        "@prisma/adapter-pg",
-        "prisma",
-        "swagger-ui-express",
-        "@casl/ability"
+        "express@^5.2.1",
+        "@prisma/client@^7.9.1",
+        "@prisma/adapter-pg@^7.9.1",
+        "prisma@^7.9.1",
+        "swagger-ui-express@^5.0.1",
+        "@casl/ability@^7.0.1"
       ],
       "postInstall": [
         "Set DATABASE_URL in .env (see .env.example)",
@@ -138,12 +138,12 @@
         "workspaces"
       ],
       "peerDependencies": [
-        "express",
-        "drizzle-orm",
-        "pg",
-        "drizzle-kit",
-        "swagger-ui-express",
-        "@casl/ability"
+        "express@^5.2.1",
+        "drizzle-orm@^0.45.2",
+        "pg@^8.23.0",
+        "drizzle-kit@^0.31.10",
+        "swagger-ui-express@^5.0.1",
+        "@casl/ability@^7.0.1"
       ],
       "postInstall": [
         "Set DATABASE_URL in .env (see .env.example)",

package/simple-auth-kit.ts

@@ -43,7 +43,7 @@ const KIND_LABELS: Record<Kind, string> = { api: "API (backend)", admin: "Admin
 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", "skip-install"]);
+const BOOLEAN_FLAGS = new Set(["workspaces", "force", "check", "config-only", "skip-install", "help"]);
 
 interface SimpleAuthKitConfig {
   path: string;
@@ -183,18 +183,41 @@ async function resolveForcePaths(runDry: () => Promise<{ result: CopyResult }>,
 const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
 type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 
-/** Detected from whichever lockfile is already sitting in targetRoot — npm if none match,
- * matching what a fresh `npm install`-first project would have. Overridden by `--pm` when
- * given, so e.g. a first-ever install (no lockfile yet to detect from) can still pick pnpm. */
-function detectPackageManager(targetRoot: string, flags: Record<string, string | true>): PackageManager {
+/** Detected from whichever lockfile is already sitting in targetRoot — unambiguous, so used
+ * without asking. Returns null when nothing on disk says which tool to use and `--pm` wasn't
+ * given either, leaving it to the caller to ask (interactive) or default (non-interactive). */
+function detectPackageManagerFromLockfile(targetRoot: string): PackageManager | null {
+  if (existsSync(join(targetRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(targetRoot, "yarn.lock"))) return "yarn";
+  if (existsSync(join(targetRoot, "bun.lockb")) || existsSync(join(targetRoot, "bun.lock"))) return "bun";
+  if (existsSync(join(targetRoot, "package-lock.json"))) return "npm";
+  return null;
+}
+
+/** `--pm` wins outright. Otherwise: a lockfile already in targetRoot is unambiguous, so it's used
+ * silently. Only when neither says anything — most commonly a scaffold install into an empty
+ * directory — and this is a real terminal do we ask; a non-interactive run in that same situation
+ * still falls back to npm rather than blocking. */
+async function resolvePackageManager(targetRoot: string, flags: Record<string, string | true>): Promise<PackageManager> {
   const requested = flagString(flags.pm);
   if (requested) {
     if ((PACKAGE_MANAGERS as readonly string[]).includes(requested)) return requested as PackageManager;
     console.error(`--pm "${requested}" isn't one of ${PACKAGE_MANAGERS.join(", ")} — falling back to auto-detection.`);
   }
-  if (existsSync(join(targetRoot, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(join(targetRoot, "yarn.lock"))) return "yarn";
-  if (existsSync(join(targetRoot, "bun.lockb")) || existsSync(join(targetRoot, "bun.lock"))) return "bun";
+
+  const detected = detectPackageManagerFromLockfile(targetRoot);
+  if (detected) return detected;
+
+  if (isTTY()) {
+    const picked = await ask<PackageManager>({
+      type: "select",
+      name: "pm",
+      message: "Which package manager?",
+      choices: PACKAGE_MANAGERS.map((value) => ({ title: value, value })),
+      initial: 0,
+    });
+    if (picked) return picked;
+  }
   return "npm";
 }
 
@@ -204,12 +227,12 @@ function detectPackageManager(targetRoot: string, flags: Record<string, string |
  * package.json" (the scaffold-mode case — dependencies are already declared, nothing to name).
  * Skipped entirely under `--skip-install`, or when `deps` is non-empty but there's nothing new
  * to add (an update that touched no files has nothing worth re-installing for). `--pm
- * <npm|pnpm|yarn|bun>` picks the tool explicitly instead of auto-detecting it from a lockfile.
+ * <npm|pnpm|yarn|bun>` picks the tool explicitly instead of auto-detecting/asking.
  */
-function installDependencies(targetRoot: string, deps: string[], flags: Record<string, string | true>): void {
+async function installDependencies(targetRoot: string, deps: string[], flags: Record<string, string | true>): Promise<void> {
   if (flags["skip-install"] === true) return;
 
-  const pm = detectPackageManager(targetRoot, flags);
+  const pm = await resolvePackageManager(targetRoot, flags);
   // "install everything in package.json" (zero deps named) is the same bare verb across all
   // four; naming specific packages is "install <pkgs>" for npm, "add <pkgs>" for the others.
   const args = deps.length ? [pm === "npm" ? "install" : "add", ...deps] : ["install"];
@@ -435,7 +458,7 @@ async function installMerge(comboName: string, combo: ComboEntry, variant: strin
   const peerDeps = [...new Set([...registry.core.peerDependencies, ...combo.peerDependencies])];
   console.log(`\nPeer dependencies: ${peerDeps.join(" ")}`);
   if (result.updated.length) {
-    installDependencies(targetRoot, peerDeps, flags);
+    await installDependencies(targetRoot, peerDeps, flags);
   } else if (flags["skip-install"] !== true) {
     console.log(`(nothing changed this run — skipping install)`);
   }
@@ -507,7 +530,7 @@ async function installScaffold(comboName: string, combo: ComboEntry, variant: st
   if (result.updated.length) {
     // Dependencies are already declared in package.json — no specific packages to name, just
     // "install whatever's there" (installDependencies with an empty list does exactly that).
-    installDependencies(targetRoot, [], flags);
+    await installDependencies(targetRoot, [], flags);
   } else if (flags["skip-install"] !== true) {
     console.log(`\n(nothing changed this run — skipping install)`);
   }
@@ -785,10 +808,47 @@ async function cmdDiff(targetRoot: string) {
   }
 }
 
+async function printUsage(exitCode: number) {
+  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] [--skip-install] [--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] [--skip-install] [--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(`  diff [--into <path>]  (shows the actual content diff for every tracked file that differs from the current registry — read-only; 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(`  --skip-install: don't run the package manager after copying files — the default is to install for you, shadcn-\`add\`-style.`);
+  console.log(`  --pm <npm|pnpm|yarn|bun>: which package manager to install with — default: detected from a lockfile in the target directory, npm if none found.`);
+  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 = exitCode;
+}
+
 async function main() {
   const { command, positional, flags } = parseArgs(process.argv.slice(2));
   const targetRoot = resolve(process.cwd(), flagString(flags.into) ?? ".");
 
+  if (command === "--help" || command === "-h" || command === "help" || flags.help === true) {
+    await printUsage(0);
+    return;
+  }
+  if (!command && isTTY()) {
+    // Bare `npx @simple-auth-kit/cli` in a real terminal — go straight to the guided picker
+    // (same flow as `add` with no combo) instead of just printing help text.
+    await cmdCreate(targetRoot, flags);
+    return;
+  }
+
   switch (command) {
     case "init":
       await cmdInit(targetRoot, flags);
@@ -809,31 +869,8 @@ async function main() {
     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] [--skip-install] [--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] [--skip-install] [--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(`  diff [--into <path>]  (shows the actual content diff for every tracked file that differs from the current registry — read-only; 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(`  --skip-install: don't run the package manager after copying files — the default is to install for you, shadcn-\`add\`-style.`);
-      console.log(`  --pm <npm|pnpm|yarn|bun>: which package manager to install with — default: detected from a lockfile in the target directory, npm if none found.`);
-      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;
-    }
+    default:
+      await printUsage(command ? 1 : 0);
   }
 }