cc-agentic-framework 1.14.1

package/dist/lib/cleanup-engine.js

@@ -0,0 +1,252 @@
+/**
+ * Cleanup Engine Module
+ *
+ * Symmetric counterpart to SyncEngine - removes module artifacts during module removal.
+ * Handles comprehensive cleanup of all synced resources:
+ * - Agents from .claude/commands/ and .claude/agents/
+ * - Skills from .claude/skills/
+ * - Templates from .claude/templates/{moduleId}/
+ * - Schemas from .claude/registries/schemas/{moduleId}/
+ * - Scripts from src/{moduleId}/
+ *
+ * Usage:
+ *     const engine = new CleanupEngine('/path/to/project', false);
+ *     const preview = await engine.previewCleanup(module);
+ *     const result = await engine.cleanupModule(module);
+ */
+import fs from "fs-extra";
+import path from "path";
+/**
+ * Removes module artifacts during module removal.
+ *
+ * The CleanupEngine handles:
+ * - Removing agents from .claude/commands/ and .claude/agents/
+ * - Removing skills from .claude/skills/ (with sharing warnings)
+ * - Removing templates from .claude/templates/{moduleId}/
+ * - Removing schemas from .claude/registries/schemas/{moduleId}/
+ * - Removing scripts from src/{moduleId}/
+ */
+export class CleanupEngine {
+    /** Files to skip during cleanup operations */
+    static SKIP_FILES = new Set([
+        ".DS_Store",
+        ".gitkeep",
+        ".gitignore",
+        "Thumbs.db",
+    ]);
+    /**
+     * Folders in .claude/ that are protected from deletion during cleanup operations.
+     * These folders contain user-owned data that must never be removed.
+     */
+    static PROTECTED_FOLDERS = new Set(["context", "hooks"]);
+    /**
+     * 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) {
+        const normalizedPath = folderPath
+            .replace(/^\.claude\//, "")
+            .replace(/\/$/, "");
+        return CleanupEngine.PROTECTED_FOLDERS.has(normalizedPath);
+    }
+    projectPath;
+    dryRun;
+    /**
+     * Initialize the CleanupEngine.
+     *
+     * @param projectPath - Absolute path to the project directory
+     * @param dryRun - If true, preview operations without making changes
+     */
+    constructor(projectPath, dryRun = false) {
+        this.projectPath = path.resolve(projectPath);
+        this.dryRun = dryRun;
+    }
+    /**
+     * Preview cleanup operations for a module without making changes.
+     *
+     * @param module - Module manifest to preview cleanup for
+     * @returns Preview showing what would be removed and any warnings
+     */
+    async previewCleanup(module) {
+        const preview = {
+            agents: [],
+            skills: [],
+            templates: [],
+            schemas: [],
+            scripts: [],
+            warnings: [],
+        };
+        // Preview agents
+        if (module.provides.agents) {
+            preview.agents = module.provides.agents;
+        }
+        // Preview skills (and add sharing warning)
+        if (module.provides.skills) {
+            preview.skills = module.provides.skills;
+            preview.warnings.push(`Skills may be shared with other modules. If another module provides the same skill name, it will need to be re-added.`);
+        }
+        // Preview templates
+        const templatesDir = path.join(this.projectPath, ".claude/templates", module.id);
+        if (await fs.pathExists(templatesDir)) {
+            preview.templates = [`.claude/templates/${module.id}/`];
+        }
+        // Preview schemas
+        const schemasDir = path.join(this.projectPath, ".claude/registries/schemas", module.id);
+        if (await fs.pathExists(schemasDir)) {
+            preview.schemas = [`.claude/registries/schemas/${module.id}/`];
+        }
+        // Preview scripts
+        const scriptsDir = path.join(this.projectPath, "src", module.id);
+        if (await fs.pathExists(scriptsDir)) {
+            preview.scripts = [`src/${module.id}/`];
+        }
+        return preview;
+    }
+    /**
+     * Clean up all artifacts for a module.
+     *
+     * @param module - Module manifest
+     * @returns Combined result of all cleanup operations
+     */
+    async cleanupModule(module) {
+        const allFiles = [];
+        const allDirectories = [];
+        // Clean up agents
+        const agentsResult = await this.cleanupAgents(module.provides.agents || []);
+        allFiles.push(...agentsResult.files);
+        allDirectories.push(...agentsResult.directories);
+        // Clean up skills
+        const skillsResult = await this.cleanupSkills(module.provides.skills || []);
+        allFiles.push(...skillsResult.files);
+        allDirectories.push(...skillsResult.directories);
+        // Clean up templates
+        const templatesResult = await this.cleanupTemplates(module.id);
+        allFiles.push(...templatesResult.files);
+        allDirectories.push(...templatesResult.directories);
+        // Clean up schemas
+        const schemasResult = await this.cleanupSchemas(module.id);
+        allFiles.push(...schemasResult.files);
+        allDirectories.push(...schemasResult.directories);
+        // Clean up scripts
+        const scriptsResult = await this.cleanupScripts(module.id);
+        allFiles.push(...scriptsResult.files);
+        allDirectories.push(...scriptsResult.directories);
+        return {
+            files: allFiles,
+            directories: allDirectories,
+        };
+    }
+    /**
+     * Remove agents from both .claude/commands/ and .claude/agents/.
+     *
+     * @param agentIds - List of agent IDs to remove (e.g., 'ai-framework-manager')
+     * @returns List of removed files and directories
+     */
+    async cleanupAgents(agentIds) {
+        const files = [];
+        const directories = [];
+        for (const agentId of agentIds) {
+            // Remove from .claude/commands/ (slash commands)
+            const commandPath = path.join(this.projectPath, ".claude/commands", `${agentId}.md`);
+            if (await fs.pathExists(commandPath)) {
+                if (!this.dryRun) {
+                    await fs.remove(commandPath);
+                }
+                files.push(path.relative(this.projectPath, commandPath));
+            }
+            // Remove from .claude/agents/ (Task tool invocation)
+            const agentPath = path.join(this.projectPath, ".claude/agents", `${agentId}.md`);
+            if (await fs.pathExists(agentPath)) {
+                if (!this.dryRun) {
+                    await fs.remove(agentPath);
+                }
+                files.push(path.relative(this.projectPath, agentPath));
+            }
+        }
+        return { files, directories };
+    }
+    /**
+     * Remove skills from .claude/skills/.
+     *
+     * Skills are deployed flat by skill name, so removal is straightforward.
+     * Warning: Multiple modules may provide skills with the same name.
+     *
+     * @param skillNames - List of skill names to remove
+     * @returns List of removed files and directories
+     */
+    async cleanupSkills(skillNames) {
+        const files = [];
+        const directories = [];
+        for (const skillName of skillNames) {
+            const skillDir = path.join(this.projectPath, ".claude/skills", skillName);
+            if (await fs.pathExists(skillDir)) {
+                if (!this.dryRun) {
+                    await fs.remove(skillDir);
+                }
+                directories.push(path.relative(this.projectPath, skillDir));
+            }
+        }
+        return { files, directories };
+    }
+    /**
+     * Remove templates from .claude/templates/{moduleId}/.
+     *
+     * Each module's templates are in a module-specific subdirectory.
+     *
+     * @param moduleId - Module ID
+     * @returns List of removed files and directories
+     */
+    async cleanupTemplates(moduleId) {
+        const files = [];
+        const directories = [];
+        const templatesDir = path.join(this.projectPath, ".claude/templates", moduleId);
+        if (await fs.pathExists(templatesDir)) {
+            if (!this.dryRun) {
+                await fs.remove(templatesDir);
+            }
+            directories.push(path.relative(this.projectPath, templatesDir));
+        }
+        return { files, directories };
+    }
+    /**
+     * Remove schemas from .claude/registries/schemas/{moduleId}/.
+     *
+     * Each module's schemas are in a module-specific subdirectory.
+     *
+     * @param moduleId - Module ID
+     * @returns List of removed files and directories
+     */
+    async cleanupSchemas(moduleId) {
+        const files = [];
+        const directories = [];
+        const schemasDir = path.join(this.projectPath, ".claude/registries/schemas", moduleId);
+        if (await fs.pathExists(schemasDir)) {
+            if (!this.dryRun) {
+                await fs.remove(schemasDir);
+            }
+            directories.push(path.relative(this.projectPath, schemasDir));
+        }
+        return { files, directories };
+    }
+    /**
+     * Remove scripts from src/{moduleId}/.
+     *
+     * @param moduleId - Module ID
+     * @returns List of removed files and directories
+     */
+    async cleanupScripts(moduleId) {
+        const files = [];
+        const directories = [];
+        const scriptsDir = path.join(this.projectPath, "src", moduleId);
+        if (await fs.pathExists(scriptsDir)) {
+            if (!this.dryRun) {
+                await fs.remove(scriptsDir);
+            }
+            directories.push(path.relative(this.projectPath, scriptsDir));
+        }
+        return { files, directories };
+    }
+}
+//# sourceMappingURL=cleanup-engine.js.map

