@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 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. Once configured, your AI assistant **automatically starts or resurrects Archlens on demand** whenever an architectural MCP tool is invoked—no manual container management required:
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
- # Scaffold .archlens/policy.json, AGENTS.md/CLAUDE.md, install project skills via npx skills, and auto-configure MCP clients:
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
- # Or install skills globally across all detected coding agents via npx skills:
22
- npx @fmatar/archlens-skill skills -g
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 the skill globally so Claude Code, Gemini CLI, and Antigravity can scaffold policies on demand:
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 { executeStart, DEFAULT_CONTAINER_NAME, DEFAULT_SERVER_URL } from '../src/docker-runner.js';
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 globally for AI coding assistants
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 globally${ui.colors.reset}`,
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 === 'mcp' || selectedAction === 'both') {
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.mcp) {
756
- executeMcpInstall(options);
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 # Auto-configure Claude, Antigravity, Cursor manifests
83
- npx @fmatar/archlens-skill mcp # Launch MCP stdio bridge server
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.2-dev.65",
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",
@@ -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.2-dev.65
10
+ version: 1.1.3-dev.66
11
11
  metadata:
12
12
  author: fmatar
13
- version: "1.1.2-dev.65"
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.2-dev.65
9
+ version: 1.1.3-dev.66
10
10
  metadata:
11
11
  author: fmatar
12
- version: "1.1.2-dev.65"
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 with defaults
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.2-dev.65
9
+ version: 1.1.3-dev.66
10
10
  metadata:
11
11
  author: fmatar
12
- version: "1.1.2-dev.65"
12
+ version: "1.1.3-dev.66"
13
13
  ---
14
14
 
15
15
  # UML Workbench Companion Skill (`uml-workbench-companion`)
@@ -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
 
package/src/mcp-server.js CHANGED
@@ -28,7 +28,7 @@ function getPackageVersion() {
28
28
  } catch {
29
29
  // ignore
30
30
  }
31
- return '1.1.2';
31
+ return '1.1.3';
32
32
  }
33
33
 
34
34
  export function getMcpToolsList() {