@moku-labs/web 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1748,12 +1748,21 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
     durationMs: number;
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$4 {
-  export { Api$2 as Api, Config$2 as Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WranglerErrorKind };
-}
+//#endregion
+//#region src/plugins/deploy/generators/github-workflow.d.ts
 /**
- * @file deploy plugin — type definitions.
+ * What triggers the generated deploy workflow:
+ * - `"auto"` — every push to `main` (plus the manual "Run workflow" button).
+ * - `"versioned-tag"` — pushing a `v*` semver tag (plus the manual button).
+ * - `"dispatch"` — only the manual "Run workflow" button (no automation).
+ *
+ * @example
+ * const trigger: WorkflowTrigger = "versioned-tag";
  */
+type WorkflowTrigger = "auto" | "versioned-tag" | "dispatch";
+declare namespace types_d_exports$4 {
+  export { Api$2 as Api, Config$2 as Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WorkflowTrigger, WranglerErrorKind };
+}
 /**
  * Options passed to the injected spawner — the subset of Bun.spawn's options the
  * plugin uses (piped stdout/stderr plus an env carrying the API token).
@@ -1867,6 +1876,11 @@ type DeployRunOptions = {
 type DeployInitOptions = {
   /** Also generate the GitHub Actions workflow. Defaults to config.ci. */ci?: boolean; /** Drift-only mode: report differences without writing any files. Defaults to `false`. */
   check?: boolean;
+  /**
+   * What triggers the generated workflow (see {@link WorkflowTrigger}): `"auto"` (push to
+   * main), `"versioned-tag"` (push a `v*` tag), or `"dispatch"` (manual only). Default `"auto"`.
+   */
+  workflowTrigger?: WorkflowTrigger;
 };
 /**
  * Result of an init/scaffold operation.
@@ -2013,8 +2027,23 @@ type CliRenderer = {
    */
   serverReady(info: ServerInfo): void;
   /**
-   * Render the post-rebuild line ("~ dir" + "✓ rebuilt N pages · Xms · reloaded"),
-   * where the label is the watched directory whose subtree changed (see {@link ReloadInfo.file}).
+   * Begin a serve() rebuild: show ONE compact, in-place "rebuilding {label}…" line
+   * (a live spinner on a TTY) and suppress the verbose per-phase rows + BUILD summary
+   * box until the matching {@link reload} (or {@link error}) settles it. The initial
+   * build is NOT a rebuild — it still renders the full live phase list. Without this
+   * gate, every keystroke reprinted the entire build log.
+   *
+   * @param label - The changed watch target shown in the line (e.g. "content").
+   * @returns Nothing.
+   * @example
+   * render.rebuildStart("content");
+   */
+  rebuildStart(label: string): void;
+  /**
+   * Settle a serve() rebuild started by {@link rebuildStart}: replace the in-place
+   * "rebuilding…" line with a compact "✓ rebuilt N pages · Xs · reloaded" result and
+   * re-enable verbose build output. The label is the watched directory whose subtree
+   * changed (see {@link ReloadInfo.file}).
    *
    * @param info - The changed watched directory plus the rebuild's page count and duration.
    * @returns Nothing.
@@ -2059,6 +2088,27 @@ type CliRenderer = {
    * render.error("build failed", err);
    */
   error(message: string, cause?: unknown): void;
+  /**
+   * Render a section heading for a multi-step flow (e.g. the guided deploy wizard).
+   *
+   * @param text - The heading label.
+   * @returns Nothing.
+   * @example
+   * render.heading("Diagnostics");
+   */
+  heading(text: string): void;
+  /**
+   * Render one diagnostic line — a green `✓` (pass) or red `✗` (fail) before the label,
+   * with optional dim, indented detail beneath it (e.g. how to fix a failing check).
+   *
+   * @param ok - Whether the check passed.
+   * @param label - The check label.
+   * @param detail - Optional multi-line guidance shown indented under the line.
+   * @returns Nothing.
+   * @example
+   * render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
+   */
+  check(ok: boolean, label: string, detail?: string): void;
 };
 /**
  * A live directory watcher handle returned by the injectable `watch` seam. Closing
@@ -2115,6 +2165,14 @@ type ServeStaticOptions = {
    * fetch(req) { return new Response("ok"); }
    */
   fetch(request: Request): Response | Promise<Response>;
