cc-agentic-framework 1.14.1

package/dist/lib/link-validator.js

@@ -0,0 +1,504 @@
+/**
+ * Markdown Link Validator
+ *
+ * Validates markdown links and detects anti-patterns in framework documentation files.
+ * TypeScript implementation of Python link_validator.py algorithm.
+ *
+ * Features:
+ * - Detects broken file links
+ * - Identifies anti-patterns (backticked paths, unlinked references, plain paths)
+ * - Two-tier strictness (framework files vs content files)
+ * - Comprehensive path resolution (relative, absolute, project-relative)
+ *
+ * @module link-validator
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+/**
+ * Markdown Link Validator
+ *
+ * Validates markdown links in framework documentation with two-tier strictness:
+ * - Framework core files (.claude/, src/, core/, cli/) → critical errors
+ * - Content files (backlog/, docs/) → warnings only
+ *
+ * @example
+ * ```typescript
+ * const validator = new MarkdownLinkValidator('/path/to/framework');
+ * const result = await validator.validateFile('.claude/commands/architect.md');
+ * if (!result.valid) {
+ *   console.log(`Found ${result.brokenLinks.length} broken links`);
+ * }
+ * ```
+ */
+export class MarkdownLinkValidator {
+    /** Framework root directory */
+    frameworkRoot;
+    /** Framework core paths (critical) */
+    static FRAMEWORK_CORE_PATHS = [
+        ".claude/commands",
+        ".claude/context",
+        ".claude/framework",
+        ".claude/shared",
+        ".claude/skills",
+        ".claude/registries",
+        "core",
+        "cli/src",
+        "src/framework",
+        "src/guards",
+    ];
+    /** Framework root files (critical) */
+    static FRAMEWORK_ROOT_FILES = [
+        "CLAUDE.md",
+        "README.md",
+        "routes.yml",
+    ];
+    /** Content paths (non-critical warnings) */
+    static CONTENT_PATHS = [
+        "backlog",
+        "confluence",
+        "docs",
+        ".claude",
+    ];
+    /** Markdown link regex: [text](path) */
+    static LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/g;
+    /** Backticked path regex */
+    static BACKTICK_PATTERN = /`([a-zA-Z0-9_\-/]+\.md)`/g;
+    /** Unlinked "See:" reference regex */
+    static SEE_PATTERN = /See:\s+([a-zA-Z0-9_\-/]+\.md)/g;
+    /** Plain path in workflow regex */
+    static WORKFLOW_PATTERN = /[→▶]\s*([a-zA-Z0-9_\-/]+\.md)\s*[→▶]?/g;
+    /** Image file extensions to skip */
+    static IMAGE_EXTENSIONS = new Set([
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".svg",
+        ".gif",
+        ".webp",
+        ".bmp",
+        ".ico",
+    ]);
+    /** Placeholder paths to skip */
+    static PLACEHOLDERS = new Set([
+        "url",
+        "path",
+        "file",
+        "link",
+        "href",
+        "src",
+        // Example paths commonly used in documentation
+        "path/to/file.md",
+        "relative/path/file.md",
+        "path.md",
+        "../parent/file.md",
+        "./same/file.md",
+        "...",
+        // Jira example placeholders
+        "jira-url",
+        "confluence-url",
+    ]);
+    /** Example link text patterns that indicate documentation examples */
+    static EXAMPLE_LINK_TEXTS = new Set([
+        "text",
+        "link",
+        "link text",
+        "description",
+        "title",
+        "name",
+        "email",
+        "ftp",
+        "jira-url",
+    ]);
+    /** Template patterns to exclude from anti-pattern detection */
+    static TEMPLATE_PATTERNS = [
+        /STORY-[a-z0-9-]+\.md/i,
+        /TASK-[a-z0-9-]+\.md/i,
+        /BUG-[a-z0-9-]+\.md/i,
+        /SPIKE-[a-z0-9-]+\.md/i,
+        /EPIC-[a-z0-9-]+\.md/i,
+        /\d{4}-[a-z0-9-]+\.md/i,
+        /YYYY-WNN\.md/i,
+        /DAPM-XXXX[a-z0-9-]*\.md/i,
+        /\[TYPE\]-[a-z0-9-[\]]+\.md/i,
+        /\[number\]-[a-z0-9-[\]]+\.md/i,
+        /\{[a-z0-9-]+\}[a-z0-9-]*\.md/i,
+        /[a-z0-9-]+-template\.md/i,
+        /[a-z0-9-]+-GUIDE\.md/i,
+        /[a-z0-9-]+-INSTRUCTIONS\.md/i,
+        /[a-z0-9-]+-report-\d{4}-\d{2}\.md/i,
+        /[a-z0-9-]*status-\d{4}W\d{2}\.md/i,
+        /README\.md/i,
+    ];
+    /**
+     * Create a new MarkdownLinkValidator
+     *
+     * @param frameworkRoot - Absolute path to framework root directory
+     */
+    constructor(frameworkRoot) {
+        this.frameworkRoot = path.resolve(frameworkRoot);
+    }
+    /**
+     * Validate markdown links in a single file
+     *
+     * @param filePath - Absolute or relative path to markdown file
+     * @returns File validation result
+     * @throws Error if file cannot be read
+     */
+    async validateFile(filePath) {
+        const absPath = path.resolve(filePath);
+        // Check if file exists
+        try {
+            await fs.access(absPath);
+        }
+        catch (_error) {
+            throw new Error(`File not found: ${filePath}`, { cause: _error });
+        }
+        // Read file content
+        let content;
+        try {
+            content = await fs.readFile(absPath, "utf-8");
+        }
+        catch (error) {
+            throw new Error(`Error reading file ${filePath}: ${error}`, {
+                cause: error,
+            });
+        }
+        // Determine if framework file
+        const isFrameworkFile = this.isFrameworkFile(absPath);
+        // Find all markdown links
+        const links = this.findMarkdownLinks(content);
+        // Validate each link
+        const brokenLinks = [];
+        let linksChecked = 0;
+        for (const link of links) {
+            // Skip external URLs
+            if (this.isExternalUrl(link.target)) {
+                continue;
+            }
+            // Skip anchor-only links
+            if (link.target.startsWith("#")) {
+                continue;
+            }
+            // Skip image files (for MVP)
+            if (this.isImageFile(link.target)) {
+                continue;
+            }
+            // Skip placeholders
+            if (this.isPlaceholder(link.target)) {
+                continue;
+            }
+            // Skip documentation examples
+            if (this.isExampleLink(link.text, link.target)) {
+                continue;
+            }
+            linksChecked++;
+            // Resolve link path
+            const resolvedPath = this.resolveLinkPath(link.target, absPath);
+            // Check if target exists
+            const exists = await this.fileExists(resolvedPath);
+            if (!exists) {
+                brokenLinks.push({
+                    file: filePath,
+                    line: link.line,
+                    linkText: link.text,
+                    target: link.target,
+                    reason: `Target file not found: ${path.relative(this.frameworkRoot, resolvedPath)}`,
+                    resolvedPath,
+                });
+            }
+        }
+        // Detect anti-patterns
+        const antiPatterns = this.detectAntiPatterns(content, filePath);
+        const valid = brokenLinks.length === 0 && antiPatterns.length === 0;
+        return {
+            file: filePath,
+            isFrameworkFile,
+            valid,
+            brokenLinks,
+            antiPatterns,
+            linksChecked,
+        };
+    }
+    /**
+     * Validate markdown links in multiple files
+     *
+     * @param files - Array of file paths to validate
+     * @returns Aggregated validation result
+     */
+    async validateMarkdownLinks(files) {
+        const filesToValidate = files || [];
+        if (filesToValidate.length === 0) {
+            return {
+                valid: true,
+                brokenLinks: [],
+                antiPatterns: [],
+                filesChecked: 0,
+                linksChecked: 0,
+            };
+        }
+        const results = [];
+        for (const file of filesToValidate) {
+            try {
+                const result = await this.validateFile(file);
+                results.push(result);
+            }
+            catch (error) {
+                // Skip files that can't be read
+                console.error(`Error validating ${file}: ${error}`);
+            }
+        }
+        // Aggregate results
+        const brokenLinks = results.flatMap((r) => r.brokenLinks);
+        const antiPatterns = results.flatMap((r) => r.antiPatterns);
+        const linksChecked = results.reduce((sum, r) => sum + r.linksChecked, 0);
+        return {
+            valid: brokenLinks.length === 0 && antiPatterns.length === 0,
+            brokenLinks,
+            antiPatterns,
+            filesChecked: results.length,
+            linksChecked,
+        };
+    }
+    /**
+     * Find all markdown links in content
+     *
+     * @param content - Markdown content to scan
+     * @returns Array of detected markdown links
+     */
+    findMarkdownLinks(content) {
+        const links = [];
+        const lines = content.split("\n");
+        let inCodeBlock = false;
+        lines.forEach((line, index) => {
+            const lineNumber = index + 1;
+            // Toggle code block state
+            if (line.trim().startsWith("```")) {
+                inCodeBlock = !inCodeBlock;
+                return;
+            }
+            // Skip code blocks
+            if (inCodeBlock) {
+                return;
+            }
+            // Reset regex state
+            MarkdownLinkValidator.LINK_PATTERN.lastIndex = 0;
+            let match;
+            while ((match = MarkdownLinkValidator.LINK_PATTERN.exec(line)) !== null) {
+                const text = match[1];
+                const target = match[2];
+                links.push({
+                    text,
+                    target,
+                    line: lineNumber,
+                    columnStart: match.index,
+                    columnEnd: match.index + match[0].length,
+                });
+            }
+        });
+        return links;
+    }
+    /**
+     * Detect anti-patterns in markdown content
+     *
+     * @param content - Markdown content to scan
+     * @param filePath - Path to file (for reporting)
+     * @returns Array of detected anti-patterns
+     */
+    detectAntiPatterns(content, filePath) {
+        const antiPatterns = [];
+        const lines = content.split("\n");
+        let inCodeBlock = false;
+        lines.forEach((line, index) => {
+            const lineNumber = index + 1;
+            // Toggle code block state
+            if (line.trim().startsWith("```")) {
+                inCodeBlock = !inCodeBlock;
+                return;
+            }
+            // Skip code blocks
+            if (inCodeBlock) {
+                return;
+            }
+            // Detect backticked paths
+            MarkdownLinkValidator.BACKTICK_PATTERN.lastIndex = 0;
+            let match;
+            while ((match = MarkdownLinkValidator.BACKTICK_PATTERN.exec(line)) !== null) {
+                const mdPath = match[1];
+                // Skip template patterns
+                if (this.isTemplatePattern(mdPath)) {
+                    continue;
+                }
+                antiPatterns.push({
+                    file: filePath,
+                    line: lineNumber,
+                    patternType: "backticked_path",
+                    pattern: line.trim(),
+                    suggestion: `Replace \`${mdPath}\` with [${mdPath}](${mdPath})`,
+                });
+            }
+            // Detect unlinked "See:" references
+            MarkdownLinkValidator.SEE_PATTERN.lastIndex = 0;
+            while ((match = MarkdownLinkValidator.SEE_PATTERN.exec(line)) !== null) {
+                const mdPath = match[1];
+                antiPatterns.push({
+                    file: filePath,
+                    line: lineNumber,
+                    patternType: "unlinked_reference",
+                    pattern: line.trim(),
+                    suggestion: `Replace "See: ${mdPath}" with "See: [${mdPath}](${mdPath})"`,
+                });
+            }
+            // Detect plain paths in workflows
+            MarkdownLinkValidator.WORKFLOW_PATTERN.lastIndex = 0;
+            while ((match = MarkdownLinkValidator.WORKFLOW_PATTERN.exec(line)) !== null) {
+                const mdPath = match[1];
+                antiPatterns.push({
+                    file: filePath,
+                    line: lineNumber,
+                    patternType: "plain_path_in_workflow",
+                    pattern: line.trim(),
+                    suggestion: `Replace plain path with [${mdPath}](${mdPath})`,
+                });
+            }
+        });
+        return antiPatterns;
+    }
+    /**
+     * Check if a path is a template pattern (should not be flagged as anti-pattern)
+     *
+     * @param mdPath - Path to check
+     * @returns True if path matches a template pattern
+     */
+    isTemplatePattern(mdPath) {
+        return MarkdownLinkValidator.TEMPLATE_PATTERNS.some((pattern) => pattern.test(mdPath));
+    }
+    /**
+     * Resolve a link path to an absolute path
+     *
+     * Handles:
+     * - Relative paths: ../context/file.md
+     * - Project-relative absolute paths: /.claude/commands/file.md
+     * - Fully-qualified absolute paths: /Users/.../project/.claude/file.md
+     * - Anchor removal: file.md#section → file.md
+     * - URL decoding: my%20docs/file.md → my docs/file.md
+     *
+     * @param linkTarget - Link target path
+     * @param sourceFile - Absolute path to source file
+     * @returns Resolved absolute path
+     */
+    resolveLinkPath(linkTarget, sourceFile) {
+        // Remove anchor fragments
+        let targetPath = linkTarget.split("#")[0];
+        // URL decode (handle spaces)
+        try {
+            targetPath = decodeURIComponent(targetPath);
+        }
+        catch (_error) {
+            // If decoding fails, use original
+        }
+        // Handle fully-qualified absolute paths (start with framework root)
+        if (targetPath.startsWith(this.frameworkRoot)) {
+            return targetPath;
+        }
+        // Handle project-relative absolute paths (start with /)
+        if (targetPath.startsWith("/")) {
+            return path.join(this.frameworkRoot, targetPath.slice(1));
+        }
+        // Handle relative paths
+        const sourceDir = path.dirname(sourceFile);
+        return path.resolve(sourceDir, targetPath);
+    }
+    /**
+     * Check if a file exists
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if file exists
+     */
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch (_error) {
+            return false;
+        }
+    }
+    /**
+     * Check if a path is a framework core file (critical)
+     *
+     * @param filePath - Absolute path to check
+     * @returns True if framework core file
+     */
+    isFrameworkFile(filePath) {
+        const absPath = path.resolve(filePath);
+        // Check if in framework core directory
+        for (const corePath of MarkdownLinkValidator.FRAMEWORK_CORE_PATHS) {
+            const fullCorePath = path.join(this.frameworkRoot, corePath);
+            if (absPath.startsWith(fullCorePath)) {
+                return true;
+            }
+        }
+        // Check if root-level framework file
+        const fileName = path.basename(absPath);
+        const fileDir = path.dirname(absPath);
+        if (MarkdownLinkValidator.FRAMEWORK_ROOT_FILES.includes(fileName)) {
+            if (fileDir === this.frameworkRoot) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if a URL is external (HTTP/HTTPS) or uses another protocol
+     *
+     * @param url - URL to check
+     * @returns True if external URL or protocol link
+     */
+    isExternalUrl(url) {
+        return (url.startsWith("http://") ||
+            url.startsWith("https://") ||
+            url.startsWith("mailto:") ||
+            url.startsWith("ftp://") ||
+            url.startsWith("tel:"));
+    }
+    /**
+     * Check if a link appears to be a documentation example
+     *
+     * @param linkText - The text of the link
+     * @param target - The link target
+     * @returns True if link appears to be an example
+     */
+    isExampleLink(linkText, target) {
+        // Check if link text is a common example pattern
+        const normalizedText = linkText.toLowerCase().trim();
+        if (MarkdownLinkValidator.EXAMPLE_LINK_TEXTS.has(normalizedText)) {
+            return true;
+        }
+        // Check for ticket reference patterns like [DAPM-123](...)
+        if (/^[A-Z]+-\d+$/.test(linkText) && target === "...") {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if a path is an image file
+     *
+     * @param filePath - File path to check
+     * @returns True if image file
+     */
+    isImageFile(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return MarkdownLinkValidator.IMAGE_EXTENSIONS.has(ext);
+    }
+    /**
+     * Check if a path is a placeholder
+     *
+     * @param linkPath - Path to check
+     * @returns True if placeholder
+     */
+    isPlaceholder(linkPath) {
+        const normalized = linkPath.toLowerCase();
+        return MarkdownLinkValidator.PLACEHOLDERS.has(normalized);
+    }
+}
+//# sourceMappingURL=link-validator.js.map

package/dist/lib/link-validator.js.map

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

package/dist/lib/manifest-manager.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Framework manifest schema (.agentic-framework.json)
+ * Tracks installed framework version, modules, and project settings
+ */
+/**
+ * MCP configuration stored in manifest
+ */
+export interface McpManifestConfig {
+    enabled: boolean;
+    graphiti: {
+        enabled: boolean;
+        groupId: string;
+    };
+    serena: {
+        enabled: boolean;
+        projectName: string;
+        language: string;
+    };
+}
+export interface FrameworkManifest {
+    version: string;
+    framework: {
+        version: string;
+        cliVersion?: string;
+        installedAt: string;
+        updatedAt: string;
+        pinned?: boolean;
+    };
+    modules: Record<string, {
+        version: string;
+        installedAt: string;
+    }>;
+    projectSkills: string[];
+    settings: {
+        autoSyncSkills: boolean;
+        linkTransformation: boolean;
+    };
+    paths?: {
+        source?: string;
+        deployed?: string;
+        projectData?: string;
+    };
+    mcp?: McpManifestConfig;
+}
+/**
+ * Manages the framework manifest for a project
+ * Handles reading, writing, and updating .agentic-framework.json
+ */
+export declare class ManifestManager {
+    private projectPath;
+    private readonly manifestFileName;
+    /**
+     * Create a new ManifestManager instance
+     * @param projectPath - Root path of the project
+     */
+    constructor(projectPath: string);
+    /**
+     * Check if manifest exists in the project
+     * @returns true if manifest file exists, false otherwise
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Read the manifest from disk
+     * @returns The parsed FrameworkManifest
+     * @throws Error if manifest does not exist or JSON is invalid
+     */
+    read(): Promise<FrameworkManifest>;
+    /**
+     * Write the manifest to disk
+     * @param manifest - The FrameworkManifest to write
+     * @throws Error if write operation fails
+     */
+    write(manifest: FrameworkManifest): Promise<void>;
+    /**
+     * Create a new manifest with default values
+     * @param frameworkVersion - The version of the framework being installed
+     * @param modules - Array of module IDs to include in the manifest
+     * @returns The newly created FrameworkManifest
+     */
+    create(frameworkVersion: string, modules: string[]): Promise<FrameworkManifest>;
+    /**
+     * Get the full path to the manifest file
+     * @returns Absolute path to .agentic-framework.json
+     */
+    getManifestPath(): string;
+    /**
+     * Add a module to the manifest
+     * @param moduleId - Unique identifier for the module
+     * @param version - Version of the module being added
+     * @throws Error if manifest does not exist or write fails
+     */
+    addModule(moduleId: string, version: string): Promise<void>;
+    /**
+     * Remove a module from the manifest
+     * @param moduleId - Unique identifier for the module to remove
+     * @throws Error if manifest does not exist or write fails
+     */
+    removeModule(moduleId: string): Promise<void>;
+    /**
+     * Update the framework version in the manifest
+     * @param version - New framework version
+     * @throws Error if manifest does not exist or write fails
+     */
+    updateFrameworkVersion(version: string): Promise<void>;
+    /**
+     * Register a project-specific skill path in the manifest
+     * @param skillPath - File system path to the project skill
+     * @throws Error if manifest does not exist or write fails
+     */
+    registerProjectSkill(skillPath: string): Promise<void>;
+}
+//# sourceMappingURL=manifest-manager.d.ts.map

package/dist/lib/manifest-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-manager.d.ts","sourceRoot":"","sources":["../../src/lib/manifest-manager.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,OAAO,EAAE,MAAM,CACb,MAAM,EACN;QACE,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB,CACF,CAAC;IACF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE;QACR,cAAc,EAAE,OAAO,CAAC;QACxB,kBAAkB,EAAE,OAAO,CAAC;KAC7B,CAAC;IACF,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,eAAe;IAOd,OAAO,CAAC,WAAW;IAN/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D;;;OAGG;gBACiB,WAAW,EAAE,MAAM;IAEvC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAKhC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAoBxC;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvD;;;;;OAKG;IACG,MAAM,CACV,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,iBAAiB,CAAC;IA8B7B;;;OAGG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjE;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnD;;;;OAIG;IACG,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5D;;;;OAIG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAa7D"}