@fmatar/archlens-skill 0.1.0-Beta-10 → 1.1.0-dev.58

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.
@@ -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
- // 2. Try native JAR first if preferNative is true
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
- message: `Archlens ${launchedMode === 'jar' ? 'native server' : 'container'} launched; service is warming up.`
382
+ binaryPath: launchedBinaryPath,
383
+ message: `Archlens ${launchedMode === 'jar' || launchedMode === 'binary' ? 'native server' : 'container'} launched; service is warming up.`
281
384
  };
282
385
  }
283
386
 
@@ -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 (!manifest.mcpServers || typeof manifest.mcpServers !== 'object') {
254
- manifest.mcpServers = {};
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');