@fmatar/archlens-skill 1.1.1 → 1.1.2-dev.65

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
@@ -15,21 +15,21 @@ Analyzes any project repository, detects programming languages and package hiera
15
15
  ### Option A: Zero-Touch Autonomous AI Setup (`--mcp` — Recommended for Antigravity & Claude)
16
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
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
18
+ # Scaffold .archlens/policy.json, AGENTS.md/CLAUDE.md, install project skills via npx skills, and auto-configure MCP clients:
19
+ npx @fmatar/archlens-skill --yes --skills --mcp
20
20
 
21
- # Or also install global skills into ~/.claude/skills and ~/.gemini/config/skills:
22
- npx @fmatar/archlens-skill --global --mcp
21
+ # Or install skills globally across all detected coding agents via npx skills:
22
+ npx @fmatar/archlens-skill skills -g
23
23
  ```
24
24
 
25
- ### Option B: Install AI Assistant Skills via Open Skills Standard
25
+ ### Option B: Install AI Assistant Skills Directly via `npx skills`
26
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):
27
27
  ```bash
28
- # Add to all detected AI assistants in project or globally:
29
- npx skills add fmatar/archlens
28
+ # Add all 3 Archlens skills to detected AI assistants in project or globally:
29
+ npx skills add fmatar/archlens --all -y
30
30
 
31
31
  # Or add to a specific assistant:
32
- npx skills add fmatar/archlens --agent claude-code
32
+ npx skills add fmatar/archlens --all --agent claude-code -y
33
33
  ```
34
34
 
35
35
  ### Option C: Run Interactive Policy Scaffolder via NPX
@@ -137,6 +137,9 @@ Configures detected AI client manifests or launches an interactive stdio bridge:
137
137
  # Auto-configure Claude Desktop, Google Antigravity, Claude Code, Cursor, and VS Code
138
138
  npx @fmatar/archlens-skill --mcp
139
139
 
140
+ # Auto-configure pure ephemeral Docker MCP container (docker run -i --rm -e QUARKUS_PROFILE=mcp-stdio)
141
+ npx @fmatar/archlens-skill --mcp --docker
142
+
140
143
  # Launch MCP stdio transport bridge (spins up Docker container automatically when needed)
141
144
  npx @fmatar/archlens-skill mcp
142
145
  ```
@@ -175,7 +178,7 @@ npx @fmatar/archlens-skill start --path /path/to/project --port 8088 --open
175
178
  | `--format <FMT>` | | Output format for `check` (`text`, `json`, `sarif`) | `text` |
176
179
  | `--output <FILE>` | `-O` | Write `check` output report (e.g. SARIF) to file | |
177
180
  | `--native` | | Force native JVM runner mode on `start` | `false` |
178
- | `--docker` | | Force Docker container mode on `start` | `false` |
181
+ | `--docker` | | Force Docker container mode on `start` or configure ephemeral `mcp-stdio` manifests with `--mcp` | `false` |
179
182
  | `--jar <PATH>` | | Custom path to `quarkus-run.jar` for native mode | Auto-detected |
180
183
  | `--open` | `-o` | Open visual workbench in default browser upon startup | `false` |
181
184
  | `--port <PORT>` | | Workbench HTTP port | `8088` |
package/bin/index.js CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  import * as path from 'node:path';
10
10
  import * as fs from 'node:fs';
11
- import { fileURLToPath } from 'node:url';
11
+ import { fileURLToPath, pathToFileURL } from 'node:url';
12
12
 
13
13
  import * as ui from '../src/ui.js';
