dimcode-darwin-x64 0.1.0-alpha.15 → 0.1.0-alpha.16

package/plugins/goal/node_modules/@arcships/rutis/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@arcships/rutis",
+  "version": "0.19.3",
+  "description": "Write rutis plugins in JavaScript or TypeScript: definePlugin, types and a test kit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcships/rutis.git",
+    "directory": "node/rutis"
+  },
+  "homepage": "https://github.com/arcships/rutis/tree/main/docs/guide#readme",
+  "keywords": ["rutis", "plugin", "rutis-plugin"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./advanced": {
+      "types": "./src/advanced.d.ts",
+      "default": "./src/advanced.mjs"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@arcships/rutis-bun": "file:../../bun/rutis-bun",
+    "@arcships/rutis-runtime": "file:../rutis-runtime"
+  }
+}

package/plugins/goal/node_modules/@arcships/rutis/src/advanced.d.ts

@@ -0,0 +1,90 @@
+// What a plugin author rarely writes (#692): the plugin API version, the
+// marks, the value constructors and the types of the events. `definePlugin`
+// and `Context` are in `@arcships/rutis`.
+import type { Plugin } from './index.js'
+
+export type MethodKind = 'sync' | 'async'
+
+/** Where a listener is, as the logical bus describes it (#464): what a filter sees. */
+export interface ListenerDescriptor {
+  /** The event name (a prefix, for a Rust pattern listener). */
+  readonly name: string
+  /** A Rust pattern listener's prefix entry. */
+  readonly prefix: boolean
+  /** The plugin that registered it: its declared name (`PluginSpec.name`, a Cordis plugin's name), else its row's id. */
+  readonly plugin: string
+  /** Its row's id, the name the configuration gives the row (the copies a group's instances make share it); `null` for a plugin a mount loaded. */
+  readonly row: string | null
+  /** The runtime it runs in; `null` for the host's own Rust plugins. */
+  readonly runtime: string | null
+  /** The node it came from over a node link; `null` otherwise. */
+  readonly node: string | null
+  /** Its scope chain, outermost first; `[]` at the root. */
+  readonly scope: ReadonlyArray<{ readonly id: string, readonly group: string }>
+  /** A `global` listener is never filtered. */
+  readonly global: boolean
+}
+
+export interface ListenerOptions {
+  /** Run before every listener of the name registered so far. */
+  prepend?: boolean
+  /** Not subject to emitters' filters. */
+  global?: boolean
+}
+
+/** A listener: the event's arguments, then, in a `waterfall`, `next` (the rest of the chain) last. */
+export type Listener = (...args: any[]) => any
+
+/** The five ways to emit. Each reaches every listener of the name on the root's flat bus, wherever the listener runs, by the same rules as if all were in this process. Emitting `rutis/*` throws `ReservedEvent`; `internal/*` is refused. */
+export interface Emitter {
+  /** Start every listener in registration order; returns at once. A listener's failure is reported where it ran and reaches neither the emitter nor the other listeners. */
+  emit(name: string, ...args: any[]): void
+  /** Start every listener and wait for all. Failures reject with an `AggregateError` in registration order, even a single one. */
+  parallel(name: string, ...args: any[]): Promise<void>
+  /** Run the listeners one by one; resolves to the first result (not `undefined`, `null` or `false`), or `undefined`. An error stops and rejects. */
+  serial<T = any>(name: string, ...args: any[]): Promise<T | undefined>
+  /** Each listener gets `next` (no arguments) last and returns the result; not calling `next` vetoes the rest. Every argument is the event's; the end of the chain gives `undefined` (see `with` for a terminal). Returns the outermost listener's value as is (a Promise whenever a listener runs elsewhere: await it). Calling `next` twice, or after the end, gives a Promise rejected with `WaterfallNext`. */
+  waterfall: Waterfall
+  /** Synchronously, the first result as `serial`. An `async` listener, or one returning a Promise, fails it with `AsyncListener`. */
+  bail<T = any>(name: string, ...args: any[]): T | undefined
+}
+
+export interface Waterfall {
+  <T = any>(name: string, ...args: any[]): T | Promise<T>
+  /** The same waterfall with a terminal: called with the event's arguments at the end of the chain, its value what the last `next` gives. */
+  with<T = any>(terminal: (...args: any[]) => any): <U = T>(name: string, ...args: any[]) => U | Promise<U>
+}
+
+/** The plugin API this SDK writes plugins against. */
+export declare const PLUGIN_API: number
+/** The mark on what `definePlugin` makes (`Symbol.for('rutis.leaf-plugin')`), across copies of this package. */
+export declare const PLUGIN: unique symbol
+/** Whether `value` is a plugin `definePlugin` made. */
+export declare function isPlugin(value: unknown): value is Plugin
+
+/** The mark on a value made by `datetime`, `date`, `time`, `decimal` or `uuid` (`Symbol.for('rutis.value')`). */
+export declare const VALUE: unique symbol
+
+/**
+ * A local date and time, date, time of day, decimal or UUID to send as that
+ * value (#308): JavaScript has no type for them. Received, they are strings
+ * (`value`'s text); a plain string is sent as a string.
+ */
+export interface TaggedValue<Tag extends 'datetime' | 'date' | 'time' | 'decimal' | 'uuid'> {
+  readonly [VALUE]: Tag
+  /** The value's text, as it crosses. */
+  readonly value: string
+  toString(): string
+  toJSON(): string
+}
+
+/** A local date and time without a time zone: `'2026-10-15T14:30'`, `'2026-10-15T14:30:05.25'` (years 0001–9999, 0–9 fraction digits). Received as its text. */
+export declare function datetime(text: string): TaggedValue<'datetime'>
+/** A calendar date: `'2026-10-15'` (years 0001–9999). Received as its text. */
+export declare function date(text: string): TaggedValue<'date'>
+/** A time of day without a time zone: `'14:30'`, `'14:30:05.25'` (24-hour). Received as its text. */
+export declare function time(text: string): TaggedValue<'time'>
+/** A decimal number, trailing zeros kept: `'1.10'`, `'-12.3400'` (no exponent, at most 4300 digits). Received as its text. */
+export declare function decimal(text: string | bigint): TaggedValue<'decimal'>
+/** A UUID, `8-4-4-4-12` hex in either case; sent and received in lowercase. */
+export declare function uuid(text: string): TaggedValue<'uuid'>

