@smthrs/plugin 0.0.0-stage → 1.0.0-rc.3

package/docs/guides/select-plugins.md

@@ -0,0 +1,72 @@
+---
+title: "Include a plugin conditionally"
+description: "Use apply to select a plugin by host target or by a predicate over the pre-resolution configuration, and know what selection does not excuse."
+sidebar:
+  order: 3
+---
+
+A plugin can decide it does not belong in this composition. Declare `apply`,
+and the kernel drops the plugin before it contributes a handler, a layer, or a
+cache identity.
+
+## Select by host target
+
+`apply: "engine"` and `apply: "harness"` name the host the plugin is for. The
+kernel compares the literal with the `target` option, which defaults to
+`"engine"`:
+
+```ts
+import { Kernel, make } from "@smthrs/plugin"
+
+const list = [
+  make({ name: "flows-plugin-shared" }),
+  make({ name: "flows-plugin-harness-only", apply: "harness" })
+]
+
+// Engine kernel: only flows-plugin-shared is selected.
+const engine = Kernel.make(list)
+
+// Harness kernel: both are selected.
+const harness = Kernel.make(list, {}, { target: "harness" })
+```
+
+A plugin with no `apply` is always selected. This is how one shared preset
+serves two hosts: list every plugin once, and let each host take its half.
+
+## Select by a predicate over the configuration
+
+A predicate receives the pre-resolution configuration, the same value you passed
+to `Kernel.make`, and returns a boolean:
+
+```ts
+const fast = make({
+  name: "flows-plugin-fast",
+  apply: (config) => config["mode"] === "fast"
+})
+
+const kernel = Kernel.make([fast], { mode: "fast" })
+```
+
+The configuration a predicate sees is a snapshot taken before the first
+predicate runs, so a predicate cannot observe another predicate's side effects,
+and a caller cannot mutate the object between two predicate calls.
+
+It is the _pre-resolution_ configuration: the `config` waterfall has not run
+yet, so a predicate cannot see a namespace another plugin is about to
+contribute. Selection has to settle before the waterfall, because the waterfall
+runs the plugins selection chose.
+
+A predicate that throws fails resolution with `apply_failed`, and its raw
+failure is not retained. A predicate that returns anything other than a boolean
+fails with `invalid_plugin`. Keep predicates pure and total.
+
+## What selection does not excuse
+
+Every plugin record is validated before `apply` runs, so a malformed plugin
+fails startup even when the predicate would have excluded it. Selection cannot
+hide a typo.
+
+Hook names are checked after selection, and that asymmetry is deliberate: a
+shared preset may carry `apply: "harness"` plugins whose hooks only the harness
+catalog declares, and it still resolves under a bare engine kernel because those
+plugins were never selected.

package/docs/guides/testing.md

