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

package/src/Kernel.ts

@@ -0,0 +1,119 @@
+/**
+ * Startup: resolve the plugin list, run the config pipeline, hand back a
+ * dispatcher, a frozen config, and the merged layer.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}, with the shipped host catalog in
+ * `packages/smithers/agent/src/CellPlugin.ts`. D14 in
+ * `docs/pages/design-decisions.md` keeps durable policy outside these hooks.
+ *
+ * Order of operations, per the spec:
+ *
+ * 1. flatten / filter / validate / order the plugin list;
+ * 2. `config` waterfall: each plugin may return a partial to deep-merge;
+ * 3. decode and freeze into a `ResolvedConfig` (`config_invalid` on failure);
+ * 4. `configResolved` parallel: observers capture the final config;
+ * 5. plugin `layer`s merge left-to-right.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Effect from "effect/Effect"
+import type * as Layer from "effect/Layer"
+import type { FlowsConfig, ResolvedConfig } from "./Config.ts"
+import * as Config from "./Config.ts"
+import type { ContextOf } from "./Hooks.ts"
+import type { FlowsHooks } from "./index.ts"
+import type { PluginInput } from "./Plugin.ts"
+import type { PluginError } from "./PluginError.ts"
+import * as Plugins from "./Plugins.ts"
+import * as Resolve from "./Resolve.ts"
+
+/**
+ * Everything startup produces from a plugin list and a raw config.
+ *
+ * `observerErrors` carries `configResolved` failures: parallel observers are
+ * lossy by contract, so they are reported rather than fatal.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Kernel<H = FlowsHooks> {
+  readonly plugins: Plugins.Service<H>
+  readonly config: ResolvedConfig
+  readonly layer: Layer.Layer<any, PluginError, any>
+  readonly observerErrors: ReadonlyArray<PluginError>
+}
+
+type HookAt<H, K extends string> = K extends keyof H ? H[K] : never
+
+/**
+ * The services a hook interface's `config` hook requires at startup. `never`
+ * for the shared `FlowsHooks`, whose startup hooks are context-free.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ConfigContext<H> = ContextOf<HookAt<H, "config">>
+
+/**
+ * The services a hook interface's startup hooks require: the union of the
+ * `config` and `configResolved` requirements. `Kernel.make` cannot supply
+ * them itself, so they surface in its Effect and the caller provides them.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type StartupContext<H> = ConfigContext<H> | ContextOf<HookAt<H, "configResolved">>
+
+/**
+ * Snapshots the config before dispatching the `config` waterfall, then
+ * admits the result as a frozen `ResolvedConfig`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const runConfig = <H = FlowsHooks>(
+  plugins: Plugins.Service<H>,
+  config: FlowsConfig
+): Effect.Effect<ResolvedConfig, PluginError, ConfigContext<H>> =>
+  Effect.gen(function*() {
+    const initial = yield* Config.snapshot(config)
+    const merged = yield* (plugins.waterfall as unknown as (
+      hook: string,
+      initial: FlowsConfig,
+      merge: (previous: FlowsConfig, patch: unknown) => FlowsConfig
+    ) => Effect.Effect<FlowsConfig, PluginError, ConfigContext<H>>)("config", initial, Config.merge)
+    return yield* Config.resolve(merged)
+  })
+
+/**
+ * Resolves plugins, executes the config pipeline, and merges plugin layers.
+ * The positional `config` is the kernel's only pre-resolution configuration;
+ * the options object cannot declare a second source, and a `config` key
+ * supplied anyway fails with `invalid_plugin` at `$options.config`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = <H = FlowsHooks>(
+  input: PluginInput<NoInfer<H>>,
+  config: FlowsConfig = {},
+  options: Omit<Resolve.Options<NoInfer<H>>, "config"> = {}
+): Effect.Effect<Kernel<H>, PluginError, StartupContext<H>> =>
+  Effect.gen(function*() {
+    const initial = yield* Config.snapshot(config)
+    const resolved = yield* Resolve.resolve<H>(input, options, initial)
+    const dispatcher = Plugins.make<H>(resolved)
+    const frozen = yield* runConfig(dispatcher, initial)
+    const observerErrors = yield* (dispatcher.parallel as unknown as (
+      hook: string,
+      value: ResolvedConfig
+    ) => Effect.Effect<ReadonlyArray<PluginError>, never, StartupContext<H>>)("configResolved", frozen)
+    return Object.freeze({
+      plugins: dispatcher,
+      config: frozen,
+      layer: Resolve.layer(resolved),
+      observerErrors
+    })
+  })

package/src/Plugin.ts

@@ -0,0 +1,80 @@
+/**
+ * The plugin object: a plain record produced by a factory function.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. The shipped consumer is the
+ * assembled cell host in `@smthrs/agent`;
+ * durable-core policy continues to use Effect services and constructor
+ * options rather than plugin lifecycle hooks.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import type * as Layer from "effect/Layer"
+import type { FlowsConfig } from "./Config.ts"
+import type { FlowsHooks } from "./index.ts"
+
+/**
+ * Conditional-inclusion predicate, mirroring Vite's `apply`.
+ *
+ * `"engine"` and `"harness"` select the matching plugin-kernel host. The
+ * assembled cell host resolves as `"harness"`; this does not make `"engine"` an
+ * engine-lifecycle hook registration.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Apply = "engine" | "harness" | ((config: FlowsConfig) => boolean)
+
+/**
+ * A flows plugin.
+ *
+ * Generic over the hook interface so a harness can hold plugins typed against
+ * its augmented `FlowsHooks` without any inheritance machinery.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface FlowsPlugin<H = FlowsHooks> {
+  /** Required, unique. Convention: `flows-plugin-<thing>`. */
+  readonly name: string
+  /**
+   * Semantic identity folded into sealed cache keys. Required when the host
+   * declares a cache environment. `Action.CacheEnvironment` is complete by
+   * contract, so a versionless composition is refused instead of claiming an
+   * ambiguous cross-run identity.
+   */
+  readonly version?: string | undefined
+  /** Ordering group; omitted means `"normal"`. */
+  readonly enforce?: "pre" | "post" | undefined
+  /** Conditional inclusion. */
+  readonly apply?: Apply | undefined
+  /** Services this plugin contributes to the engine environment. */
+  readonly layer?: Layer.Layer<never, any, any> | undefined
+  /** Typed hooks; only keys declared in the hook interface compile. */
+  readonly hooks?: Partial<H> | undefined
+}
+
+/**
+ * What a `plugins` array may contain: plugins, falsy entries, and arrays nested
+ * up to `Resolve.maximumPluginDepth`: so a preset is just a function returning
+ * plugins.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type PluginInput<H = FlowsHooks> =
+  | FlowsPlugin<H>
+  | false
+  | null
+  | undefined
+  | ReadonlyArray<PluginInput<H>>
+
+/**
+ * Identity constructor that pins a plugin literal to `FlowsPlugin` so excess
+ * hook keys are rejected at the definition site.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = <H = FlowsHooks>(plugin: FlowsPlugin<H>): FlowsPlugin<H> => plugin

package/src/PluginError.ts

@@ -0,0 +1,62 @@
+/**
+ * The single typed failure of the plugin kernel.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}; D14 in
+ * `docs/pages/design-decisions.md` bounds it to host-owned cell hooks.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * Closed set of plugin-system failure codes.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const PluginErrorCode = Schema.Literals([
+  "duplicate_name",
+  "unknown_hook",
+  "hook_kind_mismatch",
+  "invalid_plugin",
+  "apply_failed",
+  "config_invalid",
+  "cache_environment_invalid",
+  "invalid_hook_result",
+  "resource_limit",
+  "hook_failed",
+  "layer_failed"
+])
+
+/**
+ * Closed set of plugin-system failure codes.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type PluginErrorCode = typeof PluginErrorCode.Type
+
+/**
+ * Failure raised by plugin resolution, hook dispatch, config execution, or
+ * layer construction.
+ *
+ * Parallel observer failures never fail the caller; they are returned from
+ * `Plugins.parallel` with this same shape so they can be journalled on the
+ * lossy telemetry channel.
+ *
+ * `cause` is the plugin's unredacted failure and may hold secrets; hosts
+ * redact it before logging, persisting, or transmitting the error.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export class PluginError extends Schema.TaggedError<PluginError>()("flows/plugin/PluginError", {
+  code: PluginErrorCode,
+  message: Schema.String,
+  plugin: Schema.optional(Schema.String),
+  hook: Schema.optional(Schema.String),
+  path: Schema.optional(Schema.String),
+  cause: Schema.optional(Schema.Unknown)
+}) {}

package/src/Plugins.ts

@@ -0,0 +1,254 @@
+/**
+ * The dispatcher: a plain service over a resolved plugin list, generic over the
+ * hook interface.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. Each host holds an instance over its
+ * augmented `FlowsHooks` and may dispatch only the runtime catalog it supplied.
+ * The shipped cell host owns the three
+ * waterfalls declared in `packages/smithers/agent/src/CellPlugin.ts`; there is
+ * no engine-wide lifecycle dispatcher.
+ *
+ * Cancellation is fiber interruption via scope closure; nothing here threads an
+ * `AbortSignal`.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as ImmutableMap from "@smthrs/canonical/ReadonlyMap"
+import type * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import type { ArgsOf, ContextOf, HookKind, KeysOfKind, SuccessOf } from "./Hooks.ts"
+import { engineHooks } from "./Hooks.ts"
+import type { FlowsHooks } from "./index.ts"
+import { PluginError } from "./PluginError.ts"
+import { defaultParallelConcurrency, type HandlerRecord, type Resolved } from "./Resolve.ts"
+
+const empty: ReadonlyArray<HandlerRecord> = Object.freeze([])
+
+// The typed catalog and the runtime catalog can only drift when a host casts
+// around `KeysOfKind`; refuse before any handler runs rather than execute a
+// hook under semantics its declaration never promised.
+const kindMismatch = (resolved: Resolved<unknown>, hook: string, kind: HookKind): PluginError | undefined => {
+  if (!Object.hasOwn(resolved.kinds, hook)) return undefined
+  const declared = resolved.kinds[hook]
+  if (declared === kind) return undefined
+  return new PluginError({
+    code: "hook_kind_mismatch",
+    message: `hook "${hook}" is declared ${JSON.stringify(declared)} in the runtime catalog but was dispatched as ${
+      JSON.stringify(kind)
+    }`,
+    hook
+  })
+}
+
+const runHandler = (
+  record: HandlerRecord,
+  args: ReadonlyArray<unknown>
+): Effect.Effect<unknown, PluginError, any> => {
+  const onCause = (cause: Cause.Cause<unknown>) =>
+    Effect.fail(
+      new PluginError({
+        code: "hook_failed",
+        message: `hook "${record.hook}" failed in plugin "${record.plugin}"`,
+        plugin: record.plugin,
+        hook: record.hook,
+        cause
+      })
+    )
+
+  return Effect.sync(() => record.handler(...args)).pipe(
+    Effect.catchCause(onCause),
+    Effect.flatMap((result) =>
+      Effect.isEffect(result)
+        ? result.pipe(Effect.catchCause(onCause))
+        : Effect.fail(
+          new PluginError({
+            code: "hook_failed",
+            message: `hook "${record.hook}" in plugin "${record.plugin}" returned a non-Effect (${typeof result})`,
+            plugin: record.plugin,
+            hook: record.hook
+          })
+        )
+    )
+  )
+}
+
+/**
+ * The dispatch surface.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Service<H = FlowsHooks> {
+  /** The resolved list this dispatcher walks. */
+  readonly resolved: Resolved<H>
+  /** Frozen, ordered handler records for a hook. */
+  readonly handlers: (hook: string) => ReadonlyArray<HandlerRecord>
+  /** Runs every handler in resolved order, one at a time. */
+  readonly sequential: <K extends KeysOfKind<H, "sequential">>(
+    hook: K,
+    ...args: ArgsOf<H[K]>
+  ) => Effect.Effect<ReadonlyArray<SuccessOf<H[K]>>, PluginError, ContextOf<H[K]>>
+  /**
+   * Runs every handler concurrently, ignoring results. Never fails: handler
+   * failures are returned so the caller can report them at its own boundary.
+   */
+  readonly parallel: <K extends KeysOfKind<H, "parallel">>(
+    hook: K,
+    ...args: ArgsOf<H[K]>
+  ) => Effect.Effect<ReadonlyArray<PluginError>, never, ContextOf<H[K]>>
+  /** Runs handlers in order until one returns `Option.some`. */
+  readonly first: <K extends KeysOfKind<H, "first">>(
+    hook: K,
+    ...args: ArgsOf<H[K]>
+  ) => Effect.Effect<SuccessOf<H[K]>, PluginError, ContextOf<H[K]>>
+  /** Threads a value through every handler, merging each returned patch. */
+  readonly waterfall: <K extends KeysOfKind<H, "waterfall">>(
+    hook: K,
+    initial: ArgsOf<H[K]>[0],
+    merge: (previous: ArgsOf<H[K]>[0], patch: Exclude<SuccessOf<H[K]>, void>) => ArgsOf<H[K]>[0]
+  ) => Effect.Effect<ArgsOf<H[K]>[0], PluginError, ContextOf<H[K]>>
+}
+
+/**
+ * Builds a dispatcher over an already resolved plugin list.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {
+  const handlers = (hook: string): ReadonlyArray<HandlerRecord> => resolved.handlers.get(hook) ?? empty
+
+  const sequential = ((hook: string, ...args: Array<unknown>) =>
+    Effect.gen(function*() {
+      const mismatch = kindMismatch(resolved, hook, "sequential")
+      if (mismatch !== undefined) return yield* Effect.fail(mismatch)
+      const results: Array<unknown> = []
+      for (const record of handlers(hook)) {
+        results.push(yield* runHandler(record, args))
+      }
+      return results
+    })) as Service<H>["sequential"]
+
+  const parallel = ((hook: string, ...args: Array<unknown>) => {
+    const mismatch = kindMismatch(resolved, hook, "parallel")
+    if (mismatch !== undefined) return Effect.succeed([mismatch])
+    return Effect.forEach(
+      handlers(hook),
+      (record) =>
+        runHandler(record, args).pipe(
+          Effect.match({ onFailure: (error) => [error], onSuccess: () => [] as Array<PluginError> })
+        ),
+      { concurrency: resolved.parallelConcurrency }
+    ).pipe(Effect.map((chunks) => chunks.flat()))
+  }) as Service<H>["parallel"]
+
+  const first = ((hook: string, ...args: Array<unknown>) =>
+    Effect.gen(function*() {
+      const mismatch = kindMismatch(resolved, hook, "first")
+      if (mismatch !== undefined) return yield* Effect.fail(mismatch)
+      for (const record of handlers(hook)) {
+        const result = yield* runHandler(record, args)
+        if (!Option.isOption(result)) {
+          return yield* Effect.fail(
+            new PluginError({
+              code: "invalid_hook_result",
+              message: `first hook "${record.hook}" in plugin "${record.plugin}" did not return an Option`,
+              plugin: record.plugin,
+              hook: record.hook
+            })
+          )
+        }
+        if (Option.isSome(result)) return result
+      }
+      return Option.none()
+    })) as unknown as Service<H>["first"]
+
+  const waterfall =
+    ((hook: string, initial: unknown, merge: (previous: unknown, patch: unknown) => unknown) =>
+      Effect.gen(function*() {
+        const mismatch = kindMismatch(resolved, hook, "waterfall")
+        if (mismatch !== undefined) return yield* Effect.fail(mismatch)
+        let value = initial
+        for (const record of handlers(hook)) {
+          const patch = yield* runHandler(record, [value])
+          if (patch !== undefined) {
+            value = yield* Effect.try({
+              try: () => merge(value, patch),
+              catch: (cause) =>
+                cause instanceof PluginError
+                  ? new PluginError({
+                    code: cause.code,
+                    message: cause.message,
+                    plugin: record.plugin,
+                    hook: record.hook,
+                    path: cause.path
+                  })
+                  : new PluginError({
+                    code: "config_invalid",
+                    message: `waterfall hook "${record.hook}" in plugin "${record.plugin}" returned an invalid patch`,
+                    plugin: record.plugin,
+                    hook: record.hook
+                  })
+            })
+          }
+        }
+        return value
+      })) as Service<H>["waterfall"]
+
+  return Object.freeze({ resolved, handlers, sequential, parallel, first, waterfall })
+}
+
+/**
+ * A dispatcher with no plugins at all.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const makeNoop = <H = FlowsHooks>(): Service<H> =>
+  make<H>(Object.freeze({
+    plugins: Object.freeze([]),
+    handlers: ImmutableMap.make<string, ReadonlyArray<HandlerRecord>>(),
+    kinds: engineHooks,
+    parallelConcurrency: defaultParallelConcurrency
+  }))
+
+/**
+ * The shared dispatcher, as a service tag.
+ *
+ * This tag holds one dispatcher over the process-wide augmented `FlowsHooks`.
+ * `declare module "@smthrs/plugin"` augmentation is the supported extension
+ * mechanism for values placed in the tag. A host typed against a separate hook
+ * interface holds its `Service<H>` directly, as `@smthrs/agent` does, and does
+ * not use this tag or its layers.
+ *
+ * @category context
+ * @since 1.0.0-rc.0
+ */
+export class Plugins extends Context.Service<Plugins, Service>()("flows/plugin/Plugins") {}
+
+/**
+ * Layer providing a dispatcher over an already resolved plugin list.
+ *
+ * This layer targets the shared augmented `FlowsHooks` catalog only. A host
+ * with a separate hook interface holds its `Service<H>` directly.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (resolved: Resolved): Layer.Layer<Plugins> => Layer.succeed(Plugins)(make(resolved))
+
+/**
+ * Layer providing a dispatcher with no plugins.
+ *
+ * This layer targets the shared augmented `FlowsHooks` catalog only. A host
+ * with a separate hook interface holds its `Service<H>` directly.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerNoop: Layer.Layer<Plugins> = Layer.succeed(Plugins)(makeNoop())