cc-agentic-framework 1.14.1

package/dist/lib/planning/plan-creator.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Plan Creation Tool
+ *
+ * Automates the creation of plan folders with auto-numbering, templates, and validation.
+ *
+ * @deprecated This module uses a separate template resolution logic. Consider using
+ * unified-template-engine for new template-based features. This module is kept for
+ * backward compatibility with existing plan template structure.
+ *
+ * @module lib/planning/plan-creator
+ */
+/**
+ * Template variables for rendering plan templates
+ */
+export interface TemplateVars {
+    number: string;
+    date: string;
+    Category?: string;
+    category?: string;
+    status?: string;
+    title?: string;
+}
+/**
+ * Result of plan creation operation
+ */
+export interface PlanResult {
+    success: boolean;
+    message: string;
+    /** Plan ID in format NNN (e.g., "003") - only set on success */
+    planId?: string;
+    /** Absolute path to the plan folder - only set on success */
+    planPath?: string;
+}
+/**
+ * Validation result for plan names
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate plan name follows kebab-case rules.
+ *
+ * @param name - Plan name to validate
+ * @returns Validation result with error message if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validatePlanName('my-plan');
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+export declare function validatePlanName(name: string): ValidationResult;
+/**
+ * Scan category directory and compute next plan number.
+ *
+ * @param category - Plan category (e.g., "framework", "apm-r")
+ * @param projectRoot - Path to project root (defaults to current working directory)
+ * @returns Next available plan number
+ *
+ * @example
+ * ```typescript
+ * const nextNumber = await getNextPlanNumber('framework');
+ * console.log(`Next plan: ${nextNumber}`);
+ * ```
+ */
+export declare function getNextPlanNumber(category: string, projectRoot?: string): Promise<number>;
+/**
+ * Get path to template file for category.
+ *
+ * Searches in the following locations (in order):
+ * 1. Category-specific templates in ai/plans/{category}/.templates/
+ * 2. Framework templates in ai/plans/framework/.templates/
+ * 3. Installed skill templates in .claude/skills/planning-phases/templates/
+ *
+ * @param category - Plan category (e.g., "framework", "apm-r")
+ * @param templateName - Template filename (e.g., "PLAN.md.template")
+ * @param projectRoot - Path to project root (defaults to current working directory)
+ * @returns Path to template or null if not found
+ *
+ * @example
+ * ```typescript
+ * const templatePath = await getTemplatePath('framework', 'PLAN.md.template');
+ * if (templatePath) {
+ *   const content = await fs.readFile(templatePath, 'utf-8');
+ * }
+ * ```
+ */
+export declare function getTemplatePath(category: string, templateName: string, projectRoot?: string): Promise<string | null>;
+/**
+ * Render template with placeholders replaced.
+ *
+ * Supports both single-brace `{var}` and double-brace `{{var}}` syntax
+ * for backward compatibility with different template formats.
+ *
+ * @param content - Template content
+ * @param vars - Template variables
+ * @returns Rendered template content
+ *
+ * @example
+ * ```typescript
+ * const template = 'Plan {number} - {{date}}';
+ * const rendered = renderTemplate(template, { number: '001', date: '2025-12-21' });
+ * ```
+ */
+export declare function renderTemplate(content: string, vars: TemplateVars): string;
+/**
+ * Create plan folder structure with templates.
+ *
+ * @param name - Plan name (kebab-case)
+ * @param category - Plan category (e.g., "framework", "apm-r")
+ * @param projectRoot - Path to project root (defaults to current working directory)
+ * @param dryRun - If true, show what would be created without creating
+ * @param categoryPlansDir - Optional pre-resolved path to the category plans directory.
+ *                           If provided, uses this path directly instead of computing from projectRoot.
+ *                           This allows integration with CliContext path resolution.
+ * @returns Result with success status and message
+ *
+ * @example
+ * ```typescript
+ * const result = await createPlan('my-plan', 'framework');
+ * if (result.success) {
+ *   console.log(result.message);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export declare function createPlan(name: string, category: string, projectRoot?: string, dryRun?: boolean, categoryPlansDir?: string): Promise<PlanResult>;
+//# sourceMappingURL=plan-creator.d.ts.map

package/dist/lib/planning/plan-creator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-creator.d.ts","sourceRoot":"","sources":["../../../src/lib/planning/plan-creator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CA2B/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC/F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAgC1E;AA+FD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,GAAE,OAAe,EACvB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAiHrB"}

package/dist/lib/planning/plan-creator.js

@@ -0,0 +1,361 @@
+/**
+ * Plan Creation Tool
+ *
+ * Automates the creation of plan folders with auto-numbering, templates, and validation.
+ *
+ * @deprecated This module uses a separate template resolution logic. Consider using
+ * unified-template-engine for new template-based features. This module is kept for
+ * backward compatibility with existing plan template structure.
+ *
+ * @module lib/planning/plan-creator
+ */
+import fs from 'fs-extra';
+import path from 'path';
+/**
+ * Validate plan name follows kebab-case rules.
+ *
+ * @param name - Plan name to validate
+ * @returns Validation result with error message if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validatePlanName('my-plan');
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+export function validatePlanName(name) {
+    // Check length
+    if (name.length < 2 || name.length > 30) {
+        return {
+            valid: false,
+            error: 'Plan name must be 2-30 characters long',
+        };
+    }
+    // Check for double hyphens
+    if (name.includes('--')) {
+        return {
+            valid: false,
+            error: 'Plan name cannot contain consecutive hyphens',
+        };
+    }
+    // Check format: lowercase, hyphens only, starts/ends with letter/number
+    const pattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+    if (!pattern.test(name)) {
+        return {
+            valid: false,
+            error: 'Plan name must be kebab-case: lowercase letters, numbers, and hyphens only (no leading/trailing hyphens)',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Scan category directory and compute next plan number.
+ *
+ * @param category - Plan category (e.g., "framework", "apm-r")
+ * @param projectRoot - Path to project root (defaults to current working directory)
+ * @returns Next available plan number
+ *
+ * @example
+ * ```typescript
+ * const nextNumber = await getNextPlanNumber('framework');
+ * console.log(`Next plan: ${nextNumber}`);
+ * ```
+ */
+export async function getNextPlanNumber(category, projectRoot) {
+    const root = projectRoot || process.cwd();
+    const categoryDir = path.join(root, 'ai', 'plans', category);
+    // If category directory doesn't exist, start at 1
+    if (!(await fs.pathExists(categoryDir))) {
+        return 1;
+    }
+    // Scan for existing plan folders matching pattern: NNN-*
+    let maxNumber = 0;
+    const planPattern = /^(\d{3})-/;
+    const items = await fs.readdir(categoryDir);
+    for (const item of items) {
+        // Skip .templates and other hidden directories
+        if (item.startsWith('.')) {
+            continue;
+        }
+        const itemPath = path.join(categoryDir, item);
+        const stat = await fs.stat(itemPath);
+        if (stat.isDirectory()) {
+            const match = planPattern.exec(item);
+            if (match) {
+                const number = parseInt(match[1], 10);
+                maxNumber = Math.max(maxNumber, number);
+            }
+        }
+    }
+    return maxNumber + 1;
+}
+/**
+ * Get path to template file for category.
+ *
+ * Searches in the following locations (in order):
+ * 1. Category-specific templates in ai/plans/{category}/.templates/
+ * 2. Framework templates in ai/plans/framework/.templates/
+ * 3. Installed skill templates in .claude/skills/planning-phases/templates/
+ *
+ * @param category - Plan category (e.g., "framework", "apm-r")
+ * @param templateName - Template filename (e.g., "PLAN.md.template")
+ * @param projectRoot - Path to project root (defaults to current working directory)
+ * @returns Path to template or null if not found
+ *
+ * @example
+ * ```typescript
+ * const templatePath = await getTemplatePath('framework', 'PLAN.md.template');
+ * if (templatePath) {
+ *   const content = await fs.readFile(templatePath, 'utf-8');
+ * }
+ * ```
+ */
+export async function getTemplatePath(category, templateName, projectRoot) {
+    const root = projectRoot || process.cwd();
+    // Search paths in priority order
+    const searchPaths = [
+        // 1. Category-specific templates in ai/plans/
+        path.join(root, 'ai', 'plans', category, '.templates', templateName),
+        // 2. Framework templates in ai/plans/
+        path.join(root, 'ai', 'plans', 'framework', '.templates', templateName),
+        // 3. Installed skill templates (planning-phases)
+        path.join(root, '.claude', 'skills', 'planning-phases', 'templates', templateName),
+    ];
+    for (const templatePath of searchPaths) {
+        if (await fs.pathExists(templatePath)) {
+            return templatePath;
+        }
+    }
+    return null;
+}
+/**
+ * Render template with placeholders replaced.
+ *
+ * Supports both single-brace `{var}` and double-brace `{{var}}` syntax
+ * for backward compatibility with different template formats.
+ *
+ * @param content - Template content
+ * @param vars - Template variables
+ * @returns Rendered template content
+ *
+ * @example
+ * ```typescript
+ * const template = 'Plan {number} - {{date}}';
+ * const rendered = renderTemplate(template, { number: '001', date: '2025-12-21' });
+ * ```
+ */
+export function renderTemplate(content, vars) {
+    let result = content;
+    // Replace placeholders - support both {var} and {{var}} syntax
+    // Double-brace first to avoid partial matches
+    result = result.replace(/\{\{number\}\}/g, vars.number);
+    result = result.replace(/{number}/g, vars.number);
+    result = result.replace(/\{\{date\}\}/g, vars.date);
+    result = result.replace(/{date}/g, vars.date);
+    if (vars.Category) {
+        result = result.replace(/\{\{Category\}\}/g, vars.Category);
+        result = result.replace(/{Category}/g, vars.Category);
+    }
+    if (vars.category) {
+        result = result.replace(/\{\{category\}\}/g, vars.category);
+        result = result.replace(/{category}/g, vars.category);
+    }
+    if (vars.status) {
+        result = result.replace(/\{\{status\}\}/g, vars.status);
+        result = result.replace(/{status}/g, vars.status);
+    }
+    if (vars.title) {
+        result = result.replace(/\{\{title\}\}/g, vars.title);
+        result = result.replace(/{title}/g, vars.title);
+    }
+    return result;
+}
+/**
+ * Get display name for category (capitalize or special case for APM-R)
+ *
+ * @param category - Category name
+ * @returns Display name
+ */
+function getCategoryDisplay(category) {
+    if (category === 'apm-r') {
+        return 'APM-R';
+    }
+    return category.charAt(0).toUpperCase() + category.slice(1);
+}
+/**
+ * Format dry-run output message.
+ *
+ * @param planFolder - Path to plan folder
+ * @param planNumber - Plan number
+ * @param name - Plan name
+ * @param category - Plan category
+ * @param planContent - PLAN.md content
+ * @param progressContent - PROGRESS.md content
+ * @returns Formatted message
+ */
+function formatDryRunOutput(planFolder, planNumber, name, category, planContent, progressContent) {
+    return `
+DRY RUN - No files created
+
+Plan Details:
+  Number:   ${planNumber.toString().padStart(3, '0')}
+  Name:     ${name}
+  Category: ${category}
+  Folder:   ${planFolder}
+
+Would create:
+  ✓ ${planFolder}/
+  ✓ ${planFolder}/PLAN.md (${planContent.length} bytes)
+  ✓ ${planFolder}/PROGRESS.md (${progressContent.length} bytes)
+
+Next steps:
+  1. Remove --dry-run flag to create plan
+  2. Edit PLAN.md to add problem statement and phases
+  3. Commit PLAN.md to git
+  4. Share plan location with user for review
+  `.trim();
+}
+/**
+ * Format success output message.
+ *
+ * @param planFolder - Path to plan folder
+ * @param planFile - Path to PLAN.md
+ * @param progressFile - Path to PROGRESS.md
+ * @param planNumber - Plan number
+ * @param category - Plan category
+ * @returns Formatted message
+ */
+function formatSuccessOutput(planFolder, planFile, progressFile, planNumber, category) {
+    return `
+Plan created successfully!
+
+Plan Number: ${planNumber.toString().padStart(3, '0')}
+Category:    ${category}
+
+Created:
+  📁 ${planFolder}
+  📄 ${planFile}
+  📄 ${progressFile}
+
+Next steps:
+  1. Edit PLAN.md to add problem statement and phases
+  2. Commit PLAN.md to git: git add ${planFolder} && git commit -m "feat(planning): create plan ${planNumber.toString().padStart(3, '0')}"
+  3. Share plan location with user for review
+
+File paths (absolute):
+  ${planFile}
+  ${progressFile}
+  `.trim();
+}
+/**
+ * Create plan folder structure with templates.
+ *
+ * @param name - Plan name (kebab-case)
+ * @param category - Plan category (e.g., "framework", "apm-r")
+ * @param projectRoot - Path to project root (defaults to current working directory)
+ * @param dryRun - If true, show what would be created without creating
+ * @param categoryPlansDir - Optional pre-resolved path to the category plans directory.
+ *                           If provided, uses this path directly instead of computing from projectRoot.
+ *                           This allows integration with CliContext path resolution.
+ * @returns Result with success status and message
+ *
+ * @example
+ * ```typescript
+ * const result = await createPlan('my-plan', 'framework');
+ * if (result.success) {
+ *   console.log(result.message);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export async function createPlan(name, category, projectRoot, dryRun = false, categoryPlansDir) {
+    try {
+        const root = projectRoot || process.cwd();
+        // Use pre-resolved category path if provided, otherwise compute from projectRoot
+        const plansDir = categoryPlansDir
+            ? path.dirname(categoryPlansDir) // Get parent dir since categoryPlansDir includes category
+            : path.join(root, 'ai', 'plans');
+        // Validate plan name
+        const validation = validatePlanName(name);
+        if (!validation.valid) {
+            return {
+                success: false,
+                message: `Invalid plan name: ${validation.error}`,
+            };
+        }
+        // Get next plan number
+        const planNumber = await getNextPlanNumber(category, root);
+        const folderName = `${planNumber.toString().padStart(3, '0')}-${name}`;
+        const planFolder = path.join(plansDir, category, folderName);
+        // Check if folder already exists (even in dry-run mode)
+        if (await fs.pathExists(planFolder)) {
+            return {
+                success: false,
+                message: `Plan folder already exists: ${planFolder}`,
+            };
+        }
+        // Get current date
+        const currentDate = new Date().toISOString().split('T')[0];
+        // Get template paths
+        const planTemplatePath = await getTemplatePath(category, 'PLAN.md.template', root);
+        const progressTemplatePath = await getTemplatePath(category, 'PROGRESS.md.template', root);
+        if (!planTemplatePath) {
+            return {
+                success: false,
+                message: `PLAN.md.template not found for category '${category}'`,
+            };
+        }
+        if (!progressTemplatePath) {
+            return {
+                success: false,
+                message: `PROGRESS.md.template not found for category '${category}'`,
+            };
+        }
+        // Read templates
+        const planTemplateContent = await fs.readFile(planTemplatePath, 'utf-8');
+        const progressTemplateContent = await fs.readFile(progressTemplatePath, 'utf-8');
+        // Render templates
+        const categoryDisplay = getCategoryDisplay(category);
+        const vars = {
+            number: planNumber.toString().padStart(3, '0'),
+            date: currentDate,
+            Category: categoryDisplay,
+            category: category, // lowercase version for {{category}}
+            status: 'proposed', // default status for new plans (programmatic value)
+            title: '[Plan Title]', // placeholder for user to fill
+        };
+        const planContent = renderTemplate(planTemplateContent, vars);
+        const progressContent = renderTemplate(progressTemplateContent, vars);
+        // Dry run: just show what would be created
+        if (dryRun) {
+            return {
+                success: true,
+                message: formatDryRunOutput(planFolder, planNumber, name, category, planContent, progressContent),
+                planId: planNumber.toString().padStart(3, '0'),
+                planPath: planFolder,
+            };
+        }
+        // Create folder and files
+        await fs.ensureDir(planFolder);
+        const planFile = path.join(planFolder, 'PLAN.md');
+        const progressFile = path.join(planFolder, 'PROGRESS.md');
+        await fs.writeFile(planFile, planContent, 'utf-8');
+        await fs.writeFile(progressFile, progressContent, 'utf-8');
+        return {
+            success: true,
+            message: formatSuccessOutput(planFolder, planFile, progressFile, planNumber, category),
+            planId: planNumber.toString().padStart(3, '0'),
+            planPath: planFolder,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: `Failed to create plan: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+//# sourceMappingURL=plan-creator.js.map

package/dist/lib/planning/plan-creator.js.map

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

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

@@ -0,0 +1,124 @@
+import { FrameworkManifest } from './manifest-manager.js';
+/**
+ * Detection methods for finding project root, in priority order.
+ * - manifest: Found .agentic-framework.json (primary marker, most specific)
+ * - routes: Found routes.yml + CLAUDE.md (secondary marker)
+ * - git+claude: Found .git + CLAUDE.md (fallback for git repos with framework)
+ * - cwd: No markers found, using current working directory
+ */
+export type DetectionMethod = 'manifest' | 'routes' | 'git+claude' | 'cwd';
+/**
+ * Project context containing resolved project information.
+ * Provides project root path, manifest (if present), and detection metadata.
+ */
+export interface ProjectContext {
+    /** Absolute path to the project root directory */
+    projectRoot: string;
+    /** Parsed .agentic-framework.json manifest, null if not found */
+    manifest: FrameworkManifest | null;
+    /** Whether we found a valid project with framework markers */
+    isInsideProject: boolean;
+    /** Method used to detect the project root */
+    detectionMethod: DetectionMethod;
+}
+/**
+ * Error thrown when a project context is required but not found.
+ */
+export declare class ProjectNotFoundError extends Error {
+    constructor(startDir: string);
+}
+/**
+ * Find the project root by walking up the directory tree.
+ *
+ * Detection strategy (priority order):
+ * 1. `.agentic-framework.json` - Primary marker (most specific)
+ * 2. `routes.yml` + `CLAUDE.md` - Secondary marker
+ * 3. `.git` + `CLAUDE.md` - Fallback for git repos with framework
+ * 4. If nothing found, returns current directory with `isInsideProject: false`
+ *
+ * The result is cached for the session to avoid repeated filesystem scans.
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd())
+ * @returns ProjectContext with resolved project information
+ *
+ * @example
+ * ```typescript
+ * const context = findProjectRoot();
+ * if (context.isInsideProject) {
+ *   console.log(`Found project at: ${context.projectRoot}`);
+ *   console.log(`Detected via: ${context.detectionMethod}`);
+ * }
+ * ```
+ */
+export declare function findProjectRoot(startDir?: string): ProjectContext;
+/**
+ * Find the project root, throwing an error if not inside a project.
+ *
+ * Use this when the command requires being inside a valid project.
+ * Provides a clear error message guiding users to run `init`.
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd())
+ * @returns ProjectContext with resolved project information
+ * @throws ProjectNotFoundError if not inside a project
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const context = requireProjectContext();
+ *   // Guaranteed to have isInsideProject: true
+ *   console.log(`Working in: ${context.projectRoot}`);
+ * } catch (error) {
+ *   if (error instanceof ProjectNotFoundError) {
+ *     console.error(error.message);
+ *     process.exit(1);
+ *   }
+ * }
+ * ```
+ */
+export declare function requireProjectContext(startDir?: string): ProjectContext;
+/**
+ * Async version of findProjectRoot for use in async contexts.
+ * Provides better performance for operations that can be parallelized.
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd())
+ * @returns Promise resolving to ProjectContext
+ *
+ * @example
+ * ```typescript
+ * const context = await findProjectRootAsync();
+ * if (context.isInsideProject) {
+ *   console.log(`Detected via: ${context.detectionMethod}`);
+ * }
+ * ```
+ */
+export declare function findProjectRootAsync(startDir?: string): Promise<ProjectContext>;
+/**
+ * Async version of requireProjectContext.
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd())
+ * @returns Promise resolving to ProjectContext
+ * @throws ProjectNotFoundError if not inside a project
+ */
+export declare function requireProjectContextAsync(startDir?: string): Promise<ProjectContext>;
+/**
+ * Clear the cached project context.
+ *
+ * Useful for testing or when the project structure has changed.
+ * Subsequent calls to findProjectRoot() will re-scan the filesystem.
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * beforeEach(() => {
+ *   clearProjectCache();
+ * });
+ * ```
+ */
+export declare function clearProjectCache(): void;
+/**
+ * Get the cached project context without triggering a new scan.
+ *
+ * @returns Cached ProjectContext or null if not yet resolved
+ */
+export declare function getCachedContext(): ProjectContext | null;
+//# sourceMappingURL=project-resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project-resolver.d.ts","sourceRoot":"","sources":["../../src/lib/project-resolver.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAmB,MAAM,uBAAuB,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,KAAK,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,8DAA8D;IAC9D,eAAe,EAAE,OAAO,CAAC;IACzB,6CAA6C;IAC7C,eAAe,EAAE,eAAe,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM;CAQ7B;AAsID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAoBjE;AAkGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAQvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAsBrF;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ3F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,GAAG,IAAI,CAExD"}