@pantoken/scaffold 0.4.0 → 1.0.0

package/README.md

@@ -13,13 +13,27 @@ npx @pantoken/scaffold components      # plain HTML/CSS (Vite + TS) + @pantoken/
 npx @pantoken/scaffold react           # Vite + React + @pantoken/react
 npx @pantoken/scaffold vue             # Vite + Vue 3 + @pantoken/vue
 npx @pantoken/scaffold web-components  # Vite + @pantoken/web-components (no framework)
+npx @pantoken/scaffold canvas-theme-editor  # Canvas Theme Editor uploads + RCE template starter
 
 # Target a directory other than the current one:
 npx @pantoken/scaffold react ./my-app
+
+# Omit the platform (and/or directory) on a TTY to be prompted interactively:
+npx @pantoken/scaffold
+
+# Non-interactive (CI-safe): errors instead of prompting for a missing platform/directory
+npx @pantoken/scaffold react --dir ./my-app --yes
+
+# Override the auto-detected display language
+npx @pantoken/scaffold --lang hu
 ```
 
-`npx` works regardless of which package manager you use. Substitute `pnpm dlx`, `yarn dlx`, or
-`bunx` for `npx` if you prefer.
+`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`).
+
+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.
 
 Or use it programmatically:
 
@@ -35,8 +49,27 @@ await scaffoldProject("react", "./my-app");
   `ScaffoldPlatform` into `dir` (defaults to `"."`). Its basename (or `"pantoken-app"` for `"."`)
   is passed as the project name to the Bingo preset. Returns the paths written.
 - **`SCAFFOLD_PLATFORMS: readonly ScaffoldPlatform[]`** — every scaffoldable platform key (discovered
-  from available presets at build time).
-- **`ScaffoldPlatform`** — the platform union, derived from preset registry.
+  from available presets at build time, plus legacy template-only platforms like
+  `canvas-theme-editor` that aren't backed by a preset yet).
+- **`ScaffoldPlatform`** — the platform union, derived from the preset registry and the legacy
+  template map.
+
+## CLI flags
+
+| Flag                  | Description                                                               |
+| --------------------- | ------------------------------------------------------------------------- |
+| `[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"`)                 |
+| `--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.
 
 ## Architecture
 

package/bin/pantoken-scaffold.mjs

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
 import { runScaffoldCli } from "../dist/cli.mjs";
+import pkg from "../package.json" with { type: "json" };
 
-await runScaffoldCli(process.argv.slice(2), { usageCommand: "pantoken-scaffold" });
+await runScaffoldCli(process.argv.slice(2), {
+  usageCommand: "pantoken-scaffold",
+  version: pkg.version,
+});

package/dist/cli.d.mts

@@ -1,12 +1,179 @@
+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 { Command } from "commander";
+//#region src/locale.d.ts
+/**
+ * Locale detection and message lookup for the scaffold CLI.
+ *
+ * @module
+ * @alpha
+ */
+/** 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;
+}
+/**
+ * Resolves the active locale: --lang flag \> LC_ALL/LANG env \> Intl \> "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).
+ * @returns The resolved locale tag
+ */
+export declare function detectLocale(options: {
+  langFlag?: string;
+  env?: NodeJS.ProcessEnv;
+  intl?: () => string;
+}): string;
+/**
+ * Builds a lookup over the given locale bundles, falling back to `bundles[fallback]`
+ * for any key missing in the resolved locale.
+ *
+ * @param bundles - Record mapping locale tags to string bundles
+ * @param resolvedLocale - The locale to use (typically from detectLocale)
+ * @param fallback - The fallback locale when a key is missing (default "en")
+ * @returns A LocaleLookup object with a `t` function
+ */
+export declare function createLocaleLookup(bundles: Record<string, Record<string, string>>, resolvedLocale: string, fallback?: string): LocaleLookup;
+//#endregion
+//#region generated/locales/index.d.ts
+export declare const MESSAGES: Record<string, Record<string, string>>;
+//#endregion
 //#region src/cli.d.ts
-/** Options distinguishing the two bins that share this CLI. */
-interface ScaffoldCliOptions {
-  /** How the invoking command reads in its own `--help` usage line, e.g. `"pantoken-scaffold"`. */
-  usageCommand: string;
+/**
+ * Thrown for user-facing CLI errors (e.g., missing platform under --yes);
+ * carries an exit code for process.exit or CommanderError handling.
+ */
+export declare class ScaffoldCliError extends Error {
+  readonly exitCode: number;
+  constructor(message: string, exitCode?: number);
 }
-/** Whether the directory prompt should run: no `--dir` flag was given, and stdin is an interactive TTY. */
-declare function shouldPromptForDir(dirFlag: string | undefined, isTTY: boolean | undefined): boolean;
-/** Run the scaffold CLI end to end: parse argv, prompt if needed, scaffold, and print next steps. */
-declare function runScaffoldCli(argv: string[], options: ScaffoldCliOptions): Promise<void>;
+/**
+ * Whether a value should be interactively prompted for:
+ * no value given, not --yes, and (optionally injected) TTY check passes.
+ *
+ * @param value - The provided value (or undefined)
+ * @param opts - Options: `yes` flag forces non-interactive, `isTTY` injectable for testing
+ * @returns True if interactive prompt should proceed
+ */
+export declare function shouldPrompt(value: string | undefined, opts: {
+  yes?: boolean;
+  isTTY?: boolean;
+}): boolean;
+/**
+ * Expands a tilde (`~`) in a file path to the user's home directory.
+ * On interactive prompts, shells don't expand `~`, so this handles it explicitly.
+ * Uses `node:path.join()` for cross-platform robustness (Windows, macOS, Linux).
+ *
+ * @param dir - The directory path (may start with `~`)
+ * @returns The expanded path
+ */
+export declare function expandHome(dir: string): string;
+/** Options for {@link resolveScaffoldTarget}. */
+export interface ResolveScaffoldTargetOptions {
+  platformArg?: string;
+  dirOption?: string;
+  yes?: boolean;
+  isTTY?: boolean;
+  t: LocaleLookup["t"];
+}
+/**
+ * Resolves platform + directory: prompts via clack select()/text() when omitted on a TTY
+ * (not --yes); throws ScaffoldCliError with a clear, localized message when a required
+ * value is missing non-interactively.
+ *
+ * All prompt copy (message/placeholder/option labels) is looked up via `t`.
+ *
+ * @param options - Resolution options
+ * @returns Promise resolving to \{ platform, dir \}
+ * @throws ScaffoldCliError when required values are missing non-interactively
+ */
+export declare function resolveScaffoldTarget(options: ResolveScaffoldTargetOptions): Promise<{
+  platform: string;
+  dir: string;
+}>;
+/**
+ * Runs scaffoldProject() wrapped in a clack spinner() whose start/stop text comes from `t`.
+ *
+ * @param platform - The scaffold platform
+ * @param dir - The target directory
+ * @param t - Localized string lookup
+ * @param options - `theme`/`mode`/`cdn` 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;
+}): Promise<string[]>;
+/** Package managers `detectPackageManager` can identify. */
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno" | "vp";
+/**
+ * Detects the invoking package manager: first from `npm_config_user_agent` (the technique
+ * create-vite and create-vue use), then — since `vp`/`vpx` set no such env var — falling back to
+ * whether the running Node binary itself is Vite+-managed (`execPath` resolves under a
+ * `vite-plus` directory).
+ *
+ * @param env - Environment variables (defaults to process.env)
+ * @param execPath - The running Node binary's path (defaults to process.execPath)
+ * @returns Detected package manager, or undefined
+ */
+export declare function detectPackageManager(env?: NodeJS.ProcessEnv, execPath?: string): PackageManager | undefined;
+/**
+ * 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`).
+ *
+ * @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
+ */
+export declare function printNextSteps(dir: string, written: string[], t: LocaleLookup["t"], platform?: string): void;
+/**
+ * Shared commander Argument validator for the platform positional.
+ * Used by all three CLIs (scaffold, create-pantoken-app, pantoken-ai scaffold)
+ * so error wording has one source of truth.
+ *
+ * @param value - The provided platform argument
+ * @returns The validated platform value
+ * @throws InvalidArgumentError if the platform is not valid
+ */
+export declare function validateScaffoldPlatform(value: string): string;
+/**
+ * Commander Argument validator for `--cdn`.
+ *
+ * @throws InvalidArgumentError if the value isn't a known CDN provider id
+ */
+export declare function validateCdnProviderId(value: string): string;
+/** Options for {@link createScaffoldCommand}. */
+export interface ScaffoldCommandOptions {
+  name?: string;
+  usageCommand?: string;
+  version?: string;
+  enableCompletions?: boolean;
+}
+/**
+ * Builds the full, ready-to-parse commander Command for pantoken-scaffold/create-pantoken-app.
+ *
+ * @param options - Configuration for the command
+ * @returns A configured commander Command
+ */
+export declare function createScaffoldCommand(options?: ScaffoldCommandOptions): Command;
+/**
+ * Entry point both bin shims call: builds the command and parses argv against it.
+ *
+ * @param argv - Command-line arguments (typically process.argv.slice(2))
+ * @param options - Configuration for the CLI
+ * @throws Exits via process.exit on error or successful completion
+ */
+export declare function runScaffoldCli(argv: string[], options: {
+  usageCommand: string;
+  version?: string;
+}): Promise<void>;
 //#endregion
-export { ScaffoldCliOptions, runScaffoldCli, shouldPromptForDir };
+export { type LocaleLookup, SCAFFOLD_PLATFORMS, isScaffoldPlatform, resolveScaffoldPlatform, scaffoldProject };