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

package/docs/guides/order-handlers.md

@@ -0,0 +1,76 @@
+---
+title: "Control the order handlers run in"
+description: "Pick between the plugin-wide enforce group and the per-hook order object, and know which one wins when they disagree."
+sidebar:
+  order: 2
+---
+
+Two levers decide when your handler runs. Use `enforce` when the plugin as a
+whole belongs early or late. Use the per-hook `order` when one hook needs a
+different position from the rest of the plugin.
+
+## Move the whole plugin with enforce
+
+`enforce` puts a plugin in the `pre`, normal, or `post` group. Within a group,
+plugins keep the order you listed them in:
+
+```ts
+import { make } from "@smthrs/plugin"
+
+const early = make({ name: "flows-plugin-early", enforce: "pre", hooks: { configResolved: handler } })
+const late = make({ name: "flows-plugin-late", enforce: "post", hooks: { configResolved: handler } })
+```
+
+The resulting list is the resolved plugin order, and it decides two things
+beyond hook dispatch: the order `kernel.layer` merges plugin layers in, and the
+order plugin identities appear in a declared cache identity.
+
+## Move one hook with the ordering object
+
+Replace the bare handler with `{ order, handler }` to position that hook alone:
+
+```ts
+const plugin = make({
+  name: "flows-plugin-mixed",
+  hooks: {
+    config: handler,
+    configResolved: { order: "pre", handler }
+  }
+})
+```
+
+Here `config` runs at the plugin's normal position and `configResolved` runs
+early. The object form is the only way to give one plugin two different
+positions.
+
+## The per-hook order wins
+
+When the two levers disagree, the per-hook `order` wins, because it is applied
+second and re-partitions the already-sorted list:
+
+```ts
+const plugins = [
+  make({ name: "flows-plugin-a", enforce: "post", hooks: { configResolved: { order: "pre", handler } } }),
+  make({ name: "flows-plugin-b", enforce: "pre", hooks: { configResolved: { order: "post", handler } } })
+]
+// configResolved order: flows-plugin-a, then flows-plugin-b.
+```
+
+This is Vite's rule, kept verbatim, so a plugin ported from Vite orders the same
+way here. The full statement of it is in
+[Resolution](../concepts/resolution.md).
+
+## Do not order by list position alone
+
+Within a group, the array order is stable and it is the tiebreaker. It is also
+the weakest of the three signals: a host that concatenates presets, or a user
+who reorders a config file, changes it without meaning to. Declare `enforce` or
+`order` when the position matters, and leave both off when it does not.
+
+## Ordering is not a dependency system
+
+There is no `dependsOn`, and no cycle detection, because there are no
+dependencies to cycle. If your plugin needs another plugin's contribution, read
+it from the value the hook threads through: a waterfall handler sees what the
+earlier handlers produced, and a `configResolved` observer sees the whole
+resolved configuration.

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,75 @@
+---
+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
+
+```bash
+npm install @smthrs/plugin@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
+
+Install `effect` explicitly, at exactly `4.0.5`. The kernel depends on it, but your
+plugins import `Effect`, `Layer`, and `Option` directly, so `effect` belongs in
+your own dependency list, inside the range the kernel accepts. 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,152 @@
+---
+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:
+  `npm install @smthrs/plugin@next effect`.
+
+## 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.