@fmatar/archlens-skill 0.1.0-Beta-10 → 1.1.0-dev.58

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,7 +12,17 @@ Analyzes any project repository, detects programming languages and package hiera
12
12
 
13
13
  ## ⚡ Quickstart
14
14
 
15
- ### Option A: Install AI Assistant Skills via Open Skills Standard (Recommended for Agents)
15
+ ### Option A: Zero-Touch Autonomous AI Setup (`--mcp` — Recommended for Antigravity & Claude)
16
+ Equip **Google Antigravity**, **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, and **Gemini CLI** in one command. Once configured, your AI assistant **automatically starts or resurrects Archlens on demand** whenever an architectural MCP tool is invoked—no manual container management required:
17
+ ```bash
18
+ # Scaffold .archlens/policy.json, AGENTS.md/CLAUDE.md, and auto-configure all installed AI clients:
19
+ npx @fmatar/archlens-skill --yes --mcp
20
+
21
+ # Or also install global skills into ~/.claude/skills and ~/.gemini/config/skills:
22
+ npx @fmatar/archlens-skill --global --mcp
23
+ ```
24
+
25
+ ### Option B: Install AI Assistant Skills via Open Skills Standard
16
26
  Using the open [Vercel Labs Skills](https://github.com/vercel-labs/skills) standard, you can add Archlens capabilities across 15+ AI coding assistants (Claude Code, Cursor, Antigravity, Copilot, Codex, Windsurf, Zed):
17
27
  ```bash
18
28
  # Add to all detected AI assistants in project or globally:
@@ -22,7 +32,7 @@ npx skills add fmatar/archlens
22
32
  npx skills add fmatar/archlens --agent claude-code
23
33
  ```
24
34
 
25
- ### Option B: Run Policy Scaffolder via NPX
35
+ ### Option C: Run Interactive Policy Scaffolder via NPX
26
36
 
27
37
  ```bash
28
38
  # Production Stable (recommended)
@@ -35,13 +45,13 @@ npx @fmatar/archlens-skill@dev
35
45
  npx github:fmatar/archlens
36
46
  ```
37
47
 
38
- ### Option C: Install Globally via NPM
48
+ ### Option D: Install Globally via NPM
39
49
  ```bash
40
50
  npm install -g @fmatar/archlens-skill
41
51
  archlens-skill
42
52
  ```
43
53
 
44
- ### Option D: Run from Local Repository Clone
54
+ ### Option E: Run from Local Repository Clone
45
55
  ```bash
46
56
  # Install globally from the local repository:
47
57
  npm install -g ./cli
@@ -148,20 +158,33 @@ npx @fmatar/archlens-skill start --path /path/to/project --port 8088 --open
148
158
 
149
159
  ### Command-Line Options
150
160
 
151
- | Flag | Shorthand | Description | Default |
161
+ | Flag / Command | Shorthand | Description | Default |
152
162
  |------|-----------|-------------|---------|
153
- | `start` | | Start Archlens Workbench container (auto-resurrects on demand) | |
163
+ | `check` | `--check` | Run headless Clean Architecture CI quality gate | |
164
+ | `start` | | Start Archlens Workbench (Native Binary / JAR / Docker fallback) | |
165
+ | `prompt` | `--prompt` | Export LLM Refactoring Prompt Dossier | |
166
+ | `mcp` | | Run MCP stdio server bridge (online + offline static fallback) | |
167
+ | `update` | `--update`, `-u` | Re-scan code and update existing `.archlens/policy.json` | `false` |
168
+ | `upgrade` | `--upgrade` | Migrate legacy `.uml-viewer` to `.archlens` | `false` |
169
+ | `global` | `--global`, `-g` | Install skills into global agent directories | `false` |
170
+ | `--max-violations <N>` | | Maximum allowed outward layer violations in `check` | `0` |
171
+ | `--detect-cycles` | | Fail `check` if package dependency cycles (ADP) are detected | `false` |
172
+ | `--screaming-threshold <N>` | | Minimum Screaming Architecture Score (`0.0`–`1.0`) | |
173
+ | `--suggest-features` | | Suggest Screaming Architecture feature slice clusters in `check` | `false` |
174
+ | `--fitness-threshold <N>` | | Minimum Composite Architecture Fitness Index (`0.0`–`1.0`) | |
175
+ | `--format <FMT>` | | Output format for `check` (`text`, `json`, `sarif`) | `text` |
176
+ | `--output <FILE>` | `-O` | Write `check` output report (e.g. SARIF) to file | |
177
+ | `--native` | | Force native JVM runner mode on `start` | `false` |
178
+ | `--docker` | | Force Docker container mode on `start` | `false` |
179
+ | `--jar <PATH>` | | Custom path to `quarkus-run.jar` for native mode | Auto-detected |
154
180
  | `--open` | `-o` | Open visual workbench in default browser upon startup | `false` |
155
181
  | `--port <PORT>` | | Workbench HTTP port | `8088` |
156
182
  | `--path <DIR>` | `-p` | Target repository directory | `.` (current directory) |
157
183
  | `--title <NAME>` | `-t` | Project title in visual workbench | Formatted folder name |
158
184
  | `--prefix <PKG>` | | Common package prefix (e.g. `com.example.service`) | Auto-detected |
159
185
  | `--server-url <URL>` | | Visual Workbench server endpoint | `http://localhost:8088` |
160
- | `--mcp` | `-m` | Auto-configure MCP client manifests (Claude, Antigravity, Cursor) | `false` |
186
+ | `--mcp` | `-m` | Auto-configure MCP client manifests (Claude, Antigravity, Cursor, Gemini, Grok, Windsurf, VS Code) | `false` |
161
187
  | `--copy` | `-c` | Copy LLM prompt output directly to system clipboard | `false` |
162
- | `--global` | `-g` | Install skill into global agent directories | `false` |
163
- | `--update` | `-u` | Re-scan code and update existing policy | `false` |
164
- | `--upgrade` | | Migrate legacy `.uml-viewer` to `.archlens` | `false` |
165
188
  | `--force` | `-f` | Overwrite existing configuration files | `false` |
166
189
  | `--dry-run` | | Simulate execution without writing files | `false` |
167
190
  | `--yes` | `-y` | Accept defaults automatically (non-interactive) | `false` |
package/bin/index.js CHANGED
@@ -20,7 +20,12 @@ import {
20
20
  import { installLocalPolicy, installGlobalSkills } from '../src/installer.js';
21
21
  import { updateLocalPolicy, updateGlobalSkills } from '../src/updater.js';
22
22
  import { upgradeProject } from '../src/upgrader.js';
23
- import { checkArchitecture, generateSarifReport, generateJsonReport } from '../src/checker.js';
23
+ import {
24
+ checkArchitecture,
25
+ generateSarifReport,
26
+ generateJsonReport,
27
+ generateMermaidReport
28
+ } from '../src/checker.js';
24
29
  import { installMcpConfigs } from '../src/mcp-registry.js';
25
30
  import { startMcpStdioServer } from '../src/mcp-server.js';
26
31
  import { executeStart, DEFAULT_CONTAINER_NAME, DEFAULT_SERVER_URL } from '../src/docker-runner.js';
@@ -506,6 +511,8 @@ async function main() {
506
511
  formattedOutput = generateSarifReport(report, { version: getPackageVersion() });
507
512
  } else if (options.format === 'json') {
508
513
  formattedOutput = generateJsonReport(report);
514
+ } else if (options.format === 'mermaid' || options.format === 'mmd') {
515
+ formattedOutput = generateMermaidReport(report, options);
509
516
  }
510
517
 
511
518
  if (options.output) {
@@ -520,7 +527,12 @@ async function main() {
520
527
  }
521
528
  }
522
529
 
523
- if (options.format === 'sarif' || options.format === 'json') {
530
+ if (
531
+ options.format === 'sarif' ||
532
+ options.format === 'json' ||
533
+ options.format === 'mermaid' ||
534
+ options.format === 'mmd'
535
+ ) {
524
536
  if (!options.output) {
525
537
  process.stdout.write(formattedOutput + '\n');
526
538
  }
package/llms.txt CHANGED
@@ -63,7 +63,7 @@ Archlens CLI requires zero external dependencies and runs cross-platform via Nod
63
63
  ```bash
64
64
  # 1. Audit Codebase Conformance & Detect All Architectural Drifts:
65
65
  npx @fmatar/archlens-skill check
66
- npx @fmatar/archlens-skill check --detect-cycles --screaming-threshold 0.70 --fitness-threshold 0.85
66
+ npx @fmatar/archlens-skill check --detect-cycles --screaming-threshold 0.70 --suggest-features --fitness-threshold 0.85
67
67
  npx @fmatar/archlens-skill check --format json
68
68
  npx @fmatar/archlens-skill check --format sarif -O arch-drift.sarif
69
69
 
@@ -89,18 +89,32 @@ npx @fmatar/archlens-skill mcp # Launch MCP stdio bridge server
89
89
 
90
90
  When Archlens is registered as an MCP server, AI assistants can query it using standard MCP primitives:
91
91
 
92
- ### MCP Tools:
92
+ ### MCP Tools (10):
93
93
  | Tool Name | Parameters | Purpose |
94
94
  | :--- | :--- | :--- |
95
95
  | `exportLlmDossier` | `projectRoot` (default: `.`), `proposalId` | Diagnoses outward dependency breaches and outputs a Markdown refactoring prompt with concrete DIP interface port prescriptions. |
96
96
  | `inspectArchitecture` | `projectRoot` (default: `.`) | Returns full JSON graph model: concentric rings, dependency edges, cycle paths, and screaming metrics. |
97
+ | `synthesizeDipInversion` | `fromClass` (required), `toClass` (required), `projectRoot` | Synthesizes a complete Dependency Inversion Principle (DIP) interface port (`Java`, `Python`, `TypeScript`, `Go`, `Rust`), adapter/caller diffs, and surgical prompt. |
98
+ | `evaluateFitness` | `projectRoot` (default: `.`) | Evaluates the Composite Architecture Fitness Index (AFI score `0`–`100`, grade `A`–`F`, rule breakdowns). |
99
+ | `getFitnessHistory` | `projectRoot` (default: `.`) | Returns historical fitness snapshots across Git release tags and computes the regression trend (`STABLE`, `IMPROVING`, `DEGRADING`). |
100
+ | `proposeScreamingMigration` | `projectRoot` (default: `.`) | Generates a Screaming Architecture package-by-feature migration plan from technical layers into domain feature slices. |
101
+ | `getPolicy` | `projectRoot` (default: `.`) | Returns the active `.archlens/policy.json` concentric ring definitions and omission rules. |
102
+ | `syncDipAdr` | `fromClass`, `toClass`, `portName`, `portPackage`, `reason`, `projectRoot` | Mints a numbered Markdown ADR in `docs/adr/` documenting a Dependency Inversion Principle refactoring. |
97
103
  | `listSnapshots` | `projectRoot` (default: `.`) | Lists historical architecture release snapshots in `.archlens/snapshots/` and Git release tags. |
98
104
  | `getSnapshot` | `snapshotId` (required), `projectRoot` | Retrieves the graph model of a specific historical snapshot or Git tag for temporal drift diffing. |
99
105
 
100
- ### MCP Resources:
106
+ ### MCP Resources (3):
101
107
  | Resource URI | MIME Type | Description |
102
108
  | :--- | :--- | :--- |
103
109
  | `archlens://llms.txt` | `text/markdown` | This authoritative reference guide, Clean Architecture rules, CLI recipes, and refactoring protocols. |
110
+ | `archlens://policy` | `application/json` | The active `.archlens/policy.json` concentric Clean Architecture layer policy for the workspace. |
111
+ | `archlens://fitness` | `application/json` | Live Architecture Fitness Index (AFI) evaluation report, grade, and rule breakdown. |
112
+
113
+ ### MCP Prompts (2):
114
+ | Prompt Name | Arguments | Description |
115
+ | :--- | :--- | :--- |
116
+ | `architectural-review` | `projectRoot` (optional) | Comprehensive Clean Architecture review prompt combining the LLM Dossier and Fitness evaluation. |
117
+ | `dip-refactoring-guide` | `fromClass` (required), `toClass` (required), `projectRoot` | Step-by-step Dependency Inversion Principle (DIP) refactoring prompt for a specific outward violation. |
104
118
 
105
119
  ---
106
120
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fmatar/archlens-skill",
3
- "version": "0.1.0-Beta-10",
3
+ "version": "1.1.0-dev.58",
4
4
  "description": "Cross-platform CLI and installer for Archlens Clean Architecture governance policies and AI assistant skills",
5
5
  "main": "src/installer.js",
6
6
  "type": "module",
@@ -17,7 +17,7 @@ This skill equips agents (Antigravity, Gemini CLI, Claude Code) to:
17
17
  2. Scaffold and maintain `.archlens/policy.json` architectural layer policies.
18
18
  3. Act as the autonomous refactoring companion to the visual workbench via mailbox queues (`.archlens/to-agent.json` and `.archlens/to-viewer.json`).
19
19
  4. Export LLM Refactoring Prompt Dossiers prescribing concrete Dependency Inversion Principle (DIP) interface ports.
20
- 5. Invoke Archlens MCP tools (`inspectArchitecture`, `exportLlmDossier`, `listSnapshots`, `getSnapshot`).
20
+ 5. Invoke Archlens MCP tools (`inspectArchitecture`, `exportLlmDossier`, `synthesizeDipInversion`, `evaluateFitness`, `getFitnessHistory`, `proposeScreamingMigration`, `getPolicy`, `syncDipAdr`, `listSnapshots`, `getSnapshot`), resources (`archlens://llms.txt`, `archlens://policy`, `archlens://fitness`), and prompts (`architectural-review`, `dip-refactoring-guide`).
21
21
 
22
22
  ---
23
23
 
@@ -65,6 +65,9 @@ npx @fmatar/archlens-skill --path . --yes
65
65
  # Launch Workbench container (auto-resurrects on demand if stopped or killed):
66
66
  npx @fmatar/archlens-skill start --open
67
67
 
68
+ # Execute Headless Clean Architecture CI Quality Gate (ADP cycles, Screaming score, Fitness index, SARIF):
69
+ npx @fmatar/archlens-skill check --path . --max-violations 0 --detect-cycles --screaming-threshold 0.70 --suggest-features --fitness-threshold 0.85 --format sarif -O archlens-results.sarif
70
+
68
71
  # Export Clean Architecture LLM Refactoring Prompt Dossier:
69
72
  npx @fmatar/archlens-skill prompt --path .
70
73
 
@@ -144,5 +147,15 @@ When Archlens is registered as an MCP server, use the following tools:
144
147
  | :--- | :--- | :--- |
145
148
  | `inspectArchitecture` | Inspect concentric rings, outward violations, and instability metrics | `projectRoot` (default: `.`) |
146
149
  | `exportLlmDossier` | Generate copy-ready LLM refactoring prompt with DIP prescriptions | `projectRoot`, `proposalId` |
150
+ | `synthesizeDipInversion` | Synthesize polyglot DIP interface port, adapter/caller diffs, and surgical prompt | `fromClass`, `toClass`, `projectRoot` |
151
+ | `evaluateFitness` | Compute Composite Architecture Fitness Index (AFI score, grade, rule breakdown) | `projectRoot` |
152
+ | `getFitnessHistory` | Retrieve historical fitness snapshots across Git tags and regression trend | `projectRoot` |
153
+ | `proposeScreamingMigration` | Propose Screaming Architecture package-by-feature migration clusters | `projectRoot` |
154
+ | `getPolicy` | Inspect active `.archlens/policy.json` concentric ring definitions | `projectRoot` |
155
+ | `syncDipAdr` | Mint a numbered Markdown ADR in `docs/adr/` for a DIP refactoring | `fromClass`, `toClass`, `portName`, `portPackage`, `reason`, `projectRoot` |
147
156
  | `listSnapshots` | List historical Git release tags and pre-compiled architecture snapshots | `projectRoot` |
148
157
  | `getSnapshot` | Retrieve graph model for a historical release or snapshot tag | `snapshotId`, `projectRoot` |
158
+
159
+ ### MCP Resources & Prompts
160
+ - **Resources**: `archlens://llms.txt`, `archlens://policy`, `archlens://fitness`
161
+ - **Prompts**: `architectural-review` (`projectRoot`), `dip-refactoring-guide` (`fromClass`, `toClass`, `projectRoot`)
package/src/analyzer.js CHANGED
@@ -121,6 +121,123 @@ function findNestedSourceRoots(dir, lang, depth = 0, maxDepth = 5, results = [])
121
121
  return results;
122
122
  }
123
123
 
124
+ export function discoverWorkspaceModules(projectRoot) {
125
+ const root = path.resolve(projectRoot);
126
+ const discovered = new Set();
127
+
128
+ const expandGlobPattern = (pattern) => {
129
+ let clean = pattern.trim().replace(/^['"]|['"]$/g, '').replace(/\\/g, '/');
130
+ if (!clean || clean.startsWith('!')) return;
131
+ if (clean.startsWith(':')) {
132
+ clean = clean.slice(1).replace(/:/g, '/');
133
+ }
134
+ while (clean.endsWith('/')) {
135
+ clean = clean.slice(0, -1);
136
+ }
137
+ if (!clean) return;
138
+
139
+ if (clean.endsWith('/*') || clean.endsWith('/**')) {
140
+ const parentRel = clean.replace(/\/\*\*?$/, '');
141
+ const parentDir = path.join(root, parentRel);
142
+ if (fs.existsSync(parentDir) && fs.statSync(parentDir).isDirectory()) {
143
+ try {
144
+ for (const entry of fs.readdirSync(parentDir, { withFileTypes: true })) {
145
+ if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
146
+ discovered.add(path.posix.join(parentRel, entry.name));
147
+ }
148
+ }
149
+ } catch {
150
+ // Ignore unreadable parent
151
+ }
152
+ }
153
+ } else {
154
+ const candidate = path.join(root, clean);
155
+ if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
156
+ discovered.add(clean);
157
+ }
158
+ }
159
+ };
160
+
161
+ // 1. Gradle settings.gradle / settings.gradle.kts
162
+ for (const gradleSettings of ['settings.gradle', 'settings.gradle.kts']) {
163
+ const settingsPath = path.join(root, gradleSettings);
164
+ if (fs.existsSync(settingsPath)) {
165
+ try {
166
+ const content = fs.readFileSync(settingsPath, 'utf8');
167
+ const includeRegex = /\binclude\s*\(?([^)\n]+)\)?/g;
168
+ let match;
169
+ while ((match = includeRegex.exec(content)) !== null) {
170
+ const strRegex = /['"]([^'"]+)['"]/g;
171
+ let strMatch;
172
+ while ((strMatch = strRegex.exec(match[1])) !== null) {
173
+ expandGlobPattern(strMatch[1]);
174
+ }
175
+ }
176
+ } catch {
177
+ // Ignore malformed Gradle settings
178
+ }
179
+ }
180
+ }
181
+
182
+ // 2. Cargo.toml [workspace] members
183
+ const cargoPath = path.join(root, 'Cargo.toml');
184
+ if (fs.existsSync(cargoPath)) {
185
+ try {
186
+ const content = fs.readFileSync(cargoPath, 'utf8');
187
+ if (/\[workspace\]/.test(content)) {
188
+ const membersMatch = content.match(/\bmembers\s*=\s*\[([\s\S]*?)\]/);
189
+ if (membersMatch) {
190
+ const strRegex = /['"]([^'"]+)['"]/g;
191
+ let strMatch;
192
+ while ((strMatch = strRegex.exec(membersMatch[1])) !== null) {
193
+ expandGlobPattern(strMatch[1]);
194
+ }
195
+ }
196
+ }
197
+ } catch {
198
+ // Ignore malformed Cargo.toml
199
+ }
200
+ }
201
+
202
+ // 3. pnpm-workspace.yaml
203
+ const pnpmPath = path.join(root, 'pnpm-workspace.yaml');
204
+ if (fs.existsSync(pnpmPath)) {
205
+ try {
206
+ const content = fs.readFileSync(pnpmPath, 'utf8');
207
+ for (const line of content.split(/\r?\n/)) {
208
+ const itemMatch = line.match(/^\s*-\s*['"]?([^'"#]+)['"]?/);
209
+ if (itemMatch) {
210
+ expandGlobPattern(itemMatch[1]);
211
+ }
212
+ }
213
+ } catch {
214
+ // Ignore malformed pnpm-workspace.yaml
215
+ }
216
+ }
217
+
218
+ // 4. package.json workspaces (npm / Yarn / Nx / Turborepo)
219
+ const pkgJsonPath = path.join(root, 'package.json');
220
+ if (fs.existsSync(pkgJsonPath)) {
221
+ try {
222
+ const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
223
+ const workspaces = Array.isArray(pkg.workspaces)
224
+ ? pkg.workspaces
225
+ : Array.isArray(pkg.workspaces?.packages)
226
+ ? pkg.workspaces.packages
227
+ : [];
228
+ for (const pattern of workspaces) {
229
+ if (typeof pattern === 'string') {
230
+ expandGlobPattern(pattern);
231
+ }
232
+ }
233
+ } catch {
234
+ // Ignore malformed package.json
235
+ }
236
+ }
237
+
238
+ return Array.from(discovered);
239
+ }
240
+
124
241
  export function detectSourceRoot(projectRoot, lang) {
125
242
  const root = path.resolve(projectRoot);
126
243
 
@@ -145,6 +262,24 @@ export function detectSourceRoot(projectRoot, lang) {
145
262
  }
146
263
  }
147
264
 
265
+ // Check multi-build workspace manifests (Gradle, Cargo, pnpm, npm/Nx/Turborepo)
266
+ const workspaceMods = discoverWorkspaceModules(root);
267
+ for (const modRel of workspaceMods) {
268
+ if (lang === 'java') {
269
+ const javaSrc = path.posix.join(modRel, 'src/main/java');
270
+ if (fs.existsSync(path.join(root, javaSrc))) return javaSrc;
271
+ } else if (lang === 'kotlin') {
272
+ const ktSrc = path.posix.join(modRel, 'src/main/kotlin');
273
+ if (fs.existsSync(path.join(root, ktSrc))) return ktSrc;
274
+ const javaSrc = path.posix.join(modRel, 'src/main/java');
275
+ if (fs.existsSync(path.join(root, javaSrc))) return javaSrc;
276
+ } else {
277
+ const modSrc = path.posix.join(modRel, 'src');
278
+ if (fs.existsSync(path.join(root, modSrc))) return modSrc;
279
+ if (fs.existsSync(path.join(root, modRel))) return modRel;
280
+ }
281
+ }
282
+
148
283
  // Multi-module dynamic discovery if standard candidates are not found
149
284
  const nested = findNestedSourceRoots(root, lang);
150
285
  if (nested.length > 0) {