sysprom 1.1.0 → 1.2.1

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 (54) hide show
  1. package/README.md +1 -0
  2. package/dist/src/canonical-json.d.ts +0 -1
  3. package/dist/src/canonical-json.js +0 -1
  4. package/dist/src/cli/define-command.d.ts +15 -0
  5. package/dist/src/cli/define-command.js +11 -0
  6. package/dist/src/cli/shared.d.ts +23 -4
  7. package/dist/src/cli/shared.js +68 -17
  8. package/dist/src/index.d.ts +0 -1
  9. package/dist/src/index.js +0 -1
  10. package/dist/src/io.d.ts +0 -2
  11. package/dist/src/io.js +0 -2
  12. package/dist/src/json-to-md.d.ts +0 -3
  13. package/dist/src/json-to-md.js +0 -3
  14. package/dist/src/md-to-json.d.ts +0 -3
  15. package/dist/src/md-to-json.js +0 -3
  16. package/dist/src/operations/add-node.d.ts +1 -2
  17. package/dist/src/operations/add-node.js +1 -2
  18. package/dist/src/operations/add-plan-task.d.ts +1 -2
  19. package/dist/src/operations/add-plan-task.js +1 -2
  20. package/dist/src/operations/add-relationship.d.ts +1 -2
  21. package/dist/src/operations/add-relationship.js +1 -2
  22. package/dist/src/operations/define-operation.d.ts +5 -8
  23. package/dist/src/operations/define-operation.js +1 -2
  24. package/dist/src/operations/mark-task-done.d.ts +1 -2
  25. package/dist/src/operations/mark-task-done.js +1 -2
  26. package/dist/src/operations/mark-task-undone.d.ts +1 -2
  27. package/dist/src/operations/mark-task-undone.js +1 -2
  28. package/dist/src/operations/next-id.d.ts +1 -2
  29. package/dist/src/operations/next-id.js +1 -2
  30. package/dist/src/operations/remove-node.d.ts +1 -2
  31. package/dist/src/operations/remove-node.js +1 -2
  32. package/dist/src/operations/remove-relationship.d.ts +1 -2
  33. package/dist/src/operations/remove-relationship.js +1 -2
  34. package/dist/src/operations/rename.d.ts +1 -2
  35. package/dist/src/operations/rename.js +1 -2
  36. package/dist/src/operations/task-list.d.ts +1 -2
  37. package/dist/src/operations/task-list.js +1 -2
  38. package/dist/src/operations/update-node.d.ts +1 -2
  39. package/dist/src/operations/update-node.js +1 -2
  40. package/dist/src/operations/update-plan-task.d.ts +1 -2
  41. package/dist/src/operations/update-plan-task.js +1 -2
  42. package/dist/src/schema.d.ts +4 -1
  43. package/dist/src/schema.js +4 -1
  44. package/dist/src/speckit/generate.d.ts +36 -6
  45. package/dist/src/speckit/generate.js +58 -6
  46. package/dist/src/speckit/parse.d.ts +37 -6
  47. package/dist/src/speckit/parse.js +53 -6
  48. package/dist/src/speckit/plan.d.ts +22 -0
  49. package/dist/src/speckit/plan.js +53 -0
  50. package/dist/src/speckit/project.d.ts +9 -0
  51. package/dist/src/speckit/project.js +17 -0
  52. package/dist/src/text.d.ts +6 -4
  53. package/dist/src/text.js +6 -4
  54. package/package.json +2 -1
