@spekn/cli 1.0.0

package/dist/spec-lint.js

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * spec-lint CLI Tool
+ *
+ * Validate specification markdown quality and structure.
+ *
+ * Usage: npm run spec-lint <spec-file-path>
+ * Example: npm run spec-lint specs/DECISIONS.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const agents_1 = require("@spekn/agents");
+const shared_1 = require("@spekn/shared");
+const cli_runtime_1 = require("./utils/cli-runtime");
+function parseArgs(args) {
+    const options = {};
+    let filePath;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--verbose" || arg === "-v") {
+            options.verbose = true;
+        }
+        else if (arg === "--fix" || arg === "-f") {
+            options.fix = true;
+        }
+        else if (!arg.startsWith("-")) {
+            filePath = arg;
+        }
+    }
+    if (!filePath) {
+        throw new Error("missing required argument: <spec-file-path>");
+    }
+    return { filePath, options };
+}
+function printHelp() {
+    console.log(`
+spec-lint - Validate specification markdown quality
+
+USAGE:
+  npm run spec-lint <spec-file-path> [OPTIONS]
+
+ARGUMENTS:
+  <spec-file-path>    Path to the specification markdown file
+
+OPTIONS:
+  -v, --verbose       Show detailed output and suggestions
+  -f, --fix           Auto-fix deterministic anchor formatting issues
+  -h, --help          Show this help message
+
+LINTING RULES:
+  frontmatter-required  Specification has valid YAML frontmatter
+  anchor-naming         Anchors follow naming convention (lowercase, dots)
+  anchor-duplicates     No duplicate anchors
+  anchor-acceptance     All anchors have acceptance criteria
+  dependency-valid      Dependencies reference valid anchors
+  markdown-quality      Basic markdown quality checks
+
+EXAMPLES:
+  npm run spec-lint specs/SPECIFICATION.md
+  npm run spec-lint specs/DECISIONS.md --verbose
+`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeAnchorForFix(anchor) {
+    return anchor
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9._-]/g, "-")
+        .replace(/\.\./g, ".")
+        .replace(/^\./, "")
+        .replace(/\.$/, "");
+}
+function applyDeterministicFixes(content) {
+    const anchors = (0, agents_1.extractAnchors)(content);
+    const uniqueAnchors = Array.from(new Set(anchors.map((a) => a.anchor)));
+    let nextContent = content;
+    let fixesApplied = 0;
+    const replaceWithCount = (input, pattern, replacement) => {
+        let count = 0;
+        const output = input.replace(pattern, () => {
+            count += 1;
+            return replacement;
+        });
+        return { output, count };
+    };
+    for (const anchor of uniqueAnchors) {
+        const normalized = normalizeAnchorForFix(anchor);
+        if (!normalized || normalized === anchor) {
+            continue;
+        }
+        const escaped = escapeRegExp(anchor);
+        const bracket = replaceWithCount(nextContent, new RegExp(`\\[${escaped}\\]`, "g"), `[${normalized}]`);
+        nextContent = bracket.output;
+        fixesApplied += bracket.count;
+        const prefixed = replaceWithCount(nextContent, new RegExp(`spec:${escaped}\\b`, "gi"), `spec:${normalized}`);
+        nextContent = prefixed.output;
+        fixesApplied += prefixed.count;
+        const hashDeps = replaceWithCount(nextContent, new RegExp(`#${escaped}\\b`, "g"), `#${normalized}`);
+        nextContent = hashDeps.output;
+        fixesApplied += hashDeps.count;
+    }
+    return { content: nextContent, fixesApplied };
+}
+function checkAnchorNaming(anchors) {
+    const issues = [];
+    anchors.forEach((anchor) => {
+        // Check lowercase
+        if (anchor.anchor !== anchor.anchor.toLowerCase()) {
+            issues.push({
+                severity: "error",
+                rule: "anchor-naming",
+                message: "Anchor should be lowercase",
+                anchor: anchor.anchor,
+                line: anchor.lineNumber,
+                suggestion: anchor.anchor.toLowerCase(),
+            });
+        }
+        // Check valid characters (only lowercase letters, numbers, dots, hyphens)
+        if (!anchor.anchor.match(/^[a-z0-9._-]+$/)) {
+            issues.push({
+                severity: "error",
+                rule: "anchor-naming",
+                message: "Anchor contains invalid characters (only a-z, 0-9, ., -, _ allowed)",
+                anchor: anchor.anchor,
+                line: anchor.lineNumber,
+            });
+        }
+        // Check for double dots or leading/trailing dots
+        if (anchor.anchor.match(/\.\./)) {
+            issues.push({
+                severity: "warning",
+                rule: "anchor-naming",
+                message: "Anchor contains consecutive dots",
+                anchor: anchor.anchor,
+                line: anchor.lineNumber,
+            });
+        }
+        if (anchor.anchor.startsWith(".") || anchor.anchor.endsWith(".")) {
+            issues.push({
+                severity: "warning",
+                rule: "anchor-naming",
+                message: "Anchor should not start or end with a dot",
+                anchor: anchor.anchor,
+                line: anchor.lineNumber,
+            });
+        }
+        // Recommend dot notation for hierarchical anchors
+        if (anchor.anchor.includes("_") && !anchor.anchor.includes(".")) {
+            issues.push({
+                severity: "info",
+                rule: "anchor-naming",
+                message: "Consider using dot notation for hierarchical structure",
+                anchor: anchor.anchor,
+                line: anchor.lineNumber,
+                suggestion: anchor.anchor.replace(/_/g, "."),
+            });
+        }
+    });
+    return issues;
+}
+function checkDuplicateAnchors(anchors) {
+    const issues = [];
+    const anchorMap = new Map();
+    anchors.forEach((anchor) => {
+        const normalized = anchor.anchor.toLowerCase();
+        if (!anchorMap.has(normalized)) {
+            anchorMap.set(normalized, []);
+        }
+        anchorMap.get(normalized).push(anchor.lineNumber);
+    });
+    anchorMap.forEach((lines, anchor) => {
+        if (lines.length > 1) {
+            issues.push({
+                severity: "error",
+                rule: "anchor-duplicates",
+                message: `Duplicate anchor found on lines: ${lines.join(", ")}`,
+                anchor,
+            });
+        }
+    });
+    return issues;
+}
+function checkAcceptanceCriteria(content, anchors) {
+    const issues = [];
+    anchors.forEach((anchor) => {
+        const anchorContent = (0, agents_1.extractAnchorContent)(anchor.anchor, content);
+        if (!anchorContent)
+            return;
+        // Check for acceptance criteria section
+        const hasAcceptanceCriteria = anchorContent.match(/\*\*Acceptance Criteria\*\*:|##\s*Acceptance Criteria|###\s*Acceptance Criteria/i);
+        if (!hasAcceptanceCriteria) {
+            issues.push({
+                severity: "warning",
+                rule: "anchor-acceptance",
+                message: "Anchor lacks explicit acceptance criteria section",
+                anchor: anchor.anchor,
+                line: anchor.lineNumber,
+            });
+        }
+    });
+    return issues;
+}
+function checkDependencyValidity(content, anchors) {
+    const issues = [];
+    const validAnchors = (0, agents_1.getValidAnchors)(content);
+    anchors.forEach((anchor) => {
+        const anchorContent = (0, agents_1.extractAnchorContent)(anchor.anchor, content);
+        if (!anchorContent)
+            return;
+        // Look for dependency references
+        const dependencyMatch = anchorContent.match(/\*\*Dependencies\*\*:([^\n]+)/i);
+        if (dependencyMatch) {
+            const dependencyText = dependencyMatch[1];
+            const dependencyAnchors = dependencyText.match(/#[a-z0-9._-]+/gi);
+            if (dependencyAnchors) {
+                dependencyAnchors.forEach((dep) => {
+                    const depNormalized = dep.replace(/^#/, "").toLowerCase();
+                    const isValid = validAnchors.some((valid) => valid.toLowerCase() === depNormalized);
+                    if (!isValid) {
+                        issues.push({
+                            severity: "error",
+                            rule: "dependency-valid",
+                            message: `Dependency references non-existent anchor: ${dep}`,
+                            anchor: anchor.anchor,
+                            line: anchor.lineNumber,
+                        });
+                    }
+                });
+            }
+        }
+    });
+    return issues;
+}
+function checkMarkdownQuality(content) {
+    const issues = [];
+    const lines = content.split("\n");
+    lines.forEach((line, index) => {
+        const lineNumber = index + 1;
+        // Check for trailing whitespace
+        if (line.endsWith(" ") || line.endsWith("\t")) {
+            issues.push({
+                severity: "info",
+                rule: "markdown-quality",
+                message: "Line has trailing whitespace",
+                line: lineNumber,
+            });
+        }
+        // Check for inconsistent heading markers
+        const headingMatch = line.match(/^(#{1,6})\s/);
+        if (headingMatch && line.includes("#", headingMatch[1].length + 1)) {
+            const afterHeading = line.substring(headingMatch[0].length);
+            if (!afterHeading.startsWith("#")) {
+                // Check if there's a # not at the start (could be an anchor)
+                if (afterHeading.includes("#") &&
+                    !afterHeading.match(/^#[a-z0-9._-]+/i)) {
+                    issues.push({
+                        severity: "warning",
+                        rule: "markdown-quality",
+                        message: "Unexpected # character in heading",
+                        line: lineNumber,
+                    });
+                }
+            }
+        }
+    });
+    return issues;
+}
+function checkFrontmatter(content) {
+    const issues = [];
+    const result = (0, shared_1.parseSpecificationFrontmatter)(content);
+    if (!result.hasFrontmatter) {
+        issues.push({
+            severity: "error",
+            rule: "frontmatter-required",
+            message: "Specification is missing required YAML frontmatter (delimited by --- markers)",
+        });
+        return issues;
+    }
+    if (result.errors?.length) {
+        for (const error of result.errors) {
+            issues.push({
+                severity: "error",
+                rule: "frontmatter-required",
+                message: `Frontmatter validation error: ${error}`,
+            });
+        }
+        return issues;
+    }
+    const fm = result.frontmatter;
+    if (!fm)
+        return issues;
+    // Check hint lengths
+    if (fm.hints) {
+        for (const [layer, hints] of Object.entries(fm.hints)) {
+            if (!hints)
+                continue;
+            for (let i = 0; i < hints.length; i++) {
+                if (hints[i].length > shared_1.HINT_MAX_LENGTH) {
+                    issues.push({
+                        severity: "error",
+                        rule: "frontmatter-required",
+                        message: `Hint hints.${layer}[${i}] exceeds ${shared_1.HINT_MAX_LENGTH} character limit (${hints[i].length} chars)`,
+                    });
+                }
+            }
+        }
+    }
+    // Check type-specific properties match declared type
+    const typeSpecific = ["capability", "architectural", "workflow", "operational"];
+    const present = typeSpecific.filter((t) => fm[t]);
+    if (present.length > 1) {
+        issues.push({
+            severity: "error",
+            rule: "frontmatter-required",
+            message: `Multiple type-specific properties found (${present.join(", ")}). Only one is allowed.`,
+        });
+    }
+    if (present.length === 1 && present[0] !== fm.type) {
+        issues.push({
+            severity: "warning",
+            rule: "frontmatter-required",
+            message: `Type-specific property "${present[0]}" does not match declared type "${fm.type}"`,
+        });
+    }
+    return issues;
+}
+function main(argv) {
+    const args = argv ?? process.argv.slice(2);
+    if ((0, cli_runtime_1.hasHelpFlag)(args)) {
+        printHelp();
+        return 0;
+    }
+    let filePath;
+    let options;
+    try {
+        ({ filePath, options } = parseArgs(args));
+    }
+    catch {
+        console.error("Error: Missing required argument <spec-file-path>");
+        printHelp();
+        return 1;
+    }
+    // Resolve file path
+    const resolvedPath = path.resolve(process.cwd(), filePath);
+    // Check if file exists
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(`Error: File not found: ${resolvedPath}`);
+        return 1;
+    }
+    // Read file content
+    let content;
+    try {
+        content = fs.readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        console.error(`Error reading file: ${(0, cli_runtime_1.errorMessage)(error)}`);
+        return 1;
+    }
+    let fixSummary = null;
+    if (options.fix) {
+        const fixed = applyDeterministicFixes(content);
+        const fileModified = fixed.content !== content;
+        if (fileModified) {
+            fs.writeFileSync(resolvedPath, fixed.content, "utf-8");
+            content = fixed.content;
+        }
+        fixSummary = {
+            attempted: true,
+            fixesApplied: fixed.fixesApplied,
+            fileModified,
+        };
+    }
+    // Extract anchors
+    const anchors = (0, agents_1.extractAnchors)(content);
+    console.log(`\nLinting ${path.basename(filePath)}...`);
+    console.log(`Found ${anchors.length} anchor(s)\n`);
+    // Run all lint checks
+    const issues = [
+        ...checkFrontmatter(content),
+        ...checkAnchorNaming(anchors),
+        ...checkDuplicateAnchors(anchors),
+        ...checkAcceptanceCriteria(content, anchors),
+        ...checkDependencyValidity(content, anchors),
+        ...checkMarkdownQuality(content),
+    ];
+    // Group issues by severity
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    const infos = issues.filter((i) => i.severity === "info");
+    // Display results
+    if (issues.length === 0) {
+        console.log("✓ No issues found. Specification is clean!\n");
+        return 0;
+    }
+    if (errors.length > 0) {
+        console.log(`\n❌ Errors (${errors.length}):\n`);
+        errors.forEach((issue, index) => {
+            console.log(`${index + 1}. [${issue.rule}] ${issue.message}`);
+            if (issue.anchor)
+                console.log(`   Anchor: ${issue.anchor}`);
+            if (issue.line)
+                console.log(`   Line: ${issue.line}`);
+            if (issue.suggestion && options.verbose)
+                console.log(`   Suggestion: ${issue.suggestion}`);
+            console.log();
+        });
+    }
+    if (warnings.length > 0) {
+        console.log(`\n⚠️  Warnings (${warnings.length}):\n`);
+        warnings.forEach((issue, index) => {
+            console.log(`${index + 1}. [${issue.rule}] ${issue.message}`);
+            if (issue.anchor)
+                console.log(`   Anchor: ${issue.anchor}`);
+            if (issue.line)
+                console.log(`   Line: ${issue.line}`);
+            if (issue.suggestion && options.verbose)
+                console.log(`   Suggestion: ${issue.suggestion}`);
+            console.log();
+        });
+    }
+    if (infos.length > 0 && options.verbose) {
+        console.log(`\nℹ️  Info (${infos.length}):\n`);
+        infos.forEach((issue, index) => {
+            console.log(`${index + 1}. [${issue.rule}] ${issue.message}`);
+            if (issue.anchor)
+                console.log(`   Anchor: ${issue.anchor}`);
+            if (issue.line)
+                console.log(`   Line: ${issue.line}`);
+            if (issue.suggestion)
+                console.log(`   Suggestion: ${issue.suggestion}`);
+            console.log();
+        });
+    }
+    // Summary
+    console.log("Summary:");
+    console.log(`  Errors: ${errors.length}`);
+    console.log(`  Warnings: ${warnings.length}`);
+    console.log(`  Info: ${infos.length}`);
+    if (fixSummary?.attempted) {
+        console.log(`  Fixes applied: ${fixSummary.fixesApplied}`);
+        console.log(`  File modified: ${fixSummary.fileModified ? "yes" : "no"}`);
+    }
+    console.log();
+    // Exit with error code if there are errors
+    if (errors.length > 0) {
+        console.log("❌ Linting failed due to errors.\n");
+        return 1;
+    }
+    else if (warnings.length > 0) {
+        console.log("⚠️  Linting passed with warnings.\n");
+        return 0;
+    }
+    else {
+        console.log("✓ Linting passed.\n");
+        return 0;
+    }
+}
+if (require.main === module) {
+    void (0, cli_runtime_1.runCliMain)(main, { errorPrefix: "spec-lint failed" });
+}

package/dist/spec-parse.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * spec-parse CLI Tool
+ *
+ * Parse specification markdown and extract all valid anchors.
+ *
+ * Usage: npm run spec-parse <spec-file-path>
+ * Example: npm run spec-parse specs/SPECIFICATION.md
+ */
+declare function main(argv?: string[]): number;
+export { main };

package/dist/spec-parse.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * spec-parse CLI Tool
+ *
+ * Parse specification markdown and extract all valid anchors.
+ *
+ * Usage: npm run spec-parse <spec-file-path>
+ * Example: npm run spec-parse specs/SPECIFICATION.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const agents_1 = require("@spekn/agents");
+const cli_runtime_1 = require("./utils/cli-runtime");
+function parseArgs(args) {
+    const options = {};
+    let filePath;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--verbose" || arg === "-v") {
+            options.verbose = true;
+        }
+        else if (arg === "--json" || arg === "-j") {
+            options.json = true;
+        }
+        else if (!arg.startsWith("-")) {
+            filePath = arg;
+        }
+    }
+    if (!filePath) {
+        throw new Error("missing required argument: <spec-file-path>");
+    }
+    return { filePath, options };
+}
+function printHelp() {
+    console.log(`
+spec-parse - Parse specification markdown and extract anchors
+
+USAGE:
+  npm run spec-parse <spec-file-path> [OPTIONS]
+
+ARGUMENTS:
+  <spec-file-path>    Path to the specification markdown file
+
+OPTIONS:
+  -v, --verbose       Show detailed output
+  -j, --json          Output in JSON format
+  -h, --help          Show this help message
+
+EXAMPLES:
+  npm run spec-parse specs/SPECIFICATION.md
+  npm run spec-parse specs/WORKFLOW.md --json
+  npm run spec-parse specs/DECISIONS.md --verbose
+`);
+}
+function main(argv) {
+    const args = argv ?? process.argv.slice(2);
+    if ((0, cli_runtime_1.hasHelpFlag)(args)) {
+        printHelp();
+        return 0;
+    }
+    let filePath;
+    let options;
+    try {
+        ({ filePath, options } = parseArgs(args));
+    }
+    catch {
+        console.error("Error: Missing required argument <spec-file-path>");
+        printHelp();
+        return 1;
+    }
+    // Resolve file path
+    const resolvedPath = path.resolve(process.cwd(), filePath);
+    // Check if file exists
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(`Error: File not found: ${resolvedPath}`);
+        return 1;
+    }
+    // Read file content
+    let content;
+    try {
+        content = fs.readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        console.error(`Error reading file: ${(0, cli_runtime_1.errorMessage)(error)}`);
+        return 1;
+    }
+    // Extract anchors
+    const anchors = (0, agents_1.extractAnchors)(content);
+    if (anchors.length === 0) {
+        console.log("No anchors found in the specification.");
+        return 0;
+    }
+    // Output results
+    if (options.json) {
+        console.log(JSON.stringify(anchors, null, 2));
+    }
+    else {
+        console.log(`\nFound ${anchors.length} anchor(s) in ${path.basename(filePath)}:\n`);
+        // Create table data
+        const tableData = anchors.map((anchor) => ({
+            Anchor: anchor.anchor,
+            Level: "H" + anchor.level,
+            Line: anchor.lineNumber,
+            Heading: options.verbose
+                ? anchor.headingText
+                : anchor.headingText.substring(0, 60) +
+                    (anchor.headingText.length > 60 ? "..." : ""),
+        }));
+        // Print table
+        console.table(tableData);
+        if (options.verbose) {
+            console.log("\nAnchor Details:");
+            anchors.forEach((anchor, index) => {
+                console.log(`\n${index + 1}. ${anchor.anchor}`);
+                console.log(`   Level: ${anchor.level}`);
+                console.log(`   Line: ${anchor.lineNumber}`);
+                console.log(`   Heading: ${anchor.headingText}`);
+            });
+        }
+        console.log(`\nTotal: ${anchors.length} anchor(s)\n`);
+    }
+    return 0;
+}
+if (require.main === module) {
+    void (0, cli_runtime_1.runCliMain)(main, { errorPrefix: "spec-parse failed" });
+}

package/dist/stubs/dotenv.d.ts

@@ -0,0 +1,5 @@
+export declare function config(): void;
+declare const _default: {
+    config: typeof config;
+};
+export default _default;

package/dist/stubs/dotenv.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = config;
+// No-op stub for dotenv — prevents noisy logs from bundled @spekn/shared code.
+function config() { }
+exports.default = { config };