cc-agentic-framework 1.14.1

package/dist/lib/module-loader.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Get the resolved framework root path.
+ * Use this when you need access to the framework directory.
+ */
+export declare function getFrameworkRoot(): string;
+export interface ModuleManifest {
+    $schema?: string;
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    provides: {
+        agents?: string[];
+        skills?: string[];
+        capabilities?: string[];
+        scripts?: string[];
+        guards?: string[];
+    };
+    requires?: Record<string, string>;
+    'optional-dependencies'?: string[];
+    context?: {
+        business?: string[];
+        technical?: string[];
+        process?: string[];
+    };
+    'entry-points'?: {
+        cli?: Array<{
+            name: string;
+            script: string;
+            description?: string;
+        }>;
+        hooks?: {
+            'pre-commit'?: string[];
+            'post-commit'?: string[];
+            'pre-push'?: string[];
+        };
+    };
+    metadata?: {
+        author?: string;
+        license?: string;
+        repository?: string;
+        homepage?: string;
+        keywords?: string[];
+        category?: string;
+    };
+    _sourcePath?: string;
+}
+/**
+ * Get list of available modules
+ */
+export declare function getAvailableModules(): Promise<string[]>;
+/**
+ * Load a module manifest
+ */
+export declare function loadModule(moduleName: string): Promise<ModuleManifest>;
+/**
+ * Validate module dependencies
+ */
+export declare function validateDependencies(moduleName: string, installedModules: string[]): Promise<{
+    valid: boolean;
+    missing: string[];
+}>;
+/**
+ * Get modules that depend on a given module (hard dependencies only)
+ */
+export declare function getDependents(moduleName: string): Promise<string[]>;
+/**
+ * Get modules that have optional dependency on a given module
+ */
+export declare function getOptionalDependents(moduleName: string): Promise<string[]>;
+/**
+ * Check for missing optional dependencies and return warnings
+ */
+export declare function checkOptionalDependencies(moduleName: string, installedModules: string[]): Promise<{
+    warnings: string[];
+}>;
+//# sourceMappingURL=module-loader.d.ts.map

package/dist/lib/module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../../src/lib/module-loader.ts"],"names":[],"mappings":"AAgCA;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,cAAc,CAAC,EAAE;QACf,GAAG,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpE,KAAK,CAAC,EAAE;YACN,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;YACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;YACzB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;SACvB,CAAC;KACH,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAkB7D;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAa5E;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAgBhD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYzE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYjF;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsBjC"}

package/dist/lib/module-loader.js