package/plugins/goal/node_modules/@arcships/rutis/src/advanced.mjs

@@ -0,0 +1,32 @@
+// The names a plugin author rarely writes (#692): the plugin API version,
+// the marks the runtimes recognise plugins and values by, and the value
+// constructors. `ctx` and `definePlugin` are in `@arcships/rutis`.
+//
+//   import { datetime, decimal } from '@arcships/rutis/advanced'
+//   return { at: datetime('2026-10-15T14:30'), price: decimal('1.10') }
+
+// The plugin API this SDK writes plugins against. A runtime refuses a plugin
+// that needs a newer one, naming both.
+// 2: ctx.on and ctx.emit (leaf events). A runtime that supports only 1
+// refuses such a plugin at load instead of failing in apply.
+// 3: the unified events of rutis 0.13 (#464): ctx.parallel, serial,
+// waterfall, bail and filter, ctx.signal, and `prepend` / `global` on
+// ctx.on. A runtime of 0.12 or older refuses such a plugin at load.
+export const PLUGIN_API = 3
+
+// Marks what definePlugin returns, across copies of this package.
+export const PLUGIN = Symbol.for('rutis.leaf-plugin')
+
+// Whether `value` is a plugin definePlugin made.
+export const isPlugin = value => value?.[PLUGIN] === true
+
+// Values JavaScript has no type for, to send as what they are (#308): a
+// local date and time, a date, a time of day, a decimal, a UUID. Received,
+// they are strings; a plain string is sent as a string.
+//
+// A Date, Uint8Array, Map, Set and bigint need no constructor: they cross
+// as an instant, bytes, a map, a set and a big integer.
+export { datetime, date, time, decimal, uuid } from './values.mjs'
+// The mark on what they make, across copies of this package and in the
+// runtimes: `Symbol.for('rutis.value')`.
+export { MARK as VALUE } from './values.mjs'

package/plugins/goal/node_modules/@arcships/rutis/src/index.d.ts

