@moku-labs/worker 0.4.0 → 0.5.0

package/dist/cli.d.cts

@@ -1,76 +1,24 @@
 import { PluginCtx, PluginInstance } from "@moku-labs/core";
 
-//#region src/plugins/cli/types.d.ts
-/**
- * @file cli plugin — type definitions (Config, Api).
- */
-/** Resolved configuration for the cli plugin. Flat; complete defaults so omission never yields undefined. */
-type Config$1 = {
-  /**
-   * Default local dev port forwarded to deploy.dev when dev() gets no port.
-   * Passed through to `wrangler dev --port <n>`.
-   *
-   * @default 8787
-   */
-  readonly port: number;
-};
-/** Public api surface of the cli plugin, mounted at app.cli.*. */
-type Api = {
-  /**
-   * Run the Worker locally via Wrangler (delegates to deploy.dev).
-   * Defaults port to the configured value (8787) when called with no opts.
-   *
-   * @param opts - Optional port override.
-   * @param opts.port - Local dev port to bind.
-   * @returns Resolves when the dev session ends.
-   * @example
-   * ```ts
-   * await app.cli.dev();            // port 8787
-   * await app.cli.dev({ port: 3000 }); // port 3000
-   * ```
-   */
-  dev(opts?: {
-    port?: number;
-  }): Promise<void>;
-  /**
-   * One-command guided Cloudflare deploy (delegates to deploy.run).
-   * Forwards opts verbatim — passes undefined when called with no opts.
-   *
-   * @param opts - Optional guided/yes flags.
-   * @param opts.guided - Walk through each step interactively.
-   * @param opts.yes - Skip confirmation prompts (non-interactive).
-   * @returns Resolves once the deploy completes.
-   * @example
-   * ```ts
-   * await app.cli.deploy({ guided: true });
-   * await app.cli.deploy({ yes: true }); // CI
-   * await app.cli.deploy(); // no opts → undefined forwarded
-   * ```
-   */
-  deploy(opts?: {
-    guided?: boolean;
-    yes?: boolean;
-  }): Promise<void>;
-};
-//#endregion
-//#region src/plugins/cli/index.d.ts
+//#region src/plugins/deploy/types.d.ts
 /**
- * Standard tier (node-only) — developer-facing CLI surface.
- *
- * Mounts `app.cli.dev()` and `app.cli.deploy()` as thin passthroughs to deployPlugin.
- * Hooks subscribe to the global deploy:phase / provision:resource / deploy:complete events
- * and print a live progress TUI via the injected ctx.log core API.
- *
- * Inline lambdas on `api`/`hooks` preserve event-name inference so the hook map keys
- * are constrained to `WorkerEvents` keys (spec/15 §5).
+ * A web-site build hook wired in from the consumer's deploy/dev script — e.g.
+ * `() => webApp.cli.build()`. This is the seam that lets one small app-side script compose a
+ * Moku Web app with this Worker framework: `dev` / `deploy` invoke it to (re)build the site
+ * before serving or deploying. May resolve a `{ files }` count (surfaced in `dev:rebuilt`) or
+ * nothing.
  *
- * @see README.md
+ * @returns Resolves when the web build completes; optionally a rebuilt-file count.
+ * @example
+ * ```ts
+ * await server.cli.dev({ webBuild: () => web.cli.build() });
+ * ```
  */
-declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, Record<string, never>, Api, {}> & Record<never, never>;
-//#endregion
-//#region src/plugins/deploy/types.d.ts
+type WebBuild = () => Promise<void> | Promise<{
+  files?: number;
+}>;
 /** deploy plugin configuration. Flat; complete defaults so omission never yields undefined. */
