@aiready/cli 0.13.0 → 0.13.2

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/cli@0.12.23 build /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.13.2 build /Users/pengcao/projects/aiready/packages/cli
 > tsup src/index.ts src/cli.ts --format cjs,esm
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -10,7 +10,7 @@
 CJS Build start
 ESM Build start
 
- WARN  ▲ [WARNING] "import.meta" is not available with the "cjs" output format and will be empty [empty-import-meta]         6:35:40 pm
+ WARN  ▲ [WARNING] "import.meta" is not available with the "cjs" output format and will be empty [empty-import-meta]            7:51:15 pm
 
     src/cli.ts:32:31:
       32 │   return dirname(fileURLToPath(import.meta.url));
@@ -20,10 +20,10 @@
 
 
 
-CJS dist/index.js 10.62 KB
-CJS dist/cli.js   80.29 KB
-CJS ⚡️ Build success in 34ms
-ESM dist/cli.mjs            66.94 KB
-ESM dist/chunk-VOKP7FGM.mjs 9.52 KB
 ESM dist/index.mjs          170.00 B
-ESM ⚡️ Build success in 34ms
+ESM dist/chunk-VOKP7FGM.mjs 9.52 KB
+ESM dist/cli.mjs            68.68 KB
+ESM ⚡️ Build success in 30ms
+CJS dist/index.js 10.62 KB
+CJS dist/cli.js   82.21 KB
+CJS ⚡️ Build success in 30ms

package/.turbo/turbo-test.log

@@ -1,19 +1,20 @@
 
 
-> @aiready/cli@0.12.23 test /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.13.0 test /Users/pengcao/projects/aiready/packages/cli
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/cli
 
- ✓ src/commands/__tests__/testability.test.ts (2 tests) 19ms
- ✓ src/commands/__tests__/deps-health.test.ts (1 test) 16ms
- ✓ src/commands/__tests__/doc-drift.test.ts (1 test) 19ms
- ✓ src/commands/__tests__/agent-grounding.test.ts (1 test) 18ms
- ✓ src/commands/__tests__/ai-signal-clarity.test.ts (1 test) 8ms
+ ✓ src/utils/__tests__/helpers.test.ts (3 tests) 5ms
 stdout | src/commands/__tests__/visualize.test.ts > Visualize CLI Action > should generate HTML from specified report
 Building graph from report...
 
+ ✓ src/commands/__tests__/testability.test.ts (2 tests) 14ms
+ ✓ src/commands/__tests__/ai-signal-clarity.test.ts (1 test) 13ms
+ ✓ src/commands/__tests__/deps-health.test.ts (1 test) 12ms
+ ✓ src/commands/__tests__/doc-drift.test.ts (1 test) 25ms
+ ✓ src/commands/__tests__/agent-grounding.test.ts (1 test) 25ms
 stdout | src/commands/__tests__/visualize.test.ts > Visualize CLI Action > should generate HTML from specified report
 Generating HTML...
 ✅ Visualization written to: /Users/pengcao/projects/aiready/packages/cli/visualization.html
@@ -41,8 +42,7 @@ Or specify a custom report:
 Generating HTML...
 ✅ Visualization written to: /Users/pengcao/projects/aiready/packages/cli/visualization.html
 
- ✓ src/commands/__tests__/visualize.test.ts (4 tests) 30ms
- ✓ src/utils/__tests__/helpers.test.ts (3 tests) 6ms
+ ✓ src/commands/__tests__/visualize.test.ts (4 tests) 34ms
 stdout | src/commands/__tests__/upload.test.ts > Upload CLI Action > should fail if API key is missing
    Set AIREADY_API_KEY environment variable or use --api-key flag.
    Get an API key from https://platform.getaiready.dev/dashboard
@@ -58,18 +58,18 @@ Or specify a custom report:
    Score: 80/100
 
  ✓ src/commands/__tests__/upload.test.ts (2 tests) 5ms
- ✓ src/commands/__tests__/consistency.test.ts (4 tests) 6ms
- ✓ src/commands/__tests__/scan.test.ts (6 tests) 140ms
- ✓ src/commands/__tests__/extra-commands.test.ts (8 tests) 122ms
+ ✓ src/commands/__tests__/consistency.test.ts (4 tests) 4ms
+ ✓ src/commands/__tests__/scan.test.ts (6 tests) 77ms
  ✓ src/__tests__/unified.test.ts (4 tests) 3ms
