@millstone/synapse-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import { validateCommand } from "./commands/validate.js";
+import { formatCommand } from "./commands/format.js";
+import { indexCommand } from "./commands/index.js";
+import { scaffoldCommand } from "./commands/scaffold.js";
+import { generatePdfCommand } from "./commands/generate-pdf.js";
+import { initCommand } from "./commands/init.js";
+import { updateCommand } from "./commands/update.js";
+import { ejectCommand } from "./commands/eject.js";
+import { fetchReferenceCommand } from "./commands/fetch-reference.js";
+import { migrateCommand } from "./commands/migrate.js";
+import { DOC_TYPES } from "./lib/types.generated.js";
+import { detectInstallMode } from "./lib/mode-detection.js";
+// Parse command line arguments
+const [, , command, ...args] = process.argv;
+// Simple argument parser
+function parseArgs(args) {
+    const parsed = {};
+    let i = 0;
+    // Helper to convert kebab-case to camelCase
+    const toCamelCase = (str) => {
+        return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    };
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            // Handle --no-* flags
+            if (key.startsWith("no-")) {
+                const actualKey = toCamelCase(key.slice(3));
+                parsed[actualKey] = false;
+                i++;
+            }
+            else {
+                const nextArg = args[i + 1];
+                const camelKey = toCamelCase(key);
+                // Check if this is a boolean flag or has a value
+                if (!nextArg || nextArg.startsWith("--")) {
+                    parsed[camelKey] = true;
+                    i++;
+                }
+                else {
+                    parsed[camelKey] = nextArg;
+                    i += 2;
+                }
+            }
+        }
+        else if (arg.startsWith("-")) {
+            // Short flags
+            const key = arg.slice(1);
+            parsed[key] = true;
+            i++;
+        }
+        else {
+            // Positional arguments
+            if (!parsed._) {
+                parsed._ = [];
+            }
+            parsed._.push(arg);
+            i++;
+        }
+    }
+    return parsed;
+}
+// Show help message
+function showHelp() {
+    const availableTypes = DOC_TYPES.join(", ");
+    const mode = detectInstallMode();
+    const isNpm = mode === 'npm';
+    console.log(`
+Synapse Documentation Framework CLI${isNpm ? ' (npm mode)' : mode === 'fork' ? ' (fork mode)' : ''}
+
+Usage:
+  synapse <command> [options]
+
+Commands:
+  validate        Validate documentation files against schemas
+  format          Format documentation files according to body grammar rules
+  index           Generate the homepage index.md with navigation
+  scaffold        Create a new document from a template
+  generate-pdf    Generate a PDF from YAML data and template
+  fetch-reference Fetch and convert external URL to markdown${isNpm ? `
+  init            Initialize forked repository configuration  [deprecated in npm mode]
+  update          Merge upstream changes from the framework    [deprecated in npm mode]
+  eject           Mark repository as independent from upstream  [deprecated in npm mode]` : `
+  init            Initialize forked repository configuration
+  update          Merge upstream changes from the framework
+  eject           Mark repository as independent from upstream`}
+  migrate         Migrate from fork mode to npm dependency mode
+
+Options:
+  --help      Show this help message
+
+Validate Command:
+  synapse validate [options]
+
+  Options:
+    --dir <path>        Content directory to validate (default: content/)
+    --schema <path>     Schema directory (default: content/schemas/)
+    --pattern <glob>    Glob pattern to match files (default: **/*.md)
+    --format <format>   Output format: pretty, json, compact (default: pretty)
+    --strict            Enable strict mode for naming validation (default: true)
+    --no-strict         Disable strict mode for naming validation
+
+Format Command:
+  synapse format [options]
+
+  Options:
+    --dir <path>        Content directory to format (default: content/)
+    --write             Write changes to files (default: dry-run)
+    --pattern <glob>    Glob pattern to match files (default: **/*.md)
+    --verbose           Show all files, including unchanged
+
+Index Command:
+  synapse index [options]
+
+  Options:
+    --dir <path>        Content directory (default: content/)
+    --output <path>     Output file path (default: content/index.md)
+
+Scaffold Command:
+  synapse scaffold [options]
+
+  Options:
+    --type <type>       Document type (required: ${availableTypes})
+    --template <type>   Alias for --type (backward compatible)
+    --title <title>     Document title (required)
+    --owner <owner>     Document owner (optional)
+    --id <id>           Custom document ID (default: auto-generated)
+    --target-dir <path> Output directory (default: content/{type folder})
+    --force             Overwrite existing files
+
+Generate PDF Command:
+  synapse generate-pdf [options]
+
+  Options:
+    --input <path>      Input YAML data file (required)
+    --output <path>     Output PDF file path (required)
+    --logo <path>       Logo image path (optional)
+    --company <name>    Company name for letterhead (optional)
+    --url <url>         Company URL for letterhead (optional)
+    --no-validate       Skip schema validation
+
+Fetch Reference Command:
+  synapse fetch-reference <url>
+
+  Fetch external documentation and convert to markdown using Mozilla
+  Readability + Turndown. Outputs JSON with markdown content, title,
+  byline, and excerpt.
+
+Init Command:
+  synapse init [options]
+
+  Options:
+    --site-name <name>        Site name (default: prompted)
+    --display-name <name>     Display name (default: site name)
+    --base-url <url>          Base URL (default: prompted)
+    --primary-color <hex>     Primary theme color (optional)
+    --upstream-remote <name>  Git remote name (default: upstream)
+    --upstream-url <url>      Upstream repository URL
+    --force                   Reinitialize if already initialized
+    --yes                     Skip interactive prompts
+
+Update Command:
+  synapse update [options]
+
+  Options:
+    --continue           Continue merge after manual conflict resolution
+    --accept-upstream    Accept all upstream changes for conflicts
+    --accept-ours        Keep all local changes for conflicts
+    --abort              Abort in-progress merge
+    --remote <name>      Git remote name (default: upstream)
+    --branch <name>      Remote branch (default: main)
+
+Eject Command:
+  synapse eject [options]
+
+  Options:
+    --remove-remote      Remove upstream git remote
+    --remote <name>      Git remote name (default: upstream)
+    --yes                Skip confirmation prompt
+
+Migrate Command:
+  synapse migrate [options]
+
+  Options:
+    --dry-run            Show migration plan without making changes
+    --yes                Skip confirmation prompts
+
+Examples:
+  synapse validate
+  synapse validate --no-strict
+  synapse validate --pattern "70_Architecture/**/*.md"
+  synapse validate --pattern "**/ADRs/*.md" --format compact
+  synapse validate --format json > validation-results.json
+  synapse format
+  synapse format --write
+  synapse format --pattern "100_Products/**/*.md" --write
+  synapse index
+  synapse index --output site/content/index.md
+  synapse scaffold --type adr --title "Use React for Frontend"
+  synapse scaffold --type policy --title "Security Policy" --owner "Security Team"
+  synapse scaffold --type sop --title "Deployment Procedure" --id "SOP-042"
+  synapse generate-pdf --input data.yaml --output document.pdf --logo tools/pdf/logo.png --company "Your Company"
+  synapse init
+  synapse init --site-name "My Docs" --base-url "https://docs.example.com" --yes
+  synapse update
+  synapse update --accept-upstream
+  synapse update --continue
+  synapse eject
+  synapse migrate --dry-run
+  synapse migrate --yes
+`);
+}
+// Main CLI handler
+async function main() {
+    if (!command ||
+        command === "--help" ||
+        command === "-h" ||
+        command === "help") {
+        showHelp();
+        process.exit(0);
+    }
+    const parsedArgs = parseArgs(args);
+    try {
+        switch (command) {
+            case "validate":
+                await validateCommand(parsedArgs);
+                break;
+            case "format":
+                await formatCommand(parsedArgs);
+                break;
+            case "index":
+                await indexCommand(parsedArgs);
+                break;
+            case "scaffold":
+                await scaffoldCommand(parsedArgs);
+                break;
+            case "generate-pdf":
+                await generatePdfCommand(parsedArgs);
+                break;
+            case "init":
+                await initCommand(parsedArgs);
+                break;
+            case "update":
+                await updateCommand(parsedArgs);
+                break;
+            case "eject":
+                await ejectCommand(parsedArgs);
+                break;
+            case "migrate":
+                await migrateCommand(parsedArgs);
+                break;
+            case "fetch-reference":
+                // First positional arg is the URL
+                await fetchReferenceCommand({
+                    url: parsedArgs._?.[0],
+                    ...parsedArgs,
+                });
+                break;
+            default:
+                console.error(`Unknown command: ${command}`);
+                console.log('Run "synapse --help" for usage information');
+                process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error("Error:", error);
+        process.exit(1);
+    }
+}
+// Run the CLI
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/bodyRules.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Body validation rules for Synapse document types
+ * Implements AST-based validation of Markdown body structure
+ */
+import { DocType } from './types.generated.js';
+export interface ValidationIssue {
+    notePath: string;
+    type: 'error';
+    code: string;
+    message: string;
+    sectionId?: string;
+    line?: number;
+    column?: number;
+}
+export interface SectionRule {
+    id: string;
+    title: string;
+    alternativeTitles?: string[];
+    required: boolean;
+    order: number;
+    shape: SectionShape;
+}
+export type SectionShape = {
+    type: 'paragraphs';
+} | {
+    type: 'list';
+    ordered?: boolean;
+    maxDepth?: number;
+    minItems?: number;
+} | {
+    type: 'flow';
+    allowedNodes: string[];
+} | {
+    type: 'table';
+    requiredHeaders?: string[];
+    minRows?: number;
+} | {
+    type: 'milestoneList';
+    requireH3: boolean;
+    requiredSubsections: string[];
+    requiredFields?: string[];
+};
+export interface BodyRules {
+    documentTypes: Record<string, {
+        displayName: string;
+        sections: SectionRule[];
+    }>;
+}
+/**
+ * Loads body rules from the body-grammars directory
+ */
+export declare function loadBodyRules(root?: string): Promise<BodyRules>;
+/**
+ * Formats a document body according to grammar rules
+ * - Inserts missing required sections in canonical order
+ * - Normalizes section titles to match grammar
+ * - Normalizes heading levels (H2 for sections)
+ * - Normalizes list markers
+ * - Preserves existing content
+ * @param body - The original markdown body
+ * @param rules - Body grammar rules
+ * @param type - Document type
+ * @returns Formatted markdown body
+ */
+export declare function formatBody(body: string, rules: BodyRules, type: DocType): string;
+/**
+ * Validates markdown body against rules for a given document type
+ */
+export declare function validateBody(body: string, rules: BodyRules, type: DocType, notePath: string): ValidationIssue[];
+//# sourceMappingURL=bodyRules.d.ts.map

package/dist/lib/bodyRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyRules.d.ts","sourceRoot":"","sources":["../../src/lib/bodyRules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EAAE,OAAO,EAAa,MAAM,sBAAsB,CAAC;AAQ1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEN,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CACnB,MAAM,EACN;QACE,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,WAAW,EAAE,CAAC;KACzB,CACF,CAAC;CACH;AAMD;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAgDrE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,OAAO,GACZ,MAAM,CAyER;AA2ID;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CA8EnB"}