@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 +16 -3
- package/package.json +1 -1
- package/skills/archlens/SKILL.md +5 -2
- package/src/analyzer.js +109 -0
- package/src/docker-runner.js +133 -22
- package/src/mcp-server.js +1 -1
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
|
-
|
|
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
|
|
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
|
|
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-
|
|
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",
|
package/skills/archlens/SKILL.md
CHANGED
|
@@ -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
|
|
85
|
-
|
|
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
|
|
package/src/docker-runner.js
CHANGED
|
@@ -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
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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.
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
|
|
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