@shardworks/tool-signal 0.1.17

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/handler.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    name: z.ZodString;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}>;
+export default _default;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAExB,wBAeG"}

package/dist/handler.js

@@ -0,0 +1,24 @@
+/**
+ * signal tool.
+ *
+ * Signals a custom guild event. The event is persisted to the Ledger's events
+ * table and will be processed by the Clockworks runner. Validates that the
+ * event name is declared in guild.json and is not in a reserved namespace.
+ */
+import { tool, validateCustomEvent, signalEvent } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    description: 'Signal a custom guild event for the Clockworks',
+    params: {
+        name: z.string().describe('Event name (must be declared in guild.json clockworks.events)'),
+        payload: z.record(z.string(), z.unknown()).optional().describe('Event payload (JSON object)'),
+    },
+    handler: (params, { home }) => {
+        // Validate the event name is declared and not reserved
+        validateCustomEvent(home, params.name);
+        // Persist the event
+        const eventId = signalEvent(home, params.name, params.payload ?? null, 'anima');
+        return { eventId, name: params.name };
+    },
+});
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAe,IAAI,CAAC;IAClB,WAAW,EAAE,gDAAgD;IAC7D,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+DAA+D,CAAC;QAC1F,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;KAC9F;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,uDAAuD;QACvD,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAEvC,oBAAoB;QACpB,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,CAAC,CAAC;QAEhF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;CACF,CAAC,CAAC"}

package/instructions.md

@@ -0,0 +1,13 @@
+# signal
+
+Signal a custom guild event. The event is recorded in the Ledger and will be processed by the Clockworks runner when `nsg clock tick` or `nsg clock run` is invoked.
+
+## Usage
+
+- The event name **must** be declared in `guild.json` under `clockworks.events`.
+- You **cannot** signal framework events (`anima.*`, `commission.*`, `tool.*`, `migration.*`, `guild.*`, `standing-order.*`) — those are emitted automatically by the framework.
+- The optional payload is a JSON object with event-specific data.
+
+## When to use
+
+Signal an event when something meaningful has happened that other parts of the guild should know about. Standing orders in `guild.json` determine what happens in response.

package/nexus-tool.json

@@ -0,0 +1,6 @@
+{
+  "entry": "src/handler.ts",
+  "instructions": "instructions.md",
+  "version": "0.1.0",
+  "description": "Signal custom guild events for the Clockworks"
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@shardworks/tool-signal",
+  "version": "0.1.17",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus-mk2",
+    "directory": "packages/tool-signal"
+  },
+  "description": "Signal custom guild events for the Clockworks",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/handler.d.ts",
+      "import": "./dist/handler.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@shardworks/nexus-core": "0.1.17"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist",
+    "nexus-tool.json",
+    "instructions.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}