sysprom 1.0.0 → 1.0.6

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

@@ -0,0 +1,318 @@
+import * as z from "zod";
+import { resolve, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { loadDocument, saveDocument } from "../../io.js";
+import { parseSpecKitFeature } from "../../speckit/parse.js";
+import { generateSpecKitProject } from "../../speckit/generate.js";
+import { detectSpecKitProject } from "../../speckit/project.js";
+import { speckitImportOp, speckitExportOp, speckitSyncOp, speckitDiffOp, } from "../../operations/index.js";
+// ============================================================================
+// Helper: Format detection
+// ============================================================================
+function detectFormat(outputPath) {
+    if (outputPath.endsWith(".json") || outputPath.endsWith(".spm.json")) {
+        return "json";
+    }
+    if (outputPath.endsWith(".md") || outputPath.endsWith(".spm.md")) {
+        return "single-md";
+    }
+    return "json"; // default
+}
+function compareDocuments(oldDoc, newDoc) {
+    const oldNodes = new Map(oldDoc.nodes.map((n) => [n.id, n]));
+    const newNodes = new Map(newDoc.nodes.map((n) => [n.id, n]));
+    const added = [];
+    const modified = [];
+    const removed = [];
+    // Find added and modified
+    for (const [id, newNode] of newNodes) {
+        const oldNode = oldNodes.get(id);
+        if (!oldNode) {
+            added.push(newNode);
+        }
+        else if (JSON.stringify(oldNode) !== JSON.stringify(newNode)) {
+            modified.push({ old: oldNode, new: newNode });
+        }
+    }
+    // Find removed
+    for (const [id, oldNode] of oldNodes) {
+        if (!newNodes.has(id)) {
+            removed.push(oldNode);
+        }
+    }
+    return { added, modified, removed };
+}
+// ============================================================================
+// Subcommands
+// ============================================================================
+const importArgs = z.object({
+    speckitDir: z.string().describe("Path to Spec-Kit feature directory"),
+    output: z.string().describe("Path to output SysProM file"),
+});
+const importOpts = z.object({
+    prefix: z
+        .string()
+        .optional()
+        .describe("ID prefix (defaults to directory name)"),
+});
+const importSubcommand = {
+    name: "import",
+    description: speckitImportOp.def.description,
+    args: importArgs,
+    opts: importOpts,
+    action(args, opts) {
+        const specKitDir = resolve(args.speckitDir);
+        const outputPath = resolve(args.output);
+        if (!existsSync(specKitDir)) {
+            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
+            process.exit(1);
+        }
+        // Determine the prefix: use flag if provided, otherwise use directory name
+        const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
+        // Find constitution file by detecting the project from parent directories
+        let constitutionPath;
+        let searchDir = dirname(specKitDir);
+        for (let i = 0; i < 5; i++) {
+            // Search up to 5 levels
+            const project = detectSpecKitProject(searchDir);
+            if (project.constitutionPath) {
+                constitutionPath = project.constitutionPath;
+                break;
+            }
+            const parent = dirname(searchDir);
+            if (parent === searchDir)
+                break; // reached root
+            searchDir = parent;
+        }
+        // Parse Spec-Kit feature
+        const doc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
+        // Determine output format
+        const format = detectFormat(outputPath);
+        // Save document
+        saveDocument(doc, format, outputPath);
+        // Print summary
+        const nodeCount = doc.nodes.length;
+        const relationshipCount = doc.relationships?.length ?? 0;
+        console.log(`Imported Spec-Kit from ${specKitDir} to ${outputPath}`);
+        console.log(`  ${String(nodeCount)} nodes, ${String(relationshipCount)} relationships`);
+    },
+};
+const exportArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+    speckitDir: z.string().describe("Path to Spec-Kit output directory"),
+});
+const exportOpts = z.object({
+    prefix: z.string().describe("ID prefix identifying nodes to export"),
+});
+const exportSubcommand = {
+    name: "export",
+    description: speckitExportOp.def.description,
+    args: exportArgs,
+    opts: exportOpts,
+    action(args, opts) {
+        const inputPath = resolve(args.input);
+        const specKitDir = resolve(args.speckitDir);
+        if (!opts.prefix) {
+            console.error("Error: --prefix flag is required for export (identifies which nodes to export)");
+            process.exit(1);
+        }
+        // Load SysProM document
+        const { doc } = loadDocument(inputPath);
+        // Generate Spec-Kit project
+        generateSpecKitProject(doc, specKitDir, opts.prefix);
+        // Print summary
+        console.log(`Exported SysProM document from ${inputPath} to ${specKitDir}`);
+        console.log(`  Generated Spec-Kit files with prefix: ${opts.prefix}`);
+    },
+};
+const syncArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+    speckitDir: z.string().describe("Path to Spec-Kit directory"),
+});
+const syncOpts = z.object({
+    prefix: z
+        .string()
+        .optional()
+        .describe("ID prefix (defaults to directory name)"),
+});
+const syncSubcommand = {
+    name: "sync",
+    description: speckitSyncOp.def.description,
+    args: syncArgs,
+    opts: syncOpts,
+    action(args, opts) {
+        const inputPath = resolve(args.input);
+        const specKitDir = resolve(args.speckitDir);
+        if (!existsSync(inputPath)) {
+            console.error(`Error: Input file does not exist: ${inputPath}`);
+            process.exit(1);
+        }
+        if (!existsSync(specKitDir)) {
+            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
+            process.exit(1);
+        }
+        // Determine the prefix: use flag if provided, otherwise use directory name
+        const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
+        // Load SysProM document
+        const { doc: syspromDoc, format } = loadDocument(inputPath);
+        // Find constitution file
+        let constitutionPath;
+        let searchDir = dirname(specKitDir);
+        for (let i = 0; i < 5; i++) {
+            const project = detectSpecKitProject(searchDir);
+            if (project.constitutionPath) {
+                constitutionPath = project.constitutionPath;
+                break;
+            }
+            const parent = dirname(searchDir);
+            if (parent === searchDir)
+                break;
+            searchDir = parent;
+        }
+        // Parse Spec-Kit feature
+        const specKitDoc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
+        // Compare documents
+        const diff = compareDocuments(syspromDoc, specKitDoc);
+        // Merge: Spec-Kit wins for content (description, status), SysProM wins for structure
+        const mergedNodes = new Map(syspromDoc.nodes.map((n) => [n.id, n]));
+        const specKitNodes = new Map(specKitDoc.nodes.map((n) => [n.id, n]));
+        for (const [id, specKitNode] of specKitNodes) {
+            const syspromNode = mergedNodes.get(id);
+            if (!syspromNode) {
+                // Add new node from Spec-Kit
+                mergedNodes.set(id, specKitNode);
+            }
+            else {
+                // Merge: Spec-Kit content wins, SysProM structure wins
+                const merged = {
+                    ...syspromNode,
+                    description: specKitNode.description ?? syspromNode.description,
+                    status: specKitNode.status ?? syspromNode.status,
+                    context: specKitNode.context ?? syspromNode.context,
+                    options: specKitNode.options ?? syspromNode.options,
+                    selected: specKitNode.selected ?? syspromNode.selected,
+                    rationale: specKitNode.rationale ?? syspromNode.rationale,
+                    scope: specKitNode.scope ?? syspromNode.scope,
+                    operations: specKitNode.operations ?? syspromNode.operations,
+                    plan: specKitNode.plan ?? syspromNode.plan,
+                };
+                mergedNodes.set(id, merged);
+            }
+        }
+        // Remove nodes that were deleted in Spec-Kit
+        for (const node of diff.removed) {
+            mergedNodes.delete(node.id);
+        }
+        // Update merged document
+        const mergedDoc = {
+            ...syspromDoc,
+            nodes: Array.from(mergedNodes.values()),
+            relationships: syspromDoc.relationships, // Keep original relationships
+        };
+        // Save updated SysProM document
+        saveDocument(mergedDoc, format, inputPath);
+        // Re-generate Spec-Kit files from merged document
+        generateSpecKitProject(mergedDoc, specKitDir, idPrefix);
+        // Print what changed
+        console.log(`Synced SysProM document with Spec-Kit directory`);
+        if (diff.added.length > 0) {
+            console.log(`  Added: ${String(diff.added.length)} node(s)`);
+        }
+        if (diff.modified.length > 0) {
+            console.log(`  Modified: ${String(diff.modified.length)} node(s)`);
+        }
+        if (diff.removed.length > 0) {
+            console.log(`  Removed: ${String(diff.removed.length)} node(s)`);
+        }
+    },
+};
+const diffArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+    speckitDir: z.string().describe("Path to Spec-Kit directory"),
+});
+const diffOpts = z.object({
+    prefix: z
+        .string()
+        .optional()
+        .describe("ID prefix (defaults to directory name)"),
+});
+const diffSubcommand = {
+    name: "diff",
+    description: speckitDiffOp.def.description,
+    args: diffArgs,
+    opts: diffOpts,
+    action(args, opts) {
+        const inputPath = resolve(args.input);
+        const specKitDir = resolve(args.speckitDir);
+        if (!existsSync(inputPath)) {
+            console.error(`Error: Input file does not exist: ${inputPath}`);
+            process.exit(1);
+        }
+        if (!existsSync(specKitDir)) {
+            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
+            process.exit(1);
+        }
+        // Determine the prefix: use flag if provided, otherwise use directory name
+        const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
+        // Load SysProM document
+        const { doc: syspromDoc } = loadDocument(inputPath);
+        // Find constitution file
+        let constitutionPath;
+        let searchDir = dirname(specKitDir);
+        for (let i = 0; i < 5; i++) {
+            const project = detectSpecKitProject(searchDir);
+            if (project.constitutionPath) {
+                constitutionPath = project.constitutionPath;
+                break;
+            }
+            const parent = dirname(searchDir);
+            if (parent === searchDir)
+                break;
+            searchDir = parent;
+        }
+        // Parse Spec-Kit feature
+        const specKitDoc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
+        // Compare documents
+        const diff = compareDocuments(syspromDoc, specKitDoc);
+        // Print what would change (read-only)
+        console.log(`Diff between SysProM document and Spec-Kit directory:`);
+        if (diff.added.length === 0 &&
+            diff.modified.length === 0 &&
+            diff.removed.length === 0) {
+            console.log(`  (no changes)`);
+        }
+        else {
+            if (diff.added.length > 0) {
+                console.log(`  Added: ${String(diff.added.length)} node(s)`);
+                for (const node of diff.added) {
+                    console.log(`    - ${node.id}: ${node.name}`);
+                }
+            }
+            if (diff.modified.length > 0) {
+                console.log(`  Modified: ${String(diff.modified.length)} node(s)`);
+                for (const { old } of diff.modified) {
+                    console.log(`    - ${old.id}: ${old.name}`);
+                }
+            }
+            if (diff.removed.length > 0) {
+                console.log(`  Removed: ${String(diff.removed.length)} node(s)`);
+                for (const node of diff.removed) {
+                    console.log(`    - ${node.id}: ${node.name}`);
+                }
+            }
+        }
+    },
+};
+// ============================================================================
+// Main command
+// ============================================================================
+export const speckitCommand = {
+    name: "speckit",
+    description: "Spec-Kit interoperability — import, export, sync, and diff",
+    subcommands: [
+        importSubcommand,
+        exportSubcommand,
+        syncSubcommand,
+        diffSubcommand,
+    ],
+};

