@dunx/create-app 3.0.3 → 3.0.5

package/dist/features.d.ts

@@ -4,8 +4,8 @@
  * rots. `bun run sync:templates` copies them in and `features.test.ts` fails on
  * drift.
  *
- * The wiring is not copied: `app.module.ts`, `config.ts`, `bootstrap.ts` and
- * `main.ts` name every feature at once, so they are generated from the selection.
+ * The wiring is not copied: `app.module.ts`, `config.ts` and `main.ts` name every
+ * feature at once, so they are generated from the selection.
  */
 export interface Feature {
     /** Flag name, and the directory under `templates/features/`. */

package/dist/generate.d.ts

@@ -12,9 +12,6 @@ export declare const manifest: (features: readonly Feature[]) => string;
 export declare const THIRD_PARTY: Readonly<Record<string, string>>;
 export declare const appModule: (name: string, features: readonly Feature[]) => string;
 export declare const config: (name: string, groups: readonly string[]) => string;
-export declare const bootstrap: (name: string, features: readonly Feature[]) => string;
 export declare const main: (name: string, features: readonly Feature[]) => string;
-/** The queue worker, only when a queue was asked for. */
-export declare const worker: (name: string) => string;
 export declare const envExample: (groups: readonly string[]) => string;
 export declare const readme: (name: string, features: readonly Feature[]) => string;

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { scaffold, ScaffoldError, TEMPLATES, VERSION_PLACEHOLDER, type ScaffoldOptions, type ScaffoldResult, type TemplateName, } from './scaffold.js';
+export { FEATURES, featureNames, type Feature } from './features.js';
+export { blockingEntries, isValidPackageName, scaffold, ScaffoldError, TEMPLATES, VERSION_PLACEHOLDER, type ScaffoldOptions, type ScaffoldResult, type TemplateName, } from './scaffold.js';

package/dist/index.js

@@ -1,13 +1,21 @@
 // @bun
 import {
+  FEATURES,
   ScaffoldError,
   TEMPLATES,
   VERSION_PLACEHOLDER,
+  blockingEntries,
+  featureNames,
+  isValidPackageName,
   scaffold
-} from "./chunk-x7s3axkt.js";
+} from "./chunk-5tn3ybzv.js";
 export {
+  FEATURES,
   ScaffoldError,
   TEMPLATES,
   VERSION_PLACEHOLDER,
+  blockingEntries,
+  featureNames,
+  isValidPackageName,
   scaffold
 };

package/dist/keys.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The keys a prompt acts on. Everything else a terminal can send decodes to
+ * `Char` when it is printable and `Unknown` when it is not, so a prompt never has
+ * to know what a function key looks like.
+ */
+export declare const KeyName: Readonly<{
+    readonly Up: 'up';
+    readonly Down: 'down';
+    readonly Left: 'left';
+    readonly Right: 'right';
+    readonly Home: 'home';
+    readonly End: 'end';
+    readonly Enter: 'enter';
+    readonly Space: 'space';
+    readonly Tab: 'tab';
+    readonly ShiftTab: 'shiftTab';
+    readonly Backspace: 'backspace';
+    readonly ClearLine: 'clearLine';
+    readonly Escape: 'escape';
+    readonly Interrupt: 'interrupt';
+    readonly Char: 'char';
+    readonly Unknown: 'unknown';
+}>;
+export type KeyName = (typeof KeyName)[keyof typeof KeyName];
+export interface Key {
+    readonly name: KeyName;
+    /** What the key typed. Empty for every name but `Char`. */
+    readonly char: string;
+}
+/**
+ * Bytes from a raw-mode terminal, decoded into keys.
+ *
+ * A class rather than a function because two things have to survive between
+ * reads: a half-arrived escape sequence, and a UTF-8 code point split across the
+ * chunk boundary. `TextDecoder` in streaming mode holds the second; `#pending`
+ * holds the first, and an incomplete sequence is kept rather than guessed at.
+ *
+ * The one guess it does make: a chunk holding nothing but `0x1b` reads as the
+ * Escape key. A terminal that split that byte from the `[A` behind it across two
+ * reads would have it read as Escape followed by nothing bindable. Bun's PTY and every terminal
+ * measured deliver a sequence in one read - `1b 5b 41` arrived as one chunk on
+ * Bun 1.4.0, docs/bun-apis.md - and the alternative is a timer that delays every
+ * real Escape.
+ */
+export declare class KeyDecoder {
+    #private;
+    push(bytes: Uint8Array): readonly Key[];
+}