@@ -0,0 +1,43 @@
+import type * as advanced from './advanced.js'
+
+/**
+ * An error a listener threw arrives, through the host, as an `Error` of the
+ * same built-in class (`TypeError`, `RangeError`, …, `AggregateError`) or a
+ * plain `Error` with the thrower's `name`, `message` and `code`, never as
+ * the thrower's own class: match errors by `name`.
+ */
+export interface Context extends advanced.Emitter {
+  /** The service `name`, which the plugin declares in `inject`: the object itself when a plugin in the same process provides it, else a proxy whose methods are sync or async as declared. */
+  use<T = any>(name: string): T
+  /** Provide `value` as the service `name` until the plugin unloads, or until the returned function is called. It reaches rutis by itself: its methods are the object's functions (own and inherited, not `constructor`), `async` unless `provides` marks them `sync`. */
+  provide(name: string, value: unknown): () => unknown
+  /** Run `cleanup` when the plugin unloads. */
+  effect(cleanup: () => unknown): void
+  /** Aborted when the plugin unloads; its running listeners are then waited for (up to the host's shutdown deadline) before the cleanups run. */
+  readonly signal: AbortSignal
+  /** Listen to `name` on the host's logical bus: every event of that name, from any process or language (a scope is a descriptor). Registered with the host by itself; unregistered when the plugin unloads or the returned function is called. `rutis/*` (the host's framework events) can be listened to; `internal/*` cannot. */
+  on(name: string, listener: advanced.Listener, options?: advanced.ListenerOptions): () => void
+  /** The five ways to emit, delivered only to the listeners `keep` returns true for (`global` listeners are always delivered). `keep` runs in this process, once per candidate, before any listener runs. */
+  filter(keep: (listener: advanced.ListenerDescriptor) => unknown): advanced.Emitter
+}
+
+export interface PluginSpec<C = any> {
+  /** Its name: what listener descriptors (`ListenerDescriptor.plugin`) call it. Without one, they call it by its row's id. */
+  name?: string
+  /** Services the plugin uses: rutis starts it once they are all available, and stops it when one goes. */
+  inject?: string[]
+  /** Optional: services it provides, with the kind of methods to call `sync` (the others are `async`). Without it, what `ctx.provide` provides still reaches rutis; with it, `rutis-host check` knows before the plugin runs. */
+  provides?: Record<string, Record<string, advanced.MethodKind>>
+  /** The JSON Schema of its config. */
+  config?: object
+  apply(ctx: Context, config: C): void | (() => unknown) | Promise<void | (() => unknown)>
+}
+
+export interface Plugin<C = any> extends Readonly<Required<Pick<PluginSpec<C>, 'inject' | 'provides'>>>, Readonly<Omit<PluginSpec<C>, 'inject' | 'provides'>> {
+  /** The plugin API it was written against. */
+  readonly api: number
+  /** Always `true`: what it provides beyond `provides` reaches rutis by itself, known once it runs. */
+  readonly announces: boolean
+}
+
+export declare function definePlugin<C = any>(spec: PluginSpec<C>): Plugin<C>

package/plugins/goal/node_modules/@arcships/rutis/src/index.mjs

@@ -0,0 +1,71 @@
+// Write a rutis plugin in JavaScript or TypeScript. A plugin declares the
+// services it uses (`inject`), and `apply(ctx, config)` uses and provides
+// them through `ctx`; rutis decides when it starts, stops and restarts. The
+// runtime that runs it is installed by the host (`@arcships/rutis-runtime`
+// in Node, `@arcships/rutis-bun` in Bun), not by the plugin.
+//
+//   export default definePlugin({
+//     inject: ['llm'],
+//     config: { type: 'object', properties: { city: { type: 'string' } } },
+//     apply(ctx, config) {
+//       ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+//       ctx.on('weather/ask', city => city === config.city ? 'sunny' : undefined)
+//       return () => {}
+//     },
+//   })
+//
+// Events cross every process and language on the host (#464): `ctx.on`
+// listens to every event of the name on the flat bus, and
+// `ctx.emit` / `parallel` / `serial` / `waterfall` / `bail` reach every
+// listener, wherever it runs, as if all were in this process.
+//
+// What `ctx.provide` provides reaches rutis by itself: its methods are the
+// object's functions (its own and its prototype chain's, not `constructor`),
+// called as `async`. `provides` is optional: `{ weather: { unit: 'sync' } }`
+// marks methods `sync` and tells `rutis-host check` what the plugin
+// provides before it runs.
+
+import { PLUGIN, PLUGIN_API } from './advanced.mjs'
+
+// `config` is a JSON Schema object: the host fills its defaults and checks
+// the config with it before `apply`. A Standard Schema object (schemastery,
+// zod, …) was never applied: refused (config schema design §2.3).
+function checkSchema(config) {
+  const standard = config?.['~standard']
+  if (standard !== undefined) {
+    throw new TypeError(`config of definePlugin should be a JSON Schema object, got ${standard?.vendor === 'schemastery' ? 'a schemastery Schema' : 'a Standard Schema'}`)
+  }
+}
+
+// The module that defined a plugin, as a file URL: the test tool
+// (`@arcships/rutis/testing`) has a real runtime load the plugin from it.
+const FILE = Symbol.for('rutis.plugin-file')
+function definedIn() {
+  const prepare = Error.prepareStackTrace
+  try {
+    Error.prepareStackTrace = (_, sites) => sites
+    const holder = {}
+    Error.captureStackTrace(holder, definePlugin)
+    const file = holder.stack?.[0]?.getFileName?.()
+    return typeof file === 'string' ? file : undefined
+  } catch {
+    return undefined
+  } finally {
+    Error.prepareStackTrace = prepare
+  }
+}
+
+export function definePlugin(spec) {
+  if (typeof spec?.apply !== 'function') throw new TypeError('a plugin needs apply(ctx, config)')
+  checkSchema(spec.config)
+  const inject = spec.inject ?? []
+  if (!Array.isArray(inject) || inject.some(name => typeof name !== 'string')) throw new TypeError('inject must be a list of service names')
+  for (const [name, methods] of Object.entries(spec.provides ?? {})) {
+    for (const [method, kind] of Object.entries(methods ?? {})) {
+      if (kind !== 'sync' && kind !== 'async') throw new TypeError(`${name}.${method}: kind must be 'sync' or 'async'`)
+    }
+  }
+  // `announces`: what it provides beyond `provides` (all of it, without
+  // one) reaches rutis by itself, and is known once it runs.
+  return Object.freeze({ ...spec, inject, provides: spec.provides ?? {}, announces: true, api: PLUGIN_API, [PLUGIN]: true, [FILE]: definedIn() })
+}