package/dist/src/cli/commands/stats.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 statsCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export {};

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

@@ -0,0 +1,51 @@
+import * as z from "zod";
+import pc from "picocolors";
+import { statsOp } from "../../operations/index.js";
+import { inputArg, readOpts, loadDoc } from "../shared.js";
+const argsSchema = z.object({
+    input: inputArg,
+});
+const optsSchema = readOpts;
+export const statsCommand = {
+    name: "stats",
+    description: statsOp.def.description,
+    apiLink: statsOp.def.name,
+    args: argsSchema,
+    opts: optsSchema,
+    action(args) {
+        const { doc } = loadDoc(args.input);
+        const s = statsOp({ doc });
+        console.log(`${pc.bold("SysProM Document")}: ${s.title}`);
+        console.log("");
+        console.log(pc.bold("Nodes by type:"));
+        for (const [type, count] of Object.entries(s.nodesByType).sort()) {
+            console.log(`  ${type.padEnd(20)} ${pc.cyan(String(count))}`);
+        }
+        console.log(`  ${"TOTAL".padEnd(20)} ${pc.cyan(String(s.totalNodes))}`);
+        console.log("");
+        console.log(pc.bold("Relationships by type:"));
+        for (const [type, count] of Object.entries(s.relationshipsByType).sort()) {
+            console.log(`  ${type.padEnd(20)} ${pc.cyan(String(count))}`);
+        }
+        console.log(`  ${"TOTAL".padEnd(20)} ${pc.cyan(String(s.totalRelationships))}`);
+        console.log("");
+        console.log(`${pc.dim("Subsystems")}:          ${pc.cyan(String(s.subsystemCount))}`);
+        console.log(`${pc.dim("Max subsystem depth")}: ${pc.cyan(String(s.maxSubsystemDepth))}`);
+        console.log(`${pc.dim("Views")}:               ${pc.cyan(String(s.viewCount))}`);
+        console.log(`${pc.dim("External references")}: ${pc.cyan(String(s.externalReferenceCount))}`);
+        if (Object.keys(s.decisionLifecycle).length > 0) {
+            console.log("");
+            console.log(pc.bold("Decision lifecycle:"));
+            for (const [state, count] of Object.entries(s.decisionLifecycle).sort()) {
+                console.log(`  ${state.padEnd(20)} ${pc.cyan(String(count))}`);
+            }
+        }
+        if (Object.keys(s.changeLifecycle).length > 0) {
+            console.log("");
+            console.log(pc.bold("Change lifecycle:"));
+            for (const [state, count] of Object.entries(s.changeLifecycle).sort()) {
+                console.log(`  ${state.padEnd(20)} ${pc.cyan(String(count))}`);
+            }
+        }
+    },
+};

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

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

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