- ✓ src/__tests__/cli.test.ts (3 tests) 3121ms
-     ✓ should run unified analysis with both tools  3120ms
- ✓ src/__tests__/config-shape.test.ts (3 tests) 3122ms
-     ✓ should generate a strictly portable AIReadyConfig in summary  3121ms
+ ✓ src/commands/__tests__/extra-commands.test.ts (8 tests) 93ms
+ ✓ src/__tests__/cli.test.ts (3 tests) 3317ms
+     ✓ should run unified analysis with both tools  3316ms
+ ✓ src/__tests__/config-shape.test.ts (3 tests) 3318ms
+     ✓ should generate a strictly portable AIReadyConfig in summary  3316ms
 
  Test Files  14 passed (14)
       Tests  43 passed (43)
-   Start at  18:35:57
-   Duration  4.61s (transform 3.16s, setup 0ms, import 7.21s, tests 6.64s, environment 2ms)
+   Start at  00:58:55
+   Duration  4.20s (transform 1.99s, setup 0ms, import 4.11s, tests 6.94s, environment 1ms)
 
 [?25h

package/CONTRIBUTING.md

@@ -196,7 +196,7 @@ src/
 Great places to start:
 
 - **New commands**: Add new CLI commands
-- **Tool integration**: Integrate new analysis tools
+- **Tool integration**: Integrate new analysis tools. Follow the [Spoke Development Guide](./docs/SPOKE_GUIDE.md) for more details.
 - **Output formats**: Add new output options (XML, CSV, HTML)
 - **Configuration**: Improve config file handling
 - **Performance**: Optimize for large codebases

package/README.md

@@ -50,10 +50,15 @@ aiready scan .
 
 # Run a specific tool
 aiready patterns . --similarity 0.6
-````
+```
+
+## 🛠️ Building Your Own Tool (Spokes)
+
+Want to build your own analysis tool that integrates with the AIReady ecosystem? Check out our [Spoke Development Guide](./docs/SPOKE_GUIDE.md).
 
 ## 🌐 Platform Integration
 
+
 Connect your local scans to the [AIReady Dashboard](https://platform.getaiready.dev/dashboard).
 
 ### Automatic Upload
@@ -85,3 +90,4 @@ MIT
 ```
 
 ```
+````

package/dist/cli.js

@@ -550,6 +550,24 @@ async function scanAction(directory, options) {
         case "cost":
           profileTools = [import_core3.ToolName.PatternDetect, import_core3.ToolName.ContextAnalyzer];
           break;
+        case "logic":
+          profileTools = [
+            import_core3.ToolName.TestabilityIndex,
+            import_core3.ToolName.NamingConsistency,
+            import_core3.ToolName.ContextAnalyzer,
+            import_core3.ToolName.PatternDetect,
+            import_core3.ToolName.ChangeAmplification
+          ];
+          break;
+        case "ui":
+          profileTools = [
+            import_core3.ToolName.NamingConsistency,
+            import_core3.ToolName.ContextAnalyzer,
+            import_core3.ToolName.PatternDetect,
+            import_core3.ToolName.DocDrift,
+            import_core3.ToolName.AiSignalClarity
+          ];
+          break;
         case "security":
           profileTools = [
             import_core3.ToolName.NamingConsistency,
@@ -619,6 +637,7 @@ async function scanAction(directory, options) {
           );
       }
     };
+    const scoringProfile = options.profile || baseOptions.scoring?.profile || "default";
     const results = await analyzeUnified({
       ...finalOptions,
       progressCallback,
@@ -635,9 +654,16 @@ async function scanAction(directory, options) {
     );
     let scoringResult;
     if (options.score || finalOptions.scoring?.showBreakdown) {
-      scoringResult = await scoreUnified(results, finalOptions);
+      scoringResult = await scoreUnified(results, {
+        ...finalOptions,
+        scoring: {
+          ...finalOptions.scoring,
+          profile: scoringProfile
+        }
+      });
       console.log(import_chalk3.default.bold("\n\u{1F4CA} AI Readiness Overall Score"));
       console.log(`  ${(0, import_core3.formatScore)(scoringResult)}`);
+      console.log(import_chalk3.default.dim(`  (Scoring Profile: ${scoringProfile})`));
       if (options.compareTo) {
         try {
           const prevReport = JSON.parse(
@@ -735,8 +761,26 @@ async function scanAction(directory, options) {
         console.log(import_chalk3.default.bold("\nTool breakdown:"));
         scoringResult.breakdown.forEach((tool) => {
           const rating = (0, import_core3.getRating)(tool.score);
-          console.log(`  - ${tool.toolName}: ${tool.score}/100 (${rating})`);
+          const emoji = (0, import_core3.getRatingDisplay)(rating).emoji;
+          console.log(
+            `  - ${tool.toolName}: ${tool.score}/100 (${rating}) ${emoji}`
+          );
         });
+        const allRecs = scoringResult.breakdown.flatMap(
+          (t) => (t.recommendations || []).map((r) => ({ ...r, tool: t.toolName }))
+        ).sort((a, b) => b.estimatedImpact - a.estimatedImpact).slice(0, 3);
+        if (allRecs.length > 0) {
+          console.log(import_chalk3.default.bold("\n\u{1F3AF} Top Actionable Recommendations:"));
+          allRecs.forEach((rec, i) => {
+            const priorityIcon = rec.priority === "high" ? "\u{1F534}" : rec.priority === "medium" ? "\u{1F7E1}" : "\u{1F535}";
+            console.log(
+              `  ${i + 1}. ${priorityIcon} ${import_chalk3.default.bold(rec.action)}`
+            );
+            console.log(
+              `     Impact: ${import_chalk3.default.green(`+${rec.estimatedImpact} points`)} to ${rec.tool}`
+            );
+          });
+        }
       }
     }
     const mapToUnifiedReport = (res, scoring) => {
@@ -1869,11 +1913,11 @@ program.command("scan").description(
   "Tools to run (comma-separated: patterns,context,consistency,doc-drift,deps-health,aiSignalClarity,grounding,testability,changeAmplification)"
 ).option(
   "--profile <type>",
-  "Scan profile to use (agentic, cost, security, onboarding)"
+  "Scan profile to use (agentic, cost, logic, ui, security, onboarding)"
 ).option(
   "--compare-to <path>",
   "Compare results against a previous AIReady report JSON"
-).option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option(
+).option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score (0-100)").option(
   "--no-score",
   "Disable calculating AI Readiness Score (enabled by default)"
 ).option("--weights <weights>", "Custom scoring weights").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").option(

package/dist/cli.mjs

@@ -23,6 +23,7 @@ import {
   formatScore,
   calculateTokenBudget,
   getRating,
+  getRatingDisplay,
   getRepoMetadata,
   Severity,
   ToolName,
@@ -289,6 +290,24 @@ async function scanAction(directory, options) {
         case "cost":
           profileTools = [ToolName.PatternDetect, ToolName.ContextAnalyzer];
           break;
+        case "logic":
+          profileTools = [
+            ToolName.TestabilityIndex,
+            ToolName.NamingConsistency,
+            ToolName.ContextAnalyzer,
+            ToolName.PatternDetect,
+            ToolName.ChangeAmplification
+          ];
+          break;
+        case "ui":
+          profileTools = [
+            ToolName.NamingConsistency,
+            ToolName.ContextAnalyzer,
+            ToolName.PatternDetect,
+            ToolName.DocDrift,
+            ToolName.AiSignalClarity
+          ];
+          break;
         case "security":
           profileTools = [
             ToolName.NamingConsistency,
@@ -358,6 +377,7 @@ async function scanAction(directory, options) {
           );
       }
     };
+    const scoringProfile = options.profile || baseOptions.scoring?.profile || "default";
     const results = await analyzeUnified({
       ...finalOptions,
       progressCallback,
@@ -374,9 +394,16 @@ async function scanAction(directory, options) {
     );
     let scoringResult;
     if (options.score || finalOptions.scoring?.showBreakdown) {
-      scoringResult = await scoreUnified(results, finalOptions);
+      scoringResult = await scoreUnified(results, {
+        ...finalOptions,
+        scoring: {
+          ...finalOptions.scoring,
+          profile: scoringProfile
+        }
+      });
       console.log(chalk3.bold("\n\u{1F4CA} AI Readiness Overall Score"));
       console.log(`  ${formatScore(scoringResult)}`);
+      console.log(chalk3.dim(`  (Scoring Profile: ${scoringProfile})`));
       if (options.compareTo) {
         try {
           const prevReport = JSON.parse(
@@ -474,8 +501,26 @@ async function scanAction(directory, options) {
         console.log(chalk3.bold("\nTool breakdown:"));
         scoringResult.breakdown.forEach((tool) => {
           const rating = getRating(tool.score);
-          console.log(`  - ${tool.toolName}: ${tool.score}/100 (${rating})`);
+          const emoji = getRatingDisplay(rating).emoji;
+          console.log(
+            `  - ${tool.toolName}: ${tool.score}/100 (${rating}) ${emoji}`
+          );
         });
+        const allRecs = scoringResult.breakdown.flatMap(
+          (t) => (t.recommendations || []).map((r) => ({ ...r, tool: t.toolName }))
+        ).sort((a, b) => b.estimatedImpact - a.estimatedImpact).slice(0, 3);
+        if (allRecs.length > 0) {
+          console.log(chalk3.bold("\n\u{1F3AF} Top Actionable Recommendations:"));
+          allRecs.forEach((rec, i) => {
+            const priorityIcon = rec.priority === "high" ? "\u{1F534}" : rec.priority === "medium" ? "\u{1F7E1}" : "\u{1F535}";
+            console.log(
+              `  ${i + 1}. ${priorityIcon} ${chalk3.bold(rec.action)}`
+            );
+            console.log(
+              `     Impact: ${chalk3.green(`+${rec.estimatedImpact} points`)} to ${rec.tool}`
+            );
+          });
+        }
       }
     }
     const mapToUnifiedReport = (res, scoring) => {
@@ -1630,11 +1675,11 @@ program.command("scan").description(
   "Tools to run (comma-separated: patterns,context,consistency,doc-drift,deps-health,aiSignalClarity,grounding,testability,changeAmplification)"
 ).option(
   "--profile <type>",
-  "Scan profile to use (agentic, cost, security, onboarding)"
+  "Scan profile to use (agentic, cost, logic, ui, security, onboarding)"
 ).option(
   "--compare-to <path>",
   "Compare results against a previous AIReady report JSON"
-).option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option(
+).option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score (0-100)").option(
   "--no-score",
   "Disable calculating AI Readiness Score (enabled by default)"
 ).option("--weights <weights>", "Custom scoring weights").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").option(

package/docs/SPOKE_GUIDE.md

@@ -0,0 +1,184 @@
+# Building a New AIReady Spoke
+
+This guide explains how to build a new analysis tool ("spoke") and integrate it into the AIReady ecosystem. AIReady uses a hub-and-spoke architecture where independent tools are coordinated by a central CLI and Hub (@aiready/core).
+
+## 🚀 Getting Started
+
+### 1. Create Package Structure
+
+If you are contributing to the monorepo:
+
+```bash
+mkdir -p packages/your-tool/src
+cd packages/your-tool
+```
+
+### 2. Create `package.json`
+
+Your tool should depend on `@aiready/core` for shared types and utilities.
+
+```json
+{
+  "name": "@aiready/your-tool",
+  "version": "0.1.0",
+  "description": "Brief description of what this tool does",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aiready-yourtool": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@aiready/core": "workspace:*",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5"
+  },
+  "keywords": ["aiready", "your-keywords"],
+  "license": "MIT"
+}
+```
+
+### 3. Implement the Analysis Logic
+
+Create `src/analyzer.ts` to contain your core logic.
+
+```typescript
+import { scanFiles, readFileContent } from '@aiready/core';
+import type {
+  AnalysisResult,
+  Issue,
+  ScanOptions,
+  SpokeOutput,
+} from '@aiready/core';
+
+export async function analyzeYourTool(
+  options: ScanOptions
+): Promise<SpokeOutput> {
+  const files = await scanFiles(options);
+  const results: AnalysisResult[] = [];
+
+  // Your analysis logic here
+  // 1. Iterate through files
+  // 2. Detect issues
+  // 3. Return standardized AnalysisResult[]
+
+  return {
+    results,
+    summary: {
+      totalFiles: files.length,
+      totalIssues: results.reduce((acc, r) => acc + r.issues.length, 0),
+      // ... other summary stats
+    },
+  };
+}
+```
+
+### 4. Implement ToolProvider and Register
+
+Every spoke must implement the `ToolProvider` interface and register with the global `ToolRegistry` so that it is automatically discovered by the unified CLI.
+
+1.  **Create `src/provider.ts`**:
+
+    ```typescript
+    import {
+      ToolProvider,
+      ToolName,
+      SpokeOutput,
+      ScanOptions,
+      ToolScoringOutput,
+    } from '@aiready/core';
+    import { analyzeYourTool } from './analyzer';
+
+    export const YourToolProvider: ToolProvider = {
+      id: ToolName.YourToolID, // Use an existing ToolName or request a new one
+      alias: ['your-alias'],
+
+      async analyze(options: ScanOptions): Promise<SpokeOutput> {
+        const output = await analyzeYourTool(options);
+        return {
+          ...output,
+          metadata: { toolName: ToolName.YourToolID, version: '0.1.0' },
+        };
+      },
+
+      score(output: SpokeOutput, options: ScanOptions): ToolScoringOutput {
+        // Implement scoring logic (0-100)
+        return {
+          score: 100, // Example
+          metrics: output.summary,
+        };
+      },
+
+      defaultWeight: 10,
+    };
+    ```
+
+2.  **Register in `src/index.ts`**:
+
+    ```typescript
+    import { ToolRegistry } from '@aiready/core';
+    import { YourToolProvider } from './provider';
+
+    // Register with global registry for automatic CLI discovery
+    ToolRegistry.register(YourToolProvider);
+
+    export { YourToolProvider };
+    export * from './analyzer';
+    ```
+
+### 5. Create Standalone CLI (`src/cli.ts`)
+
+```typescript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { analyzeYourTool } from './analyzer';
+import chalk from 'chalk';
+
+const program = new Command();
+
+program
+  .name('aiready-yourtool')
+  .description('Description of your tool')
+  .version('0.1.0')
+  .argument('<directory>', 'Directory to analyze')
+  .action(async (directory, options) => {
+    console.log(chalk.blue('🔍 Analyzing...\n'));
+    const output = await analyzeYourTool({ rootDir: directory });
+    console.log(JSON.stringify(output, null, 2));
+  });
+
+program.parse();
+```
+
+## 📋 Standard Specs to Follow
+
+To ensure your tool integrates perfectly with the AIReady ecosystem, it must follow these rules:
+
+1.  **Standard Options**: Support `--include`, `--exclude`, and `--output` (standardized via `ScanOptions`).
+2.  **No Direct Dependencies**: Spokes should never depend on other spokes. Only depend on `@aiready/core`.
+3.  **Standard Issue Types**: Use `IssueType` from `@aiready/core` whenever possible.
+4.  **Severity Levels**: Use `critical`, `major`, `minor`, and `info`.
+5.  **Non-Blocking**: The `analyze` function should be asynchronous and handle large codebases efficiently.
+
+## 🧪 Testing
+
+Use `vitest` for unit and integration tests. Ensure you test your `ToolProvider` implementation using the `validateSpokeOutput` utility from `@aiready/core`.
+
+```typescript
+import { validateSpokeOutput } from '@aiready/core/types/contract';
+
+test('output matches AIReady contract', async () => {
+  const output = await analyzeYourTool({ rootDir: './test' });
+  const validation = validateSpokeOutput('your-tool', output);
+  expect(validation.valid).toBe(true);
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/cli",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Unified CLI for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,18 +11,18 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
+    "@aiready/consistency": "0.19.0",
     "@aiready/clawmart": "0.1.2",
     "@aiready/context-analyzer": "0.20.0",
     "@aiready/agent-grounding": "0.12.0",
-    "@aiready/consistency": "0.19.0",
-    "@aiready/core": "0.22.0",
-    "@aiready/deps": "0.12.0",
+    "@aiready/core": "0.22.1",
     "@aiready/doc-drift": "0.12.0",
     "@aiready/change-amplification": "0.12.0",
+    "@aiready/deps": "0.12.0",
     "@aiready/ai-signal-clarity": "0.12.0",
-    "@aiready/pattern-detect": "0.15.0",
     "@aiready/visualizer": "0.5.0",
-    "@aiready/testability": "0.5.0"
+    "@aiready/testability": "0.5.0",
+    "@aiready/pattern-detect": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",