@@ -0,0 +1,149 @@
+---
+title: "Test a plugin"
+description: "Exercise a plugin without booting a host: resolve a list, dispatch a hook, assert on ordering and typed failures, and stub the kernel out of a composition under test."
+sidebar:
+  order: 6
+---
+
+A plugin is a plain record and the dispatcher is a plain service, so a plugin
+test needs no host, no engine, and no I/O. Resolve the list, dispatch the hook,
+assert on the result.
+
+## Dispatch a hook without a kernel
+
+`Resolve.resolve` gives you the catalog and `Plugins.make` gives you the
+dispatcher. Use them directly when the test is about one hook, with the hook
+interface as an explicit type argument:
+
+```ts
+import { type FlowsPlugin, Plugins, Resolve, type WaterfallHook } from "@smthrs/plugin"
+import * as Effect from "effect/Effect"
+import { expect, it } from "vitest"
+
+interface HostHooks {
+  readonly tools: WaterfallHook<
+    (tools: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string> | void>
+  >
+}
+
+const subject: FlowsPlugin<HostHooks> = {
+  name: "flows-plugin-subject",
+  hooks: { tools: (tools) => Effect.succeed([...tools, "read", "write"]) }
+}
+
+it("contributes its tools", async () => {
+  const resolved = await Effect.runPromise(
+    Resolve.resolve<HostHooks>([subject], { hooks: { tools: "waterfall" } })
+  )
+  const tools = await Effect.runPromise(
+    Plugins.make<HostHooks>(resolved).waterfall("tools", [] as ReadonlyArray<string>, (_previous, next) => next)
+  )
+  expect(tools).toEqual(["read", "write"])
+})
+```
+
+Use `Kernel.make` instead when the test is about the whole startup path: the
+waterfall, the freeze, the observers, and the merged layer together.
+
+## Startup hooks see no services
+
+The shared `config` and `configResolved` hooks are context-free: `Kernel.make`
+runs them before any plugin layer exists and supplies nothing itself, so a
+handler that reads a service does not compile against `FlowsHooks`, and one
+cast past the type fails at runtime with `hook_failed` on that hook. Provide
+the service inside the hook, or, when a host's startup hooks genuinely require
+services, declare a separate hook interface and provide them to the startup
+Effect. `Kernel.make<H>` carries the requirement as `Kernel.StartupContext<H>`:
+
+```ts
+interface HostHooks {
+  readonly config: WaterfallHook<
+    (config: FlowsConfig) => Effect.Effect<Partial<FlowsConfig> | void, never, Settings>
+  >
+  readonly configResolved: ParallelHook<(config: ResolvedConfig) => Effect.Effect<void, never, Settings>>
+}
+
+const kernel = await Effect.runPromise(
+  Kernel.make<HostHooks>([reader], {}, { hooks: { config: "waterfall", configResolved: "parallel" } }).pipe(
+    Effect.provideService(Settings, { enabled: true })
+  )
+)
+```
+
+Without the `provideService`, the program does not compile.
+
+## Assert the order, not just the membership
+
+`resolved.plugins` is the resolved plugin order and
+`resolved.handlers.get(hook)` is the ordered handler list for one hook, each
+record carrying the plugin that declared it:
+
+```ts
+const names = (resolved: Resolve.Resolved, hook: string) =>
+  (resolved.handlers.get(hook) ?? []).map((record) => record.plugin)
+
+expect(names(resolved, "configResolved")).toEqual(["early", "normal", "late"])
+```
+
+Assert both when a plugin declares a per-hook `order`: the two lists differ on
+purpose, and only the handler list proves the hook is positioned the way you
+meant.
+
+## Assert typed failures by code
+
+Every refusal is a `PluginError` with a `code`, and most carry the plugin, the
+hook, and the value path. Flip the Effect and match the fields you care about:
+
+```ts
+import { Kernel } from "@smthrs/plugin"
+
+const error = await Effect.runPromise(
+  Kernel.make([{ name: "duplicate" }, { name: "duplicate" }]).pipe(Effect.flip)
+)
+expect(error).toMatchObject({ code: "duplicate_name", plugin: "duplicate" })
+```
+
+Match on `code`, `plugin`, `hook`, and `path`, not on `message`. The codes are a
+closed set, listed in [Troubleshooting](../troubleshooting.md); the messages are
+prose and may be reworded.
+
+## Observer failures are a return value
+
+A failing `configResolved` handler does not fail startup, so an assertion that
+the kernel succeeded proves nothing about it. Read `observerErrors`:
+
+```ts
+const kernel = await Effect.runPromise(
+  Kernel.make([{ name: "noisy", hooks: { configResolved: () => Effect.fail("boom") } }])
+)
+expect(kernel.observerErrors.map((error) => error.plugin)).toEqual(["noisy"])
+```
+
+## Stub the kernel out of a composition under test
+
+When the subject is the host rather than the plugins, give it a dispatcher with
+no plugins at all:
+
+```ts
+const dispatcher = Plugins.makeNoop()
+```
+
+`Plugins.layerNoop` is the same thing as a layer, for a composition that resolves
+the shared `Plugins` service tag. Both dispatch nothing: a parallel hook returns
+an empty error list, a first hook answers `Option.none()`, and a waterfall
+returns the value it was given.
+
+## Test the pure pieces directly
+
+`Config.merge` and `Config.deepFreeze` are ordinary functions that throw a
+`PluginError` rather than returning an Effect, so a merge-semantics test needs no
+runtime:
+
+```ts
+import { Config } from "@smthrs/plugin"
+
+expect(Config.merge({ a: { b: 1 } }, { a: { c: 2 } })).toEqual({ a: { b: 1, c: 2 } })
+```
+
+`Hooks.handlerOf` and `Hooks.orderOf` read either hook entry form and are the
+same shape of test.

