sysprom 1.4.0 → 1.6.0

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

@@ -7,9 +7,9 @@ declare const optsSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodEnum<{
-        dir: "dir";
         json: "json";
         md: "md";
+        dir: "dir";
     }>>;
 }, z.core.$strict>;
 export declare const initCommand: CommandDef<typeof argsSchema, typeof optsSchema>;

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

@@ -0,0 +1,18 @@
+import type { CommandDef } from "../define-command.js";
+import { type BidirectionalSyncResult, type ConflictStrategy } from "../../operations/index.js";
+interface SyncCommandInput {
+    jsonPath: string;
+    mdPath: string;
+    strategy?: ConflictStrategy;
+    dryRun?: boolean;
+}
+/**
+ * Synchronise JSON and Markdown representations of a SysProM document.
+ * @param input - Configuration for sync operation
+ * @returns Result of the synchronisation
+ * @example
+ * const result = syncCommand({ jsonPath: "doc.spm.json", mdPath: "doc.spm.md" });
+ */
+export declare function syncCommand(input: SyncCommandInput): BidirectionalSyncResult;
+export declare const syncCommandDef: CommandDef;
+export {};

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

@@ -0,0 +1,112 @@
+import * as z from "zod";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { syncDocumentsOp, } from "../../operations/index.js";
+import { detectChanges } from "../../sync.js";
+import { markdownToJson } from "../../md-to-json.js";
+import { jsonToMarkdownSingle } from "../../json-to-md.js";
+import { canonicalise } from "../../canonical-json.js";
+import { SysProMDocument } from "../../schema.js";
+/**
+ * Synchronise JSON and Markdown representations of a SysProM document.
+ * @param input - Configuration for sync operation
+ * @returns Result of the synchronisation
+ * @example
+ * const result = syncCommand({ jsonPath: "doc.spm.json", mdPath: "doc.spm.md" });
+ */
+export function syncCommand(input) {
+    const { jsonPath, mdPath, strategy = "json", dryRun = false } = input;
+    // Read JSON document
+    const jsonContent = readFileSync(jsonPath, "utf8");
+    const jsonDoc = JSON.parse(jsonContent);
+    if (!SysProMDocument.is(jsonDoc)) {
+        throw new Error("JSON file is not a valid SysProM document");
+    }
+    // Parse Markdown to document
+    const mdDoc = markdownToJson(mdPath);
+    // Detect which side changed
+    const changes = detectChanges(jsonPath, mdPath);
+    // Perform sync operation
+    const result = syncDocumentsOp({
+        jsonDoc,
+        mdDoc,
+        jsonChanged: changes.jsonChanged,
+        mdChanged: changes.mdChanged,
+        strategy,
+    });
+    // Write results if not dry-run
+    if (!dryRun) {
+        // Write synced document back to both formats
+        if (result.jsonChanged || result.mdChanged || result.conflict) {
+            // Update JSON
+            writeFileSync(jsonPath, canonicalise(result.synced, { indent: "\t" }) + "\n");
+            // Update Markdown
+            const mdContent = jsonToMarkdownSingle(result.synced);
+            writeFileSync(mdPath, mdContent);
+        }
+    }
+    return result;
+}
+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 syncCommandDef = {
+    name: "sync",
+    description: "Synchronise JSON and Markdown representations with conflict resolution",
+    apiLink: "syncDocuments",
+    args: z.object({
+        input: z.string().describe("Path to JSON file"),
+        output: z.string().describe("Path to Markdown file"),
+    }),
+    opts: z
+        .object({
+        preferJson: z
+            .boolean()
+            .optional()
+            .describe("Prefer JSON as source of truth in conflicts"),
+        preferMd: z
+            .boolean()
+            .optional()
+            .describe("Prefer Markdown as source of truth in conflicts"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("Preview changes without writing files"),
+        report: z
+            .boolean()
+            .optional()
+            .describe("Report conflicts without resolving"),
+    })
+        .strict(),
+    action(args, opts) {
+        if (!isArgs(args))
+            throw new Error("Invalid args");
+        if (!isOpts(opts))
+            throw new Error("Invalid opts");
+        const jsonPath = resolve(args.input);
+        const mdPath = resolve(args.output);
+        // Determine conflict strategy
+        let strategy = "json";
+        if (opts.preferMd)
+            strategy = "md";
+        if (opts.report)
+            strategy = "report";
+        const result = syncCommand({
+            jsonPath,
+            mdPath,
+            strategy,
+            dryRun: opts.dryRun ?? false,
+        });
+        // Output results
+        console.log(`Sync complete:`);
+        console.log(`  JSON changed: ${String(result.jsonChanged)}`);
+        console.log(`  Markdown changed: ${String(result.mdChanged)}`);
+        console.log(`  Conflict: ${String(result.conflict)}`);
+        if (result.changedNodes.length > 0) {
+            console.log(`  Changed nodes: ${result.changedNodes.join(", ")}`);
+        }
+    },
+};

package/dist/src/cli/program.js

@@ -16,6 +16,7 @@ import { updateCommand } from "./commands/update.js";
 import { speckitCommand } from "./commands/speckit.js";
 import { taskCommand } from "./commands/task.js";
 import { planCommand } from "./commands/plan.js";
+import { syncCommandDef } from "./commands/sync.js";
 const VERSION = "1.0.0";
 export const program = new Command();
 program
@@ -40,6 +41,7 @@ export const commands = [
     speckitCommand,
     taskCommand,
     planCommand,
+    syncCommandDef,
 ];
 for (const cmd of commands) {
     buildCommander(cmd, program);

package/dist/src/json-to-md.js

@@ -261,6 +261,7 @@ function generateReadme(doc, fromIdx) {
     const lines = [];
     const title = doc.metadata?.title ?? "SysProM";
     lines.push(renderFrontMatter({
+        ...(doc.$schema ? { $schema: doc.$schema } : {}),
         title,
         doc_type: doc.metadata?.doc_type ?? "sysprom",
         scope: doc.metadata?.scope,
@@ -373,6 +374,7 @@ export function jsonToMarkdownSingle(doc) {
     const lines = [];
     const title = doc.metadata?.title ?? "SysProM";
     lines.push(renderFrontMatter({
+        ...(doc.$schema ? { $schema: doc.$schema } : {}),
         title,
         doc_type: doc.metadata?.doc_type ?? "sysprom",
         scope: doc.metadata?.scope,

package/dist/src/md-to-json.js

@@ -35,6 +35,13 @@ function parseText(raw) {
     const lines = raw.split("\n");
     return lines.length === 1 ? lines[0] : lines;
 }
+/** Separate $schema from front matter so it becomes a top-level document key. */
+function extractSchema(front) {
+    const schema = typeof front.$schema === "string" ? front.$schema : undefined;
+    const metadata = { ...front };
+    delete metadata.$schema;
+    return { schema, metadata };
+}
 function parseFrontMatter(content) {
     if (!content.startsWith("---\n"))
         return { front: {}, body: content };
@@ -44,7 +51,7 @@ function parseFrontMatter(content) {
     const yaml = content.slice(4, end);
     const front = {};
     for (const line of yaml.split("\n")) {
-        const match = /^(\w+):\s*(.+)$/.exec(line);
+        const match = /^([\w$]+):\s*(.+)$/.exec(line);
         if (!match)
             continue;
         const [, key, raw] = match;
@@ -167,9 +174,22 @@ function parseListItems(body, prefix) {
     return items;
 }
 function parseSingleValue(body, prefix) {
-    for (const line of body.split("\n")) {
-        if (line.startsWith(`${prefix}: `)) {
-            return line.slice(prefix.length + 2);
+    const lines = body.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith(`${prefix}: `)) {
+            const firstLine = lines[i].slice(prefix.length + 2);
+            const continuationLines = [firstLine];
+            for (let j = i + 1; j < lines.length; j++) {
+                const next = lines[j];
+                if (next === "")
+                    break;
+                if (next.startsWith("- ") || next.startsWith("#"))
+                    break;
+                if (/^[A-Z][a-z]+: /.test(next))
+                    break;
+                continuationLines.push(next);
+            }
+            return continuationLines.join("\n");
         }
     }
     return undefined;
@@ -450,14 +470,16 @@ export function markdownSingleToJson(content) {
     const { nodes, rels } = parseDocFile(content, allTypes);
     const tableRels = parseRelationshipTable(body);
     const extRefs = parseExternalReferences(body);
+    const { schema, metadata: metaFront } = extractSchema(front);
     const doc = {
-        metadata: Object.keys(front).length > 0 ? front : undefined,
+        ...(schema ? { $schema: schema } : {}),
+        metadata: Object.keys(metaFront).length > 0 ? metaFront : undefined,
         nodes,
         relationships: [...rels, ...tableRels].length > 0 ? [...rels, ...tableRels] : undefined,
         external_references: extRefs.length > 0 ? extRefs : undefined,
     };
-    if (front.title && typeof front.title === "string") {
-        doc.metadata = { ...front };
+    if (metaFront.title && typeof metaFront.title === "string") {
+        doc.metadata = { ...metaFront };
     }
     return doc;
 }
@@ -532,8 +554,10 @@ export function markdownMultiDocToJson(dir) {
         }
     }
     scanForSubsystems(dir);
+    const { schema, metadata: metaFront } = extractSchema(front);
     const doc = {
-        metadata: Object.keys(front).length > 0 ? front : undefined,
+        ...(schema ? { $schema: schema } : {}),
+        metadata: Object.keys(metaFront).length > 0 ? metaFront : undefined,
         nodes,
         relationships: rels.length > 0 ? rels : undefined,
         external_references: extRefs.length > 0 ? extRefs : undefined,

package/dist/src/operations/index.d.ts

@@ -32,6 +32,7 @@ export { graphOp } from "./graph.js";
 export { renameOp } from "./rename.js";
 export { jsonToMarkdownOp } from "./json-to-markdown.js";
 export { markdownToJsonOp } from "./markdown-to-json.js";
+export { syncDocumentsOp, type BidirectionalSyncResult, type ConflictStrategy, } from "./sync.js";
 export { speckitImportOp } from "./speckit-import.js";
 export { speckitExportOp } from "./speckit-export.js";
 export { speckitSyncOp, type SyncResult } from "./speckit-sync.js";

package/dist/src/operations/index.js

@@ -38,6 +38,8 @@ export { renameOp } from "./rename.js";
 // Conversion operations
 export { jsonToMarkdownOp } from "./json-to-markdown.js";
 export { markdownToJsonOp } from "./markdown-to-json.js";
+// Synchronisation operations
+export { syncDocumentsOp, } from "./sync.js";
 // Spec-Kit interoperability operations
 export { speckitImportOp } from "./speckit-import.js";
 export { speckitExportOp } from "./speckit-export.js";