@fmatar/archlens-skill 0.0.1-Alpha-07
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/LICENSE +190 -0
- package/README.md +161 -0
- package/bin/index.js +379 -0
- package/package.json +48 -0
- package/skills/archlens-install-policy/SKILL.md +84 -0
- package/skills/archlens-install-policy/scripts/init_policy.py +325 -0
- package/src/analyzer.js +289 -0
- package/src/installer.js +200 -0
- package/src/ui.js +149 -0
- package/src/updater.js +172 -0
- package/src/upgrader.js +122 -0
package/bin/index.js
ADDED
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Archlens Skill & Policy CLI
|
|
5
|
+
* Interactive and headless runner for Clean Architecture governance and AI assistant integration.
|
|
6
|
+
* Zero external dependencies.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import * as path from 'node:path';
|
|
10
|
+
import * as fs from 'node:fs';
|
|
11
|
+
import { fileURLToPath } from 'node:url';
|
|
12
|
+
|
|
13
|
+
import * as ui from '../src/ui.js';
|
|
14
|
+
import { detectProjectLanguage, detectSourceRoot, findCommonPackagePrefix } from '../src/analyzer.js';
|
|
15
|
+
import { installLocalPolicy, installGlobalSkills } from '../src/installer.js';
|
|
16
|
+
import { updateLocalPolicy, updateGlobalSkills } from '../src/updater.js';
|
|
17
|
+
import { upgradeProject } from '../src/upgrader.js';
|
|
18
|
+
|
|
19
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
20
|
+
const __dirname = path.dirname(__filename);
|
|
21
|
+
|
|
22
|
+
function getPackageVersion() {
|
|
23
|
+
try {
|
|
24
|
+
const pkgPath = path.resolve(__dirname, '..', 'package.json');
|
|
25
|
+
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
|
|
26
|
+
return pkg.version || '0.0.1';
|
|
27
|
+
} catch {
|
|
28
|
+
return '0.0.1';
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function printHelp() {
|
|
33
|
+
const version = getPackageVersion();
|
|
34
|
+
console.log(`
|
|
35
|
+
${ui.colors.brightCyan}${ui.colors.bold}Archlens Skill & Policy Installer${ui.colors.reset} ${ui.colors.dim}v${version}${ui.colors.reset}
|
|
36
|
+
|
|
37
|
+
${ui.colors.bold}USAGE:${ui.colors.reset}
|
|
38
|
+
npx @fmatar/archlens-skill [command] [options]
|
|
39
|
+
archlens-skill [command] [options]
|
|
40
|
+
archlens-init [command] [options]
|
|
41
|
+
|
|
42
|
+
${ui.colors.bold}COMMANDS:${ui.colors.reset}
|
|
43
|
+
init Initialize Clean Architecture policy in target project (default)
|
|
44
|
+
update Update existing policy with newly discovered packages and refresh skills
|
|
45
|
+
upgrade Upgrade legacy .uml-viewer configuration to .archlens
|
|
46
|
+
global Install Archlens skills globally for AI coding assistants
|
|
47
|
+
|
|
48
|
+
${ui.colors.bold}OPTIONS:${ui.colors.reset}
|
|
49
|
+
-p, --path <DIR> Target repository path (default: current directory)
|
|
50
|
+
-t, --title <NAME> Project title displayed in Archlens workbench
|
|
51
|
+
--prefix <PKG> Common package prefix (e.g. com.example.app)
|
|
52
|
+
--server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
|
|
53
|
+
-g, --global Install or update skill globally in ~/.claude and ~/.gemini
|
|
54
|
+
-u, --update Update mode: sync new packages into existing policy
|
|
55
|
+
--upgrade Upgrade mode: migrate .uml-viewer to .archlens
|
|
56
|
+
-f, --force Overwrite existing policy files
|
|
57
|
+
--dry-run Simulate actions without writing files to disk
|
|
58
|
+
-y, --yes Accept defaults automatically (non-interactive mode)
|
|
59
|
+
-v, --version Display version information
|
|
60
|
+
-h, --help Display this help guide
|
|
61
|
+
|
|
62
|
+
${ui.colors.bold}EXAMPLES:${ui.colors.reset}
|
|
63
|
+
${ui.colors.dim}# Interactive setup wizard:${ui.colors.reset}
|
|
64
|
+
npx @fmatar/archlens-skill
|
|
65
|
+
|
|
66
|
+
${ui.colors.dim}# Initialize policy in current directory with default settings:${ui.colors.reset}
|
|
67
|
+
npx @fmatar/archlens-skill --yes
|
|
68
|
+
|
|
69
|
+
${ui.colors.dim}# Upgrade legacy .uml-viewer configuration to .archlens:${ui.colors.reset}
|
|
70
|
+
npx @fmatar/archlens-skill upgrade
|
|
71
|
+
|
|
72
|
+
${ui.colors.dim}# Install Archlens skill globally for Claude Code and Gemini CLI:${ui.colors.reset}
|
|
73
|
+
npx @fmatar/archlens-skill global
|
|
74
|
+
|
|
75
|
+
${ui.colors.dim}# Update existing policy after adding new modules:${ui.colors.reset}
|
|
76
|
+
npx @fmatar/archlens-skill update
|
|
77
|
+
`);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function parseArgs(args) {
|
|
81
|
+
const parsed = {
|
|
82
|
+
command: null,
|
|
83
|
+
path: '.',
|
|
84
|
+
title: null,
|
|
85
|
+
prefix: null,
|
|
86
|
+
serverUrl: 'http://localhost:8088',
|
|
87
|
+
global: false,
|
|
88
|
+
update: false,
|
|
89
|
+
upgrade: false,
|
|
90
|
+
force: false,
|
|
91
|
+
dryRun: false,
|
|
92
|
+
yes: false,
|
|
93
|
+
version: false,
|
|
94
|
+
help: false
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
const positional = [];
|
|
98
|
+
|
|
99
|
+
for (let i = 0; i < args.length; i++) {
|
|
100
|
+
const arg = args[i];
|
|
101
|
+
|
|
102
|
+
if (arg === '--help' || arg === '-h') {
|
|
103
|
+
parsed.help = true;
|
|
104
|
+
} else if (arg === '--version' || arg === '-v') {
|
|
105
|
+
parsed.version = true;
|
|
106
|
+
} else if (arg === '--global' || arg === '-g') {
|
|
107
|
+
parsed.global = true;
|
|
108
|
+
} else if (arg === '--update' || arg === '-u') {
|
|
109
|
+
parsed.update = true;
|
|
110
|
+
} else if (arg === '--upgrade') {
|
|
111
|
+
parsed.upgrade = true;
|
|
112
|
+
} else if (arg === '--force' || arg === '-f') {
|
|
113
|
+
parsed.force = true;
|
|
114
|
+
} else if (arg === '--dry-run') {
|
|
115
|
+
parsed.dryRun = true;
|
|
116
|
+
} else if (arg === '--yes' || arg === '-y') {
|
|
117
|
+
parsed.yes = true;
|
|
118
|
+
} else if (arg === '--path' || arg === '-p') {
|
|
119
|
+
parsed.path = args[++i] || '.';
|
|
120
|
+
} else if (arg === '--title' || arg === '-t') {
|
|
121
|
+
parsed.title = args[++i];
|
|
122
|
+
} else if (arg === '--prefix') {
|
|
123
|
+
parsed.prefix = args[++i];
|
|
124
|
+
} else if (arg === '--server-url') {
|
|
125
|
+
parsed.serverUrl = args[++i] || 'http://localhost:8088';
|
|
126
|
+
} else if (!arg.startsWith('-')) {
|
|
127
|
+
positional.push(arg);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
if (positional.length > 0) {
|
|
132
|
+
const cmd = positional[0].toLowerCase();
|
|
133
|
+
if (['init', 'update', 'upgrade', 'global', 'help', 'version'].includes(cmd)) {
|
|
134
|
+
parsed.command = cmd;
|
|
135
|
+
} else if (!parsed.title && !parsed.path) {
|
|
136
|
+
parsed.path = positional[0];
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
if (parsed.command === 'help') parsed.help = true;
|
|
141
|
+
if (parsed.command === 'version') parsed.version = true;
|
|
142
|
+
if (parsed.command === 'update') parsed.update = true;
|
|
143
|
+
if (parsed.command === 'upgrade') parsed.upgrade = true;
|
|
144
|
+
if (parsed.command === 'global') parsed.global = true;
|
|
145
|
+
|
|
146
|
+
return parsed;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
async function runInteractive(options) {
|
|
150
|
+
ui.banner();
|
|
151
|
+
|
|
152
|
+
const targetRoot = path.resolve(options.path || '.');
|
|
153
|
+
const lang = detectProjectLanguage(targetRoot);
|
|
154
|
+
const src = detectSourceRoot(targetRoot, lang);
|
|
155
|
+
const prefix = options.prefix || findCommonPackagePrefix(path.join(targetRoot, src));
|
|
156
|
+
|
|
157
|
+
console.log(`${ui.colors.bold}Target Workspace Diagnostics:${ui.colors.reset}`);
|
|
158
|
+
ui.table([
|
|
159
|
+
['Directory', targetRoot],
|
|
160
|
+
['Language', lang.toUpperCase()],
|
|
161
|
+
['Source Root', src],
|
|
162
|
+
['Package Prefix', prefix || '(root)']
|
|
163
|
+
]);
|
|
164
|
+
|
|
165
|
+
const choices = [
|
|
166
|
+
{
|
|
167
|
+
value: 'init_local',
|
|
168
|
+
label: `${ui.colors.bold}Initialize Archlens Policy locally${ui.colors.reset}`,
|
|
169
|
+
description: 'Scaffolds .archlens/policy.json and AI companion protocols'
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
value: 'install_global',
|
|
173
|
+
label: `${ui.colors.bold}Deploy AI Agent Skills globally${ui.colors.reset}`,
|
|
174
|
+
description: 'Equips Claude Code, Gemini CLI, and Antigravity with Archlens skills'
|
|
175
|
+
},
|
|
176
|
+
{
|
|
177
|
+
value: 'both',
|
|
178
|
+
label: `${ui.colors.bold}Full Suite (Local Policy + Global Skills)${ui.colors.reset}`,
|
|
179
|
+
description: 'Configures current repository and installs global AI assistant skills'
|
|
180
|
+
},
|
|
181
|
+
{
|
|
182
|
+
value: 'update',
|
|
183
|
+
label: `${ui.colors.bold}Update Existing Policy & Skills${ui.colors.reset}`,
|
|
184
|
+
description: 'Re-scans code for new packages and updates installed agent skills'
|
|
185
|
+
},
|
|
186
|
+
{
|
|
187
|
+
value: 'upgrade',
|
|
188
|
+
label: `${ui.colors.bold}Upgrade Legacy Config (.uml-viewer -> .archlens)${ui.colors.reset}`,
|
|
189
|
+
description: 'Migrate configuration and mailbox directories to modern .archlens layout'
|
|
190
|
+
}
|
|
191
|
+
];
|
|
192
|
+
|
|
193
|
+
const selectedAction = await ui.askChoice('Select installation action:', choices);
|
|
194
|
+
|
|
195
|
+
let customTitle = options.title;
|
|
196
|
+
if (['init_local', 'both'].includes(selectedAction) && !customTitle) {
|
|
197
|
+
const defaultTitle = ui.colors.dim + path.basename(targetRoot) + ui.colors.reset;
|
|
198
|
+
customTitle = await ui.askQuestion('Project display title', path.basename(targetRoot));
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
const execOptions = {
|
|
202
|
+
...options,
|
|
203
|
+
title: customTitle,
|
|
204
|
+
prefix
|
|
205
|
+
};
|
|
206
|
+
|
|
207
|
+
ui.divider();
|
|
208
|
+
|
|
209
|
+
if (selectedAction === 'init_local' || selectedAction === 'both') {
|
|
210
|
+
executeLocalInit(targetRoot, execOptions);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
if (selectedAction === 'install_global' || selectedAction === 'both') {
|
|
214
|
+
executeGlobalInstall(execOptions);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
if (selectedAction === 'update') {
|
|
218
|
+
executeUpdate(targetRoot, execOptions);
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
if (selectedAction === 'upgrade') {
|
|
222
|
+
executeUpgrade(targetRoot, execOptions);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
printCompletionMessage(targetRoot, execOptions.serverUrl);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function executeLocalInit(targetRoot, options) {
|
|
229
|
+
ui.step(1, 2, 'Scaffolding Clean Architecture Policy');
|
|
230
|
+
const result = installLocalPolicy(targetRoot, options);
|
|
231
|
+
|
|
232
|
+
if (result.policyCreated) {
|
|
233
|
+
ui.success(`Created policy file: ${path.relative(targetRoot, result.policyFile)}`);
|
|
234
|
+
} else {
|
|
235
|
+
ui.info(`Policy file already exists: ${path.relative(targetRoot, result.policyFile)} (use --force to overwrite)`);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
ui.success(`Created workbench config: ${path.relative(targetRoot, result.configFile)}`);
|
|
239
|
+
|
|
240
|
+
if (result.companionFiles.length > 0) {
|
|
241
|
+
ui.success(`Configured agent guidelines in: ${result.companionFiles.join(', ')}`);
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
if (result.policyData) {
|
|
245
|
+
console.log(`\n ${ui.colors.bold}Architectural Rings Defined:${ui.colors.reset}`);
|
|
246
|
+
const tiers = ['Domain Core (L0)', 'Application (L1)', 'Adapters (L2)', 'Infrastructure (L3)'];
|
|
247
|
+
result.policyData.levels.forEach((lvl, idx) => {
|
|
248
|
+
const tierName = tiers[idx] || `Level ${idx}`;
|
|
249
|
+
console.log(` ${ui.colors.cyan}${tierName}:${ui.colors.reset} [${lvl.join(', ')}]`);
|
|
250
|
+
});
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
function executeGlobalInstall(options) {
|
|
255
|
+
const modeSuffix = options.dryRun ? ' (dry run)' : '';
|
|
256
|
+
ui.step(2, 2, `Deploying AI Assistant Skills Globally${modeSuffix}`);
|
|
257
|
+
const result = installGlobalSkills(options);
|
|
258
|
+
|
|
259
|
+
if (result.installed.length === 0) {
|
|
260
|
+
ui.warn('No active AI agent directories found (~/.claude, ~/.gemini). Use --force to deploy anyway.');
|
|
261
|
+
} else {
|
|
262
|
+
for (const inst of result.installed) {
|
|
263
|
+
ui.success(`Installed skill for ${inst.agent}: ${inst.path}${modeSuffix}`);
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
function executeUpgrade(targetRoot, options) {
|
|
269
|
+
const modeSuffix = options.dryRun ? ' (dry run)' : '';
|
|
270
|
+
ui.step(1, 1, `Migrating Configuration to .archlens${modeSuffix}`);
|
|
271
|
+
const result = upgradeProject(targetRoot, options);
|
|
272
|
+
|
|
273
|
+
if (result.migrated) {
|
|
274
|
+
ui.success(
|
|
275
|
+
`Migrated legacy directory: ${path.relative(targetRoot, result.legacyDir)} -> ${path.relative(targetRoot, result.primaryDir)}`
|
|
276
|
+
);
|
|
277
|
+
if (result.migratedFiles.length > 0) {
|
|
278
|
+
ui.info(`Files moved: ${result.migratedFiles.join(', ')}`);
|
|
279
|
+
}
|
|
280
|
+
} else {
|
|
281
|
+
ui.info('Project is already aligned with .archlens configuration standard.');
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
if (result.updatedCompanions.length > 0) {
|
|
285
|
+
ui.success(`Updated companion references in: ${result.updatedCompanions.join(', ')}`);
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
function executeUpdate(targetRoot, options) {
|
|
290
|
+
const modeSuffix = options.dryRun ? ' (dry run)' : '';
|
|
291
|
+
ui.step(1, 2, `Synchronizing Clean Architecture Policy${modeSuffix}`);
|
|
292
|
+
const result = updateLocalPolicy(targetRoot, options);
|
|
293
|
+
|
|
294
|
+
if (result.newPackages.length > 0) {
|
|
295
|
+
ui.success(`Detected and incorporated ${result.newPackages.length} new package(s): ${result.newPackages.join(', ')}`);
|
|
296
|
+
} else {
|
|
297
|
+
ui.info('All discovered packages are already declared in the architectural policy.');
|
|
298
|
+
}
|
|
299
|
+
ui.info(`Total governed packages: ${result.totalPackages}`);
|
|
300
|
+
|
|
301
|
+
ui.step(2, 2, `Refreshing Global AI Assistant Skills${modeSuffix}`);
|
|
302
|
+
const globalResult = updateGlobalSkills(options);
|
|
303
|
+
if (globalResult.updatedLocations && globalResult.updatedLocations.length > 0) {
|
|
304
|
+
for (const loc of globalResult.updatedLocations) {
|
|
305
|
+
ui.success(`Updated skill for ${loc.agent}: ${loc.path}${modeSuffix}`);
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
function printCompletionMessage(targetRoot, serverUrl) {
|
|
311
|
+
ui.divider();
|
|
312
|
+
console.log(`\n${ui.colors.brightGreen}${ui.colors.bold}✦ Archlens Configuration Complete! ✦${ui.colors.reset}\n`);
|
|
313
|
+
console.log(`To visualize and govern Clean Architecture boundaries:`);
|
|
314
|
+
console.log(` 1. Launch Archlens workbench`);
|
|
315
|
+
console.log(` 2. Visit: ${ui.colors.brightCyan}${serverUrl}?projectRoot=${targetRoot}${ui.colors.reset}`);
|
|
316
|
+
console.log(` 3. Or press ${ui.colors.bold}⌘O / Ctrl+O${ui.colors.reset} inside Archlens to select this workspace.\n`);
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
async function main() {
|
|
320
|
+
const options = parseArgs(process.argv.slice(2));
|
|
321
|
+
|
|
322
|
+
if (options.help) {
|
|
323
|
+
printHelp();
|
|
324
|
+
process.exit(0);
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
if (options.version) {
|
|
328
|
+
console.log(getPackageVersion());
|
|
329
|
+
process.exit(0);
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
const isInteractive = Boolean(
|
|
333
|
+
process.stdin.isTTY &&
|
|
334
|
+
process.stdout.isTTY &&
|
|
335
|
+
!options.yes &&
|
|
336
|
+
!options.dryRun &&
|
|
337
|
+
!options.command &&
|
|
338
|
+
!options.global &&
|
|
339
|
+
!options.update &&
|
|
340
|
+
!options.upgrade
|
|
341
|
+
);
|
|
342
|
+
|
|
343
|
+
if (isInteractive) {
|
|
344
|
+
try {
|
|
345
|
+
await runInteractive(options);
|
|
346
|
+
} catch (err) {
|
|
347
|
+
ui.error(err.message || String(err));
|
|
348
|
+
process.exit(1);
|
|
349
|
+
}
|
|
350
|
+
return;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
// Non-interactive or flag-driven execution
|
|
354
|
+
const targetRoot = path.resolve(options.path || '.');
|
|
355
|
+
|
|
356
|
+
try {
|
|
357
|
+
if (options.upgrade) {
|
|
358
|
+
executeUpgrade(targetRoot, options);
|
|
359
|
+
} else if (options.update) {
|
|
360
|
+
executeUpdate(targetRoot, options);
|
|
361
|
+
} else if (options.global && !options.command) {
|
|
362
|
+
executeGlobalInstall(options);
|
|
363
|
+
executeLocalInit(targetRoot, options);
|
|
364
|
+
} else if (options.global || options.command === 'global') {
|
|
365
|
+
executeGlobalInstall(options);
|
|
366
|
+
} else {
|
|
367
|
+
executeLocalInit(targetRoot, options);
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
if (!options.dryRun) {
|
|
371
|
+
printCompletionMessage(targetRoot, options.serverUrl);
|
|
372
|
+
}
|
|
373
|
+
} catch (err) {
|
|
374
|
+
ui.error(err.message || String(err));
|
|
375
|
+
process.exit(1);
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
main();
|
package/package.json
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@fmatar/archlens-skill",
|
|
3
|
+
"version": "0.0.1-Alpha-07",
|
|
4
|
+
"description": "Cross-platform CLI and installer for Archlens Clean Architecture governance policies and AI assistant skills",
|
|
5
|
+
"main": "src/installer.js",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"archlens-skill": "./bin/index.js",
|
|
9
|
+
"archlens-init": "./bin/index.js"
|
|
10
|
+
},
|
|
11
|
+
"files": [
|
|
12
|
+
"bin",
|
|
13
|
+
"src",
|
|
14
|
+
"skills",
|
|
15
|
+
"README.md",
|
|
16
|
+
"LICENSE"
|
|
17
|
+
],
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=18.0.0"
|
|
20
|
+
},
|
|
21
|
+
"scripts": {
|
|
22
|
+
"test": "node --test test/*.test.js",
|
|
23
|
+
"start": "node bin/index.js"
|
|
24
|
+
},
|
|
25
|
+
"keywords": [
|
|
26
|
+
"archlens",
|
|
27
|
+
"clean-architecture",
|
|
28
|
+
"architecture-governance",
|
|
29
|
+
"dependency-inversion",
|
|
30
|
+
"claude-skill",
|
|
31
|
+
"gemini-skill",
|
|
32
|
+
"antigravity",
|
|
33
|
+
"npx-installer",
|
|
34
|
+
"scaffolder",
|
|
35
|
+
"code-analysis"
|
|
36
|
+
],
|
|
37
|
+
"author": "Fady Matar",
|
|
38
|
+
"license": "Apache-2.0",
|
|
39
|
+
"repository": {
|
|
40
|
+
"type": "git",
|
|
41
|
+
"url": "git+https://github.com/fmatar/archlens.git",
|
|
42
|
+
"directory": "cli"
|
|
43
|
+
},
|
|
44
|
+
"bugs": {
|
|
45
|
+
"url": "https://github.com/fmatar/archlens/issues"
|
|
46
|
+
},
|
|
47
|
+
"homepage": "https://github.com/fmatar/archlens#readme"
|
|
48
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
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.0
|
|
5
|
+
license: Apache-2.0
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Archlens Policy & Companion Installer (`archlens-install-policy`)
|
|
9
|
+
|
|
10
|
+
Use this skill to initialize Clean Architecture governance in any target software project for the **Archlens Dynamic Clean Architecture Workbench**.
|
|
11
|
+
|
|
12
|
+
This skill analyzes the project build system and directory layout, infers common package prefixes, organizes architectural packages into concentric rings, generates `.archlens/policy.json`, configures workbench connectivity, and equips AI coding assistants (Claude Code, Gemini CLI, Google Antigravity) with mailbox refactoring protocols.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 🎯 When to Use This Skill
|
|
17
|
+
Trigger this skill whenever the user asks to:
|
|
18
|
+
- "Install Archlens policy in this project"
|
|
19
|
+
- "Setup Archlens" or "Configure Clean Architecture policy"
|
|
20
|
+
- "Initialize .archlens/policy.json"
|
|
21
|
+
- "Upgrade Archlens config from .uml-viewer to .archlens"
|
|
22
|
+
- "Connect repository to Archlens workbench"
|
|
23
|
+
- "Prepare this repository for Archlens refactoring companion"
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 📋 Core Deliverables
|
|
28
|
+
When executed, this skill generates the following artifacts in the target project root:
|
|
29
|
+
1. **`.archlens/policy.json`**:
|
|
30
|
+
- Declares the project title, source root, and common package prefix.
|
|
31
|
+
- Organizes discovered packages into concentric tiers:
|
|
32
|
+
- **Level 0 (Domain Core)**: Entities, value objects, domain logic (`domain`, `model`, `entities`, `core`).
|
|
33
|
+
- **Level 1 (Application)**: Use cases, interaction services, application ports (`usecase`, `application`, `service`, `port`).
|
|
34
|
+
- **Level 2 (Adapters)**: Controllers, presenters, gateways, repository implementations (`adapter`, `controller`, `gateway`, `presenter`, `repository`, `dto`).
|
|
35
|
+
- **Level 3 (Infrastructure)**: Databases, web frameworks, persistence drivers, configuration (`infrastructure`, `config`, `db`, `web`).
|
|
36
|
+
2. **`.archlens/workbench.config.json`**:
|
|
37
|
+
- Configures the Archlens server URL (`http://localhost:8088`) and mailbox version.
|
|
38
|
+
3. **`CLAUDE.md` and `AGENTS.md`**:
|
|
39
|
+
- Injects the Clean Architecture Companion Protocol to instruct agents how to handle inbound mailbox tasks (`REGEN`, `APPLY_PROPOSAL`, `REFRESH_CRAP`) and enforce the Dependency Inversion Principle.
|
|
40
|
+
|
|
41
|
+
> [!NOTE]
|
|
42
|
+
> Backward Compatibility: Projects with existing `.uml-viewer/` configurations continue to function without modification. Upgrading to `.archlens/` is recommended for standard alignment.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 🛠️ Execution Instructions for Agents
|
|
47
|
+
|
|
48
|
+
### Step 1: Run the Archlens Installer or Upgrader
|
|
49
|
+
Execute the cross-platform CLI via NPX against the target repository:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Initialize a new project with defaults
|
|
53
|
+
npx @fmatar/archlens-skill --path . --yes
|
|
54
|
+
|
|
55
|
+
# Or upgrade an existing project from .uml-viewer to .archlens
|
|
56
|
+
npx @fmatar/archlens-skill upgrade --path .
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
*Flags available:*
|
|
60
|
+
- `--path <DIR>`: Target project directory (defaults to current directory).
|
|
61
|
+
- `--title <NAME>`: Custom project display title.
|
|
62
|
+
- `--prefix <PKG>`: Explicit package prefix (e.g. `com.mycompany.service`).
|
|
63
|
+
- `--server-url <URL>`: Archlens workbench endpoint (defaults to `http://localhost:8088`).
|
|
64
|
+
- `--update`: Re-scans code for new packages and updates existing policy.
|
|
65
|
+
- `--upgrade`: Migrates legacy `.uml-viewer/` configuration and mailboxes to `.archlens/`.
|
|
66
|
+
- `--force`: Overwrite existing `.archlens/policy.json` if present.
|
|
67
|
+
|
|
68
|
+
Alternatively, agents can run the bundled Python script:
|
|
69
|
+
```bash
|
|
70
|
+
python3 scripts/init_policy.py --path .
|
|
71
|
+
|
|
72
|
+
# Or upgrade:
|
|
73
|
+
python3 scripts/init_policy.py --path . --upgrade
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Step 2: Review Generated Policy
|
|
77
|
+
Inspect the generated `.archlens/policy.json` to confirm the packages align with the developer's architecture intent. If the project uses custom domain terminology, adjust the `levels` array accordingly.
|
|
78
|
+
|
|
79
|
+
### Step 3: Verify with Archlens Workbench
|
|
80
|
+
Once configured, developers can open the project in the visual workbench:
|
|
81
|
+
```text
|
|
82
|
+
http://localhost:8088/?projectRoot=<ABSOLUTE_PATH_TO_PROJECT>
|
|
83
|
+
```
|
|
84
|
+
Or open Archlens and use `⌘O` / `Ctrl+O` to select the project via the visual filesystem explorer.
|