-type Config = {
+type Config$1 = {
   /**
    * Wrangler config file generated/updated and read by `wrangler deploy`. Default "wrangler.jsonc".
    * Also the file parsed in the universal/non-moku path.
@@ -81,7 +29,18 @@ type Config = {
    * CF credentials are read from the Node env (CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID).
    * Default false.
    */
-  ci: boolean;
+  ci: boolean; /** Globs watched by `dev()` to trigger a Moku-site rebuild. */
+  watch: string[];
+  /**
+   * Standing default web-site build hook (e.g. `() => webApp.cli.build()`). Usually passed
+   * call-time to `dev` / `deploy` via `opts.webBuild` (the script-driven path); set here only for
+   * a persistent default. When absent, dev() falls back to `buildCommand`, then auto-detects
+   * `scripts/build.ts`.
+   */
+  webBuild?: WebBuild; /** Shell rebuild fallback (e.g. "bun run scripts/build.ts"); empty → auto-detect scripts/build.ts. */
+  buildCommand: string; /** Apply local D1 migrations before serving when a d1 manifest is present. */
+  migrateLocal: boolean; /** Debounce window (ms) coalescing rapid file changes into one rebuild. */
+  debounceMs: number;
 };
 /** Discriminated union of resource descriptors returned by each plugin's deployManifest(). */
 type ResourceManifest = {
@@ -138,6 +97,141 @@ type ProvisionResult = {
   skipped: ProvisionedRef[]; /** Merged binding → Cloudflare id map (existing + created) for writeWranglerConfig. */
   ids: Record<string, string>;
 };
+/** Result of verifying the `.env` Cloudflare API token and resolving its account. */
+type AuthStatus = {
+  /** Whether the token is present and active. */ok: boolean; /** Resolved account display name (or id when the name is unknown). */
+  account: string; /** Resolved Cloudflare account id. */
+  accountId: string; /** Token scopes, when discoverable (empty otherwise). */
+  scopes: string[];
+};
+/** One Cloudflare API-token permission group the app's manifest requires. */
+type PermissionGroup = {
+  /** Human-readable group label, e.g. "Account · D1". */group: string; /** Permission scope. */
+  scope: "Edit" | "Read"; /** Why it is required, e.g. "d1", "queue", "deploy", "account". */
+  reason: string; /** Whether Cloudflare's stock "Edit Cloudflare Workers" template already includes it. */
+  inBaseTemplate: boolean;
+};
+/** The Cloudflare API token this app requires, derived from its manifest. */
+type TokenRequirement = {
+  /** The recommended starting template. */base: "Edit Cloudflare Workers"; /** The full set of permission groups required. */
+  required: PermissionGroup[]; /** Groups NOT in the base template that the user must add (e.g. D1, Queues). */
+  toAdd: PermissionGroup[];
+};
+//#endregion
+//#region src/plugins/cli/types.d.ts
+/** Resolved configuration for the cli plugin. Flat; complete defaults so omission never yields undefined. */
+type Config = {
+  /**
+   * Default local dev port forwarded to deploy.dev when dev() gets no port.
+   * Passed through to `wrangler dev --port <n>`.
+   *
+   * @default 8787
+   */
+  readonly port: number;
+};
+/** Public api surface of the cli plugin, mounted at app.cli.*. */
+type Api = {
+  /**
+   * Run the Worker locally via Wrangler (delegates to deploy.dev).
+   * Defaults port to the configured value (8787) when called with no opts.
+   *
+   * @param opts - Optional port override and web build hook.
+   * @param opts.port - Local dev port to bind.
+   * @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
+   * @returns Resolves when the dev session ends.
+   * @example
+   * ```ts
+   * await app.cli.dev();                               // port 8787, worker only
+   * await app.cli.dev({ webBuild: () => web.cli.build() }); // wire the web build in
+   * ```
+   */
+  dev(opts?: {
+    port?: number;
+    webBuild?: WebBuild;
+  }): Promise<void>;
+  /**
+   * One-command guided Cloudflare deploy (delegates to deploy.run).
+   * Forwards opts verbatim — passes undefined when called with no opts.
+   *
+   * @param opts - Optional guided/yes flags and a web build hook.
+   * @param opts.guided - Walk through each step interactively.
+   * @param opts.yes - Skip confirmation prompts (non-interactive).
+   * @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+   * @returns Resolves once the deploy completes.
+   * @example
+   * ```ts
+   * await app.cli.deploy({ guided: true, webBuild: () => web.cli.build() });
+   * await app.cli.deploy({ yes: true }); // CI
+   * await app.cli.deploy(); // no opts → undefined forwarded
+   * ```
+   */
+  deploy(opts?: {
+    guided?: boolean;
+    yes?: boolean;
+    webBuild?: WebBuild;
+  }): Promise<void>;
+  /**
+   * Verify the `.env` Cloudflare token (no sub), or print the config-derived token-creation
+   * guidance (`"setup"`). Delegates to deploy.verifyAuth() / deploy.tokenInstructions().
+   *
+   * @param sub - Pass "setup" to print token guidance; omit to verify the current token.
+   * @returns Resolves once the auth check or guidance render completes.
+   * @example
+   * ```ts
+   * await app.cli.auth();        // verify the current token
+   * await app.cli.auth("setup"); // print what token to create
+   * ```
+   */
+  auth(sub?: "setup"): Promise<void>;
+  /**
+   * One-shot preflight report: token + account (verifyAuth) and infra drift (checkInfra),
+   * each rendered as a branded check line.
+   *
+   * @returns Resolves once the report is printed.
+   * @example
+   * ```ts
+   * await app.cli.doctor();
+   * ```
+   */
+  doctor(): Promise<void>;
+  /**
+   * Print the resolved Cloudflare account for the current `.env` token (delegates to verifyAuth).
+   *
+   * @returns Resolves once the account summary is printed.
+   * @example
+   * ```ts
+   * await app.cli.whoami();
+   * ```
+   */
+  whoami(): Promise<void>;
+  /**
+   * Run an arbitrary `wrangler` command through the branded CLI — the escape hatch for subcommands
+   * Moku does not wrap (kv / d1 / r2 / queues / secret / tail / …). Streams wrangler's output.
+   *
+   * @param args - The wrangler arguments (e.g. ["kv", "namespace", "list"]).
+   * @returns Resolves once wrangler exits.
+   * @example
+   * ```ts
+   * await app.cli.wrangler(["kv", "namespace", "list"]);
+   * ```
+   */
+  wrangler(args: string[]): Promise<void>;
+};
+//#endregion
+//#region src/plugins/cli/index.d.ts
+/**
+ * Standard tier (node-only) — developer-facing CLI surface.
+ *
+ * Mounts `app.cli.dev()` and `app.cli.deploy()` as thin passthroughs to deployPlugin.
+ * Hooks subscribe to the global deploy:phase / provision:resource / deploy:complete events
+ * and print a live progress TUI via the injected ctx.log core API.
+ *
+ * Inline lambdas on `api`/`hooks` preserve event-name inference so the hook map keys
+ * are constrained to `WorkerEvents` keys (spec/15 §5).
+ *
+ * @see README.md
+ */
+declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config, Record<string, never>, Api, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/deploy/index.d.ts
 /**
@@ -152,20 +246,26 @@ type ProvisionResult = {
  *
  * @see README.md
  */
-declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, Record<string, never>, {
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config$1, Record<string, never>, {
   run(opts?: {
     guided?: boolean;
     yes?: boolean;
+    webBuild?: WebBuild;
     manifest?: ExternalManifest;
   }): Promise<void>;
   dev: (opts?: {
     port?: number;
+    webBuild?: WebBuild;
   }) => Promise<void>;
   init: (opts?: {
     ci?: boolean;
   }) => Promise<void>;
   checkInfra: () => Promise<InfraPlan>;
   provisionInfra: (plan: InfraPlan) => Promise<ProvisionResult>;
+  verifyAuth: () => Promise<AuthStatus>;
+  requiredToken: () => TokenRequirement;
+  tokenInstructions: () => string;
+  wrangler: (args: string[]) => Promise<void>;
 }, {}> & Record<never, never>;
 //#endregion
 export { type ExternalManifest, type ResourceManifest, cliPlugin, deployPlugin };

package/dist/cli.d.mts

@@ -1,76 +1,24 @@
 import { PluginCtx, PluginInstance } from "@moku-labs/core";
 
-//#region src/plugins/cli/types.d.ts
-/**
- * @file cli plugin — type definitions (Config, Api).
- */
-/** Resolved configuration for the cli plugin. Flat; complete defaults so omission never yields undefined. */
-type Config$1 = {
-  /**
-   * Default local dev port forwarded to deploy.dev when dev() gets no port.
-   * Passed through to `wrangler dev --port <n>`.
-   *
-   * @default 8787
-   */
-  readonly port: number;
-};
-/** Public api surface of the cli plugin, mounted at app.cli.*. */
-type Api = {
-  /**
-   * Run the Worker locally via Wrangler (delegates to deploy.dev).
-   * Defaults port to the configured value (8787) when called with no opts.
-   *
-   * @param opts - Optional port override.
-   * @param opts.port - Local dev port to bind.
-   * @returns Resolves when the dev session ends.
-   * @example
-   * ```ts
-   * await app.cli.dev();            // port 8787
-   * await app.cli.dev({ port: 3000 }); // port 3000
-   * ```
-   */
-  dev(opts?: {
-    port?: number;
-  }): Promise<void>;
-  /**
-   * One-command guided Cloudflare deploy (delegates to deploy.run).
-   * Forwards opts verbatim — passes undefined when called with no opts.
-   *
-   * @param opts - Optional guided/yes flags.
-   * @param opts.guided - Walk through each step interactively.
-   * @param opts.yes - Skip confirmation prompts (non-interactive).
-   * @returns Resolves once the deploy completes.
-   * @example
-   * ```ts
-   * await app.cli.deploy({ guided: true });
-   * await app.cli.deploy({ yes: true }); // CI
-   * await app.cli.deploy(); // no opts → undefined forwarded
-   * ```
-   */
-  deploy(opts?: {
-    guided?: boolean;
-    yes?: boolean;
-  }): Promise<void>;
-};
-//#endregion
-//#region src/plugins/cli/index.d.ts
+//#region src/plugins/deploy/types.d.ts
 /**
- * Standard tier (node-only) — developer-facing CLI surface.
- *
- * Mounts `app.cli.dev()` and `app.cli.deploy()` as thin passthroughs to deployPlugin.
- * Hooks subscribe to the global deploy:phase / provision:resource / deploy:complete events
- * and print a live progress TUI via the injected ctx.log core API.
- *
- * Inline lambdas on `api`/`hooks` preserve event-name inference so the hook map keys
- * are constrained to `WorkerEvents` keys (spec/15 §5).
+ * A web-site build hook wired in from the consumer's deploy/dev script — e.g.
+ * `() => webApp.cli.build()`. This is the seam that lets one small app-side script compose a
+ * Moku Web app with this Worker framework: `dev` / `deploy` invoke it to (re)build the site
+ * before serving or deploying. May resolve a `{ files }` count (surfaced in `dev:rebuilt`) or
+ * nothing.
  *
- * @see README.md
+ * @returns Resolves when the web build completes; optionally a rebuilt-file count.
+ * @example
+ * ```ts
+ * await server.cli.dev({ webBuild: () => web.cli.build() });
+ * ```
  */
-declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, Record<string, never>, Api, {}> & Record<never, never>;
-//#endregion
-//#region src/plugins/deploy/types.d.ts
+type WebBuild = () => Promise<void> | Promise<{
+  files?: number;
+}>;
 /** deploy plugin configuration. Flat; complete defaults so omission never yields undefined. */
-type Config = {
+type Config$1 = {
   /**
    * Wrangler config file generated/updated and read by `wrangler deploy`. Default "wrangler.jsonc".
    * Also the file parsed in the universal/non-moku path.
@@ -81,7 +29,18 @@ type Config = {
    * CF credentials are read from the Node env (CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID).
    * Default false.
    */
-  ci: boolean;
+  ci: boolean; /** Globs watched by `dev()` to trigger a Moku-site rebuild. */
+  watch: string[];
+  /**
+   * Standing default web-site build hook (e.g. `() => webApp.cli.build()`). Usually passed
+   * call-time to `dev` / `deploy` via `opts.webBuild` (the script-driven path); set here only for
+   * a persistent default. When absent, dev() falls back to `buildCommand`, then auto-detects
+   * `scripts/build.ts`.
+   */
+  webBuild?: WebBuild; /** Shell rebuild fallback (e.g. "bun run scripts/build.ts"); empty → auto-detect scripts/build.ts. */
+  buildCommand: string; /** Apply local D1 migrations before serving when a d1 manifest is present. */
+  migrateLocal: boolean; /** Debounce window (ms) coalescing rapid file changes into one rebuild. */
+  debounceMs: number;
 };
 /** Discriminated union of resource descriptors returned by each plugin's deployManifest(). */
 type ResourceManifest = {
@@ -138,6 +97,141 @@ type ProvisionResult = {
   skipped: ProvisionedRef[]; /** Merged binding → Cloudflare id map (existing + created) for writeWranglerConfig. */
   ids: Record<string, string>;
 };
+/** Result of verifying the `.env` Cloudflare API token and resolving its account. */
+type AuthStatus = {
+  /** Whether the token is present and active. */ok: boolean; /** Resolved account display name (or id when the name is unknown). */
+  account: string; /** Resolved Cloudflare account id. */
+  accountId: string; /** Token scopes, when discoverable (empty otherwise). */
+  scopes: string[];
+};
+/** One Cloudflare API-token permission group the app's manifest requires. */
+type PermissionGroup = {
+  /** Human-readable group label, e.g. "Account · D1". */group: string; /** Permission scope. */
+  scope: "Edit" | "Read"; /** Why it is required, e.g. "d1", "queue", "deploy", "account". */
+  reason: string; /** Whether Cloudflare's stock "Edit Cloudflare Workers" template already includes it. */
+  inBaseTemplate: boolean;
+};
+/** The Cloudflare API token this app requires, derived from its manifest. */
+type TokenRequirement = {
+  /** The recommended starting template. */base: "Edit Cloudflare Workers"; /** The full set of permission groups required. */
+  required: PermissionGroup[]; /** Groups NOT in the base template that the user must add (e.g. D1, Queues). */
+  toAdd: PermissionGroup[];
+};
+//#endregion
+//#region src/plugins/cli/types.d.ts
+/** Resolved configuration for the cli plugin. Flat; complete defaults so omission never yields undefined. */
+type Config = {
+  /**
+   * Default local dev port forwarded to deploy.dev when dev() gets no port.
+   * Passed through to `wrangler dev --port <n>`.
+   *
+   * @default 8787
+   */
+  readonly port: number;
+};
+/** Public api surface of the cli plugin, mounted at app.cli.*. */
+type Api = {
+  /**
+   * Run the Worker locally via Wrangler (delegates to deploy.dev).
+   * Defaults port to the configured value (8787) when called with no opts.
+   *
+   * @param opts - Optional port override and web build hook.
+   * @param opts.port - Local dev port to bind.
+   * @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
+   * @returns Resolves when the dev session ends.
+   * @example
+   * ```ts
+   * await app.cli.dev();                               // port 8787, worker only
+   * await app.cli.dev({ webBuild: () => web.cli.build() }); // wire the web build in
+   * ```
+   */
+  dev(opts?: {
+    port?: number;
+    webBuild?: WebBuild;
+  }): Promise<void>;
+  /**
+   * One-command guided Cloudflare deploy (delegates to deploy.run).
+   * Forwards opts verbatim — passes undefined when called with no opts.
+   *
+   * @param opts - Optional guided/yes flags and a web build hook.
+   * @param opts.guided - Walk through each step interactively.
+   * @param opts.yes - Skip confirmation prompts (non-interactive).
+   * @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+   * @returns Resolves once the deploy completes.
+   * @example
+   * ```ts
+   * await app.cli.deploy({ guided: true, webBuild: () => web.cli.build() });
+   * await app.cli.deploy({ yes: true }); // CI
+   * await app.cli.deploy(); // no opts → undefined forwarded
+   * ```
+   */
+  deploy(opts?: {
+    guided?: boolean;
+    yes?: boolean;
+    webBuild?: WebBuild;
+  }): Promise<void>;
+  /**
+   * Verify the `.env` Cloudflare token (no sub), or print the config-derived token-creation
+   * guidance (`"setup"`). Delegates to deploy.verifyAuth() / deploy.tokenInstructions().
+   *
+   * @param sub - Pass "setup" to print token guidance; omit to verify the current token.
+   * @returns Resolves once the auth check or guidance render completes.
+   * @example
+   * ```ts
+   * await app.cli.auth();        // verify the current token
+   * await app.cli.auth("setup"); // print what token to create
+   * ```
+   */
+  auth(sub?: "setup"): Promise<void>;
+  /**
+   * One-shot preflight report: token + account (verifyAuth) and infra drift (checkInfra),
+   * each rendered as a branded check line.
+   *
+   * @returns Resolves once the report is printed.
+   * @example
+   * ```ts
+   * await app.cli.doctor();
+   * ```
+   */
+  doctor(): Promise<void>;
+  /**
+   * Print the resolved Cloudflare account for the current `.env` token (delegates to verifyAuth).
+   *
+   * @returns Resolves once the account summary is printed.
+   * @example
+   * ```ts
+   * await app.cli.whoami();
+   * ```
+   */
+  whoami(): Promise<void>;
+  /**
+   * Run an arbitrary `wrangler` command through the branded CLI — the escape hatch for subcommands
+   * Moku does not wrap (kv / d1 / r2 / queues / secret / tail / …). Streams wrangler's output.
+   *
+   * @param args - The wrangler arguments (e.g. ["kv", "namespace", "list"]).
+   * @returns Resolves once wrangler exits.
+   * @example
+   * ```ts
+   * await app.cli.wrangler(["kv", "namespace", "list"]);
+   * ```
+   */
+  wrangler(args: string[]): Promise<void>;
+};
+//#endregion
+//#region src/plugins/cli/index.d.ts
+/**
+ * Standard tier (node-only) — developer-facing CLI surface.
+ *
+ * Mounts `app.cli.dev()` and `app.cli.deploy()` as thin passthroughs to deployPlugin.
+ * Hooks subscribe to the global deploy:phase / provision:resource / deploy:complete events
+ * and print a live progress TUI via the injected ctx.log core API.
+ *
+ * Inline lambdas on `api`/`hooks` preserve event-name inference so the hook map keys
+ * are constrained to `WorkerEvents` keys (spec/15 §5).
+ *
+ * @see README.md
+ */
+declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config, Record<string, never>, Api, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/deploy/index.d.ts
 /**
@@ -152,20 +246,26 @@ type ProvisionResult = {
  *
  * @see README.md
  */
-declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, Record<string, never>, {
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config$1, Record<string, never>, {
   run(opts?: {
     guided?: boolean;
     yes?: boolean;
+    webBuild?: WebBuild;
     manifest?: ExternalManifest;
   }): Promise<void>;
   dev: (opts?: {
     port?: number;
+    webBuild?: WebBuild;
   }) => Promise<void>;
   init: (opts?: {
     ci?: boolean;
   }) => Promise<void>;
   checkInfra: () => Promise<InfraPlan>;
   provisionInfra: (plan: InfraPlan) => Promise<ProvisionResult>;
+  verifyAuth: () => Promise<AuthStatus>;
+  requiredToken: () => TokenRequirement;
+  tokenInstructions: () => string;
+  wrangler: (args: string[]) => Promise<void>;
 }, {}> & Record<never, never>;
 //#endregion
 export { type ExternalManifest, type ResourceManifest, cliPlugin, deployPlugin };