@moku-labs/worker 0.9.2 → 0.11.0

package/dist/index.d.mts

@@ -1,10 +1,95 @@
-import { a as ResourceManifest, c as WorkerEnv, i as ExternalManifest, l as WorkerEvents, n as cliPlugin, o as SeedConfig, r as DeployReport, s as WorkerConfig, t as deployPlugin, u as WorkerPluginCtx } from "./index-CWxQr2Q3.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
 import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 
 //#region \0rolldown/runtime.js
+//#endregion
+//#region src/config.d.ts
+/** Per-request Cloudflare bindings object (env). Framework-level shared type. */
+type WorkerEnv = Record<string, unknown>;
+/** Global framework config — flat, with complete defaults. */
+type WorkerConfig = {
+  stage: "production" | "development" | "test";
+  name: string;
+  compatibilityDate: string;
+};
+/** Global framework events — declared once, visible to every plugin. */
+type WorkerEvents = {
+  "request:start": {
+    method: string;
+    path: string;
+    requestId: string;
+  };
+  "request:end": {
+    method: string;
+    path: string;
+    status: number;
+    ms: number;
+  };
+  "deploy:phase": {
+    phase: string;
+    detail?: string;
+  };
+  "deploy:complete": {
+    url: string;
+  };
+  "provision:resource": {
+    kind: "kv" | "r2" | "d1" | "queue" | "do";
+    name: string;
+  };
+  "provision:plan": {
+    exists: number;
+    missing: number;
+    ships: number;
+    account: string;
+  };
+  "provision:skip": {
+    kind: "kv" | "r2" | "d1" | "queue" | "do";
+    name: string;
+  };
+  "auth:verified": {
+    account: string;
+    accountId: string;
+    scopes: string[];
+  };
+  "dev:phase": {
+    phase: string;
+    detail?: string;
+  };
+  "dev:rebuilt": {
+    files: number;
+    ms: number;
+  };
+  "dev:error": {
+    message: string;
+  };
+};
+/**
+ * Worker-bound plugin context for Layer-3 consumer plugins. Aliases the core
+ * {@link PluginCtx} with the global {@link WorkerEvents} pre-merged into the event
+ * map, so a consumer plugin types its own `config`/`state`/`emit` by passing only
+ * its OWN event map — never hand-merging `WorkerEvents`, and never importing from
+ * `@moku-labs/core` (a Layer-1 boundary the spec validator flags for consumers).
+ *
+ * A plugin that resolves sibling plugins also needs a `require` field; intersect the
+ * public `Server.RequireFn` for it, exactly as this framework's own plugins do. When
+ * you need the unaliased shape (e.g. a different global event map), use the raw
+ * re-exported {@link PluginCtx} instead.
+ *
+ * @template Config - This plugin's own flat configuration object.
+ * @template State - This plugin's mutable state (use `Record<string, never>` when stateless).
+ * @template Events - This plugin's own event map, merged on top of {@link WorkerEvents}; defaults to none.
+ * @example
+ * ```typescript
+ * import type { Server, WorkerPluginCtx } from "@moku-labs/worker";
+ * type MyEvents = { "my:done": { id: string } };
+ * export type MyCtx = WorkerPluginCtx<MyConfig, Record<string, never>, MyEvents> & {
+ *   require: Server.RequireFn;
+ * };
+ * ```
+ */
+type WorkerPluginCtx<Config, State, Events extends Record<string, unknown> = Record<never, never>> = PluginCtx$1<Config, State, WorkerEvents & Events>;
 declare namespace types_d_exports {
-  export { BindingsApi, Config$5 as Config, Context };
+  export { BindingsApi, Config$7 as Config, Context };
 }
 /**
  * bindings config. Flat (spec/05 §3,§6) — a complete default so omission
@@ -15,7 +100,7 @@ declare namespace types_d_exports {
  * { required: ["MY_KV", "DB"] }
  * ```
  */