package/dist/prompt.d.ts

@@ -0,0 +1,43 @@
+import { type Key } from './keys.js';
+import type { Tty } from './tty.js';
+export declare class CancelledError extends Error {
+    readonly name = "CancelledError";
+}
+/**
+ * One question, as a state machine over keypresses.
+ *
+ * Rendering is a pure function of the state and returns lines rather than writing
+ * them, and `press` is the only way the state moves. Nothing here touches a
+ * terminal, so every prompt is exercised in-process by feeding it keys and reading
+ * the frame back; `PromptRunner` is the half that owns the real one.
+ */
+export declare abstract class Prompt<T> {
+    #private;
+    /** The interactive frame, one entry per line, within `width` and `height`. */
+    abstract frame(width: number, height: number): readonly string[];
+    /** The single line left in the scrollback once the question is answered. */
+    abstract summary(width: number): string;
+    protected abstract handle(key: Key): void;
+    press(key: Key): void;
+    protected finish(answer: T): void;
+    get done(): boolean;
+    get cancelled(): boolean;
+    /** The answer. Reading it before `done`, or after a cancel, is a bug here. */
+    get answer(): T;
+}
+/**
+ * Drives one prompt at a time against a real terminal.
+ *
+ * Repainting is "up N lines, erase to the bottom, write the frame" rather than an
+ * alternate screen: the answered prompts stay in the scrollback above, which is
+ * what makes the summary line a record of what was chosen rather than something
+ * that vanishes on exit.
+ *
+ * Every line is clipped to the terminal's width and the frame to its height, so a
+ * wrapped line can never make the cursor arithmetic wrong.
+ */
+export declare class PromptRunner {
+    #private;
+    constructor(tty: Tty);
+    ask<T>(prompt: Prompt<T>): Promise<T>;
+}

package/dist/prompts.d.ts

@@ -0,0 +1,53 @@
+import { type Key } from './keys.js';
+import { Prompt } from './prompt.js';
+import type { Style } from './style.js';
+/** One line of free text, with the cursor drawn as reverse video over it. */
+export declare class TextPrompt extends Prompt<string> {
+    #private;
+    protected readonly style: Style;
+    readonly title: string;
+    constructor(style: Style, title: string, initial: string);
+    /** An error to show instead of accepting, or `undefined` to accept. */
+    protected validate(_value: string): string | undefined;
+    /** The line under the field when there is nothing wrong with the value. */
+    protected hint(): string;
+    frame(width: number): readonly string[];
+    summary(width: number): string;
+    protected handle(key: Key): void;
+}
+/** Yes or no, defaulting to whichever the caller says is safe. */
+export declare class ConfirmPrompt extends Prompt<boolean> {
+    #private;
+    private readonly style;
+    private readonly title;
+    constructor(style: Style, title: string, initial: boolean);
+    frame(width: number): readonly string[];
+    summary(width: number): string;
+    protected handle(key: Key): void;
+}
+export interface SelectItem {
+    readonly value: string;
+    readonly label: string;
+    readonly hint: string;
+}
+/**
+ * A multi-select list: space toggles, the arrows move, Enter takes the set.
+ *
+ * The list scrolls rather than being clipped, because eighteen features do not fit
+ * a 24-row terminal alongside anything else. The window offset is the one piece of
+ * state `frame` writes, since only `frame` is told how tall the terminal is.
+ */
+export declare class SelectPrompt extends Prompt<readonly string[]> {
+    #private;
+    protected readonly style: Style;
+    readonly title: string;
+    protected readonly items: readonly SelectItem[];
+    constructor(style: Style, title: string, items: readonly SelectItem[], initial?: readonly string[]);
+    /** Values the chosen set pulls in without the user having chosen them. */
+    protected implied(_chosen: ReadonlySet<string>): ReadonlySet<string>;
+    /** Lines between the list and the footer: what came along, what it needs. */
+    protected notes(_chosen: ReadonlySet<string>): readonly string[];
+    frame(width: number, height: number): readonly string[];
+    summary(width: number): string;
+    protected handle(key: Key): void;
+}

package/dist/scaffold.d.ts

@@ -8,6 +8,15 @@ export type TemplateName = (typeof TEMPLATES)[number];
  * written into the template, which would go stale on the next release.
  */
 export declare const VERSION_PLACEHOLDER = "__DUNX_VERSION__";
