@shardworks/fabricator-apparatus 0.1.109

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/fabricator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The Fabricator — guild engine design registry apparatus.
+ *
+ * Scans installed engine designs from kit contributions and apparatus supportKits,
+ * and serves them to the Walker on demand.
+ *
+ * The Fabricator does not execute engines. It is a pure query service:
+ * designs in, designs out.
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+/** Minimal execution context passed to an engine's run() method. */
+export interface EngineRunContext {
+    /** Simple string identity for this engine instance (e.g. 'draft', 'implement'). */
+    engineId: string;
+    /** All upstream yields, keyed by engine id. Escape hatch for engines that need to inspect the full upstream chain. */
+    upstream: Record<string, unknown>;
+}
+/**
+ * The result of an engine run.
+ *
+ * 'completed' — synchronous work done inline, yields are available immediately.
+ * 'launched'  — async work launched in a session; the Walker polls for completion.
+ */
+export type EngineRunResult = {
+    status: 'completed';
+    yields: unknown;
+} | {
+    status: 'launched';
+    sessionId: string;
+};
+/**
+ * An engine design — the unit of work the Fabricator catalogues and the
+ * Walker executes. Kit authors import this type from @shardworks/fabricator-apparatus.
+ */
+export interface EngineDesign {
+    /** Unique identifier for this engine design (e.g. 'draft', 'implement', 'review'). */
+    id: string;
+    /**
+     * Execute this engine.
+     *
+     * @param givens   — the engine's declared inputs, assembled by the Walker.
+     * @param context  — minimal execution context: engine id and upstream yields.
+     */
+    run(givens: Record<string, unknown>, context: EngineRunContext): Promise<EngineRunResult>;
+}
+/** The Fabricator's public API, exposed via `provides`. */
+export interface FabricatorApi {
+    /**
+     * Look up an engine design by ID.
+     * Returns the design if registered, undefined otherwise.
+     */
+    getEngineDesign(id: string): EngineDesign | undefined;
+}
+/**
+ * Create the Fabricator apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `consumes: ['engines']` — scans kit/supportKit contributions
+ * - `provides: FabricatorApi` — the engine design registry API
+ */
+export declare function createFabricator(): Plugin;
+//# sourceMappingURL=fabricator.d.ts.map

package/dist/fabricator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fabricator.d.ts","sourceRoot":"","sources":["../src/fabricator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAIV,MAAM,EACP,MAAM,wBAAwB,CAAC;AAShC,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,sHAAsH;IACtH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC3F;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CACvD;AAmDD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAoCzC"}

package/dist/fabricator.js

@@ -0,0 +1,90 @@
+/**
+ * The Fabricator — guild engine design registry apparatus.
+ *
+ * Scans installed engine designs from kit contributions and apparatus supportKits,
+ * and serves them to the Walker on demand.
+ *
+ * The Fabricator does not execute engines. It is a pure query service:
+ * designs in, designs out.
+ */
+import { guild, isLoadedKit, isLoadedApparatus, } from '@shardworks/nexus-core';
+// ── Type guard ────────────────────────────────────────────────────────
+/** Narrow an unknown value to EngineDesign. */
+function isEngineDesign(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string' &&
+        typeof value.run === 'function');
+}
+// ── Implementation ────────────────────────────────────────────────────
+/** The engine design registry — populated at startup, queried at runtime. */
+class EngineRegistry {
+    designs = new Map();
+    /** Register all engine designs from a loaded plugin. */
+    register(plugin) {
+        if (isLoadedKit(plugin)) {
+            this.registerFromKit(plugin.kit);
+        }
+        else if (isLoadedApparatus(plugin)) {
+            if (plugin.apparatus.supportKit) {
+                this.registerFromKit(plugin.apparatus.supportKit);
+            }
+        }
+    }
+    /** Extract and register engine designs from a kit (or supportKit) contribution. */
+    registerFromKit(kit) {
+        const rawEngines = kit.engines;
+        if (typeof rawEngines !== 'object' || rawEngines === null)
+            return;
+        for (const value of Object.values(rawEngines)) {
+            if (isEngineDesign(value)) {
+                this.designs.set(value.id, value);
+            }
+        }
+    }
+    /** Look up an engine design by ID. */
+    get(id) {
+        return this.designs.get(id);
+    }
+}
+// ── Apparatus factory ─────────────────────────────────────────────────
+/**
+ * Create the Fabricator apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `consumes: ['engines']` — scans kit/supportKit contributions
+ * - `provides: FabricatorApi` — the engine design registry API
+ */
+export function createFabricator() {
+    const registry = new EngineRegistry();
+    const api = {
+        getEngineDesign(id) {
+            return registry.get(id);
+        },
+    };
+    return {
+        apparatus: {
+            requires: [],
+            consumes: ['engines'],
+            provides: api,
+            start(ctx) {
+                const g = guild();
+                // Scan all already-loaded kits. These fired plugin:initialized before
+                // any apparatus started, so we can't catch them via events.
+                for (const kit of g.kits()) {
+                    registry.register(kit);
+                }
+                // Subscribe to plugin:initialized for apparatus supportKits that
+                // fire after us in the startup sequence.
+                ctx.on('plugin:initialized', (plugin) => {
+                    const loaded = plugin;
+                    // Skip kits — we already scanned them above.
+                    if (isLoadedApparatus(loaded)) {
+                        registry.register(loaded);
+                    }
+                });
+            },
+        },
+    };
+}
+//# sourceMappingURL=fabricator.js.map

