@fmatar/archlens-skill 1.1.2 → 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
@@ -137,6 +142,9 @@ Configures detected AI client manifests or launches an interactive stdio bridge:
137
142
  # Auto-configure Claude Desktop, Google Antigravity, Claude Code, Cursor, and VS Code
138
143
  npx @fmatar/archlens-skill --mcp
139
144
 
145
+ # Auto-configure pure ephemeral Docker MCP container (docker run -i --rm -e QUARKUS_PROFILE=mcp-stdio)
146
+ npx @fmatar/archlens-skill --mcp --docker
147
+
140
148
  # Launch MCP stdio transport bridge (spins up Docker container automatically when needed)
141
149
  npx @fmatar/archlens-skill mcp
142
150
  ```
@@ -175,7 +183,7 @@ npx @fmatar/archlens-skill start --path /path/to/project --port 8088 --open
175
183
  | `--format <FMT>` | | Output format for `check` (`text`, `json`, `sarif`) | `text` |
176
184
  | `--output <FILE>` | `-O` | Write `check` output report (e.g. SARIF) to file | |
177
185
  | `--native` | | Force native JVM runner mode on `start` | `false` |
178
- | `--docker` | | Force Docker container mode on `start` | `false` |
186
+ | `--docker` | | Force Docker container mode on `start` or configure ephemeral `mcp-stdio` manifests with `--mcp` | `false` |
179
187
  | `--jar <PATH>` | | Custom path to `quarkus-run.jar` for native mode | Auto-detected |
180
188
  | `--open` | `-o` | Open visual workbench in default browser upon startup | `false` |
181
189
  | `--port <PORT>` | | Workbench HTTP port | `8088` |
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
 
@@ -77,10 +82,11 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
77
82
  --server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
78
83
  --port <PORT> Workbench HTTP port (default: 8088)
79
84
  --native Prefer running workbench via native Java Quarkus runner (default)
80
- --docker Force running workbench via Docker container
85
+ --docker Force Docker container mode on start or ephemeral MCP STDIO with --mcp
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
@@ -101,6 +107,9 @@ ${ui.colors.bold}EXAMPLES:${ui.colors.reset}
101
107
  ${ui.colors.dim}# Configure MCP manifests across Claude, Antigravity, and Cursor:${ui.colors.reset}
102
108
  npx @fmatar/archlens-skill --mcp
103
109
 
110
+ ${ui.colors.dim}# Configure ephemeral Docker MCP container (docker run -i --rm):${ui.colors.reset}
111
+ npx @fmatar/archlens-skill --mcp --docker
112
+
104
113
  ${ui.colors.dim}# Launch MCP stdio bridge server for AI coding assistants:${ui.colors.reset}
105
114
  npx @fmatar/archlens-skill mcp
106
115
 
@@ -145,6 +154,7 @@ export function parseArgs(args) {
145
154
  update: false,
146
155
  upgrade: false,
147
156
  mcp: false,
157
+ noMcp: false,
148
158
  check: false,
149
159
  maxViolations: 0,
150
160
  detectCycles: false,
@@ -175,6 +185,10 @@ export function parseArgs(args) {
175
185
  parsed.port = args[++i] || '8088';
176
186
  } else if (arg === '--mcp' || arg === '-m') {
177
187
  parsed.mcp = true;
188
+ parsed.noMcp = false;
189
+ } else if (arg === '--no-mcp') {
190
+ parsed.noMcp = true;
191
+ parsed.mcp = false;
178
192
  } else if (arg === '--skills') {
179
193
  parsed.skills = true;
180
194
  } else if (arg === '--agent') {
@@ -256,6 +270,7 @@ export function parseArgs(args) {
256
270
  async function runInteractive(options, deps = {}) {
257
271
  const askChoice = deps.askChoice || ui.askChoice;
258
272
  const askQuestion = deps.askQuestion || ui.askQuestion;
273
+ const checkDocker = deps.isDockerAvailable || isDockerAvailable;
259
274
  ui.banner();
260
275
 
261
276
  const targetRoot = path.resolve(options.path || '.');
@@ -279,8 +294,8 @@ async function runInteractive(options, deps = {}) {
279
294
  },
280
295
  {
281
296
  value: 'install_global',
282
- label: `${ui.colors.bold}Deploy AI Agent Skills globally${ui.colors.reset}`,
283
- 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'
284
299
  },
285
300
  {
286
301
  value: 'both',
@@ -313,10 +328,30 @@ async function runInteractive(options, deps = {}) {
313
328
 
314
329
  const execOptions = {
315
330
  ...options,
331
+ path: targetRoot,
316
332
  title: customTitle,
317
333
  prefix
318
334
  };
319
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
+
320
355
  ui.divider();
321
356
 
322
357
  if (selectedAction === 'init_local' || selectedAction === 'both') {
@@ -327,7 +362,9 @@ async function runInteractive(options, deps = {}) {
327
362
  executeGlobalInstall(execOptions);
328
363
  }
329
364
 
330
- 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) {
331
368
  executeMcpInstall(execOptions);
332
369
  }
333
370
 
@@ -749,8 +786,15 @@ export async function main(rawArgs = process.argv.slice(2), deps = {}) {
749
786
  }
750
787
  }
751
788
 
752
- if (options.mcp) {
753
- 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
+ }
754
798
  }
755
799
 
756
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",
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
10
+ version: 1.1.3-dev.66
11
11
  metadata:
12
12
  author: fmatar
13
- version: "1.1.2"
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
@@ -88,6 +94,9 @@ npx @fmatar/archlens-skill upgrade --path .
88
94
  # Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
89
95
  npx @fmatar/archlens-skill --mcp
90
96
 
97
+ # Auto-configure pure ephemeral Docker MCP container (docker run -i --rm -e QUARKUS_PROFILE=mcp-stdio):
98
+ npx @fmatar/archlens-skill --mcp --docker
99
+
91
100
  # Launch Model Context Protocol (MCP) stdio server:
92
101
  npx @fmatar/archlens-skill mcp
93
102
  ```