+  /**
+   * Idle timeout in SECONDS before the server severs a connection with no traffic
+   * (Bun semantics; `0` disables it, max `255`). The dev server passes `0` so the
+   * long-lived live-reload SSE stream is never cut — Bun's 10s default closes it,
+   * which the browser surfaces as `ERR_INCOMPLETE_CHUNKED_ENCODING` and then
+   * reconnects in an endless storm. Omitted by `preview()` (short static requests).
+   */
+  idleTimeout?: number;
 };
 /**
  * An injectable static-server factory (defaults to `Bun.serve`). Keeps the Bun
@@ -2169,6 +2227,18 @@ type State$1 = {
    * const ok = await state.confirm("Deploy dist/?");
    */
   confirm: (question: string) => Promise<boolean>;
+  /**
+   * Interactive single-choice prompt used by the guided deploy wizard. Presents the
+   * `choices` numbered from 1 and resolves the chosen zero-based index (clamped to a
+   * valid choice). Default reads stdin (TTY); tests inject a canned selection.
+   *
+   * @param question - The prompt to display.
+   * @param choices - The selectable option labels.
+   * @returns Resolves the chosen zero-based index.
+   * @example
+   * const i = await state.select("Workflow trigger?", ["Auto on push", "Manual only"]);
+   */
+  select: (question: string, choices: readonly string[]) => Promise<number>;
   /**
    * Monotonic clock for durations. Default `Date.now`; tests inject for deterministic timing.
    *
@@ -2182,12 +2252,14 @@ type State$1 = {
    * tests inject a fake emitter.
    *
    * @param dir - The directory to watch recursively.
-   * @param onChange - Invoked on any change beneath `dir`.
+   * @param onChange - Invoked on any change beneath `dir`, with the changed path
+   *   relative to `dir` when the platform reports it (`undefined` otherwise). serve()
+   *   uses it to ignore `outDir`/noise writes and to drop duplicate events by mtime.
    * @returns A handle whose `close()` detaches the watcher.
    * @example
-   * const handle = state.watch("content", () => rebuild());
+   * const handle = state.watch("content", file => rebuild(file));
    */
-  watch: (dir: string, onChange: () => void) => WatchHandle; /** Static-server factory used by serve()/preview(). Default `Bun.serve`; tests inject a fake. */
+  watch: (dir: string, onChange: (filename?: string) => void) => WatchHandle; /** Static-server factory used by serve()/preview(). Default `Bun.serve`; tests inject a fake. */
   serveStatic: ServeStaticFunction; /** File-response factory mapping a resolved path + status to a `Response`. Default `Bun.file`. */
   fileResponse: FileResponseFunction;
   /**
@@ -2200,6 +2272,18 @@ type State$1 = {
    * const url = state.networkUrl(4173);
    */
   networkUrl: (port: number) => string | null;
