@agiflowai/aicode-utils 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,419 @@
+# @agiflowai/aicode-utils
+
+Shared utilities and types for AI-powered code generation, scaffolding, and template management in monorepo/monolith workspaces.
+
+## What It Does
+
+Core utilities used across the aicode-toolkit ecosystem:
+- **Template discovery** - Find templates/ folder by walking up from any directory
+- **Workspace detection** - Locate .git root and resolve project structure
+- **Config management** - Read/write toolkit.yaml and project.json configurations
+- **CLI output** - Themed console utilities with consistent formatting
+- **Project resolution** - Find which project owns a given file path
+
+## Installation
+
+```bash
+pnpm add @agiflowai/aicode-utils
+```
+
+## Quick Start
+
+### 1. Find Templates Directory
+
+```typescript
+import { TemplatesManagerService } from '@agiflowai/aicode-utils';
+
+// Searches upward from cwd, checks toolkit.yaml, defaults to templates/
+const templatesPath = await TemplatesManagerService.findTemplatesPath();
+console.log(templatesPath); // /workspace/templates
+```
+
+**Algorithm**:
+1. Find workspace root (searches for .git)
+2. Check toolkit.yaml for custom templatesPath
+3. Falls back to /workspace/templates
+
+### 2. Read Toolkit Configuration
+
+```typescript
+const config = await TemplatesManagerService.readToolkitConfig();
+console.log(config);
+// {
+//   version: '1.0',
+//   templatesPath: 'templates',
+//   projectType: 'monorepo',
+//   sourceTemplate: 'nextjs-15'
+// }
+```
+
+### 3. Pretty CLI Output
+
+```typescript
+import { print, messages, sections } from '@agiflowai/aicode-utils';
+
+messages.success('Templates initialized');
+print.header('Available Templates');
+print.item('nextjs-15');
+print.item('typescript-mcp-package');
+
+sections.createdFiles([
+  'src/app/page.tsx',
+  'src/components/Button.tsx',
+]);
+```
+
+**Output**:
+```
+✅ Templates initialized
+
+Available Templates
+   - nextjs-15
+   - typescript-mcp-package
+
+📁 Created files:
+   - src/app/page.tsx
+   - src/components/Button.tsx
+```
+
+### 4. Find Project Config for File
+
+```typescript
+import { ProjectFinderService } from '@agiflowai/aicode-utils';
+
+const finder = new ProjectFinderService('/workspace');
+const project = await finder.findProjectForFile('/workspace/apps/web/src/page.tsx');
+
+console.log(project);
+// {
+//   name: 'web',
+//   root: '/workspace/apps/web',
+//   sourceTemplate: 'nextjs-15',
+//   projectType: 'monorepo'
+// }
+```
+
+## API Reference
+
+### TemplatesManagerService
+
+Static service for template and workspace management.
+
+#### Find Templates
+
+```typescript
+// Async - searches upward from startPath for workspace root + templates
+static async findTemplatesPath(startPath?: string): Promise<string>
+
+// Sync version
+static findTemplatesPathSync(startPath?: string): string
+
+// Check if templates folder exists
+static async isInitialized(templatesPath: string): Promise<boolean>
+```
+
+#### Workspace Root
+
+```typescript
+// Find workspace root (where .git exists)
+static async getWorkspaceRoot(startPath?: string): Promise<string>
+
+// Sync version
+static getWorkspaceRootSync(startPath?: string): string
+```
+
+#### Toolkit Config (toolkit.yaml)
+
+```typescript
+// Read toolkit.yaml from workspace root
+static async readToolkitConfig(startPath?: string): Promise<ToolkitConfig | null>
+
+// Sync version
+static readToolkitConfigSync(startPath?: string): ToolkitConfig | null
+
+// Write toolkit.yaml to workspace root
+static async writeToolkitConfig(config: ToolkitConfig, startPath?: string): Promise<void>
+```
+
+**ToolkitConfig interface**:
+```typescript
+interface ToolkitConfig {
+  version?: string;
+  templatesPath?: string; // Relative or absolute path
+  projectType?: 'monolith' | 'monorepo';
+  sourceTemplate?: string; // For monolith projects
+}
+```
+
+#### Constants
+
+```typescript
+static getConfigFileName(): string // Returns 'scaffold.yaml'
+static getTemplatesFolderName(): string // Returns 'templates'
+```
+
+### ProjectFinderService
+
+Find project configuration by walking up directory tree.
+
+```typescript
+constructor(workspaceRoot?: string)
+
+// Find project.json for a given file
+async findProjectForFile(filePath: string): Promise<ProjectConfig | null>
+
+// Sync version
+findProjectForFileSync(filePath: string): ProjectConfig | null
+
+// Get workspace root
+getWorkspaceRoot(): string
+
+// Clear internal cache
+clearCache(): void
+```
+
+**ProjectConfig interface**:
+```typescript
+interface ProjectConfig {
+  name: string;
+  root: string; // Absolute path to project directory
+  sourceTemplate?: string;
+  projectType?: 'monolith' | 'monorepo';
+}
+```
+
+**Use case**: Used by MCP servers to determine which template rules apply to a file being edited.
+
+### CLI Output Utilities
+
+#### print - Basic output
+
+```typescript
+import { print } from '@agiflowai/aicode-utils';
+
+print.info('Information message');     // Cyan
+print.success('Success message');      // Green
+print.warning('Warning message');      // Yellow
+print.error('Error message');          // Red
+print.debug('Debug message');          // Gray
+print.header('Section Header');        // Bold cyan
+print.item('List item');               // White with "   - " prefix
+print.indent('Indented text');         // White with "   " prefix
+print.highlight('Important text');     // Bold green
+print.newline();                       // Empty line
+```
+
+#### messages - Output with icons
+
+```typescript
+import { messages } from '@agiflowai/aicode-utils';
+
+messages.info('Info with ℹ️ icon');
+messages.success('Success with ✅ icon');
+messages.error('Error with ❌ icon');
+messages.warning('Warning with ⚠️ icon');
+messages.hint('Hint with 💡 icon');
+messages.loading('Processing with 🚀 icon');
+```
+
+#### sections - Formatted sections
+
+```typescript
+import { sections } from '@agiflowai/aicode-utils';
+
+sections.header('Main Title');
+
+sections.list('Available Options', [
+  'Option 1',
+  'Option 2',
+]);
+
+sections.nextSteps([
+  'Run pnpm install',
+  'Run pnpm dev',
+]);
+
+sections.createdFiles([
+  'src/app/page.tsx',
+  'src/components/Button.tsx',
+], 10); // maxShow = 10
+
+sections.warnings([
+  'Deprecated API usage',
+  'Missing required field',
+]);
+```
+
+#### icons - Emoji constants
+
+```typescript
+import { icons } from '@agiflowai/aicode-utils';
+
+console.log(icons.rocket);    // 🚀
+console.log(icons.check);     // ✅
+console.log(icons.cross);     // ❌
+console.log(icons.warning);   // ⚠️
+console.log(icons.package);   // 📦
+console.log(icons.folder);    // 📁
+console.log(icons.bulb);      // 💡
+// ... and more
+```
+
+### Constants
+
+```typescript
+import { ProjectType, ConfigSource } from '@agiflowai/aicode-utils';
+
+// Project types
+ProjectType.MONOLITH  // 'monolith'
+ProjectType.MONOREPO  // 'monorepo'
+
+// Config sources
+ConfigSource.PROJECT_JSON   // 'project.json'
+ConfigSource.TOOLKIT_YAML   // 'toolkit.yaml'
+```
+
+## Use Cases
+
+### 1. MCP Server Project Detection
+
+MCP servers use this package to detect which project contains a file being edited:
+
+```typescript
+import { ProjectFinderService, TemplatesManagerService } from '@agiflowai/aicode-utils';
+
+const workspaceRoot = await TemplatesManagerService.getWorkspaceRoot();
+const finder = new ProjectFinderService(workspaceRoot);
+
+// User editing apps/web/src/components/Button.tsx
+const project = await finder.findProjectForFile(
+  '/workspace/apps/web/src/components/Button.tsx'
+);
+
+if (project?.sourceTemplate === 'nextjs-15') {
+  // Apply Next.js 15 specific rules
+}
+```
+
+### 2. CLI Tool Template Discovery
+
+CLI tools use this to find templates without requiring user configuration:
+
+```typescript
+import { TemplatesManagerService } from '@agiflowai/aicode-utils';
+
+// Automatically finds templates even when run from nested directories
+const templatesPath = await TemplatesManagerService.findTemplatesPath();
+const scaffoldYaml = path.join(templatesPath, 'nextjs-15', 'scaffold.yaml');
+```
+
+### 3. Consistent CLI Output
+
+Build polished CLI tools with consistent formatting:
+
+```typescript
+import { messages, sections, print } from '@agiflowai/aicode-utils';
+
+messages.loading('Downloading templates...');
+
+sections.header('Setup Complete!');
+sections.nextSteps([
+  'cd my-project',
+  'pnpm install',
+  'pnpm dev',
+]);
+
+print.highlight('🎉 Ready to code!');
+```
+
+### 4. Workspace Configuration Management
+
+Read and write toolkit.yaml for project configuration:
+
+```typescript
+import { TemplatesManagerService } from '@agiflowai/aicode-utils';
+
+// Read existing config
+const config = await TemplatesManagerService.readToolkitConfig();
+
+// Update config
+await TemplatesManagerService.writeToolkitConfig({
+  version: '1.0',
+  templatesPath: 'custom-templates',
+  projectType: 'monorepo',
+});
+```
+
+## Architecture
+
+**Design patterns**:
+- Static service classes for utility functions
+- File system traversal with caching
+- Upward directory search (finds .git root)
+- Consistent error handling with descriptive messages
+
+**Key features**:
+- Both async and sync APIs for flexibility
+- Caching in ProjectFinderService for performance
+- Graceful fallbacks (defaults to cwd if no .git found)
+- Type-safe constants with `as const` assertions
+
+**Dependencies**:
+- `chalk` - Terminal colors and styling
+- `fs-extra` - Enhanced file system operations
+- `js-yaml` - YAML parsing for toolkit.yaml
+- `pino` - Structured logging
+
+## Common Patterns
+
+### Workspace Root Discovery
+
+All services use the same algorithm:
+1. Start from provided path (or cwd)
+2. Walk up directories looking for .git
+3. Return .git parent directory
+4. Fallback to cwd if no .git found
+
+### Template Path Resolution
+
+1. Find workspace root
+2. Check toolkit.yaml for custom templatesPath
+3. Handle absolute or relative paths
+4. Fallback to /workspace/templates
+5. Throw descriptive error if not found
+
+### Project Config Resolution
+
+1. Start from file path
+2. Walk up directories
+3. Find first project.json
+4. Parse and cache result
+5. Return null if none found
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+## Related Packages
+
+- `@agiflowai/aicode-toolkit` - CLI tool using these utilities
+- `@agiflowai/architect-mcp` - MCP server using project detection
+- `@agiflowai/scaffold-mcp` - MCP server using template discovery
+
+## License
+
+AGPL-3.0
+
+## Links
+
+- [GitHub](https://github.com/AgiFlow/aicode-toolkit)
+- [Issues](https://github.com/AgiFlow/aicode-toolkit/issues)

package/dist/index.cjs

@@ -29,6 +29,8 @@ let node_os = require("node:os");
 node_os = __toESM(node_os);
 let pino = require("pino");
 pino = __toESM(pino);
+let js_yaml = require("js-yaml");
+js_yaml = __toESM(js_yaml);
 let chalk = require("chalk");
 chalk = __toESM(chalk);
 
@@ -613,6 +615,9 @@ const print = {
 	},
 	newline: () => {
 		console.log();
+	},
+	divider: () => {
+		console.log(chalk.default.gray("·".repeat(60)));
 	}
 };
 /**
@@ -696,6 +701,92 @@ const sections = {
 	}
 };
 
+//#endregion
+//#region src/utils/projectTypeDetector.ts
+/**
+* Monorepo configuration files that indicate a monorepo setup
+*/
+const MONOREPO_INDICATOR_FILES = [
+	"nx.json",
+	"turbo.json",
+	"rush.json",
+	"lerna.json",
+	"pnpm-workspace.yaml"
+];
+/**
+* Detect project type (monorepo vs monolith) based on workspace files
+* Deterministic detection: monorepo exists when monorepo configuration files are found
+*
+* Detection priority:
+* 1. toolkit.yaml (highest priority - explicit configuration)
+* 2. Monorepo configuration files (nx.json, turbo.json, rush.json, lerna.json, pnpm-workspace.yaml)
+* 3. package.json with workspaces field (npm/yarn workspaces)
+* 4. If nothing found, returns undefined (user should choose)
+*
+* @param workspaceRoot - Absolute path to the workspace root directory
+* @returns Detection result with project type and indicators
+*/
+async function detectProjectType(workspaceRoot) {
+	const indicators = [];
+	const toolkitYamlPath = node_path.default.join(workspaceRoot, "toolkit.yaml");
+	if (await fs_extra.pathExists(toolkitYamlPath)) try {
+		const content = await fs_extra.readFile(toolkitYamlPath, "utf-8");
+		const config = js_yaml.load(content);
+		if (config?.projectType) {
+			indicators.push(`toolkit.yaml specifies ${config.projectType}`);
+			return {
+				projectType: config.projectType,
+				indicators
+			};
+		}
+	} catch {}
+	for (const filename of MONOREPO_INDICATOR_FILES) {
+		const filePath = node_path.default.join(workspaceRoot, filename);
+		if (await fs_extra.pathExists(filePath)) {
+			indicators.push(`${filename} found`);
+			return {
+				projectType: ProjectType.MONOREPO,
+				indicators
+			};
+		}
+	}
+	const packageJsonPath = node_path.default.join(workspaceRoot, "package.json");
+	if (await fs_extra.pathExists(packageJsonPath)) try {
+		if ((await fs_extra.readJson(packageJsonPath)).workspaces) {
+			indicators.push("package.json with workspaces found");
+			return {
+				projectType: ProjectType.MONOREPO,
+				indicators
+			};
+		}
+	} catch {}
+	indicators.push("No monorepo indicators found");
+	return {
+		projectType: void 0,
+		indicators
+	};
+}
+/**
+* Check if a workspace is a monorepo
+* Convenience function that returns a boolean
+*
+* @param workspaceRoot - Absolute path to the workspace root directory
+* @returns True if workspace is detected as monorepo, false otherwise
+*/
+async function isMonorepo(workspaceRoot) {
+	return (await detectProjectType(workspaceRoot)).projectType === ProjectType.MONOREPO;
+}
+/**
+* Check if a workspace is a monolith
+* Convenience function that returns a boolean
+*
+* @param workspaceRoot - Absolute path to the workspace root directory
+* @returns True if workspace is detected as monolith, false otherwise
+*/
+async function isMonolith(workspaceRoot) {
+	return (await detectProjectType(workspaceRoot)).projectType === ProjectType.MONOLITH;
+}
+
 //#endregion
 exports.ConfigSource = ConfigSource;
 exports.ProjectConfigResolver = ProjectConfigResolver;
@@ -703,7 +794,10 @@ exports.ProjectFinderService = ProjectFinderService;
 exports.ProjectType = ProjectType;
 exports.ScaffoldProcessingService = ScaffoldProcessingService;
 exports.TemplatesManagerService = TemplatesManagerService;
+exports.detectProjectType = detectProjectType;
 exports.icons = icons;
+exports.isMonolith = isMonolith;
+exports.isMonorepo = isMonorepo;
 exports.log = log;
 exports.logger = logger;
 exports.messages = messages;

package/dist/index.d.cts

@@ -42,59 +42,16 @@ interface NxProjectJson {
   [key: string]: unknown;
 }
 //#endregion
-//#region src/services/ProjectConfigResolver.d.ts
+//#region src/types/index.d.ts
 /**
- * ProjectConfigResolver
- *
- * Resolves project configuration from multiple sources with priority:
- * 1. project.json (monorepo - Nx/Lerna/Turborepo)
- * 2. toolkit.yaml at workspace root (monolith)
+ * Toolkit configuration from toolkit.yaml
  */
-declare class ProjectConfigResolver {
-  /**
-   * Resolve project configuration with priority fallback
-   *
-   * Priority order:
-   * 1. Check for project.json (monorepo case)
-   * 2. Check for toolkit.yaml at workspace root (monolith case)
-   * 3. Error with helpful message
-   *
-   * @param projectPath - Absolute path to the project directory
-   * @param explicitTemplate - Optional explicit template override
-   * @returns Project configuration result
-   * @throws Error if no configuration found
-   */
-  static resolveProjectConfig(projectPath: string, explicitTemplate?: string): Promise<ProjectConfigResult>;
-  /**
-   * Get helpful error message when no configuration is found
-   */
-  private static getHelpfulErrorMessage;
-  /**
-   * Check if project has configuration (without throwing error)
-   *
-   * @param projectPath - Absolute path to the project directory
-   * @returns true if configuration exists, false otherwise
-   * @throws Error if there's a filesystem error (not just missing config)
-   */
-  static hasConfiguration(projectPath: string): Promise<boolean>;
-  /**
-   * Create toolkit.yaml for monolith projects
-   *
-   * @param sourceTemplate - The template identifier
-   * @param workspaceRoot - Optional workspace root path (defaults to current directory)
-   */
-  static createToolkitYaml(sourceTemplate: string, workspaceRoot?: string): Promise<void>;
-  /**
-   * Create or update project.json for monorepo projects
-   *
-   * @param projectPath - Absolute path to the project directory
-   * @param projectName - Name of the project
-   * @param sourceTemplate - The template identifier
-   */
-  static createProjectJson(projectPath: string, projectName: string, sourceTemplate: string): Promise<void>;
+interface ToolkitConfig {
+  version?: string;
+  templatesPath?: string;
+  projectType?: 'monolith' | 'monorepo';
+  sourceTemplate?: string;
 }
-//#endregion
-//#region src/types/index.d.ts
 /**
  * Project configuration from project.json
  */
@@ -166,6 +123,58 @@ interface GeneratorContext {
  */
 type GeneratorFunction = (context: GeneratorContext) => Promise<ScaffoldResult>;
 //#endregion
+//#region src/services/ProjectConfigResolver.d.ts
+/**
+ * ProjectConfigResolver
+ *
+ * Resolves project configuration from multiple sources with priority:
+ * 1. project.json (monorepo - Nx/Lerna/Turborepo)
+ * 2. toolkit.yaml at workspace root (monolith)
+ */
+declare class ProjectConfigResolver {
+  /**
+   * Resolve project configuration with priority fallback
+   *
+   * Priority order:
+   * 1. Check for project.json (monorepo case)
+   * 2. Check for toolkit.yaml at workspace root (monolith case)
+   * 3. Error with helpful message
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param explicitTemplate - Optional explicit template override
+   * @returns Project configuration result
+   * @throws Error if no configuration found
+   */
+  static resolveProjectConfig(projectPath: string, explicitTemplate?: string): Promise<ProjectConfigResult>;
+  /**
+   * Get helpful error message when no configuration is found
+   */
+  private static getHelpfulErrorMessage;
+  /**
+   * Check if project has configuration (without throwing error)
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @returns true if configuration exists, false otherwise
+   * @throws Error if there's a filesystem error (not just missing config)
+   */
+  static hasConfiguration(projectPath: string): Promise<boolean>;
+  /**
+   * Create toolkit.yaml for monolith projects
+   *
+   * @param sourceTemplate - The template identifier
+   * @param workspaceRoot - Optional workspace root path (defaults to current directory)
+   */
+  static createToolkitYaml(sourceTemplate: string, workspaceRoot?: string): Promise<void>;
+  /**
+   * Create or update project.json for monorepo projects
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param projectName - Name of the project
+   * @param sourceTemplate - The template identifier
+   */
+  static createProjectJson(projectPath: string, projectName: string, sourceTemplate: string): Promise<void>;
+}
+//#endregion
 //#region src/services/ProjectFinderService.d.ts
 declare class ProjectFinderService {
   private projectCache;
@@ -239,35 +248,6 @@ declare class ScaffoldProcessingService {
 }
 //#endregion
 //#region src/services/TemplatesManagerService.d.ts
-/**
- * TemplatesManagerService
- *
- * DESIGN PATTERNS:
- * - Class-based service pattern for encapsulating business logic
- * - Static methods for utility-like functionality
- * - File system traversal for workspace detection
- * - Configuration-driven template path resolution
- *
- * CODING STANDARDS:
- * - Service class names use PascalCase with 'Service' suffix
- * - Method names use camelCase with descriptive verbs
- * - Return types should be explicit (never use implicit any)
- * - Use async/await for asynchronous operations
- * - Handle errors with try-catch and throw descriptive Error objects
- * - Document public methods with JSDoc comments
- *
- * AVOID:
- * - Side effects in constructors (keep them lightweight)
- * - Mixing concerns (keep services focused on single domain)
- * - Direct coupling to other services (use dependency injection)
- * - Exposing internal implementation details
- */
-interface ToolkitConfig {
-  version?: string;
-  templatesPath?: string;
-  projectType?: 'monolith' | 'monorepo';
-  sourceTemplate?: string;
-}
 declare class TemplatesManagerService {
   private static SCAFFOLD_CONFIG_FILE;
   private static TEMPLATES_FOLDER;
@@ -411,6 +391,10 @@ declare const print: {
    * Empty line
    */
   newline: () => void;
+  /**
+   * Print a visual divider (dots)
+   */
+  divider: () => void;
 };
 /**
  * Emoji icons for consistent visual markers
@@ -489,4 +473,45 @@ declare const sections: {
   warnings: (warnings: string[]) => void;
 };
 //#endregion
-export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, icons, log, logger, messages, print, sections };
+//#region src/utils/projectTypeDetector.d.ts
+/**
+ * Result of project type detection
+ */
+interface ProjectTypeDetectionResult {
+  /** Detected project type (undefined if not detected) */
+  projectType?: ProjectType;
+  /** List of indicators that led to the detection */
+  indicators: string[];
+}
+/**
+ * Detect project type (monorepo vs monolith) based on workspace files
+ * Deterministic detection: monorepo exists when monorepo configuration files are found
+ *
+ * Detection priority:
+ * 1. toolkit.yaml (highest priority - explicit configuration)
+ * 2. Monorepo configuration files (nx.json, turbo.json, rush.json, lerna.json, pnpm-workspace.yaml)
+ * 3. package.json with workspaces field (npm/yarn workspaces)
+ * 4. If nothing found, returns undefined (user should choose)
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns Detection result with project type and indicators
+ */
+declare function detectProjectType(workspaceRoot: string): Promise<ProjectTypeDetectionResult>;
+/**
+ * Check if a workspace is a monorepo
+ * Convenience function that returns a boolean
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns True if workspace is detected as monorepo, false otherwise
+ */
+declare function isMonorepo(workspaceRoot: string): Promise<boolean>;
+/**
+ * Check if a workspace is a monolith
+ * Convenience function that returns a boolean
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns True if workspace is detected as monolith, false otherwise
+ */
+declare function isMonolith(workspaceRoot: string): Promise<boolean>;
+//#endregion
+export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ProjectTypeDetectionResult, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, detectProjectType, icons, isMonolith, isMonorepo, log, logger, messages, print, sections };

package/dist/index.d.ts

@@ -42,59 +42,16 @@ interface NxProjectJson {
   [key: string]: unknown;
 }
 //#endregion
-//#region src/services/ProjectConfigResolver.d.ts
+//#region src/types/index.d.ts
 /**
- * ProjectConfigResolver
- *
- * Resolves project configuration from multiple sources with priority:
- * 1. project.json (monorepo - Nx/Lerna/Turborepo)
- * 2. toolkit.yaml at workspace root (monolith)
+ * Toolkit configuration from toolkit.yaml
  */
-declare class ProjectConfigResolver {
-  /**
-   * Resolve project configuration with priority fallback
-   *
-   * Priority order:
-   * 1. Check for project.json (monorepo case)
-   * 2. Check for toolkit.yaml at workspace root (monolith case)
-   * 3. Error with helpful message
-   *
-   * @param projectPath - Absolute path to the project directory
-   * @param explicitTemplate - Optional explicit template override
-   * @returns Project configuration result
-   * @throws Error if no configuration found
-   */
-  static resolveProjectConfig(projectPath: string, explicitTemplate?: string): Promise<ProjectConfigResult>;
-  /**
-   * Get helpful error message when no configuration is found
-   */
-  private static getHelpfulErrorMessage;
-  /**
-   * Check if project has configuration (without throwing error)
-   *
-   * @param projectPath - Absolute path to the project directory
-   * @returns true if configuration exists, false otherwise
-   * @throws Error if there's a filesystem error (not just missing config)
-   */
-  static hasConfiguration(projectPath: string): Promise<boolean>;
-  /**
-   * Create toolkit.yaml for monolith projects
-   *
-   * @param sourceTemplate - The template identifier
-   * @param workspaceRoot - Optional workspace root path (defaults to current directory)
-   */
-  static createToolkitYaml(sourceTemplate: string, workspaceRoot?: string): Promise<void>;
-  /**
-   * Create or update project.json for monorepo projects
-   *
-   * @param projectPath - Absolute path to the project directory
-   * @param projectName - Name of the project
-   * @param sourceTemplate - The template identifier
-   */
-  static createProjectJson(projectPath: string, projectName: string, sourceTemplate: string): Promise<void>;
+interface ToolkitConfig {
+  version?: string;
+  templatesPath?: string;
+  projectType?: 'monolith' | 'monorepo';
+  sourceTemplate?: string;
 }
-//#endregion
-//#region src/types/index.d.ts
 /**
  * Project configuration from project.json
  */
@@ -166,6 +123,58 @@ interface GeneratorContext {
  */
 type GeneratorFunction = (context: GeneratorContext) => Promise<ScaffoldResult>;
 //#endregion
+//#region src/services/ProjectConfigResolver.d.ts
+/**
+ * ProjectConfigResolver
+ *
+ * Resolves project configuration from multiple sources with priority:
+ * 1. project.json (monorepo - Nx/Lerna/Turborepo)
+ * 2. toolkit.yaml at workspace root (monolith)
+ */
+declare class ProjectConfigResolver {
+  /**
+   * Resolve project configuration with priority fallback
+   *
+   * Priority order:
+   * 1. Check for project.json (monorepo case)
+   * 2. Check for toolkit.yaml at workspace root (monolith case)
+   * 3. Error with helpful message
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param explicitTemplate - Optional explicit template override
+   * @returns Project configuration result
+   * @throws Error if no configuration found
+   */
+  static resolveProjectConfig(projectPath: string, explicitTemplate?: string): Promise<ProjectConfigResult>;
+  /**
+   * Get helpful error message when no configuration is found
+   */
+  private static getHelpfulErrorMessage;
+  /**
+   * Check if project has configuration (without throwing error)
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @returns true if configuration exists, false otherwise
+   * @throws Error if there's a filesystem error (not just missing config)
+   */
+  static hasConfiguration(projectPath: string): Promise<boolean>;
+  /**
+   * Create toolkit.yaml for monolith projects
+   *
+   * @param sourceTemplate - The template identifier
+   * @param workspaceRoot - Optional workspace root path (defaults to current directory)
+   */
+  static createToolkitYaml(sourceTemplate: string, workspaceRoot?: string): Promise<void>;
+  /**
+   * Create or update project.json for monorepo projects
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param projectName - Name of the project
+   * @param sourceTemplate - The template identifier
+   */
+  static createProjectJson(projectPath: string, projectName: string, sourceTemplate: string): Promise<void>;
+}
+//#endregion
 //#region src/services/ProjectFinderService.d.ts
 declare class ProjectFinderService {
   private projectCache;
@@ -239,35 +248,6 @@ declare class ScaffoldProcessingService {
 }
 //#endregion
 //#region src/services/TemplatesManagerService.d.ts
-/**
- * TemplatesManagerService
- *
- * DESIGN PATTERNS:
- * - Class-based service pattern for encapsulating business logic
- * - Static methods for utility-like functionality
- * - File system traversal for workspace detection
- * - Configuration-driven template path resolution
- *
- * CODING STANDARDS:
- * - Service class names use PascalCase with 'Service' suffix
- * - Method names use camelCase with descriptive verbs
- * - Return types should be explicit (never use implicit any)
- * - Use async/await for asynchronous operations
- * - Handle errors with try-catch and throw descriptive Error objects
- * - Document public methods with JSDoc comments
- *
- * AVOID:
- * - Side effects in constructors (keep them lightweight)
- * - Mixing concerns (keep services focused on single domain)
- * - Direct coupling to other services (use dependency injection)
- * - Exposing internal implementation details
- */
-interface ToolkitConfig {
-  version?: string;
-  templatesPath?: string;
-  projectType?: 'monolith' | 'monorepo';
-  sourceTemplate?: string;
-}
 declare class TemplatesManagerService {
   private static SCAFFOLD_CONFIG_FILE;
   private static TEMPLATES_FOLDER;
@@ -411,6 +391,10 @@ declare const print: {
    * Empty line
    */
   newline: () => void;
+  /**
+   * Print a visual divider (dots)
+   */
+  divider: () => void;
 };
 /**
  * Emoji icons for consistent visual markers
@@ -489,4 +473,45 @@ declare const sections: {
   warnings: (warnings: string[]) => void;
 };
 //#endregion
-export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, icons, log, logger, messages, print, sections };
+//#region src/utils/projectTypeDetector.d.ts
+/**
+ * Result of project type detection
+ */
+interface ProjectTypeDetectionResult {
+  /** Detected project type (undefined if not detected) */
+  projectType?: ProjectType;
+  /** List of indicators that led to the detection */
+  indicators: string[];
+}
+/**
+ * Detect project type (monorepo vs monolith) based on workspace files
+ * Deterministic detection: monorepo exists when monorepo configuration files are found
+ *
+ * Detection priority:
+ * 1. toolkit.yaml (highest priority - explicit configuration)
+ * 2. Monorepo configuration files (nx.json, turbo.json, rush.json, lerna.json, pnpm-workspace.yaml)
+ * 3. package.json with workspaces field (npm/yarn workspaces)
+ * 4. If nothing found, returns undefined (user should choose)
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns Detection result with project type and indicators
+ */
+declare function detectProjectType(workspaceRoot: string): Promise<ProjectTypeDetectionResult>;
+/**
+ * Check if a workspace is a monorepo
+ * Convenience function that returns a boolean
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns True if workspace is detected as monorepo, false otherwise
+ */
+declare function isMonorepo(workspaceRoot: string): Promise<boolean>;
+/**
+ * Check if a workspace is a monolith
+ * Convenience function that returns a boolean
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory
+ * @returns True if workspace is detected as monolith, false otherwise
+ */
+declare function isMonolith(workspaceRoot: string): Promise<boolean>;
+//#endregion
+export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ProjectTypeDetectionResult, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, detectProjectType, icons, isMonolith, isMonorepo, log, logger, messages, print, sections };

package/dist/index.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import * as fs from "fs-extra";
 import * as os from "node:os";
 import pino from "pino";
+import * as yaml from "js-yaml";
 import chalk from "chalk";
 
 //#region rolldown:runtime
@@ -69,9 +70,9 @@ var TemplatesManagerService = class TemplatesManagerService {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
 		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		if (await fs.pathExists(toolkitConfigPath)) {
-			const yaml = await import("js-yaml");
+			const yaml$1 = await import("js-yaml");
 			const content = await fs.readFile(toolkitConfigPath, "utf-8");
-			const config = yaml.load(content);
+			const config = yaml$1.load(content);
 			if (config?.templatesPath) {
 				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
 				if (await fs.pathExists(templatesPath$1)) return templatesPath$1;
@@ -107,9 +108,9 @@ var TemplatesManagerService = class TemplatesManagerService {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
 		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		if (fs.pathExistsSync(toolkitConfigPath)) {
-			const yaml = __require("js-yaml");
+			const yaml$1 = __require("js-yaml");
 			const content = fs.readFileSync(toolkitConfigPath, "utf-8");
-			const config = yaml.load(content);
+			const config = yaml$1.load(content);
 			if (config?.templatesPath) {
 				const templatesPath$1 = path.isAbsolute(config.templatesPath) ? config.templatesPath : path.join(workspaceRoot, config.templatesPath);
 				if (fs.pathExistsSync(templatesPath$1)) return templatesPath$1;
@@ -165,9 +166,9 @@ var TemplatesManagerService = class TemplatesManagerService {
 		const workspaceRoot = await TemplatesManagerService.findWorkspaceRoot(startPath);
 		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		if (!await fs.pathExists(toolkitConfigPath)) return null;
-		const yaml = await import("js-yaml");
+		const yaml$1 = await import("js-yaml");
 		const content = await fs.readFile(toolkitConfigPath, "utf-8");
-		return yaml.load(content);
+		return yaml$1.load(content);
 	}
 	/**
 	* Read toolkit.yaml configuration from workspace root (sync)
@@ -179,9 +180,9 @@ var TemplatesManagerService = class TemplatesManagerService {
 		const workspaceRoot = TemplatesManagerService.findWorkspaceRootSync(startPath);
 		const toolkitConfigPath = path.join(workspaceRoot, TemplatesManagerService.TOOLKIT_CONFIG_FILE);
 		if (!fs.pathExistsSync(toolkitConfigPath)) return null;
-		const yaml = __require("js-yaml");
+		const yaml$1 = __require("js-yaml");
 		const content = fs.readFileSync(toolkitConfigPath, "utf-8");
-		return yaml.load(content);
+		return yaml$1.load(content);
 	}
 	/**
 	* Write toolkit.yaml configuration to workspace root
@@ -591,6 +592,9 @@ const print = {
 	},
 	newline: () => {
 		console.log();
+	},
+	divider: () => {
+		console.log(chalk.gray("·".repeat(60)));
 	}
 };
 /**
@@ -675,4 +679,90 @@ const sections = {
 };
 
 //#endregion
-export { ConfigSource, ProjectConfigResolver, ProjectFinderService, ProjectType, ScaffoldProcessingService, TemplatesManagerService, icons, log, logger, messages, print, sections };
+//#region src/utils/projectTypeDetector.ts
+/**
+* Monorepo configuration files that indicate a monorepo setup
+*/
+const MONOREPO_INDICATOR_FILES = [
+	"nx.json",
+	"turbo.json",
+	"rush.json",
+	"lerna.json",
+	"pnpm-workspace.yaml"
+];
+/**
+* Detect project type (monorepo vs monolith) based on workspace files
+* Deterministic detection: monorepo exists when monorepo configuration files are found
+*
+* Detection priority:
+* 1. toolkit.yaml (highest priority - explicit configuration)
+* 2. Monorepo configuration files (nx.json, turbo.json, rush.json, lerna.json, pnpm-workspace.yaml)
+* 3. package.json with workspaces field (npm/yarn workspaces)
+* 4. If nothing found, returns undefined (user should choose)
+*
+* @param workspaceRoot - Absolute path to the workspace root directory
+* @returns Detection result with project type and indicators
+*/
+async function detectProjectType(workspaceRoot) {
+	const indicators = [];
+	const toolkitYamlPath = path.join(workspaceRoot, "toolkit.yaml");
+	if (await fs.pathExists(toolkitYamlPath)) try {
+		const content = await fs.readFile(toolkitYamlPath, "utf-8");
+		const config = yaml.load(content);
+		if (config?.projectType) {
+			indicators.push(`toolkit.yaml specifies ${config.projectType}`);
+			return {
+				projectType: config.projectType,
+				indicators
+			};
+		}
+	} catch {}
+	for (const filename of MONOREPO_INDICATOR_FILES) {
+		const filePath = path.join(workspaceRoot, filename);
+		if (await fs.pathExists(filePath)) {
+			indicators.push(`${filename} found`);
+			return {
+				projectType: ProjectType.MONOREPO,
+				indicators
+			};
+		}
+	}
+	const packageJsonPath = path.join(workspaceRoot, "package.json");
+	if (await fs.pathExists(packageJsonPath)) try {
+		if ((await fs.readJson(packageJsonPath)).workspaces) {
+			indicators.push("package.json with workspaces found");
+			return {
+				projectType: ProjectType.MONOREPO,
+				indicators
+			};
+		}
+	} catch {}
+	indicators.push("No monorepo indicators found");
+	return {
+		projectType: void 0,
+		indicators
+	};
+}
+/**
+* Check if a workspace is a monorepo
+* Convenience function that returns a boolean
+*
+* @param workspaceRoot - Absolute path to the workspace root directory
+* @returns True if workspace is detected as monorepo, false otherwise
+*/
+async function isMonorepo(workspaceRoot) {
+	return (await detectProjectType(workspaceRoot)).projectType === ProjectType.MONOREPO;
+}
+/**
+* Check if a workspace is a monolith
+* Convenience function that returns a boolean
+*
+* @param workspaceRoot - Absolute path to the workspace root directory
+* @returns True if workspace is detected as monolith, false otherwise
+*/
+async function isMonolith(workspaceRoot) {
+	return (await detectProjectType(workspaceRoot)).projectType === ProjectType.MONOLITH;
+}
+
+//#endregion
+export { ConfigSource, ProjectConfigResolver, ProjectFinderService, ProjectType, ScaffoldProcessingService, TemplatesManagerService, detectProjectType, icons, isMonolith, isMonorepo, log, logger, messages, print, sections };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/aicode-utils",
   "description": "Shared utilities and types for AI-powered code generation, scaffolding, and analysis",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {
@@ -33,12 +33,14 @@
     "chalk": "5.6.2",
     "fs-extra": "11.3.2",
     "js-yaml": "4.1.0",
+    "ora": "^9.0.0",
     "pino": "^10.0.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@types/ora": "^3.2.0",
     "@vitest/coverage-v8": "^3.0.0",
     "tsdown": "^0.15.6",
     "typescript": "5.9.3",