sysprom 1.0.0 → 1.0.6

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

@@ -0,0 +1,219 @@
+import * as z from "zod";
+import { RelationshipType, NodeStatus } from "../../schema.js";
+import { updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, } from "../../operations/index.js";
+import { inputArg, mutationOpts, loadDoc, persistDoc } from "../shared.js";
+// ---------------------------------------------------------------------------
+// CLI helper functions
+// ---------------------------------------------------------------------------
+function parseLifecycleValue(rawVal) {
+    if (rawVal === "true") {
+        return true;
+    }
+    if (rawVal === "false") {
+        return false;
+    }
+    if (/^\d{4}-\d{2}-\d{2}/.test(rawVal)) {
+        return rawVal; // ISO date string
+    }
+    return rawVal;
+}
+function parseMetaValue(val) {
+    const numVal = Number(val);
+    return Number.isFinite(numVal) && val === String(numVal) ? numVal : val;
+}
+// ---------------------------------------------------------------------------
+// Arg/opt schemas
+// ---------------------------------------------------------------------------
+const updateNodeArgs = z.object({
+    input: inputArg,
+    id: z.string().describe("node ID to update"),
+});
+const updateNodeOpts = mutationOpts.extend({
+    description: z.string().optional().describe("update node description"),
+    status: NodeStatus.optional().describe("update node status"),
+    context: z.string().optional().describe("update node context"),
+    rationale: z.string().optional().describe("update node rationale"),
+    lifecycle: z
+        .array(z.string())
+        .optional()
+        .describe("set lifecycle state (key=value format)"),
+});
+const addRelArgs = z.object({
+    input: inputArg,
+    from: z.string().describe("source node ID"),
+    type: RelationshipType.describe("relationship type"),
+    to: z.string().describe("target node ID"),
+});
+const addRelOpts = mutationOpts;
+const removeRelArgs = z.object({
+    input: inputArg,
+    from: z.string().describe("source node ID"),
+    type: RelationshipType.describe("relationship type"),
+    to: z.string().describe("target node ID"),
+});
+const removeRelOpts = mutationOpts;
+const metaArgs = z.object({
+    input: inputArg,
+});
+const metaOpts = mutationOpts.extend({
+    fields: z
+        .array(z.string())
+        .describe("metadata field updates (key=value format)"),
+});
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+const nodeSubcommand = {
+    name: "node",
+    description: updateNodeOp.def.description,
+    apiLink: updateNodeOp.def.name,
+    args: updateNodeArgs,
+    opts: updateNodeOpts,
+    action(rawArgs, rawOpts) {
+        const args = updateNodeArgs.parse(rawArgs);
+        const opts = updateNodeOpts.parse(rawOpts);
+        const loaded = loadDoc(args.input);
+        const { doc } = loaded;
+        const node = doc.nodes.find((n) => n.id === args.id);
+        if (!node) {
+            console.error(`Node not found: ${args.id}`);
+            process.exit(1);
+        }
+        const fields = {};
+        if (opts.description !== undefined)
+            fields.description = opts.description;
+        if (opts.status !== undefined)
+            fields.status = opts.status;
+        if (opts.context !== undefined)
+            fields.context = opts.context;
+        if (opts.rationale !== undefined)
+            fields.rationale = opts.rationale;
+        if (opts.lifecycle && opts.lifecycle.length > 0) {
+            const lifecycle = { ...node.lifecycle };
+            for (const kv of opts.lifecycle) {
+                const eqIdx = kv.indexOf("=");
+                if (eqIdx < 0) {
+                    console.error(`Invalid --lifecycle format: ${kv} (expected key=value)`);
+                    process.exit(1);
+                }
+                const key = kv.slice(0, eqIdx);
+                const rawVal = kv.slice(eqIdx + 1);
+                lifecycle[key] = parseLifecycleValue(rawVal);
+            }
+            fields.lifecycle = lifecycle;
+        }
+        if (Object.keys(fields).length === 0) {
+            console.error("No fields specified to update.");
+            console.error("Use --description, --status, --context, --rationale, or --lifecycle.");
+            process.exit(1);
+        }
+        const newDoc = updateNodeOp({ doc, id: args.id, fields });
+        persistDoc(newDoc, loaded, opts);
+        if (opts.json) {
+            console.log(JSON.stringify(fields, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry-run] Would update" : "Updated"} ${node.type} ${args.id} — ${node.name}`);
+        }
+    },
+};
+const addRelSubcommand = {
+    name: "add-rel",
+    description: addRelationshipOp.def.description,
+    apiLink: addRelationshipOp.def.name,
+    args: addRelArgs,
+    opts: addRelOpts,
+    action(rawArgs, rawOpts) {
+        const args = addRelArgs.parse(rawArgs);
+        const opts = addRelOpts.parse(rawOpts);
+        const loaded = loadDoc(args.input);
+        const { doc } = loaded;
+        const newDoc = addRelationshipOp({
+            doc,
+            rel: { from: args.from, to: args.to, type: args.type },
+        });
+        persistDoc(newDoc, loaded, opts);
+        if (opts.json) {
+            const rel = newDoc.relationships?.find((r) => r.from === args.from && r.type === args.type && r.to === args.to);
+            console.log(JSON.stringify(rel, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry-run] Would add" : "Added"} relationship: ${args.from} ${args.type} ${args.to}`);
+        }
+    },
+};
+const removeRelSubcommand = {
+    name: "remove-rel",
+    description: removeRelationshipOp.def.description,
+    apiLink: removeRelationshipOp.def.name,
+    args: removeRelArgs,
+    opts: removeRelOpts,
+    action(rawArgs, rawOpts) {
+        const args = removeRelArgs.parse(rawArgs);
+        const opts = removeRelOpts.parse(rawOpts);
+        const loaded = loadDoc(args.input);
+        const { doc } = loaded;
+        const newDoc = removeRelationshipOp({
+            doc,
+            from: args.from,
+            type: args.type,
+            to: args.to,
+        });
+        persistDoc(newDoc, loaded, opts);
+        if (opts.json) {
+            console.log(JSON.stringify({ from: args.from, type: args.type, to: args.to }, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry-run] Would remove" : "Removed"} relationship: ${args.from} ${args.type} ${args.to}`);
+        }
+    },
+};
+const metaSubcommand = {
+    name: "meta",
+    description: updateMetadataOp.def.description,
+    apiLink: updateMetadataOp.def.name,
+    args: metaArgs,
+    opts: metaOpts,
+    action(rawArgs, rawOpts) {
+        const args = metaArgs.parse(rawArgs);
+        const opts = metaOpts.parse(rawOpts);
+        if (opts.fields.length === 0) {
+            console.error("No metadata fields specified. Use --fields key=value");
+            process.exit(1);
+        }
+        const loaded = loadDoc(args.input);
+        const { doc } = loaded;
+        const fields = {};
+        for (const kv of opts.fields) {
+            const eqIdx = kv.indexOf("=");
+            if (eqIdx < 0) {
+                console.error(`Invalid --fields format: ${kv} (expected key=value)`);
+                process.exit(1);
+            }
+            const key = kv.slice(0, eqIdx);
+            const val = kv.slice(eqIdx + 1);
+            fields[key] = parseMetaValue(val);
+        }
+        const newDoc = updateMetadataOp({ doc, fields });
+        persistDoc(newDoc, loaded, opts);
+        if (opts.json) {
+            console.log(JSON.stringify(fields, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry-run] Would update" : "Updated"} metadata: ${opts.fields.join(", ")}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+export const updateCommand = {
+    name: "update",
+    description: "Update nodes, relationships, and document metadata",
+    subcommands: [
+        nodeSubcommand,
+        addRelSubcommand,
+        removeRelSubcommand,
+        metaSubcommand,
+    ],
+};

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

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

@@ -0,0 +1,30 @@
+import * as z from "zod";
+import pc from "picocolors";
+import { validateOp } from "../../operations/index.js";
+import { inputArg, readOpts, loadDoc } from "../shared.js";
+const argsSchema = z.object({
+    input: inputArg,
+});
+const optsSchema = readOpts;
+export const validateCommand = {
+    name: "validate",
+    description: validateOp.def.description,
+    apiLink: validateOp.def.name,
+    args: argsSchema,
+    opts: optsSchema,
+    action(args) {
+        const { doc } = loadDoc(args.input);
+        const result = validateOp({ doc });
+        if (result.valid) {
+            console.log(pc.green("Valid SysProM document."));
+            console.log(`  ${pc.cyan(String(result.nodeCount))} nodes, ${pc.cyan(String(result.relationshipCount))} relationships`);
+        }
+        else {
+            console.error(pc.red(`Found ${String(result.issues.length)} issue(s):`));
+            for (const issue of result.issues) {
+                console.error(`  - ${pc.red(issue)}`);
+            }
+            process.exit(1);
+        }
+    },
+};

package/dist/src/cli/define-command.d.ts

@@ -0,0 +1,34 @@
+import * as z from "zod";
+import { Command } from "commander";
+export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOpts extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+    name: string;
+    description: string;
+    args?: TArgs;
+    opts?: TOpts;
+    subcommands?: CommandDef[];
+    action?: (args: z.infer<TArgs>, opts: z.infer<TOpts>) => void;
+    apiLink?: string;
+}
+export declare function buildCommander(def: CommandDef, parent: Command): Command;
+export interface ArgDoc {
+    name: string;
+    description: string;
+    required: boolean;
+    choices?: string[];
+}
+export interface OptDoc {
+    flag: string;
+    description: string;
+    required: boolean;
+    repeatable: boolean;
+    choices?: string[];
+}
+export interface CommandDoc {
+    name: string;
+    description: string;
+    args: ArgDoc[];
+    opts: OptDoc[];
+    subcommands?: CommandDoc[];
+    apiLink?: string;
+}
+export declare function extractDocs(def: CommandDef): CommandDoc;

package/dist/src/cli/define-command.js

@@ -0,0 +1,237 @@
+import { Argument, Option } from "commander";
+function unwrapField(field) {
+    if (typeof field.removeDefault === "function")
+        return unwrapField(field.removeDefault());
+    if (fieldIsOptional(field) && typeof field.unwrap === "function")
+        return unwrapField(field.unwrap());
+    return field;
+}
+function fieldIsOptional(field) {
+    return (typeof field.safeParse === "function" && field.safeParse(undefined).success);
+}
+function fieldIsArray(field) {
+    const inner = unwrapField(field);
+    return "element" in inner;
+}
+function fieldIsBoolean(field) {
+    const inner = unwrapField(field);
+    // ZodBoolean has no unique property, but we can check safeParse
+    const trueResult = inner.safeParse(true);
+    const strResult = inner.safeParse("test");
+    return trueResult.success && !strResult.success;
+}
+function fieldChoices(field) {
+    const inner = unwrapField(field);
+    if ("options" in inner && Array.isArray(inner.options)) {
+        return inner.options.map(String);
+    }
+    if ("element" in inner && inner.element) {
+        const el = inner.element;
+        if ("options" in el && Array.isArray(el.options)) {
+            return el.options.map(String);
+        }
+    }
+    return undefined;
+}
+function isZodField(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    // Check if it has methods/properties characteristic of Zod fields
+    const maybeField = toRecord(obj);
+    return (maybeField !== undefined &&
+        (typeof maybeField.safeParse === "function" ||
+            "description" in maybeField ||
+            "options" in maybeField ||
+            "element" in maybeField));
+}
+function isRecord(obj) {
+    return typeof obj === "object" && obj !== null;
+}
+function toRecord(obj) {
+    if (isRecord(obj)) {
+        return obj;
+    }
+    return undefined;
+}
+function fieldDescription(field) {
+    return field.description ?? "";
+}
+function camelToKebab(name) {
+    return name.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+function isZodLikeSchema(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const maybeShape = toRecord(obj)?.shape;
+    return typeof maybeShape === "object" && maybeShape !== null;
+}
+function getShape(schema) {
+    if (isZodLikeSchema(schema)) {
+        return schema.shape;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Build Commander from CommandDef
+// ---------------------------------------------------------------------------
+function collect(value, previous) {
+    return [...previous, value];
+}
+export function buildCommander(def, parent) {
+    const cmd = parent.command(def.name);
+    cmd.description(def.description);
+    {
+        const argsShape = getShape(def.args);
+        if (argsShape) {
+            for (const key of Object.keys(argsShape)) {
+                const field = argsShape[key];
+                if (!field || !isZodField(field))
+                    continue;
+                const desc = fieldDescription(field);
+                const choices = fieldChoices(field);
+                const flagName = camelToKebab(key);
+                if (choices) {
+                    cmd.addArgument(new Argument(`<${flagName}>`, desc).choices(choices));
+                }
+                else {
+                    cmd.argument(`<${flagName}>`, desc);
+                }
+            }
+        }
+    }
+    {
+        const optsShape = getShape(def.opts);
+        if (optsShape) {
+            for (const key of Object.keys(optsShape)) {
+                const field = optsShape[key];
+                if (!field || !isZodField(field))
+                    continue;
+                const desc = fieldDescription(field);
+                const choices = fieldChoices(field);
+                const flagName = camelToKebab(key);
+                const optional = fieldIsOptional(field);
+                const isArr = fieldIsArray(field);
+                const isBool = fieldIsBoolean(field);
+                if (isBool) {
+                    cmd.option(`--${flagName}`, desc);
+                }
+                else if (isArr) {
+                    if (optional) {
+                        cmd.option(`--${flagName} <value>`, desc, collect, []);
+                    }
+                    else {
+                        cmd.requiredOption(`--${flagName} <value>`, desc, collect, []);
+                    }
+                }
+                else if (choices) {
+                    const opt = new Option(`--${flagName} <value>`, desc).choices(choices);
+                    if (!optional)
+                        opt.makeOptionMandatory();
+                    cmd.addOption(opt);
+                }
+                else if (optional) {
+                    cmd.option(`--${flagName} <value>`, desc);
+                }
+                else {
+                    cmd.requiredOption(`--${flagName} <value>`, desc);
+                }
+            }
+        }
+    }
+    if (def.action) {
+        const action = def.action;
+        const argsSchema = def.args;
+        const optsSchema = def.opts;
+        cmd.action((...commanderArgs) => {
+            let argsKeys = [];
+            const argsShape = getShape(argsSchema);
+            if (argsShape) {
+                argsKeys = Object.keys(argsShape);
+            }
+            const argsObj = {};
+            for (let i = 0; i < argsKeys.length; i++) {
+                argsObj[argsKeys[i]] = commanderArgs[i];
+            }
+            const optsObjValue = commanderArgs[argsKeys.length];
+            const optsObj = toRecord(optsObjValue) ?? {};
+            const parsedArgs = argsSchema
+                ? argsSchema.safeParse(argsObj)
+                : { data: {} };
+            const parsedOpts = optsSchema
+                ? optsSchema.safeParse(optsObj)
+                : { data: {} };
+            if ("success" in parsedArgs && !parsedArgs.success) {
+                for (const issue of parsedArgs.error.issues) {
+                    console.error(`${issue.path.join(".")}: ${issue.message}`);
+                }
+                process.exit(1);
+            }
+            if ("success" in parsedOpts && !parsedOpts.success) {
+                for (const issue of parsedOpts.error.issues) {
+                    console.error(`${issue.path.join(".")}: ${issue.message}`);
+                }
+                process.exit(1);
+            }
+            try {
+                const argsData = "data" in parsedArgs ? parsedArgs.data : {};
+                const optsData = "data" in parsedOpts ? parsedOpts.data : {};
+                action(argsData, optsData);
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+        });
+    }
+    if (def.subcommands) {
+        for (const sub of def.subcommands) {
+            buildCommander(sub, cmd);
+        }
+    }
+    return cmd;
+}
+export function extractDocs(def) {
+    const args = [];
+    {
+        const argsShape = getShape(def.args);
+        if (argsShape) {
+            for (const key of Object.keys(argsShape)) {
+                const field = argsShape[key];
+                if (!field || !isZodField(field))
+                    continue;
+                args.push({
+                    name: camelToKebab(key),
+                    description: fieldDescription(field),
+                    required: !fieldIsOptional(field),
+                    choices: fieldChoices(field),
+                });
+            }
+        }
+    }
+    const opts = [];
+    {
+        const optsShape = getShape(def.opts);
+        if (optsShape) {
+            for (const key of Object.keys(optsShape)) {
+                const field = optsShape[key];
+                if (!field || !isZodField(field))
+                    continue;
+                opts.push({
+                    flag: `--${camelToKebab(key)}`,
+                    description: fieldDescription(field),
+                    required: !fieldIsOptional(field),
+                    repeatable: fieldIsArray(field),
+                    choices: fieldChoices(field),
+                });
+            }
+        }
+    }
+    return {
+        name: def.name,
+        description: def.description,
+        args,
+        opts,
+        subcommands: def.subcommands?.map(extractDocs),
+        apiLink: def.apiLink,
+    };
+}

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { program } from "./program.js";
+program.parse();

package/dist/src/cli/program.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import type { CommandDef } from "./define-command.js";
+export declare const program: Command;
+export declare const commands: CommandDef[];

package/dist/src/cli/program.js

@@ -0,0 +1,46 @@
+import { Command } from "commander";
+import { buildCommander } from "./define-command.js";
+import { validateCommand } from "./commands/validate.js";
+import { statsCommand } from "./commands/stats.js";
+import { json2mdCommand } from "./commands/json2md.js";
+import { md2jsonCommand } from "./commands/md2json.js";
+import { removeCommand } from "./commands/remove.js";
+import { addCommand } from "./commands/add.js";
+import { initCommand } from "./commands/init.js";
+import { searchCommand } from "./commands/search.js";
+import { checkCommand } from "./commands/check.js";
+import { graphCommand } from "./commands/graph.js";
+import { renameCommand } from "./commands/rename.js";
+import { queryCommand } from "./commands/query.js";
+import { updateCommand } from "./commands/update.js";
+import { speckitCommand } from "./commands/speckit.js";
+import { taskCommand } from "./commands/task.js";
+import { planCommand } from "./commands/plan.js";
+const VERSION = "1.0.0";
+export const program = new Command();
+program
+    .name("sysprom")
+    .description("System Provenance Model CLI — record where every part of a system came from")
+    .version(VERSION)
+    .showHelpAfterError(true);
+export const commands = [
+    validateCommand,
+    statsCommand,
+    json2mdCommand,
+    md2jsonCommand,
+    queryCommand,
+    addCommand,
+    removeCommand,
+    updateCommand,
+    initCommand,
+    searchCommand,
+    checkCommand,
+    graphCommand,
+    renameCommand,
+    speckitCommand,
+    taskCommand,
+    planCommand,
+];
+for (const cmd of commands) {
+    buildCommander(cmd, program);
+}

package/dist/src/cli/shared.d.ts

@@ -0,0 +1,26 @@
+import * as z from "zod";
+import { type Format } from "../io.js";
+import type { SysProMDocument } from "../schema.js";
+/** Positional argument for a SysProM document path. */
+export declare const inputArg: z.ZodString;
+/** Common output/persistence options for read-only commands. */
+export declare const readOpts: z.ZodObject<{
+    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+/** Common output/persistence options for mutation commands. */
+export declare const mutationOpts: z.ZodObject<{
+    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    sync: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReadOpts = z.infer<typeof readOpts>;
+export type MutationOpts = z.infer<typeof mutationOpts>;
+export interface LoadedDoc {
+    doc: SysProMDocument;
+    format: Format;
+    path: string;
+}
+/** Load a document from a CLI input path. */
+export declare function loadDoc(input: string): LoadedDoc;
+/** Persist a document and optionally sync to markdown. */
+export declare function persistDoc(doc: SysProMDocument, loaded: LoadedDoc, opts: MutationOpts): void;

package/dist/src/cli/shared.js

@@ -0,0 +1,41 @@
+import * as z from "zod";
+import { loadDocument, saveDocument } from "../io.js";
+import { jsonToMarkdownMultiDoc } from "../json-to-md.js";
+// ---------------------------------------------------------------------------
+// Reusable CLI schemas — shared across all commands
+// ---------------------------------------------------------------------------
+/** Positional argument for a SysProM document path. */
+export const inputArg = z
+    .string()
+    .describe("SysProM document path (JSON, .md, or directory)");
+/** Common output/persistence options for read-only commands. */
+export const readOpts = z.object({
+    json: z.boolean().optional().default(false).describe("output as JSON"),
+});
+/** Common output/persistence options for mutation commands. */
+export const mutationOpts = z.object({
+    json: z.boolean().optional().default(false).describe("output as JSON"),
+    dryRun: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("preview changes without saving"),
+    sync: z
+        .string()
+        .optional()
+        .describe("sync to markdown directory after saving"),
+});
+/** Load a document from a CLI input path. */
+export function loadDoc(input) {
+    return loadDocument(input);
+}
+/** Persist a document and optionally sync to markdown. */
+export function persistDoc(doc, loaded, opts) {
+    if (!opts.dryRun) {
+        saveDocument(doc, loaded.format, loaded.path);
+        if (opts.sync) {
+            jsonToMarkdownMultiDoc(doc, opts.sync);
+            console.log(`Synced to ${opts.sync}`);
+        }
+    }
+}

package/dist/src/generate-schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/generate-schema.js

@@ -0,0 +1,9 @@
+import { writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalise } from "./canonical-json.js";
+import { toJSONSchema } from "./schema.js";
+const schema = toJSONSchema();
+const outPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "schema.json");
+writeFileSync(outPath, canonicalise(schema, { indent: "\t" }) + "\n");
+console.log(`Written to ${outPath}`);