+  /**
+   * Resolve a file's modification time in epoch milliseconds, or `null` when it does
+   * not exist. serve() uses it to collapse the burst of duplicate `fs.watch` events
+   * macOS emits per save (same mtime ⇒ already-built ⇒ ignored) into one rebuild.
+   * Default wraps `node:fs.statSync`; tests inject deterministic values.
+   *
+   * @param path - The absolute path to stat.
+   * @returns The mtime in milliseconds, or `null` when the file is missing.
+   * @example
+   * const mtime = state.fileMtime("/abs/content/a.md");
+   */
+  fileMtime: (path: string) => number | null;
 };
 /**
  * Summary returned by `cli.build()` — the awaited `build.run()` result.
@@ -2214,9 +2298,10 @@ type BuildSummary = {
 };
 /**
  * Outcome returned by `cli.deploy()` — either a completed deploy (with details) or a
- * skipped one. A skip happens only when an interactive TTY user answers "no" at the
- * confirm prompt (`reason: "declined"`). Non-interactive runs (CI / non-TTY) never
- * prompt and always proceed, so they never skip — the scripts are CI-safe.
+ * skipped one. A skip is `"declined"` when a user answers "no" at the confirm prompt,
+ * or `"blocked"` when the guided wizard found unmet prerequisites and stopped before
+ * deploying. Non-interactive direct runs (CI / non-TTY) never prompt and always proceed,
+ * so they never skip — the scripts are CI-safe.
  *
  * @example
  * const outcome: DeployOutcome = { deployed: false, reason: "declined" };
@@ -2229,7 +2314,7 @@ type DeployOutcome = {
   durationMs: number;
 } | {
   deployed: false;
-  reason: "declined";
+  reason: "declined" | "blocked";
 };
 /**
  * Options for `cli.build()`.
@@ -2268,6 +2353,13 @@ type PreviewOptions = {
 type DeployOptions = {
   /** Branch to deploy. Defaults to the deploy plugin's production branch. */branch?: string; /** Skip the y/N confirm and deploy immediately. Defaults to `false`. */
   yes?: boolean;
+  /**
+   * Run the guided, interactive setup wizard instead of the direct `--cli` deploy:
+   * diagnose prerequisites, guide the user to fix anything missing, gate the deploy on
+   * everything being green, then offer to scaffold a GitHub Actions workflow. Defaults
+   * to `false` (the direct, CI-safe path). Thin scripts pass `{ guided: !"--cli" }`.
+   */
+  guided?: boolean;
 };
 /**
  * Public API of the cli plugin (mounted at `app.cli`) — exactly four methods.

package/dist/index.d.mts

@@ -1748,12 +1748,21 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
     durationMs: number;
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$4 {
-  export { Api$2 as Api, Config$2 as Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WranglerErrorKind };
-}
+//#endregion
+//#region src/plugins/deploy/generators/github-workflow.d.ts
 /**
- * @file deploy plugin — type definitions.
+ * What triggers the generated deploy workflow:
+ * - `"auto"` — every push to `main` (plus the manual "Run workflow" button).
+ * - `"versioned-tag"` — pushing a `v*` semver tag (plus the manual button).
+ * - `"dispatch"` — only the manual "Run workflow" button (no automation).
+ *
+ * @example
+ * const trigger: WorkflowTrigger = "versioned-tag";
  */
+type WorkflowTrigger = "auto" | "versioned-tag" | "dispatch";
+declare namespace types_d_exports$4 {
+  export { Api$2 as Api, Config$2 as Config, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WorkflowTrigger, WranglerErrorKind };
+}
 /**
  * Options passed to the injected spawner — the subset of Bun.spawn's options the
  * plugin uses (piped stdout/stderr plus an env carrying the API token).
@@ -1867,6 +1876,11 @@ type DeployRunOptions = {
 type DeployInitOptions = {
   /** Also generate the GitHub Actions workflow. Defaults to config.ci. */ci?: boolean; /** Drift-only mode: report differences without writing any files. Defaults to `false`. */
   check?: boolean;
