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

package/src/Hooks.ts

@@ -0,0 +1,212 @@
+/**
+ * The typed hook surface: hook kinds, the hook entry shape, and the shared
+ * kernel's base hook catalog.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. The shared catalog is limited to
+ * `config` and `configResolved`;
+ * `@smthrs/agent` adds only `cellRegistry`, `cellFlows`, and
+ * `cellModelRequest`. Durable-core lifecycle policy is not a hook catalog.
+ *
+ * `FlowsHooks` is **open for augmentation, closed for dispatch**: a host
+ * declares its hooks with `declare module "@smthrs/plugin"`, supplies the
+ * matching runtime catalog, and dispatches only that bounded set.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import type * as Effect from "effect/Effect"
+
+/**
+ * Dispatch semantics of a hook, fixed by the core.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type HookKind = "sequential" | "parallel" | "first" | "waterfall"
+
+declare const HookTypeId: unique symbol
+
+/**
+ * Phantom carrier that records a hook's kind and handler type in the type
+ * system without adding anything at runtime.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HookMeta<K extends HookKind, F> {
+  readonly [HookTypeId]?: { readonly kind: K; readonly handler: F }
+}
+
+/**
+ * The object form of a hook entry: Vite's per-hook ordering object, verbatim.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HookObject<F> {
+  readonly order?: "pre" | "post" | undefined
+  readonly handler: F
+}
+
+/**
+ * A hook entry is either the bare handler or `{ order?, handler }`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type HookEntry<K extends HookKind, F> = (F | HookObject<F>) & HookMeta<K, F>
+
+/**
+ * Every handler runs, in resolved order, one at a time.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type SequentialHook<F> = HookEntry<"sequential", F>
+
+/**
+ * Every handler runs concurrently; results are ignored and failures are
+ * returned to the caller rather than failing it.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ParallelHook<F> = HookEntry<"parallel", F>
+
+/**
+ * Handlers run in order until one returns `Option.some`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type FirstHook<F> = HookEntry<"first", F>
+
+/**
+ * Each handler receives the previous handler's output.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type WaterfallHook<F> = HookEntry<"waterfall", F>
+
+/**
+ * Extracts the declared kind of a hook entry type.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type KindOf<T> = T extends HookMeta<infer K, any> ? K : never
+
+/**
+ * The runtime catalog a host supplies for a hook interface: each hook name
+ * mapped to its kind. A name declared in `H` must carry the kind its type
+ * declares. Names outside `H` are admitted with any kind, because the type
+ * system cannot enumerate an augmentable interface; resolution checks them
+ * at runtime and dispatch refuses a kind that disagrees with the catalog.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type HookCatalog<H> =
+  & { readonly [K in keyof H & string]?: KindOf<H[K]> }
+  & { readonly [name: string]: HookKind | undefined }
+
+/**
+ * Extracts the handler type of a hook entry type.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type HandlerOf<T> = T extends HookMeta<any, infer F> ? F : never
+
+/**
+ * Selects the hook names of a given kind from a hook interface.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type KeysOfKind<H, K extends HookKind> =
+  & {
+    [P in keyof H]: KindOf<H[P]> extends K ? P : never
+  }[keyof H]
+  & string
+
+/**
+ * Extracts the positional argument tuple accepted by a hook entry.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ArgsOf<T> = HandlerOf<T> extends (...args: infer A) => any ? A : never
+
+/**
+ * Extracts the Effect returned by a hook entry.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ReturnOf<T> = HandlerOf<T> extends (...args: any) => infer R ? R : never
+
+/**
+ * Extracts the success value returned by a hook entry's Effect.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type SuccessOf<T> = ReturnOf<T> extends Effect.Effect<infer A, any, any> ? A : never
+
+/**
+ * Extracts the context required by a hook entry's Effect.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ContextOf<T> = ReturnOf<T> extends Effect.Effect<any, any, infer R> ? R : never
+
+/**
+ * Runtime catalog of the shared kernel's hook names and kinds.
+ *
+ * The type system cannot enumerate an augmentable interface, so this constant
+ * is what the `unknown_hook` guard checks against. A host passes its own
+ * superset to {@link resolve}. The cell harness adds only the hooks it
+ * dispatches; lifecycle and engine-policy hooks do not belong here.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+const sharedHooks: { config: "waterfall"; configResolved: "parallel" } = Object.create(null)
+Object.defineProperties(sharedHooks, {
+  config: { value: "waterfall", enumerable: true },
+  configResolved: { value: "parallel", enumerable: true }
+})
+/**
+ * Frozen runtime catalog for the shared configuration hooks.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const engineHooks: Readonly<{
+  readonly config: "waterfall"
+  readonly configResolved: "parallel"
+}> = Object.freeze(sharedHooks)
+
+/**
+ * Normalizes a hook entry to its handler.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export const handlerOf = (entry: unknown): (...args: Array<any>) => unknown =>
+  typeof entry === "function"
+    ? entry as (...args: Array<any>) => unknown
+    : (entry as HookObject<(...args: Array<any>) => unknown>).handler
+
+/**
+ * Reads the per-hook `order` of a hook entry.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export const orderOf = (entry: unknown): "pre" | "post" | undefined =>
+  typeof entry === "function" ? undefined : (entry as HookObject<unknown>).order

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)
+}) {}