@pantoken/scaffold 1.0.1 → 1.2.0

package/README.md

@@ -29,8 +29,9 @@ npx @pantoken/scaffold --lang hu
 ```
 
 `npx` works regardless of which package manager you use. Substitute `pnpm dlx`, `yarn dlx`,
-`bunx`, or `deno run npm:` for `npx` if you prefer — the printed "Next steps" install command
-matches whichever one invoked the CLI (detected from `npm_config_user_agent`).
+`bunx`, or `deno run npm:` for `npx` if you prefer — dependencies are installed automatically with
+whichever one invoked the CLI (detected from `npm_config_user_agent`), leaving "start the dev
+server" as the only manual step. Pass `--no-install` to skip the automatic install.
 
 Run `npx @pantoken/scaffold --help` for the full flag reference, or `npx @pantoken/scaffold
 completion <shell>` to generate a bash/zsh/fish/PowerShell completion script.
@@ -61,15 +62,23 @@ await scaffoldProject("react", "./my-app");
 | `[platform]`          | Platform to scaffold (prompted interactively if omitted on a TTY)         |
 | `-d, --dir <path>`    | Target directory (prompted interactively if omitted on a TTY)             |
 | `-y, --yes`           | Never prompt; error instead of prompting for a missing platform/directory |
-| `-l, --lang <tag>`    | Override the auto-detected display language (e.g. `"hu"`)                 |
+| `--no-install`        | Skip automatically installing dependencies after scaffolding              |
+| `-l, --lang <tag>`    | Language for the CLI and the scaffolded project (e.g. `"hu"`)             |
 | `--theme <name>`      | Token theme: `rebrand` (default), `canvas`, `canvasHighContrast`          |
 | `--theme-mode <mode>` | Rebrand token mode: `light` (default) or `adaptive`                       |
 | `-v, --version`       | Print the installed version                                               |
 | `-h, --help`          | Print usage                                                               |
 | `completion <shell>`  | Generate a bash/zsh/fish/PowerShell completion script                     |
 
-The CLI auto-detects its display language from `--lang` > `LC_ALL`/`LANG` > the runtime's `Intl`
-locale > English, falling back to English for any untranslated string.
+The CLI auto-detects its language from `--lang` > `LC_ALL`/`LANG` > the runtime's `Intl` locale >
+English, falling back to English for any untranslated string. Region subtags survive when pantoken
+supports them (`pt_BR.UTF-8` resolves to `pt-BR`) and narrow to the base language when it doesn't
+(`es_MX` resolves to `es`).
+
+The resolved locale also shapes the generated project: entry markup gets a matching `lang`/`dir`
+pair (so `--lang ar` scaffolds `<html lang="ar" dir="rtl">`), and the project README is written in
+that language where a translation exists. An explicit `--lang` must name a supported locale — it
+errors rather than silently falling back, since the value is written into the scaffolded files.
 
 ## Architecture
 

package/dist/cli.d.mts

@@ -1,21 +1,30 @@
-import { a as scaffoldProject, i as resolveScaffoldPlatform, o as ThemeMode, r as isScaffoldPlatform, s as ThemeVariant, t as SCAFFOLD_PLATFORMS } from "./index-CyolWk0E.mjs";
+import { a as scaffoldProject, i as resolveScaffoldPlatform, o as ThemeMode, r as isScaffoldPlatform, s as ThemeVariant, t as SCAFFOLD_PLATFORMS } from "./index-D2-Dhvt8.mjs";
 import { Command } from "commander";
 //#region src/locale.d.ts
-/**
- * Locale detection and message lookup for the scaffold CLI.
- *
- * @module
- * @alpha
- */
+/** Every locale tag pantoken supports, as `--lang` accepts them. */
+export declare const SUPPORTED_LOCALES: readonly string[];
 /** Resolved locale plus a message lookup function. */
 interface LocaleLookup {
   readonly locale: string;
   /** Looks up `key`, substituting any `{{param}}` placeholders from `params`. */
   t: (key: string, params?: Record<string, string>) => string;
 }
+/**
+ * Commander option validator for `--lang`.
+ *
+ * Unlike ambient detection, an explicit flag must not silently fall back to English — and because
+ * the resolved tag is written into scaffolded files (an HTML `lang`/`dir` attribute), constraining
+ * it to the registry also keeps arbitrary caller input out of generated markup.
+ *
+ * @throws InvalidArgumentError if the value isn't a supported locale
+ */
+export declare function validateLocaleTag(value: string): string;
 /**
  * Resolves the active locale: --lang flag \> LC_ALL/LANG env \> Intl \> "en".
  *
+ * Ambient sources (env, Intl) are advisory: an unsupported or region-only tag narrows to its
+ * closest supported parent (`pt_BR.UTF-8` → `pt-BR`, `es_MX` → `es`) and falls back to `"en"`.
+ *
  * @param options - Detection options. `langFlag` is an optional --lang flag value; `env` is
  * environment variables (defaults to process.env); `intl` is an optional injected
  * Intl.DateTimeFormat locale function (for testing).
@@ -99,13 +108,14 @@ export declare function resolveScaffoldTarget(options: ResolveScaffoldTargetOpti
  * @param platform - The scaffold platform
  * @param dir - The target directory
  * @param t - Localized string lookup
- * @param options - `theme`/`mode`/`cdn` forwarded to {@link scaffoldProject}
+ * @param options - `theme`/`mode`/`cdn`/`locale` forwarded to {@link scaffoldProject}
  * @returns The paths written by scaffoldProject
  */
 export declare function scaffoldWithSpinner(platform: string, dir: string, t: LocaleLookup["t"], options?: {
   theme?: ThemeVariant;
   mode?: ThemeMode;
   cdn?: string;
+  locale?: string;
 }): Promise<string[]>;
 /** Package managers `detectPackageManager` can identify. */
 export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno" | "vp";
@@ -120,20 +130,41 @@ export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno" | "vp";
  * @returns Detected package manager, or undefined
  */
 export declare function detectPackageManager(env?: NodeJS.ProcessEnv, execPath?: string): PackageManager | undefined;
+/**
+ * The invocation string `create-pantoken-app`'s bin shim shows in `--help`/usage, matching
+ * whichever package manager actually invoked it (falls back to the npm form when undetected).
+ *
+ * @param pm - The detected package manager (defaults to `detectPackageManager()`'s result)
+ */
+export declare function buildCreateUsageCommand(pm?: PackageManager): string;
+/**
+ * Runs the detected package manager's install command in `dir`, wrapped in a clack spinner.
+ * Failures are reported but non-fatal — the project is still usable, just not installed — so the
+ * caller decides how `printNextSteps` should reflect the outcome via the returned boolean.
+ *
+ * @param dir - The scaffold directory to install into
+ * @param pm - The detected package manager (defaults to npm's command when undefined)
+ * @param t - Localized string lookup
+ * @returns Whether the install command exited successfully
+ */
+export declare function installWithSpinner(dir: string, pm: PackageManager | undefined, t: LocaleLookup["t"]): boolean;
 /**
  * Prints the post-scaffold "Next steps" block (plus any template-authored notes/caveats).
  *
- * When `platform` has a `scaffold.json`-derived entry in `SCAFFOLD_METADATA`, next steps/notes/
- * caveats are rendered from its (localized, `{{var}}`-substituted) authored strings. Otherwise a
- * generic cd/install/run-script fallback is used, with the run script itself detected from the
- * scaffolded `package.json` (`dev`, else `preview`).
+ * When `installed` is true (dependencies were already installed automatically), the block collapses
+ * to the single remaining manual action — starting the dev server, prefixed with `cd <dir>` when
+ * needed — regardless of platform. Otherwise, when `platform` has a `scaffold.json`-derived entry in
+ * `SCAFFOLD_METADATA`, next steps/notes/caveats are rendered from its (localized, `{{var}}`-
+ * substituted) authored strings; failing that, a generic cd/install/run-script fallback is used,
+ * with the run script itself detected from the scaffolded `package.json` (`dev`, else `preview`).
  *
  * @param dir - The scaffold directory
  * @param written - The paths written by scaffoldProject
  * @param t - Localized string lookup
  * @param platform - The resolved (alias-free) scaffold platform, used to look up `scaffold.json` metadata
+ * @param installed - Whether dependencies were already installed automatically
  */
-export declare function printNextSteps(dir: string, written: string[], t: LocaleLookup["t"], platform?: string): void;
+export declare function printNextSteps(dir: string, written: string[], t: LocaleLookup["t"], platform?: string, installed?: boolean): void;
 /**
  * Shared commander Argument validator for the platform positional.
  * Used by all three CLIs (scaffold, create-pantoken-app, pantoken-ai scaffold)