@pantoken/scaffold 1.1.0 → 1.2.0

package/README.md

@@ -63,15 +63,22 @@ await scaffoldProject("react", "./my-app");
 | `-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 |
 | `--no-install`        | Skip automatically installing dependencies after scaffolding              |
-| `-l, --lang <tag>`    | Override the auto-detected display language (e.g. `"hu"`)                 |
+| `-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,6 +130,13 @@ 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