@lunora/cli 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runCli } from './packem_shared/COMMANDS-1V_KEx35.mjs';
+import { runCli } from './packem_shared/COMMANDS-D3h9Iwvl.mjs';
 
 try {
   const code = await runCli();

package/dist/index.d.mts

@@ -64,6 +64,12 @@ declare const createLogger: () => Logger;
 * the package barrel) stays side-effect-free.
 */
 declare const pail: PailLogger;
+/**
+* Emit a badged step line through the shared pail (the `init` flow's off-TTY
+* fallback for the create-astro-style transcript). The `message` may contain
+* newlines — `LunoraReporter` indents continuation lines under the badge so a
+* dimmed answer sits below its question.
+*/
 interface CodegenCommandOptions {
   /** Which API spec(s) to emit. Defaults to codegen's `"openapi"` when omitted. */
   apiSpec?: ApiSpec;
@@ -496,15 +502,145 @@ declare const runDevCommand: (options: DevCommandOptions) => Promise<{
 /** `lunora dev` handler (lazy-loaded via the command's `loader`). */
 /** Supported CI providers. */
 type CiProvider = "github" | "gitlab";
+type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+/** True when `manager` is on PATH — probed by running `&lt;manager> --version`. Injectable for tests. */
+type PackageManagerProbe = (manager: PackageManager) => boolean;
+/**
+* The package managers actually installed on this machine, in preference order
+* ({@link INSTALL_PREFERENCE} — pnpm > bun > yarn > npm). The first entry is the
+* recommended default for the install prompt; the whole list is what the user
+* picks from. Empty when none are found.
+*/
 /** A registry item a feature can install. */
 type FeatureItem = "auth" | "auth-auth0" | "auth-clerk" | "mail";
 /** The auth-provider choices offered for `add auth` / the init auth prompt. Each value is a registry item name. */
-
-/** A feature offered in the post-scaffold multi-select. `value` is the stack-feature key, not (yet) a registry item. */
-type StackFeature = "auth" | "email";
+/** A single file the item scaffolds into the project. */
+interface RegistryFile {
+  /** Source path inside the item dir (e.g. `schema.ts`). */
+  from: string;
+  /** Merge strategy. `create-or-skip` writes whole files; `schema-extension` AST-merges schema.ts. */
+  merge: "create-or-skip" | "schema-extension";
+  /** Destination relative to the project root (e.g. `lunora/ratelimit/index.ts`). */
+  to: string;
+}
+/** A wrangler.jsonc binding addition. `path` is the jsonc key path; `value` the value to set. */
+interface RegistryBinding {
+  path: ReadonlyArray<string>;
+  value: unknown;
+}
+/**
+* An environment variable an item needs. Scaffolded into `.dev.vars` (Workers'
+* local-secrets file) on add — non-secrets get their `value`; secrets get an
+* empty placeholder and a reminder to run `wrangler secret put` for production.
+*/
+interface RegistryEnvVariable {
+  /** Human note on what the variable is for. */
+  description?: string;
+  /** The variable name (e.g. `RESEND_API_KEY`). */
+  name: string;
+  /** Mark as a secret: never write a value, only a placeholder, and remind about prod. Defaults to `true` when no `value` is given. */
+  secret?: boolean;
+  /** A default/example value for non-secret vars. */
+  value?: string;
+}
+/** The `registry.json` manifest shape. */
+interface RegistryManifest {
+  /** wrangler.jsonc additions (best-effort structural edits). */
+  bindings?: ReadonlyArray<RegistryBinding>;
+  /** npm deps to add to the project package.json (name → version range). */
+  deps?: Readonly<Record<string, string>>;
+  description?: string;
+  /** npm devDependencies to add to the project package.json. */
+  devDependencies?: Readonly<Record<string, string>>;
+  /** Post-install guidance printed after the item is added (per-item next steps). */
+  docs?: string;
+  /** Environment variables the item needs; scaffolded into `.dev.vars`. */
+  envVars?: ReadonlyArray<RegistryEnvVariable>;
+  files: ReadonlyArray<RegistryFile>;
+  name: string;
+  /** Other registry items this one depends on (resolved transitively, deps first). */
+  requires?: ReadonlyArray<string>;
+  /** Short human-readable label (distinct from the longer `description`). */
+  title?: string;
+}
+interface AddCommandOptions {
+  /** Bypass the `--source` safety gate (matches init). */
+  allowUnsafeSource?: boolean;
+  /** `registry build --check`: verify the index is current instead of rewriting it. */
+  check?: boolean;
+  /** Inject a confirmer for non-interactive callers / tests. */
+  confirm?: (prompt: string) => Promise<boolean>;
+  cwd?: string;
+  /** Preview the file-level changes (a content diff) and write nothing. */
+  diff?: boolean;
+  /** Print the plan and stop without writing anything. */
+  dryRun?: boolean;
+  /** Local registry root (offline / tests). Expects per-item subdirs, each with a `registry.json`. */
+  from?: string;
+  /** Emit a JSON snapshot of the plan/result. */
+  json?: boolean;
+  /** `--list`: enumerate available items instead of adding. */
+  list?: boolean;
+  logger: Logger;
+  /** Item names to add (positional args). */
+  names: ReadonlyArray<string>;
+  /** `registry build` output path for the generated catalog (defaults to the root's `index.json`). */
+  out?: string;
+  /** Force-overwrite existing files (take the incoming copy) instead of skipping/conflicting. */
+  overwrite?: boolean;
+  /** Override the git ref (branch, tag, or commit) items are fetched from (default: version-derived); appended to the `source` base when that is set. Ignored when `from` is set. */
+  ref?: string;
+  /** Override the remote registry source base (default gh:anolilab/lunora/registry). */
+  source?: string;
+  /**
+  * Customize each resolved manifest after it is loaded but before the plan is
+  * printed / reconciled — used to inject user-chosen values into otherwise
+  * static manifests (e.g. the R2 `bucket_name` the init storage prompt asks
+  * for). Applied to every item; return the manifest unchanged to leave it as-is.
+  */
+  transformManifest?: (manifest: RegistryManifest) => RegistryManifest;
+  /** Skip the package.json mutation confirmation prompt. */
+  yes?: boolean;
+}
+interface AddCommandResult {
+  /** Bindings written to wrangler.jsonc. */
+  bindings: ReadonlyArray<string>;
+  code: number;
+  /** Deps added to package.json. */
+  deps: ReadonlyArray<string>;
+  /** Files skipped because they already existed. */
+  skipped: ReadonlyArray<string>;
+  /** Files written (absolute paths). */
+  written: ReadonlyArray<string>;
+}
+/** One resolved item: its parsed manifest plus the (possibly staged) directory it lives in. */
+/**
+* A feature offered in the post-scaffold multi-select. `auth`/`email` carry a
+* sub-prompt or alias; every other value IS the registry item name applied
+* directly (`storage` → the `storage` registry item, etc.).
+*/
+type StackFeature = "auth" | "backup" | "crons" | "email" | "presence" | "ratelimit" | "storage";
+/** Customize a resolved manifest before it is written (e.g. inject the chosen R2 bucket name). */
+type OfferTransformManifest = (manifest: RegistryManifest) => RegistryManifest;
+/**
+* One feature ready to apply: the registry item name(s), an optional manifest
+* transform, and a short `label` (the feature value) shown on the combined
+* progress line. Built up-front by the collectors so every prompt is answered
+* before any apply runs.
+*/
+interface FeatureApply {
+  label: string;
+  names: ReadonlyArray<string>;
+  transformManifest?: OfferTransformManifest;
+}
 interface OfferDeps {
-  /** Apply one or more registry items into the new project; resolves `true` on success. */
-  apply: (names: ReadonlyArray<FeatureItem>) => Promise<boolean>;
+  /**
+  * Apply the collected features into the new project in one batch — resolves
+  * `true` when every item succeeds. The CLI renders this as a single progress
+  * line whose label changes per feature; each plan's `transformManifest`
+  * customizes that item's manifest before it is written.
+  */
+  applyAll: (plans: ReadonlyArray<FeatureApply>) => Promise<boolean>;
   /** When `false`, skip all prompts and print the later-setup hint. */
   interactive: boolean;
   logger: Logger;
@@ -516,6 +652,14 @@ interface OfferDeps {
   }>, settings?: {
     defaults?: ReadonlyArray<StackFeature>;
   }) => Promise<StackFeature[]>;
+  /**
+  * Features chosen non-interactively (the `--add` flag). When set, the
+  * multi-select and every sub-prompt are skipped — each feature is applied with
+  * its shipped defaults (base registry item, placeholder bindings).
+  */
+  preselected?: ReadonlyArray<StackFeature>;
+  /** The new project's name — seeds smart defaults like the `project-uploads` bucket name. */
+  projectName: string;
   /** Single-select among the auth providers (TTY-backed in production). */
   select: (message: string, options: ReadonlyArray<{
     description?: string;
@@ -524,16 +668,32 @@ interface OfferDeps {
   }>, settings?: {
     default?: FeatureItem;
   }) => Promise<FeatureItem | undefined>;
+  /** Single-line text input (TTY-backed in production) — used for the storage bucket-name prompt. */
+  text: (message: string, settings?: {
+    default?: string;
+    placeholder?: string;
+  }) => Promise<string>;
 }
 /**
-* Offer the stack features (authentication, transactional email) in ONE
-* multi-select after a successful scaffold. When auth is picked, a follow-up
-* single-select chooses the provider (email+password / Clerk / Auth0); email
-* maps to the `mail` item. Picked items are applied in selection order.
-* Non-interactive: prints how to add them later and changes nothing.
+* Offer the stack features (auth, email, storage, rate limiting, crons,
+* presence, backups) in ONE multi-select after a successful scaffold. Auth,
+* email, and storage run a follow-up prompt (provider / destination / bucket
+* name); every other feature value is applied as its registry item directly.
+*
+* Every question is asked FIRST (in selection order), then the picked features
+* are applied together via {@link OfferDeps.applyAll} — the CLI renders that as a
+* single progress line whose label changes per feature, instead of one spinner
+* per item. Non-interactive: prints how to add them later and changes nothing.
 */
-type Template = "astro" | "next" | "nuxt" | "standalone" | "sveltekit" | "tanstack-start-react" | "tanstack-start-solid" | "vite";
+type Template = "analog" | "astro" | "next" | "nuxt" | "react-router" | "standalone" | "sveltekit" | "tanstack-start-react" | "tanstack-start-solid";
 interface InitCommandOptions {
+  /**
+  * Add features non-interactively after scaffolding (the `--add` flag): a
+  * comma-separated list of `auth | email | storage | ratelimit | crons |
+  * presence | backup`. Bypasses the interactive multi-select and sub-prompts —
+  * each named feature is applied with its shipped defaults.
+  */
+  add?: string;
   /**
   * When true, accept `--source` values that don't start with `gh:` /
   * `github:` / `https://` or that contain `..`. Defaults to false; the CLI
@@ -545,6 +705,12 @@ interface InitCommandOptions {
   ci?: CiProvider;
   cwd?: string;
   /**
+  * Walk the whole flow — prompts, task list, next-steps, mascot — but make no
+  * changes: skip the template fetch/copy, the feature applies, the dependency
+  * install, and `git init`. Each skipped action logs a `would …` line instead.
+  */
+  dryRun?: boolean;
+  /**
   * Local directory containing the template subdirs (e.g. `vite/`,
   * `standalone/`). When provided, skips the network fetch entirely.
   * Useful for offline runs, the clean-machine smoke test, and unit tests.
@@ -559,6 +725,15 @@ interface InitCommandOptions {
   */
   inPlace?: boolean;
   /**
+  * Inject the post-scaffold install offer's prompts (tests). When set, the
+  * offer runs regardless of TTY: `confirmInstall` drives the yes/no, and
+  * `selectManager` picks among the detected managers.
+  */
+  installPrompt?: {
+    confirmInstall: () => Promise<boolean>;
+    selectManager: (managers: ReadonlyArray<PackageManager>) => Promise<PackageManager>;
+  };
+  /**
   * Force the post-scaffold "add auth / email?" offer on (the `--interactive`
   * flag). When omitted, the offer runs only when stdin is a TTY. `--yes`
   * suppresses it regardless. Has no effect once {@link prompt} is injected.
@@ -567,22 +742,47 @@ interface InitCommandOptions {
   logger: Logger;
   name?: string;
   /**
+  * Local directory holding create-vite bases (one `template-&lt;id>/` subdir per
+  * framework). When set with `vite`, the overlay copies the base from disk
+  * instead of fetching `create-vite` over the network — offline mode + tests.
+  */
+  overlayBaseFrom?: string;
+  /** Probe for which package managers are installed (tests). Defaults to a real `&lt;pm> --version` check. */
+  packageManagerProbe?: PackageManagerProbe;
+  /**
   * Inject the offer's prompts (tests). When set, the offer is treated as
-  * interactive regardless of TTY, and these drive the feature multi-select
-  * and the auth-provider sub-select.
+  * interactive regardless of TTY, and these drive the feature multi-select,
+  * the auth-provider sub-select, and the storage bucket-name text input.
   */
-  prompt?: Pick<OfferDeps, "multiSelect" | "select">;
+  prompt?: Pick<OfferDeps, "multiSelect" | "select" | "text">;
+  /**
+  * Override the git ref (branch, tag, or commit) the default template source
+  * is fetched from. Takes precedence over the version-derived ref. Ignored
+  * when `source` or `from` is set.
+  */
+  ref?: string;
   /** Local registry root for the offer's `runAddCommand` (offline / tests). Mirrors `from` but for registry items. */
   registryFrom?: string;
   /** Override the remote registry source base for the offer (default `gh:anolilab/lunora/registry`). */
   registrySource?: string;
   /**
   * Override the remote source giget downloads from. Default:
-  * `gh:anolilab/lunora/templates/&lt;templateType>#v&lt;cliVersion>`. Tests
-  * typically use `from` instead to skip the network.
+  * `gh:anolilab/lunora/templates/&lt;templateType>#&lt;ref>`, where `&lt;ref>` is
+  * the `ref` option when set, else derived from the CLI version (pre-release
+  * channels → their branch, stable → `main`). Tests typically use `from`
+  * instead to skip the network.
   */
   source?: string;
+  /** Spawner for the post-scaffold dependency install (tests inject a recording stub). Defaults to a real subprocess. */
+  spawner?: Spawner;
   templateType?: Template;
+  /**
+  * Scaffold via the **create-vite overlay** for this framework (`react`,
+  * `vue`, `solid`, `svelte`, `vanilla`) instead of a bespoke template: fetch
+  * the official create-vite base and apply the Lunora layer on top. Takes
+  * precedence over `templateType`.
+  */
+  vite?: string;
   /** Suppress the offer entirely (the `--yes` flag): scaffold only, print the later-setup hint. */
   yes?: boolean;
 }
@@ -591,13 +791,8 @@ interface InitCommandResult {
   files: ReadonlyArray<string>;
   target: string;
 }
-/**
-* `lunora init` entry: scaffold (in-place or a new directory), then — on success
-* — offer to add auth + email via the registry. The offer never affects the
-* scaffold's exit code.
-*/
 declare const runInitCommand: (options: InitCommandOptions) => Promise<InitCommandResult>;
-/** Narrow a raw `--template` value to a known {@link Template} (defaults to vite). */
+/** Narrow a raw `--template` value to a known {@link Template}. */
 interface MigrateGenerateCommandOptions {
   cwd?: string;
   logger: Logger;
@@ -633,97 +828,6 @@ interface IndexItem extends CatalogItem {
 declare const buildRegistryIndex: (root: string) => {
   items: IndexItem[];
 };
-/** A single file the item scaffolds into the project. */
-interface RegistryFile {
-  /** Source path inside the item dir (e.g. `schema.ts`). */
-  from: string;
-  /** Merge strategy. `create-or-skip` writes whole files; `schema-extension` AST-merges schema.ts. */
-  merge: "create-or-skip" | "schema-extension";
-  /** Destination relative to the project root (e.g. `lunora/ratelimit/index.ts`). */
-  to: string;
-}
-/** A wrangler.jsonc binding addition. `path` is the jsonc key path; `value` the value to set. */
-interface RegistryBinding {
-  path: ReadonlyArray<string>;
-  value: unknown;
-}
-/**
-* An environment variable an item needs. Scaffolded into `.dev.vars` (Workers'
-* local-secrets file) on add — non-secrets get their `value`; secrets get an
-* empty placeholder and a reminder to run `wrangler secret put` for production.
-*/
-interface RegistryEnvVariable {
-  /** Human note on what the variable is for. */
-  description?: string;
-  /** The variable name (e.g. `RESEND_API_KEY`). */
-  name: string;
-  /** Mark as a secret: never write a value, only a placeholder, and remind about prod. Defaults to `true` when no `value` is given. */
-  secret?: boolean;
-  /** A default/example value for non-secret vars. */
-  value?: string;
-}
-/** The `registry.json` manifest shape. */
-interface RegistryManifest {
-  /** wrangler.jsonc additions (best-effort structural edits). */
-  bindings?: ReadonlyArray<RegistryBinding>;
-  /** npm deps to add to the project package.json (name → version range). */
-  deps?: Readonly<Record<string, string>>;
-  description?: string;
-  /** npm devDependencies to add to the project package.json. */
-  devDependencies?: Readonly<Record<string, string>>;
-  /** Post-install guidance printed after the item is added (per-item next steps). */
-  docs?: string;
-  /** Environment variables the item needs; scaffolded into `.dev.vars`. */
-  envVars?: ReadonlyArray<RegistryEnvVariable>;
-  files: ReadonlyArray<RegistryFile>;
-  name: string;
-  /** Other registry items this one depends on (resolved transitively, deps first). */
-  requires?: ReadonlyArray<string>;
-  /** Short human-readable label (distinct from the longer `description`). */
-  title?: string;
-}
-interface AddCommandOptions {
-  /** Bypass the `--source` safety gate (matches init). */
-  allowUnsafeSource?: boolean;
-  /** `registry build --check`: verify the index is current instead of rewriting it. */
-  check?: boolean;
-  /** Inject a confirmer for non-interactive callers / tests. */
-  confirm?: (prompt: string) => Promise<boolean>;
-  cwd?: string;
-  /** Preview the file-level changes (a content diff) and write nothing. */
-  diff?: boolean;
-  /** Print the plan and stop without writing anything. */
-  dryRun?: boolean;
-  /** Local registry root (offline / tests). Expects per-item subdirs, each with a `registry.json`. */
-  from?: string;
-  /** Emit a JSON snapshot of the plan/result. */
-  json?: boolean;
-  /** `--list`: enumerate available items instead of adding. */
-  list?: boolean;
-  logger: Logger;
-  /** Item names to add (positional args). */
-  names: ReadonlyArray<string>;
-  /** `registry build` output path for the generated catalog (defaults to the root's `index.json`). */
-  out?: string;
-  /** Force-overwrite existing files (take the incoming copy) instead of skipping/conflicting. */
-  overwrite?: boolean;
-  /** Override the remote registry source base (default gh:anolilab/lunora/registry). */
-  source?: string;
-  /** Skip the package.json mutation confirmation prompt. */
-  yes?: boolean;
-}
-interface AddCommandResult {
-  /** Bindings written to wrangler.jsonc. */
-  bindings: ReadonlyArray<string>;
-  code: number;
-  /** Deps added to package.json. */
-  deps: ReadonlyArray<string>;
-  /** Files skipped because they already existed. */
-  skipped: ReadonlyArray<string>;
-  /** Files written (absolute paths). */
-  written: ReadonlyArray<string>;
-}
-/** One resolved item: its parsed manifest plus the (possibly staged) directory it lives in. */
 /** `lunora registry add` (one or more item names): scaffold items into the project. */
 declare const runAddCommand: (options: AddCommandOptions) => Promise<AddCommandResult>;
 /**