package/dist/lib/cleanup-engine.js.map

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

package/dist/lib/cli-context.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Unified CLI Context
+ *
+ * Combines project resolution and path resolution into a single, easy-to-use API
+ * for all CLI commands. Provides both async and sync variants, with caching support.
+ *
+ * @module cli-context
+ */
+import { type DetectionMethod } from './project-resolver.js';
+import { type PathResolver } from './path-resolver.js';
+import type { FrameworkManifest } from './manifest-manager.js';
+export * from './project-resolver.js';
+export * from './path-resolver.js';
+/**
+ * Options for creating a CLI context
+ */
+export interface CliContextOptions {
+    /**
+     * Explicit project path (overrides auto-detection).
+     * If provided, the context will be created for this path directly
+     * without walking up the directory tree.
+     */
+    path?: string;
+    /**
+     * If true, don't use cached context.
+     * Forces a fresh filesystem scan for project detection.
+     */
+    fresh?: boolean;
+}
+/**
+ * Extended options for getCliContext helper functions
+ */
+export interface GetCliContextOptions extends CliContextOptions {
+    /**
+     * If true, the function will log an error and exit the process
+     * when not inside a valid project. Otherwise returns null.
+     */
+    required?: boolean;
+}
+/**
+ * Unified CLI context providing project detection and path resolution.
+ *
+ * This class combines the functionality of project-resolver and path-resolver
+ * into a single, easy-to-use API. It provides:
+ *
+ * - Project root detection with multiple strategies
+ * - Framework manifest access (if present)
+ * - Semantic path resolution via routes.yml
+ * - Both async and sync variants
+ *
+ * @example
+ * ```typescript
+ * // In a command handler:
+ * const ctx = await CliContext.require();
+ * const ticketsDir = ctx.paths.getTicketPath('story');
+ * console.log(`Creating ticket in: ${ticketsDir}`);
+ *
+ * // Check if inside a project (without throwing):
+ * const ctx = await CliContext.create();
+ * if (ctx.isInsideProject) {
+ *   console.log(`Project found at: ${ctx.projectRoot}`);
+ * }
+ *
+ * // Use explicit path:
+ * const ctx = await CliContext.create({ path: '/path/to/project' });
+ * ```
+ */
+export declare class CliContext {
+    /**
+     * Absolute path to the project root directory.
+     * This is always set, even if not inside a project (falls back to cwd).
+     */
+    readonly projectRoot: string;
+    /**
+     * Parsed framework manifest (.agentic-framework.json), or null if not found.
+     */
+    readonly manifest: FrameworkManifest | null;
+    /**
+     * Whether we found a valid project with framework markers.
+     * If false, projectRoot falls back to cwd or provided path.
+     */
+    readonly isInsideProject: boolean;
+    /**
+     * Method used to detect the project root.
+     * - 'manifest': Found .agentic-framework.json
+     * - 'routes': Found routes.yml + CLAUDE.md
+     * - 'git+claude': Found .git + CLAUDE.md
+     * - 'cwd': No markers found
+     */
+    readonly detectionMethod: DetectionMethod;
+    /**
+     * Path resolver for semantic path resolution.
+     * Provides methods like getTicketPath(), getPlanPath(), etc.
+     */
+    readonly paths: PathResolver;
+    /**
+     * Private constructor - use static factory methods instead.
+     */
+    private constructor();
+    /**
+     * Create a CLI context asynchronously.
+     *
+     * This is the preferred method for most use cases as it allows
+     * parallel filesystem operations during project detection.
+     *
+     * @param options - Optional configuration for context creation
+     * @returns Promise resolving to a CliContext instance
+     *
+     * @example
+     * ```typescript
+     * const ctx = await CliContext.create();
+     * if (ctx.isInsideProject) {
+     *   console.log(`Found project at: ${ctx.projectRoot}`);
+     *   console.log(`Detection method: ${ctx.detectionMethod}`);
+     * }
+     * ```
+     */
+    static create(options?: CliContextOptions): Promise<CliContext>;
+    /**
+     * Create a CLI context synchronously.
+     *
+     * Use this when you need the context immediately and cannot use async/await,
+     * such as in synchronous command handlers or initialization code.
+     *
+     * @param options - Optional configuration for context creation
+     * @returns CliContext instance
+     *
+     * @example
+     * ```typescript
+     * const ctx = CliContext.createSync();
+     * console.log(`Project root: ${ctx.projectRoot}`);
+     * ```
+     */
+    static createSync(options?: CliContextOptions): CliContext;
+    /**
+     * Create a CLI context asynchronously, throwing if not inside a project.
+     *
+     * Use this when your command requires being inside a valid project.
+     * Provides a clear error message guiding users to run `init`.
+     *
+     * @param options - Optional configuration for context creation
+     * @returns Promise resolving to a CliContext instance
+     * @throws ProjectNotFoundError if not inside a project
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const ctx = await CliContext.require();
+     *   // Guaranteed to have isInsideProject: true
+     *   const storiesDir = ctx.paths.getTicketPath('story');
+     *   console.log(`Working in: ${storiesDir}`);
+     * } catch (error) {
+     *   if (error instanceof ProjectNotFoundError) {
+     *     console.error(error.message);
+     *     process.exit(1);
+     *   }
+     * }
+     * ```
+     */
+    static require(options?: CliContextOptions): Promise<CliContext>;
+    /**
+     * Create a CLI context synchronously, throwing if not inside a project.
+     *
+     * Synchronous version of `require()` for use in sync command handlers.
+     *
+     * @param options - Optional configuration for context creation
+     * @returns CliContext instance
+     * @throws ProjectNotFoundError if not inside a project
+     *
+     * @example
+     * ```typescript
+     * const ctx = CliContext.requireSync();
+     * console.log(`Working in project: ${ctx.projectRoot}`);
+     * ```
+     */
+    static requireSync(options?: CliContextOptions): CliContext;
+    /**
+     * Check if a specific module is installed in this project.
+     *
+     * @param moduleId - The module identifier to check
+     * @returns true if the module is installed
+     *
+     * @example
+     * ```typescript
+     * const ctx = await CliContext.require();
+     * if (ctx.hasModule('backlog')) {
+     *   console.log('Backlog module is installed');
+     * }
+     * ```
+     */
+    hasModule(moduleId: string): boolean;
+    /**
+     * Get the version of a specific installed module.
+     *
+     * @param moduleId - The module identifier
+     * @returns Module version string, or null if not installed
+     *
+     * @example
+     * ```typescript
+     * const ctx = await CliContext.require();
+     * const version = ctx.getModuleVersion('planning');
+     * if (version) {
+     *   console.log(`Planning module version: ${version}`);
+     * }
+     * ```
+     */
+    getModuleVersion(moduleId: string): string | null;
+    /**
+     * Get all installed module IDs.
+     *
+     * @returns Array of installed module identifiers
+     *
+     * @example
+     * ```typescript
+     * const ctx = await CliContext.require();
+     * const modules = ctx.getInstalledModules();
+     * console.log(`Installed modules: ${modules.join(', ')}`);
+     * ```
+     */
+    getInstalledModules(): string[];
+    /**
+     * Get the framework version for this project.
+     *
+     * @returns Framework version string, or null if no manifest
+     *
+     * @example
+     * ```typescript
+     * const ctx = await CliContext.require();
+     * console.log(`Framework version: ${ctx.getFrameworkVersion()}`);
+     * ```
+     */
+    getFrameworkVersion(): string | null;
+}
+/**
+ * Get CLI context with standard error handling.
+ *
+ * This is a convenience function for command handlers that provides
+ * consistent error handling. When `required: true` is set and the
+ * context cannot be found, it logs an error and exits the process.
+ *
+ * @param options - Configuration options including `required` flag
+ * @returns Promise resolving to CliContext, or null if not found and not required
+ *
+ * @example
+ * ```typescript
+ * // In a command handler that requires being in a project:
+ * const ctx = await getCliContext({ required: true });
+ * // If we get here, ctx is guaranteed to be non-null
+ * const ticketsDir = ctx!.paths.getTicketPath('story');
+ *
+ * // In a command that works without a project:
+ * const ctx = await getCliContext();
+ * if (ctx?.isInsideProject) {
+ *   console.log('Found project context');
+ * } else {
+ *   console.log('Working without project context');
+ * }
+ * ```
+ */
+export declare function getCliContext(options?: GetCliContextOptions): Promise<CliContext | null>;
+/**
+ * Get CLI context synchronously with standard error handling.
+ *
+ * Synchronous version of getCliContext for use in sync command handlers.
+ *
+ * @param options - Configuration options including `required` flag
+ * @returns CliContext, or null if not found and not required
+ *
+ * @example
+ * ```typescript
+ * const ctx = getCliContextSync({ required: true });
+ * console.log(`Project: ${ctx!.projectRoot}`);
+ * ```
+ */
+export declare function getCliContextSync(options?: GetCliContextOptions): CliContext | null;
+/**
+ * Type guard to check if a value is a CliContext.
+ *
+ * @param value - Value to check
+ * @returns true if value is a CliContext instance
+ */
+export declare function isCliContext(value: unknown): value is CliContext;
+//# sourceMappingURL=cli-context.d.ts.map

package/dist/lib/cli-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../../src/lib/cli-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,UAAU;IACrB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE5C;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;OAEG;IACH,OAAO;IAWP;;;;;;;;;;;;;;;;;OAiBG;WACU,MAAM,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBrE;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU;IAwB1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACU,OAAO,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAUtE;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU;IAU3D;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAOpC;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAejD;;;;;;;;;;;OAWG;IACH,mBAAmB,IAAI,MAAM,EAAE;IAO/B;;;;;;;;;;OAUG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;CAGrC;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,aAAa,CACjC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA0B5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,UAAU,GAAG,IAAI,CA0BnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}