@fmatar/archlens-skill 0.1.0-Beta-02 → 0.1.0-Beta-04

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/bin/index.js CHANGED
@@ -70,6 +70,9 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
70
70
  --prefix <PKG> Common package prefix (e.g. com.example.app)
71
71
  --server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
72
72
  --port <PORT> Workbench HTTP port (default: 8088)
73
+ --native Prefer running workbench via native Java Quarkus runner (default)
74
+ --docker Force running workbench via Docker container
75
+ --jar <PATH> Custom path to Archlens Quarkus runner JAR
73
76
  -o, --open Open visual workbench in default browser upon startup
74
77
  -m, --mcp Auto-configure MCP server manifests in AI clients (Claude, Antigravity, Cursor)
75
78
  -c, --copy Copy LLM prompt output directly to system clipboard
@@ -202,6 +205,12 @@ function parseArgs(args) {
202
205
  parsed.prefix = args[++i];
203
206
  } else if (arg === '--server-url') {
204
207
  parsed.serverUrl = args[++i] || 'http://localhost:8088';
208
+ } else if (arg === '--docker') {
209
+ parsed.preferDocker = true;
210
+ } else if (arg === '--native') {
211
+ parsed.preferNative = true;
212
+ } else if (arg === '--jar') {
213
+ parsed.jarPath = args[++i];
205
214
  } else if (!arg.startsWith('-')) {
206
215
  positional.push(arg);
207
216
  }
