@fmatar/archlens-skill 0.1.0-Beta-11 → 1.1.0
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 +33 -10
- package/bin/index.js +14 -2
- package/llms.txt +17 -3
- package/package.json +1 -1
- package/skills/archlens/SKILL.md +14 -1
- package/src/analyzer.js +135 -0
- package/src/checker.js +179 -20
- package/src/docker-runner.js +108 -5
- package/src/mcp-registry.js +185 -7
- package/src/mcp-server.js +339 -8
package/src/docker-runner.js
CHANGED
|
@@ -11,6 +11,7 @@ import * as os from 'node:os';
|
|
|
11
11
|
|
|
12
12
|
export const DEFAULT_SERVER_URL = 'http://localhost:8088';
|
|
13
13
|
export const DEFAULT_DOCKER_IMAGE = 'ghcr.io/fmatar/archlens:latest';
|
|
14
|
+
export const DEFAULT_DOCKERHUB_IMAGE = 'docker.io/fmatar/archlens:latest';
|
|
14
15
|
export const DEFAULT_CONTAINER_NAME = 'archlens-server';
|
|
15
16
|
|
|
16
17
|
export async function checkServerHealth(serverUrl = DEFAULT_SERVER_URL, timeoutMs = 1500) {
|
|
@@ -38,6 +39,89 @@ export function isJavaAvailable(customExec = execSync) {
|
|
|
38
39
|
}
|
|
39
40
|
}
|
|
40
41
|
|
|
42
|
+
export function getPlatformBinarySuffix(platform = process.platform, arch = process.arch) {
|
|
43
|
+
if (platform === 'darwin') {
|
|
44
|
+
return arch === 'arm64' ? 'macos-arm64' : 'macos-amd64';
|
|
45
|
+
}
|
|
46
|
+
if (platform === 'win32') {
|
|
47
|
+
return 'windows-amd64.exe';
|
|
48
|
+
}
|
|
49
|
+
return arch === 'arm64' ? 'linux-arm64' : 'linux-amd64';
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export function findNativeBinary(options = {}, deps = {}) {
|
|
53
|
+
const exists = deps.existsSync || fs.existsSync;
|
|
54
|
+
const homedir = (deps.os && deps.os.homedir)
|
|
55
|
+
? deps.os.homedir()
|
|
56
|
+
: os.homedir
|
|
57
|
+
? os.homedir()
|
|
58
|
+
: process.env.HOME || '';
|
|
59
|
+
const workspace = path.resolve(options.workspace || options.path || '.');
|
|
60
|
+
const cwd = (deps.process && deps.process.cwd) ? deps.process.cwd() : process.cwd();
|
|
61
|
+
const suffix = getPlatformBinarySuffix(deps.platform || process.platform, deps.arch || process.arch);
|
|
62
|
+
const isWin = (deps.platform || process.platform) === 'win32';
|
|
63
|
+
const runnerName = isWin ? 'archlens-runner.exe' : 'archlens-runner';
|
|
64
|
+
|
|
65
|
+
const candidates = [];
|
|
66
|
+
if (options.binaryPath) candidates.push(path.resolve(options.binaryPath));
|
|
67
|
+
if (process.env.ARCHLENS_BINARY) candidates.push(path.resolve(process.env.ARCHLENS_BINARY));
|
|
68
|
+
|
|
69
|
+
if (homedir) {
|
|
70
|
+
candidates.push(path.join(homedir, '.archlens', 'bin', `archlens-${suffix}`));
|
|
71
|
+
candidates.push(path.join(homedir, '.archlens', 'bin', isWin ? 'archlens.exe' : 'archlens'));
|
|
72
|
+
candidates.push(path.join(homedir, '.archlens', `archlens-${suffix}`));
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const projectRoots = [workspace];
|
|
76
|
+
if (cwd && cwd !== workspace) {
|
|
77
|
+
projectRoots.push(cwd);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
for (const root of projectRoots) {
|
|
81
|
+
candidates.push(path.resolve(root, 'backend', 'target', `archlens-${suffix}`));
|
|
82
|
+
candidates.push(path.resolve(root, 'backend', 'target', runnerName));
|
|
83
|
+
candidates.push(path.resolve(root, 'target', `archlens-${suffix}`));
|
|
84
|
+
candidates.push(path.resolve(root, 'target', runnerName));
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
for (const candidate of candidates) {
|
|
88
|
+
try {
|
|
89
|
+
if (candidate && exists(candidate)) {
|
|
90
|
+
return candidate;
|
|
91
|
+
}
|
|
92
|
+
} catch {
|
|
93
|
+
// ignore
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
return null;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export function startNativeBinary(binaryPath, options = {}, deps = {}) {
|
|
100
|
+
const port = options.port || '8088';
|
|
101
|
+
const customSpawn = deps.spawn || spawn;
|
|
102
|
+
const args = [`-Dquarkus.http.port=${port}`];
|
|
103
|
+
|
|
104
|
+
if (options.jvmArgs && Array.isArray(options.jvmArgs)) {
|
|
105
|
+
args.unshift(...options.jvmArgs);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const child = customSpawn(binaryPath, args, {
|
|
109
|
+
detached: true,
|
|
110
|
+
stdio: 'ignore'
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
if (child && typeof child.unref === 'function') {
|
|
114
|
+
child.unref();
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
return {
|
|
118
|
+
action: 'started_binary',
|
|
119
|
+
mode: 'binary',
|
|
120
|
+
binaryPath,
|
|
121
|
+
pid: child ? child.pid : undefined
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
|
|
41
125
|
export function findNativeJar(options = {}, deps = {}) {
|
|
42
126
|
const exists = deps.existsSync || fs.existsSync;
|
|
43
127
|
const homedir = (deps.os && deps.os.homedir) ? deps.os.homedir() : (os.homedir ? os.homedir() : process.env.HOME || '');
|
|
@@ -195,6 +279,8 @@ export async function ensureServerRunning(options = {}, deps = {}) {
|
|
|
195
279
|
const spawnDocker = options.spawnDocker !== false;
|
|
196
280
|
|
|
197
281
|
const healthChecker = deps.checkServerHealth || checkServerHealth;
|
|
282
|
+
const binaryFinder = deps.findNativeBinary || (deps.findNativeJar ? () => null : findNativeBinary);
|
|
283
|
+
const binaryStarter = deps.startNativeBinary || startNativeBinary;
|
|
198
284
|
const javaChecker = deps.isJavaAvailable || isJavaAvailable;
|
|
199
285
|
const jarFinder = deps.findNativeJar || findNativeJar;
|
|
200
286
|
const jarStarter = deps.startNativeJar || startNativeJar;
|
|
@@ -214,9 +300,24 @@ export async function ensureServerRunning(options = {}, deps = {}) {
|
|
|
214
300
|
|
|
215
301
|
let launchedMode = null;
|
|
216
302
|
let launchedJarPath = null;
|
|
303
|
+
let launchedBinaryPath = null;
|
|
304
|
+
|
|
305
|
+
// 2a. Try GraalVM native binary first if preferNative is true
|
|
306
|
+
if (preferNative) {
|
|
307
|
+
const binPath = binaryFinder(options, deps);
|
|
308
|
+
if (binPath) {
|
|
309
|
+
try {
|
|
310
|
+
binaryStarter(binPath, options, deps);
|
|
311
|
+
launchedMode = 'binary';
|
|
312
|
+
launchedBinaryPath = binPath;
|
|
313
|
+
} catch {
|
|
314
|
+
// Fall back to JAR or Docker if native binary launch throws
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
}
|
|
217
318
|
|
|
218
|
-
//
|
|
219
|
-
if (preferNative && javaChecker(deps.execSync || execSync)) {
|
|
319
|
+
// 2b. Try native JAR if preferNative is true and no native binary launched
|
|
320
|
+
if (!launchedMode && preferNative && javaChecker(deps.execSync || execSync)) {
|
|
220
321
|
const jarPath = jarFinder(options, deps);
|
|
221
322
|
if (jarPath) {
|
|
222
323
|
try {
|
|
@@ -229,7 +330,7 @@ export async function ensureServerRunning(options = {}, deps = {}) {
|
|
|
229
330
|
}
|
|
230
331
|
}
|
|
231
332
|
|
|
232
|
-
// 3. Fallback to Docker if native JAR was not launched
|
|
333
|
+
// 3. Fallback to Docker if native binary/JAR was not launched
|
|
233
334
|
if (!launchedMode) {
|
|
234
335
|
const dockerAvailable = spawnDocker && dockerChecker(deps.execSync || execSync);
|
|
235
336
|
if (dockerAvailable) {
|
|
@@ -266,7 +367,8 @@ export async function ensureServerRunning(options = {}, deps = {}) {
|
|
|
266
367
|
version: probe.version,
|
|
267
368
|
spawned: true,
|
|
268
369
|
mode: launchedMode,
|
|
269
|
-
jarPath: launchedJarPath
|
|
370
|
+
jarPath: launchedJarPath,
|
|
371
|
+
binaryPath: launchedBinaryPath
|
|
270
372
|
};
|
|
271
373
|
}
|
|
272
374
|
}
|
|
@@ -277,7 +379,8 @@ export async function ensureServerRunning(options = {}, deps = {}) {
|
|
|
277
379
|
spawned: true,
|
|
278
380
|
mode: launchedMode,
|
|
279
381
|
jarPath: launchedJarPath,
|
|
280
|
-
|
|
382
|
+
binaryPath: launchedBinaryPath,
|
|
383
|
+
message: `Archlens ${launchedMode === 'jar' || launchedMode === 'binary' ? 'native server' : 'container'} launched; service is warming up.`
|
|
281
384
|
};
|
|
282
385
|
}
|
|
283
386
|
|
package/src/mcp-registry.js
CHANGED
|
@@ -87,6 +87,133 @@ export const ARCHLENS_TOOL_SCHEMAS = {
|
|
|
87
87
|
},
|
|
88
88
|
required: ['snapshotId']
|
|
89
89
|
}
|
|
90
|
+
},
|
|
91
|
+
synthesizeDipInversion: {
|
|
92
|
+
name: 'synthesizeDipInversion',
|
|
93
|
+
description:
|
|
94
|
+
'Generate a Dependency Inversion Principle (DIP) interface port and outward adapter blueprint to resolve a concentric ring violation.',
|
|
95
|
+
parameters: {
|
|
96
|
+
type: 'object',
|
|
97
|
+
properties: {
|
|
98
|
+
fromClass: {
|
|
99
|
+
type: 'string',
|
|
100
|
+
description: 'Fully qualified or simple name of the inner-layer class with the outward dependency (alias: sourceClass)'
|
|
101
|
+
},
|
|
102
|
+
toClass: {
|
|
103
|
+
type: 'string',
|
|
104
|
+
description: 'Fully qualified or simple name of the outer-layer class being depended upon (alias: targetClass)'
|
|
105
|
+
},
|
|
106
|
+
projectRoot: {
|
|
107
|
+
type: 'string',
|
|
108
|
+
description:
|
|
109
|
+
'Absolute or relative path to the target project directory. Defaults to current directory.',
|
|
110
|
+
default: '.'
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
required: ['fromClass', 'toClass']
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
evaluateFitness: {
|
|
117
|
+
name: 'evaluateFitness',
|
|
118
|
+
description:
|
|
119
|
+
'Evaluate the Architecture Fitness Index (AFI), Main Sequence Distance, Screaming Architecture Score, and concentric ring compliance.',
|
|
120
|
+
parameters: {
|
|
121
|
+
type: 'object',
|
|
122
|
+
properties: {
|
|
123
|
+
projectRoot: {
|
|
124
|
+
type: 'string',
|
|
125
|
+
description:
|
|
126
|
+
'Absolute or relative path to the target project directory. Defaults to current directory.',
|
|
127
|
+
default: '.'
|
|
128
|
+
}
|
|
129
|
+
},
|
|
130
|
+
required: []
|
|
131
|
+
}
|
|
132
|
+
},
|
|
133
|
+
getFitnessHistory: {
|
|
134
|
+
name: 'getFitnessHistory',
|
|
135
|
+
description:
|
|
136
|
+
'Retrieve historical Architecture Fitness Index (AFI) snapshots and regression trend (IMPROVING, STABLE, DEGRADING).',
|
|
137
|
+
parameters: {
|
|
138
|
+
type: 'object',
|
|
139
|
+
properties: {
|
|
140
|
+
projectRoot: {
|
|
141
|
+
type: 'string',
|
|
142
|
+
description:
|
|
143
|
+
'Absolute or relative path to the target project directory. Defaults to current directory.',
|
|
144
|
+
default: '.'
|
|
145
|
+
}
|
|
146
|
+
},
|
|
147
|
+
required: []
|
|
148
|
+
}
|
|
149
|
+
},
|
|
150
|
+
proposeScreamingMigration: {
|
|
151
|
+
name: 'proposeScreamingMigration',
|
|
152
|
+
description:
|
|
153
|
+
'Generate a Screaming Architecture package-by-feature verticalization migration proposal.',
|
|
154
|
+
parameters: {
|
|
155
|
+
type: 'object',
|
|
156
|
+
properties: {
|
|
157
|
+
projectRoot: {
|
|
158
|
+
type: 'string',
|
|
159
|
+
description:
|
|
160
|
+
'Absolute or relative path to the target project directory. Defaults to current directory.',
|
|
161
|
+
default: '.'
|
|
162
|
+
}
|
|
163
|
+
},
|
|
164
|
+
required: []
|
|
165
|
+
}
|
|
166
|
+
},
|
|
167
|
+
getPolicy: {
|
|
168
|
+
name: 'getPolicy',
|
|
169
|
+
description:
|
|
170
|
+
'Retrieve the active .archlens/policy.json concentric ring governance policy for the target project.',
|
|
171
|
+
parameters: {
|
|
172
|
+
type: 'object',
|
|
173
|
+
properties: {
|
|
174
|
+
projectRoot: {
|
|
175
|
+
type: 'string',
|
|
176
|
+
description:
|
|
177
|
+
'Absolute or relative path to the target project directory. Defaults to current directory.',
|
|
178
|
+
default: '.'
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
required: []
|
|
182
|
+
}
|
|
183
|
+
},
|
|
184
|
+
syncDipAdr: {
|
|
185
|
+
name: 'syncDipAdr',
|
|
186
|
+
description:
|
|
187
|
+
'Generate and synchronize an Architecture Decision Record (ADR) documenting a Dependency Inversion Principle (DIP) port extraction.',
|
|
188
|
+
parameters: {
|
|
189
|
+
type: 'object',
|
|
190
|
+
properties: {
|
|
191
|
+
sourceClass: {
|
|
192
|
+
type: 'string',
|
|
193
|
+
description: 'Fully qualified or simple name of the inner-layer class'
|
|
194
|
+
},
|
|
195
|
+
targetClass: {
|
|
196
|
+
type: 'string',
|
|
197
|
+
description: 'Fully qualified or simple name of the outer-layer class'
|
|
198
|
+
},
|
|
199
|
+
interfacePortName: {
|
|
200
|
+
type: 'string',
|
|
201
|
+
description: 'Synthesized interface port name (e.g. OrderRepositoryPort)'
|
|
202
|
+
},
|
|
203
|
+
reason: {
|
|
204
|
+
type: 'string',
|
|
205
|
+
description: 'Architectural rationale for the DIP inversion',
|
|
206
|
+
default: 'Invert outward Clean Architecture dependency'
|
|
207
|
+
},
|
|
208
|
+
projectRoot: {
|
|
209
|
+
type: 'string',
|
|
210
|
+
description:
|
|
211
|
+
'Absolute or relative path to the target project directory. Defaults to current directory.',
|
|
212
|
+
default: '.'
|
|
213
|
+
}
|
|
214
|
+
},
|
|
215
|
+
required: ['sourceClass', 'targetClass', 'interfacePortName']
|
|
216
|
+
}
|
|
90
217
|
}
|
|
91
218
|
};
|
|
92
219
|
|
|
@@ -110,14 +237,24 @@ It strictly enforces Uncle Bob's Dependency Rule: source code dependencies must
|
|
|
110
237
|
- **Main Sequence Balance Invariant**: Distance from Main Sequence $D = |A + I - 1| \le 0.35$ avoiding Zones of Pain and Uselessness.
|
|
111
238
|
- **Architectural Fitness Index (AFI)**: Composite fitness score (0-100%) and letter grade (A-F) tracking regression trends.
|
|
112
239
|
|
|
113
|
-
## Available MCP Tools:
|
|
240
|
+
## Available MCP Tools (10):
|
|
114
241
|
- \`exportLlmDossier\`: Primary tool to diagnose architectural drift and generate copy-ready LLM refactoring instructions with Dependency Inversion Principle (DIP) interface port prescriptions. Accepts \`{ "projectRoot": "." }\`.
|
|
115
242
|
- \`inspectArchitecture\`: Returns full structural JSON graph model: concentric rings, dependency edges, cycle paths, and screaming metrics.
|
|
243
|
+
- \`synthesizeDipInversion\`: Synthesizes a polyglot Dependency Inversion port (Java/Python/TS/Go/Rust) with caller and adapter diff previews. Accepts \`{ "fromClass": "...", "toClass": "...", "projectRoot": "." }\`.
|
|
244
|
+
- \`evaluateFitness\`: Evaluates the Architecture Fitness Index (\`AFI\` 0-100%, Grade \`A\`-\`F\`), Main Sequence metrics ($I, A, D$), and Screaming Architecture Score (\`SAS\`).
|
|
245
|
+
- \`getFitnessHistory\`: Retrieves historical Architecture Fitness Index snapshots and regression trajectory (\`IMPROVING\`, \`STABLE\`, \`DEGRADING\`).
|
|
246
|
+
- \`proposeScreamingMigration\`: Generates a Screaming Architecture package-by-feature verticalization migration proposal.
|
|
116
247
|
- \`listSnapshots\`: Lists historical architecture release snapshots in \`.archlens/snapshots/\` and Git release tags.
|
|
117
248
|
- \`getSnapshot\`: Retrieves architectural graph models for a specific historical release tag or snapshot ID.
|
|
249
|
+
- \`getPolicy\`: Retrieves the active \`.archlens/policy.json\` concentric ring governance policy.
|
|
250
|
+
- \`syncDipAdr\`: Mints and synchronizes a living Architecture Decision Record (\`docs/adr/ADR-*.md\`) for a DIP port extraction.
|
|
118
251
|
|
|
119
|
-
## Available MCP Resources:
|
|
252
|
+
## Available MCP Resources (3) & Prompts (2):
|
|
120
253
|
- \`archlens://llms.txt\`: Canonical reference guide, architectural rules, CLI commands, and refactoring protocols.
|
|
254
|
+
- \`archlens://policy\`: Active \`.archlens/policy.json\` concentric ring policy and refactoring proposals.
|
|
255
|
+
- \`archlens://fitness\`: Live Architecture Fitness Index (\`AFI\`) evaluation JSON report.
|
|
256
|
+
- \`architectural-review\` (Prompt): Structured prompt template for conducting a concentric ring & Main Sequence architectural review.
|
|
257
|
+
- \`dip-refactoring-guide\` (Prompt): Guided prompt template for executing a surgical Dependency Inversion refactoring.
|
|
121
258
|
|
|
122
259
|
## Refactoring Guidelines (Remediating Architectural Drift):
|
|
123
260
|
Whenever outward breaches are detected from inner layers (Domain Core or Application) to outer layers (Adapters or Infrastructure):
|
|
@@ -166,12 +303,44 @@ export function getClientConfigLocations(projectRoot = '.', homedir = os.homedir
|
|
|
166
303
|
},
|
|
167
304
|
{
|
|
168
305
|
id: 'antigravity-global',
|
|
169
|
-
name: 'Google Antigravity & Gemini CLI',
|
|
306
|
+
name: 'Google Antigravity & Gemini CLI (Schema Directory)',
|
|
170
307
|
type: 'tool-directory',
|
|
171
308
|
scope: 'global',
|
|
172
309
|
filePath: path.join(homedir, '.gemini', 'antigravity', 'mcp', 'archlens'),
|
|
173
310
|
parentDir: path.join(homedir, '.gemini', 'antigravity', 'mcp')
|
|
174
311
|
},
|
|
312
|
+
{
|
|
313
|
+
id: 'antigravity-config',
|
|
314
|
+
name: 'Google Antigravity (mcp_config.json)',
|
|
315
|
+
type: 'json-manifest',
|
|
316
|
+
scope: 'global',
|
|
317
|
+
filePath: path.join(homedir, '.gemini', 'antigravity', 'mcp_config.json'),
|
|
318
|
+
parentDir: path.join(homedir, '.gemini', 'antigravity')
|
|
319
|
+
},
|
|
320
|
+
{
|
|
321
|
+
id: 'gemini-cli',
|
|
322
|
+
name: 'Gemini CLI',
|
|
323
|
+
type: 'json-manifest',
|
|
324
|
+
scope: 'global',
|
|
325
|
+
filePath: path.join(homedir, '.gemini', 'settings.json'),
|
|
326
|
+
parentDir: path.join(homedir, '.gemini')
|
|
327
|
+
},
|
|
328
|
+
{
|
|
329
|
+
id: 'grok',
|
|
330
|
+
name: 'Grok CLI (xAI)',
|
|
331
|
+
type: 'json-manifest',
|
|
332
|
+
scope: 'local',
|
|
333
|
+
filePath: path.join(root, '.grok', 'mcp.json'),
|
|
334
|
+
parentDir: path.join(root, '.grok')
|
|
335
|
+
},
|
|
336
|
+
{
|
|
337
|
+
id: 'windsurf',
|
|
338
|
+
name: 'Windsurf',
|
|
339
|
+
type: 'json-manifest',
|
|
340
|
+
scope: 'global',
|
|
341
|
+
filePath: path.join(homedir, '.codeium', 'windsurf', 'mcp_config.json'),
|
|
342
|
+
parentDir: path.join(homedir, '.codeium', 'windsurf')
|
|
343
|
+
},
|
|
175
344
|
{
|
|
176
345
|
id: 'cursor',
|
|
177
346
|
name: 'Cursor',
|
|
@@ -250,12 +419,21 @@ export function installMcpConfigs(options = {}) {
|
|
|
250
419
|
}
|
|
251
420
|
}
|
|
252
421
|
|
|
253
|
-
if (
|
|
254
|
-
manifest.
|
|
422
|
+
if (target.id === 'vscode') {
|
|
423
|
+
if (!manifest.servers || typeof manifest.servers !== 'object') {
|
|
424
|
+
manifest.servers = {};
|
|
425
|
+
}
|
|
426
|
+
manifest.servers.archlens = {
|
|
427
|
+
type: 'stdio',
|
|
428
|
+
...getMcpManifestEntry(serverUrl)
|
|
429
|
+
};
|
|
430
|
+
} else {
|
|
431
|
+
if (!manifest.mcpServers || typeof manifest.mcpServers !== 'object') {
|
|
432
|
+
manifest.mcpServers = {};
|
|
433
|
+
}
|
|
434
|
+
manifest.mcpServers.archlens = getMcpManifestEntry(serverUrl);
|
|
255
435
|
}
|
|
256
436
|
|
|
257
|
-
manifest.mcpServers.archlens = getMcpManifestEntry(serverUrl);
|
|
258
|
-
|
|
259
437
|
if (!dryRun) {
|
|
260
438
|
fs.mkdirSync(path.dirname(target.filePath), { recursive: true });
|
|
261
439
|
fs.writeFileSync(target.filePath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
|