@shardworks/nexus-core 0.1.99 → 0.1.101

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/README.md +95 -166
  2. package/dist/guild-config.d.ts +14 -52
  3. package/dist/guild-config.d.ts.map +1 -1
  4. package/dist/guild-config.js +7 -10
  5. package/dist/guild-config.js.map +1 -1
  6. package/dist/guild.d.ts +83 -0
  7. package/dist/guild.d.ts.map +1 -0
  8. package/dist/guild.js +45 -0
  9. package/dist/guild.js.map +1 -0
  10. package/dist/id.d.ts +14 -0
  11. package/dist/id.d.ts.map +1 -0
  12. package/dist/id.js +19 -0
  13. package/dist/id.js.map +1 -0
  14. package/dist/index.d.ts +6 -30
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +7 -32
  17. package/dist/index.js.map +1 -1
  18. package/dist/nexus-home.d.ts +0 -4
  19. package/dist/nexus-home.d.ts.map +1 -1
  20. package/dist/nexus-home.js +1 -9
  21. package/dist/nexus-home.js.map +1 -1
  22. package/dist/plugin.d.ts +115 -0
  23. package/dist/plugin.d.ts.map +1 -0
  24. package/dist/plugin.js +39 -0
  25. package/dist/plugin.js.map +1 -0
  26. package/dist/resolve-package.d.ts +58 -0
  27. package/dist/resolve-package.d.ts.map +1 -0
  28. package/dist/resolve-package.js +123 -0
  29. package/dist/resolve-package.js.map +1 -0
  30. package/package.json +5 -14
  31. package/dist/book.d.ts +0 -110
  32. package/dist/book.d.ts.map +0 -1
  33. package/dist/book.js +0 -16
  34. package/dist/book.js.map +0 -1
  35. package/dist/legacy/1/anima.d.ts +0 -79
  36. package/dist/legacy/1/anima.d.ts.map +0 -1
  37. package/dist/legacy/1/anima.js +0 -285
  38. package/dist/legacy/1/anima.js.map +0 -1
  39. package/dist/legacy/1/audit.d.ts +0 -23
  40. package/dist/legacy/1/audit.d.ts.map +0 -1
  41. package/dist/legacy/1/audit.js +0 -61
  42. package/dist/legacy/1/audit.js.map +0 -1
  43. package/dist/legacy/1/bundle.d.ts +0 -111
  44. package/dist/legacy/1/bundle.d.ts.map +0 -1
  45. package/dist/legacy/1/bundle.js +0 -452
  46. package/dist/legacy/1/bundle.js.map +0 -1
  47. package/dist/legacy/1/clock-daemon.d.ts +0 -2
  48. package/dist/legacy/1/clock-daemon.d.ts.map +0 -1
  49. package/dist/legacy/1/clock-daemon.js +0 -72
  50. package/dist/legacy/1/clock-daemon.js.map +0 -1
  51. package/dist/legacy/1/clockworks.d.ts +0 -98
  52. package/dist/legacy/1/clockworks.d.ts.map +0 -1
  53. package/dist/legacy/1/clockworks.js +0 -359
  54. package/dist/legacy/1/clockworks.js.map +0 -1
  55. package/dist/legacy/1/conversation.d.ts +0 -165
  56. package/dist/legacy/1/conversation.d.ts.map +0 -1
  57. package/dist/legacy/1/conversation.js +0 -457
  58. package/dist/legacy/1/conversation.js.map +0 -1
  59. package/dist/legacy/1/engine.d.ts +0 -90
  60. package/dist/legacy/1/engine.d.ts.map +0 -1
  61. package/dist/legacy/1/engine.js +0 -89
  62. package/dist/legacy/1/engine.js.map +0 -1
  63. package/dist/legacy/1/events.d.ts +0 -88
  64. package/dist/legacy/1/events.d.ts.map +0 -1
  65. package/dist/legacy/1/events.js +0 -239
  66. package/dist/legacy/1/events.js.map +0 -1
  67. package/dist/legacy/1/guild-config.d.ts +0 -74
  68. package/dist/legacy/1/guild-config.d.ts.map +0 -1
  69. package/dist/legacy/1/guild-config.js +0 -51
  70. package/dist/legacy/1/guild-config.js.map +0 -1
  71. package/dist/legacy/1/id.d.ts +0 -8
  72. package/dist/legacy/1/id.d.ts.map +0 -1
  73. package/dist/legacy/1/id.js +0 -27
  74. package/dist/legacy/1/id.js.map +0 -1
  75. package/dist/legacy/1/index.d.ts +0 -28
  76. package/dist/legacy/1/index.d.ts.map +0 -1
  77. package/dist/legacy/1/index.js +0 -32
  78. package/dist/legacy/1/index.js.map +0 -1
  79. package/dist/legacy/1/init-guild.d.ts +0 -24
  80. package/dist/legacy/1/init-guild.d.ts.map +0 -1
  81. package/dist/legacy/1/init-guild.js +0 -230
  82. package/dist/legacy/1/init-guild.js.map +0 -1
  83. package/dist/legacy/1/install-tool.d.ts +0 -73
  84. package/dist/legacy/1/install-tool.d.ts.map +0 -1
  85. package/dist/legacy/1/install-tool.js +0 -436
  86. package/dist/legacy/1/install-tool.js.map +0 -1
  87. package/dist/legacy/1/instantiate.d.ts +0 -33
  88. package/dist/legacy/1/instantiate.d.ts.map +0 -1
  89. package/dist/legacy/1/instantiate.js +0 -137
  90. package/dist/legacy/1/instantiate.js.map +0 -1
  91. package/dist/legacy/1/manifest.d.ts +0 -132
  92. package/dist/legacy/1/manifest.d.ts.map +0 -1
  93. package/dist/legacy/1/manifest.js +0 -321
  94. package/dist/legacy/1/manifest.js.map +0 -1
  95. package/dist/legacy/1/migrate.d.ts +0 -84
  96. package/dist/legacy/1/migrate.d.ts.map +0 -1
  97. package/dist/legacy/1/migrate.js +0 -228
  98. package/dist/legacy/1/migrate.js.map +0 -1
  99. package/dist/legacy/1/nexus-home.d.ts +0 -11
  100. package/dist/legacy/1/nexus-home.d.ts.map +0 -1
  101. package/dist/legacy/1/nexus-home.js +0 -16
  102. package/dist/legacy/1/nexus-home.js.map +0 -1
  103. package/dist/legacy/1/plugin-descriptor.d.ts +0 -3
  104. package/dist/legacy/1/plugin-descriptor.d.ts.map +0 -1
  105. package/dist/legacy/1/plugin-descriptor.js +0 -2
  106. package/dist/legacy/1/plugin-descriptor.js.map +0 -1
  107. package/dist/legacy/1/preconditions.d.ts +0 -100
  108. package/dist/legacy/1/preconditions.d.ts.map +0 -1
  109. package/dist/legacy/1/preconditions.js +0 -189
  110. package/dist/legacy/1/preconditions.js.map +0 -1
  111. package/dist/legacy/1/rehydrate.d.ts +0 -22
  112. package/dist/legacy/1/rehydrate.d.ts.map +0 -1
  113. package/dist/legacy/1/rehydrate.js +0 -109
  114. package/dist/legacy/1/rehydrate.js.map +0 -1
  115. package/dist/legacy/1/remove-tool.d.ts +0 -19
  116. package/dist/legacy/1/remove-tool.d.ts.map +0 -1
  117. package/dist/legacy/1/remove-tool.js +0 -105
  118. package/dist/legacy/1/remove-tool.js.map +0 -1
  119. package/dist/legacy/1/session.d.ts +0 -343
  120. package/dist/legacy/1/session.d.ts.map +0 -1
  121. package/dist/legacy/1/session.js +0 -499
  122. package/dist/legacy/1/session.js.map +0 -1
  123. package/dist/legacy/1/tool-registry.d.ts +0 -12
  124. package/dist/legacy/1/tool-registry.d.ts.map +0 -1
  125. package/dist/legacy/1/tool-registry.js +0 -28
  126. package/dist/legacy/1/tool-registry.js.map +0 -1
  127. package/dist/legacy/1/tool.d.ts +0 -10
  128. package/dist/legacy/1/tool.d.ts.map +0 -1
  129. package/dist/legacy/1/tool.js +0 -2
  130. package/dist/legacy/1/tool.js.map +0 -1
  131. package/dist/legacy/1/upgrade.d.ts +0 -129
  132. package/dist/legacy/1/upgrade.d.ts.map +0 -1
  133. package/dist/legacy/1/upgrade.js +0 -355
  134. package/dist/legacy/1/upgrade.js.map +0 -1
  135. package/dist/legacy/1/workshop.d.ts +0 -95
  136. package/dist/legacy/1/workshop.d.ts.map +0 -1
  137. package/dist/legacy/1/workshop.js +0 -229
  138. package/dist/legacy/1/workshop.js.map +0 -1
  139. package/dist/legacy/1/worktree.d.ts +0 -67
  140. package/dist/legacy/1/worktree.d.ts.map +0 -1
  141. package/dist/legacy/1/worktree.js +0 -117
  142. package/dist/legacy/1/worktree.js.map +0 -1
  143. package/dist/legacy/1/writ.d.ts +0 -130
  144. package/dist/legacy/1/writ.d.ts.map +0 -1
  145. package/dist/legacy/1/writ.js +0 -599
  146. package/dist/legacy/1/writ.js.map +0 -1
  147. package/dist/rig-context.d.ts +0 -47
  148. package/dist/rig-context.d.ts.map +0 -1
  149. package/dist/rig-context.js +0 -11
  150. package/dist/rig-context.js.map +0 -1
  151. package/dist/rig-descriptor.d.ts +0 -39
  152. package/dist/rig-descriptor.d.ts.map +0 -1
  153. package/dist/rig-descriptor.js +0 -12
  154. package/dist/rig-descriptor.js.map +0 -1
  155. package/dist/rig.d.ts +0 -70
  156. package/dist/rig.d.ts.map +0 -1
  157. package/dist/rig.js +0 -14
  158. package/dist/rig.js.map +0 -1
  159. package/dist/tool.d.ts +0 -136
  160. package/dist/tool.d.ts.map +0 -1
  161. package/dist/tool.js +0 -135
  162. package/dist/tool.js.map +0 -1
  163. package/migrations/001-schema.sql +0 -177
  164. package/migrations/002-writs.sql +0 -44
  165. package/migrations/003-conversations.sql +0 -43
  166. package/migrations/004-remove-commissions.sql +0 -24
