@fmatar/archlens-skill 0.0.1-Alpha-07 → 0.0.1-Alpha-09
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 +40 -0
- package/bin/index.js +161 -5
- package/package.json +1 -1
- package/skills/archlens/SKILL.md +139 -0
- package/skills/archlens-install-policy/SKILL.md +8 -0
- package/skills/uml-workbench-companion/SKILL.md +88 -0
- package/src/analyzer.js +169 -0
- package/src/docker-runner.js +215 -0
- package/src/installer.js +46 -18
- package/src/mcp-registry.js +268 -0
- package/src/mcp-server.js +272 -0
package/README.md
CHANGED
|
@@ -57,6 +57,8 @@ node ./cli/bin/index.js
|
|
|
57
57
|
- **Multi-Agent Skill Deployment**: Installs the `archlens-install-policy` skill globally into Claude Code (`~/.claude/skills/`), Gemini CLI / Antigravity (`~/.gemini/config/skills/`), and custom agent workspaces.
|
|
58
58
|
- **Safe Incremental Updates**: Re-scans codebases for newly introduced packages, updating `order` and `levels` while preserving user custom rules and configurations.
|
|
59
59
|
- **Seamless Upgrade Migration**: Automatically migrates legacy `.uml-viewer/` folders and companion files to modern `.archlens/` via `archlens-skill upgrade`.
|
|
60
|
+
- **Model Context Protocol (MCP) Client Auto-Configuration**: Detects and configures host AI client manifests (Claude Desktop, Google Antigravity, Claude Code, Cursor, VS Code) in a single command (`--mcp`).
|
|
61
|
+
- **On-Demand Container Orchestration & Stdio Bridge**: Automatically spins up the Archlens container when needed, bridges MCP over stdio (`mcp` command), and provides an instant offline AST fallback if Docker is unavailable.
|
|
60
62
|
- **Mailbox Protocol Integration**: Injects the Clean Architecture Companion Protocol into `CLAUDE.md` and `AGENTS.md` for seamless asynchronous mailbox refactoring (`to-agent.json`, `to-viewer.json`).
|
|
61
63
|
|
|
62
64
|
---
|
|
@@ -100,16 +102,54 @@ Migrates older `.uml-viewer/` directories and companions to the standard `.archl
|
|
|
100
102
|
npx @fmatar/archlens-skill upgrade
|
|
101
103
|
```
|
|
102
104
|
|
|
105
|
+
#### 6. Export LLM Refactoring Prompt Dossier
|
|
106
|
+
Generates copy-ready architectural diagnostics and concrete Dependency Inversion Principle (DIP) instructions for Claude Code, Gemini, ChatGPT, or Antigravity:
|
|
107
|
+
```bash
|
|
108
|
+
# Print dossier to stdout
|
|
109
|
+
npx @fmatar/archlens-skill prompt
|
|
110
|
+
|
|
111
|
+
# Or copy directly to system clipboard
|
|
112
|
+
npx @fmatar/archlens-skill prompt --copy
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
#### 7. Model Context Protocol (MCP) Setup & Stdio Bridge
|
|
116
|
+
Configures detected AI client manifests or launches an interactive stdio bridge:
|
|
117
|
+
```bash
|
|
118
|
+
# Auto-configure Claude Desktop, Google Antigravity, Claude Code, Cursor, and VS Code
|
|
119
|
+
npx @fmatar/archlens-skill --mcp
|
|
120
|
+
|
|
121
|
+
# Launch MCP stdio transport bridge (spins up Docker container automatically when needed)
|
|
122
|
+
npx @fmatar/archlens-skill mcp
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
#### 8. Start Workbench Container & Auto-Resurrection
|
|
126
|
+
Starts the Archlens container, mounts the workspace, verifies readiness, and optionally opens your browser. **If the container is killed or stopped, running `start` (or calling an MCP tool) automatically starts it again:**
|
|
127
|
+
```bash
|
|
128
|
+
# Start container and automatically open workbench in browser:
|
|
129
|
+
npx @fmatar/archlens-skill start --open
|
|
130
|
+
|
|
131
|
+
# Start container in background on default port 8088:
|
|
132
|
+
npx @fmatar/archlens-skill start
|
|
133
|
+
|
|
134
|
+
# Specify a custom port or target workspace directory:
|
|
135
|
+
npx @fmatar/archlens-skill start --path /path/to/project --port 8088 --open
|
|
136
|
+
```
|
|
137
|
+
|
|
103
138
|
---
|
|
104
139
|
|
|
105
140
|
### Command-Line Options
|
|
106
141
|
|
|
107
142
|
| Flag | Shorthand | Description | Default |
|
|
108
143
|
|------|-----------|-------------|---------|
|
|
144
|
+
| `start` | | Start Archlens Workbench container (auto-resurrects on demand) | |
|
|
145
|
+
| `--open` | `-o` | Open visual workbench in default browser upon startup | `false` |
|
|
146
|
+
| `--port <PORT>` | | Workbench HTTP port | `8088` |
|
|
109
147
|
| `--path <DIR>` | `-p` | Target repository directory | `.` (current directory) |
|
|
110
148
|
| `--title <NAME>` | `-t` | Project title in visual workbench | Formatted folder name |
|
|
111
149
|
| `--prefix <PKG>` | | Common package prefix (e.g. `com.example.service`) | Auto-detected |
|
|
112
150
|
| `--server-url <URL>` | | Visual Workbench server endpoint | `http://localhost:8088` |
|
|
151
|
+
| `--mcp` | `-m` | Auto-configure MCP client manifests (Claude, Antigravity, Cursor) | `false` |
|
|
152
|
+
| `--copy` | `-c` | Copy LLM prompt output directly to system clipboard | `false` |
|
|
113
153
|
| `--global` | `-g` | Install skill into global agent directories | `false` |
|
|
114
154
|
| `--update` | `-u` | Re-scan code and update existing policy | `false` |
|
|
115
155
|
| `--upgrade` | | Migrate legacy `.uml-viewer` to `.archlens` | `false` |
|
package/bin/index.js
CHANGED
|
@@ -11,10 +11,19 @@ import * as fs from 'node:fs';
|
|
|
11
11
|
import { fileURLToPath } from 'node:url';
|
|
12
12
|
|
|
13
13
|
import * as ui from '../src/ui.js';
|
|
14
|
-
import {
|
|
14
|
+
import {
|
|
15
|
+
detectProjectLanguage,
|
|
16
|
+
detectSourceRoot,
|
|
17
|
+
findCommonPackagePrefix,
|
|
18
|
+
generateLlmPrompt
|
|
19
|
+
} from '../src/analyzer.js';
|
|
15
20
|
import { installLocalPolicy, installGlobalSkills } from '../src/installer.js';
|
|
16
21
|
import { updateLocalPolicy, updateGlobalSkills } from '../src/updater.js';
|
|
17
22
|
import { upgradeProject } from '../src/upgrader.js';
|
|
23
|
+
import { installMcpConfigs } from '../src/mcp-registry.js';
|
|
24
|
+
import { startMcpStdioServer } from '../src/mcp-server.js';
|
|
25
|
+
import { executeStart, DEFAULT_CONTAINER_NAME, DEFAULT_SERVER_URL } from '../src/docker-runner.js';
|
|
26
|
+
import { spawnSync } from 'node:child_process';
|
|
18
27
|
|
|
19
28
|
const __filename = fileURLToPath(import.meta.url);
|
|
20
29
|
const __dirname = path.dirname(__filename);
|
|
@@ -41,15 +50,22 @@ ${ui.colors.bold}USAGE:${ui.colors.reset}
|
|
|
41
50
|
|
|
42
51
|
${ui.colors.bold}COMMANDS:${ui.colors.reset}
|
|
43
52
|
init Initialize Clean Architecture policy in target project (default)
|
|
53
|
+
start Start Archlens Workbench container (auto-resurrects on demand)
|
|
44
54
|
update Update existing policy with newly discovered packages and refresh skills
|
|
45
55
|
upgrade Upgrade legacy .uml-viewer configuration to .archlens
|
|
46
56
|
global Install Archlens skills globally for AI coding assistants
|
|
57
|
+
prompt Export Clean Architecture LLM Refactoring Prompt Dossier
|
|
58
|
+
mcp Launch Model Context Protocol (MCP) stdio server for AI assistants
|
|
47
59
|
|
|
48
60
|
${ui.colors.bold}OPTIONS:${ui.colors.reset}
|
|
49
61
|
-p, --path <DIR> Target repository path (default: current directory)
|
|
50
62
|
-t, --title <NAME> Project title displayed in Archlens workbench
|
|
51
63
|
--prefix <PKG> Common package prefix (e.g. com.example.app)
|
|
52
64
|
--server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
|
|
65
|
+
--port <PORT> Workbench HTTP port (default: 8088)
|
|
66
|
+
-o, --open Open visual workbench in default browser upon startup
|
|
67
|
+
-m, --mcp Auto-configure MCP server manifests in AI clients (Claude, Antigravity, Cursor)
|
|
68
|
+
-c, --copy Copy LLM prompt output directly to system clipboard
|
|
53
69
|
-g, --global Install or update skill globally in ~/.claude and ~/.gemini
|
|
54
70
|
-u, --update Update mode: sync new packages into existing policy
|
|
55
71
|
--upgrade Upgrade mode: migrate .uml-viewer to .archlens
|
|
@@ -60,6 +76,20 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
|
|
|
60
76
|
-h, --help Display this help guide
|
|
61
77
|
|
|
62
78
|
${ui.colors.bold}EXAMPLES:${ui.colors.reset}
|
|
79
|
+
${ui.colors.dim}# Start Archlens workbench container and open in browser:${ui.colors.reset}
|
|
80
|
+
npx @fmatar/archlens-skill start --open
|
|
81
|
+
${ui.colors.dim}# Configure MCP manifests across Claude, Antigravity, and Cursor:${ui.colors.reset}
|
|
82
|
+
npx @fmatar/archlens-skill --mcp
|
|
83
|
+
|
|
84
|
+
${ui.colors.dim}# Launch MCP stdio bridge server for AI coding assistants:${ui.colors.reset}
|
|
85
|
+
npx @fmatar/archlens-skill mcp
|
|
86
|
+
|
|
87
|
+
${ui.colors.dim}# Export Clean Architecture LLM Refactoring Prompt to stdout:${ui.colors.reset}
|
|
88
|
+
npx @fmatar/archlens-skill prompt
|
|
89
|
+
|
|
90
|
+
${ui.colors.dim}# Copy prompt directly to system clipboard:${ui.colors.reset}
|
|
91
|
+
npx @fmatar/archlens-skill prompt --copy
|
|
92
|
+
|
|
63
93
|
${ui.colors.dim}# Interactive setup wizard:${ui.colors.reset}
|
|
64
94
|
npx @fmatar/archlens-skill
|
|
65
95
|
|
|
@@ -84,9 +114,15 @@ function parseArgs(args) {
|
|
|
84
114
|
title: null,
|
|
85
115
|
prefix: null,
|
|
86
116
|
serverUrl: 'http://localhost:8088',
|
|
117
|
+
port: '8088',
|
|
118
|
+
open: false,
|
|
119
|
+
start: false,
|
|
120
|
+
copy: false,
|
|
121
|
+
prompt: false,
|
|
87
122
|
global: false,
|
|
88
123
|
update: false,
|
|
89
124
|
upgrade: false,
|
|
125
|
+
mcp: false,
|
|
90
126
|
force: false,
|
|
91
127
|
dryRun: false,
|
|
92
128
|
yes: false,
|
|
@@ -103,12 +139,22 @@ function parseArgs(args) {
|
|
|
103
139
|
parsed.help = true;
|
|
104
140
|
} else if (arg === '--version' || arg === '-v') {
|
|
105
141
|
parsed.version = true;
|
|
142
|
+
} else if (arg === '--open' || arg === '-o') {
|
|
143
|
+
parsed.open = true;
|
|
144
|
+
} else if (arg === '--port') {
|
|
145
|
+
parsed.port = args[++i] || '8088';
|
|
146
|
+
} else if (arg === '--mcp' || arg === '-m') {
|
|
147
|
+
parsed.mcp = true;
|
|
106
148
|
} else if (arg === '--global' || arg === '-g') {
|
|
107
149
|
parsed.global = true;
|
|
108
150
|
} else if (arg === '--update' || arg === '-u') {
|
|
109
151
|
parsed.update = true;
|
|
110
152
|
} else if (arg === '--upgrade') {
|
|
111
153
|
parsed.upgrade = true;
|
|
154
|
+
} else if (arg === '--prompt') {
|
|
155
|
+
parsed.prompt = true;
|
|
156
|
+
} else if (arg === '--copy' || arg === '-c') {
|
|
157
|
+
parsed.copy = true;
|
|
112
158
|
} else if (arg === '--force' || arg === '-f') {
|
|
113
159
|
parsed.force = true;
|
|
114
160
|
} else if (arg === '--dry-run') {
|
|
@@ -130,7 +176,7 @@ function parseArgs(args) {
|
|
|
130
176
|
|
|
131
177
|
if (positional.length > 0) {
|
|
132
178
|
const cmd = positional[0].toLowerCase();
|
|
133
|
-
if (['init', 'update', 'upgrade', 'global', 'help', 'version'].includes(cmd)) {
|
|
179
|
+
if (['init', 'start', 'update', 'upgrade', 'global', 'prompt', 'mcp', 'help', 'version'].includes(cmd)) {
|
|
134
180
|
parsed.command = cmd;
|
|
135
181
|
} else if (!parsed.title && !parsed.path) {
|
|
136
182
|
parsed.path = positional[0];
|
|
@@ -139,9 +185,12 @@ function parseArgs(args) {
|
|
|
139
185
|
|
|
140
186
|
if (parsed.command === 'help') parsed.help = true;
|
|
141
187
|
if (parsed.command === 'version') parsed.version = true;
|
|
188
|
+
if (parsed.command === 'start') parsed.start = true;
|
|
142
189
|
if (parsed.command === 'update') parsed.update = true;
|
|
143
190
|
if (parsed.command === 'upgrade') parsed.upgrade = true;
|
|
144
191
|
if (parsed.command === 'global') parsed.global = true;
|
|
192
|
+
if (parsed.command === 'prompt') parsed.prompt = true;
|
|
193
|
+
if (parsed.command === 'mcp') parsed.mcp = true;
|
|
145
194
|
|
|
146
195
|
return parsed;
|
|
147
196
|
}
|
|
@@ -175,8 +224,13 @@ async function runInteractive(options) {
|
|
|
175
224
|
},
|
|
176
225
|
{
|
|
177
226
|
value: 'both',
|
|
178
|
-
label: `${ui.colors.bold}Full Suite (Local Policy + Global Skills)${ui.colors.reset}`,
|
|
179
|
-
description: 'Configures
|
|
227
|
+
label: `${ui.colors.bold}Full Suite (Local Policy + Global Skills + MCP)${ui.colors.reset}`,
|
|
228
|
+
description: 'Configures repository, global AI skills, and Model Context Protocol manifests'
|
|
229
|
+
},
|
|
230
|
+
{
|
|
231
|
+
value: 'mcp',
|
|
232
|
+
label: `${ui.colors.bold}Configure Model Context Protocol (MCP)${ui.colors.reset}`,
|
|
233
|
+
description: 'Register Archlens MCP tools into Claude Desktop, Antigravity, and Cursor'
|
|
180
234
|
},
|
|
181
235
|
{
|
|
182
236
|
value: 'update',
|
|
@@ -214,6 +268,10 @@ async function runInteractive(options) {
|
|
|
214
268
|
executeGlobalInstall(execOptions);
|
|
215
269
|
}
|
|
216
270
|
|
|
271
|
+
if (selectedAction === 'mcp' || selectedAction === 'both') {
|
|
272
|
+
executeMcpInstall(execOptions);
|
|
273
|
+
}
|
|
274
|
+
|
|
217
275
|
if (selectedAction === 'update') {
|
|
218
276
|
executeUpdate(targetRoot, execOptions);
|
|
219
277
|
}
|
|
@@ -225,6 +283,20 @@ async function runInteractive(options) {
|
|
|
225
283
|
printCompletionMessage(targetRoot, execOptions.serverUrl);
|
|
226
284
|
}
|
|
227
285
|
|
|
286
|
+
function executeMcpInstall(options) {
|
|
287
|
+
const modeSuffix = options.dryRun ? ' (dry run)' : '';
|
|
288
|
+
ui.step(3, 3, `Configuring Model Context Protocol (MCP) Clients${modeSuffix}`);
|
|
289
|
+
const result = installMcpConfigs(options);
|
|
290
|
+
|
|
291
|
+
if (result.configuredClients.length === 0) {
|
|
292
|
+
ui.warn('No active AI client configurations found (~/.claude, ~/.gemini). Use --force to deploy anyway.');
|
|
293
|
+
} else {
|
|
294
|
+
for (const client of result.configuredClients) {
|
|
295
|
+
ui.success(`Configured MCP for ${client.name} (${client.action}): ${client.path}${modeSuffix}`);
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
|
|
228
300
|
function executeLocalInit(targetRoot, options) {
|
|
229
301
|
ui.step(1, 2, 'Scaffolding Clean Architecture Policy');
|
|
230
302
|
const result = installLocalPolicy(targetRoot, options);
|
|
@@ -316,6 +388,26 @@ function printCompletionMessage(targetRoot, serverUrl) {
|
|
|
316
388
|
console.log(` 3. Or press ${ui.colors.bold}⌘O / Ctrl+O${ui.colors.reset} inside Archlens to select this workspace.\n`);
|
|
317
389
|
}
|
|
318
390
|
|
|
391
|
+
function copyToSystemClipboard(text) {
|
|
392
|
+
try {
|
|
393
|
+
if (process.platform === 'darwin') {
|
|
394
|
+
spawnSync('pbcopy', { input: text, encoding: 'utf8' });
|
|
395
|
+
return true;
|
|
396
|
+
} else if (process.platform === 'win32') {
|
|
397
|
+
spawnSync('clip', { input: text, encoding: 'utf8' });
|
|
398
|
+
return true;
|
|
399
|
+
} else {
|
|
400
|
+
const res = spawnSync('xclip', ['-selection', 'clipboard'], { input: text, encoding: 'utf8' });
|
|
401
|
+
if (res.error) {
|
|
402
|
+
spawnSync('wl-copy', { input: text, encoding: 'utf8' });
|
|
403
|
+
}
|
|
404
|
+
return true;
|
|
405
|
+
}
|
|
406
|
+
} catch {
|
|
407
|
+
return false;
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
|
|
319
411
|
async function main() {
|
|
320
412
|
const options = parseArgs(process.argv.slice(2));
|
|
321
413
|
|
|
@@ -329,15 +421,75 @@ async function main() {
|
|
|
329
421
|
process.exit(0);
|
|
330
422
|
}
|
|
331
423
|
|
|
424
|
+
if (options.command === 'prompt' || options.prompt) {
|
|
425
|
+
const targetRoot = path.resolve(options.path || '.');
|
|
426
|
+
try {
|
|
427
|
+
const dossier = await generateLlmPrompt(targetRoot, options);
|
|
428
|
+
if (options.copy) {
|
|
429
|
+
const ok = copyToSystemClipboard(dossier);
|
|
430
|
+
if (ok) {
|
|
431
|
+
ui.success('Clean Architecture Refactoring Dossier copied to system clipboard!');
|
|
432
|
+
} else {
|
|
433
|
+
process.stdout.write(dossier);
|
|
434
|
+
}
|
|
435
|
+
} else {
|
|
436
|
+
process.stdout.write(dossier);
|
|
437
|
+
}
|
|
438
|
+
process.exit(0);
|
|
439
|
+
} catch (err) {
|
|
440
|
+
ui.error(err.message || String(err));
|
|
441
|
+
process.exit(1);
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
if (options.command === 'mcp') {
|
|
446
|
+
startMcpStdioServer({
|
|
447
|
+
version: getPackageVersion(),
|
|
448
|
+
...options
|
|
449
|
+
});
|
|
450
|
+
return;
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
if (options.command === 'start' || options.start) {
|
|
454
|
+
try {
|
|
455
|
+
const port = options.port || '8088';
|
|
456
|
+
const targetUrl = options.serverUrl || (port === '8088' ? DEFAULT_SERVER_URL : `http://localhost:${port}`);
|
|
457
|
+
ui.info(`Checking Archlens Workbench server on ${targetUrl}...`);
|
|
458
|
+
const status = await executeStart(options);
|
|
459
|
+
if (status.status === 'running') {
|
|
460
|
+
if (status.spawned) {
|
|
461
|
+
ui.success(`Archlens container (${DEFAULT_CONTAINER_NAME}) launched successfully!`);
|
|
462
|
+
} else {
|
|
463
|
+
ui.success(`Archlens Workbench server is active (${status.version || 'running'}).`);
|
|
464
|
+
}
|
|
465
|
+
console.log(`\n ${ui.colors.bold}Workbench URL:${ui.colors.reset} ${ui.colors.cyan}${status.serverUrl}${ui.colors.reset}\n`);
|
|
466
|
+
} else if (status.status === 'offline') {
|
|
467
|
+
ui.warn(status.message || 'Archlens server is offline and Docker daemon is unavailable.');
|
|
468
|
+
console.log(`\n ${ui.colors.dim}To run offline architecture analysis:${ui.colors.reset}`);
|
|
469
|
+
console.log(` npx @fmatar/archlens-skill prompt\n`);
|
|
470
|
+
} else {
|
|
471
|
+
ui.error(status.message || 'Failed to start Archlens container.');
|
|
472
|
+
process.exit(1);
|
|
473
|
+
}
|
|
474
|
+
process.exit(0);
|
|
475
|
+
} catch (err) {
|
|
476
|
+
ui.error(err.message || String(err));
|
|
477
|
+
process.exit(1);
|
|
478
|
+
}
|
|
479
|
+
}
|
|
480
|
+
|
|
332
481
|
const isInteractive = Boolean(
|
|
333
482
|
process.stdin.isTTY &&
|
|
334
483
|
process.stdout.isTTY &&
|
|
335
484
|
!options.yes &&
|
|
336
485
|
!options.dryRun &&
|
|
337
486
|
!options.command &&
|
|
487
|
+
!options.start &&
|
|
338
488
|
!options.global &&
|
|
339
489
|
!options.update &&
|
|
340
|
-
!options.upgrade
|
|
490
|
+
!options.upgrade &&
|
|
491
|
+
!options.prompt &&
|
|
492
|
+
!options.mcp
|
|
341
493
|
);
|
|
342
494
|
|
|
343
495
|
if (isInteractive) {
|
|
@@ -367,6 +519,10 @@ async function main() {
|
|
|
367
519
|
executeLocalInit(targetRoot, options);
|
|
368
520
|
}
|
|
369
521
|
|
|
522
|
+
if (options.mcp) {
|
|
523
|
+
executeMcpInstall(options);
|
|
524
|
+
}
|
|
525
|
+
|
|
370
526
|
if (!options.dryRun) {
|
|
371
527
|
printCompletionMessage(targetRoot, options.serverUrl);
|
|
372
528
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fmatar/archlens-skill",
|
|
3
|
-
"version": "0.0.1-Alpha-
|
|
3
|
+
"version": "0.0.1-Alpha-09",
|
|
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",
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: archlens
|
|
3
|
+
description: >-
|
|
4
|
+
Polyglot Clean Architecture governance, dynamic visual workbench companion,
|
|
5
|
+
policy scaffolding, mailbox refactoring protocols, LLM prompt dossiers,
|
|
6
|
+
and Model Context Protocol (MCP) diagnostics for Archlens.
|
|
7
|
+
version: 1.2.0
|
|
8
|
+
license: Apache-2.0
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Archlens — Clean Architecture Governance & Workbench Companion
|
|
12
|
+
|
|
13
|
+
Use this skill when analyzing, governing, or refactoring codebases using **Archlens (Dynamic Clean Architecture Workbench)**.
|
|
14
|
+
|
|
15
|
+
This skill equips agents (Antigravity, Gemini CLI, Claude Code) to:
|
|
16
|
+
1. Enforce Uncle Bob's **Dependency Rule** (dependencies strictly point inward).
|
|
17
|
+
2. Scaffold and maintain `.archlens/policy.json` architectural layer policies.
|
|
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
|
+
4. Export LLM Refactoring Prompt Dossiers prescribing concrete Dependency Inversion Principle (DIP) interface ports.
|
|
20
|
+
5. Invoke Archlens MCP tools (`inspectArchitecture`, `exportLlmDossier`, `listSnapshots`, `getSnapshot`).
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 🏛️ Clean Architecture Concentric Layer Hierarchy
|
|
25
|
+
|
|
26
|
+
Archlens models codebases as concentric circular rings. Source code dependencies (imports, inheritance, calls) MUST point strictly inward:
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
[Level 3: Infrastructure / Web / DB / CLI]
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
[Level 2: Adapters / Controllers / Presenters / Gateways]
|
|
33
|
+
│
|
|
34
|
+
▼
|
|
35
|
+
[Level 1: Application / Use Cases / Ports]
|
|
36
|
+
│
|
|
37
|
+
▼
|
|
38
|
+
[Level 0: Domain Core / Entities / Value Objects]
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- **Level 0 (Domain Core)**: Pure business entities, primitives, domain logic. Zero outward imports or dependencies on frameworks, databases, or UI.
|
|
42
|
+
- **Level 1 (Application)**: Use cases, interaction orchestrators, domain ports. Depends only on Domain Core (Level 0).
|
|
43
|
+
- **Level 2 (Adapters)**: HTTP controllers, presenters, REST resources, repository implementations. Translates between external formats and application models.
|
|
44
|
+
- **Level 3 (Infrastructure)**: Web frameworks, databases, persistence drivers, third-party libraries, CLI entrypoints, configuration.
|
|
45
|
+
|
|
46
|
+
> [!IMPORTANT]
|
|
47
|
+
> **Dependency Inversion Principle (DIP)**: When an inner layer (e.g. Domain or Application) needs a service provided by an outer layer (e.g. Database or External API), declare an **interface port** in the inner layer. Implement the interface in the outer layer (Adapter), and inject it.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## ⚡ CLI & Quickstart Commands
|
|
52
|
+
|
|
53
|
+
Archlens is executed cross-platform via NPX or Node CLI:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Initialize Clean Architecture policy in target project:
|
|
57
|
+
npx @fmatar/archlens-skill --path . --yes
|
|
58
|
+
|
|
59
|
+
# Launch Workbench container (auto-resurrects on demand if stopped or killed):
|
|
60
|
+
npx @fmatar/archlens-skill start --open
|
|
61
|
+
|
|
62
|
+
# Export Clean Architecture LLM Refactoring Prompt Dossier:
|
|
63
|
+
npx @fmatar/archlens-skill prompt --path .
|
|
64
|
+
|
|
65
|
+
# Copy LLM refactoring prompt directly to system clipboard:
|
|
66
|
+
npx @fmatar/archlens-skill prompt --path . --copy
|
|
67
|
+
|
|
68
|
+
# Synchronize policy with newly added packages:
|
|
69
|
+
npx @fmatar/archlens-skill update --path .
|
|
70
|
+
|
|
71
|
+
# Migrate legacy .uml-viewer configuration to modern .archlens layout:
|
|
72
|
+
npx @fmatar/archlens-skill upgrade --path .
|
|
73
|
+
|
|
74
|
+
# Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
|
|
75
|
+
npx @fmatar/archlens-skill --mcp
|
|
76
|
+
|
|
77
|
+
# Launch Model Context Protocol (MCP) stdio server:
|
|
78
|
+
npx @fmatar/archlens-skill mcp
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Launching the Workbench & Auto-Resurrection
|
|
82
|
+
When the user asks to start Archlens, launch the studio, or open the visual workbench:
|
|
83
|
+
1. Run `npx @fmatar/archlens-skill start --open` (or `archlens-skill start`).
|
|
84
|
+
2. The CLI inspects whether the container (`archlens-server`) is active. If stopped or killed, it immediately starts it again on demand and confirms readiness at `http://localhost:8088`.
|
|
85
|
+
3. When using MCP tools (`inspectArchitecture`, `exportLlmDossier`), the stdio bridge also auto-resurrects the container if offline.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## 🤖 Dynamic Workbench Companion Protocol
|
|
90
|
+
|
|
91
|
+
Archlens provides a real-time visual canvas (`http://localhost:8088`). When human architects interact with the UI, tasks are dispatched through a bidirectional mailbox IPC protocol:
|
|
92
|
+
|
|
93
|
+
- **Inbound queue (UI $\rightarrow$ Agent)**: `.archlens/to-agent.json` (or `.uml-viewer/to-agent.json`)
|
|
94
|
+
- **Outbound events (Agent $\rightarrow$ UI)**: `.archlens/to-viewer.json` (or `.uml-viewer/to-viewer.json`)
|
|
95
|
+
|
|
96
|
+
### Mailbox Format (`to-agent.json`)
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"nextId": 2,
|
|
100
|
+
"queue": [
|
|
101
|
+
{
|
|
102
|
+
"id": 1,
|
|
103
|
+
"op": "REGEN",
|
|
104
|
+
"target": { "id": "project" },
|
|
105
|
+
"payload": {}
|
|
106
|
+
}
|
|
107
|
+
]
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Supported Operations:
|
|
112
|
+
1. **`REGEN`**: Re-scan AST, compute violations and instability metrics, compile/test (`mvn test-compile`), and notify UI via `REGEN_COMPLETE`.
|
|
113
|
+
2. **`APPLY_PROPOSAL`**: Read requested layers from `.archlens/policy.json`. Physically restructure packages to match proposed layers. Where inner layers import outer layers, apply DIP by introducing interface ports. Run test suite to verify zero regressions.
|
|
114
|
+
3. **`REFRESH_CRAP`**: Run tests with code coverage (`mvn test` / `npm test`) and update metric snapshots.
|
|
115
|
+
4. **`REFRESH_MUTATION`**: Run mutation testing on target classes.
|
|
116
|
+
5. **`OMIT`**: Add specified package or class to the `:omit` list in policy.
|
|
117
|
+
|
|
118
|
+
### Completing Tasks (`to-viewer.json`):
|
|
119
|
+
Write completion acknowledgment to `.archlens/to-viewer.json`. The backend file watcher pushes an SSE event to hot-reload the canvas:
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"op": "REGEN_COMPLETE",
|
|
123
|
+
"target": { "id": "project" },
|
|
124
|
+
"payload": { "status": "SUCCESS" }
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 🛠️ MCP Tool Suite Reference
|
|
131
|
+
|
|
132
|
+
When Archlens is registered as an MCP server, use the following tools:
|
|
133
|
+
|
|
134
|
+
| MCP Tool | Purpose | Key Arguments |
|
|
135
|
+
| :--- | :--- | :--- |
|
|
136
|
+
| `inspectArchitecture` | Inspect concentric rings, outward violations, and instability metrics | `projectRoot` (default: `.`) |
|
|
137
|
+
| `exportLlmDossier` | Generate copy-ready LLM refactoring prompt with DIP prescriptions | `projectRoot`, `proposalId` |
|
|
138
|
+
| `listSnapshots` | List historical Git release tags and pre-compiled architecture snapshots | `projectRoot` |
|
|
139
|
+
| `getSnapshot` | Retrieve graph model for a historical release or snapshot tag | `snapshotId`, `projectRoot` |
|
|
@@ -21,6 +21,8 @@ Trigger this skill whenever the user asks to:
|
|
|
21
21
|
- "Upgrade Archlens config from .uml-viewer to .archlens"
|
|
22
22
|
- "Connect repository to Archlens workbench"
|
|
23
23
|
- "Prepare this repository for Archlens refactoring companion"
|
|
24
|
+
- "Export LLM refactoring prompt / Clean Architecture diagnostic dossier"
|
|
25
|
+
- "Generate prompt for Claude Code or LLM to fix Clean Architecture violations"
|
|
24
26
|
|
|
25
27
|
---
|
|
26
28
|
|
|
@@ -54,6 +56,12 @@ npx @fmatar/archlens-skill --path . --yes
|
|
|
54
56
|
|
|
55
57
|
# Or upgrade an existing project from .uml-viewer to .archlens
|
|
56
58
|
npx @fmatar/archlens-skill upgrade --path .
|
|
59
|
+
|
|
60
|
+
# Or export LLM Refactoring Prompt Dossier (copy-ready markdown)
|
|
61
|
+
npx @fmatar/archlens-skill prompt --path .
|
|
62
|
+
|
|
63
|
+
# Copy LLM Refactoring Prompt directly to system clipboard
|
|
64
|
+
npx @fmatar/archlens-skill prompt --path . --copy
|
|
57
65
|
```
|
|
58
66
|
|
|
59
67
|
*Flags available:*
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: uml-workbench-companion
|
|
3
|
+
description: >-
|
|
4
|
+
Companion agent for the Clean Architecture Dynamic UML Workbench.
|
|
5
|
+
Monitors .archlens/ and .uml-viewer/ mailbox queues, processes architectural refactoring requests,
|
|
6
|
+
evaluates Clean Architecture violations, runs builds and tests, and signals live diagram reloads.
|
|
7
|
+
version: 1.2.0
|
|
8
|
+
license: Apache-2.0
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# UML Workbench Companion Skill (`uml-workbench-companion`)
|
|
12
|
+
|
|
13
|
+
Use this skill when interacting with the **Clean Architecture Dynamic UML Workbench**. This skill enables Antigravity or Gemini agents to act as the autonomous coding companion to the human architect who is using the visual UML viewer.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## ⚙️ Configuration & Service Endpoints
|
|
18
|
+
|
|
19
|
+
The workbench service endpoint defaults to `http://localhost:8088`, configurable via `.archlens/workbench.config.json` (or `.uml-viewer/workbench.config.json`) or the `ARCHLENS_SERVER_URL` / `WORKBENCH_URL` environment variables.
|
|
20
|
+
|
|
21
|
+
- **Graph & Violation API**: `GET http://localhost:8088/api/graph?proposalId=<id>&projectRoot=<root>`
|
|
22
|
+
- **Mailbox Files**: Located in `.archlens/` (or legacy `.uml-viewer/`) under the examined repository root.
|
|
23
|
+
|
|
24
|
+
## 📋 Core Responsibilities
|
|
25
|
+
|
|
26
|
+
1. **Mailbox Polling & Queue Processing**:
|
|
27
|
+
- Continuously check `.archlens/to-agent.json` (falling back to `.uml-viewer/to-agent.json`).
|
|
28
|
+
- Process commands sequentially in FIFO order (`nextId`, `queue`).
|
|
29
|
+
- Pop handled items from `queue` and atomically rewrite the mailbox file.
|
|
30
|
+
|
|
31
|
+
2. **Command Handlers**:
|
|
32
|
+
- **`REGEN`**: Re-scan the project's AST, re-calculate Clean Architecture levels and dependency violations, and trigger a live graph refresh.
|
|
33
|
+
- **`APPLY_PROPOSAL`**: Read the requested proposal from `.archlens/policy.json` (or `.uml-viewer/policy.json`), physically restructure packages to match the proposed layers, introduce interfaces to invert violating inward-to-outward dependencies, and ensure tests pass.
|
|
34
|
+
- **`REFRESH_CRAP`**: Run tests (`mvn test` / `npm test`) for the target class or package and update JaCoCo coverage metrics.
|
|
35
|
+
- **`REFRESH_MUTATION`**: Run mutation testing on the specified target files and update metrics snapshots.
|
|
36
|
+
- **`OMIT`**: Add the target class or package to the active proposal's `:omit` list in policy.json.
|
|
37
|
+
|
|
38
|
+
3. **Acknowledging to the Viewer**:
|
|
39
|
+
- Append completion status and results to `.archlens/to-viewer.json` (or `.uml-viewer/to-viewer.json`).
|
|
40
|
+
- The Quarkus backend file watcher detects this change and pushes an SSE event to the Svelte frontend, hot-reloading the diagram immediately.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 🛠️ Step-by-Step Execution Workflow
|
|
45
|
+
|
|
46
|
+
### When a User Says: "Check for workbench commands" or "Act as UML companion"
|
|
47
|
+
|
|
48
|
+
1. **Inspect the Outbox**:
|
|
49
|
+
- Read `.archlens/to-agent.json` (or `.uml-viewer/to-agent.json`).
|
|
50
|
+
- If `queue` is empty, report that no commands are pending.
|
|
51
|
+
- If commands exist, select the first command `cmd = queue[0]`.
|
|
52
|
+
|
|
53
|
+
2. **Execute the Requested Operation**:
|
|
54
|
+
- If `cmd.op == "REGEN"`:
|
|
55
|
+
- Verify source integrity.
|
|
56
|
+
- Compile or test if required (`mvn test-compile` or `npm run build`).
|
|
57
|
+
- Write an acknowledgment to `.archlens/to-viewer.json`:
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"op": "REGEN_COMPLETE",
|
|
61
|
+
"target": { "id": "project" },
|
|
62
|
+
"payload": { "status": "SUCCESS" }
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
- If `cmd.op == "APPLY_PROPOSAL"`:
|
|
66
|
+
- Read `.archlens/policy.json` to inspect the requested layer boundaries.
|
|
67
|
+
- Move or refactor classes to conform to the Clean Architecture rule:
|
|
68
|
+
- **Rule**: Dependencies must only point inward (e.g. `adapters` $\rightarrow$ `application` $\rightarrow$ `domain`).
|
|
69
|
+
- If `domain` depends on `adapters`, introduce an interface in `domain` and implement it in `adapters` (Dependency Inversion Principle).
|
|
70
|
+
- Run tests to verify zero regressions.
|
|
71
|
+
- Acknowledge completion in `.archlens/to-viewer.json`.
|
|
72
|
+
|
|
73
|
+
3. **Pop Handled Command**:
|
|
74
|
+
- Remove `cmd` from the queue and update `nextId`.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## 🔄 Autonomous Background Monitoring
|
|
79
|
+
|
|
80
|
+
To monitor the workbench autonomously in the background while the architect is using the browser UI:
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
schedule(
|
|
84
|
+
CronExpression="*/1 * * * *",
|
|
85
|
+
Prompt="Check .archlens/to-agent.json (or .uml-viewer/to-agent.json) for pending workbench commands and process them.",
|
|
86
|
+
IsDaemon=false
|
|
87
|
+
)
|
|
88
|
+
```
|