+/**
+ * What is in `directory` that stops it being a scaffolding target. Empty means it
+ * is one, whether or not it exists.
+ *
+ * Exported because the wizard asks about a non-empty directory before writing
+ * anything, and asking a different question from the one `scaffold` then enforces
+ * is how a prompt and its guard drift apart.
+ */
+export declare const blockingEntries: (directory: string) => readonly string[];
 export interface ScaffoldOptions {
     /** Directory to create. Relative paths resolve against `cwd`. */
     readonly target: string;
@@ -40,4 +49,12 @@ export interface ScaffoldResult {
 export declare class ScaffoldError extends Error {
     readonly name = "ScaffoldError";
 }
+/**
+ * npm forbids uppercase and a leading dot or underscore, and a scope is legal.
+ * Checked here because the failure would otherwise surface as a confusing
+ * `bun install` error inside a directory the user just created.
+ */
+export declare const isValidPackageName: (name: string) => boolean;
+/** This package's own version, which is also the one it writes into the app. */
+export declare const packageVersion: () => Promise<string>;
 export declare const scaffold: (options: ScaffoldOptions) => Promise<ScaffoldResult>;

package/dist/style.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ANSI styling, and the switch that turns it off.
+ *
+ * `Bun.enableANSIColors` is the capability check rather than a `TERM` sniff: it is
+ * false under `NO_COLOR` and for a non-TTY, and it cannot be faked in-process.
+ * Tests construct one with the switch off and assert on plain text.
+ */
+export declare class Style {
+    #private;
+    constructor(enabled?: boolean);
+    accent(text: string): string;
+    muted(text: string): string;
+    danger(text: string): string;
+    warn(text: string): string;
+    bold(text: string): string;
+    /** Reverse video, which is how the text cursor is drawn over a character. */
+    invert(text: string): string;
+    /** An arbitrary colour, for the one place a gradient needs more than four. */
+    hex(colour: string, text: string): string;
+    /**
+     * Clipped to `width` columns, measured the way a terminal measures them.
+     * `Bun.stringWidth` counts columns rather than code units, and `Bun.sliceAnsi`
+     * cuts by the same measure without severing an escape sequence.
+     */
+    clip(text: string, width: number): string;
+}

package/dist/tty.d.ts

@@ -0,0 +1,58 @@
+import { type Key } from './keys.js';
+/**
+ * What a prompt needs from a terminal, and nothing else.
+ *
+ * An abstract class rather than an interface so the fake the tests drive is the
+ * same shape the real one is, checked by the compiler. `ProcessTty` is the real
+ * one; `tty.fixture.ts` holds the one that records frames instead of writing them.
+ */
+export declare abstract class Tty {
+    abstract get columns(): number;
+    abstract get rows(): number;
+    abstract write(text: string): void;
+    /** Raw mode on, decoded keys to `onKey`. */
+    abstract open(onKey: (key: Key) => void): void;
+    /** Raw mode off, and the read released so the process can exit. */
+    abstract close(): void;
+}
+/** The half of `process.stdin` that reading keys in raw mode uses. */
+export interface KeySource {
+    readonly isTTY?: boolean | undefined;
+    setRawMode?(enabled: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    off(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+}
+/** The half of `process.stdout` that a frame is written to. */
+export interface FrameSink {
+    readonly columns?: number | undefined;
+    readonly rows?: number | undefined;
+    write(text: string): unknown;
+}
+/**
+ * `process.stdin` in raw mode, `process.stdout` for the frames.
+ *
+ * Raw mode turns an arrow key into three bytes this process reads rather than a
+ * line the terminal buffers, and stops the terminal echoing keystrokes over the
+ * frame. It also makes `close()` load bearing twice over: Ctrl+C arrives as a byte
+ * with no `SIGINT` behind it, and the read holds the event loop open until the
+ * listener is removed. Both measured in docs/bun-apis.md, "Raw-mode stdin".
+ *
+ * The streams are arguments so the suite can drive this without a terminal;
+ * `interactive.test.ts` spawns a real one for what a fake cannot answer.
+ */
+export declare class ProcessTty extends Tty {
+    #private;
+    constructor(input?: KeySource, output?: FrameSink);
+    /**
+     * Whether this process can ask a question at all. Both halves are checked: a
+     * piped stdin has no `setRawMode`, and a piped stdout has no width to draw into.
+     */
+    static available(): boolean;
+    get columns(): number;
+    get rows(): number;
+    write(text: string): void;
+    open(onKey: (key: Key) => void): void;
+    close(): void;
+}

package/dist/wizard.d.ts

@@ -0,0 +1,35 @@
+import { type PromptRunner } from './prompt.js';
+import type { Style } from './style.js';
+export interface WizardAnswers {
+    readonly target: string;
+    readonly name: string;
+    readonly features: readonly string[];
+    readonly force: boolean;
+}
+/** What the flags already settled, so the wizard skips asking again. */
+export interface WizardDefaults {
+    readonly target: string | undefined;
+    readonly name: string | undefined;
+    readonly features: readonly string[];
+    readonly force: boolean;
+    readonly cwd: string;
+}
+/**
+ * The questions, in the order the answers are needed.
+ *
+ * Each one is skipped when there is nothing to ask: a target given on the command
+ * line, a package name that is already legal, a directory that is already empty.
+ * Running `bunx @dunx/create-app my-api` in a clean directory therefore asks one
+ * question, the one nothing else can answer.
+ */
+export declare class Wizard {
+    #private;
+    constructor(runner: PromptRunner, style: Style);
+    run(defaults: WizardDefaults): Promise<WizardAnswers>;
+}
+/**
+ * A package name npm will take, from a directory name it will not. Uppercase and
+ * the characters npm forbids both become a hyphen, and a leading dot, underscore
+ * or hyphen is dropped.
+ */
+export declare const slug: (value: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/create-app",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "Scaffold a new dunx application - bunx @dunx/create-app my-api",
   "keywords": [
     "bun",

package/templates/features/assets/assets.module.ts

@@ -7,7 +7,7 @@ const HASHED = /\.[0-9a-f]{8}\.(js|css)$/;
 
 /**
  * `public/` served at `/assets`. `StaticModule` binds `StaticFiles`; the app
- * registers it in `bootstrap.ts`, because position in the chain is the app's
+ * registers it in `main.ts`, because position in the chain is the app's
  * call. The mount skips the global prefix: middleware is not a discovered route.
  */
 @Module({

package/templates/features/auth/auth.module.ts

@@ -54,7 +54,7 @@ import { ProfileController } from './profile.controller.js';
   controllers: [ProfileController],
   providers: [AuthTables, Audit, AuthDemo],
   // `Auth` is exported because `OpenApiModule` wraps the root and can only
-  // inject what the root exports. See bootstrap.ts.
+  // inject what the root exports. See main.ts.
   exports: [Audit, AuthDemo, Auth],
 })
 export class AccountsModule {}

package/templates/features/http/http.module.ts

@@ -10,7 +10,7 @@ import { RequestTrail, RequestTrailMiddleware } from './request-trail.js';
 // declaring them here is for the reader, not for the resolver.
 @Module({
   imports: [
-    // Binds `Compression`; the **app** registers it, in `bootstrap.ts`, for the
+    // Binds `Compression`; the **app** registers it, in `main.ts`, for the
     // same reason `StaticFiles` is registered there. Nothing is installed by
     // importing this, so an app that never calls `app.use(Compression)` has no
     // branch in the request path to skip.

package/templates/minimal/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "bun --watch src/main.ts",
     "start": "bun src/main.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
@@ -15,10 +16,10 @@
   },
   "devDependencies": {
     "@dunx/testing": "__DUNX_VERSION__",
-    "@types/bun": ">=1.3.0",
+    "@types/bun": ">=1.4.0",
     "typescript": "^5.7.0"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   }
 }

package/dist/stdin.d.ts

@@ -1,14 +0,0 @@
-/**
- * One line of stdin, with the iteration ended before the value comes back.
- *
- * `console[Symbol.asyncIterator]().next()` on its own leaves stdin referenced for
- * the life of the process: the scaffold wrote its files, printed the next steps and
- * then sat there until the user pressed Ctrl+C. Ending the iteration runs the
- * iterator's `return()`, which releases the handle, so the process exits on its own.
- * Measured on Bun 1.4.0 - docs/bun-apis.md, "One line of stdin keeps the process
- * alive".
- *
- * A function rather than a class because it is the whole module: no state, no
- * configuration, and nothing to hold between calls.
- */
-export declare const readLine: () => Promise<string>;