package/dist/fabricator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fabricator.js","sourceRoot":"","sources":["../src/fabricator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EACL,KAAK,EACL,WAAW,EACX,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAgDhC,yEAAyE;AAEzE,+CAA+C;AAC/C,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAiC,CAAC,EAAE,KAAK,QAAQ;QACzD,OAAQ,KAAiC,CAAC,GAAG,KAAK,UAAU,CAC7D,CAAC;AACJ,CAAC;AAED,yEAAyE;AAEzE,6EAA6E;AAC7E,MAAM,cAAc;IACD,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE3D,wDAAwD;IACxD,QAAQ,CAAC,MAAoB;QAC3B,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;gBAChC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;IACH,CAAC;IAED,mFAAmF;IAC3E,eAAe,CAAC,GAA4B;QAClD,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC;QAC/B,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI;YAAE,OAAO;QAElE,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,UAAqC,CAAC,EAAE,CAAC;YACzE,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAED,sCAAsC;IACtC,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;CACF;AAED,yEAAyE;AAEzE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;IAEtC,MAAM,GAAG,GAAkB;QACzB,eAAe,CAAC,EAAU;YACxB,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC;IAEF,OAAO;QACL,SAAS,EAAE;YACT,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,CAAC,SAAS,CAAC;YACrB,QAAQ,EAAE,GAAG;YAEb,KAAK,CAAC,GAAmB;gBACvB,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;gBAElB,sEAAsE;gBACtE,4DAA4D;gBAC5D,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;oBAC3B,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACzB,CAAC;gBAED,iEAAiE;gBACjE,yCAAyC;gBACzC,GAAG,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAe,EAAE,EAAE;oBAC/C,MAAM,MAAM,GAAG,MAAsB,CAAC;oBACtC,6CAA6C;oBAC7C,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;wBAC9B,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBAC5B,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @shardworks/fabricator-apparatus — The Fabricator.
+ *
+ * Guild engine design registry: scans kit contributions, stores engine designs
+ * by ID, and provides the FabricatorApi for design lookup.
+ *
+ * The EngineDesign, EngineRunContext, and EngineRunResult types live here
+ * canonically — kit authors import from this package to contribute engines.
+ */
+export type { EngineDesign, EngineRunContext, EngineRunResult, } from './fabricator.ts';
+export type { FabricatorApi } from './fabricator.ts';
+declare const _default: import("@shardworks/nexus-core").Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAIzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;;AAIrD,wBAAkC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @shardworks/fabricator-apparatus — The Fabricator.
+ *
+ * Guild engine design registry: scans kit contributions, stores engine designs
+ * by ID, and provides the FabricatorApi for design lookup.
+ *
+ * The EngineDesign, EngineRunContext, and EngineRunResult types live here
+ * canonically — kit authors import from this package to contribute engines.
+ */
+import { createFabricator } from "./fabricator.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+export default createFabricator();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAcnD,yEAAyE;AAEzE,eAAe,gBAAgB,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@shardworks/fabricator-apparatus",
+  "version": "0.1.109",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/fabricator"
+  },
+  "description": "The Fabricator — guild engine design registry apparatus",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@shardworks/nexus-core": "0.1.109"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}