package/docs/installation.md

@@ -0,0 +1,71 @@
+---
+title: "Installation"
+description: "Install @smthrs/plugin, its runtime requirements, its import forms, and the subpaths its export map blocks."
+sidebar:
+  order: 1
+---
+
+## Install the package
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Install `effect` explicitly at `4.0.0-rc.115`. The kernel depends on it, but your
+plugins import `Effect`, `Layer`, and `Option` directly, so `effect` belongs in
+your own dependency list at the release the kernel is built against. A different
+`effect` major gives you two copies of the runtime and two sets of service tags.
+
+The package requires Node.js 26.4.0 or later and ships as both ESM and
+CommonJS with TypeScript declarations. Its runtime dependencies install with it:
+[`@smthrs/flow`](/api/flow) supplies `Action.CacheEnvironment` for
+[cache identity](./guides/cache-identity.md), and
+[`@smthrs/canonical`](/api/canonical) supplies immutable catalog maps.
+
+## Import forms
+
+The root entry point exports the plugin, hook, and error declarations directly,
+and the four stateful modules as namespaces:
+
+```ts
+import { Config, Kernel, Plugins, Resolve } from "@smthrs/plugin"
+import type { FlowsHooks, FlowsPlugin, PluginInput } from "@smthrs/plugin"
+import { engineHooks, make, PluginError } from "@smthrs/plugin"
+```
+
+Each module is also importable from its own subpath, which is the form the
+[API reference](./api.md) uses:
+
+```ts
+import * as Config from "@smthrs/plugin/Config"
+import * as Kernel from "@smthrs/plugin/Kernel"
+import * as Plugins from "@smthrs/plugin/Plugins"
+import * as Resolve from "@smthrs/plugin/Resolve"
+```
+
+The full list of public subpaths is `@smthrs/plugin/Config`,
+`@smthrs/plugin/Hooks`, `@smthrs/plugin/Kernel`, `@smthrs/plugin/Plugin`,
+`@smthrs/plugin/PluginError`, `@smthrs/plugin/Plugins`, and
+`@smthrs/plugin/Resolve`. Two forms are blocked in the export map:
+`@smthrs/plugin/internal/*` and `@smthrs/plugin/*/index`.
+`@smthrs/plugin/package.json` is exported.
+
+## The augmentation specifier
+
+A host that declares its own hooks augments the interface in the root module,
+never in a subpath:
+
+```ts
+declare module "@smthrs/plugin" {
+  interface FlowsHooks {
+    // your hooks
+  }
+}
+```
+
+`FlowsHooks` is declared in the entry point precisely so this specifier works:
+TypeScript can augment an interface only in the module that declares it. See
+[Declare hooks for your host](./guides/host-your-own-hooks.md).
+
+## Next step
+
+Build a host with one hook of its own and run it in the
+[Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,151 @@
+---
+title: "Quickstart"
+description: "Build a host with a hook of its own: declare the catalog, write two plugins, run the kernel, and dispatch the hook to a typed result."
+sidebar:
+  order: 2
+---
+
+This quickstart builds a small host end to end. The host offers plugins one
+extension point of its own, a `tools` waterfall, alongside the kernel's config
+lifecycle. By the end you will have run the kernel, read a frozen configuration,
+and dispatched a hook whose result is typed by the declaration you wrote.
+
+The example uses two files: `host.ts` declares the hook catalog, and `main.ts`
+defines the plugins and runs the host. There are no services to provide.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later.
+- A TypeScript project with the package installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## Declare the host's hook catalog
+
+A host declares its hooks twice: once in the type system, so plugin authors get
+completion and excess-key errors, and once as a runtime catalog, so the kernel
+can refuse a hook name nobody dispatches.
+
+Create `host.ts`:
+
+```ts
+import { engineHooks, type WaterfallHook } from "@smthrs/plugin"
+import type * as Effect from "effect/Effect"
+
+declare module "@smthrs/plugin" {
+  interface FlowsHooks {
+    /** Contributes or rewrites the tool names the host offers. */
+    readonly tools: WaterfallHook<
+      (tools: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string> | void>
+    >
+  }
+}
+
+/** The runtime catalog: the kernel's two config hooks plus this host's one. */
+export const hooks = Object.freeze(
+  {
+    ...engineHooks,
+    tools: "waterfall"
+  } as const
+)
+```
+
+The two declarations must agree. The interface says what compiles; the runtime
+catalog says what dispatches. `WaterfallHook` in the interface and
+`"waterfall"` in the catalog are the same claim, written for the two audiences.
+
+## Write two plugins
+
+Add all remaining TypeScript snippets to `main.ts` in order, starting with the
+complete import block and the first plugin.
+
+A plugin is a record. This one contributes a configuration namespace and two
+tools.
+
+Create `main.ts` beside `host.ts`:
+
+```ts
+import { type FlowsHooks, Kernel, make } from "@smthrs/plugin"
+import * as Effect from "effect/Effect"
+import { hooks } from "./host.ts"
+
+const editor = make<FlowsHooks>({
+  name: "flows-plugin-editor",
+  hooks: {
+    config: () => Effect.succeed({ editor: { readOnly: false } }),
+    tools: (tools) => Effect.succeed([...tools, "read", "write"])
+  }
+})
+```
+
+`make` is an identity function that pins the literal to `FlowsPlugin<H>`. Pass
+the hook interface explicitly, as above: it is what types the `tools` parameter
+as `ReadonlyArray<string>` and what makes a misspelled hook key fail at the
+definition site instead of at startup.
+
+The second plugin runs first, because it is declared `enforce: "pre"`, and it
+reads what the host resolved rather than adding to it:
+
+```ts
+const audit = make<FlowsHooks>({
+  name: "flows-plugin-audit",
+  enforce: "pre",
+  hooks: {
+    configResolved: (config) => Effect.log(`resolved namespaces: ${Object.keys(config).join(", ")}`)
+  }
+})
+```
+
+## Run the kernel
+
+`Kernel.make` takes the plugin list, the pre-resolution configuration, and the
+host's options. It resolves the list, runs the config waterfall, freezes the
+result, notifies the observers, and merges the plugin layers:
+
+```ts
+const kernel = await Effect.runPromise(
+  Kernel.make([editor, audit], { host: { name: "quickstart" } }, { target: "harness", hooks })
+)
+
+console.log(kernel.config)
+// { host: { name: "quickstart" }, editor: { readOnly: false } }
+```
+
+`target` names which kind of host you are, and it is what a plugin's
+`apply: "engine" | "harness"` selector is compared against. It defaults to
+`"engine"`, meaning the Smithers durable engine, so pass `"harness"` for any
+other host, including this one.
+
+## Dispatch the hook
+
+`kernel.plugins` is the dispatcher. A waterfall needs one more argument than the
+other kinds, the merge function that folds each handler's answer into the value
+the next handler sees:
+
+```ts
+const tools = await Effect.runPromise(
+  kernel.plugins.waterfall("tools", [] as ReadonlyArray<string>, (_previous, next) => next)
+)
+
+console.log(tools) // ["read", "write"]
+```
+
+The literal `"tools"` is checked against the hook interface: a name that is not
+a waterfall in `FlowsHooks` does not compile, and `tools` is typed as the
+handler's argument type, not as `unknown`.
+
+## What you just built
+
+- A hook catalog only your host dispatches. Another host augmenting the same
+  interface still dispatches only the catalog it supplied.
+- A plugin list resolved once into a frozen catalog. Mutating `editor` after
+  this point changes nothing about dispatch.
+- A configuration every plugin agreed on, deeply copied and frozen before the
+  first plugin saw it.
+
+## Next steps
+
+- [Hook kinds](./concepts/hook-kinds.md) for what `sequential`, `parallel`,
+  `first`, and `waterfall` each promise.
+- [Control the order handlers run in](./guides/order-handlers.md) for `enforce`
+  and the per-hook `order`.
+- [Contribute services from a plugin](./guides/contribute-services.md) to add a
+  `layer` to the plugin above.

package/docs/troubleshooting.md

@@ -0,0 +1,179 @@
+---
+title: "Troubleshooting"
+description: "Every PluginError code the kernel reports, what causes it, and what to change, plus the failures that are silent by design."
+---
+
+Every refusal this package makes is a `PluginError` with a `code` from a closed
+set. Find the code and read its section. The full error schema is in the
+[API reference](./api.md).
+
+Most errors carry `plugin`, `hook`, and `path` alongside the message. Read
+`path` first: it is a diagnostic dollar-path into the value the kernel refused,
+not an RFC 6901 JSON Pointer. `$` is the input, `.config` an identifier
+property, `[2]` an array index, and `["not an identifier"]` any other key,
+JSON-quoted. So `$[2].hooks.config` is the third plugin's `config` entry and
+`$options.parallelConcurrency` is an option.
+
+## duplicate_name
+
+**What happened.** Two selected plugins have the same name. Names compare as
+exact Unicode strings with no normalization, so this is a real collision, not a
+spelling variant.
+
+**What to change.** Rename one, or exclude one with
+[`apply`](./guides/select-plugins.md). The kernel refuses rather than letting
+the last one win, because last-wins turns a duplicated preset into a silently
+dropped plugin.
+
+## unknown_hook
+
+**What happened.** A selected plugin declares a hook name that is not in the
+host's runtime catalog. The error names the plugin and the hook.
+
+**What to change.** If the hook is yours to add, list it in the catalog you pass
+as `Resolve.Options.hooks` and augment `FlowsHooks` to match. See
+[Declare hooks for your host](./guides/host-your-own-hooks.md). If the hook
+belongs to a different host, give the plugin an `apply` selector so this host
+does not select it.
+
+Passing no catalog means the shared one: `config` and `configResolved` only.
+
+## hook_kind_mismatch
+
+**What happened.** The runtime catalog and the kind actually run disagree.
+At startup, `Options.hooks` labelled `config` with a kind other than
+`waterfall`, or `configResolved` with a kind other than `parallel`; the path
+names the entry, such as `$options.hooks.config`. At dispatch, a method was
+called for a hook the catalog declares with a different kind, which only a cast
+around the typed dispatcher can reach. In both cases no handler ran.
+
+**What to change.** Make the catalog agree with the hook interface: spread
+`engineHooks` for the shared hooks and write each of your own hooks with the
+kind its type declares. `HookCatalog<H>` refuses a wrong kind for a declared
+name at compile time.
+
+## invalid_plugin
+
+**What happened.** A plugin, preset, option, or hook entry has a shape the
+kernel will not accept. Common causes, each reported at its own path:
+
+- A hook entry that is `undefined` or `null`. Declarations must be callable, so
+  a conditionally built hook is refused rather than skipped.
+- An unknown property on a plugin record or on the options object.
+- A name or version that is empty, whitespace only, longer than 256 UTF-16 code
+  units, or not well-formed text.
+- `enforce` or `order` that is not `"pre"` or `"post"`.
+- `apply` that is not `"engine"`, `"harness"`, or a function.
+- `layer` that is not an Effect `Layer`.
+- A preset array that is sparse, cyclic, repeated, or carries extra properties.
+- An accessor, a symbol key, or a non-enumerable property anywhere in the
+  record.
+
+**What to change.** Read `path`, fix that value. To omit an optional hook, leave
+the key out of the `hooks` record instead of setting it to `undefined`.
+
+## apply_failed
+
+**What happened.** An `apply` predicate threw. The raw failure is not retained,
+because a predicate runs before the kernel has anywhere safe to put an arbitrary
+value.
+
+**What to change.** Make the predicate total. It receives the pre-resolution
+configuration and must return a boolean without reading anything it cannot
+guarantee is there. A predicate that returns a non-boolean fails with
+`invalid_plugin` instead.
+
+## config_invalid
+
+**What happened.** A configuration value is not bounded strict JSON, or it uses
+a reserved root key. This covers the pre-resolution config, any patch a `config`
+handler returned, and the merged result.
+
+**What to change.** Read `path`. The frequent causes:
+
+- `$.engine`, `$.retry`, `$.store`, or `$.plugins`: rename the namespace. The
+  kernel does not apply those policies and refuses to look like it does.
+- An `undefined` member: omit the key, or write `null`. `{ endpoint: undefined }`
+  fails at `$.endpoint` rather than resolving to `{}`.
+- A `Date`, `Map`, class instance, or non-finite number: encode it as JSON, or
+  keep it in a service instead of in configuration.
+- `__proto__`, `constructor`, or `prototype` as a key at any depth.
+- A tree over 1 MiB, 64 deep, 4,096 members, or 8,192 values. See
+  [Configuration](./concepts/configuration.md) for the whole list.
+
+When a `config` handler returned the offending patch, the error also carries
+that plugin and hook.
+
+## cache_environment_invalid
+
+**What happened.** You declared `cacheEnvironment` and the kernel could not
+build a complete identity from it. Either a selected plugin has no `version`, or
+the environment does not match the `Action.CacheEnvironment` schema.
+
+**What to change.** Add a `version` to every selected plugin, or drop
+`cacheEnvironment` and let sealed keys stay run-local. Both are correct; a bare
+plugin name folded into a cross-run cache key is not. See
+[Declare a cache identity](./guides/cache-identity.md).
+
+## invalid_hook_result
+
+**What happened.** A `first` hook handler returned something other than an
+`Option`. The error names the plugin and the hook.
+
+**What to change.** Return `Option.some(value)` to answer and `Option.none()` to
+pass. A `first` hook stops at the first `some`, so returning a bare value would
+make "no opinion" indistinguishable from "the answer is undefined".
+
+## resource_limit
+
+**What happened.** The plugin input, the handler count, or a concurrency option
+exceeded a published bound: 256 plugins, 1,024 handlers, 4,096 input nodes, 64
+nested preset arrays, or a `parallelConcurrency` outside 1 through 256.
+
+**What to change.** Split the composition, or raise nothing: these bounds are
+fixed. A list this large is usually a preset included twice or an array building
+itself in a loop. The [limits table](./concepts/resolution.md) has each bound
+and the export that names it.
+
+## hook_failed
+
+**What happened.** A handler failed, defected, threw synchronously, or returned
+something that is not an Effect. The error names the plugin and the hook, and
+the original failure is on `cause`.
+
+**What to change.** Fix the handler. Where it surfaces depends on the kind: a
+`sequential`, `first`, or `waterfall` hook fails the caller and stops dispatch
+at that handler, while a `parallel` hook returns the error and keeps going. See
+[Hook kinds](./concepts/hook-kinds.md).
+
+## layer_failed
+
+**What happened.** A plugin's layer failed while it was being built. The error
+names the plugin, with the layer's own failure on `cause`.
+
+**What to change.** Fix the layer's acquisition, or make the plugin conditional
+so it is not selected in compositions where its dependencies are absent. The
+failure arrives when something provides `kernel.layer`, not when `Kernel.make`
+returns.
+
+## Failures that are silent by design
+
+**A `configResolved` handler failed and nothing happened.** Parallel observers
+are lossy on purpose: their failures are collected, not raised. Read
+`kernel.observerErrors` and log them. A composition that ignores that array
+cannot tell a working observer from a broken one.
+
+**A plugin was dropped and no error was reported.** Exclusion is not a failure.
+`apply: "harness"` under the default `target: "engine"` drops the plugin
+silently, which is exactly what a shared preset needs. Check
+`kernel.plugins.resolved.plugins` for what was actually selected, and pass
+`{ target: "harness" }` if your host is a harness.
+
+**A hook never runs even though it resolved.** The kernel dispatches only the
+config lifecycle. Every other hook runs when the host calls the dispatcher for
+it, so a hook in the catalog that no host code dispatches is a handler nobody
+calls.
+
+**Mutating a plugin or a config object after startup changed nothing.**
+Resolution copies everything it accepts. Dispatch reads the kernel's own frozen
+records, never yours. Change the input and resolve again.