@@ -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
9
+ version: 1.1.3-dev.66
10
10
  metadata:
11
11
  author: fmatar
12
- version: "1.1.2"
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
9
+ version: 1.1.3-dev.66
10
10
  metadata:
11
11
  author: fmatar
12
- version: "1.1.2"
12
+ version: "1.1.3-dev.66"
13
13
  ---
14
14
 
15
15
  # UML Workbench Companion Skill (`uml-workbench-companion`)
@@ -8,6 +8,7 @@
8
8
  import * as fs from 'node:fs';
9
9
  import * as path from 'node:path';
10
10
  import * as os from 'node:os';
11
+ import { DEFAULT_DOCKER_IMAGE } from './docker-runner.js';
11
12
 
12
13
  export const ARCHLENS_TOOL_SCHEMAS = {
13
14
  inspectArchitecture: {
@@ -360,7 +361,49 @@ export function getClientConfigLocations(projectRoot = '.', homedir = os.homedir
360
361
  ];
361
362
  }
362
363
 
363
- export function getMcpManifestEntry(serverUrl = 'http://localhost:8088') {
364
+ export function resolveDockerHostWorkspace(options = {}) {
365
+ if (options.hostWorkspace) {
366
+ return path.resolve(options.hostWorkspace);
367
+ }
368
+ const exists = options.existsSync || fs.existsSync;
369
+ const projectRoot = path.resolve(options.path || '.');
370
+ if (options.scope === 'global' && options.homedir) {
371
+ const sharedWorkspace = path.resolve(options.homedir, 'workspace');
372
+ if (
373
+ exists(sharedWorkspace) &&
374
+ (projectRoot === sharedWorkspace || projectRoot.startsWith(sharedWorkspace + path.sep))
375
+ ) {
376
+ return sharedWorkspace;
377
+ }
378
+ }
379
+ return projectRoot;
380
+ }
381
+
382
+ export function getMcpManifestEntry(serverUrl = 'http://localhost:8088', options = {}) {
383
+ if (options.preferDocker || options.docker) {
384
+ const hostWorkspace = resolveDockerHostWorkspace(options);
385
+ const image = options.image || DEFAULT_DOCKER_IMAGE;
386
+ return {
387
+ command: 'docker',
388
+ args: [
389
+ 'run',
390
+ '-i',
391
+ '--rm',
392
+ '-e',
393
+ 'QUARKUS_PROFILE',
394
+ '-e',
395
+ 'ARCHLENS_HOST_WORKSPACE',
396
+ '-v',
397
+ `${hostWorkspace}:/workspace`,
398
+ image
399
+ ],
400
+ env: {
401
+ QUARKUS_PROFILE: 'mcp-stdio',
402
+ ARCHLENS_HOST_WORKSPACE: hostWorkspace
403
+ }
404
+ };
405
+ }
406
+
364
407
  return {
365
408
  command: 'npx',
366
409
  args: ['-y', '@fmatar/archlens-skill', 'mcp'],
@@ -375,12 +418,16 @@ export function installMcpConfigs(options = {}) {
375
418
  const homedir = options.homedir || os.homedir();
376
419
  const dryRun = Boolean(options.dryRun);
377
420
  const force = Boolean(options.force);
421
+ const scopeOnly = options.scopeOnly || null;
378
422
  const serverUrl = options.serverUrl || 'http://localhost:8088';
379
423
 
380
424
  const targets = getClientConfigLocations(projectRoot, homedir);
381
425
  const results = [];
382
426
 
383
427
  for (const target of targets) {
428
+ if (scopeOnly && target.scope !== scopeOnly) {
429
+ continue;
430
+ }
384
431
  const parentExists = fs.existsSync(target.parentDir);
385
432
  const targetExists = fs.existsSync(target.filePath);
386
433
 
@@ -419,19 +466,26 @@ export function installMcpConfigs(options = {}) {
419
466
  }
420
467
  }
421
468
 
469
+ const entryOptions = {
470
+ ...options,
471
+ path: projectRoot,
472
+ homedir,
473
+ scope: target.scope
474
+ };
475
+
422
476
  if (target.id === 'vscode') {
423
477
  if (!manifest.servers || typeof manifest.servers !== 'object') {
424
478
  manifest.servers = {};
425
479
  }
426
480
  manifest.servers.archlens = {
427
481
  type: 'stdio',
428
- ...getMcpManifestEntry(serverUrl)
482
+ ...getMcpManifestEntry(serverUrl, entryOptions)
429
483
  };
430
484
  } else {
431
485
  if (!manifest.mcpServers || typeof manifest.mcpServers !== 'object') {
432
486
  manifest.mcpServers = {};
433
487
  }
434
- manifest.mcpServers.archlens = getMcpManifestEntry(serverUrl);
488
+ manifest.mcpServers.archlens = getMcpManifestEntry(serverUrl, entryOptions);
435
489
  }
436
490
 
437
491
  if (!dryRun) {
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() {
@@ -166,7 +166,17 @@ export async function executeToolCall(toolName, args = {}, options = {}, deps =
166
166
  const runner = deps.ensureServerRunning || ensureServerRunning;
167
167
 
168
168
  // Attempt server readiness inspection
169
- const serverStatus = await runner({ serverUrl, workspace: projectRoot }, deps);
169
+ const serverStatus = await runner(
170
+ {
171
+ serverUrl,
172
+ workspace: projectRoot,
173
+ preferDocker: options.preferDocker,
174
+ preferNative: options.preferNative,
175
+ jarPath: options.jarPath,
176
+ binaryPath: options.binaryPath
177
+ },
178
+ deps
179
+ );
170
180
  const isOnline = serverStatus.status === 'running';
171
181
 
172
182
  if (toolName === 'exportLlmDossier') {