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

package/package.json

@@ -1,6 +1,182 @@
 {
   "name": "@smthrs/plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.3",
+  "license": "MIT",
+  "smthrs": {
+    "group": "agent"
+  },
+  "description": "Vite-style typed plugin kernel for flows: hooks, resolution, and config execution",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/agent/plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "plugin",
+    "hooks"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "plugin",
+    "hooks"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./Config": {
+      "import": {
+        "types": "./dist/esm/Config.d.ts",
+        "default": "./dist/esm/Config.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Config.d.ts",
+        "default": "./dist/cjs/Config.js"
+      }
+    },
+    "./Hooks": {
+      "import": {
+        "types": "./dist/esm/Hooks.d.ts",
+        "default": "./dist/esm/Hooks.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Hooks.d.ts",
+        "default": "./dist/cjs/Hooks.js"
+      }
+    },
+    "./Kernel": {
+      "import": {
+        "types": "./dist/esm/Kernel.d.ts",
+        "default": "./dist/esm/Kernel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Kernel.d.ts",
+        "default": "./dist/cjs/Kernel.js"
+      }
+    },
+    "./Plugin": {
+      "import": {
+        "types": "./dist/esm/Plugin.d.ts",
+        "default": "./dist/esm/Plugin.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Plugin.d.ts",
+        "default": "./dist/cjs/Plugin.js"
+      }
+    },
+    "./PluginError": {
+      "import": {
+        "types": "./dist/esm/PluginError.d.ts",
+        "default": "./dist/esm/PluginError.js"
+      },
+      "require": {
+        "types": "./dist/cjs/PluginError.d.ts",
+        "default": "./dist/cjs/PluginError.js"
+      }
+    },
+    "./Plugins": {
+      "import": {
+        "types": "./dist/esm/Plugins.d.ts",
+        "default": "./dist/esm/Plugins.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Plugins.d.ts",
+        "default": "./dist/cjs/Plugins.js"
+      }
+    },
+    "./Resolve": {
+      "import": {
+        "types": "./dist/esm/Resolve.d.ts",
+        "default": "./dist/esm/Resolve.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Resolve.d.ts",
+        "default": "./dist/cjs/Resolve.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/canonical": "1.0.0-rc.3",
+    "@smthrs/flow": "1.0.0-rc.3"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }

package/src/Config.ts

@@ -0,0 +1,207 @@
+/**
+ * Bounded JSON configuration consumed and produced by the plugin kernel.
+ *
+ * Configuration is an extension namespace, not an engine-policy surface.
+ * Durable retry, concurrency, and storage policy stay on their owning Effect
+ * services and constructor options. Every accepted value is copied before any
+ * plugin observes it, then frozen recursively.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as SchemaGetter from "effect/SchemaGetter"
+import * as SchemaIssue from "effect/SchemaIssue"
+import * as Boundary from "./internal/Boundary.ts"
+import { PluginError } from "./PluginError.ts"
+
+/**
+ * Maximum encoded bytes accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigBytes = Boundary.defaultLimits.maxBytes
+
+/**
+ * Maximum nesting accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigDepth = Boundary.defaultLimits.maxDepth
+
+/**
+ * Maximum aggregate members accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigMembers = Boundary.defaultLimits.maxMembers
+
+/**
+ * Maximum aggregate values accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigNodes = Boundary.defaultLimits.maxNodes
+
+/**
+ * One value accepted in a plugin-owned configuration namespace.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const ConfigValue = Schema.Json
+
+/**
+ * One value accepted in a plugin-owned configuration namespace.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ConfigValue = typeof ConfigValue.Type
+
+const admittedConfigs = new WeakSet<object>()
+
+const configurationSchema = Schema.Unknown.pipe(
+  Schema.decodeTo(
+    Schema.declare<Readonly<Record<string, ConfigValue>>>((value): value is Readonly<Record<string, ConfigValue>> =>
+      typeof value === "object" && value !== null && admittedConfigs.has(value)
+    ),
+    {
+      decode: SchemaGetter.transformEffect((value) =>
+        Effect.try({
+          try: () => snapshotRecord(value),
+          catch: (cause) => {
+            const error = cause as PluginError
+            return new SchemaIssue.InvalidValue({ message: `${error.path}: ${error.message}` })
+          }
+        })
+      ),
+      encode: SchemaGetter.transform((value) => value)
+    }
+  )
+)
+
+/**
+ * Admits pre-resolution configuration as a detached, recursively frozen snapshot.
+ *
+ * Keys name plugin-owned namespaces. `engine`, `retry`, `store`, and
+ * `plugins` are refused because accepting those names would imply policy the
+ * plugin kernel does not own or apply.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const FlowsConfig = configurationSchema
+
+/**
+ * The decoded form of {@link FlowsConfig}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type FlowsConfig = typeof FlowsConfig.Type
+
+/**
+ * Admits the detached, recursively frozen configuration handed to plugins.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const ResolvedConfig = configurationSchema
+
+/**
+ * The decoded form of {@link ResolvedConfig}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ResolvedConfig = typeof ResolvedConfig.Type
+
+const reservedRootKeys = new Set(["engine", "retry", "store", "plugins"])
+
+const invalid = (path: string, complaint: string): PluginError =>
+  new PluginError({
+    code: "config_invalid",
+    message: `plugin configuration ${complaint}`,
+    path
+  })
+
+const snapshotRecord = (input: unknown, reuse = true): Readonly<Record<string, ConfigValue>> => {
+  if (reuse && typeof input === "object" && input !== null && admittedConfigs.has(input)) return input as ResolvedConfig
+  const admitted = Boundary.record(input)
+  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint)
+  const record = admitted.value as Readonly<Record<string, ConfigValue>>
+  for (const key of Object.keys(record)) {
+    if (reservedRootKeys.has(key)) {
+      throw invalid(`$.${key}`, "uses a runtime-policy key that the plugin kernel does not own")
+    }
+  }
+  admittedConfigs.add(record)
+  return record
+}
+
+/**
+ * Empty defaults. Engine policy is deliberately not defaulted here.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const defaults: ResolvedConfig = snapshotRecord({})
+
+/**
+ * Copies and deep-merges a configuration patch over a base configuration.
+ *
+ * Records merge key-by-key and every other JSON value replaces wholesale.
+ * Raw operands are admitted; known snapshots retain unchanged subtrees.
+ * Cached subtree totals enforce merged output bounds. Unsafe property names,
+ * accessors, cycles, exotic prototypes, and aggregate values outside the
+ * resource limits fail with `config_invalid`.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export const merge = (base: FlowsConfig, patch: unknown): FlowsConfig => {
+  const safeBase = snapshotRecord(base)
+  if (patch === undefined) return safeBase
+  // Even a known patch is copied so its tree cannot alias the retained base.
+  const safePatch = snapshotRecord(patch, false)
+  const merged = Boundary.mergeRecords(safeBase, safePatch)
+  if (!merged.ok) throw invalid(merged.path, merged.complaint)
+  const record = merged.value as ResolvedConfig
+  admittedConfigs.add(record)
+  return record
+}
+
+/**
+ * Copies and freezes one JSON value without retaining caller-owned objects.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export const deepFreeze = <A extends ConfigValue>(value: A): A => {
+  const admitted = Boundary.admit(value)
+  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint)
+  return admitted.value as A
+}
+
+/**
+ * Admits a raw pre-resolution configuration as an immutable snapshot.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const snapshot = (config: unknown): Effect.Effect<FlowsConfig, PluginError> =>
+  Effect.try({ try: () => snapshotRecord(config), catch: (cause) => cause as PluginError })
+
+/**
+ * Decodes the post-waterfall configuration into its final immutable form.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const resolve = (config: unknown): Effect.Effect<ResolvedConfig, PluginError> => snapshot(config)

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