+  /**
+   * What triggers the generated workflow (see {@link WorkflowTrigger}): `"auto"` (push to
+   * main), `"versioned-tag"` (push a `v*` tag), or `"dispatch"` (manual only). Default `"auto"`.
+   */
+  workflowTrigger?: WorkflowTrigger;
 };
 /**
  * Result of an init/scaffold operation.
@@ -2013,8 +2027,23 @@ type CliRenderer = {
    */
   serverReady(info: ServerInfo): void;
   /**
-   * Render the post-rebuild line ("~ dir" + "✓ rebuilt N pages · Xms · reloaded"),
-   * where the label is the watched directory whose subtree changed (see {@link ReloadInfo.file}).
+   * Begin a serve() rebuild: show ONE compact, in-place "rebuilding {label}…" line
+   * (a live spinner on a TTY) and suppress the verbose per-phase rows + BUILD summary
+   * box until the matching {@link reload} (or {@link error}) settles it. The initial
+   * build is NOT a rebuild — it still renders the full live phase list. Without this
+   * gate, every keystroke reprinted the entire build log.
+   *
+   * @param label - The changed watch target shown in the line (e.g. "content").
+   * @returns Nothing.
+   * @example
+   * render.rebuildStart("content");
+   */
+  rebuildStart(label: string): void;
+  /**
+   * Settle a serve() rebuild started by {@link rebuildStart}: replace the in-place
+   * "rebuilding…" line with a compact "✓ rebuilt N pages · Xs · reloaded" result and
+   * re-enable verbose build output. The label is the watched directory whose subtree
+   * changed (see {@link ReloadInfo.file}).
    *
    * @param info - The changed watched directory plus the rebuild's page count and duration.
    * @returns Nothing.
@@ -2059,6 +2088,27 @@ type CliRenderer = {
    * render.error("build failed", err);
    */
   error(message: string, cause?: unknown): void;
+  /**
+   * Render a section heading for a multi-step flow (e.g. the guided deploy wizard).
+   *
+   * @param text - The heading label.
+   * @returns Nothing.
+   * @example
+   * render.heading("Diagnostics");
+   */
+  heading(text: string): void;
+  /**
+   * Render one diagnostic line — a green `✓` (pass) or red `✗` (fail) before the label,
+   * with optional dim, indented detail beneath it (e.g. how to fix a failing check).
+   *
+   * @param ok - Whether the check passed.
+   * @param label - The check label.
+   * @param detail - Optional multi-line guidance shown indented under the line.
+   * @returns Nothing.
+   * @example
+   * render.check(false, "CLOUDFLARE_API_TOKEN is set", "Create one at …");
+   */
+  check(ok: boolean, label: string, detail?: string): void;
 };
 /**
  * A live directory watcher handle returned by the injectable `watch` seam. Closing
@@ -2115,6 +2165,14 @@ type ServeStaticOptions = {
    * fetch(req) { return new Response("ok"); }
    */
   fetch(request: Request): Response | Promise<Response>;
+  /**
+   * Idle timeout in SECONDS before the server severs a connection with no traffic
+   * (Bun semantics; `0` disables it, max `255`). The dev server passes `0` so the
+   * long-lived live-reload SSE stream is never cut — Bun's 10s default closes it,
+   * which the browser surfaces as `ERR_INCOMPLETE_CHUNKED_ENCODING` and then
+   * reconnects in an endless storm. Omitted by `preview()` (short static requests).
+   */
+  idleTimeout?: number;
 };
 /**
  * An injectable static-server factory (defaults to `Bun.serve`). Keeps the Bun
@@ -2169,6 +2227,18 @@ type State$1 = {
    * const ok = await state.confirm("Deploy dist/?");
    */
   confirm: (question: string) => Promise<boolean>;
+  /**
+   * Interactive single-choice prompt used by the guided deploy wizard. Presents the
+   * `choices` numbered from 1 and resolves the chosen zero-based index (clamped to a
+   * valid choice). Default reads stdin (TTY); tests inject a canned selection.
+   *
+   * @param question - The prompt to display.
+   * @param choices - The selectable option labels.
+   * @returns Resolves the chosen zero-based index.
+   * @example
+   * const i = await state.select("Workflow trigger?", ["Auto on push", "Manual only"]);
+   */
+  select: (question: string, choices: readonly string[]) => Promise<number>;
   /**
    * Monotonic clock for durations. Default `Date.now`; tests inject for deterministic timing.
    *
@@ -2182,12 +2252,14 @@ type State$1 = {
    * tests inject a fake emitter.
    *
    * @param dir - The directory to watch recursively.
-   * @param onChange - Invoked on any change beneath `dir`.
+   * @param onChange - Invoked on any change beneath `dir`, with the changed path
+   *   relative to `dir` when the platform reports it (`undefined` otherwise). serve()
+   *   uses it to ignore `outDir`/noise writes and to drop duplicate events by mtime.
    * @returns A handle whose `close()` detaches the watcher.
    * @example
-   * const handle = state.watch("content", () => rebuild());
+   * const handle = state.watch("content", file => rebuild(file));
    */
