@shaferllc/keel 0.68.0 → 0.74.0

package/dist/core/cli/stubs.js

@@ -100,6 +100,45 @@ export class ${name} extends Notification {
 }
 `;
 }
+/**
+ * A package skeleton: a `PackageProvider` wired for the common jobs — merging
+ * config, contributing a migration, mounting routes + assets, and declaring a
+ * publishable config stub. `name` is the short package name (e.g. "billing").
+ */
+export function packageProviderStub(name) {
+    const cls = name.charAt(0).toUpperCase() + name.slice(1);
+    return `import { PackageProvider, type Router } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The ${cls} package. Registered like any provider:
+ *   app.register(${cls}ServiceProvider)
+ */
+export class ${cls}ServiceProvider extends PackageProvider {
+  readonly name = "${name}";
+
+  register(): void {
+    this.mergeConfig("${name}", {
+      enabled: true,
+      path: "${name}",
+    });
+    // this.migrations([${name}Migration]);
+    this.publishes({ [join(here, "config.stub")]: "config/${name}.ts" }, "${name}-config");
+  }
+
+  boot(): void {
+    if (this.app.config().get("${name}.enabled") === false) return;
+    // Serve a bundled UI (after \`vite build\`): this.assets("${name}/assets", join(here, "ui"), { immutable: true });
+    this.routes((r: Router) => {
+      r.get("/", (c) => c.json({ package: "${name}", ok: true }));
+    }, { prefix: this.app.config().get("${name}.path", "${name}"), as: "${name}" });
+  }
+}
+`;
+}
 /** `name` is the class (e.g. "UserTransformer"); `model` is the value it maps. */
 export function transformerStub(name, model) {
     return `import { Transformer, type Attributes } from "@shaferllc/keel/core";