package/plugins/goal/node_modules/@arcships/rutis/src/testing.d.ts

@@ -0,0 +1,77 @@
+import type { Plugin } from './index.js'
+import type { Emitter, Listener, ListenerDescriptor, ListenerOptions } from './advanced.js'
+
+/** What the test tool refuses: a load that fails (the row's line, as the host prints it), a plugin it cannot load. */
+export declare class PluginTestError extends Error {}
+
+/** The five ways to emit, with `filter`. */
+export interface TestEmitter extends Emitter {
+  filter(keep: (listener: ListenerDescriptor) => unknown): Emitter
+}
+
+/** A failure the host reported of a row: a listener failing in an `emit`, or a filter (protocol §5.6). */
+export interface Reported {
+  /** The line the host prints. */
+  line: string
+}
+
+/** One loaded plugin: a row of the host. Its emitting methods emit as the test's plugin next to it. */
+export interface Loaded extends TestEmitter {
+  /** The row's id on the host: its module's file name, `-2`, `-3`… when taken. */
+  readonly row: string
+  /** The host it is loaded on. */
+  readonly host: Host
+  /** The service `name` the plugin provides, as rutis sees it: its declared methods, or, undeclared, the object's methods, all async. */
+  service<T = any>(name: string): T
+  /** The methods rutis sees on the service `name`, with their kinds. */
+  methods(name: string): Record<string, 'sync' | 'async'>
+  /** The names of the services the plugin provides now. */
+  provided(): string[]
+  /** What the host reported of this row. */
+  reported(): Promise<Reported[]>
+  /**
+   * Listen to the event `name` as a plugin next to it does: the plugin's emissions of `name` reach `listener`, and so do the test's own.
+   * Its arguments and what it returns cross between processes. Returns the function that stops it; without it, it stops when the row unloads.
+   */
+  on(name: string, listener: Listener, options?: ListenerOptions): () => void
+  /** Change the row's config, as a host does. */
+  update(config: unknown): Promise<void>
+  /** Unload the row as the host does (its listeners and services withdrawn, its `ctx.signal` aborted, its running listeners waited for, its cleanups run, latest first), then the test's services and listeners of it. */
+  unload(): Promise<void>
+}
+
+export interface LoadOptions {
+  config?: unknown
+  /** The test's services the plugin injects, by name. */
+  services?: Record<string, unknown>
+}
+
+export interface HostOptions {
+  /** The test's services, for every row that injects them. */
+  services?: Record<string, unknown>
+}
+
+export interface RowOptions {
+  config?: unknown
+  /** The test's services for this row only. */
+  services?: Record<string, unknown>
+  /** The row's id (default: its module's file name, with `-2`, `-3`, … when taken). */
+  id?: string
+  /** As a row's `isolate`: the services it keeps to a scope of its own (`{ forecast: true }`), or a label. */
+  isolate?: Record<string, true | string>
+}
+
+/** Plugins on the host, sharing its bus; its emitting methods emit as the test's plugin. */
+export interface Host extends TestEmitter {
+  load(plugin: Plugin | { default: Plugin }, options?: RowOptions): Promise<Loaded>
+  /** What the host reported of the rows here. */
+  reported(): Promise<Reported[]>
+  /** Unload every row, latest first, then withdraw the test's services. */
+  unload(): Promise<void>
+}
+
+/** Plugins on the real host of this test process (`rutis-host test`, in the real runtime), which must be their modules' default exports. */
+export declare function host(options?: HostOptions): Host
+
+/** Load `plugin` (or a module whose default export it is) on a `host()` of its own. */
+export declare function load(plugin: Plugin | { default: Plugin }, options?: LoadOptions): Promise<Loaded>