sysprom 1.0.0 → 1.0.5

package/dist/src/cli/commands/add.js

@@ -0,0 +1,95 @@
+import * as z from "zod";
+import { NodeType, NodeStatus } from "../../schema.js";
+import { addNodeOp, nextIdOp } from "../../operations/index.js";
+import { inputArg, mutationOpts, loadDoc, persistDoc } from "../shared.js";
+const argsSchema = z.object({
+    input: inputArg,
+    nodeType: z.string().describe("Node type to add"),
+});
+const optsSchema = mutationOpts.extend({
+    id: z.string().optional().describe("Node ID (auto-generated if omitted)"),
+    name: z.string().describe("Human-readable node name"),
+    description: z.string().optional().describe("Node description"),
+    status: z.string().optional().describe("Lifecycle status"),
+    context: z.string().optional().describe("Decision context"),
+    rationale: z.string().optional().describe("Decision rationale"),
+    scope: z.array(z.string()).optional().describe("Change scope (repeatable)"),
+    selected: z.string().optional().describe("Selected option ID"),
+    option: z
+        .array(z.string())
+        .optional()
+        .describe("Option in format 'ID:description' or just 'description' (repeatable)"),
+});
+export const addCommand = {
+    name: "add",
+    description: addNodeOp.def.description,
+    apiLink: addNodeOp.def.name,
+    args: argsSchema,
+    opts: optsSchema,
+    action(args, opts) {
+        if (!opts.name) {
+            console.error("--name is required.");
+            process.exit(1);
+        }
+        const loaded = loadDoc(args.input);
+        const { doc } = loaded;
+        const type = args.nodeType;
+        if (!NodeType.is(type)) {
+            console.error(`Unknown node type: ${type}`);
+            process.exit(1);
+        }
+        const id = opts.id ?? nextIdOp({ doc, type });
+        // Build the node from CLI options
+        const node = { id, type, name: opts.name };
+        if (opts.description) {
+            node.description = opts.description;
+        }
+        if (opts.status) {
+            if (!NodeStatus.is(opts.status)) {
+                console.error(`Unknown status: ${opts.status}`);
+                process.exit(1);
+            }
+            node.status = opts.status;
+        }
+        if (opts.context) {
+            node.context = opts.context;
+        }
+        if (opts.rationale) {
+            node.rationale = opts.rationale;
+        }
+        if (opts.scope && opts.scope.length > 0) {
+            node.scope = opts.scope;
+        }
+        if (opts.selected) {
+            node.selected = opts.selected;
+        }
+        if (opts.option && opts.option.length > 0) {
+            node.options = opts.option.map((arg, i) => {
+                const colonIdx = arg.indexOf(":");
+                if (colonIdx >= 0) {
+                    return {
+                        id: arg.slice(0, colonIdx),
+                        description: arg.slice(colonIdx + 1),
+                    };
+                }
+                // Auto-generate ID: D26-OPT-A, D26-OPT-B, etc.
+                const letter = String.fromCharCode(65 + i); // A, B, C, ...
+                return { id: `${id}-OPT-${letter}`, description: arg };
+            });
+        }
+        try {
+            const newDoc = addNodeOp({ doc, node });
+            persistDoc(newDoc, loaded, opts);
+            if (opts.json) {
+                console.log(JSON.stringify(node, null, 2));
+            }
+            else {
+                console.log(`${opts.dryRun ? "[dry-run] Would add" : "Added"} ${type} ${id} — ${opts.name}`);
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};

package/dist/src/cli/commands/check.d.ts

@@ -0,0 +1,10 @@
+import * as z from "zod";
+import type { CommandDef } from "../define-command.js";
+declare const argsSchema: z.ZodObject<{
+    input: z.ZodString;
+}, z.core.$strip>;
+declare const optsSchema: z.ZodObject<{
+    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const checkCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export {};

package/dist/src/cli/commands/check.js

@@ -0,0 +1,33 @@
+import * as z from "zod";
+import { checkOp } from "../../operations/index.js";
+import { inputArg, readOpts, loadDoc } from "../shared.js";
+const argsSchema = z.object({
+    input: inputArg,
+});
+const optsSchema = readOpts;
+export const checkCommand = {
+    name: "check",
+    description: checkOp.def.description,
+    apiLink: checkOp.def.name,
+    args: argsSchema,
+    opts: optsSchema,
+    action(args, opts) {
+        const { doc } = loadDoc(args.input);
+        const result = checkOp({ doc });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            if (result.warnings.length === 0 && result.info.length === 0) {
+                console.log("No issues found.");
+            }
+            else {
+                for (const w of result.warnings)
+                    console.log(`⚠ ${w}`);
+                for (const i of result.info)
+                    console.log(`ℹ ${i}`);
+                console.log(`\n${String(result.warnings.length)} warning(s), ${String(result.info.length)} info`);
+            }
+        }
+    },
+};

package/dist/src/cli/commands/graph.d.ts

@@ -0,0 +1,15 @@
+import * as z from "zod";
+import type { CommandDef } from "../define-command.js";
+declare const argsSchema: z.ZodObject<{
+    input: z.ZodString;
+}, z.core.$strip>;
+declare const optsSchema: z.ZodObject<{
+    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    format: z.ZodOptional<z.ZodEnum<{
+        dot: "dot";
+        mermaid: "mermaid";
+    }>>;
+    type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const graphCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export {};

package/dist/src/cli/commands/graph.js

@@ -0,0 +1,32 @@
+import * as z from "zod";
+import { graphOp } from "../../operations/index.js";
+import { inputArg, readOpts, loadDoc } from "../shared.js";
+const argsSchema = z.object({
+    input: inputArg,
+});
+const optsSchema = readOpts.extend({
+    format: z.enum(["mermaid", "dot"]).optional().describe("Output format"),
+    type: z.string().optional().describe("Filter by relationship type"),
+});
+export const graphCommand = {
+    name: "graph",
+    description: graphOp.def.description,
+    apiLink: graphOp.def.name,
+    args: argsSchema,
+    opts: optsSchema,
+    action(args, opts) {
+        try {
+            const { doc } = loadDoc(args.input);
+            const output = graphOp({
+                doc,
+                format: opts.format ?? "mermaid",
+                typeFilter: opts.type,
+            });
+            console.log(output);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};

package/dist/src/cli/commands/init.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDef } from "../define-command.js";
+export declare const initCommand: CommandDef;

package/dist/src/cli/commands/init.js

@@ -0,0 +1,44 @@
+import * as z from "zod";
+import { writeFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { canonicalise } from "../../canonical-json.js";
+import { initDocumentOp } from "../../operations/index.js";
+function isArgs(arg) {
+    return typeof arg === "object" && arg !== null && "output" in arg;
+}
+function isOpts(opt) {
+    return typeof opt === "object" && opt !== null;
+}
+export const initCommand = {
+    name: "init",
+    description: initDocumentOp.def.description,
+    apiLink: initDocumentOp.def.name,
+    args: z.object({
+        output: z.string().describe("Output file path"),
+    }),
+    opts: z
+        .object({
+        title: z.string().optional().describe("Document title"),
+        scope: z.string().optional().describe("Document scope"),
+    })
+        .strict(),
+    action(args, opts) {
+        if (!isArgs(args))
+            throw new Error("Invalid args");
+        if (!isOpts(opts))
+            throw new Error("Invalid opts");
+        const typedArgs = args;
+        const typedOpts = opts;
+        const outputPath = resolve(typedArgs.output);
+        if (existsSync(outputPath)) {
+            console.error(`File already exists: ${outputPath}`);
+            process.exit(1);
+        }
+        const doc = initDocumentOp({
+            title: typedOpts.title ?? "Untitled",
+            scope: typedOpts.scope ?? "system",
+        });
+        writeFileSync(outputPath, canonicalise(doc, { indent: "\t" }) + "\n");
+        console.log(`Created ${outputPath}`);
+    },
+};

package/dist/src/cli/commands/json2md.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDef } from "../define-command.js";
+export declare const json2mdCommand: CommandDef;

package/dist/src/cli/commands/json2md.js

@@ -0,0 +1,60 @@
+import * as z from "zod";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { SysProMDocument } from "../../schema.js";
+import { jsonToMarkdown } from "../../json-to-md.js";
+import { jsonToMarkdownOp } from "../../operations/index.js";
+function isArgs(arg) {
+    return (typeof arg === "object" && arg !== null && "input" in arg && "output" in arg);
+}
+function isOpts(opt) {
+    return typeof opt === "object" && opt !== null;
+}
+export const json2mdCommand = {
+    name: "json2md",
+    description: jsonToMarkdownOp.def.description,
+    apiLink: jsonToMarkdownOp.def.name,
+    args: z.object({
+        input: z.string().describe("Path to SysProM JSON file"),
+        output: z.string().describe("Output path (file or directory)"),
+    }),
+    opts: z
+        .object({
+        singleFile: z
+            .boolean()
+            .optional()
+            .describe("Force single-file output format"),
+    })
+        .strict(),
+    action(args, opts) {
+        if (!isArgs(args))
+            throw new Error("Invalid args");
+        if (!isOpts(opts))
+            throw new Error("Invalid opts");
+        const typedArgs = args;
+        const typedOpts = opts;
+        const inputPath = resolve(typedArgs.input);
+        const outputPath = resolve(typedArgs.output);
+        const raw = JSON.parse(readFileSync(inputPath, "utf8"));
+        if (!SysProMDocument.is(raw)) {
+            const result = SysProMDocument.safeParse(raw);
+            if (!result.success) {
+                console.error("Input is not a valid SysProM document:");
+                for (const issue of result.error.issues) {
+                    console.error(`  ${issue.path.join(".")}: ${issue.message}`);
+                }
+            }
+            process.exit(1);
+        }
+        const form = typedOpts.singleFile || outputPath.endsWith(".md")
+            ? "single-file"
+            : "multi-doc";
+        jsonToMarkdown(raw, outputPath, { form });
+        if (form === "single-file") {
+            console.log(`Written to ${outputPath}`);
+        }
+        else {
+            console.log(`Written to ${outputPath}/`);
+        }
+    },
+};

package/dist/src/cli/commands/md2json.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDef } from "../define-command.js";
+export declare const md2jsonCommand: CommandDef;

package/dist/src/cli/commands/md2json.js

@@ -0,0 +1,29 @@
+import * as z from "zod";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { markdownToJson } from "../../md-to-json.js";
+import { canonicalise } from "../../canonical-json.js";
+import { markdownToJsonOp } from "../../operations/index.js";
+function isArgs(arg) {
+    return (typeof arg === "object" && arg !== null && "input" in arg && "output" in arg);
+}
+export const md2jsonCommand = {
+    name: "md2json",
+    description: markdownToJsonOp.def.description,
+    apiLink: markdownToJsonOp.def.name,
+    args: z.object({
+        input: z.string().describe("Path to SysProM Markdown (file or directory)"),
+        output: z.string().describe("Output JSON file path"),
+    }),
+    opts: z.object({}).strict(),
+    action(args) {
+        if (!isArgs(args))
+            throw new Error("Invalid args");
+        const typedArgs = args;
+        const inputPath = resolve(typedArgs.input);
+        const outputPath = resolve(typedArgs.output);
+        const doc = markdownToJson(inputPath);
+        writeFileSync(outputPath, canonicalise(doc, { indent: "\t" }) + "\n");
+        console.log(`Written to ${outputPath}`);
+    },
+};

package/dist/src/cli/commands/plan.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDef } from "../define-command.js";
+export declare const planCommand: CommandDef;

package/dist/src/cli/commands/plan.js

@@ -0,0 +1,227 @@
+import * as z from "zod";
+import { existsSync } from "node:fs";
+import { loadDocument, saveDocument } from "../../io.js";
+import { planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, } from "../../operations/index.js";
+// ============================================================================
+// Subcommands
+// ============================================================================
+const initArgs = z.object({
+    output: z.string().describe("Path to output SysProM file"),
+});
+const initOpts = z.object({
+    prefix: z.string().describe("Plan prefix (e.g. PLAN)"),
+    name: z.string().optional().describe("Plan name (defaults to prefix)"),
+});
+const initSubcommand = {
+    name: "init",
+    description: planInitOp.def.description,
+    apiLink: planInitOp.def.name,
+    args: initArgs,
+    opts: initOpts,
+    action(args, opts) {
+        const outputPath = args.output;
+        const prefix = opts.prefix;
+        const name = opts.name ?? prefix;
+        if (existsSync(outputPath)) {
+            console.error(`Output file already exists: ${outputPath}`);
+            process.exit(1);
+        }
+        try {
+            const doc = planInitOp({ prefix, name });
+            saveDocument(doc, "json", outputPath);
+            console.log(`Created ${outputPath} with prefix ${prefix}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const addTaskArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+});
+const addTaskOpts = z.object({
+    prefix: z.string().describe("Plan prefix"),
+    name: z.string().optional().describe("Task name"),
+    parent: z.string().optional().describe("Parent task ID"),
+});
+const addTaskSubcommand = {
+    name: "add-task",
+    description: planAddTaskOp.def.description,
+    apiLink: planAddTaskOp.def.name,
+    args: addTaskArgs,
+    opts: addTaskOpts,
+    action(args, opts) {
+        const inputPath = args.input;
+        const prefix = opts.prefix;
+        const name = opts.name;
+        const parentId = opts.parent;
+        try {
+            const { doc, format, path } = loadDocument(inputPath);
+            const newDoc = planAddTaskOp({ doc, prefix, name, parent: parentId });
+            saveDocument(newDoc, format, path);
+            const target = parentId ? `to ${parentId}` : `to ${prefix}-PROT-IMPL`;
+            console.log(`Added task ${target}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const statusArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+});
+const statusOpts = z.object({
+    prefix: z.string().describe("Plan prefix"),
+    json: z.boolean().optional().describe("Output as JSON"),
+});
+const statusSubcommand = {
+    name: "status",
+    description: planStatusOp.def.description,
+    apiLink: planStatusOp.def.name,
+    args: statusArgs,
+    opts: statusOpts,
+    action(args, opts) {
+        const inputPath = args.input;
+        const prefix = opts.prefix;
+        const asJson = opts.json === true;
+        try {
+            const { doc } = loadDocument(inputPath);
+            const status = planStatusOp({ doc, prefix });
+            if (asJson) {
+                console.log(JSON.stringify(status, null, 2));
+                return;
+            }
+            // Format: Constitution, Spec, Plan, Tasks, Checklist status report
+            const formatBoolean = (defined) => defined ? "✅ defined" : "❌ not defined";
+            console.log(`Constitution: ${formatBoolean(status.constitution.defined)} (${String(status.constitution.principleCount)} principles)`);
+            console.log(`Spec:         ${formatBoolean(status.spec.defined)} (${String(status.spec.userStoryCount)} user stories)`);
+            console.log(`Plan:         ${formatBoolean(status.plan.defined)} (${String(status.plan.phaseCount)} phases)`);
+            console.log(`Tasks:        ${String(status.tasks.done)}/${String(status.tasks.total)} done`);
+            console.log(`Checklist:    ${formatBoolean(status.checklist.defined)} (${String(status.checklist.done)}/${String(status.checklist.total)})`);
+            console.log();
+            console.log(`Next: ${status.nextStep}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const progressArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+});
+const progressOpts = z.object({
+    prefix: z.string().describe("Plan prefix"),
+    json: z.boolean().optional().describe("Output as JSON"),
+});
+const progressSubcommand = {
+    name: "progress",
+    description: planProgressOp.def.description,
+    apiLink: planProgressOp.def.name,
+    args: progressArgs,
+    opts: progressOpts,
+    action(args, opts) {
+        const inputPath = args.input;
+        const prefix = opts.prefix;
+        const asJson = opts.json === true;
+        try {
+            const { doc } = loadDocument(inputPath);
+            const progress = planProgressOp({ doc, prefix });
+            if (asJson) {
+                console.log(JSON.stringify(progress, null, 2));
+                return;
+            }
+            // Format: ASCII progress bars
+            // Bar width: 10 chars. Filled: █, empty: ░. Name padded to 20 chars. Percent right-aligned to 3 chars.
+            for (const phase of progress) {
+                const filledCount = Math.round((phase.percent / 100) * 10);
+                const emptyCount = 10 - filledCount;
+                const bar = "█".repeat(filledCount) + "░".repeat(emptyCount);
+                const name = phase.name.padEnd(20);
+                const percent = String(phase.percent).padStart(3);
+                const ratio = `(${String(phase.done)}/${String(phase.total)})`;
+                console.log(`${name} [${bar}] ${percent}% ${ratio}`);
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const gateArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+});
+const gateOpts = z.object({
+    prefix: z.string().describe("Plan prefix"),
+    phase: z.string().describe("Phase number"),
+    json: z.boolean().optional().describe("Output as JSON"),
+});
+const gateSubcommand = {
+    name: "gate",
+    description: planGateOp.def.description,
+    apiLink: planGateOp.def.name,
+    args: gateArgs,
+    opts: gateOpts,
+    action(args, opts) {
+        const inputPath = args.input;
+        const prefix = opts.prefix;
+        const phaseNum = parseInt(opts.phase, 10);
+        const asJson = opts.json === true;
+        if (isNaN(phaseNum) || phaseNum < 1) {
+            console.error(`Invalid phase number: ${opts.phase}`);
+            process.exit(1);
+        }
+        try {
+            const { doc } = loadDocument(inputPath);
+            const result = planGateOp({ doc, prefix, phase: phaseNum });
+            if (asJson) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            // Format: Gate check result with detailed issues
+            if (result.ready) {
+                console.log(`Gate check for phase ${String(phaseNum)}: ✅ READY`);
+            }
+            else {
+                console.log(`Gate check for phase ${String(phaseNum)}: ❌ NOT READY`);
+                for (const issue of result.issues) {
+                    switch (issue.kind) {
+                        case "previous_tasks_incomplete":
+                            console.log(`  ❌ Phase ${String(issue.phase)} has ${String(issue.remaining)} incomplete tasks`);
+                            break;
+                        case "user_story_no_change":
+                            console.log(`  ❌ ${issue.storyId} has no implementing change`);
+                            break;
+                        case "user_story_no_acceptance_criteria":
+                            console.log(`  ❌ ${issue.storyId} has no acceptance criteria`);
+                            break;
+                        case "fr_no_change":
+                            console.log(`  ❌ ${issue.frId} has no implementing change`);
+                            break;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+// ============================================================================
+// Main command
+// ============================================================================
+export const planCommand = {
+    name: "plan",
+    description: "Manage project plans and phase gates",
+    subcommands: [
+        initSubcommand,
+        addTaskSubcommand,
+        statusSubcommand,
+        progressSubcommand,
+        gateSubcommand,
+    ],
+};

package/dist/src/cli/commands/query.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDef } from "../define-command.js";
+export declare const queryCommand: CommandDef;