@@ -618,17 +627,21 @@ async function main() {
618
627
  const status = await executeStart(options);
619
628
  if (status.status === 'running') {
620
629
  if (status.spawned) {
621
- ui.success(`Archlens container (${DEFAULT_CONTAINER_NAME}) launched successfully!`);
630
+ if (status.mode === 'jar') {
631
+ ui.success(`Archlens native runner (${status.jarPath || 'JAR'}) launched successfully!`);
632
+ } else {
633
+ ui.success(`Archlens container (${DEFAULT_CONTAINER_NAME}) launched successfully!`);
634
+ }
622
635
  } else {
623
636
  ui.success(`Archlens Workbench server is active (${status.version || 'running'}).`);
624
637
  }
625
638
  console.log(`\n ${ui.colors.bold}Workbench URL:${ui.colors.reset} ${ui.colors.cyan}${status.serverUrl}${ui.colors.reset}\n`);
626
639
  } else if (status.status === 'offline') {
627
- ui.warn(status.message || 'Archlens server is offline and Docker daemon is unavailable.');
640
+ ui.warn(status.message || 'Archlens server is offline and neither native runner JAR nor Docker is available.');
628
641
  console.log(`\n ${ui.colors.dim}To run offline architecture analysis:${ui.colors.reset}`);
629
642
  console.log(` npx @fmatar/archlens-skill prompt\n`);
630
643
  } else {
631
- ui.error(status.message || 'Failed to start Archlens container.');
644
+ ui.error(status.message || 'Failed to start Archlens server.');
632
645
  process.exit(1);
633
646
  }
634
647
  process.exit(0);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fmatar/archlens-skill",
3
- "version": "0.1.0-Beta-02",
3
+ "version": "0.1.0-Beta-04",
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",
@@ -81,8 +81,11 @@ npx @fmatar/archlens-skill mcp
81
81
  ### Launching the Workbench & Auto-Resurrection
82
82
  When the user asks to start Archlens, launch the studio, or open the visual workbench:
83
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.
84
+ 2. The CLI inspects whether the server is active on `http://localhost:8088`. If offline, it automatically auto-resurrects:
85
+ - **Native Java Runner (Default)**: If Java 21+ and a runner JAR (`quarkus-run.jar` in `~/.archlens/`, project `target/`, or via `--jar <PATH>`) are detected, it launches the native JVM server in ~0.5s with bare-metal filesystem speed.
86
+ - **Docker Container (Fallback)**: If Java or a local runner is absent, it automatically starts or creates the `archlens-server` Docker container.
87
+ - Use `--docker` to force Docker mode, or `--native` to force native mode.
88
+ 3. When using MCP tools (`inspectArchitecture`, `exportLlmDossier`), the stdio bridge also auto-resurrects the server if offline.
86
89
 
87
90
  ---
88
91
 
package/src/analyzer.js CHANGED
@@ -47,6 +47,79 @@ export function detectProjectLanguage(projectRoot) {
47
47
  return 'java';
48
48
  }
49
49
 
50
+ function findNestedSourceRoots(dir, lang, depth = 0, maxDepth = 5, results = []) {
51
+ if (depth > maxDepth || !fs.existsSync(dir)) {
52
+ return results;
53
+ }
54
+
55
+ const skipDirs = new Set([
56
+ '.git',
57
+ 'node_modules',
58
+ 'target',
59
+ 'build',
60
+ '.gradle',
61
+ '.idea',
62
+ '.vscode',
63
+ '.svelte-kit',
64
+ 'dist',
65
+ 'out',
66
+ 'bin',
67
+ '.archlens',
68
+ '.uml-viewer',
69
+ '.mvn',
70
+ 'infra',
71
+ 'cpln',
72
+ 'assets',
73
+ 'screenshots',
74
+ 'docs'
75
+ ]);
76
+
77
+ try {
78
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
79
+ for (const entry of entries) {
80
+ if (!entry.isDirectory() || skipDirs.has(entry.name) || entry.name.startsWith('.')) {
81
+ continue;
82
+ }
83
+
84
+ const fullPath = path.join(dir, entry.name);
85
+
86
+ if (lang === 'java' && fullPath.endsWith(path.join('src', 'main', 'java'))) {
87
+ results.push(fullPath);
88
+ continue;
89
+ }
90
+ if (
91
+ lang === 'kotlin' &&
92
+ (fullPath.endsWith(path.join('src', 'main', 'kotlin')) ||
93
+ fullPath.endsWith(path.join('src', 'main', 'java')))
94
+ ) {
95
+ results.push(fullPath);
96
+ continue;
97
+ }
98
+ if ((lang === 'typescript' || lang === 'javascript') && entry.name === 'src') {
99
+ results.push(fullPath);
100
+ continue;
101
+ }
102
+ if (lang === 'python' && (entry.name === 'src' || entry.name === 'app')) {
103
+ results.push(fullPath);
104
+ continue;
105
+ }
106
+ if (
107
+ lang === 'go' &&
108
+ (entry.name === 'pkg' || entry.name === 'internal' || entry.name === 'cmd')
109
+ ) {
110
+ results.push(fullPath);
111
+ continue;
112
+ }
113
+
114
+ findNestedSourceRoots(fullPath, lang, depth + 1, maxDepth, results);
115
+ }
116
+ } catch {
117
+ // Gracefully handle unreadable directories
118
+ }
119
+
120
+ return results;
121
+ }
122
+
50
123
  export function detectSourceRoot(projectRoot, lang) {
51
124
  const root = path.resolve(projectRoot);
52
125
 
@@ -64,12 +137,48 @@ export function detectSourceRoot(projectRoot, lang) {
64
137
  const candidates = candidateMap[lang] || ['src', '.'];
65
138
 
66
139
  for (const cand of candidates) {
140
+ if (cand === '.') continue;
67
141
  const p = path.join(root, cand);
68
142
  if (fs.existsSync(p) && fs.statSync(p).isDirectory()) {
69
143
  return cand;
70
144
  }
71
145
  }
72
146
 
147
+ // Multi-module dynamic discovery if standard candidates are not found
148
+ const nested = findNestedSourceRoots(root, lang);
149
+ if (nested.length > 0) {
150
+ const ext =
151
+ lang === 'java'
152
+ ? '.java'
153
+ : lang === 'kotlin'
154
+ ? '.kt'
155
+ : lang === 'typescript'
156
+ ? '.ts'
157
+ : lang === 'python'
158
+ ? '.py'
159
+ : '';
160
+ const ranked = nested.map((dir) => {
161
+ const rel = path.relative(root, dir).replace(/\\/g, '/');
162
+ const files = ext
163
+ ? findMatchingFiles(dir, (f) => f.endsWith(ext), 100)
164
+ : [];
165
+ let score = files.length;
166
+ const lower = rel.toLowerCase();
167
+ if (lower.includes('api')) score += 15;
168
+ if (lower.includes('backend') || lower.includes('server')) score += 10;
169
+ if (lower.includes('core') || lower.includes('app')) score += 5;
170
+ return { rel, score };
171
+ });
172
+ ranked.sort((a, b) => b.score - a.score);
173
+ if (ranked[0] && ranked[0].rel) {
174
+ return ranked[0].rel;
175
+ }
176
+ }
177
+
178
+ if (candidates.includes('.')) {
179
+ return '.';
180
+ }
181
+
73
182
  return 'src';
74
183
  }
75
184
 
@@ -4,8 +4,10 @@
4
4
  * Zero external dependencies.
5
5
  */
6
6
 
7
- import { spawnSync, execSync } from 'node:child_process';
7
+ import { spawn, spawnSync, execSync } from 'node:child_process';
8
8
  import * as path from 'node:path';
9
+ import * as fs from 'node:fs';
10
+ import * as os from 'node:os';
9
11
 
10
12
  export const DEFAULT_SERVER_URL = 'http://localhost:8088';
11
13
  export const DEFAULT_DOCKER_IMAGE = 'ghcr.io/fmatar/archlens:latest';
@@ -27,6 +29,86 @@ export async function checkServerHealth(serverUrl = DEFAULT_SERVER_URL, timeoutM
27
29
  }
28
30
  }
29
31
 
32
+ export function isJavaAvailable(customExec = execSync) {
33
+ try {
34
+ customExec('java -version', { stdio: 'pipe', timeout: 3000 });
35
+ return true;
36
+ } catch {
37
+ return false;
38
+ }
39
+ }
40
+
41
+ export function findNativeJar(options = {}, deps = {}) {
42
+ const exists = deps.existsSync || fs.existsSync;
43
+ const homedir = (deps.os && deps.os.homedir) ? deps.os.homedir() : (os.homedir ? os.homedir() : process.env.HOME || '');
44
+ const workspace = path.resolve(options.workspace || options.path || '.');
45
+ const cwd = (deps.process && deps.process.cwd) ? deps.process.cwd() : process.cwd();
46
+
47
+ const candidates = [];
48
+ if (options.jarPath) candidates.push(path.resolve(options.jarPath));
49
+ if (process.env.ARCHLENS_JAR) candidates.push(path.resolve(process.env.ARCHLENS_JAR));
50
+
51
+ if (homedir) {
52
+ candidates.push(path.join(homedir, '.archlens', 'runner', 'quarkus-app', 'quarkus-run.jar'));
53
+ candidates.push(path.join(homedir, '.archlens', 'quarkus-app', 'quarkus-run.jar'));
54
+ candidates.push(path.join(homedir, '.archlens', 'runner', 'archlens-runner.jar'));
55
+ candidates.push(path.join(homedir, '.archlens', 'archlens-runner.jar'));
56
+ }
57
+
58
+ const projectRoots = [workspace];
59
+ if (cwd && cwd !== workspace) {
60
+ projectRoots.push(cwd);
61
+ }
62
+
63
+ for (const root of projectRoots) {
64
+ candidates.push(path.resolve(root, 'target', 'runner-release', 'quarkus-app', 'quarkus-run.jar'));
65
+ candidates.push(path.resolve(root, 'target', 'quarkus-app', 'quarkus-run.jar'));
66
+ candidates.push(path.resolve(root, 'backend', 'target', 'quarkus-app', 'quarkus-run.jar'));
67
+ }
68
+
69
+ for (const candidate of candidates) {
70
+ try {
71
+ if (candidate && exists(candidate)) {
72
+ return candidate;
73
+ }
74
+ } catch {
75
+ // ignore
76
+ }
77
+ }
78
+ return null;
79
+ }
80
+
81
+ export function startNativeJar(jarPath, options = {}, deps = {}) {
82
+ const port = options.port || '8088';
83
+ const customSpawn = deps.spawn || spawn;
84
+
85
+ const jvmArgs = [
86
+ `-Dquarkus.http.port=${port}`,
87
+ '-jar',
88
+ jarPath
89
+ ];
90
+
91
+ if (options.jvmArgs && Array.isArray(options.jvmArgs)) {
92
+ jvmArgs.unshift(...options.jvmArgs);
93
+ }
94
+
95
+ const child = customSpawn('java', jvmArgs, {
96
+ detached: true,
97
+ stdio: 'ignore'
98
+ });
99
+
100
+ if (child && typeof child.unref === 'function') {
101
+ child.unref();
102
+ }
103
+
104
+ return {
105
+ action: 'started_jar',
106
+ mode: 'jar',
107
+ jarPath,
108
+ pid: child ? child.pid : undefined
109
+ };
110
+ }
111
+
30
112
  export function isDockerAvailable(customExec = execSync) {
31
113
  try {
32
114
  customExec('docker info', { stdio: 'pipe', timeout: 3000 });
@@ -102,15 +184,20 @@ export function startContainer(options = {}, deps = {}) {
102
184
  customSpawn('docker', runArgs, { stdio: 'pipe', timeout: 15000 });
103
185
  }
104
186
 
105
- return { action: 'created', containerName };
187
+ return { action: 'created', containerName, mode: 'docker' };
106
188
  }
107
189
 
108
190
  export async function ensureServerRunning(options = {}, deps = {}) {
109
191
  const serverUrl = options.serverUrl || DEFAULT_SERVER_URL;
110
192
  const maxWaitMs = options.maxWaitMs || 5000;
193
+ const preferDocker = Boolean(options.preferDocker || options.dockerOnly);
194
+ const preferNative = options.preferNative !== false && !preferDocker;
111
195
  const spawnDocker = options.spawnDocker !== false;
112
196
 
113
197
  const healthChecker = deps.checkServerHealth || checkServerHealth;
198
+ const javaChecker = deps.isJavaAvailable || isJavaAvailable;
199
+ const jarFinder = deps.findNativeJar || findNativeJar;
200
+ const jarStarter = deps.startNativeJar || startNativeJar;
114
201
  const dockerChecker = deps.isDockerAvailable || isDockerAvailable;
115
202
  const starter = deps.startContainer || startContainer;
116
203
 
@@ -125,26 +212,46 @@ export async function ensureServerRunning(options = {}, deps = {}) {
125
212
  };
126
213
  }
127
214
 
128
- // 2. Fallback check when Docker is disabled or unavailable
129
- if (!spawnDocker || !dockerChecker(deps.execSync || execSync)) {
130
- return {
131
- status: 'offline',
132
- serverUrl,
133
- spawned: false,
134
- message: 'Archlens Quarkus server is unreachable and Docker daemon is unavailable.'
135
- };
215
+ let launchedMode = null;
216
+ let launchedJarPath = null;
217
+
218
+ // 2. Try native JAR first if preferNative is true
219
+ if (preferNative && javaChecker(deps.execSync || execSync)) {
220
+ const jarPath = jarFinder(options, deps);
221
+ if (jarPath) {
222
+ try {
223
+ jarStarter(jarPath, options, deps);
224
+ launchedMode = 'jar';
225
+ launchedJarPath = jarPath;
226
+ } catch {
227
+ // Fall back to Docker if native JAR launch throws
228
+ }
229
+ }
136
230
  }
137
231
 
138
- // 3. Launch Docker container
139
- try {
140
- starter(options, deps);
141
- } catch (err) {
142
- return {
143
- status: 'error',
144
- serverUrl,
145
- spawned: false,
146
- message: `Failed to launch Docker container: ${err.message}`
147
- };
232
+ // 3. Fallback to Docker if native JAR was not launched
233
+ if (!launchedMode) {
234
+ const dockerAvailable = spawnDocker && dockerChecker(deps.execSync || execSync);
235
+ if (dockerAvailable) {
236
+ try {
237
+ starter(options, deps);
238
+ launchedMode = 'docker';
239
+ } catch (err) {
240
+ return {
241
+ status: 'error',
242
+ serverUrl,
243
+ spawned: false,
244
+ message: `Failed to launch Docker container: ${err.message}`
245
+ };
246
+ }
247
+ } else {
248
+ return {
249
+ status: 'offline',
250
+ serverUrl,
251
+ spawned: false,
252
+ message: 'Archlens Quarkus server is unreachable. Neither a native runner JAR (with Java 21+) nor Docker daemon is available.'
253
+ };
254
+ }
148
255
  }
149
256
 
150
257
  // 4. Poll readiness until maxWaitMs
@@ -157,7 +264,9 @@ export async function ensureServerRunning(options = {}, deps = {}) {
157
264
  status: 'running',
158
265
  serverUrl,
159
266
  version: probe.version,
160
- spawned: true
267
+ spawned: true,
268
+ mode: launchedMode,
269
+ jarPath: launchedJarPath
161
270
  };
162
271
  }
163
272
  }
@@ -166,7 +275,9 @@ export async function ensureServerRunning(options = {}, deps = {}) {
166
275
  status: 'starting',
167
276
  serverUrl,
168
277
  spawned: true,
169
- message: 'Archlens container launched; service is warming up.'
278
+ mode: launchedMode,
279
+ jarPath: launchedJarPath,
280
+ message: `Archlens ${launchedMode === 'jar' ? 'native server' : 'container'} launched; service is warming up.`
170
281
  };
171
282
  }
172
283
 
package/src/mcp-server.js CHANGED
@@ -237,7 +237,7 @@ export async function handleMcpMessage(request, options = {}, deps = {}) {
237
237
  },
238
238
  serverInfo: {
239
239
  name: 'archlens-mcp-server',
240
- version: options.version || '0.1.0-Beta-02'
240
+ version: options.version || '0.1.0-Beta-04'
241
241
  }
242
242
  }
243
243
  };