@simple-auth-kit/cli 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# @simple-auth-kit/cli
+
+The CLI for [simple-auth-kit](https://github.com/shahriar-ratul/simple-auth-kit) — a
+shadcn/ui-style auth library. It copies source (backend combos, admin consoles, mobile apps)
+into your own project; nothing is ever installed as a runtime dependency of your app.
+
+## Install
+
+Nothing to install — use it directly with `npx`:
+
+```bash
+npx @simple-auth-kit/cli add nestjs-prisma --into .
+```
+
+Package: https://www.npmjs.com/package/@simple-auth-kit/cli
+
+## Commands
+
+```bash
+npx @simple-auth-kit/cli init                       # fresh setup: guided "what do you need" picker
+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                              # full command/flag reference + available combos
+```
+
+`--into <path>` targets any directory (defaults to the current one). In a real terminal,
+without `--force` or `--check`, a file that's changed locally since install prompts you —
+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.
+
+## 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 `api`/`admin`/`mobile` combo for the workspaces variant.
+
+## Your own database models are safe
+
+The Prisma combos install `prisma.config.ts` + `prisma/` at your project root, using Prisma's
+own multi-file schema support: the CLI's own models live in
+`prisma/schema/simple-auth-kit.prisma`, and Prisma automatically merges every other `.prisma`
+file you add alongside it. Add your own models in a sibling file (e.g.
+`prisma/schema/app.prisma`) — the CLI only ever tracks its own file by exact name, so `update`
+never touches yours, `--force` included.
+
+The Drizzle combos work the same way at a smaller scale: `drizzle.config.ts`'s `schema` field
+is `[schema.ts, *.schema.ts]` — add your own tables in a sibling `*.schema.ts` file (e.g.
+`billing.schema.ts`, next to the CLI-managed `schema.ts`) and `drizzle-kit` picks it up
+automatically, with no edits to `drizzle.config.ts` itself.
+
+## Clone the source
+
+This is a **standalone copy**, published from the monorepo, with the registry it installs
+from bundled in. To pull just this package's source without cloning the whole repo:
+
+```bash
+npx degit shahriar-ratul/simple-auth-kit/packages/cli cli
+```
+
+(Note: unlike a plain `npm install`, this clone won't have `registry/` bundled in — that
+folder is generated fresh from the monorepo's own `registry/` right before every publish. Run
+against the monorepo checkout instead if you need the registry alongside the CLI source — see
+Development below.)
+
+## Development
+
+Run directly against this monorepo's own `registry/` (no publish/bundle step needed — see
+`simple-auth-kit.ts`'s `REGISTRY_ROOT` resolution):
+
+```bash
+cd packages/cli
+npm run typecheck
+npx tsx simple-auth-kit.ts add <combo> --into ../../examples/<app>
+```
+
+`npm run prepack` (or a real `npm publish`/`npm pack`) bundles a fresh copy of the repo's
+`registry/` into `registry/` here first — that's what makes the published package
+self-contained. See `scripts/bundle-registry.mjs`.
+
+## Source
+
+Full source, every backend combo, and every consuming app:
+[simple-auth-kit](https://github.com/shahriar-ratul/simple-auth-kit).

package/bin/simple-auth-kit.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Thin launcher so `npm link` (run once, inside cli/) makes `simple-auth-kit` a real global command —
+// matching shadcn's `npx shadcn add <component>` ergonomics: run it from inside any consumer
+// project, no `cd` into this repo, no `--into` needed (it already defaults to cwd). Spawns the
+// local tsx binary by absolute path so this works regardless of the caller's cwd or global PATH.
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const tsxBin = join(here, "..", "node_modules", ".bin", "tsx");
+const entry = join(here, "..", "simple-auth-kit.ts");
+
+const result = spawnSync(tsxBin, [entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+process.exit(result.status ?? 1);

package/lib/copy.ts

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+// Never copied out of the registry: build output, the registry's own package/tsconfig wiring,
+// and the per-variant test harness. A consumer gets source, not this repo's scaffolding.
+export const NEVER_COPY = new Set(["node_modules", "dist", "generated", "test", "scripts", ".variant", "package.json", "tsconfig.json", ".env"]);
+
+// For "scaffold" installs (admin/mobile apps materialized as whole standalone projects, not
+// merged into an existing one): package.json/tsconfig.json are real, consumer-facing content
+// here, not the registry's own dev wiring, so they're copied like any other file.
+export const SCAFFOLD_NEVER_COPY = new Set(["node_modules", "dist", "generated", "test", "scripts", ".variant", ".env"]);
+
+export interface CopyOptions {
+  /**
+   * Rewrites this literal string to `aliasTo` inside every copied `.ts`/`.tsx` file — used to
+   * retarget the core package's placeholder import alias to the consumer's configured one. Omit
+   * both for installs (e.g. scaffold-mode admin/mobile apps) that have no such alias to rewrite.
+   */
+  aliasFrom?: string;
+  aliasTo?: string;
+  /**
+   * Additional literal-string replacements applied to every copied `.ts`/`.tsx` file, alongside
+   * the alias rewrite above. Used by the ORM combos: `prisma`/`drizzle`'s config+data folder
+   * relocates to the project root on a real install, so the generated client's import path
+   * inside every copied source file has to change to match (see `installMerge` in
+   * `cli/simple-auth-kit.ts`) — the registry source itself keeps the path that's correct for its
+   * own dev/typecheck loop, where nothing has moved.
+   */
+  extraRewrites?: { from: string; to: string }[];
+  /**
+   * The previous install's sha256-by-path manifest. A destination file whose current content
+   * no longer matches what was recorded is a file the user edited, and is left alone.
+   */
+  previous?: Record<string, string>;
+  /** Overwrite user-modified files anyway. */
+  force?: boolean;
+  /** Paths (relative to destRoot, same form as `previous`'s keys) to overwrite even though
+   * they're locally modified — a per-file version of `force`, for when only some conflicts were
+   * approved (e.g. via an interactive per-file prompt) rather than all of them. */
+  forcePaths?: Set<string>;
+  /** Paths (relative to destRoot, POSIX separators) this install must not write or delete. */
+  ignore?: string[];
+  /** Overrides the default skip-by-name set (see NEVER_COPY / SCAFFOLD_NEVER_COPY). */
+  neverCopy?: Set<string>;
+  /**
+   * Compute everything (manifest, skipped/ignored/updated classification) without writing or
+   * deleting anything on disk — for a "what would change" check before actually applying it.
+   */
+  dryRun?: boolean;
+}
+
+export interface CopyResult {
+  /** sha256 by path relative to destRoot, for every file this install now owns. */
+  manifest: Record<string, string>;
+  /** Files left alone because the user had edited them. */
+  skipped: string[];
+  /** Files left alone because they are on the ignore list. */
+  ignored: string[];
+  /** Files that are new or whose content differs from what's currently on disk — written (or,
+   * under `dryRun`, would be written) this run. Anything not in skipped/ignored/updated was
+   * already byte-identical to what's being installed — genuinely nothing to do for it. */
+  updated: string[];
+}
+
+export const sha256 = (content: string) => createHash("sha256").update(content).digest("hex");
+export const toPosix = (path: string) => path.split(sep).join("/");
+
+async function readIfExists(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export async function copyOneFile(srcPath: string, destPath: string, destRoot: string, opts: CopyOptions, result: CopyResult): Promise<void> {
+  const rel = toPosix(relative(destRoot, destPath));
+
+  if (opts.ignore?.includes(rel)) {
+    result.ignored.push(rel);
+    const existing = await readIfExists(destPath);
+    if (existing !== null) result.manifest[rel] = sha256(existing);
+    return;
+  }
+
+  let content = await readFile(srcPath, "utf8");
+  if (destPath.endsWith(".ts") || destPath.endsWith(".tsx")) {
+    if (opts.aliasFrom && opts.aliasTo !== undefined) {
+      content = content.split(opts.aliasFrom).join(opts.aliasTo);
+    }
+    for (const { from, to } of opts.extraRewrites ?? []) {
+      content = content.split(from).join(to);
+    }
+  }
+
+  const existing = await readIfExists(destPath);
+  const recorded = opts.previous?.[rel];
+  const forced = opts.force || opts.forcePaths?.has(rel);
+  if (!forced && existing !== null && recorded !== undefined && sha256(existing) !== recorded) {
+    result.skipped.push(rel);
+    result.manifest[rel] = sha256(existing);
+    return;
+  }
+
+  const newHash = sha256(content);
+  if (existing !== null && sha256(existing) === newHash) {
+    result.manifest[rel] = newHash; // already byte-identical — nothing to do
+    return;
+  }
+
+  result.updated.push(rel);
+  result.manifest[rel] = newHash;
+  if (opts.dryRun) return;
+
+  await mkdir(dirname(destPath), { recursive: true });
+  await writeFile(destPath, content, "utf8");
+}
+
+/** Recursively copies srcDir into destDir, rewriting the placeholder core import alias in .ts files. */
+export async function copyDir(srcDir: string, destDir: string, opts: CopyOptions, destRoot: string = destDir, result?: CopyResult): Promise<CopyResult> {
+  const acc: CopyResult = result ?? { manifest: {}, skipped: [], ignored: [], updated: [] };
+  const skipNames = opts.neverCopy ?? NEVER_COPY;
+  const entries = await readdir(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (skipNames.has(entry.name)) continue;
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, opts, destRoot, acc);
+    } else {
+      await copyOneFile(srcPath, destPath, destRoot, opts, acc);
+    }
+  }
+
+  return acc;
+}
+
+/**
+ * Removes the directory a pruned file lived in once it is empty, and keeps walking up. Leaving
+ * the husk behind is not cosmetic: an empty `prisma/migrations/<name>/` is a migration with no
+ * SQL, which the migration tooling rejects.
+ */
+async function removeEmptyParents(dir: string, stopAt: string): Promise<void> {
+  const root = resolve(stopAt);
+  let current = resolve(dir);
+  while (current.startsWith(root) && current !== root) {
+    try {
+      await rmdir(current); // fails, harmlessly, as soon as a directory still has contents
+    } catch {
+      return;
+    }
+    current = dirname(current);
+  }
+}
+
+/**
+ * Removes files the previous install owned that this one does not — what makes switching
+ * variants clean rather than additive, so the emitted project never carries the other variant's
+ * leftovers. A file the user has edited since it was installed is kept and reported instead.
+ */
+export async function pruneRemovedFiles(
+  destRoot: string,
+  previous: Record<string, string>,
+  result: CopyResult,
+  opts: { force?: boolean; ignore?: string[]; dryRun?: boolean } = {},
+): Promise<{ removed: string[]; keptModified: string[] }> {
+  const removed: string[] = [];
+  const keptModified: string[] = [];
+
+  for (const [rel, recorded] of Object.entries(previous)) {
+    if (rel in result.manifest || opts.ignore?.includes(rel)) continue;
+
+    const existing = await readIfExists(join(destRoot, rel));
+    if (existing === null) continue;
+    if (!opts.force && sha256(existing) !== recorded) {
+      keptModified.push(rel);
+      continue;
+    }
+    if (!opts.dryRun) {
+      await rm(join(destRoot, rel), { force: true });
+      await removeEmptyParents(dirname(join(destRoot, rel)), destRoot);
+    }
+    removed.push(rel);
+  }
+
+  return { removed, keptModified };
+}

package/lib/rename-native.ts

@@ -0,0 +1,173 @@
+import { readdir, readFile, mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname, extname, join, relative } from "node:path";
+import { sha256 } from "./copy.js";
+
+export interface NativeIdentity {
+  /** PascalCase app name baked into the native scaffolding, e.g. "MobileBareRn". */
+  name: string;
+  /** Reverse-DNS package/bundle id, e.g. "com.mobilebarern". */
+  package: string;
+}
+
+// Anything under android/ or ios/ with one of these extensions is binary — left untouched by
+// the text-content replace pass. Everything else (including extensionless files like Podfile
+// and .xcode.env) is read as text.
+const BINARY_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".keystore", ".jar", ".zip", ".ttf", ".otf", ".icns", ".car"]);
+
+export function toPascalCase(input: string): string {
+  return input
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((seg) => seg[0].toUpperCase() + seg.slice(1))
+    .join("");
+}
+
+export const derivePackage = (pascalName: string): string => `com.${pascalName.toLowerCase()}`;
+
+async function walkFilesIfExists(dir: string): Promise<string[]> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await walkFilesIfExists(full)));
+    else out.push(full);
+  }
+  return out;
+}
+
+async function renameIfExists(from: string, to: string): Promise<boolean> {
+  try {
+    await rename(from, to);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    return false;
+  }
+}
+
+/** Renames every file/directory anywhere under `dir` whose name is exactly `oldName` or starts
+ * with `oldName.` (e.g. `MobileBareRn.xcodeproj`, `MobileBareRn.xcscheme`, or the bare
+ * `MobileBareRn` source folder) — bottom-up, so a renamed parent doesn't strand its children's
+ * still-pending renames. Returns every (oldPath, newPath) pair actually renamed, absolute. */
+async function renameMatchingEntries(dir: string, oldName: string, newName: string): Promise<Array<[string, string]>> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const renamed: Array<[string, string]> = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      renamed.push(...(await renameMatchingEntries(full, oldName, newName)));
+    }
+    if (entry.name === oldName || entry.name.startsWith(`${oldName}.`)) {
+      const newFull = join(dir, newName + entry.name.slice(oldName.length));
+      if (await renameIfExists(full, newFull)) renamed.push([full, newFull]);
+    }
+  }
+  return renamed;
+}
+
+/** Replaces oldName/oldPackage with newName/newPackage in a text file's content. Returns the
+ * new sha256 if the file was text and its content actually changed, else null (binary, missing,
+ * or unchanged — nothing for the caller to update in a hash manifest). */
+async function replaceInFile(path: string, oldName: string, newName: string, oldPackage: string, newPackage: string): Promise<string | null> {
+  if (BINARY_EXTENSIONS.has(extname(path).toLowerCase())) return null;
+  let content: string;
+  try {
+    content = await readFile(path, "utf8");
+  } catch {
+    return null; // gone (e.g. inside a dir renamed out from under this listing) — not an error
+  }
+  const replaced = content.split(oldName).join(newName).split(oldPackage).join(newPackage);
+  if (replaced === content) return null;
+  await writeFile(path, replaced, "utf8");
+  return sha256(replaced);
+}
+
+export interface RenameResult {
+  /** [oldRelPath, newRelPath] (relative to targetRoot, POSIX) for every path that moved. */
+  movedPaths: Array<[string, string]>;
+  /** relPath (post-move, POSIX) -> new sha256, for every text file whose content changed. */
+  contentHashUpdates: Record<string, string>;
+}
+
+/**
+ * Re-templates a bare React Native app's baked-in native identity — Android
+ * applicationId/package folder, iOS Xcode project/scheme/bundle id — from the registry's
+ * placeholder values to a consumer-chosen name. Without this, every app the CLI generates
+ * from this combo would collide on the same applicationId/bundle id (the registry's source
+ * apps are literally identical on this point — they're never installed side by side).
+ * Every occurrence of the old PascalCase name and old package string across every text file
+ * under android/ and ios/, plus the RN-specific app.json at the project root, is replaced —
+ * mirroring what `react-native rename` tooling does, since the alternative (surgically
+ * parsing build.gradle / a semi-structured .pbxproj) is far more fragile for no real benefit.
+ *
+ * Returns what moved and what changed so the caller (simple-auth-kit.ts) can keep auth.lock.json's
+ * manifest in sync with what's actually on disk — otherwise a future re-sync would see every
+ * renamed/rewritten native file as "removed" or "user-modified" for no real reason.
+ */
+export async function renameNative(targetRoot: string, oldIdentity: NativeIdentity, newDisplayName: string): Promise<RenameResult> {
+  const newName = toPascalCase(newDisplayName) || oldIdentity.name;
+  const newPackage = derivePackage(newName);
+  if (newName === oldIdentity.name && newPackage === oldIdentity.package) return { movedPaths: [], contentHashUpdates: {} };
+
+  const androidDir = join(targetRoot, "android");
+  const iosDir = join(targetRoot, "ios");
+  const movedAbs: Array<[string, string]> = [];
+
+  const oldPkgPath = join(androidDir, "app/src/main/java", ...oldIdentity.package.split("."));
+  const newPkgPath = join(androidDir, "app/src/main/java", ...newPackage.split("."));
+  if (oldPkgPath !== newPkgPath) {
+    await mkdir(dirname(newPkgPath), { recursive: true });
+    if (await renameIfExists(oldPkgPath, newPkgPath)) movedAbs.push([oldPkgPath, newPkgPath]);
+  }
+
+  movedAbs.push(...(await renameMatchingEntries(iosDir, oldIdentity.name, newName)));
+
+  // Content replace runs after every move, so it operates on final paths only.
+  const files = [...(await walkFilesIfExists(androidDir)), ...(await walkFilesIfExists(iosDir)), join(targetRoot, "app.json")];
+  const contentHashUpdates: Record<string, string> = {};
+  for (const file of files) {
+    const newHash = await replaceInFile(file, oldIdentity.name, newName, oldIdentity.package, newPackage);
+    if (newHash) contentHashUpdates[relative(targetRoot, file).split("\\").join("/")] = newHash;
+  }
+
+  const movedPaths: Array<[string, string]> = movedAbs.map(([from, to]) => [
+    relative(targetRoot, from).split("\\").join("/"),
+    relative(targetRoot, to).split("\\").join("/"),
+  ]);
+  return { movedPaths, contentHashUpdates };
+}
+
+/** Rewrites a manifest (relPath -> sha256) so keys under any renamed directory/file follow the
+ * move, and applies the recomputed hashes for files whose content also changed. */
+export function reconcileManifest(manifest: Record<string, string>, result: RenameResult): Record<string, string> {
+  if (result.movedPaths.length === 0 && Object.keys(result.contentHashUpdates).length === 0) return manifest;
+
+  // movedPaths is bottom-up (a nested file's own rename lands before its parent directory's
+  // rename), so a path can need more than one substitution applied in sequence — e.g. a
+  // scheme file renamed inside a still-old-named .xcodeproj, whose .xcodeproj is itself
+  // renamed one step later. Chain every applicable move against the progressively-updated
+  // path rather than stopping at the first match.
+  const next: Record<string, string> = {};
+  for (const [rel, hash] of Object.entries(manifest)) {
+    let newRel = rel;
+    for (const [oldPrefix, newPrefix] of result.movedPaths) {
+      if (newRel === oldPrefix) {
+        newRel = newPrefix;
+      } else if (newRel.startsWith(`${oldPrefix}/`)) {
+        newRel = newPrefix + newRel.slice(oldPrefix.length);
+      }
+    }
+    next[newRel] = result.contentHashUpdates[newRel] ?? hash;
+  }
+  return next;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@simple-auth-kit/cli",
+  "version": "1.0.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": {
+    "simple-auth-kit": "./bin/simple-auth-kit.mjs"
+  },
+  "type": "module",
+  "files": [
+    "simple-auth-kit.ts",
+    "lib",
+    "bin",
+    "registry.json",
+    "registry"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "cli": "tsx simple-auth-kit.ts",
+    "prepack": "node scripts/bundle-registry.mjs"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "tsx": "^4.23.11"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^7.0.2"
+  }
+}