-type Config$5 = {
+type Config$7 = {
   required: string[];
 };
 /**
@@ -50,7 +135,7 @@ type BindingsApi = {
  * api-factory context. State slot is Record<string, never> — bindings holds NO
  * state (F4). Type-argument order is PluginCtx<Config, State, Events>.
  */
-type Context = PluginCtx$1<Config$5, Record<string, never>, WorkerEvents>;
+type Context = PluginCtx$1<Config$7, Record<string, never>, WorkerEvents>;
 //#endregion
 //#region src/plugins/bindings/index.d.ts
 /**
@@ -62,9 +147,9 @@ type Context = PluginCtx$1<Config$5, Record<string, never>, WorkerEvents>;
  *
  * @see README.md
  */
-declare const bindingsPlugin: import("@moku-labs/core").PluginInstance<"bindings", Config$5, Record<string, never>, BindingsApi, {}> & Record<never, never>;
+declare const bindingsPlugin: import("@moku-labs/core").PluginInstance<"bindings", Config$7, Record<string, never>, BindingsApi, {}> & Record<never, never>;
 declare namespace types_d_exports$4 {
-  export { Api$3 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathParams, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
+  export { Api$4 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathParams, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
 }
 /** HTTP method an endpoint matches; "ALL" matches any verb. */
 type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
@@ -191,7 +276,7 @@ type ServerCtx = PluginCtx$1<ServerConfig, ServerState, WorkerEvents & ServerEve
   has: (name: string) => boolean;
 };
 /** Public api surface of the server plugin. */
-type Api$3 = {
+type Api$4 = {
   /**
    * Route one HTTP request and return its Response (or 404).
    *
@@ -335,7 +420,7 @@ type EndpointBuilder<Path extends string> = {
  */
 declare const endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
 declare namespace types_d_exports$1 {
-  export { Api$2 as Api, Config$4 as Config, D1Ctx, D1DatabaseApi, D1Instance };
+  export { Api$3 as Api, Config$6 as Config, D1Ctx, D1DatabaseApi, D1Instance };
 }
 /**
  * A single D1 database instance: its base Cloudflare name + the env binding it resolves off, plus
@@ -361,7 +446,7 @@ type D1Instance = {
  * { main: { name: "tracker-db", binding: "DB", migrations: "db/migrations" } }
  * ```
  */
-type Config$4 = Record<string, D1Instance>;
+type Config$6 = Record<string, D1Instance>;
 /**
  * The SQL surface for one D1 database (the thin typed wrappers bound to a single instance).
  *
@@ -425,7 +510,7 @@ type D1DatabaseApi = {
  * await app.d1.use("analytics").run(env, "INSERT INTO events (name) VALUES (?)", "click");
  * ```
  */
-type Api$2 = D1DatabaseApi & {
+type Api$3 = D1DatabaseApi & {
   /**
    * Select a specific D1 database instance by its config key.
    *
@@ -450,7 +535,7 @@ type Api$2 = D1DatabaseApi & {
  * Internal context type — own config first, no state, no d1-local events.
  * Intersected with a narrow `require` typed to the one dependency d1 resolves.
  */
-type D1Ctx = PluginCtx$1<Config$4, Record<string, never>, WorkerEvents> & {
+type D1Ctx = PluginCtx$1<Config$6, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. d1 only ever resolves `bindingsPlugin`.
    *
@@ -470,7 +555,7 @@ type D1Ctx = PluginCtx$1<Config$4, Record<string, never>, WorkerEvents> & {
  *
  * @see README.md
  */
-declare const d1Plugin: import("@moku-labs/core").PluginInstance<"d1", Config$4, Record<string, never>, {
+declare const d1Plugin: import("@moku-labs/core").PluginInstance<"d1", Config$6, Record<string, never>, {
   use: (key: string) => {
     query: <T = unknown>(env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<D1Result<T>>;
     first: <T = unknown>(env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<T | null>;
@@ -548,7 +633,7 @@ declare const defineDurableObject: (name: string) => DurableObjectBaseConstructo
   readonly doName: string;
 };
 declare namespace types_d_exports$2 {
-  export { Api$1 as Api, Config$3 as Config, Ctx$1 as Ctx, DoInstance };
+  export { Api$2 as Api, Config$5 as Config, Ctx$1 as Ctx, DoInstance };
 }
 /**
  * A single Durable Object instance: the env binding it resolves off plus the EXPORTED class it
@@ -576,9 +661,9 @@ type DoInstance = {
  * { board: { binding: "BOARD", className: "BoardChannel" } }
  * ```
  */
-type Config$3 = Record<string, DoInstance>;
+type Config$5 = Record<string, DoInstance>;
 /** Public api surface of the durableObjects plugin. */
-type Api$1 = {
+type Api$2 = {
   /**
    * Resolve a DurableObjectStub off the request env (logical key -> configured binding).
    *
@@ -604,7 +689,7 @@ type Api$1 = {
  * Internal context type — own config first, no state, no DO events.
  * Intersected with a narrow `require` typed to the one dependency durableObjects resolves.
  */
-type Ctx$1 = PluginCtx$1<Config$3, Record<string, never>, WorkerEvents> & {
+type Ctx$1 = PluginCtx$1<Config$5, Record<string, never>, WorkerEvents> & {
   /**
    * Resolve a dependency plugin's api. durableObjects only ever resolves `bindingsPlugin`.
    *
@@ -635,7 +720,7 @@ type Ctx$1 = PluginCtx$1<Config$3, Record<string, never>, WorkerEvents> & {
  * ```
  * @see README.md
  */
-declare const durableObjectsPlugin: import("@moku-labs/core").PluginInstance<"durableObjects", Config$3, Record<string, never>, {
+declare const durableObjectsPlugin: import("@moku-labs/core").PluginInstance<"durableObjects", Config$5, Record<string, never>, {
   get: (env: WorkerEnv, logicalName: string, idName: string) => DurableObjectStub;
   deployManifest: () => Array<{
     kind: "do";
@@ -671,7 +756,7 @@ type KvInstance = {
  * { cache: { name: "tracker-cache", binding: "CACHE" } }
  * ```
  */
-type Config$2 = Record<string, KvInstance>;
+type Config$4 = Record<string, KvInstance>;
 /**
  * The env-first key/value surface for one KV namespace (the methods bound to a single instance).
  *
@@ -758,9 +843,9 @@ type KvApi = KvNamespaceApi & {
  *
  * @see README.md
  */
-declare const kvPlugin: import("@moku-labs/core").PluginInstance<"kv", Config$2, Record<string, never>, KvApi, {}> & Record<never, never>;
+declare const kvPlugin: import("@moku-labs/core").PluginInstance<"kv", Config$4, Record<string, never>, KvApi, {}> & Record<never, never>;
 declare namespace types_d_exports$3 {
-  export { Api, Config$1 as Config, Ctx, QueueEvents, QueueInstance, QueueProducerApi };
+  export { Api$1 as Api, Config$3 as Config, Ctx, QueueEvents, QueueInstance, QueueProducerApi };
 }
 /**
  * A single Cloudflare Queue instance: its base CF queue name, the producer env binding it
@@ -793,7 +878,7 @@ type QueueInstance = {
  * { activity: { name: "tracker-activity", binding: "ACTIVITY", onMessage: async () => {} } }
  * ```
  */
-type Config$1 = Record<string, QueueInstance>;
+type Config$3 = Record<string, QueueInstance>;
 /** Per-plugin event map for queues. */
 type QueueEvents = {
   "queue:message": {
@@ -837,7 +922,7 @@ type QueueProducerApi = {
  * await app.queues.use("activity").send(env, { id: 2 }); // a named instance
  * ```
  */
-type Api = QueueProducerApi & {
+type Api$1 = QueueProducerApi & {
   /**
    * Select a specific Queue instance by its config key.
    *
@@ -878,7 +963,7 @@ type Api = QueueProducerApi & {
  * (core's "advanced composition" note), typed to the one dependency queues resolves —
  * `require(bindingsPlugin)` → `BindingsApi`. Core does not export `RequireFunction`.
  */
-type Ctx = PluginCtx$1<Config$1, Record<string, never>, WorkerEvents & QueueEvents> & {
+type Ctx = PluginCtx$1<Config$3, Record<string, never>, WorkerEvents & QueueEvents> & {
   /**
    * Resolve a dependency plugin's api. queues only ever resolves `bindingsPlugin`.
    *
@@ -900,7 +985,7 @@ type Ctx = PluginCtx$1<Config$1, Record<string, never>, WorkerEvents & QueueEven
  *
  * @see README.md
  */
-declare const queuesPlugin: import("@moku-labs/core").PluginInstance<"queues", Config$1, Record<string, never>, Api, {
+declare const queuesPlugin: import("@moku-labs/core").PluginInstance<"queues", Config$3, Record<string, never>, Api$1, {
   "queue:message": {
     queue: string;
     messageId: string;
@@ -915,7 +1000,7 @@ declare const queuesPlugin: import("@moku-labs/core").PluginInstance<"queues", C
  *
  * @see README.md
  */
-declare const serverPlugin: import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+declare const serverPlugin: import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$4, {
   "server:matched": {
     path: string;
     method: string;
@@ -1079,6 +1164,448 @@ type StorageCtx = PluginCtx$1<StorageConfig, Record<string, never>, WorkerEvents
  */
 declare const storagePlugin: import("@moku-labs/core").PluginInstance<"storage", StorageConfig, Record<string, never>, StorageApi, {}> & Record<never, never>;
 //#endregion
+//#region src/plugins/deploy/types.d.ts
+/**
+ * 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. The hook may resolve ANYTHING — `void`, the web app's own build summary, or
+ * a `{ files }` count; when the resolved value carries a numeric `files` field it is surfaced in
+ * `dev:rebuilt`, otherwise the count is reported as 0. Returning `Promise<unknown>` keeps the hook
+ * assignable from any real build function (whose return type the worker framework cannot know).
+ *
+ * @returns Resolves when the web build completes (the value is read opportunistically for `files`).
+ * @example
+ * ```ts
+ * await server.cli.dev({ webBuild: () => web.cli.build() });
+ * ```
+ */
+type WebBuild = () => Promise<unknown>;
+/**
+ * A per-change INCREMENTAL rebuild hook wired in from the consumer's dev script — e.g.
+ * `(changes) => webApp.cli.update(changes)`. The fast counterpart to {@link WebBuild}: `dev`
+ * calls {@link WebBuild} ONCE for the cold build, then (when this hook is wired) calls `onChange`
+ * with the set of paths changed in the debounce window so the web build can rebuild only what
+ * changed instead of doing a full `webBuild()` every keystroke. Omit it and `dev` keeps doing a
+ * full `webBuild()` per change (the prior behavior). Like {@link WebBuild} it may resolve ANYTHING
+ * (the web build's own summary); the value is read opportunistically for a `files` count.
+ *
+ * @param changes - The paths changed since the last rebuild (the watcher's debounced set).
+ * @returns Resolves when the incremental rebuild completes.
+ * @example
+ * ```ts
+ * await server.cli.dev({ webBuild: () => web.cli.build(), onChange: changes => web.cli.update(changes) });
+ * ```
+ */
+type OnChange = (changes: readonly string[]) => Promise<unknown>;
+/**
+ * The remote seed wired into `deploy({ seed: true })`: which SQL file to load into the REMOTE D1
+ * AFTER a successful deploy (+ migration), and which cached KV keys to clear afterwards so the app
+ * rebuilds them from the freshly-seeded rows. Declarative — the deploy plugin runs no app code, so
+ * the app-specific seed lives in `pluginConfigs.deploy.seed` (config) rather than a deploy hook.
+ *
+ * @example
+ * ```ts
+ * deploy: { seed: { file: "db/seed.sql", resetKv: [{ binding: "BOARDS_KV", key: "boards:index" }] } }
+ * ```
+ */
+type SeedConfig = {
+  /** SQL file executed against the remote D1 (e.g. "db/seed.sql"). */file: string; /** The d1 binding to target when more than one database is configured (e.g. "DB"); the sole one otherwise. */
+  binding?: string; /** Cached KV keys to delete after seeding so reads rebuild from the freshly-seeded DB. */
+  resetKv?: {
+    binding: string;
+    key: string;
+  }[];
+};
+/** deploy plugin configuration. Flat; complete defaults so omission never yields undefined. */
+type Config$2 = {
+  /**
+   * Wrangler config file generated/updated and read by `wrangler deploy`. Default "wrangler.jsonc".
+   * Also the file parsed in the universal/non-moku path.
+   */
+  configFile: string;
+  /**
+   * The Worker entry module → wrangler `main` (e.g. "src/cloudflare/worker.ts"). Required for any
+   * real Worker deploy (its absence is wrangler's "Missing entry-point" error).
+   */
+  entry?: string;
+  /**
+   * Enable Node.js compat → `compatibility_flags: ["nodejs_compat"]`. Needed when the Worker bundle
+   * pulls in Node-flavored code (e.g. composing the deploy/cli tooling into the runtime app).
+   */
+  nodeCompat?: boolean;
+  /**
+   * Static assets served via `env.<binding>` → the wrangler `assets` block. `spa: true` sets
+   * `not_found_handling: "single-page-application"` so client-routed deep links resolve to index.html.
+   */
+  assets?: {
+    binding: string;
+    directory: string;
+    spa?: boolean;
+  };
+  /**
+   * Escape hatch — extra top-level wrangler keys merged into the generated config for anything the
+   * typed fields above don't cover (`vars`, `routes`, `observability`, `triggers`, …). The
+   * deploy-managed resource keys (name, compatibility_date, kv_namespaces, r2_buckets, d1_databases,
+   * queues, durable_objects, and the auto-derived Durable Object `migrations`) always win over these.
+   */
+  wrangler?: Record<string, unknown>;
+  /**
+   * Standing CI/automated default for `run()`. When true (or when stdout is non-TTY) the deploy
+   * never prompts and auto-confirms every gate; `run({ ci })` overrides it per call. CF credentials
+   * are read from the env (CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID) via `ctx.env`. Default false.
+   */
+  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;
+  /**
+   * The remote seed `deploy({ seed: true })` loads AFTER a successful deploy (+ migration): the SQL
+   * file and the cached KV keys to reset. Omit it and `deploy({ seed: true })` reports a clear
+   * "no seed configured" error instead of silently doing nothing.
+   */
+  seed?: SeedConfig;
+};
+/**
+ * Discriminated union of per-INSTANCE resource descriptors. Each resource plugin's `deployManifest()`
+ * returns an ARRAY of these (one per configured instance). `name` is the base Cloudflare resource
+ * name (stage-suffixed downstream via {@link stageName}); `binding` is the stable env var. Durable
+ * Objects carry no provisioned `name` — they ship with the Worker script — and declare the exported
+ * `className` instead.
+ */
+type ResourceManifest = {
+  kind: "r2";
+  name: string;
+  binding: string;
+  upload?: string;
+} | {
+  kind: "kv";
+  name: string;
+  binding: string;
+} | {
+  kind: "d1";
+  name: string;
+  binding: string;
+  migrations?: string;
+} | {
+  kind: "queue";
+  name: string;
+  binding: string;
+  consumer?: boolean;
+  maxBatchTimeout?: number;
+} | {
+  kind: "do";
+  binding: string;
+  className: string;
+};
+/**
+ * The whole deploy manifest the pipeline consumes (assembled, or caller-supplied for the
+ * universal path).
+ */
+type ExternalManifest = {
+  /** Worker name. */name: string; /** Cloudflare compatibility date. */
+  compatibilityDate: string; /** Resource descriptors to provision. */
+  resources: ResourceManifest[];
+};
+/**
+ * A resource that already exists in the account (the infra preflight discovered it), with its
+ * captured Cloudflare id when the kind has one (kv namespace id, d1 database id).
+ */
+type ProvisionedRef = {
+  /** The resource descriptor from the manifest. */resource: ResourceManifest; /** The existing resource's Cloudflare id (kv/d1 only). */
+  id?: string;
+};
+/**
+ * Read-only infra preflight result: which declared resources already exist in the Cloudflare
+ * account, which are still missing and must be created, and which ship with the Worker. Produced by
+ * `checkInfra()`. Durable Objects are neither "exists" nor "missing" — the planner never queries the
+ * account for them and never API-provisions them; they are created by `wrangler deploy` (the
+ * auto-derived DO migration), so they get their own `ships` bucket instead of masquerading as
+ * already-existing.
+ */
+type InfraPlan = {
+  /** Resolved account display name (or id when the name is unknown). */account: string; /** Resolved Cloudflare account id used for the existence checks. */
+  accountId: string; /** Declared resources the account listing confirmed already exist (with captured ids where applicable). */
+  exists: ProvisionedRef[]; /** Declared resources that do not yet exist and must be created. */
+  missing: ResourceManifest[]; /** Durable Objects that ship with the Worker — created by `wrangler deploy`, never API-provisioned. */
+  ships: ResourceManifest[];
+};
+/**
+ * A resource that failed to provision, with the (branded) error message captured so the guided flow
+ * can show WHICH resource failed and why — instead of aborting the whole run on the first failure.
+ */
+type ProvisionFailure = {
+  /** The resource descriptor that failed to create. */resource: ResourceManifest; /** The captured error message (e.g. the branded wrangler failure). */
+  error: string;
+};
+/**
+ * Outcome of acting on an {@link InfraPlan}: the resources just created, those skipped because they
+ * already existed, those that ship with the Worker (Durable Objects — not created here), those that
+ * FAILED to create, and the merged id map (binding → Cloudflare id) for the config writer.
+ * Provisioning is resilient — a single resource failure is captured here, not thrown, so the guided
+ * flow can report a clear per-resource result.
+ */
+type ProvisionResult = {
+  /** Resources created during this run. */created: ProvisionedRef[]; /** Resources skipped because they already existed. */
+  skipped: ProvisionedRef[]; /** Durable Objects that ship with the Worker — not created at the provision step (`wrangler deploy` does). */
+  bundled: ResourceManifest[]; /** Resources that failed to create (captured, not thrown). */
+  failed: ProvisionFailure[]; /** Merged binding → Cloudflare id map (existing + created) for writeWranglerConfig. */
+  ids: Record<string, string>;
+};
+/**
+ * Structured outcome of a deploy run (the value `run()` / `cli.deploy()` now resolve to, replacing
+ * the old `void`) so a script can branch on the result instead of guessing from a thrown error. It
+ * is also WHY the post-deploy migration + seed live inside `run()`: the report's `status` is the
+ * single source of truth for whether the worker actually went live, so those remote-DB steps run
+ * only on a successful deploy and never on an aborted one.
+ *
+ * `ok` is true only when the worker is live AND every requested post-step (migration, seed) also
+ * succeeded. `status` is the coarse outcome: `"deployed"` (live, all post-steps ok), `"aborted"`
+ * (a gate was declined or auth was never set up — nothing shipped), `"failed"` (a step errored).
+ */
+type DeployReport = {
+  /** True only when the worker is live and every requested post-step (migration, seed) succeeded. */ok: boolean; /** Coarse outcome: "deployed" (live + post-steps ok), "aborted" (a gate declined / auth not set up), "failed" (a step errored). */
+  status: "deployed" | "aborted" | "failed"; /** The resolved deploy stage (resource-name suffix; "production" is bare). */
+  stage: string; /** The live worker URL once `wrangler deploy` succeeded — set even if a later migration/seed failed. */
+  url?: string; /** Provisioning tally: resources created, already-existing, shipped-with-the-Worker (DOs), and failed to create. */
+  resources?: {
+    created: number;
+    exists: number;
+    bundled: number;
+    failed: number;
+  }; /** Remote D1 migration outcome — "skipped" (not requested), "applied", or "failed". */
+  migration: "skipped" | "applied" | "failed"; /** Remote seed outcome — "skipped" (not requested), "applied", or "failed". */
+  seed: "skipped" | "applied" | "failed"; /** Wall-clock duration of the whole run (ms). */
+  elapsedMs: number; /** Branded failure message(s) — empty when `ok`; one per failed step otherwise. */
+  errors: 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. The cli surface is configuration-free: the dev port is
+ * NOT set here (it comes only from `dev({ port })`), so there are no keys to set under
+ * `pluginConfigs.cli`.
+ */
+type Config$1 = Record<string, never>;
+/** Public api surface of the cli plugin, mounted at app.cli.*. */
+type Api = {
+  /**
+   * Run the Worker locally via Wrangler (delegates to deploy.dev). The dev port comes only from
+   * `opts.port` — the consumer passes it (e.g. parsed from its own CLI flags); it defaults to 8787
+   * when omitted. A failure renders a branded `✗` line and sets a non-zero exit code rather than
+   * throwing a raw stack trace.
+   *
+   * @param opts - Optional port, stage, cold-build hook, and incremental change hook.
+   * @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
+   * @param opts.stage - Stage for the generated wrangler config's resource names. Falls back to the
+   *   `--stage` CLI flag, then the app's configured stage. Pass it explicitly from a script for a
+   *   self-documenting `dev({ stage })` instead of relying on the hidden flag.
+   * @param opts.webBuild - Cold-build the web site (e.g. `() => webApp.cli.build()`); also the
+   *   per-change rebuild when `onChange` is omitted.
+   * @param opts.onChange - Incremental per-change rebuild (e.g. `changes => webApp.cli.update(changes)`),
+   *   so each change rebuilds only the changed paths instead of a full `webBuild()` every keystroke.
+   * @param opts.seed - Load the configured seed (`pluginConfigs.deploy.seed`) into the LOCAL D1 and
+   *   reset its cached KV keys before serving — the local analogue of `deploy({ seed: true })`.
+   * @returns Resolves when the dev session ends.
+   * @example
+   * ```ts
+   * await app.cli.dev({ stage: "dev", port: 7878, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
+   * ```
+   */
+  dev(opts?: {
+    port?: number;
+    stage?: string;
+    webBuild?: WebBuild;
+    onChange?: OnChange;
+    seed?: boolean;
+  }): Promise<void>;
+  /**
+   * One-command Cloudflare deploy (delegates to deploy.run), then — only on a successful deploy —
+   * the requested post-deploy remote steps (migration, seed). Guided/interactive by default; pass
+   * `{ ci: true }` for the automated/non-interactive path (CI). Unlike the other verbs this RETURNS
+   * the structured {@link DeployReport} (so a script can branch on the outcome) AND, on a failure,
+   * renders a branded `✗` line + sets a non-zero exit code rather than throwing a raw stack trace.
+   *
+   * @param opts - Optional ci flag, stage, a web build hook, and the post-deploy migration/seed flags.
+   * @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
+   * @param opts.stage - Stage for the generated wrangler config's resource names (e.g. "production",
+   *   "staging"). Falls back to the `--stage` CLI flag, then the app's configured stage. Pass it
+   *   explicitly from a script for a self-documenting `deploy({ stage })` instead of the hidden flag.
+   * @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+   * @param opts.migration - Apply pending remote D1 migrations after a successful deploy (skipped on abort).
+   * @param opts.seed - Load the configured remote seed (`pluginConfigs.deploy.seed`) after a
+   *   successful deploy (+ migration); skipped on an aborted deploy.
+   * @returns The deploy report (status, url, resource tally, migration/seed outcome, errors).
+   * @example
+   * ```ts
+   * const report = await app.cli.deploy({ webBuild: () => web.cli.build(), migration: true, seed: true });
+   * if (report.status === "aborted") return; // creds not set up yet — nothing shipped
+   * ```
+   */
+  deploy(opts?: {
+    ci?: boolean;
+    stage?: string;
+    webBuild?: WebBuild;
+    migration?: boolean;
+    seed?: boolean;
+  }): Promise<DeployReport>;
+  /**
+   * Seed a configured D1 database from a SQL file (delegates to deploy.seed). Local by default
+   * (applies the database's migrations first so its tables exist, then executes the file);
+   * `opts.remote` seeds Cloudflare. A failure renders a branded `✗` line and sets a non-zero exit
+   * code rather than throwing.
+   *
+   * @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+   * @param opts - Optional options.
+   * @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+   * @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+   * @returns Resolves once the seed completes (or after a failure is rendered).
+   * @example
+   * ```ts
+   * await app.cli.seed("db/seed.sql"); // local; --stage honored
+   * ```
+   */
+  seed(sqlFile: string, opts?: {
+    binding?: string;
+    remote?: boolean;
+  }): 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$1, Record<string, never>, Api, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/deploy/index.d.ts
+/**
+ * Complex tier (node-only) — build-time deploy orchestrator over the five resource plugins.
+ *
+ * Assembles each resource plugin's deployManifest() via ctx.require, provisions resources,
+ * generates/updates wrangler config, uploads the R2 upload dir, and runs wrangler deploy.
+ * Also supports a universal path: run({ manifest }) uses a caller-supplied manifest verbatim.
+ *
+ * Emits only the global events `deploy:phase`, `deploy:complete`, and `provision:resource`
+ * (declared in WorkerEvents — no per-plugin events block).
+ *
+ * @see README.md
+ */
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config$2, Record<string, never>, {
+  run(opts?: {
+    ci?: boolean;
+    stage?: string;
+    webBuild?: WebBuild;
+    manifest?: ExternalManifest;
+    migration?: boolean;
+    seed?: boolean;
+  }): Promise<DeployReport>;
+  dev(opts?: {
+    port?: number;
+    stage?: string;
+    webBuild?: WebBuild;
+    onChange?: OnChange;
+    seed?: boolean;
+  }): Promise<void>;
+  seed(sqlFile: string, opts?: {
+    stage?: string;
+    binding?: string;
+    remote?: boolean;
+  }): Promise<void>;
+  init: (opts?: {
+    ci?: boolean;
+  }) => Promise<void>;
+  checkInfra: () => Promise<InfraPlan>;
+  provisionInfra: (plan: InfraPlan) => Promise<ProvisionResult>;
+  verifyAuth: () => Promise<AuthStatus>;
+  requiredToken: () => TokenRequirement;
+  ciToken: () => PermissionGroup[];
+  tokenInstructions: () => string;
+  wrangler: (args: string[]) => Promise<void>;
+}, {}> & Record<never, never>;
+//#endregion
 //#region src/plugins/stage/index.d.ts
 /** This plugin's own config type (Nano tier — declared inline, no types.ts). */
 type Config = {
@@ -1181,7 +1708,7 @@ declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<
   current: () => "production" | "development" | "test";
 }>]>>;
 /** The core-bound app factory; wrapped by {@link createApp} to bridge `config.stage`. */
-declare const boundCreateApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$5, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+declare const boundCreateApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$7, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$4, {
   "server:matched": {
     path: string;
     method: string;
@@ -1194,7 +1721,7 @@ declare const boundCreateApp: <const ExtraPlugins extends readonly import("@moku
   isDev: () => boolean;
   isProduction: () => boolean;
   current: () => "production" | "development" | "test";
-}>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$5, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+}>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$7, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$4, {
   "server:matched": {
     path: string;
     method: string;