@@ -0,0 +1,162 @@
+import * as z from "zod";
+import { loadDocument, saveDocument } from "../../io.js";
+import { addPlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, } from "../../operations/index.js";
+// ============================================================================
+// Subcommands
+// ============================================================================
+const listArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+});
+const listOpts = z.object({
+    change: z.string().optional().describe("Filter by change ID"),
+    pending: z.boolean().optional().describe("Show only pending tasks"),
+    json: z.boolean().optional().describe("Output as JSON"),
+});
+const listSubcommand = {
+    name: "list",
+    description: taskListOp.def.description,
+    apiLink: taskListOp.def.name,
+    args: listArgs,
+    opts: listOpts,
+    action(args, opts) {
+        const { doc } = loadDocument(args.input);
+        try {
+            const rows = taskListOp({
+                doc,
+                changeId: opts.change,
+                pendingOnly: opts.pending,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(rows, null, 2));
+                return;
+            }
+            const header = `${"Change".padEnd(12)} ${"#".padEnd(4)} ${"Done".padEnd(6)} Description`;
+            const divider = `${"-".repeat(12)} ${"-".repeat(4)} ${"-".repeat(6)} ${"-".repeat(30)}`;
+            console.log(header);
+            console.log(divider);
+            for (const row of rows) {
+                const doneStr = row.done ? "[x]" : "[ ]";
+                console.log(`${row.changeId.padEnd(12)} ${String(row.index).padEnd(4)} ${doneStr.padEnd(6)} ${row.description}`);
+            }
+            console.log(`\n${String(rows.length)} task(s)`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const addArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+    changeId: z.string().describe("Change node ID"),
+    description: z.string().describe("Task description"),
+});
+const addOpts = z.object({});
+const addSubcommand = {
+    name: "add",
+    description: addPlanTaskOp.def.description,
+    apiLink: addPlanTaskOp.def.name,
+    args: addArgs,
+    opts: addOpts,
+    action(args) {
+        const { doc, format, path } = loadDocument(args.input);
+        try {
+            const newDoc = addPlanTaskOp({
+                doc,
+                changeId: args.changeId,
+                description: args.description,
+            });
+            saveDocument(newDoc, format, path);
+            const node = newDoc.nodes.find((n) => n.id === args.changeId);
+            if (!node)
+                throw new Error(`Node ${args.changeId} not found`);
+            const newIndex = (node.plan?.length ?? 1) - 1;
+            console.log(`Added task ${String(newIndex)} to ${args.changeId}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const doneArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+    changeId: z.string().describe("Change node ID"),
+    taskIndex: z.string().describe("Task index"),
+});
+const doneOpts = z.object({});
+const doneSubcommand = {
+    name: "done",
+    description: markTaskDoneOp.def.description,
+    apiLink: markTaskDoneOp.def.name,
+    args: doneArgs,
+    opts: doneOpts,
+    action(args) {
+        const { doc, format, path } = loadDocument(args.input);
+        const taskIndex = parseInt(args.taskIndex, 10);
+        if (isNaN(taskIndex) || taskIndex < 0) {
+            console.error(`Invalid task index: ${args.taskIndex}`);
+            process.exit(1);
+        }
+        try {
+            const newDoc = markTaskDoneOp({
+                doc,
+                changeId: args.changeId,
+                taskIndex,
+            });
+            saveDocument(newDoc, format, path);
+            console.log(`Marked task ${String(taskIndex)} done on ${args.changeId}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+const undoneArgs = z.object({
+    input: z.string().describe("Path to SysProM document"),
+    changeId: z.string().describe("Change node ID"),
+    taskIndex: z.string().describe("Task index"),
+});
+const undoneOpts = z.object({});
+const undoneSubcommand = {
+    name: "undone",
+    description: markTaskUndoneOp.def.description,
+    apiLink: markTaskUndoneOp.def.name,
+    args: undoneArgs,
+    opts: undoneOpts,
+    action(args) {
+        const { doc, format, path } = loadDocument(args.input);
+        const taskIndex = parseInt(args.taskIndex, 10);
+        if (isNaN(taskIndex) || taskIndex < 0) {
+            console.error(`Invalid task index: ${args.taskIndex}`);
+            process.exit(1);
+        }
+        try {
+            const newDoc = markTaskUndoneOp({
+                doc,
+                changeId: args.changeId,
+                taskIndex,
+            });
+            saveDocument(newDoc, format, path);
+            console.log(`Marked task ${String(taskIndex)} undone on ${args.changeId}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+};
+// ============================================================================
+// Main command
+// ============================================================================
+export const taskCommand = {
+    name: "task",
+    description: "Manage tasks within change nodes",
+    subcommands: [
+        listSubcommand,
+        addSubcommand,
+        doneSubcommand,
+        undoneSubcommand,
+    ],
+};

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

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