-  watch: (dir: string, onChange: () => void) => WatchHandle; /** Static-server factory used by serve()/preview(). Default `Bun.serve`; tests inject a fake. */
+  watch: (dir: string, onChange: (filename?: string) => void) => WatchHandle; /** Static-server factory used by serve()/preview(). Default `Bun.serve`; tests inject a fake. */
   serveStatic: ServeStaticFunction; /** File-response factory mapping a resolved path + status to a `Response`. Default `Bun.file`. */
   fileResponse: FileResponseFunction;
   /**
@@ -2200,6 +2272,18 @@ type State$1 = {
    * const url = state.networkUrl(4173);
    */
   networkUrl: (port: number) => string | null;
+  /**
+   * Resolve a file's modification time in epoch milliseconds, or `null` when it does
+   * not exist. serve() uses it to collapse the burst of duplicate `fs.watch` events
+   * macOS emits per save (same mtime ⇒ already-built ⇒ ignored) into one rebuild.
+   * Default wraps `node:fs.statSync`; tests inject deterministic values.
+   *
+   * @param path - The absolute path to stat.
+   * @returns The mtime in milliseconds, or `null` when the file is missing.
+   * @example
+   * const mtime = state.fileMtime("/abs/content/a.md");
+   */
+  fileMtime: (path: string) => number | null;
 };
 /**
  * Summary returned by `cli.build()` — the awaited `build.run()` result.
@@ -2214,9 +2298,10 @@ type BuildSummary = {
 };
 /**
  * Outcome returned by `cli.deploy()` — either a completed deploy (with details) or a
- * skipped one. A skip happens only when an interactive TTY user answers "no" at the
- * confirm prompt (`reason: "declined"`). Non-interactive runs (CI / non-TTY) never
- * prompt and always proceed, so they never skip — the scripts are CI-safe.
+ * skipped one. A skip is `"declined"` when a user answers "no" at the confirm prompt,
+ * or `"blocked"` when the guided wizard found unmet prerequisites and stopped before
+ * deploying. Non-interactive direct runs (CI / non-TTY) never prompt and always proceed,
+ * so they never skip — the scripts are CI-safe.
  *
  * @example
  * const outcome: DeployOutcome = { deployed: false, reason: "declined" };
@@ -2229,7 +2314,7 @@ type DeployOutcome = {
   durationMs: number;
 } | {
   deployed: false;
-  reason: "declined";
+  reason: "declined" | "blocked";
 };
 /**
  * Options for `cli.build()`.
@@ -2268,6 +2353,13 @@ type PreviewOptions = {
 type DeployOptions = {
   /** Branch to deploy. Defaults to the deploy plugin's production branch. */branch?: string; /** Skip the y/N confirm and deploy immediately. Defaults to `false`. */
   yes?: boolean;
+  /**
+   * Run the guided, interactive setup wizard instead of the direct `--cli` deploy:
+   * diagnose prerequisites, guide the user to fix anything missing, gate the deploy on
+   * everything being green, then offer to scaffold a GitHub Actions workflow. Defaults
+   * to `false` (the direct, CI-safe path). Thin scripts pass `{ guided: !"--cli" }`.
+   */
+  guided?: boolean;
 };
 /**
  * Public API of the cli plugin (mounted at `app.cli`) — exactly four methods.