@fmatar/archlens-skill 1.1.2-dev.65 → 1.1.3-dev.66
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 +11 -6
- package/bin/index.js +48 -7
- package/llms.txt +4 -2
- package/package.json +1 -1
- package/skills/archlens/SKILL.md +9 -3
- package/skills/archlens-install-policy/SKILL.md +13 -5
- package/skills/uml-workbench-companion/SKILL.md +2 -2
- package/src/mcp-registry.js +4 -0
- package/src/mcp-server.js +1 -1
package/README.md
CHANGED
|
@@ -13,13 +13,17 @@ Analyzes any project repository, detects programming languages and package hiera
|
|
|
13
13
|
## ⚡ Quickstart
|
|
14
14
|
|
|
15
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.
|
|
16
|
+
Equip **Google Antigravity**, **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, and **Gemini CLI** in one command. Choose the portable NPX stdio bridge (with 4-tier offline AST fallback) or an ephemeral Docker `mcp-stdio` container:
|
|
17
17
|
```bash
|
|
18
|
-
#
|
|
18
|
+
# Portable / shared-repo setup (.archlens/policy.json + AGENTS.md + skills + NPX MCP bridge):
|
|
19
19
|
npx @fmatar/archlens-skill --yes --skills --mcp
|
|
20
20
|
|
|
21
|
-
#
|
|
22
|
-
npx @fmatar/archlens-skill skills
|
|
21
|
+
# Personal workstation setup (ephemeral docker run -i --rm -e QUARKUS_PROFILE=mcp-stdio container):
|
|
22
|
+
npx @fmatar/archlens-skill --yes --skills --mcp --docker
|
|
23
|
+
|
|
24
|
+
# Equip global skills AND global MCP manifests across all detected coding agents:
|
|
25
|
+
npx @fmatar/archlens-skill global
|
|
26
|
+
npx @fmatar/archlens-skill global --docker
|
|
23
27
|
```
|
|
24
28
|
|
|
25
29
|
### Option B: Install AI Assistant Skills Directly via `npx skills`
|
|
@@ -103,10 +107,11 @@ Target a specific repository directory:
|
|
|
103
107
|
npx @fmatar/archlens-skill --path /path/to/project --yes
|
|
104
108
|
```
|
|
105
109
|
|
|
106
|
-
#### 3. Global AI Agent Skill Installation
|
|
107
|
-
Deploys
|
|
110
|
+
#### 3. Global AI Agent Skill & MCP Installation
|
|
111
|
+
Deploys skills and global MCP manifests so Claude Code, Gemini CLI, and Antigravity are equipped across all workspaces (pass `--docker` for ephemeral container mode or `--no-mcp` to skip MCP setup):
|
|
108
112
|
```bash
|
|
109
113
|
npx @fmatar/archlens-skill global
|
|
114
|
+
npx @fmatar/archlens-skill global --docker
|
|
110
115
|
```
|
|
111
116
|
|
|
112
117
|
#### 4. Synchronize Existing Policy
|
package/bin/index.js
CHANGED
|
@@ -28,7 +28,12 @@ import {
|
|
|
28
28
|
} from '../src/checker.js';
|
|
29
29
|
import { installMcpConfigs } from '../src/mcp-registry.js';
|
|
30
30
|
import { startMcpStdioServer } from '../src/mcp-server.js';
|
|
31
|
-
import {
|
|
31
|
+
import {
|
|
32
|
+
executeStart,
|
|
33
|
+
isDockerAvailable,
|
|
34
|
+
DEFAULT_CONTAINER_NAME,
|
|
35
|
+
DEFAULT_SERVER_URL
|
|
36
|
+
} from '../src/docker-runner.js';
|
|
32
37
|
import { spawnSync } from 'node:child_process';
|
|
33
38
|
|
|
34
39
|
const __filename = fileURLToPath(import.meta.url);
|
|
@@ -61,7 +66,7 @@ ${ui.colors.bold}COMMANDS:${ui.colors.reset}
|
|
|
61
66
|
update Update existing policy with newly discovered packages and refresh skills
|
|
62
67
|
upgrade Upgrade legacy .uml-viewer configuration to .archlens
|
|
63
68
|
skills Install Archlens skills via npx skills (local project or -g global)
|
|
64
|
-
global Install Archlens skills
|
|
69
|
+
global Install Archlens skills and global MCP manifests for AI coding assistants
|
|
65
70
|
prompt Export Clean Architecture LLM Refactoring Prompt Dossier
|
|
66
71
|
mcp Launch Model Context Protocol (MCP) stdio server for AI assistants
|
|
67
72
|
|
|
@@ -81,6 +86,7 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
|
|
|
81
86
|
--jar <PATH> Custom path to Archlens Quarkus runner JAR
|
|
82
87
|
-o, --open Open visual workbench in default browser upon startup
|
|
83
88
|
-m, --mcp Auto-configure MCP server manifests in AI clients (Claude, Antigravity, Cursor)
|
|
89
|
+
--no-mcp Skip automatic MCP client configuration (e.g. during global install)
|
|
84
90
|
--skills Install Archlens skills into target project via npx skills
|
|
85
91
|
--agent <AGENT> Target specific coding agent(s) when installing skills (e.g. claude-code,cursor)
|
|
86
92
|
-c, --copy Copy LLM prompt output directly to system clipboard
|
|
@@ -148,6 +154,7 @@ export function parseArgs(args) {
|
|
|
148
154
|
update: false,
|
|
149
155
|
upgrade: false,
|
|
150
156
|
mcp: false,
|
|
157
|
+
noMcp: false,
|
|
151
158
|
check: false,
|
|
152
159
|
maxViolations: 0,
|
|
153
160
|
detectCycles: false,
|
|
@@ -178,6 +185,10 @@ export function parseArgs(args) {
|
|
|
178
185
|
parsed.port = args[++i] || '8088';
|
|
179
186
|
} else if (arg === '--mcp' || arg === '-m') {
|
|
180
187
|
parsed.mcp = true;
|
|
188
|
+
parsed.noMcp = false;
|
|
189
|
+
} else if (arg === '--no-mcp') {
|
|
190
|
+
parsed.noMcp = true;
|
|
191
|
+
parsed.mcp = false;
|
|
181
192
|
} else if (arg === '--skills') {
|
|
182
193
|
parsed.skills = true;
|
|
183
194
|
} else if (arg === '--agent') {
|
|
@@ -259,6 +270,7 @@ export function parseArgs(args) {
|
|
|
259
270
|
async function runInteractive(options, deps = {}) {
|
|
260
271
|
const askChoice = deps.askChoice || ui.askChoice;
|
|
261
272
|
const askQuestion = deps.askQuestion || ui.askQuestion;
|
|
273
|
+
const checkDocker = deps.isDockerAvailable || isDockerAvailable;
|
|
262
274
|
ui.banner();
|
|
263
275
|
|
|
264
276
|
const targetRoot = path.resolve(options.path || '.');
|
|
@@ -282,8 +294,8 @@ async function runInteractive(options, deps = {}) {
|
|
|
282
294
|
},
|
|
283
295
|
{
|
|
284
296
|
value: 'install_global',
|
|
285
|
-
label: `${ui.colors.bold}Deploy AI Agent Skills
|
|
286
|
-
description: 'Equips Claude Code, Gemini CLI, and Antigravity with Archlens skills'
|
|
297
|
+
label: `${ui.colors.bold}Deploy AI Agent Skills & Global MCP${ui.colors.reset}`,
|
|
298
|
+
description: 'Equips Claude Code, Gemini CLI, and Antigravity with Archlens skills and MCP'
|
|
287
299
|
},
|
|
288
300
|
{
|
|
289
301
|
value: 'both',
|
|
@@ -316,10 +328,30 @@ async function runInteractive(options, deps = {}) {
|
|
|
316
328
|
|
|
317
329
|
const execOptions = {
|
|
318
330
|
...options,
|
|
331
|
+
path: targetRoot,
|
|
319
332
|
title: customTitle,
|
|
320
333
|
prefix
|
|
321
334
|
};
|
|
322
335
|
|
|
336
|
+
const wantsMcp = ['install_global', 'mcp', 'both'].includes(selectedAction) && !execOptions.noMcp;
|
|
337
|
+
if (wantsMcp && !execOptions.preferDocker && !execOptions.preferNative && checkDocker()) {
|
|
338
|
+
const transportChoice = await askChoice('Select MCP transport mode:', [
|
|
339
|
+
{
|
|
340
|
+
value: 'npx',
|
|
341
|
+
label: `${ui.colors.bold}NPX Stdio Bridge (Recommended for shared repos)${ui.colors.reset}`,
|
|
342
|
+
description: 'Path-agnostic npx -y @fmatar/archlens-skill mcp with 4-tier offline AST fallback'
|
|
343
|
+
},
|
|
344
|
+
{
|
|
345
|
+
value: 'docker',
|
|
346
|
+
label: `${ui.colors.bold}Ephemeral Docker Container (mcp-stdio)${ui.colors.reset}`,
|
|
347
|
+
description: 'Pure docker run -i --rm ghcr.io/fmatar/archlens:latest (zero host Node/Java needed)'
|
|
348
|
+
}
|
|
349
|
+
]);
|
|
350
|
+
if (transportChoice === 'docker') {
|
|
351
|
+
execOptions.preferDocker = true;
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
|
|
323
355
|
ui.divider();
|
|
324
356
|
|
|
325
357
|
if (selectedAction === 'init_local' || selectedAction === 'both') {
|
|
@@ -330,7 +362,9 @@ async function runInteractive(options, deps = {}) {
|
|
|
330
362
|
executeGlobalInstall(execOptions);
|
|
331
363
|
}
|
|
332
364
|
|
|
333
|
-
if (selectedAction === '
|
|
365
|
+
if (selectedAction === 'install_global' && !execOptions.noMcp) {
|
|
366
|
+
executeMcpInstall({ ...execOptions, scopeOnly: 'global' });
|
|
367
|
+
} else if ((selectedAction === 'mcp' || selectedAction === 'both') && !execOptions.noMcp) {
|
|
334
368
|
executeMcpInstall(execOptions);
|
|
335
369
|
}
|
|
336
370
|
|
|
@@ -752,8 +786,15 @@ export async function main(rawArgs = process.argv.slice(2), deps = {}) {
|
|
|
752
786
|
}
|
|
753
787
|
}
|
|
754
788
|
|
|
755
|
-
if (options.
|
|
756
|
-
|
|
789
|
+
if (!options.noMcp) {
|
|
790
|
+
if (options.mcp) {
|
|
791
|
+
executeMcpInstall({ ...options, path: targetRoot });
|
|
792
|
+
} else if (
|
|
793
|
+
options.command === 'global' ||
|
|
794
|
+
(options.global && options.command !== 'skills' && !options.skills && !options.update && !options.upgrade)
|
|
795
|
+
) {
|
|
796
|
+
executeMcpInstall({ ...options, path: targetRoot, scopeOnly: 'global' });
|
|
797
|
+
}
|
|
757
798
|
}
|
|
758
799
|
|
|
759
800
|
if (!options.dryRun) {
|
package/llms.txt
CHANGED
|
@@ -79,8 +79,10 @@ npx @fmatar/archlens-skill init --yes
|
|
|
79
79
|
npx @fmatar/archlens-skill update
|
|
80
80
|
|
|
81
81
|
# 5. Model Context Protocol (MCP) Integration:
|
|
82
|
-
npx @fmatar/archlens-skill --mcp
|
|
83
|
-
npx @fmatar/archlens-skill mcp
|
|
82
|
+
npx @fmatar/archlens-skill --mcp # Auto-configure portable NPX bridge manifests
|
|
83
|
+
npx @fmatar/archlens-skill --mcp --docker # Auto-configure ephemeral Docker mcp-stdio manifests
|
|
84
|
+
npx @fmatar/archlens-skill global [--docker] # Install global skills + global MCP manifests
|
|
85
|
+
npx @fmatar/archlens-skill mcp # Launch MCP stdio bridge server
|
|
84
86
|
```
|
|
85
87
|
|
|
86
88
|
---
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fmatar/archlens-skill",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.3-dev.66",
|
|
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",
|
package/skills/archlens/SKILL.md
CHANGED
|
@@ -7,10 +7,10 @@ description: >-
|
|
|
7
7
|
layer boundaries, inverting outward dependencies (DIP), or running Archlens.
|
|
8
8
|
license: Apache-2.0
|
|
9
9
|
compatibility: "Node.js >= 18"
|
|
10
|
-
version: 1.1.
|
|
10
|
+
version: 1.1.3-dev.66
|
|
11
11
|
metadata:
|
|
12
12
|
author: fmatar
|
|
13
|
-
version: "1.1.
|
|
13
|
+
version: "1.1.3-dev.66"
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
# Archlens — Clean Architecture Governance & Workbench Companion
|
|
@@ -57,10 +57,16 @@ Archlens models codebases as concentric circular rings. Source code dependencies
|
|
|
57
57
|
|
|
58
58
|
Install Archlens across 15+ coding agents (Antigravity, Claude Code, Cursor, Gemini CLI) via `skills.sh`:
|
|
59
59
|
```bash
|
|
60
|
-
# Add Archlens to your active agent skills library:
|
|
60
|
+
# Add Archlens skills to your active agent skills library:
|
|
61
61
|
npx skills add fmatar/archlens --all -y
|
|
62
|
+
|
|
63
|
+
# Equip global skills AND global MCP manifests in one command (add --docker for ephemeral container mode):
|
|
64
|
+
npx @fmatar/archlens-skill global
|
|
62
65
|
```
|
|
63
66
|
|
|
67
|
+
> [!TIP]
|
|
68
|
+
> **First-Run MCP Auto-Bootstrap (for `npx skills` installs)**: Because `npx skills add` only copies `SKILL.md` files without executing scripts, check whether the `archlens` MCP tools (`inspectArchitecture`, `exportLlmDossier`, `evaluateFitness`) are registered in your active session. If missing, run `npx @fmatar/archlens-skill --path . --yes --mcp` (portable NPX bridge) or `npx @fmatar/archlens-skill global --docker` (ephemeral `mcp-stdio` Docker container when Docker is running).
|
|
69
|
+
|
|
64
70
|
Or execute directly on demand via NPX:
|
|
65
71
|
|
|
66
72
|
```bash
|
|
@@ -6,10 +6,10 @@ description: >-
|
|
|
6
6
|
agent workbench companion integration. Use when setting up or upgrading Archlens.
|
|
7
7
|
license: Apache-2.0
|
|
8
8
|
compatibility: "Node.js >= 18"
|
|
9
|
-
version: 1.1.
|
|
9
|
+
version: 1.1.3-dev.66
|
|
10
10
|
metadata:
|
|
11
11
|
author: fmatar
|
|
12
|
-
version: "1.1.
|
|
12
|
+
version: "1.1.3-dev.66"
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
# Archlens Policy & Companion Installer (`archlens-install-policy`)
|
|
@@ -55,11 +55,17 @@ When executed, this skill generates the following artifacts in the target projec
|
|
|
55
55
|
## 🛠️ Execution Instructions for Agents
|
|
56
56
|
|
|
57
57
|
### Step 1: Run the Archlens Installer or Upgrader
|
|
58
|
-
Execute the cross-platform CLI via NPX against the target repository:
|
|
58
|
+
Execute the cross-platform CLI via NPX against the target repository (passing `--mcp` so the `archlens` MCP server is also registered if not yet configured):
|
|
59
59
|
|
|
60
60
|
```bash
|
|
61
|
-
# Initialize a new project
|
|
62
|
-
npx @fmatar/archlens-skill --path . --yes
|
|
61
|
+
# Initialize a new project and register portable MCP manifests:
|
|
62
|
+
npx @fmatar/archlens-skill --path . --yes --mcp
|
|
63
|
+
|
|
64
|
+
# Or register MCP as an ephemeral Docker STDIO container (when Docker is running on personal workstations):
|
|
65
|
+
npx @fmatar/archlens-skill --path . --yes --mcp --docker
|
|
66
|
+
|
|
67
|
+
# Initialize policy only (skip MCP client configuration):
|
|
68
|
+
npx @fmatar/archlens-skill --path . --yes --no-mcp
|
|
63
69
|
|
|
64
70
|
# Or upgrade an existing project from .uml-viewer to .archlens
|
|
65
71
|
npx @fmatar/archlens-skill upgrade --path .
|
|
@@ -76,6 +82,8 @@ npx @fmatar/archlens-skill prompt --path . --copy
|
|
|
76
82
|
- `--title <NAME>`: Custom project display title.
|
|
77
83
|
- `--prefix <PKG>`: Explicit package prefix (e.g. `com.mycompany.service`).
|
|
78
84
|
- `--server-url <URL>`: Archlens workbench endpoint (defaults to `http://localhost:8088`).
|
|
85
|
+
- `--mcp` / `--no-mcp`: Register (or skip) Archlens MCP manifests across Antigravity, Claude, Cursor, Gemini CLI, and VS Code.
|
|
86
|
+
- `--docker`: Configure MCP as an ephemeral `docker run -i --rm -e QUARKUS_PROFILE=mcp-stdio` container instead of `npx`.
|
|
79
87
|
- `--update`: Re-scans code for new packages and updates existing policy.
|
|
80
88
|
- `--upgrade`: Migrates legacy `.uml-viewer/` configuration and mailboxes to `.archlens/`.
|
|
81
89
|
- `--force`: Overwrite existing `.archlens/policy.json` if present.
|
|
@@ -6,10 +6,10 @@ description: >-
|
|
|
6
6
|
evaluates Clean Architecture violations, runs builds and tests, and signals live diagram reloads.
|
|
7
7
|
license: Apache-2.0
|
|
8
8
|
compatibility: "Node.js >= 18"
|
|
9
|
-
version: 1.1.
|
|
9
|
+
version: 1.1.3-dev.66
|
|
10
10
|
metadata:
|
|
11
11
|
author: fmatar
|
|
12
|
-
version: "1.1.
|
|
12
|
+
version: "1.1.3-dev.66"
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
# UML Workbench Companion Skill (`uml-workbench-companion`)
|
package/src/mcp-registry.js
CHANGED
|
@@ -418,12 +418,16 @@ export function installMcpConfigs(options = {}) {
|
|
|
418
418
|
const homedir = options.homedir || os.homedir();
|
|
419
419
|
const dryRun = Boolean(options.dryRun);
|
|
420
420
|
const force = Boolean(options.force);
|
|
421
|
+
const scopeOnly = options.scopeOnly || null;
|
|
421
422
|
const serverUrl = options.serverUrl || 'http://localhost:8088';
|
|
422
423
|
|
|
423
424
|
const targets = getClientConfigLocations(projectRoot, homedir);
|
|
424
425
|
const results = [];
|
|
425
426
|
|
|
426
427
|
for (const target of targets) {
|
|
428
|
+
if (scopeOnly && target.scope !== scopeOnly) {
|
|
429
|
+
continue;
|
|
430
|
+
}
|
|
427
431
|
const parentExists = fs.existsSync(target.parentDir);
|
|
428
432
|
const targetExists = fs.existsSync(target.filePath);
|
|
429
433
|
|