@@ -1,47 +0,0 @@
1
- /**
2
- * RigContext — the single injected context for tool and engine handlers.
3
- *
4
- * Replaces the old `ToolContext`. Both tool handlers and engine handlers
5
- * receive a `RigContext`. Cross-rig capabilities grow directly on this
6
- * interface as the runtime expands.
7
- *
8
- * `ToolContext` is kept as an alias for backward compatibility.
9
- */
10
- import type { Book, ReadOnlyBook } from './book.ts';
11
- /**
12
- * The context injected into every tool and engine handler invocation.
13
- *
14
- * Scoped to the rig that owns the handler — `book()` returns handles to
15
- * books declared in that rig's schema. Cross-rig reads go through `rigBook()`.
16
- */
17
- export interface RigContext {
18
- /** Absolute path to the guild root. */
19
- home: string;
20
- /**
21
- * Get a typed handle to one of this rig's books.
22
- *
23
- * The book must be declared in this rig's `Rig` export under `books`.
24
- * Returns a writable `Book<T>`.
25
- *
26
- * @example
27
- * const writs = ctx.book<Writ>('writs');
28
- * await writs.put({ id: ulid(), status: 'ready', ... });
29
- */
30
- book<T extends {
31
- id: string;
32
- }>(name: string): Book<T>;
33
- /**
34
- * Get a read-only handle to a book owned by another rig.
35
- *
36
- * Cross-rig access is read-only — use this to read framework or sibling
37
- * rig data without taking a write dependency on it.
38
- *
39
- * @example
40
- * const writs = ctx.rigBook<Writ>('nexus-ledger', 'writs');
41
- * const active = await writs.find({ where: { status: 'active' } });
42
- */
43
- rigBook<T extends {
44
- id: string;
45
- }>(rigId: string, name: string): ReadOnlyBook<T>;
46
- }
47
- //# sourceMappingURL=rig-context.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"rig-context.d.ts","sourceRoot":"","sources":["../src/rig-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;OASG;IACH,IAAI,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtD;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;CAGjF"}
@@ -1,11 +0,0 @@
1
- /**
2
- * RigContext — the single injected context for tool and engine handlers.
3
- *
4
- * Replaces the old `ToolContext`. Both tool handlers and engine handlers
5
- * receive a `RigContext`. Cross-rig capabilities grow directly on this
6
- * interface as the runtime expands.
7
- *
8
- * `ToolContext` is kept as an alias for backward compatibility.
9
- */
10
- export {};
11
- //# sourceMappingURL=rig-context.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"rig-context.js","sourceRoot":"","sources":["../src/rig-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
@@ -1,39 +0,0 @@
1
- /**
2
- * rig.json — the rig descriptor format.
3
- *
4
- * Declared by rig packages to advertise their capabilities and
5
- * requirements. Read by mainspring at install time.
6
- *
7
- * A rig package MAY include a rig.json at its root.
8
- * If absent, mainspring discovers tools from the package's exports
9
- * and assumes no dependencies.
10
- */
11
- /**
12
- * A dependency on another rig.
13
- *
14
- * Rig dependencies are checked at install time — if a required
15
- * rig is not installed in the guild, the install fails with a
16
- * clear error message.
17
- */
18
- export interface RigDependency {
19
- /** Rig key of the required rig (e.g. 'nexus-stdlib'). */
20
- rig: string;
21
- }
22
- /**
23
- * The rig.json descriptor shape.
24
- *
25
- * All fields are optional — a minimal descriptor is just `{}`.
26
- * Mainspring uses this for dependency checking at install time.
27
- */
28
- export interface RigDescriptor {
29
- /**
30
- * Human-readable rig description.
31
- */
32
- description?: string;
33
- /**
34
- * Rigs this rig depends on.
35
- * Checked at install time — missing dependencies cause install to fail.
36
- */
37
- dependencies?: RigDependency[];
38
- }
39
- //# sourceMappingURL=rig-descriptor.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"rig-descriptor.d.ts","sourceRoot":"","sources":["../src/rig-descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,aAAa,EAAE,CAAC;CAChC"}
@@ -1,12 +0,0 @@
1
- /**
2
- * rig.json — the rig descriptor format.
3
- *
4
- * Declared by rig packages to advertise their capabilities and
5
- * requirements. Read by mainspring at install time.
6
- *
7
- * A rig package MAY include a rig.json at its root.
8
- * If absent, mainspring discovers tools from the package's exports
9
- * and assumes no dependencies.
10
- */
11
- export {};
12
- //# sourceMappingURL=rig-descriptor.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"rig-descriptor.js","sourceRoot":"","sources":["../src/rig-descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}
package/dist/rig.d.ts DELETED
@@ -1,70 +0,0 @@
1
- import type { ToolDefinition } from './tool.ts';
2
- /**
3
- * Schema declaration for a single Book in a rig's `books` map.
4
- *
5
- * Rig authors declare which fields they want to query on — mainspring
6
- * creates the backing SQLite indexes at startup. No SQL, no JSONPath
7
- * syntax; field names are plain or dot-notation for nested fields.
8
- *
9
- * @example
10
- * books: {
11
- * writs: { indexes: ['status', 'createdAt', 'parent.id'] },
12
- * }
13
- */
14
- export interface BookOptions {
15
- /**
16
- * Field names to index for efficient querying.
17
- *
18
- * Plain field names ('status') or dot notation for nested fields
19
- * ('parent.id'). The storage adapter translates these internally.
20
- *
21
- * @example ['status', 'createdAt', 'anima']
22
- */
23
- indexes?: string[];
24
- }
25
- /**
26
- * The author-facing export type for a rig package.
27
- *
28
- * Rig packages export this as their default export. Mainspring reads
29
- * it at load time to discover the rig's contributions.
30
- *
31
- * All fields are optional — a rig may contribute tools, future engine
32
- * definitions, lifecycle hooks, or any combination thereof.
33
- *
34
- * @example
35
- * ```typescript
36
- * import { type Rig, tool } from '@shardworks/nexus-core';
37
- *
38
- * const myTool = tool({ ... });
39
- *
40
- * export default {
41
- * tools: [myTool],
42
- * } satisfies Rig;
43
- * ```
44
- */
45
- export interface Rig {
46
- /** Tools this rig contributes to the guild. */
47
- tools?: ToolDefinition[];
48
- /**
49
- * Books this rig declares — named document collections backed by SQLite.
50
- *
51
- * Mainspring reads these declarations at startup and creates tables and
52
- * indexes for any that don't yet exist. Additive only — no destructive
53
- * migrations.
54
- *
55
- * @example
56
- * books: {
57
- * writs: { indexes: ['status', 'createdAt'] },
58
- * }
59
- */
60
- books?: Record<string, BookOptions>;
61
- }
62
- /**
63
- * Type guard: is this value a Rig export object?
64
- *
65
- * Distinguished from bare ToolDefinition/array exports for backward
66
- * compatibility — rigs may still export a single tool or tool array
67
- * directly.
68
- */
69
- export declare function isRig(obj: unknown): obj is Rig;
70
- //# sourceMappingURL=rig.d.ts.map
package/dist/rig.d.ts.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"rig.d.ts","sourceRoot":"","sources":["../src/rig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,GAAG;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,GAAG,CAO9C"}
package/dist/rig.js DELETED
@@ -1,14 +0,0 @@
1
- /**
2
- * Type guard: is this value a Rig export object?
3
- *
4
- * Distinguished from bare ToolDefinition/array exports for backward
5
- * compatibility — rigs may still export a single tool or tool array
6
- * directly.
7
- */
8
- export function isRig(obj) {
9
- return (typeof obj === 'object' &&
10
- obj !== null &&
11
- !Array.isArray(obj) &&
12
- ('tools' in obj));
13
- }
14
- //# sourceMappingURL=rig.js.map
package/dist/rig.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"rig.js","sourceRoot":"","sources":["../src/rig.ts"],"names":[],"mappings":"AAiEA;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY;IAChC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QACnB,CAAC,OAAO,IAAI,GAAG,CAAC,CACjB,CAAC;AACJ,CAAC"}
package/dist/tool.d.ts DELETED
@@ -1,136 +0,0 @@
1
- /**
2
- * Tool SDK — the primary authoring interface for module-based tools.
3
- *
4
- * Use `tool()` to define a typed tool with Zod parameter schemas.
5
- * The returned definition is what the MCP engine imports and registers as a tool,
6
- * what the CLI uses to auto-generate subcommands, and what engines import directly.
7
- *
8
- * A package can export a single tool or an array of tools:
9
- *
10
- * @example Single tool
11
- * ```typescript
12
- * import { tool } from '@shardworks/nexus-core';
13
- * import { z } from 'zod';
14
- *
15
- * export default tool({
16
- * name: 'lookup',
17
- * description: 'Look up an anima by name',
18
- * instructionsFile: './instructions.md',
19
- * params: {
20
- * name: z.string().describe('Anima name'),
21
- * },
22
- * handler: async ({ name }, { home }) => {
23
- * return { found: true, status: 'active' };
24
- * },
25
- * });
26
- * ```
27
- *
28
- * @example Tool collection
29
- * ```typescript
30
- * export default [
31
- * tool({ name: 'commission', description: '...', params: {...}, handler: ... }),
32
- * tool({ name: 'signal', description: '...', params: {...}, handler: ... }),
33
- * ];
34
- * ```
35
- */
36
- import { z } from 'zod';
37
- import type { RigContext } from './rig-context.ts';
38
- type ZodShape = Record<string, z.ZodType>;
39
- /**
40
- * The caller types a tool can be invoked from.
41
- * - `'cli'` — accessible via `nsg` commands (human-facing)
42
- * - `'mcp'` — accessible via MCP server (anima-facing)
43
- *
44
- * Defaults to all caller types if `callableFrom` is unspecified.
45
- */
46
- export type ToolCaller = 'cli' | 'mcp';
47
- /**
48
- * A fully-defined tool — the return type of `tool()`.
49
- *
50
- * The MCP engine uses `.params.shape` to register the tool's input schema,
51
- * `.description` for the tool description, and `.handler` to execute calls.
52
- * The CLI uses `.params` to auto-generate Commander options.
53
- * Engines call `.handler` directly.
54
- */
55
- export interface ToolDefinition<TShape extends ZodShape = ZodShape> {
56
- /** Tool name — used for resolution when a package exports multiple tools. */
57
- readonly name: string;
58
- readonly description: string;
59
- /** Per-tool instructions injected into the anima's session context (inline text). */
60
- readonly instructions?: string;
61
- /**
62
- * Path to an instructions file, relative to the package root.
63
- * Resolved by the manifest engine at session time.
64
- * Mutually exclusive with `instructions`.
65
- */
66
- readonly instructionsFile?: string;
67
- /**
68
- * Caller types this tool is available to.
69
- * Always a normalized array. Absent means available to all callers.
70
- */
71
- readonly callableFrom?: ToolCaller[];
72
- readonly params: z.ZodObject<TShape>;
73
- readonly handler: (params: z.infer<z.ZodObject<TShape>>, context: RigContext) => unknown | Promise<unknown>;
74
- }
75
- /** Input to `tool()` — instructions are either inline text or a file path, not both. */
76
- type ToolInput<TShape extends ZodShape> = {
77
- name: string;
78
- description: string;
79
- params: TShape;
80
- handler: (params: z.infer<z.ZodObject<TShape>>, context: RigContext) => unknown | Promise<unknown>;
81
- /**
82
- * Caller types this tool is available to.
83
- * Accepts a single caller or an array. Normalized to an array in the returned definition.
84
- */
85
- callableFrom?: ToolCaller | ToolCaller[];
86
- } & ({
87
- instructions?: string;
88
- instructionsFile?: never;
89
- } | {
90
- instructions?: never;
91
- instructionsFile?: string;
92
- });
93
- /**
94
- * Define a Nexus tool.
95
- *
96
- * This is the primary SDK entry point for module-based tools. Pass a
97
- * name, description, a params object of Zod schemas, and a handler function.
98
- * The framework handles the rest — MCP registration, CLI generation, validation.
99
- *
100
- * The handler receives two arguments:
101
- * - `params` — the validated input, typed from your Zod schemas
102
- * - `context` — framework-injected context (guild root path, etc.)
103
- *
104
- * Return any JSON-serializable value. The MCP engine wraps it as tool output;
105
- * the CLI prints it; engines use it directly.
106
- *
107
- * Instructions can be provided inline or as a file path:
108
- * - `instructions: 'Use this tool when...'` — inline text
109
- * - `instructionsFile: './instructions.md'` — resolved at manifest time
110
- */
111
- export declare function tool<TShape extends ZodShape>(def: ToolInput<TShape>): ToolDefinition<TShape>;
112
- /**
113
- * Resolve a single ToolDefinition from a module's default export.
114
- *
115
- * Handles both single-tool and array-of-tools exports:
116
- * - Single tool: `export default tool({...})` → returned directly
117
- * - Array: `export default [tool({...}), tool({...})]` → find by name
118
- *
119
- * @param moduleDefault - The module's default export
120
- * @param toolName - The tool name to find (required for array exports)
121
- * @returns The matching ToolDefinition, or null if not found
122
- */
123
- export declare function resolveToolFromExport(moduleDefault: unknown, toolName?: string): ToolDefinition | null;
124
- /**
125
- * Resolve all ToolDefinitions from a module's default export.
126
- *
127
- * Handles three export shapes:
128
- * - `Rig` object: `{ tools: [...] }` — preferred form
129
- * - `ToolDefinition[]` — bare array, backward compatible
130
- * - `ToolDefinition` — single tool, backward compatible
131
- */
132
- export declare function resolveAllToolsFromExport(moduleDefault: unknown): ToolDefinition[];
133
- /** Type guard: is this value a ToolDefinition? */
134
- export declare function isToolDefinition(obj: unknown): obj is ToolDefinition;
135
- export {};
136
- //# sourceMappingURL=tool.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,KAAK,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,QAAQ,GAAG,QAAQ;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAChB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,EAAE,UAAU,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,wFAAwF;AACxF,KAAK,SAAS,CAAC,MAAM,SAAS,QAAQ,IAAI;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,EAAE,UAAU,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;OAGG;IACH,YAAY,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;CAC1C,GAAG,CACA;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,KAAK,CAAA;CAAE,GACnD;IAAE,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CACtD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,QAAQ,EAAE,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAY5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,OAAO,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB,cAAc,GAAG,IAAI,CAoBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,OAAO,GACrB,cAAc,EAAE,CAclB;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAYpE"}
package/dist/tool.js DELETED
@@ -1,135 +0,0 @@
1
- /**
2
- * Tool SDK — the primary authoring interface for module-based tools.
3
- *
4
- * Use `tool()` to define a typed tool with Zod parameter schemas.
5
- * The returned definition is what the MCP engine imports and registers as a tool,
6
- * what the CLI uses to auto-generate subcommands, and what engines import directly.
7
- *
8
- * A package can export a single tool or an array of tools:
9
- *
10
- * @example Single tool
11
- * ```typescript
12
- * import { tool } from '@shardworks/nexus-core';
13
- * import { z } from 'zod';
14
- *
15
- * export default tool({
16
- * name: 'lookup',
17
- * description: 'Look up an anima by name',
18
- * instructionsFile: './instructions.md',
19
- * params: {
20
- * name: z.string().describe('Anima name'),
21
- * },
22
- * handler: async ({ name }, { home }) => {
23
- * return { found: true, status: 'active' };
24
- * },
25
- * });
26
- * ```
27
- *
28
- * @example Tool collection
29
- * ```typescript
30
- * export default [
31
- * tool({ name: 'commission', description: '...', params: {...}, handler: ... }),
32
- * tool({ name: 'signal', description: '...', params: {...}, handler: ... }),
33
- * ];
34
- * ```
35
- */
36
- import { z } from 'zod';
37
- import { isRig } from "./rig.js";
38
- /**
39
- * Define a Nexus tool.
40
- *
41
- * This is the primary SDK entry point for module-based tools. Pass a
42
- * name, description, a params object of Zod schemas, and a handler function.
43
- * The framework handles the rest — MCP registration, CLI generation, validation.
44
- *
45
- * The handler receives two arguments:
46
- * - `params` — the validated input, typed from your Zod schemas
47
- * - `context` — framework-injected context (guild root path, etc.)
48
- *
49
- * Return any JSON-serializable value. The MCP engine wraps it as tool output;
50
- * the CLI prints it; engines use it directly.
51
- *
52
- * Instructions can be provided inline or as a file path:
53
- * - `instructions: 'Use this tool when...'` — inline text
54
- * - `instructionsFile: './instructions.md'` — resolved at manifest time
55
- */
56
- export function tool(def) {
57
- return {
58
- name: def.name,
59
- description: def.description,
60
- ...(def.instructions ? { instructions: def.instructions } : {}),
61
- ...(def.instructionsFile ? { instructionsFile: def.instructionsFile } : {}),
62
- ...(def.callableFrom !== undefined
63
- ? { callableFrom: Array.isArray(def.callableFrom) ? def.callableFrom : [def.callableFrom] }
64
- : {}),
65
- params: z.object(def.params),
66
- handler: def.handler,
67
- };
68
- }
69
- /**
70
- * Resolve a single ToolDefinition from a module's default export.
71
- *
72
- * Handles both single-tool and array-of-tools exports:
73
- * - Single tool: `export default tool({...})` → returned directly
74
- * - Array: `export default [tool({...}), tool({...})]` → find by name
75
- *
76
- * @param moduleDefault - The module's default export
77
- * @param toolName - The tool name to find (required for array exports)
78
- * @returns The matching ToolDefinition, or null if not found
79
- */
80
- export function resolveToolFromExport(moduleDefault, toolName) {
81
- // Single tool export
82
- if (isToolDefinition(moduleDefault)) {
83
- if (!toolName || moduleDefault.name === toolName)
84
- return moduleDefault;
85
- return null;
86
- }
87
- // Array of tools — find by name
88
- if (Array.isArray(moduleDefault)) {
89
- for (const item of moduleDefault) {
90
- if (!isToolDefinition(item))
91
- continue;
92
- if (item.name === toolName)
93
- return item;
94
- }
95
- // If no name match but array has exactly one tool, return it
96
- const tools = moduleDefault.filter(isToolDefinition);
97
- if (tools.length === 1 && !toolName)
98
- return tools[0];
99
- return null;
100
- }
101
- return null;
102
- }
103
- /**
104
- * Resolve all ToolDefinitions from a module's default export.
105
- *
106
- * Handles three export shapes:
107
- * - `Rig` object: `{ tools: [...] }` — preferred form
108
- * - `ToolDefinition[]` — bare array, backward compatible
109
- * - `ToolDefinition` — single tool, backward compatible
110
- */
111
- export function resolveAllToolsFromExport(moduleDefault) {
112
- if (isRig(moduleDefault)) {
113
- return (moduleDefault.tools ?? []).filter(isToolDefinition);
114
- }
115
- if (isToolDefinition(moduleDefault)) {
116
- return [moduleDefault];
117
- }
118
- if (Array.isArray(moduleDefault)) {
119
- return moduleDefault.filter(isToolDefinition);
120
- }
121
- return [];
122
- }
123
- /** Type guard: is this value a ToolDefinition? */
124
- export function isToolDefinition(obj) {
125
- return (typeof obj === 'object' &&
126
- obj !== null &&
127
- 'name' in obj &&
128
- 'description' in obj &&
129
- 'params' in obj &&
130
- 'handler' in obj &&
131
- typeof obj.name === 'string' &&
132
- typeof obj.description === 'string' &&
133
- typeof obj.handler === 'function');
134
- }
135
- //# sourceMappingURL=tool.js.map
package/dist/tool.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}