@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/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.