package/README.md CHANGED
@@ -139,6 +139,7 @@ SysProM models systems as directed graphs across abstraction layers — intent,
139
139
  | [RFC Processes](https://www.rfc-editor.org/rfc/rfc2026) | ✅ | | | ✅ | 🔶 | | | | | | | | 🔶 | 🔶 |
140
140
  | [Ralplan](https://github.com/yeachan-heo/oh-my-claudecode/blob/main/skills/ralplan/SKILL.md) | ✅ | | 🔶 | ✅ | | 🔶 | | | | | | | ✅ | 🔶 |
141
141
  | [GSD](https://github.com/gsd-build/get-shit-done) | ✅ | | | 🔶 | | 🔶 | | | | | | | | |
142
+ | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | ✅ | 🔶 | ✅ | ✅ | ✅ | | 🔶 | | | | | ✅ | ✅ | ✅ |
142
143
  | [Superpowers](https://github.com/obra/superpowers) | ✅ | 🔶 | 🔶 | 🔶 | 🔶 | ✅ | 🔶 | | ✅ | 🔶 | | ✅ | ✅ | ✅ |
143
144
  | **SysProM** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🔶 | | 🔶 | ✅ | ✅ | ✅ | ✅ |
144
145
 
@@ -17,7 +17,6 @@ export interface FormatOptions {
17
17
  }
18
18
  /**
19
19
  * Serialise a value to canonical JSON with RFC 8785 key ordering.
20
- *
21
20
  * @param value - The value to serialise.
22
21
  * @param options - Formatting options (e.g. indentation).
23
22
  * @returns The canonical JSON string.
@@ -12,7 +12,6 @@
12
12
  */
13
13
  /**
14
14
  * Serialise a value to canonical JSON with RFC 8785 key ordering.
15
- *
16
15
  * @param value - The value to serialise.
17
16
  * @param options - Formatting options (e.g. indentation).
18
17
  * @returns The canonical JSON string.
@@ -1,5 +1,6 @@
1
1
  import * as z from "zod";
2
2
  import { Command } from "commander";
3
+ /** Definition of a CLI command — name, description, Zod schemas for args/opts, optional subcommands, and action handler. */
3
4
  export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOpts extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
4
5
  name: string;
5
6
  description: string;
@@ -9,13 +10,21 @@ export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObje
9
10
  action?: (args: z.infer<TArgs>, opts: z.infer<TOpts>) => void;
10
11
  apiLink?: string;
11
12
  }
13
+ /**
14
+ * Build a Commander.js command tree from a declarative CommandDef, wiring up Zod-validated args, options, and actions.
15
+ * @param def - The command definition to build from.
16
+ * @param parent - The parent Commander command to attach to.
17
+ * @returns The constructed Commander command.
18
+ */
12
19
  export declare function buildCommander(def: CommandDef, parent: Command): Command;
20
+ /** Extracted documentation for a CLI positional argument. */
13
21
  export interface ArgDoc {
14
22
  name: string;
15
23
  description: string;
16
24
  required: boolean;
17
25
  choices?: string[];
18
26
  }
27
+ /** Extracted documentation for a CLI option/flag. */
19
28
  export interface OptDoc {
20
29
  flag: string;
21
30
  description: string;
@@ -23,6 +32,7 @@ export interface OptDoc {
23
32
  repeatable: boolean;
24
33
  choices?: string[];
25
34
  }
35
+ /** Extracted documentation for a CLI command, including its arguments, options, and subcommands. */
26
36
  export interface CommandDoc {
27
37
  name: string;
28
38
  description: string;
@@ -31,4 +41,9 @@ export interface CommandDoc {
31
41
  subcommands?: CommandDoc[];
32
42
  apiLink?: string;
33
43
  }
44
+ /**
45
+ * Extract structured documentation from a CommandDef by introspecting its Zod schemas for args and options.
46
+ * @param def - The command definition to extract docs from.
47
+ * @returns Structured documentation for the command.
48
+ */
34
49
  export declare function extractDocs(def: CommandDef): CommandDoc;
@@ -77,6 +77,12 @@ function getShape(schema) {
77
77
  function collect(value, previous) {
78
78
  return [...previous, value];
79
79
  }
80
+ /**
81
+ * Build a Commander.js command tree from a declarative CommandDef, wiring up Zod-validated args, options, and actions.
82
+ * @param def - The command definition to build from.
83
+ * @param parent - The parent Commander command to attach to.
84
+ * @returns The constructed Commander command.
85
+ */
80
86
  export function buildCommander(def, parent) {
81
87
  const cmd = parent.command(def.name);
82
88
  cmd.description(def.description);
@@ -190,6 +196,11 @@ export function buildCommander(def, parent) {
190
196
  }
191
197
  return cmd;
192
198
  }
199
+ /**
200
+ * Extract structured documentation from a CommandDef by introspecting its Zod schemas for args and options.
201
+ * @param def - The command definition to extract docs from.
202
+ * @returns Structured documentation for the command.
203
+ */
193
204
  export function extractDocs(def) {
194
205
  const args = [];
195
206
  {
@@ -8,8 +8,15 @@ export declare const noArgs: z.ZodObject<{}, z.core.$strict>;
8
8
  /**
9
9
  * Resolve a SysProM document path. If no explicit path is given, search the
10
10
  * working directory by priority:
11
- * 1. .spm.json 2. .spm.md 3. .spm/
12
- * 4. *.spm.json 5. *.spm.md 6. *.spm/ (glob — must be unique)
11
+ * 1. .spm.json 2. .spm.md 3. .spm/
12
+ * 4. .sysprom.json 5. .sysprom.md 6. .sysprom/
13
+ * 7. *.spm.json 8. *.spm.md 9. *.spm/
14
+ * 10. *.sysprom.json 11. *.sysprom.md 12. *.sysprom/
15
+ *
16
+ * All matching is case-insensitive. Glob tiers must have exactly one match.
17
+ * @param input - Explicit document path, or undefined for auto-detection.
18
+ * @param cwd - Working directory to search from (defaults to `.`).
19
+ * @returns The resolved document path.
13
20
  */
14
21
  export declare function resolveInput(input?: string, cwd?: string): string;
15
22
  /** Common output/persistence options for read-only commands. */
@@ -24,14 +31,26 @@ export declare const mutationOpts: z.ZodObject<{
24
31
  dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
25
32
  sync: z.ZodOptional<z.ZodString>;
26
33
  }, z.core.$strip>;
34
+ /** Inferred type for read-only CLI options (input path, JSON output flag). */
27
35
  export type ReadOpts = z.infer<typeof readOpts>;
36
+ /** Inferred type for mutation CLI options (extends ReadOpts with sync-to-markdown). */
28
37
  export type MutationOpts = z.infer<typeof mutationOpts>;
38
+ /** A document loaded from a CLI input path with its format and resolved path. */
29
39
  export interface LoadedDoc {
30
40
  doc: SysProMDocument;
31
41
  format: Format;
32
42
  path: string;
33
43
  }
34
- /** Load a document from a CLI input path (auto-resolved if omitted). */
44
+ /**
45
+ * Load a document from a CLI input path (auto-resolved if omitted).
46
+ * @param input - Explicit document path, or undefined for auto-detection.
47
+ * @returns The loaded document with format and resolved path.
48
+ */
35
49
  export declare function loadDoc(input?: string): LoadedDoc;
36
- /** Persist a document and optionally sync to markdown. */
50
+ /**
51
+ * Persist a document and optionally sync to markdown.
52
+ * @param doc - The document to save.
53
+ * @param loaded - The original loaded document (provides format and path).
54
+ * @param opts - Mutation options (e.g. sync-to-markdown flag).
55
+ */
37
56
  export declare function persistDoc(doc: SysProMDocument, loaded: LoadedDoc, opts: MutationOpts): void;
@@ -1,5 +1,5 @@
1
1
  import * as z from "zod";
2
- import { existsSync, readdirSync, statSync } from "node:fs";
2
+ import { readdirSync, statSync } from "node:fs";
3
3
  import { join, resolve } from "node:path";
4
4
  import { loadDocument, saveDocument } from "../io.js";
5
5
  import { jsonToMarkdownMultiDoc } from "../json-to-md.js";
@@ -23,29 +23,71 @@ const pathOpt = z
23
23
  /**
24
24
  * Resolve a SysProM document path. If no explicit path is given, search the
25
25
  * working directory by priority:
26
- * 1. .spm.json 2. .spm.md 3. .spm/
27
- * 4. *.spm.json 5. *.spm.md 6. *.spm/ (glob — must be unique)
26
+ * 1. .spm.json 2. .spm.md 3. .spm/
27
+ * 4. .sysprom.json 5. .sysprom.md 6. .sysprom/
28
+ * 7. *.spm.json 8. *.spm.md 9. *.spm/
29
+ * 10. *.sysprom.json 11. *.sysprom.md 12. *.sysprom/
30
+ *
31
+ * All matching is case-insensitive. Glob tiers must have exactly one match.
32
+ * @param input - Explicit document path, or undefined for auto-detection.
33
+ * @param cwd - Working directory to search from (defaults to `.`).
34
+ * @returns The resolved document path.
28
35
  */
29
36
  export function resolveInput(input, cwd) {
30
37
  if (input)
31
38
  return input;
32
39
  const dir = resolve(cwd ?? ".");
33
- // Priority 1–3: exact names
34
- const exact = [".spm.json", ".spm.md", ".spm"];
35
- for (const name of exact) {
36
- const candidate = join(dir, name);
37
- if (existsSync(candidate))
38
- return candidate;
39
- }
40
- // Priority 4–6: glob by suffix
40
+ // Exact names to check, in priority order (case-insensitive)
41
+ const exactNames = [
42
+ ".spm.json",
43
+ ".spm.md",
44
+ ".spm",
45
+ ".sysprom.json",
46
+ ".sysprom.md",
47
+ ".sysprom",
48
+ ];
41
49
  const entries = readdirSync(dir);
42
- const suffixes = [".spm.json", ".spm.md", ".spm"];
43
- for (const suffix of suffixes) {
50
+ for (const name of exactNames) {
51
+ const isDirSuffix = name.endsWith(".spm") || name.endsWith(".sysprom");
52
+ const found = entries.filter((e) => e.toLowerCase() === name);
53
+ if (found.length > 1) {
54
+ throw new Error(`Multiple SysProM documents found: ${found.join(", ")}. Specify one explicitly.`);
55
+ }
56
+ if (found.length === 1) {
57
+ const candidate = join(dir, found[0]);
58
+ if (isDirSuffix) {
59
+ try {
60
+ if (statSync(candidate).isDirectory())
61
+ return candidate;
62
+ }
63
+ catch {
64
+ /* skip */
65
+ }
66
+ }
67
+ else {
68
+ return candidate;
69
+ }
70
+ }
71
+ }
72
+ // Glob suffixes in priority order (case-insensitive)
73
+ const globSuffixes = [
74
+ ".spm.json",
75
+ ".spm.md",
76
+ ".spm",
77
+ ".sysprom.json",
78
+ ".sysprom.md",
79
+ ".sysprom",
80
+ ];
81
+ for (const suffix of globSuffixes) {
82
+ const isDirSuffix = suffix === ".spm" || suffix === ".sysprom";
44
83
  const matches = entries
45
- .filter((e) => e.endsWith(suffix) && e !== suffix)
84
+ .filter((e) => {
85
+ const lower = e.toLowerCase();
86
+ return lower.endsWith(suffix) && lower !== suffix;
87
+ })
46
88
  .map((e) => join(dir, e))
47
89
  .filter((p) => {
48
- if (suffix === ".spm") {
90
+ if (isDirSuffix) {
49
91
  try {
50
92
  return statSync(p).isDirectory();
51
93
  }
@@ -83,11 +125,20 @@ export const mutationOpts = z.object({
83
125
  .optional()
84
126
  .describe("sync to markdown directory after saving"),
85
127
  });
86
- /** Load a document from a CLI input path (auto-resolved if omitted). */
128
+ /**
129
+ * Load a document from a CLI input path (auto-resolved if omitted).
130
+ * @param input - Explicit document path, or undefined for auto-detection.
131
+ * @returns The loaded document with format and resolved path.
132
+ */
87
133
  export function loadDoc(input) {
88
134
  return loadDocument(resolveInput(input));
89
135
  }
90
- /** Persist a document and optionally sync to markdown. */
136
+ /**
137
+ * Persist a document and optionally sync to markdown.
138
+ * @param doc - The document to save.
139
+ * @param loaded - The original loaded document (provides format and path).
140
+ * @param opts - Mutation options (e.g. sync-to-markdown flag).
141
+ */
91
142
  export function persistDoc(doc, loaded, opts) {
92
143
  if (!opts.dryRun) {
93
144
  saveDocument(doc, loaded.format, loaded.path);
@@ -3,7 +3,6 @@
3
3
  *
4
4
  * A recursive, decision-driven model for recording where every part of a
5
5
  * system came from, what decisions shaped it, and how it reached its current form.
6
- *
7
6
  * @packageDocumentation
8
7
  */
9
8
  export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, RelationshipType, Text, Option, Operation, Task, ExternalReference, ExternalReferenceRole, Metadata, NODE_TYPE_LABELS, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, EXTERNAL_REFERENCE_ROLE_LABELS, EXTERNAL_REFERENCE_LABEL_TO_ROLE, NODE_STATUSES, NODE_FILE_MAP, NODE_ID_PREFIX, toJSONSchema, } from "./schema.js";
package/dist/src/index.js CHANGED
@@ -3,7 +3,6 @@
3
3
  *
4
4
  * A recursive, decision-driven model for recording where every part of a
5
5
  * system came from, what decisions shaped it, and how it reached its current form.
6
- *
7
6
  * @packageDocumentation
8
7
  */
9
8
  // Schema types and validators
package/dist/src/io.d.ts CHANGED
@@ -12,14 +12,12 @@ export interface LoadedDocument {
12
12
  }
13
13
  /**
14
14
  * Load a SysProM document from a file (JSON or Markdown).
15
- *
16
15
  * @param input - File path or directory to load from.
17
16
  * @returns The loaded document with its detected format and resolved path.
18
17
  */
19
18
  export declare function loadDocument(input: string): LoadedDocument;
20
19
  /**
21
20
  * Save a SysProM document to a file (JSON or Markdown).
22
- *
23
21
  * @param doc - The SysProM document to save.
24
22
  * @param format - Output format: 'json', 'single-md', or 'multi-md'.
25
23
  * @param path - Destination file path or directory.
package/dist/src/io.js CHANGED
@@ -14,7 +14,6 @@ function detectFormat(input) {
14
14
  }
15
15
  /**
16
16
  * Load a SysProM document from a file (JSON or Markdown).
17
- *
18
17
  * @param input - File path or directory to load from.
19
18
  * @returns The loaded document with its detected format and resolved path.
20
19
  */
@@ -46,7 +45,6 @@ export function loadDocument(input) {
46
45
  }
47
46
  /**
48
47
  * Save a SysProM document to a file (JSON or Markdown).
49
- *
50
48
  * @param doc - The SysProM document to save.
51
49
  * @param format - Output format: 'json', 'single-md', or 'multi-md'.
52
50
  * @param path - Destination file path or directory.
@@ -5,21 +5,18 @@ export interface ConvertOptions {
5
5
  }
6
6
  /**
7
7
  * Convert a SysProM document to a single Markdown string.
8
- *
9
8
  * @param doc - The SysProM document to convert.
10
9
  * @returns The Markdown representation.
11
10
  */
12
11
  export declare function jsonToMarkdownSingle(doc: SysProMDocument): string;
13
12
  /**
14
13
  * Convert a SysProM document to a multi-document Markdown folder.
15
- *
16
14
  * @param doc - The SysProM document to convert.
17
15
  * @param outDir - Output directory path.
18
16
  */
19
17
  export declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: string): void;
20
18
  /**
21
19
  * Convert a SysProM document to Markdown, writing to the specified output path.
22
- *
23
20
  * @param doc - The SysProM document to convert.
24
21
  * @param output - Output file or directory path.
25
22
  * @param options - Conversion options specifying single-file or multi-doc form.
@@ -360,7 +360,6 @@ function generateDocFile(doc, fileName, types, fromIdx) {
360
360
  }
361
361
  /**
362
362
  * Convert a SysProM document to a single Markdown string.
363
- *
364
363
  * @param doc - The SysProM document to convert.
365
364
  * @returns The Markdown representation.
366
365
  */
@@ -417,7 +416,6 @@ export function jsonToMarkdownSingle(doc) {
417
416
  }
418
417
  /**
419
418
  * Convert a SysProM document to a multi-document Markdown folder.
420
- *
421
419
  * @param doc - The SysProM document to convert.
422
420
  * @param outDir - Output directory path.
423
421
  */
@@ -483,7 +481,6 @@ export function jsonToMarkdownMultiDoc(doc, outDir) {
483
481
  }
484
482
  /**
485
483
  * Convert a SysProM document to Markdown, writing to the specified output path.
486
- *
487
484
  * @param doc - The SysProM document to convert.
488
485
  * @param output - Output file or directory path.
489
486
  * @param options - Conversion options specifying single-file or multi-doc form.
@@ -1,21 +1,18 @@
1
1
  import { type SysProMDocument } from "./schema.js";
2
2
  /**
3
3
  * Parse a single Markdown file into a SysProM document.
4
- *
5
4
  * @param content - The Markdown content to parse.
6
5
  * @returns The parsed SysProM document.
7
6
  */
8
7
  export declare function markdownSingleToJson(content: string): SysProMDocument;
9
8
  /**
10
9
  * Parse a multi-document Markdown folder into a SysProM document.
11
- *
12
10
  * @param dir - Path to the directory containing Markdown files.
13
11
  * @returns The parsed SysProM document.
14
12
  */
15
13
  export declare function markdownMultiDocToJson(dir: string): SysProMDocument;
16
14
  /**
17
15
  * Parse Markdown into a SysProM document, auto-detecting single-file or multi-doc format.
18
- *
19
16
  * @param input - File path or directory path to parse.
20
17
  * @returns The parsed SysProM document.
21
18
  */
@@ -428,7 +428,6 @@ function parseRelationshipTable(body) {
428
428
  // ---------------------------------------------------------------------------
429
429
  /**
430
430
  * Parse a single Markdown file into a SysProM document.
431
- *
432
431
  * @param content - The Markdown content to parse.
433
432
  * @returns The parsed SysProM document.
434
433
  */
@@ -460,7 +459,6 @@ export function markdownSingleToJson(content) {
460
459
  }
461
460
  /**
462
461
  * Parse a multi-document Markdown folder into a SysProM document.
463
- *
464
462
  * @param dir - Path to the directory containing Markdown files.
465
463
  * @returns The parsed SysProM document.
466
464
  */
@@ -536,7 +534,6 @@ export function markdownMultiDocToJson(dir) {
536
534
  }
537
535
  /**
538
536
  * Parse Markdown into a SysProM document, auto-detecting single-file or multi-doc format.
539
- *
540
537
  * @param input - File path or directory path to parse.
541
538
  * @returns The parsed SysProM document.
542
539
  */
@@ -1,8 +1,7 @@
1
1
  import * as z from "zod";
2
2
  /**
3
3
  * Add a node to a SysProM document. Returns a new document with the node appended.
4
- *
5
- * @throws If a node with the same ID already exists.
4
+ * @throws {Error} If a node with the same ID already exists.
6
5
  */
7
6
  export declare const addNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
8
7
  doc: z.ZodObject<{
@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
3
3
  import { SysProMDocument, Node } from "../schema.js";
4
4
  /**
5
5
  * Add a node to a SysProM document. Returns a new document with the node appended.
6
- *
7
- * @throws If a node with the same ID already exists.
6
+ * @throws {Error} If a node with the same ID already exists.
8
7
  */
9
8
  export const addNodeOp = defineOperation({
10
9
  name: "addNode",
@@ -1,8 +1,7 @@
1
1
  import * as z from "zod";
2
2
  /**
3
3
  * Append a new task to a change node's plan array. Returns a new document with the task added.
4
- *
5
- * @throws If the change node is not found.
4
+ * @throws {Error} If the change node is not found.
6
5
  */
7
6
  export declare const addPlanTaskOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
8
7
  doc: z.ZodObject<{
@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
3
3
  import { SysProMDocument } from "../schema.js";
4
4
  /**
5
5
  * Append a new task to a change node's plan array. Returns a new document with the task added.
6
- *
7
- * @throws If the change node is not found.
6
+ * @throws {Error} If the change node is not found.
8
7
  */
9
8
  export const addPlanTaskOp = defineOperation({
10
9
  name: "addPlanTask",
@@ -1,8 +1,7 @@
1
1
  import * as z from "zod";
2
2
  /**
3
3
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
4
- *
5
- * @throws If either endpoint node does not exist in the document.
4
+ * @throws {Error} If either endpoint node does not exist in the document.
6
5
  */
7
6
  export declare const addRelationshipOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
8
7
  doc: z.ZodObject<{
@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
3
3
  import { SysProMDocument, Relationship } from "../schema.js";
4
4
  /**
5
5
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
6
- *
7
- * @throws If either endpoint node does not exist in the document.
6
+ * @throws {Error} If either endpoint node does not exist in the document.
8
7
  */
9
8
  export const addRelationshipOp = defineOperation({
10
9
  name: "addRelationship",
@@ -2,9 +2,8 @@ import * as z from "zod";
2
2
  /**
3
3
  * Definition of a SysProM operation — a named, typed function with Zod schemas
4
4
  * for input validation and output description.
5
- *
6
- * @typeParam TInput - Zod schema type for the operation's input.
7
- * @typeParam TOutput - Zod schema type for the operation's output.
5
+ * @template TInput - Zod schema type for the operation's input.
6
+ * @template TOutput - Zod schema type for the operation's output.
8
7
  */
9
8
  export interface OperationDef<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> {
10
9
  /** Machine-readable operation name (e.g. `"addNode"`). */
@@ -22,9 +21,8 @@ export interface OperationDef<TInput extends z.ZodType = z.ZodType, TOutput exte
22
21
  * A callable operation with attached metadata. Can be invoked directly as a
23
22
  * function, and also exposes `.def`, `.inputSchema`, and `.outputSchema` for
24
23
  * introspection.
25
- *
26
- * @typeParam TInput - Zod schema type for the operation's input.
27
- * @typeParam TOutput - Zod schema type for the operation's output.
24
+ * @template TInput - Zod schema type for the operation's input.
25
+ * @template TOutput - Zod schema type for the operation's output.
28
26
  */
29
27
  export type DefinedOperation<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> = ((input: z.infer<TInput>) => z.infer<TOutput>) & {
30
28
  /** The full operation definition including name, description, and schemas. */
@@ -37,9 +35,8 @@ export type DefinedOperation<TInput extends z.ZodType = z.ZodType, TOutput exten
37
35
  /**
38
36
  * Create a callable operation from a definition. The returned function validates
39
37
  * input against the Zod schema before delegating to the implementation.
40
- *
41
38
  * @param def - The operation definition with name, schemas, and implementation.
42
39
  * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
43
- * @throws If the input fails Zod validation.
40
+ * @throws {Error} If the input fails Zod validation.
44
41
  */
45
42
  export declare function defineOperation<TInput extends z.ZodType, TOutput extends z.ZodType>(def: OperationDef<TInput, TOutput>): DefinedOperation<TInput, TOutput>;
@@ -4,10 +4,9 @@
4
4
  /**
5
5
  * Create a callable operation from a definition. The returned function validates
6
6
  * input against the Zod schema before delegating to the implementation.
7
- *
8
7
  * @param def - The operation definition with name, schemas, and implementation.
9
8
  * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
10
- * @throws If the input fails Zod validation.
9
+ * @throws {Error} If the input fails Zod validation.
11
10
  */
12
11
  export function defineOperation(def) {
13
12
  function execute(input) {
@@ -1,8 +1,7 @@
1
1
  import * as z from "zod";
2
2
  /**
3
3
  * Mark a task as done within a change node's plan.
4
- *
5
- * @throws If the change node is not found or the task index is out of range.
4
+ * @throws {Error} If the change node is not found or the task index is out of range.
6
5
  */
7
6
  export declare const markTaskDoneOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
8
7
  doc: z.ZodObject<{
@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
3
3
  import { SysProMDocument } from "../schema.js";
4
4
  /**
5
5
  * Mark a task as done within a change node's plan.
6
- *
7
- * @throws If the change node is not found or the task index is out of range.
6
+ * @throws {Error} If the change node is not found or the task index is out of range.
8
7
  */
9
8
  export const markTaskDoneOp = defineOperation({
10
9
  name: "markTaskDone",
@@ -1,8 +1,7 @@
1
1
  import * as z from "zod";
2
2
  /**
3
3
  * Mark a task as undone (incomplete) within a change node's plan.
4
- *
5
- * @throws If the change node is not found or the task index is out of range.
4
+ * @throws {Error} If the change node is not found or the task index is out of range.
6
5
  */
7
6
  export declare const markTaskUndoneOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
8
7
  doc: z.ZodObject<{
@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
3
3
  import { SysProMDocument } from "../schema.js";
4
4
  /**
5
5
  * Mark a task as undone (incomplete) within a change node's plan.
6
- *
7
- * @throws If the change node is not found or the task index is out of range.
6
+ * @throws {Error} If the change node is not found or the task index is out of range.
8
7
  */
9
8
  export const markTaskUndoneOp = defineOperation({
10
9
  name: "markTaskUndone",
@@ -2,8 +2,7 @@ import * as z from "zod";
2
2
  /**
3
3
  * Generate the next available ID for a given node type. Scans existing node IDs
4
4
  * matching the type's conventional prefix and returns `prefix + (max + 1)`.
5
- *
6
- * @throws If no ID prefix is defined for the given node type.
5
+ * @throws {Error} If no ID prefix is defined for the given node type.
7
6
  */
8
7
  export declare const nextIdOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
9
8
  doc: z.ZodObject<{
@@ -4,8 +4,7 @@ import { SysProMDocument, NodeType, NODE_ID_PREFIX } from "../schema.js";
4
4
  /**
5
5
  * Generate the next available ID for a given node type. Scans existing node IDs
6
6
  * matching the type's conventional prefix and returns `prefix + (max + 1)`.
7
- *
8
- * @throws If no ID prefix is defined for the given node type.
7
+ * @throws {Error} If no ID prefix is defined for the given node type.
9
8
  */
10
9
  export const nextIdOp = defineOperation({
11
10
  name: "nextId",
@@ -303,8 +303,7 @@ export type RemoveResult = z.infer<typeof RemoveResult>;
303
303
  /**
304
304
  * Remove a node and all relationships involving it. Also removes the node from
305
305
  * view includes and external references. Warns if scope or operation references remain.
306
- *
307
- * @throws If the node ID is not found.
306
+ * @throws {Error} If the node ID is not found.
308
307
  */
309
308
  export declare const removeNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
310
309
  doc: z.ZodObject<{
@@ -9,8 +9,7 @@ export const RemoveResult = z.object({
9
9
  /**
10
10
  * Remove a node and all relationships involving it. Also removes the node from
11
11
  * view includes and external references. Warns if scope or operation references remain.
12
- *
13
- * @throws If the node ID is not found.
12
+ * @throws {Error} If the node ID is not found.
14
13
  */
15
14
  export const removeNodeOp = defineOperation({
16
15
  name: "removeNode",
@@ -1,8 +1,7 @@
1
1
  import * as z from "zod";
2
2
  /**
3
3
  * Remove a relationship matching from, type, and to. Returns a new document without it.
4
- *
5
- * @throws If no matching relationship is found.
4
+ * @throws {Error} If no matching relationship is found.
6
5
  */
7
6
  export declare const removeRelationshipOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
8
7
  doc: z.ZodObject<{
@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
3
3
  import { SysProMDocument, RelationshipType } from "../schema.js";
4
4
  /**
5
5
  * Remove a relationship matching from, type, and to. Returns a new document without it.
6
- *
7
- * @throws If no matching relationship is found.
6
+ * @throws {Error} If no matching relationship is found.
8
7
  */
9
8
  export const removeRelationshipOp = defineOperation({
10
9
  name: "removeRelationship",
@@ -3,8 +3,7 @@ import * as z from "zod";
3
3
  * Rename a node ID across all references in the document — the node itself,
4
4
  * relationships, scope, includes, operation targets, external references, and
5
5
  * recursively into subsystems.
6
- *
7
- * @throws If the old ID is not found or the new ID already exists.
6
+ * @throws {Error} If the old ID is not found or the new ID already exists.
8
7
  */
9
8
  export declare const renameOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
10
9
  doc: z.ZodObject<{