14
14
  import {
@@ -17,7 +17,7 @@ import {
17
17
  findCommonPackagePrefix,
18
18
  generateLlmPrompt
19
19
  } from '../src/analyzer.js';
20
- import { installLocalPolicy, installGlobalSkills } from '../src/installer.js';
20
+ import { installLocalPolicy, installLocalSkills, installGlobalSkills } from '../src/installer.js';
21
21
  import { updateLocalPolicy, updateGlobalSkills } from '../src/updater.js';
22
22
  import { upgradeProject } from '../src/upgrader.js';
23
23
  import {
@@ -60,6 +60,7 @@ ${ui.colors.bold}COMMANDS:${ui.colors.reset}
60
60
  check Audit repository against Clean Architecture policy rules
61
61
  update Update existing policy with newly discovered packages and refresh skills
62
62
  upgrade Upgrade legacy .uml-viewer configuration to .archlens
63
+ skills Install Archlens skills via npx skills (local project or -g global)
63
64
  global Install Archlens skills globally for AI coding assistants
64
65
  prompt Export Clean Architecture LLM Refactoring Prompt Dossier
65
66
  mcp Launch Model Context Protocol (MCP) stdio server for AI assistants
@@ -76,10 +77,12 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
76
77
  --server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
77
78
  --port <PORT> Workbench HTTP port (default: 8088)
78
79
  --native Prefer running workbench via native Java Quarkus runner (default)
79
- --docker Force running workbench via Docker container
80
+ --docker Force Docker container mode on start or ephemeral MCP STDIO with --mcp
80
81
  --jar <PATH> Custom path to Archlens Quarkus runner JAR
81
82
  -o, --open Open visual workbench in default browser upon startup
82
83
  -m, --mcp Auto-configure MCP server manifests in AI clients (Claude, Antigravity, Cursor)
84
+ --skills Install Archlens skills into target project via npx skills
85
+ --agent <AGENT> Target specific coding agent(s) when installing skills (e.g. claude-code,cursor)
83
86
  -c, --copy Copy LLM prompt output directly to system clipboard
84
87
  -g, --global Install or update skill globally in ~/.claude and ~/.gemini
85
88
  -u, --update Update mode: sync new packages into existing policy
@@ -98,6 +101,9 @@ ${ui.colors.bold}EXAMPLES:${ui.colors.reset}
98
101
  ${ui.colors.dim}# Configure MCP manifests across Claude, Antigravity, and Cursor:${ui.colors.reset}
99
102
  npx @fmatar/archlens-skill --mcp
100
103
 
104
+ ${ui.colors.dim}# Configure ephemeral Docker MCP container (docker run -i --rm):${ui.colors.reset}
105
+ npx @fmatar/archlens-skill --mcp --docker
106
+
101
107
  ${ui.colors.dim}# Launch MCP stdio bridge server for AI coding assistants:${ui.colors.reset}
102
108
  npx @fmatar/archlens-skill mcp
103
109
 
@@ -124,7 +130,7 @@ ${ui.colors.bold}EXAMPLES:${ui.colors.reset}
124
130
  `);
125
131
  }
126
132
 
127
- function parseArgs(args) {
133
+ export function parseArgs(args) {
128
134
  const parsed = {
129
135
  command: null,
130
136
  path: '.',
@@ -137,6 +143,8 @@ function parseArgs(args) {
137
143
  copy: false,
138
144
  prompt: false,
139
145
  global: false,
146
+ skills: false,
147
+ agent: null,
140
148
  update: false,
141
149
  upgrade: false,
142
150
  mcp: false,
@@ -170,6 +178,10 @@ function parseArgs(args) {
170
178
  parsed.port = args[++i] || '8088';
171
179
  } else if (arg === '--mcp' || arg === '-m') {
172
180
  parsed.mcp = true;
181
+ } else if (arg === '--skills') {
182
+ parsed.skills = true;
183
+ } else if (arg === '--agent') {
184
+ parsed.agent = args[++i] || null;
173
185
  } else if (arg === '--global' || arg === '-g') {
174
186
  parsed.global = true;
175
187
  } else if (arg === '--update' || arg === '-u') {
@@ -223,7 +235,7 @@ function parseArgs(args) {
223
235
 
224
236
  if (positional.length > 0) {
225
237
  const cmd = positional[0].toLowerCase();
226
- if (['init', 'start', 'update', 'upgrade', 'global', 'prompt', 'mcp', 'check', 'help', 'version'].includes(cmd)) {
238
+ if (['init', 'start', 'update', 'upgrade', 'skills', 'global', 'prompt', 'mcp', 'check', 'help', 'version'].includes(cmd)) {
227
239
  parsed.command = cmd;
228
240
  } else if (!parsed.title && !parsed.path) {
229
241
  parsed.path = positional[0];
@@ -235,6 +247,7 @@ function parseArgs(args) {
235
247
  if (parsed.command === 'start') parsed.start = true;
236
248
  if (parsed.command === 'update') parsed.update = true;
237
249
  if (parsed.command === 'upgrade') parsed.upgrade = true;
250
+ if (parsed.command === 'skills') parsed.skills = true;
238
251
  if (parsed.command === 'global') parsed.global = true;
239
252
  if (parsed.command === 'prompt') parsed.prompt = true;
240
253
  if (parsed.command === 'check') parsed.check = true;
@@ -243,7 +256,9 @@ function parseArgs(args) {
243
256
  return parsed;
244
257
  }
245
258
 
246
- async function runInteractive(options) {
259
+ async function runInteractive(options, deps = {}) {
260
+ const askChoice = deps.askChoice || ui.askChoice;
261
+ const askQuestion = deps.askQuestion || ui.askQuestion;
247
262
  ui.banner();
248
263
 
249
264
  const targetRoot = path.resolve(options.path || '.');
@@ -292,12 +307,11 @@ async function runInteractive(options) {
292
307
  }
293
308
  ];
294
309
 
295
- const selectedAction = await ui.askChoice('Select installation action:', choices);
310
+ const selectedAction = await askChoice('Select installation action:', choices);
296
311
 
297
312
  let customTitle = options.title;
298
313
  if (['init_local', 'both'].includes(selectedAction) && !customTitle) {
299
- const defaultTitle = ui.colors.dim + path.basename(targetRoot) + ui.colors.reset;
300
- customTitle = await ui.askQuestion('Project display title', path.basename(targetRoot));
314
+ customTitle = await askQuestion('Project display title', path.basename(targetRoot));
301
315
  }
302
316
 
303
317
  const execOptions = {
@@ -347,7 +361,8 @@ function executeMcpInstall(options) {
347
361
 
348
362
  function executeLocalInit(targetRoot, options) {
349
363
  ui.step(1, 2, 'Scaffolding Clean Architecture Policy');
350
- const result = installLocalPolicy(targetRoot, options);
364
+ // Orchestration of --mcp and --skills is handled explicitly in main() with UI progress logging
365
+ const result = installLocalPolicy(targetRoot, { ...options, mcp: false, skills: false });
351
366
 
352
367
  if (result.policyCreated) {
353
368
  ui.success(`Created policy file: ${path.relative(targetRoot, result.policyFile)}`);
@@ -377,7 +392,7 @@ function executeGlobalInstall(options) {
377
392
  const result = installGlobalSkills(options);
378
393
 
379
394
  if (result.method === 'skills-cli') {
380
- ui.success(`Installed Archlens skills across AI agents via vercel-labs/skills CLI${modeSuffix}`);
395
+ ui.success(`Installed Archlens skills across AI agents via npx skills${modeSuffix}`);
381
396
  } else if (result.installed.length === 0) {
382
397
  ui.warn('No active AI agent directories found (~/.claude, ~/.gemini). Use --force to deploy anyway.');
383
398
  } else {
@@ -386,8 +401,21 @@ function executeGlobalInstall(options) {
386
401
  }
387
402
  }
388
403
 
389
- console.log(`\n ${ui.colors.dim}💡 Tip: You can also manage Archlens skills with the open Skills CLI:${ui.colors.reset}`);
390
- console.log(` ${ui.colors.cyan}npx skills add fmatar/archlens${ui.colors.reset}\n`);
404
+ console.log(`\n ${ui.colors.dim}💡 Tip: You can also manage Archlens skills directly with npx skills:${ui.colors.reset}`);
405
+ console.log(` ${ui.colors.cyan}npx skills add fmatar/archlens --all -y${ui.colors.reset}\n`);
406
+ }
407
+
408
+ function executeLocalSkillsInstall(targetRoot, options) {
409
+ const modeSuffix = options.dryRun ? ' (dry run)' : '';
410
+ ui.step(2, 2, `Deploying AI Assistant Skills in Project via npx skills${modeSuffix}`);
411
+ const result = installLocalSkills(targetRoot, options);
412
+ if (result.method === 'skills-cli') {
413
+ ui.success(`Installed Archlens skills in ${targetRoot} via npx skills${modeSuffix}`);
414
+ } else {
415
+ for (const inst of result.installed) {
416
+ ui.success(`Installed skill for ${inst.agent}: ${inst.path}${modeSuffix}`);
417
+ }
418
+ }
391
419
  }
392
420
 
393
421
  function executeUpgrade(targetRoot, options) {
@@ -461,25 +489,29 @@ function copyToSystemClipboard(text) {
461
489
  }
462
490
  }
463
491
 
464
- async function main() {
465
- const options = parseArgs(process.argv.slice(2));
492
+ export async function main(rawArgs = process.argv.slice(2), deps = {}) {
493
+ const exit = deps.exit || ((code) => process.exit(code));
494
+ const mcpStarter = deps.startMcpStdioServer || startMcpStdioServer;
495
+ const startExecutor = deps.executeStart || executeStart;
496
+ const copyClipboard = deps.copyToSystemClipboard || copyToSystemClipboard;
497
+ const options = { ...parseArgs(rawArgs), ...(deps.options || {}) };
466
498
  const targetRoot = path.resolve(options.path || '.');
467
499
 
468
500
  if (options.help) {
469
501
  printHelp();
470
- process.exit(0);
502
+ return exit(0);
471
503
  }
472
504
 
473
505
  if (options.version) {
474
506
  console.log(getPackageVersion());
475
- process.exit(0);
507
+ return exit(0);
476
508
  }
477
509
 
478
510
  if (options.command === 'prompt' || options.prompt) {
479
511
  try {
480
512
  const dossier = await generateLlmPrompt(targetRoot, options);
481
513
  if (options.copy) {
482
- const ok = copyToSystemClipboard(dossier);
514
+ const ok = copyClipboard(dossier);
483
515
  if (ok) {
484
516
  ui.success('Clean Architecture Refactoring Dossier copied to system clipboard!');
485
517
  } else {
@@ -488,10 +520,10 @@ async function main() {
488
520
  } else {
489
521
  process.stdout.write(dossier);
490
522
  }
491
- process.exit(0);
523
+ return exit(0);
492
524
  } catch (err) {
493
525
  ui.error(err.message || String(err));
494
- process.exit(1);
526
+ return exit(1);
495
527
  }
496
528
  }
497
529
 
@@ -503,7 +535,7 @@ async function main() {
503
535
  const report = await checkArchitecture(targetRoot, options);
504
536
  if (report.error) {
505
537
  ui.error(report.error);
506
- process.exit(1);
538
+ return exit(1);
507
539
  }
508
540
 
509
541
  let formattedOutput = null;
@@ -536,7 +568,7 @@ async function main() {
536
568
  if (!options.output) {
537
569
  process.stdout.write(formattedOutput + '\n');
538
570
  }
539
- process.exit(report.passed ? 0 : 1);
571
+ return exit(report.passed ? 0 : 1);
540
572
  }
541
573
 
542
574
  console.log(`\n ${ui.colors.bold}Architecture Governance Results (${report.projectTitle}):${ui.colors.reset}`);
@@ -592,7 +624,7 @@ async function main() {
592
624
  options.detectCycles ? ', 0 package cycles' : ''
593
625
  }${report.screamingThreshold !== null ? `, screaming score ${report.screaming.score.toFixed(2)} >= ${report.screamingThreshold.toFixed(2)}` : ''}${report.fitnessThreshold !== null && !isNaN(report.fitnessThreshold) ? `, fitness ${(report.fitness.fitnessScore * 100).toFixed(0)}% >= ${(report.fitnessThreshold * 100).toFixed(0)}%` : ''}).`
594
626
  );
595
- process.exit(0);
627
+ return exit(0);
596
628
  } else {
597
629
  ui.error(
598
630
  `Clean Architecture Gate FAILED (${report.violationsCount} violation(s), ${
@@ -620,18 +652,18 @@ async function main() {
620
652
  console.log(`\n Architectural Fitness Invariant Violation:`);
621
653
  console.log(` Fitness Score ${(report.fitness.fitnessScore * 100).toFixed(0)}% [Grade ${report.fitness.grade}] is below required threshold ${(report.fitnessThreshold * 100).toFixed(0)}%.`);
622
654
  }
623
- process.exit(1);
655
+ return exit(1);
624
656
  }
625
657
  } catch (err) {
626
658
  ui.error(err.message || String(err));
627
- process.exit(1);
659
+ return exit(1);
628
660
  }
629
661
  }
630
662
 
631
663
  if (options.command === 'mcp') {
632
- startMcpStdioServer({
633
- version: getPackageVersion(),
634
- ...options
664
+ mcpStarter({
665
+ ...options,
666
+ version: getPackageVersion()
635
667
  });
636
668
  return;
637
669
  }
@@ -641,7 +673,7 @@ async function main() {
641
673
  const port = options.port || '8088';
642
674
  const targetUrl = options.serverUrl || (port === '8088' ? DEFAULT_SERVER_URL : `http://localhost:${port}`);
643
675
  ui.info(`Checking Archlens Workbench server on ${targetUrl}...`);
644
- const status = await executeStart(options);
676
+ const status = await startExecutor(options);
645
677
  if (status.status === 'running') {
646
678
  if (status.spawned) {
647
679
  if (status.mode === 'jar') {
@@ -659,22 +691,23 @@ async function main() {
659
691
  console.log(` npx @fmatar/archlens-skill prompt\n`);
660
692
  } else {
661
693
  ui.error(status.message || 'Failed to start Archlens server.');
662
- process.exit(1);
694
+ return exit(1);
663
695
  }
664
- process.exit(0);
696
+ return exit(0);
665
697
  } catch (err) {
666
698
  ui.error(err.message || String(err));
667
- process.exit(1);
699
+ return exit(1);
668
700
  }
669
701
  }
670
702
 
703
+ const ttyAvailable = deps.isTTY !== undefined ? Boolean(deps.isTTY) : Boolean(process.stdin.isTTY && process.stdout.isTTY);
671
704
  const isInteractive = Boolean(
672
- process.stdin.isTTY &&
673
- process.stdout.isTTY &&
705
+ ttyAvailable &&
674
706
  !options.yes &&
675
707
  !options.dryRun &&
676
708
  !options.command &&
677
709
  !options.start &&
710
+ !options.skills &&
678
711
  !options.global &&
679
712
  !options.update &&
680
713
  !options.upgrade &&
@@ -684,10 +717,10 @@ async function main() {
684
717
 
685
718
  if (isInteractive) {
686
719
  try {
687
- await runInteractive(options);
720
+ await (deps.runInteractive || ((opts) => runInteractive(opts, deps)))(options);
688
721
  } catch (err) {
689
722
  ui.error(err.message || String(err));
690
- process.exit(1);
723
+ return exit(1);
691
724
  }
692
725
  return;
693
726
  }
@@ -698,13 +731,25 @@ async function main() {
698
731
  executeUpgrade(targetRoot, options);
699
732
  } else if (options.update) {
700
733
  executeUpdate(targetRoot, options);
734
+ } else if (options.command === 'skills' || (options.skills && options.global && !options.yes)) {
735
+ if (options.global) {
736
+ executeGlobalInstall(options);
737
+ } else {
738
+ executeLocalSkillsInstall(targetRoot, options);
739
+ }
701
740
  } else if (options.global && !options.command) {
702
741
  executeGlobalInstall(options);
703
742
  executeLocalInit(targetRoot, options);
743
+ if (options.skills) {
744
+ executeLocalSkillsInstall(targetRoot, options);
745
+ }
704
746
  } else if (options.global || options.command === 'global') {
705
747
  executeGlobalInstall(options);
706
748
  } else {
707
749
  executeLocalInit(targetRoot, options);
750
+ if (options.skills) {
751
+ executeLocalSkillsInstall(targetRoot, options);
752
+ }
708
753
  }
709
754
 
710
755
  if (options.mcp) {
@@ -716,8 +761,10 @@ async function main() {
716
761
  }
717
762
  } catch (err) {
718
763
  ui.error(err.message || String(err));
719
- process.exit(1);
764
+ return exit(1);
720
765
  }
721
766
  }
722
767
 
723
- main();
768
+ if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
769
+ main();
770
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fmatar/archlens-skill",
3
- "version": "1.1.1",
3
+ "version": "1.1.2-dev.65",
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",
@@ -20,6 +20,7 @@
20
20
  "node": ">=18.0.0"
21
21
  },
22
22
  "scripts": {
23
+ "prepack": "node ../scripts/sync-skills.js --if-repo",
23
24
  "test": "node --test test/*.test.js",
24
25
  "start": "node bin/index.js"
25
26
  },
@@ -3,9 +3,14 @@ name: archlens
3
3
  description: >-
4
4
  Polyglot Clean Architecture governance, dynamic visual workbench companion,
5
5
  policy scaffolding, mailbox refactoring protocols, LLM prompt dossiers,
6
- and Model Context Protocol (MCP) diagnostics for Archlens.
7
- version: 1.2.0
6
+ and Model Context Protocol (MCP) diagnostics for Archlens. Use when auditing
7
+ layer boundaries, inverting outward dependencies (DIP), or running Archlens.
8
8
  license: Apache-2.0
9
+ compatibility: "Node.js >= 18"
10
+ version: 1.1.2-dev.65
11
+ metadata:
12
+ author: fmatar
13
+ version: "1.1.2-dev.65"
9
14
  ---
10
15
 
11
16
  # Archlens — Clean Architecture Governance & Workbench Companion
@@ -53,7 +58,7 @@ Archlens models codebases as concentric circular rings. Source code dependencies
53
58
  Install Archlens across 15+ coding agents (Antigravity, Claude Code, Cursor, Gemini CLI) via `skills.sh`:
54
59
  ```bash
55
60
  # Add Archlens to your active agent skills library:
56
- npx skills add fmatar/archlens
61
+ npx skills add fmatar/archlens --all -y
57
62
  ```
58
63
 
59
64
  Or execute directly on demand via NPX:
@@ -83,6 +88,9 @@ npx @fmatar/archlens-skill upgrade --path .
83
88
  # Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
84
89
  npx @fmatar/archlens-skill --mcp
85
90
 
91
+ # Auto-configure pure ephemeral Docker MCP container (docker run -i --rm -e QUARKUS_PROFILE=mcp-stdio):
92
+ npx @fmatar/archlens-skill --mcp --docker
93
+
86
94
  # Launch Model Context Protocol (MCP) stdio server:
87
95
  npx @fmatar/archlens-skill mcp
88
96
  ```
@@ -1,8 +1,15 @@
1
1
  ---
2
2
  name: archlens-install-policy
3
- description: Inspects any target codebase, detects programming languages and packages, and scaffolds an Archlens Clean Architecture policy (.archlens/policy.json) and agent workbench companion integration.
4
- version: 1.1.1
3
+ description: >-
4
+ Inspects any target codebase, detects programming languages and packages, and
5
+ scaffolds an Archlens Clean Architecture policy (.archlens/policy.json) and
6
+ agent workbench companion integration. Use when setting up or upgrading Archlens.
5
7
  license: Apache-2.0
8
+ compatibility: "Node.js >= 18"
9
+ version: 1.1.2-dev.65
10
+ metadata:
11
+ author: fmatar
12
+ version: "1.1.2-dev.65"
6
13
  ---
7
14
 
8
15
  # Archlens Policy & Companion Installer (`archlens-install-policy`)
@@ -4,8 +4,12 @@ description: >-
4
4
  Companion agent for the Clean Architecture Dynamic UML Workbench.
5
5
  Monitors .archlens/ and .uml-viewer/ mailbox queues, processes architectural refactoring requests,
6
6
  evaluates Clean Architecture violations, runs builds and tests, and signals live diagram reloads.
7
- version: 1.2.0
8
7
  license: Apache-2.0
8
+ compatibility: "Node.js >= 18"
9
+ version: 1.1.2-dev.65
10
+ metadata:
11
+ author: fmatar
12
+ version: "1.1.2-dev.65"
9
13
  ---
10
14
 
11
15
  # UML Workbench Companion Skill (`uml-workbench-companion`)
package/src/installer.js CHANGED
@@ -120,6 +120,11 @@ export function installLocalPolicy(projectRoot, options = {}) {
120
120
  mcpResult = installMcpConfigs({ path: root, ...options });
121
121
  }
122
122
 
123
+ let skillsResult = null;
124
+ if (options.skills) {
125
+ skillsResult = installLocalSkills(root, options);
126
+ }
127
+
123
128
  return {
124
129
  targetDir: root,
125
130
  archlensDir: targetDir,
@@ -130,22 +135,91 @@ export function installLocalPolicy(projectRoot, options = {}) {
130
135
  policyData,
131
136
  companionFiles: updatedCompanions,
132
137
  mcpResult,
138
+ skillsResult,
133
139
  dryRun
134
140
  };
135
141
  }
136
142
 
137
- export function getGlobalSkillDirectories(home = os.homedir()) {
138
- const bundledSkillsDir = path.resolve(__dirname, '..', 'skills');
139
- let skillNames = ['archlens-install-policy'];
140
- if (fs.existsSync(bundledSkillsDir)) {
141
- try {
142
- skillNames = fs.readdirSync(bundledSkillsDir, { withFileTypes: true })
143
- .filter((d) => d.isDirectory())
144
- .map((d) => d.name);
145
- } catch {
146
- // fallback
143
+ function parseListOption(val) {
144
+ if (!val) return [];
145
+ if (Array.isArray(val)) return val.map((v) => String(v).trim()).filter(Boolean);
146
+ if (typeof val === 'string') {
147
+ return val
148
+ .split(',')
149
+ .map((v) => v.trim())
150
+ .filter(Boolean);
151
+ }
152
+ return [];
153
+ }
154
+
155
+ export function buildSkillsCliArgs(options = {}) {
156
+ const packageRoot = options.sourceDir || path.resolve(__dirname, '..');
157
+ const args = ['--yes', 'skills', 'add', packageRoot];
158
+
159
+ const selectedSkills = parseListOption(options.skill || options.skillsList);
160
+ if (selectedSkills.length > 0) {
161
+ for (const s of selectedSkills) {
162
+ args.push('--skill', s);
147
163
  }
164
+ } else {
165
+ args.push('--all');
166
+ }
167
+
168
+ if (options.global) {
169
+ args.push('-g');
170
+ }
171
+
172
+ const agents = parseListOption(options.agent || options.agents);
173
+ for (const a of agents) {
174
+ args.push('--agent', a);
175
+ }
176
+
177
+ if (!options.symlink) {
178
+ args.push('--copy');
179
+ }
180
+ args.push('-y');
181
+ return args;
182
+ }
183
+
184
+ function runSkillsCliInstall(options = {}) {
185
+ const packageRoot = options.skillsSource || path.resolve(__dirname, '..');
186
+ const spawnFn = options.spawnSync || spawnSync;
187
+ const isWin = process.platform === 'win32';
188
+ const npxCmd = isWin ? 'npx.cmd' : 'npx';
189
+ const args = buildSkillsCliArgs({ ...options, sourceDir: packageRoot });
190
+
191
+ const proc = spawnFn(npxCmd, args, {
192
+ cwd: options.cwd || process.cwd(),
193
+ encoding: 'utf8',
194
+ timeout: options.timeoutMs || 60000,
195
+ stdio: ['ignore', 'pipe', 'pipe']
196
+ });
197
+
198
+ if (proc && proc.status === 0) {
199
+ return {
200
+ ok: true,
201
+ sourceDir: packageRoot,
202
+ output: proc.stdout || ''
203
+ };
148
204
  }
205
+ return { ok: false, error: proc?.stderr || '' };
206
+ }
207
+
208
+ function listBundledSkillNames(bundledSkillsDir) {
209
+ if (!fs.existsSync(bundledSkillsDir)) return ['archlens', 'archlens-install-policy', 'uml-workbench-companion'];
210
+ try {
211
+ return fs
212
+ .readdirSync(bundledSkillsDir, { withFileTypes: true })
213
+ .filter((d) => d.isDirectory())
214
+ .map((d) => d.name);
215
+ } catch {
216
+ return ['archlens-install-policy'];
217
+ }
218
+ }
219
+
220
+ export function getGlobalSkillDirectories(home = os.homedir()) {
221
+ const bundledSkillsDir = path.resolve(__dirname, '..', 'skills');
222
+ const skillNames = listBundledSkillNames(bundledSkillsDir);
149
223
 
150
224
  const agents = [
151
225
  {
@@ -176,33 +250,92 @@ export function getGlobalSkillDirectories(home = os.homedir()) {
176
250
  return results;
177
251
  }
178
252
 
253
+ export function installLocalSkills(projectRoot, options = {}) {
254
+ const root = path.resolve(projectRoot);
255
+ const dryRun = Boolean(options.dryRun);
256
+ const bundledSkillsRoot = path.resolve(__dirname, '..', 'skills');
257
+
258
+ if (options.preferVercelSkills !== false && !dryRun) {
259
+ try {
260
+ const cliRes = runSkillsCliInstall({
261
+ ...options,
262
+ global: false,
263
+ cwd: root
264
+ });
265
+ if (cliRes.ok) {
266
+ return {
267
+ sourceDir: cliRes.sourceDir,
268
+ method: 'skills-cli',
269
+ output: cliRes.output,
270
+ installed: [
271
+ {
272
+ agent: options.agent || 'Detected Project Agents (via npx skills)',
273
+ skill: 'archlens-suite',
274
+ path: root
275
+ }
276
+ ],
277
+ dryRun: false
278
+ };
279
+ }
280
+ } catch {
281
+ // Offline fallback to standard .agents/skills directory
282
+ }
283
+ }
284
+
285
+ const installed = [];
286
+ for (const skillName of listBundledSkillNames(bundledSkillsRoot)) {
287
+ const sourceSkillDir = path.join(bundledSkillsRoot, skillName);
288
+ const targetSkillDir = path.join(root, '.agents', 'skills', skillName);
289
+ if (fs.existsSync(sourceSkillDir)) {
290
+ if (!dryRun) {
291
+ fs.mkdirSync(targetSkillDir, { recursive: true });
292
+ copyDirectorySync(sourceSkillDir, targetSkillDir);
293
+ }
294
+ installed.push({
295
+ agent: 'Project Agents (.agents/skills)',
296
+ skill: skillName,
297
+ path: targetSkillDir
298
+ });
299
+ }
300
+ }
301
+
302
+ return {
303
+ sourceDir: bundledSkillsRoot,
304
+ method: 'direct-copy',
305
+ installed,
306
+ dryRun
307
+ };
308
+ }
309
+
179
310
  export function installGlobalSkills(options = {}) {
180
311
  const dryRun = Boolean(options.dryRun);
181
312
  const force = Boolean(options.force);
182
313
  const bundledSkillsRoot = path.resolve(__dirname, '..', 'skills');
183
314
 
184
- // Attempt using vercel-labs/skills CLI if available and not explicitly disabled
185
- if (!options.homedir && options.preferVercelSkills !== false && !dryRun) {
315
+ // Primary path: delegate to `npx skills add <cliPackageRoot> --all -g --copy -y`
316
+ if ((options.preferVercelSkills ?? !options.homedir) && !dryRun) {
186
317
  try {
187
- const isWin = process.platform === 'win32';
188
- const npxCmd = isWin ? 'npx.cmd' : 'npx';
189
- // Install skills package from GitHub or local bundled skills via `npx skills add`
190
- const skillsProc = spawnSync(npxCmd, ['--yes', 'skills', 'add', bundledSkillsRoot, '-g', '--copy', '-y'], {
191
- encoding: 'utf8',
192
- timeout: 15000,
193
- stdio: ['ignore', 'pipe', 'pipe']
318
+ const cliRes = runSkillsCliInstall({
319
+ ...options,
320
+ global: true
194
321
  });
195
- if (skillsProc.status === 0) {
322
+ if (cliRes.ok) {
196
323
  return {
197
- sourceDir: bundledSkillsRoot,
324
+ sourceDir: cliRes.sourceDir,
198
325
  method: 'skills-cli',
199
- output: skillsProc.stdout,
200
- installed: [{ agent: 'All Supported Agents (via vercel-labs/skills)', skill: 'archlens-suite', path: 'global' }],
326
+ output: cliRes.output,
327
+ installed: [
328
+ {
329
+ agent: options.agent || 'All Supported Agents (via npx skills)',
330
+ skill: 'archlens-suite',
331
+ path: 'global'
332
+ }
333
+ ],
201
334
  dryRun: false
202
335
  };
203
336
  }
204
337
  } catch {
205
- // Fallback seamlessly to native direct directory installation
338
+ // Fallback seamlessly when offline / air-gapped
206
339
  }
207
340
  }
208
341
 
@@ -210,7 +343,6 @@ export function installGlobalSkills(options = {}) {
210
343
  const installed = [];
211
344
 
212
345
  for (const dest of destinations) {
213
- // Install if parent agent directory exists or if force flag is enabled
214
346
  const agentHomeDir = path.dirname(dest.baseDir);
215
347
  const shouldInstall = force || fs.existsSync(agentHomeDir);
216
348
  const sourceSkillDir = path.join(bundledSkillsRoot, dest.skill);
@@ -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'],
@@ -419,19 +462,26 @@ export function installMcpConfigs(options = {}) {
419
462
  }
420
463
  }
421
464
 
465
+ const entryOptions = {
466
+ ...options,
467
+ path: projectRoot,
468
+ homedir,
469
+ scope: target.scope
470
+ };
471
+
422
472
  if (target.id === 'vscode') {
423
473
  if (!manifest.servers || typeof manifest.servers !== 'object') {
424
474
  manifest.servers = {};
425
475
  }
426
476
  manifest.servers.archlens = {
427
477
  type: 'stdio',
428
- ...getMcpManifestEntry(serverUrl)
478
+ ...getMcpManifestEntry(serverUrl, entryOptions)
429
479
  };
430
480
  } else {
431
481
  if (!manifest.mcpServers || typeof manifest.mcpServers !== 'object') {
432
482
  manifest.mcpServers = {};
433
483
  }
434
- manifest.mcpServers.archlens = getMcpManifestEntry(serverUrl);
484
+ manifest.mcpServers.archlens = getMcpManifestEntry(serverUrl, entryOptions);
435
485
  }
436
486
 
437
487
  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.1';
31
+ return '1.1.2';
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') {
package/src/updater.js CHANGED
@@ -17,14 +17,17 @@ import {
17
17
  import {
18
18
  COMPANION_PROTOCOL_HEADER,
19
19
  getCompanionProtocolBlock,
20
- installGlobalSkills,
21
- getGlobalSkillDirectories
20
+ installGlobalSkills
22
21
  } from './installer.js';
23
22
 
24
23
  export function updateLocalPolicy(projectRoot, options = {}) {
25
24
  const root = path.resolve(projectRoot);
26
25
  const dryRun = Boolean(options.dryRun);
27
26
 
27
+ if (!fs.existsSync(root)) {
28
+ throw new Error(`Target directory does not exist: ${root}`);
29
+ }
30
+
28
31
  const primaryDir = path.join(root, '.archlens');
29
32
  const legacyDir = path.join(root, '.uml-viewer');
30
33
  const primaryPolicy = path.join(primaryDir, 'policy.json');
@@ -45,10 +48,6 @@ export function updateLocalPolicy(projectRoot, options = {}) {
45
48
 
46
49
  const configFile = path.join(targetDir, 'workbench.config.json');
47
50
 
48
- if (!fs.existsSync(root)) {
49
- throw new Error(`Target directory does not exist: ${root}`);
50
- }
51
-
52
51
  const existingPolicy = JSON.parse(fs.readFileSync(policyFile, 'utf8'));
53
52
 
54
53
  const lang = existingPolicy.lang || detectProjectLanguage(root);
@@ -152,20 +151,13 @@ export function updateLocalPolicy(projectRoot, options = {}) {
152
151
  }
153
152
 
154
153
  export function updateGlobalSkills(options = {}) {
155
- const destinations = getGlobalSkillDirectories();
156
- const existingDestinations = destinations.filter((dest) => fs.existsSync(dest.targetDir));
157
-
158
- if (existingDestinations.length === 0) {
159
- // If none installed yet, install to all detected agent environments
160
- return installGlobalSkills(options);
161
- }
162
-
163
154
  const installResult = installGlobalSkills({
164
155
  ...options,
165
156
  force: true
166
157
  });
167
158
 
168
159
  return {
160
+ method: installResult.method,
169
161
  updatedLocations: installResult.installed,
170
162
  dryRun: installResult.dryRun
171
163
  };