@@ -0,0 +1,135 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDirPath = path.dirname(currentFilePath);
+/**
+ * Resolve framework root based on execution context.
+ *
+ * In development mode:
+ *   framework/cli/dist/lib/module-loader.js → framework/ (3 levels up)
+ *
+ * In published mode:
+ *   node_modules/agentic-framework/dist/lib/module-loader.js →
+ *   node_modules/agentic-framework/framework/ (2 levels up + framework/)
+ */
+function resolveFrameworkRoot() {
+    // Check for bundled framework (published mode)
+    const publishedPath = path.resolve(currentDirPath, '..', '..', 'framework');
+    if (fs.pathExistsSync(publishedPath)) {
+        // Published mode: node_modules/agentic-framework/framework/
+        return publishedPath;
+    }
+    // Development mode: framework/cli/dist/lib → framework/ (3 levels up)
+    return path.resolve(currentDirPath, '..', '..', '..');
+}
+const FRAMEWORK_ROOT = resolveFrameworkRoot();
+/**
+ * Get the resolved framework root path.
+ * Use this when you need access to the framework directory.
+ */
+export function getFrameworkRoot() {
+    return FRAMEWORK_ROOT;
+}
+/**
+ * Get list of available modules
+ */
+export async function getAvailableModules() {
+    const modules = [];
+    // Check modules directory (includes core)
+    const modulesDir = path.join(FRAMEWORK_ROOT, 'modules');
+    if (await fs.pathExists(modulesDir)) {
+        const entries = await fs.readdir(modulesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const moduleJsonPath = path.join(modulesDir, entry.name, 'module.json');
+                if (await fs.pathExists(moduleJsonPath)) {
+                    modules.push(entry.name);
+                }
+            }
+        }
+    }
+    return modules;
+}
+/**
+ * Load a module manifest
+ */
+export async function loadModule(moduleName) {
+    // All modules (including core) are now in modules/ directory
+    const modulePath = path.join(FRAMEWORK_ROOT, 'modules', moduleName);
+    const manifestPath = path.join(modulePath, 'module.json');
+    if (!await fs.pathExists(manifestPath)) {
+        throw new Error(`Module '${moduleName}' not found at ${manifestPath}`);
+    }
+    const manifest = await fs.readJson(manifestPath);
+    manifest._sourcePath = modulePath;
+    return manifest;
+}
+/**
+ * Validate module dependencies
+ */
+export async function validateDependencies(moduleName, installedModules) {
+    const module = await loadModule(moduleName);
+    const missing = [];
+    if (module.requires) {
+        for (const dep of Object.keys(module.requires)) {
+            if (!installedModules.includes(dep)) {
+                missing.push(dep);
+            }
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+/**
+ * Get modules that depend on a given module (hard dependencies only)
+ */
+export async function getDependents(moduleName) {
+    const dependents = [];
+    const availableModules = await getAvailableModules();
+    for (const mod of availableModules) {
+        const module = await loadModule(mod);
+        if (module.requires && moduleName in module.requires) {
+            dependents.push(mod);
+        }
+    }
+    return dependents;
+}
+/**
+ * Get modules that have optional dependency on a given module
+ */
+export async function getOptionalDependents(moduleName) {
+    const dependents = [];
+    const availableModules = await getAvailableModules();
+    for (const mod of availableModules) {
+        const module = await loadModule(mod);
+        if (module['optional-dependencies']?.includes(moduleName)) {
+            dependents.push(mod);
+        }
+    }
+    return dependents;
+}
+/**
+ * Check for missing optional dependencies and return warnings
+ */
+export async function checkOptionalDependencies(moduleName, installedModules) {
+    const module = await loadModule(moduleName);
+    const warnings = [];
+    if (module['optional-dependencies']) {
+        for (const optDep of module['optional-dependencies']) {
+            if (!installedModules.includes(optDep)) {
+                // Generate appropriate warning based on what the optional dependency provides
+                if (optDep === 'core') {
+                    warnings.push(`Module '${moduleName}' works best with 'core' module (shared skills like verifying-quality, committing-code will be unavailable)`);
+                }
+                else {
+                    warnings.push(`Optional dependency '${optDep}' is not installed (some features may be limited)`);
+                }
+            }
+        }
+    }
+    return { warnings };
+}
+//# sourceMappingURL=module-loader.js.map

package/dist/lib/module-loader.js.map

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

package/dist/lib/path-resolver.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Ticket types supported by the backlog module
+ */
+export type TicketType = 'story' | 'task' | 'bug' | 'epic' | 'spike';
+/**
+ * Configuration structure parsed from routes.yml
+ *
+ * Example structure:
+ * ```yaml
+ * paths:
+ *   backlog:
+ *     root: ".claude/backlog/"
+ *     tickets: ".claude/backlog/tickets/"
+ *   agents:
+ *     root: ".claude/agents/"
+ * meta:
+ *   last-updated: "2024-12-27"
+ *   sync-status: "synchronized"
+ * ```
+ */
+export interface RoutesConfig {
+    /** Nested path mappings by category and key */
+    paths: Record<string, Record<string, string>>;
+    /** Optional metadata about the routes file */
+    meta?: Record<string, string>;
+}
+/**
+ * Path resolver interface for semantic path resolution
+ *
+ * Provides both generic route-based resolution and semantic accessors
+ * for common framework paths. All returned paths are absolute.
+ */
+export interface PathResolver {
+    /** The project root directory (absolute path) */
+    readonly projectRoot: string;
+    /** The parsed routes configuration, or null if not available */
+    readonly routesConfig: RoutesConfig | null;
+    /**
+     * Resolve a path from routes.yml using dot notation
+     *
+     * @param routeKey - Dot-separated key (e.g., 'backlog.tickets')
+     * @returns Absolute path or null if route not found
+     *
+     * @example
+     * ```typescript
+     * resolver.resolve('backlog.tickets')  // '/project/.claude/backlog/tickets'
+     * resolver.resolve('agents.root')      // '/project/.claude/agents'
+     * ```
+     */
+    resolve(routeKey: string): string | null;
+    /**
+     * Get the path for a specific ticket type directory
+     *
+     * @param type - The ticket type (story, task, bug, epic, spike)
+     * @returns Absolute path to the ticket type directory
+     *
+     * @example
+     * ```typescript
+     * resolver.getTicketPath('story')  // '/project/.claude/backlog/tickets/stories'
+     * resolver.getTicketPath('bug')    // '/project/.claude/backlog/tickets/bugs'
+     * ```
+     */
+    getTicketPath(type: TicketType): string;
+    /**
+     * Get the path for plans directory, optionally with a category
+     *
+     * @param category - Optional category subdirectory
+     * @returns Absolute path to plans directory or category subdirectory
+     *
+     * @example
+     * ```typescript
+     * resolver.getPlanPath()           // '/project/.claude/plans'
+     * resolver.getPlanPath('framework') // '/project/.claude/plans/framework'
+     * ```
+     */
+    getPlanPath(category?: string): string;
+    /**
+     * Get the path to the context directory
+     *
+     * @returns Absolute path to the context directory
+     */
+    getContextPath(): string;
+    /**
+     * Get the path to the agents directory
+     *
+     * @returns Absolute path to the agents directory
+     */
+    getAgentPath(): string;
+    /**
+     * Get the path to the skills directory
+     *
+     * @returns Absolute path to the skills directory
+     */
+    getSkillPath(): string;
+    /**
+     * Get the path to the registries directory
+     *
+     * @returns Absolute path to the registries directory
+     */
+    getRegistryPath(): string;
+}
+/**
+ * Default paths used when routes.yml is missing or incomplete
+ */
+declare const DEFAULT_PATHS: {
+    readonly backlog: ".claude/backlog";
+    readonly tickets: ".claude/backlog/tickets";
+    readonly plans: ".claude/plans";
+    readonly context: ".claude/context";
+    readonly agents: ".claude/commands";
+    readonly skills: ".claude/skills";
+    readonly registries: ".claude/registries";
+};
+/**
+ * Create a PathResolver instance for the given project root
+ *
+ * The resolver will attempt to load routes.yml from the project root.
+ * If the file doesn't exist or cannot be parsed, the resolver will
+ * still function using default paths.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @returns A PathResolver instance
+ *
+ * @example
+ * ```typescript
+ * const resolver = await createPathResolver('/path/to/project');
+ *
+ * // Use semantic accessors
+ * const storiesDir = resolver.getTicketPath('story');
+ * const plansDir = resolver.getPlanPath('framework');
+ *
+ * // Or use generic resolution
+ * const customPath = resolver.resolve('backlog.archive');
+ * ```
+ */
+export declare function createPathResolver(projectRoot: string): Promise<PathResolver>;
+/**
+ * Create a PathResolver synchronously with pre-loaded routes config
+ *
+ * This is useful when routes.yml has already been loaded elsewhere.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @param routesConfig - Pre-parsed routes configuration (or null)
+ * @returns A PathResolver instance
+ */
+export declare function createPathResolverSync(projectRoot: string, routesConfig: RoutesConfig | null): PathResolver;
+/**
+ * Get default paths for when routes.yml is not available
+ *
+ * @returns Object containing all default path mappings
+ */
+export declare function getDefaultPaths(): typeof DEFAULT_PATHS;
+/**
+ * Get ticket type directory mappings
+ *
+ * @returns Object mapping ticket types to directory names
+ */
+export declare function getTicketTypeDirs(): Record<TicketType, string>;
+export {};
+//# sourceMappingURL=path-resolver.d.ts.map

package/dist/lib/path-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-resolver.d.ts","sourceRoot":"","sources":["../../src/lib/path-resolver.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAE3C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAExC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvC;;;;OAIG;IACH,cAAc,IAAI,MAAM,CAAC;IAEzB;;;;OAIG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB;;;;OAIG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB;;;;OAIG;IACH,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,QAAA,MAAM,aAAa;;;;;;;;CAQT,CAAC;AA8JX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAOnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,YAAY,GAAG,IAAI,GAChC,YAAY,CAGd;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,aAAa,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAE9D"}

package/dist/lib/path-resolver.js

@@ -0,0 +1,205 @@
+import path from 'path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+/**
+ * Default paths used when routes.yml is missing or incomplete
+ */
+const DEFAULT_PATHS = {
+    backlog: '.claude/backlog',
+    tickets: '.claude/backlog/tickets',
+    plans: '.claude/plans',
+    context: '.claude/context',
+    agents: '.claude/commands',
+    skills: '.claude/skills',
+    registries: '.claude/registries',
+};
+/**
+ * Mapping of ticket types to their directory names (pluralized)
+ */
+const TICKET_TYPE_DIRS = {
+    story: 'stories',
+    task: 'tasks',
+    bug: 'bugs',
+    epic: 'epics',
+    spike: 'spikes',
+};
+/**
+ * Implementation of the PathResolver interface
+ */
+class PathResolverImpl {
+    projectRoot;
+    routesConfig;
+    constructor(projectRoot, routesConfig) {
+        this.projectRoot = projectRoot;
+        this.routesConfig = routesConfig;
+    }
+    /**
+     * Resolve a path from routes.yml using dot notation
+     */
+    resolve(routeKey) {
+        if (!this.routesConfig?.paths) {
+            return null;
+        }
+        const [category, key] = routeKey.split('.');
+        if (!category) {
+            return null;
+        }
+        const categoryPaths = this.routesConfig.paths[category];
+        if (!categoryPaths) {
+            return null;
+        }
+        // If no key specified, try 'root' as default
+        const pathKey = key || 'root';
+        const relativePath = categoryPaths[pathKey];
+        if (typeof relativePath !== 'string') {
+            return null;
+        }
+        // Normalize path: remove trailing slashes
+        const normalizedPath = relativePath.replace(/\/+$/, '');
+        if (!normalizedPath) {
+            return null;
+        }
+        return path.join(this.projectRoot, normalizedPath);
+    }
+    /**
+     * Get the path for a specific ticket type directory
+     */
+    getTicketPath(type) {
+        const dirName = TICKET_TYPE_DIRS[type];
+        // Try to resolve from routes.yml first
+        const ticketsPath = this.resolve('backlog.tickets');
+        if (ticketsPath) {
+            return path.join(ticketsPath, dirName);
+        }
+        // Fall back to default
+        return path.join(this.projectRoot, DEFAULT_PATHS.tickets, dirName);
+    }
+    /**
+     * Get the path for plans directory
+     */
+    getPlanPath(category) {
+        // Try to resolve from routes.yml first
+        const plansPath = this.resolve('plans.root') || this.resolve('planning.root');
+        const basePath = plansPath || path.join(this.projectRoot, DEFAULT_PATHS.plans);
+        if (category) {
+            return path.join(basePath, category);
+        }
+        return basePath;
+    }
+    /**
+     * Get the path to the context directory
+     */
+    getContextPath() {
+        const contextPath = this.resolve('context.root');
+        return contextPath || path.join(this.projectRoot, DEFAULT_PATHS.context);
+    }
+    /**
+     * Get the path to the agents directory
+     */
+    getAgentPath() {
+        const agentPath = this.resolve('agents.root');
+        return agentPath || path.join(this.projectRoot, DEFAULT_PATHS.agents);
+    }
+    /**
+     * Get the path to the skills directory
+     */
+    getSkillPath() {
+        const skillPath = this.resolve('skills.root');
+        return skillPath || path.join(this.projectRoot, DEFAULT_PATHS.skills);
+    }
+    /**
+     * Get the path to the registries directory
+     */
+    getRegistryPath() {
+        const registryPath = this.resolve('registries.root');
+        return registryPath || path.join(this.projectRoot, DEFAULT_PATHS.registries);
+    }
+}
+/**
+ * Parse routes.yml file and return the configuration
+ *
+ * @param routesFilePath - Absolute path to the routes.yml file
+ * @returns Parsed routes configuration or null if parsing fails
+ */
+async function parseRoutesYml(routesFilePath) {
+    try {
+        if (!await fs.pathExists(routesFilePath)) {
+            return null;
+        }
+        const content = await fs.readFile(routesFilePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        // Validate that paths is an object if present
+        if (parsed.paths && typeof parsed.paths !== 'object') {
+            return null;
+        }
+        return {
+            paths: parsed.paths || {},
+            meta: parsed.meta,
+        };
+    }
+    catch (_error) {
+        // Return null on any parsing error - graceful degradation
+        return null;
+    }
+}
+/**
+ * Create a PathResolver instance for the given project root
+ *
+ * The resolver will attempt to load routes.yml from the project root.
+ * If the file doesn't exist or cannot be parsed, the resolver will
+ * still function using default paths.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @returns A PathResolver instance
+ *
+ * @example
+ * ```typescript
+ * const resolver = await createPathResolver('/path/to/project');
+ *
+ * // Use semantic accessors
+ * const storiesDir = resolver.getTicketPath('story');
+ * const plansDir = resolver.getPlanPath('framework');
+ *
+ * // Or use generic resolution
+ * const customPath = resolver.resolve('backlog.archive');
+ * ```
+ */
+export async function createPathResolver(projectRoot) {
+    const absoluteRoot = path.resolve(projectRoot);
+    const routesFilePath = path.join(absoluteRoot, 'routes.yml');
+    const routesConfig = await parseRoutesYml(routesFilePath);
+    return new PathResolverImpl(absoluteRoot, routesConfig);
+}
+/**
+ * Create a PathResolver synchronously with pre-loaded routes config
+ *
+ * This is useful when routes.yml has already been loaded elsewhere.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @param routesConfig - Pre-parsed routes configuration (or null)
+ * @returns A PathResolver instance
+ */
+export function createPathResolverSync(projectRoot, routesConfig) {
+    const absoluteRoot = path.resolve(projectRoot);
+    return new PathResolverImpl(absoluteRoot, routesConfig);
+}
+/**
+ * Get default paths for when routes.yml is not available
+ *
+ * @returns Object containing all default path mappings
+ */
+export function getDefaultPaths() {
+    return { ...DEFAULT_PATHS };
+}
+/**
+ * Get ticket type directory mappings
+ *
+ * @returns Object mapping ticket types to directory names
+ */
+export function getTicketTypeDirs() {
+    return { ...TICKET_TYPE_DIRS };
+}
+//# sourceMappingURL=path-resolver.js.map

package/dist/lib/path-resolver.js.map

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