@@ -118,3 +157,69 @@ export class ${name} extends Transformer</* ${model} */ any> {
 }
 `;
 }
+/**
+ * A page — `resources/pages/<path>.tsx`. The file's location *is* its URL, so the
+ * stub is deliberately bare: a component, and a loader only when the path takes a
+ * parameter to load anything by.
+ */
+export function pageStub(file) {
+    const params = [...file.matchAll(/\[(?:\.\.\.)?([^\]]+)\]/g)].map((m) => m[1]);
+    const propsType = params.length
+        ? `{ ${params.map((p) => `${p}: string`).join("; ")} }`
+        : "Record<string, never>";
+    const loader = params.length
+        ? `
+export const loader = async (c: Ctx) => {
+  // Load whatever this page needs; it arrives as \`data\`.
+  return { ${params.map((p) => `${p}: c.req.param("${p}")`).join(", ")} };
+};
+`
+        : "";
+    const dataType = params.length ? propsType : "undefined";
+    // Only import Ctx when there's a loader to use it — an unused import would
+    // fail the very typecheck the generated file is supposed to pass.
+    const imports = params.length ? "Ctx, PageProps" : "PageProps";
+    return `import type { ${imports} } from "@shaferllc/keel/core";
+${loader}
+export default function Page({ params, data }: PageProps<${propsType}, ${dataType}>) {
+  void params;
+  void data;
+
+  return (
+    <main>
+      <h1>${file}</h1>
+    </main>
+  );
+}
+`;
+}
+/** A console command — `app/Commands/<name>.ts`. */
+export function commandStub(name) {
+    const varName = name.replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase()).replace(/^./, (c) => c.toLowerCase());
+    return `import { defineCommand, arg, flag } from "@shaferllc/keel/core";
+
+export const ${varName} = defineCommand({
+  name: "${name}",
+  description: "Describe what this command does",
+
+  args: {
+    // \`args.target\` is a string, inferred from this spec.
+    target: arg.string({ description: "what to act on" }),
+  },
+
+  flags: {
+    // \`flags.force\` is a boolean.
+    force: flag.boolean({ alias: "f", description: "skip the confirmation" }),
+  },
+
+  async run({ args, flags, ui, prompt }) {
+    if (!flags.force && !(await prompt.confirm(\`Really do this to \${args.target}?\`))) {
+      ui.warning("Cancelled.");
+      return 1;
+    }
+
+    ui.success(\`Done: \${args.target}\`);
+  },
+});
+`;
+}

package/dist/core/console-prompt.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Interactive prompts for console commands — ask, confirm, choice, and friends.
+ *
+ *   const name = await prompt.ask("What is your name?");
+ *   const ok = await prompt.confirm("Delete everything?");
+ *   const driver = await prompt.choice("Pick a driver", ["sqlite", "postgres"]);
+ *
+ * `node:readline` is imported dynamically, so the core still loads on the edge.
+ *
+ * ## Prompts are testable, which is the whole point
+ *
+ * A command that asks questions is normally a command you can't test. So a prompt
+ * can be **trapped**: you script the answer up front, and the prompt never
+ * touches the terminal.
+ *
+ *   const prompt = createPrompt({ trap: true });
+ *   prompt.trap("What is your name?").replyWith("Ada");
+ *   prompt.trap("Delete everything?").reject();
+ *
+ * An untrapped prompt in trap mode **throws** rather than hanging forever waiting
+ * on stdin that a test will never provide.
+ */
+export interface PromptOptions<T> {
+    /** Pressing enter accepts this. */
+    default?: T;
+    /** Shown in dim text beside the question. */
+    hint?: string;
+    /** Return true to accept, or a string explaining why not. */
+    validate?: (value: T) => true | string;
+    /** Transform the value before it's returned. */
+    result?: (value: T) => T;
+}
+export interface ChoiceOptions<T> extends PromptOptions<T> {
+    /** Show this many options at once. */
+    limit?: number;
+}
+/** A choice: a bare string, or a value with a label. */
+export type Choice = string | {
+    value: string;
+    label?: string;
+    hint?: string;
+};
+/** A scripted answer, waiting for the prompt that matches it. */
+export interface Trap {
+    /** Answer an `ask` / `secure` / `autocomplete`. */
+    replyWith(value: string): Trap;
+    /** Answer a `confirm` / `toggle` with yes. */
+    accept(): Trap;
+    /** Answer a `confirm` / `toggle` with no. */
+    reject(): Trap;
+    /** Answer a `choice` by index. */
+    chooseOption(index: number): Trap;
+    /** Answer a `multiple` by indexes. */
+    chooseOptions(indexes: number[]): Trap;
+    /** Assert the prompt's `validate` rejects this input, with this message. */
+    assertFails(value: string, message?: string): Trap;
+    /** Assert the prompt's `validate` accepts this input. */
+    assertPasses(value: string): Trap;
+}
+export interface Prompt {
+    ask(question: string, options?: PromptOptions<string>): Promise<string>;
+    /** Like `ask`, but the input isn't echoed. */
+    secure(question: string, options?: PromptOptions<string>): Promise<string>;
+    confirm(question: string, options?: PromptOptions<boolean>): Promise<boolean>;
+    /** A confirm with your own labels. */
+    toggle(question: string, labels: [string, string], options?: PromptOptions<boolean>): Promise<boolean>;
+    choice(question: string, choices: Choice[], options?: ChoiceOptions<string>): Promise<string>;
+    multiple(question: string, choices: Choice[], options?: ChoiceOptions<string[]>): Promise<string[]>;
+    autocomplete(question: string, choices: Choice[], options?: ChoiceOptions<string>): Promise<string>;
+    /** Script an answer for a question, so a test never blocks on stdin. */
+    trap(question: string): Trap;
+    /** Whether every trapped question was actually asked. */
+    assertAllTrapsUsed(): void;
+}
+export interface PromptFactoryOptions {
+    /** Answer from traps instead of the terminal. Tests set this. */
+    trap?: boolean;
+}
+export declare function createPrompt(options?: PromptFactoryOptions): Prompt;

package/dist/core/console-prompt.js

@@ -0,0 +1,239 @@
+/**
+ * Interactive prompts for console commands — ask, confirm, choice, and friends.
+ *
+ *   const name = await prompt.ask("What is your name?");
+ *   const ok = await prompt.confirm("Delete everything?");
+ *   const driver = await prompt.choice("Pick a driver", ["sqlite", "postgres"]);
+ *
+ * `node:readline` is imported dynamically, so the core still loads on the edge.
+ *
+ * ## Prompts are testable, which is the whole point
+ *
+ * A command that asks questions is normally a command you can't test. So a prompt
+ * can be **trapped**: you script the answer up front, and the prompt never
+ * touches the terminal.
+ *
+ *   const prompt = createPrompt({ trap: true });
+ *   prompt.trap("What is your name?").replyWith("Ada");
+ *   prompt.trap("Delete everything?").reject();
+ *
+ * An untrapped prompt in trap mode **throws** rather than hanging forever waiting
+ * on stdin that a test will never provide.
+ */
+const valueOf = (choice) => (typeof choice === "string" ? choice : choice.value);
+const labelOf = (choice) => typeof choice === "string" ? choice : (choice.label ?? choice.value);
+export function createPrompt(options = {}) {
+    const traps = new Map();
+    const trapping = options.trap ?? false;
+    /** Read one line from the terminal. */
+    async function readLine(question, mask = false) {
+        const readline = await import("node:readline");
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: true,
+        });
+        // For a secure prompt, swallow the echo so the password isn't left on screen.
+        if (mask) {
+            const output = rl;
+            const original = output.output.write.bind(output.output);
+            output.output.write = (chunk) => {
+                if (chunk.includes(question))
+                    original(chunk);
+            };
+        }
+        return new Promise((resolve) => {
+            rl.question(question, (answer) => {
+                rl.close();
+                if (mask)
+                    process.stdout.write("\n");
+                resolve(answer);
+            });
+        });
+    }
+    /**
+     * Resolve a question from its trap, running whatever assertions were attached.
+     * Returns `undefined` when there's no trap — the caller decides what that means.
+     */
+    function fromTrap(question, validate) {
+        const state = traps.get(question);
+        if (!state)
+            return undefined;
+        for (const { value, message } of state.expectFail) {
+            const result = validate ? validate(value) : true;
+            if (result === true) {
+                throw new Error(`Expected the prompt "${question}" to reject ${JSON.stringify(value)}, but it passed.`);
+            }
+            if (message !== undefined && result !== message) {
+                throw new Error(`Expected the prompt "${question}" to reject ${JSON.stringify(value)} with "${message}", got "${result}".`);
+            }
+        }
+        for (const value of state.expectPass) {
+            const result = validate ? validate(value) : true;
+            if (result !== true) {
+                throw new Error(`Expected the prompt "${question}" to accept ${JSON.stringify(value)}, but it said "${result}".`);
+            }
+        }
+        state.answered = true;
+        return state.answer;
+    }
+    /** Nothing scripted this question, and there's no terminal to ask. */
+    function untrapped(question) {
+        throw new Error(`The prompt "${question}" was not trapped. Script it with prompt.trap(${JSON.stringify(question)}).replyWith(…) — ` +
+            `otherwise the command would block forever waiting for input a test can't give it.`);
+    }
+    function check(question, value, options) {
+        const problem = options?.validate?.(value);
+        if (problem !== undefined && problem !== true)
+            throw new Error(`${question}: ${problem}`);
+        return options?.result ? options.result(value) : value;
+    }
+    const prompt = {
+        async ask(question, options) {
+            if (trapping) {
+                const answer = fromTrap(question, options?.validate);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            const hint = options?.default ? ` (${options.default})` : "";
+            const raw = (await readLine(`${question}${hint} `)).trim();
+            const value = raw || options?.default || "";
+            const problem = options?.validate?.(value);
+            // Ask again rather than dying — a typo shouldn't cost them the whole command.
+            if (problem !== undefined && problem !== true) {
+                console.error(problem);
+                return prompt.ask(question, options);
+            }
+            return options?.result ? options.result(value) : value;
+        },
+        async secure(question, options) {
+            if (trapping) {
+                const answer = fromTrap(question, options?.validate);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            const value = (await readLine(`${question} `, true)).trim();
+            return check(question, value, options);
+        },
+        async confirm(question, options) {
+            return prompt.toggle(question, ["y", "n"], options);
+        },
+        async toggle(question, labels, options) {
+            if (trapping) {
+                const answer = fromTrap(question, options?.validate);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            const fallback = options?.default ?? false;
+            const hint = fallback ? `[${labels[0].toUpperCase()}/${labels[1]}]` : `[${labels[0]}/${labels[1].toUpperCase()}]`;
+            const raw = (await readLine(`${question} ${hint} `)).trim().toLowerCase();
+            const value = raw === "" ? fallback : raw === labels[0].toLowerCase() || raw === "yes" || raw === "true";
+            return check(question, value, options);
+        },
+        async choice(question, choices, options) {
+            if (trapping) {
+                const index = fromTrap(question);
+                if (index === undefined)
+                    untrapped(question);
+                const choice = choices[index];
+                if (!choice)
+                    throw new Error(`The prompt "${question}" has no option at index ${index}.`);
+                return check(question, valueOf(choice), options);
+            }
+            console.log(question);
+            choices.forEach((choice, i) => console.log(`  ${i + 1}) ${labelOf(choice)}`));
+            const raw = (await readLine("> ")).trim();
+            const index = Number(raw) - 1;
+            const choice = choices[index];
+            if (!choice) {
+                console.error(`Pick a number between 1 and ${choices.length}.`);
+                return prompt.choice(question, choices, options);
+            }
+            return check(question, valueOf(choice), options);
+        },
+        async multiple(question, choices, options) {
+            if (trapping) {
+                const indexes = fromTrap(question);
+                if (indexes === undefined)
+                    untrapped(question);
+                const values = indexes.map((i) => {
+                    const choice = choices[i];
+                    if (!choice)
+                        throw new Error(`The prompt "${question}" has no option at index ${i}.`);
+                    return valueOf(choice);
+                });
+                return check(question, values, options);
+            }
+            console.log(`${question} (comma-separated numbers)`);
+            choices.forEach((choice, i) => console.log(`  ${i + 1}) ${labelOf(choice)}`));
+            const raw = (await readLine("> ")).trim();
+            const values = raw
+                .split(",")
+                .map((part) => choices[Number(part.trim()) - 1])
+                .filter((choice) => choice !== undefined)
+                .map(valueOf);
+            return check(question, values, options);
+        },
+        async autocomplete(question, choices, options) {
+            if (trapping) {
+                const answer = fromTrap(question);
+                if (answer === undefined)
+                    untrapped(question);
+                return check(question, answer, options);
+            }
+            // Without a raw-mode TTY there's no live filtering to do, so it degrades to
+            // a plain choice list rather than pretending.
+            return prompt.choice(question, choices, options);
+        },
+        trap(question) {
+            const state = {
+                question,
+                answered: false,
+                expectFail: [],
+                expectPass: [],
+            };
+            traps.set(question, state);
+            const api = {
+                replyWith(value) {
+                    state.answer = value;
+                    return api;
+                },
+                accept() {
+                    state.answer = true;
+                    return api;
+                },
+                reject() {
+                    state.answer = false;
+                    return api;
+                },
+                chooseOption(index) {
+                    state.answer = index;
+                    return api;
+                },
+                chooseOptions(indexes) {
+                    state.answer = indexes;
+                    return api;
+                },
+                assertFails(value, message) {
+                    state.expectFail.push({ value, message });
+                    return api;
+                },
+                assertPasses(value) {
+                    state.expectPass.push(value);
+                    return api;
+                },
+            };
+            return api;
+        },
+        assertAllTrapsUsed() {
+            const unused = [...traps.values()].filter((t) => !t.answered).map((t) => t.question);
+            if (unused.length) {
+                throw new Error(`These prompts were trapped but never asked: ${unused.map((q) => `"${q}"`).join(", ")}.`);
+            }
+        },
+    };
+    return prompt;
+}

package/dist/core/console-ui.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Terminal UI for console commands — colors, a logger, tables, boxes, and a task
+ * runner. No dependency: ANSI codes are a dozen escape sequences, not a package.
+ *
+ *   ui.success("Migrated 3 tables");
+ *   ui.table(["Name", "Rows"]).row(["users", "42"]).render();
+ *
+ * Everything goes through the same `write`, which is what makes the whole thing
+ * testable: `createUi({ raw: true })` strips the colors and buffers the output
+ * instead of printing it, so a test can assert on exactly what a command said.
+ */
+declare const CODES: {
+    readonly reset: 0;
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly italic: 3;
+    readonly underline: 4;
+    readonly red: 31;
+    readonly green: 32;
+    readonly yellow: 33;
+    readonly blue: 34;
+    readonly magenta: 35;
+    readonly cyan: 36;
+    readonly white: 37;
+    readonly gray: 90;
+    readonly bgRed: 41;
+    readonly bgGreen: 42;
+    readonly bgYellow: 43;
+};
+export type ColorName = keyof typeof CODES;
+/** Paint text, or don't — the same call site works either way. */
+export interface Colors {
+    (name: ColorName, text: string): string;
+    readonly enabled: boolean;
+}
+/** Strip ANSI escapes — used by the raw mode, and handy in assertions. */
+export declare function stripAnsi(text: string): string;
+export interface Table {
+    head(...columns: string[]): Table;
+    row(cells: string[]): Table;
+    rows(rows: string[][]): Table;
+    /** Render it and write it out. */
+    render(): void;
+    /** Render it to a string instead of writing it. */
+    toString(): string;
+}
+/** What a single task can report while it runs. */
+export interface TaskHandle {
+    update(message: string): void;
+}
+export interface Tasks {
+    add(title: string, run: (task: TaskHandle) => Promise<string | void> | string | void): Tasks;
+    /** Run them in order. Resolves to false if any task failed. */
+    run(): Promise<boolean>;
+}
+export interface UiOptions {
+    /**
+     * Buffer output instead of printing it, and drop the colors. What tests use —
+     * `ui.logs` then holds every line.
+     */
+    raw?: boolean;
+    /** Force colors on or off. Defaults to on unless raw, or NO_COLOR is set. */
+    colors?: boolean;
+}
+export interface Ui {
+    readonly colors: Colors;
+    /** In raw mode, every line written. Empty otherwise. */
+    readonly logs: string[];
+    /** In raw mode, every line written to stderr. */
+    readonly errors: string[];
+    /** Write a line verbatim. */
+    write(line: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    success(message: string): void;
+    warning(message: string): void;
+    /** Goes to stderr. */
+    error(message: string): void;
+    /** Goes to stderr. */
+    fatal(message: string): void;
+    /**
+     * A one-line status for something you did: `CREATE  app/Models/User.ts`.
+     * The verb is padded so a run of them lines up.
+     */
+    action(verb: string, target: string, status?: "done" | "skipped" | "failed"): void;
+    table(head?: string[]): Table;
+    /** A boxed message — for the thing you want them to actually read. */
+    sticker(lines: string[], title?: string): void;
+    /** Numbered next-steps. */
+    instructions(lines: string[], title?: string): void;
+    tasks(): Tasks;
+    /** Clear the captured buffers (raw mode). */
+    clear(): void;
+}
+export declare function createUi(options?: UiOptions): Ui;
+export {};