@moku-labs/common 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moku-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+<div align="center">
+
+# @moku-labs/common
+
+**Shared, framework-agnostic plugins for the Moku family.**
+
+Author a plugin once, reuse it across every Moku framework. `@moku-labs/common` is
+a *catalog* — it exports plugin objects built on the
+[@moku-labs/core](https://github.com/moku-labs/core) micro-kernel, ready to drop
+into any framework's `createCoreConfig`. No framework of its own, no lock-in.
+
+<br/>
+
+[![npm](https://img.shields.io/npm/v/@moku-labs/common?logo=npm&color=cb3837&label=npm)](https://www.npmjs.com/package/@moku-labs/common)
+[![types](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)](#requirements)
+[![browser entry](https://img.shields.io/badge/browser%20entry-node--free-2da44e)](#entry-points)
+[![node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](#requirements)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+<br/>
+
+[Install](#install) ·
+[Catalog](#catalog) ·
+[Usage](#usage) ·
+[Entry points](#entry-points) ·
+[Scripts](#scripts)
+
+</div>
+
+---
+
+## Install
+
+```sh
+bun add @moku-labs/common @moku-labs/core
+```
+
+> [!NOTE]
+> **Status: `0.x` — early.** The catalog is small and growing. The plugins are built on `@moku-labs/core`; install it alongside (your framework already depends on it).
+
+## Why @moku-labs/common
+
+- **Write once, reuse everywhere.** Cross-cutting plugins (logging, env, …) live here instead of being copy-pasted into every Moku framework.
+- **A catalog, not a framework.** No `createApp`, no defaults of its own. You import plugin objects and register them in *your* framework's `createCoreConfig`.
+- **Core plugins.** Everything here is built with `createCorePlugin`, so a plugin's API is injected onto every plugin's context (`ctx.log`, `ctx.env`) — framework-agnostic by construction.
+- **The `/browser` entry is guaranteed node-free.** A client-safe subset whose static import graph references zero node modules, enforced by a CI gate.
+
+## Catalog
+
+| Export | Kind | Responsibility |
+|---|---|---|
+| [`logPlugin`](src/plugins/log/README.md) | core plugin | Always-on in-memory trace + an `expect()` event-trace DSL for testable workflows. Injected as `ctx.log`. |
+| [`envPlugin`](src/plugins/env/README.md) | core plugin | Multi-provider environment / secret injection, validated and frozen at `onInit`, with `PUBLIC_` cross-validation. Exposed as `ctx.env`. |
+| `dotenv` · `processEnv` · `cloudflareBindings` | env providers (Node) | Resolve env from `.env` files / `process.env` / Cloudflare bindings. Import `node:fs`. |
+| `browserEnv` | env provider (browser) | Reads `import.meta.env` + `globalThis.__ENV__`. Zero `node:*`. |
+| `Log` · `Env` | type namespaces | `Log.LogApi`, `Env.EnvConfig`, … |
+
+## Usage
+
+Register the plugins in your framework's `createCoreConfig` — their APIs are then injected onto every plugin's context:
+
+```ts
+// my-framework/config.ts
+import { createCoreConfig } from "@moku-labs/core";
+import { envPlugin, logPlugin } from "@moku-labs/common";
+
+type Config = { /* … */ };
+type Events = { /* … */ };
+
+export const coreConfig = createCoreConfig<Config, Events, [typeof logPlugin, typeof envPlugin]>(
+  "my-framework",
+  {
+    config: { /* … */ },
+    plugins: [logPlugin, envPlugin] // ctx.log + ctx.env on every plugin
+  }
+);
+```
+
+Supply the `env` provider that matches each target:
+
+```ts
+import { dotenv, processEnv } from "@moku-labs/common"; // Node
+import { browserEnv } from "@moku-labs/common/browser"; // browser (node-free)
+```
+
+## Entry points
+
+| Entry | Format | For | Includes |
+|---|---|---|---|
+| **`@moku-labs/common`** | dual ESM + CJS | Node | the full catalog, incl. the Node env providers (`dotenv` / `processEnv` / `cloudflareBindings`) |
+| **`@moku-labs/common/browser`** | ESM-only | client bundles | `logPlugin`, `envPlugin`, `browserEnv` and the `Log` / `Env` types — **with all node-only code excluded** |
+
+Importing `@moku-labs/common/browser` can **never** drag `node:*` code into a client bundle, regardless of bundler or tree-shaking — its static import graph references zero node-only modules. CI proves it:
+
+```sh
+bun run check:bundle   # asserts: zero static node imports + under the gzip budget
+```
+
+## Scripts
+
+```sh
+bun run build              # build with tsdown (dual ESM+CJS + ESM-only browser entry)
+bun run test               # all tests (vitest)
+bun run test:unit          # unit tests only
+bun run test:integration   # integration tests only
+bun run test:coverage      # tests with coverage (90% threshold)
+bun run lint               # biome check + eslint
+bun run lint:fix           # auto-fix lint issues
+bun run format             # format with biome
+bun run validate           # publint + attw — verify the package export map
+bun run check:bundle       # assert the browser bundle is node-free + under the gzip budget
+```
+
+## Requirements
+
+- **Node `>= 24`** and **Bun `>= 1.3.14`** — use `bun` exclusively (never npm/yarn/pnpm).
+- **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
+- **[`@moku-labs/core`](https://github.com/moku-labs/core)** — the micro-kernel the plugins are built on.
+
+## License
+
+[MIT](./LICENSE) © [moku-labs](https://github.com/moku-labs)

package/dist/browser.d.mts

@@ -0,0 +1,344 @@
+declare namespace types_d_exports$1 {
+  export { ExpectChain, LogApi, LogConfig, LogEntry, LogLevel, LogSink, LogState };
+}
+/**
+ * @file log plugin — type definitions skeleton.
+ *
+ * Core-plugin type surface: config, state, public API, and the supporting
+ * value/sink/assertion-chain types. These types are inferred onto the plugin
+ * via state.ts / api.ts; index.ts passes NO explicit generics.
+ */
+/**
+ * Runtime mode for the log plugin. Selects which default sinks are installed at
+ * onInit. The in-memory trace sink is ALWAYS installed regardless of mode.
+ *
+ * - "test"       — no console sink (keeps test output clean); trace only.
+ * - "silent"     — no console sink (explicit quiet); trace only.
+ * - "dev"        — console sink + trace.
+ * - "production" — console sink + trace.
+ */
+type LogConfig = {
+  /** Sink-selection mode. Defaults to `production`. */mode: "test" | "dev" | "production" | "silent";
+};
+/** Severity level for a log entry. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A single recorded log entry.
+ */
+type LogEntry = {
+  /** Severity level. */level: LogLevel; /** Event identifier (free-form string; convention: `domain:action`). */
+  event: string; /** Optional structured payload associated with the event. */
+  data?: unknown; /** Capture timestamp in epoch milliseconds (`Date.now()` at append time). */
+  ts: number; /** Optional originating plugin name. Reserved for future enrichment. */
+  plugin?: string;
+};
+/**
+ * Pluggable output target. Implement this to add console/file/JSON/etc. sinks
+ * WITHOUT changing the log API. Each logged entry is passed to `write` once,
+ * in registration order.
+ */
+type LogSink = {
+  /**
+   * Write a single entry to this sink.
+   *
+   * @param entry - The entry to emit.
+   */
+  write(entry: LogEntry): void;
+};
+/**
+ * Fluent event-trace assertion chain. Reads the live entries array on each call,
+ * so assertions reflect the trace state at call time (not chain-creation time).
+ * Every method returns the same chain for fluent chaining; assertion failures throw.
+ */
+type ExpectChain = {
+  /**
+   * Assert at least one entry has `event`, optionally matching `partial` (subset match).
+   *
+   * @param event - Event name to find.
+   * @param partial - Optional partial data shape (subset-matched against `entry.data`).
+   * @returns The same chain for chaining.
+   * @throws {Error} `LogExpectAssertionError` when no matching entry exists.
+   */
+  toHaveEvent(event: string, partial?: Record<string, unknown>): ExpectChain;
+  /**
+   * Assert all of `events` appear in the trace in the given relative order
+   * (gaps allowed; later events must occur after earlier ones).
+   *
+   * @param events - Ordered list of event names.
+   * @returns The same chain for chaining.
+   * @throws {Error} `LogExpectAssertionError` when the ordering cannot be satisfied.
+   */
+  toHaveEventInOrder(events: string[]): ExpectChain;
+  /**
+   * Assert NO entry has `event` (optionally narrowed by `partial`).
+   *
+   * @param event - Event name that must be absent.
+   * @param partial - Optional partial data shape; only matching entries violate the assertion.
+   * @returns The same chain for chaining.
+   * @throws {Error} `LogExpectAssertionError` when a matching entry exists.
+   */
+  toNotHaveEvent(event: string, partial?: Record<string, unknown>): ExpectChain;
+};
+/**
+ * Internal mutable state for the log plugin. Created fresh per createApp construction.
+ */
+type LogState = {
+  /** Append-only ordered trace of every logged entry (the in-memory trace sink's backing store). */entries: LogEntry[]; /** Registered output sinks. Each entry is written to every sink in order. */
+  sinks: LogSink[];
+};
+/** Public log API injected as `ctx.log` on every regular plugin and exposed as `app.log`. */
+type LogApi = {
+  /**
+   * Append an `info` entry and fan it out to every sink.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   */
+  info(event: string, data?: unknown): void;
+  /**
+   * Append a `debug` entry and fan it out to every sink.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   */
+  debug(event: string, data?: unknown): void;
+  /**
+   * Append a `warn` entry and fan it out to every sink.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   */
+  warn(event: string, data?: unknown): void;
+  /**
+   * Append an `error` entry. When `error` is provided, its `message`/`stack` are
+   * merged into `data` under an `error` key; otherwise `data` is recorded as-is.
+   *
+   * @param event - Event identifier (convention: `domain:action`).
+   * @param data - Optional structured payload.
+   * @param error - Optional originating Error to merge into `data`.
+   */
+  error(event: string, data?: unknown, error?: Error): void;
+  /**
+   * Return a frozen snapshot of the entries recorded so far (a fresh copy).
+   *
+   * @returns A readonly, frozen copy of the recorded entries.
+   */
+  trace(): readonly LogEntry[];
+  /**
+   * Return a fluent assertion chain bound to the live entries array.
+   *
+   * @returns A fresh {@link ExpectChain}.
+   */
+  expect(): ExpectChain;
+  /**
+   * Register an additional output sink at runtime.
+   *
+   * @param sink - The sink to add to the fan-out list.
+   */
+  addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
+  reset(): void;
+};
+//#endregion
+//#region src/plugins/log/index.d.ts
+/**
+ * Core logging plugin — always-on in-memory trace + `expect()` event-trace DSL.
+ * API injected as `ctx.log` on every regular plugin and surfaced as `app.log`.
+ * No depends / events / hooks (core plugin per spec/03 §5).
+ *
+ * @see README.md
+ */
+declare const logPlugin: import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>;
+declare namespace types_d_exports {
+  export { EnvApi, EnvConfig, EnvProvider, EnvState, EnvVarSpec };
+}
+/**
+ * @file env plugin — public + boundary type definitions.
+ */
+/**
+ * A source of raw environment values.
+ *
+ * Providers are walked in array order during resolution; the first provider to
+ * return a non-`undefined` (and non-empty-string) value for a key wins. `load()`
+ * is called exactly once per resolution at `onInit` time, after which both env
+ * maps are frozen. A provider like {@link cloudflareBindings} reads `globalThis`
+ * at that single `onInit` call (not per request).
+ *
+ * @example
+ * ```ts
+ * const custom: EnvProvider = {
+ *   name: "vault",
+ *   load: () => ({ DB_URL: readVaultSecret("db") })
+ * };
+ * ```
+ */
+interface EnvProvider {
+  /** Human-readable provider name, used in diagnostics and error messages. */
+  name: string;
+  /**
+   * Reads this provider's current view of the environment.
+   *
+   * @returns A flat record of variable names to string values. Keys the
+   *   provider cannot supply must be omitted or set to `undefined`.
+   */
+  load(): Record<string, string | undefined>;
+}
+/**
+ * Declares how a single environment variable is validated and exposed.
+ *
+ * @example
+ * ```ts
+ * const port: EnvVarSpec = { public: false, required: false, default: "3000" };
+ * const apiBase: EnvVarSpec = { public: true }; // key must start with PUBLIC_
+ * const token: EnvVarSpec = { public: false, required: true, secret: true };
+ * ```
+ */
+interface EnvVarSpec {
+  /**
+   * Whether the variable is safe to ship to the browser. When `true`, the key
+   * **must** start with {@link EnvConfig.publicPrefix} (cross-checked at
+   * `onInit`), and the variable is included in {@link EnvApi.getPublicMap}.
+   */
+  public: boolean;
+  /** Whether resolution fails if the variable is still undefined after defaults. */
+  required?: boolean;
+  /** Value applied when no provider supplies the variable. */
+  default?: string;
+  /**
+   * Marks the variable as a secret for documentation / tooling. Has no runtime
+   * effect on resolution, but secrets are never permitted to be `public`.
+   */
+  secret?: boolean;
+}
+/**
+ * Configuration for the {@link envPlugin} core plugin.
+ *
+ * @example
+ * ```ts
+ * createCoreConfig("web", {
+ *   plugins: [envPlugin],
+ *   pluginConfigs: {
+ *     env: {
+ *       schema: {
+ *         PUBLIC_API_URL: { public: true, default: "/api" },
+ *         SESSION_SECRET: { public: false, required: true, secret: true }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+type EnvConfig = {
+  /** Per-variable validation + exposure rules, keyed by variable name. */schema: Record<string, EnvVarSpec>;
+  /**
+   * Ordered list of value sources. The first provider yielding a non-`undefined`
+   * (and non-empty-string) value for a key wins. The plugin's own spec default is
+   * `[]`; the consumer supplies the providers per target (`[dotenv(), processEnv()]`
+   * on Node) — only the `/browser` entry pre-wires `browserEnv()` out of the box.
+   */
+  providers: EnvProvider[];
+  /**
+   * Prefix that public variable names must carry. Bidirectionally enforced at
+   * `onInit`. Framework default is `"PUBLIC_"`.
+   */
+  publicPrefix: string;
+};
+/**
+ * Internal env plugin state: the resolved variable table and its public subset.
+ * Both maps are populated and frozen (via `freezeMap`) during `onInit`.
+ *
+ * Exported only to type the `createState` / `api` / `validate` boundary —
+ * consumers use {@link EnvApi}, never `EnvState`.
+ */
+interface EnvState {
+  /** All validated variables that resolved to a defined value (incl. defaults). */
+  resolved: Map<string, string>;
+  /** Subset of `resolved` where `schema[key].public === true`. */
+  publicMap: Map<string, string>;
+}
+/**
+ * The resolved-environment accessor mounted at `ctx.env`. Built by the plugin's
+ * `api` factory over `ctx.state` ({@link EnvState}).
+ *
+ * Available after `onInit` (i.e. inside any plugin's lifecycle and in consumer
+ * code). All accessors read from the frozen `resolved` / `publicMap` maps;
+ * mutation is impossible.
+ *
+ * @example
+ * ```ts
+ * const url = ctx.env.get("PUBLIC_API_URL"); // string | undefined
+ * const token = ctx.env.require("DEPLOY_TOKEN"); // string, or throws
+ * ```
+ */
+type EnvApi = {
+  /**
+   * Reads a resolved variable.
+   *
+   * @param key - Variable name.
+   * @returns The value, or `undefined` if not present / not in schema.
+   */
+  get(key: string): string | undefined;
+  /**
+   * Reads a variable that must exist.
+   *
+   * @param key - Variable name.
+   * @returns The value.
+   * @throws {Error} If the variable is undefined.
+   */
+  require(key: string): string;
+  /**
+   * Tests presence of a resolved variable.
+   *
+   * @param key - Variable name.
+   * @returns `true` if a value is present.
+   */
+  has(key: string): boolean;
+  /**
+   * Returns all public variables as a frozen plain object — convenient for
+   * spreading into a serializable payload.
+   *
+   * @returns A frozen `Record` of public variable names to values.
+   */
+  getPublic(): Readonly<Record<string, string>>;
+  /**
+   * Returns the frozen map of public variables. This is the **sole** intended
+   * input to a build-time `define` injection: every entry is safe to inline
+   * into the browser bundle.
+   *
+   * @returns The frozen public map.
+   */
+  getPublicMap(): ReadonlyMap<string, string>;
+};
+//#endregion
+//#region src/plugins/env/providers.browser.d.ts
+/**
+ * A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
+ * `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
+ * Contains zero `node:*` imports, so it is safe to include in the client bundle.
+ * Never throws on missing sources — each absent source resolves to `{}`.
+ *
+ * @param options - Optional settings.
+ * @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
+ * @returns An {@link EnvProvider} named `browser-env`.
+ * @example
+ * ```ts
+ * const provider = browserEnv();
+ * provider.load(); // { PUBLIC_API_URL: "/api", ... }
+ * ```
+ */
+declare function browserEnv(options?: {
+  globalKey?: string;
+}): EnvProvider;
+//#endregion
+//#region src/plugins/env/index.d.ts
+/**
+ * Core plugin that resolves, validates, and freezes the environment at `onInit`,
+ * exposing a read-only accessor at `ctx.env`. No `onStart`/`onStop` — holds no resource.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { env: { schema: { PUBLIC_API_URL: { public: true } } } } });
+ * ```
+ */
+declare const envPlugin: import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>;
+//#endregion
+export { types_d_exports as Env, types_d_exports$1 as Log, browserEnv, envPlugin, logPlugin };