cc-agentic-framework 1.14.1

package/dist/lib/sync-engine.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Sync Engine Module
+ *
+ * Synchronizes skills and agents from module source directories to deployment
+ * directories (.claude/skills/ and .claude/commands/). Uses LinkTransformer to
+ * transform markdown links during sync.
+ *
+ * Usage:
+ *     const engine = new SyncEngine('/path/to/framework', '/path/to/project');
+ *     const modules = await loadAllModules();
+ *     const report = await engine.syncAll(modules);
+ *
+ * Project structure managed:
+ *     project/
+ *     ├── .claude/skills/project/      # Project-owned skills (synced TO .claude/skills/)
+ *     ├── .claude/skills/              # Target for framework + project skills
+ *     ├── .claude/commands/            # Target for agents (slash commands)
+ *     └── .claude/agents/             # Target for agents (Task tool invocation)
+ *
+ * Module structure synced FROM:
+ *     core/
+ *     ├── agents/ai-*.md            # Agents to sync
+ *     └── skills/shared/*           # Skills to sync (taxonomy structure)
+ */
+import { type ModuleManifest } from "./module-loader.js";
+export interface SyncReport {
+    skills: SyncItem[];
+    agents: SyncItem[];
+    commands: SyncItem[];
+    hooks: SyncItem[];
+    statusline?: SyncItem;
+    config?: ConfigSyncResult;
+    errors: SyncError[];
+    stats: {
+        skillsSynced: number;
+        agentsSynced: number;
+        commandsSynced: number;
+        hooksSynced: number;
+        errors: number;
+    };
+}
+export interface SyncCheckResult {
+    inSync: boolean;
+    skillsNeedSync: string[];
+    agentsNeedSync: string[];
+    commandsNeedSync: string[];
+    projectSkillsNeedSync: string[];
+}
+export interface SyncItem {
+    name: string;
+    source: string;
+    target: string;
+    action: "created" | "updated" | "skipped";
+}
+export interface SyncError {
+    item: string;
+    error: string;
+}
+export interface SyncValidationViolation {
+    file: string;
+    line: number;
+    match: string;
+    context: string;
+}
+export interface ConfigSyncResult {
+    agenticFramework: "created" | "updated" | "skipped";
+    settingsLocal: "created" | "skipped";
+    settingsJson: "created" | "updated" | "skipped";
+}
+/**
+ * Synchronizes skills and agents from modules to deployment directories.
+ *
+ * The SyncEngine handles:
+ * - Copying skills from module taxonomy structures to flat .claude/skills/
+ * - Copying agents to .claude/commands/
+ * - Copying project skills from .claude/skills/project/ to .claude/skills/
+ * - Transforming markdown links in all .md files using LinkTransformer
+ * - Reporting all sync actions and errors
+ */
+export declare class SyncEngine {
+    /** Files to skip during sync operations */
+    private static readonly SKIP_FILES;
+    /**
+     * Folders in .claude/ that are protected from deletion during sync operations.
+     * These folders contain user-owned data that must never be removed.
+     */
+    private static readonly PROTECTED_FOLDERS;
+    /**
+     * Check if a path is a protected folder that should never be deleted.
+     *
+     * @param folderPath - Path relative to .claude/ directory
+     * @returns True if the folder is protected
+     */
+    static isProtectedFolder(folderPath: string): boolean;
+    private readonly frameworkRoot;
+    private readonly projectPath;
+    private readonly linkTransformer;
+    /**
+     * Initialize the SyncEngine.
+     *
+     * @param frameworkRoot - Absolute path to the framework root directory
+     * @param projectPath - Absolute path to the project directory
+     */
+    constructor(frameworkRoot: string, projectPath: string);
+    /**
+     * Sync all skills from installed modules to .claude/skills/.
+     *
+     * Processes each module's skills/ directory, recursively copies skill
+     * directories to a flat structure in .claude/skills/, and transforms all
+     * markdown links.
+     *
+     * @param modules - List of installed module manifests
+     * @returns List of sync actions performed
+     */
+    syncSkills(modules: ModuleManifest[]): Promise<SyncItem[]>;
+    /**
+     * Sync all agents from installed modules to .claude/commands/ and .claude/agents/.
+     *
+     * Copies all ai-*.md agent files from each module's agents/ directory
+     * to both .claude/commands/ (for slash commands) and .claude/agents/
+     * (for programmatic Task tool invocation), transforming markdown links
+     * in the process.
+     *
+     * @param modules - List of installed module manifests
+     * @returns List of sync actions performed
+     */
+    syncAgents(modules: ModuleManifest[]): Promise<SyncItem[]>;
+    /**
+     * Sync all CLI command wrappers from installed modules to .claude/commands/.
+     *
+     * Copies all cmd-*.md command files from each module's commands/ directory
+     * to .claude/commands/, transforming markdown links in the process.
+     *
+     * @param modules - List of installed module manifests
+     * @returns List of sync actions performed
+     */
+    syncCommands(modules: ModuleManifest[]): Promise<SyncItem[]>;
+    /**
+     * Sync project skills from .claude/skills/project/ to .claude/skills/.
+     *
+     * Project skills are skills owned by the project (not from framework modules).
+     * They are synced alongside framework skills to .claude/skills/.
+     *
+     * @returns List of sync actions performed
+     */
+    syncProjectSkills(): Promise<SyncItem[]>;
+    /**
+     * Sync module templates to .claude/templates/{module}/.
+     *
+     * Each module may have a templates/ directory at its root containing
+     * template files (e.g., world templates for writer module). These are
+     * deployed to .claude/templates/{module-id}/ for use by CLI commands.
+     *
+     * @param modules - List of installed module manifests
+     * @returns List of sync actions performed
+     */
+    syncTemplates(modules: ModuleManifest[]): Promise<SyncItem[]>;
+    /**
+     * Sync module schemas to .claude/registries/schemas/{module}/.
+     *
+     * Schemas are JSON schema files used by modules for validation.
+     * Each module's schemas are copied to a module-specific subdirectory
+     * in .claude/registries/schemas/.
+     *
+     * @param modules - List of installed module manifests
+     * @returns List of sync actions performed
+     */
+    syncSchemas(modules: ModuleManifest[]): Promise<SyncItem[]>;
+    /**
+     * Sync hooks to .claude/hooks/.
+     *
+     * Core hooks are ALWAYS deployed from the framework (regardless of installed modules).
+     * Additional module-specific hooks can be provided by installed modules.
+     * These hooks integrate with Claude Code's hook system.
+     *
+     * @param modules - List of installed module manifests (for module-specific hooks)
+     * @returns List of sync actions performed
+     */
+    syncHooks(modules: ModuleManifest[]): Promise<SyncItem[]>;
+    /**
+     * Sync statusline script to .claude/statusline.sh.
+     *
+     * The statusline provides real-time feedback in the Claude Code status bar.
+     * This is framework infrastructure that should always be updated during sync.
+     *
+     * @returns Sync item indicating action taken
+     */
+    syncStatusline(): Promise<SyncItem>;
+    /**
+     * Sync configuration files.
+     *
+     * Updates .agentic-framework.json with lastSyncAt timestamp and creates
+     * .claude/settings.local.json if it doesn't exist (preserves user customizations).
+     *
+     * @returns Config sync result indicating actions taken
+     */
+    syncConfig(): Promise<ConfigSyncResult>;
+    /**
+     * Sync framework-owned settings.json with hook configurations.
+     * Always overwrites hooks but preserves non-hook keys from existing file.
+     */
+    syncSettingsJson(): Promise<"created" | "updated">;
+    /**
+     * Check if sync is needed without making changes.
+     *
+     * Compares source files with deployed files to determine if synchronization
+     * is required. Used by pre-commit hooks to validate that deployment files
+     * are up to date.
+     *
+     * @param modules - List of installed module manifests
+     * @returns Check result indicating if sync is needed
+     */
+    checkSync(modules: ModuleManifest[]): Promise<SyncCheckResult>;
+    /**
+     * Check if deployed files are missing (regardless of content).
+     *
+     * Detects when files have been deleted from .claude/ but modules
+     * are still registered in the manifest.
+     *
+     * @param modules - List of installed module manifests
+     * @returns Lists of missing skills, agents, and commands
+     */
+    checkMissingFiles(modules: ModuleManifest[]): Promise<{
+        missingSkills: string[];
+        missingAgents: string[];
+        missingCommands: string[];
+    }>;
+    /**
+     * Run full sync (skills + agents + project skills).
+     *
+     * Performs a complete synchronization of all framework skills, agents, and
+     * project skills to their deployment directories.
+     *
+     * @param modules - List of installed module manifests
+     * @returns Complete sync report with all actions and errors
+     */
+    syncAll(modules: ModuleManifest[]): Promise<SyncReport>;
+    /**
+     * Find all skill directories within a source directory.
+     *
+     * Skills may be nested in taxonomy structures (shared/, core/, etc.).
+     * This method recursively finds all directories that contain SKILL.md files.
+     *
+     * @param sourceDir - Root directory to search for skills
+     * @returns List of absolute paths to skill directories
+     */
+    private findSkillDirectories;
+    /**
+     * Find all agent files within a source directory.
+     *
+     * Agent files follow the ai-*.md naming pattern.
+     *
+     * @param sourceDir - Directory to search for agent files
+     * @returns List of absolute paths to agent files
+     */
+    private findAgentFiles;
+    /**
+     * Read the deploy-to field from an agent markdown file's YAML frontmatter.
+     * Returns 'both' if field is absent (backward-compatible default).
+     */
+    private getAgentDeployTarget;
+    /**
+     * Find all command files within a source directory.
+     *
+     * Command files follow the cmd-*.md naming pattern.
+     *
+     * @param sourceDir - Directory to search for command files
+     * @returns List of absolute paths to command files
+     */
+    private findCommandFiles;
+    /**
+     * Copy a skill directory to the target location.
+     *
+     * Recursively copies all files in the skill directory, skipping special files
+     * (.DS_Store, etc.) and transforming markdown links in .md files.
+     *
+     * @param source - Source skill directory
+     * @param target - Target deployment directory
+     */
+    private copySkillDirectory;
+    /**
+     * Copy a template directory to the target location.
+     *
+     * Recursively copies all files in the template directory, skipping special files
+     * (.DS_Store, etc.). Template files are copied as-is without link transformation.
+     *
+     * @param source - Source template directory
+     * @param target - Target deployment directory
+     */
+    private copyTemplateDirectory;
+    /**
+     * Copy an agent file to the target location.
+     *
+     * Copies the agent file and transforms markdown links.
+     *
+     * @param source - Source agent file path
+     * @param target - Target deployment file path
+     */
+    private copyAgentFile;
+    /**
+     * Transform markdown links in a file and write to target.
+     *
+     * Uses LinkTransformer to transform relative links to absolute paths,
+     * ensuring links remain valid in the deployment location.
+     *
+     * @param sourcePath - Source file path
+     * @param targetPath - Target file path
+     */
+    private transformMarkdownLinks;
+    /**
+     * Check if a file is in sync between source and target.
+     *
+     * Compares the transformed content of the source file with the target file.
+     * For markdown files, applies link transformation before comparison.
+     *
+     * @param sourcePath - Source file path
+     * @param targetPath - Target file path
+     * @returns True if files are in sync, false otherwise
+     */
+    private isFileInSync;
+    /**
+     * Check if a directory is in sync between source and target.
+     *
+     * Recursively compares all files in the directory, accounting for
+     * transformed markdown links.
+     *
+     * @param sourceDir - Source directory path
+     * @param targetDir - Target directory path
+     * @returns True if directories are in sync, false otherwise
+     */
+    private isDirectoryInSync;
+    /**
+     * Validate synced output files for hardcoded absolute paths.
+     *
+     * This method ensures that no hardcoded user-specific absolute paths
+     * (like /Users/username/...) remain in synced files. These paths indicate
+     * that source files were not properly updated to use {project} placeholders.
+     *
+     * @param syncedItems - List of items that were synced
+     * @throws Error if any violations are detected
+     */
+    validateSyncOutput(syncedItems: SyncItem[]): Promise<void>;
+}
+//# sourceMappingURL=sync-engine.d.ts.map

package/dist/lib/sync-engine.d.ts.map

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