@aiready/cli 0.13.0 → 0.13.1

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.1 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:38:32 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
+CJS dist/index.js 10.62 KB
+CJS ⚡️ Build success in 77ms
 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 ⚡️ Build success in 77ms

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/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.1",
   "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/clawmart": "0.1.2",
-    "@aiready/context-analyzer": "0.20.0",
     "@aiready/agent-grounding": "0.12.0",
-    "@aiready/consistency": "0.19.0",
+    "@aiready/context-analyzer": "0.20.0",
     "@aiready/core": "0.22.0",
     "@aiready/deps": "0.12.0",
+    "@aiready/consistency": "0.19.0",
+    "@aiready/clawmart": "0.1.2",
     "@aiready/doc-drift": "0.12.0",
     "@aiready/change-amplification": "0.12.0",
-    "@aiready/ai-signal-clarity": "0.12.0",
+    "@aiready/testability": "0.5.0",
     "@aiready/pattern-detect": "0.15.0",
-    "@aiready/visualizer": "0.5.0",
-    "@aiready/testability": "0.5.0"
+    "@aiready/ai-signal-clarity": "0.12.0",
+    "@aiready/visualizer": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",