@moku-labs/worker 0.5.1 → 0.6.0

package/dist/index-VZ99IAMv.d.cts

@@ -0,0 +1,353 @@
+import { PluginCtx, PluginInstance } from "@moku-labs/core";
+
+//#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;
+    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<Config, State, WorkerEvents & Events>;
+//#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>;
+/** deploy plugin configuration. Flat; complete defaults so omission never yields undefined. */
+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.
+   */
+  configFile: string;
+  /**
+   * 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;
+};
+/** Discriminated union of resource descriptors returned by each plugin's deployManifest(). */
+type ResourceManifest = {
+  kind: "r2";
+  bucket: string;
+  upload?: string;
+} | {
+  kind: "kv";
+  binding: string;
+} | {
+  kind: "d1";
+  binding: string;
+  migrations?: string;
+} | {
+  kind: "queue";
+  producers: string[];
+} | {
+  kind: "do";
+  bindings: Record<string, 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 versus which are still missing and must be created. Produced by `checkInfra()`.
+ */
+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 that already exist (with their captured ids where applicable). */
+  exists: ProvisionedRef[]; /** Declared resources that do not yet exist and must be created. */
+  missing: ResourceManifest[];
+};
+/**
+ * Outcome of acting on an {@link InfraPlan}: the resources just created, those skipped because
+ * they already existed, and the merged id map (binding → Cloudflare id) for the config writer.
+ */
+type ProvisionResult = {
+  /** Resources created during this run. */created: ProvisionedRef[]; /** Resources skipped because they already existed. */
+  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). Resolves the port from
+   * `opts.port`, else a `--port <n>` CLI flag, else the configured default (8787). A failure renders
+   * a branded `✗` line and sets a non-zero exit code rather than throwing a raw stack trace.
+   *
+   * @param opts - Optional port override and web build hook.
+   * @param opts.port - Local dev port to bind (overrides the `--port` flag and the default).
+   * @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({ webBuild: () => web.cli.build() }); // port from --port or 8787
+   * ```
+   */
+  dev(opts?: {
+    port?: number;
+    webBuild?: WebBuild;
+  }): Promise<void>;
+  /**
+   * One-command Cloudflare deploy (delegates to deploy.run). Guided/interactive by default; pass
+   * `{ ci: true }` for the automated/non-interactive path (CI). A failure renders a branded `✗`
+   * line and sets a non-zero exit code rather than throwing a raw stack trace.
+   *
+   * @param opts - Optional ci flag and a web build hook.
+   * @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
+   * @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+   * @returns Resolves once the deploy completes (or after a failure is rendered).
+   * @example
+   * ```ts
+   * await app.cli.deploy({ webBuild: () => web.cli.build() });           // guided
+   * await app.cli.deploy({ ci: true, webBuild: () => web.cli.build() }); // CI
+   * ```
+   */
+  deploy(opts?: {
+    ci?: 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
+/**
+ * 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$1, Record<string, never>, {
+  run(opts?: {
+    ci?: 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 { WorkerConfig as a, WorkerPluginCtx as c, ResourceManifest as i, cliPlugin as n, WorkerEnv as o, ExternalManifest as r, WorkerEvents as s, deployPlugin as t };