@hanv89/arch-skill 0.0.0 → 0.2.0

package/dist/adapters/claude-code.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeAdapter = void 0;
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const _shared_1 = require("./_shared");
+function claudeRootDir() {
+    return path.join(os.homedir(), ".claude");
+}
+exports.claudeCodeAdapter = (0, _shared_1.makeFolderInstallAdapter)({
+    rootDir: claudeRootDir,
+    rootDisplay: () => "~/.claude",
+    agentFlag: "claude-code",
+});

package/dist/adapters/codex.js

@@ -0,0 +1,56 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexAdapter = void 0;
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const _shared_1 = require("./_shared");
+// Codex CLI discovers user-installed skills at $CODEX_HOME/skills/<name>/SKILL.md,
+// defaulting to ~/.codex/skills/ when CODEX_HOME is unset. Verified against the
+// Codex Rust binary's bundled prompt strings. See https://github.com/openai/codex.
+function codexRootDir() {
+    const explicit = process.env.CODEX_HOME;
+    if (explicit)
+        return path.resolve(explicit);
+    return path.join(os.homedir(), ".codex");
+}
+function codexRootDisplay() {
+    return process.env.CODEX_HOME ? `$CODEX_HOME=${process.env.CODEX_HOME}` : "~/.codex";
+}
+exports.codexAdapter = (0, _shared_1.makeFolderInstallAdapter)({
+    rootDir: codexRootDir,
+    rootDisplay: codexRootDisplay,
+    agentFlag: "codex",
+});

package/dist/adapters/cursor.js

@@ -0,0 +1,198 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cursorAdapter = exports.PROVENANCE_RE = void 0;
+exports.provenanceMarker = provenanceMarker;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const _shared_1 = require("./_shared");
+// Cursor's project-scoped rules live at <cwd>/.cursor/rules/*.mdc with a
+// distinct frontmatter shape (description / globs / alwaysApply). User Rules
+// are settings-only and not programmatically writable from an external CLI,
+// so this adapter targets Project Rules only.
+//
+// Unlike Claude Code + Codex (per-user folder containing SKILL.md + examples/),
+// Cursor installs a SINGLE .mdc file. The skill body is concatenated under a
+// Cursor-shaped frontmatter; examples are NOT bundled locally — the skill body
+// references their public raw GitHub URLs and the agent fetches them at
+// diagram-authoring time.
+//
+// See https://cursor.com/docs/context/rules for the format reference.
+const RULE_BASENAME = "arch-skill.mdc";
+const RULE_DESCRIPTION = "Use this rule when drawing Microsoft Azure or Microsoft Fabric architecture diagrams using PlantUML. " +
+    "Triggers on \"draw Azure architecture\", \"draw Azure diagram\", \"create deployment diagram\", " +
+    "\"Lakehouse + Notebook + Warehouse diagram\", \"PlantUML diagram for [project]\". " +
+    "Also triggers on the Vietnamese phrase \"vẽ Azure\".";
+// Cursor's rule discovery is per-project: <cwd>/.cursor/rules/*.mdc is the
+// canonical install location, so the team picks up the rule via the project's
+// git repo. A HOME-relative install would only help the local developer. The
+// trade-off — running install from an unintended cwd — is mitigated by a
+// runtime warn-line (see `install` below) and the `--target=<path>` override.
+function defaultTarget() {
+    return path.join(process.cwd(), ".cursor", "rules");
+}
+const CWD_DISPLAY = "<cwd>/.cursor/rules";
+async function resolveTarget(target) {
+    return (0, _shared_1.safeResolveTarget)(target, process.cwd(), CWD_DISPLAY);
+}
+// `provenanceMarker` and `PROVENANCE_RE` are paired: the regex MUST parse what
+// the marker writes. Keep them in lockstep — a unit test in version.test.ts
+// asserts the round-trip.
+function provenanceMarker(version, requiresIcons) {
+    return `<!-- ${_shared_1.SKILL_NAME} v${version} (requires_icons: ${requiresIcons}) -->`;
+}
+const PROVENANCE_RE = new RegExp(`<!--\\s*${_shared_1.SKILL_NAME}\\s+v([^\\s]+)\\s+\\(requires_icons:\\s*([^)]+)\\)\\s*-->`);
+exports.PROVENANCE_RE = PROVENANCE_RE;
+function renderRule(skillBody, version, requiresIcons) {
+    return [
+        "---",
+        `description: ${RULE_DESCRIPTION}`,
+        "alwaysApply: false",
+        "---",
+        "",
+        provenanceMarker(version, requiresIcons),
+        "",
+        skillBody.trimStart(),
+    ].join("\n");
+}
+async function isOurRuleFile(file) {
+    try {
+        const body = await fs.readFile(file, "utf8");
+        const match = body.match(PROVENANCE_RE);
+        if (!match)
+            return { ours: false };
+        return { ours: true, version: match[1] };
+    }
+    catch {
+        return { ours: false };
+    }
+}
+async function install(opts) {
+    return (0, _shared_1.withFatalReturn)(async () => {
+        if (opts.target === undefined) {
+            process.stderr.write(`note: Cursor target resolved to ${defaultTarget()} (per-project install). Pass --target=<path> to override.\n`);
+        }
+        const targetDir = await resolveTarget(opts.target ?? defaultTarget());
+        const base = (0, _shared_1.baseUrl)(opts.version);
+        const ruleFile = path.join(targetDir, RULE_BASENAME);
+        // Fetch manifest first so we know which file is the canonical SKILL.md
+        // and what version / requires_icons to embed in the provenance marker.
+        const manifest = await (0, _shared_1.fetchManifest)(base);
+        if (manifest.name !== _shared_1.SKILL_NAME) {
+            throw new Error(`manifest name mismatch: expected '${_shared_1.SKILL_NAME}', got '${manifest.name}'. CLI and bundle are out of sync.`);
+        }
+        const skillFile = manifest.files[0];
+        const skillUrl = `${base}/${skillFile.src}`;
+        const skillMd = await (0, _shared_1.fetchText)(skillUrl);
+        // Integrity gate (verify-before-write): the Cursor adapter doesn't use
+        // makeFolderInstallAdapter, so it must apply the same sha256 check the
+        // folder adapters get for free. Keeps the manifest-checksum guarantee
+        // uniform across all three adapters.
+        (0, _shared_1.verifyBundleFile)(skillFile, skillMd);
+        const fm = (0, _shared_1.parseFrontmatter)(skillMd);
+        if (!fm.requires_icons) {
+            throw new Error("SKILL.md missing requires_icons frontmatter");
+        }
+        await (0, _shared_1.verifyIconsAvailability)(base, manifest, opts.version);
+        const exists = await fs.stat(ruleFile).then(() => true).catch(() => false);
+        if (exists && !opts.overwrite) {
+            const probe = await isOurRuleFile(ruleFile);
+            throw new Error(probe.ours
+                ? `${ruleFile} already contains an install. Run 'arch-skill update --agent=cursor' to refresh.`
+                : `${ruleFile} exists but is not one of ours (no '${_shared_1.SKILL_NAME}' provenance marker). Move/rename the file or remove it manually if intentional.`);
+        }
+        await fs.mkdir(targetDir, { recursive: true });
+        const body = (0, _shared_1.stripFrontmatter)(skillMd);
+        const rendered = renderRule(body, fm.version ?? manifest.version, fm.requires_icons);
+        await fs.writeFile(ruleFile, rendered, "utf8");
+        process.stdout.write(`installed ${_shared_1.SKILL_NAME} to ${ruleFile}\n`);
+        return 0;
+    });
+}
+async function uninstall(opts) {
+    return (0, _shared_1.withFatalReturn)(async () => {
+        const targetDir = await resolveTarget(opts.target ?? defaultTarget());
+        const ruleFile = path.join(targetDir, RULE_BASENAME);
+        const exists = await fs.stat(ruleFile).then(() => true).catch(() => false);
+        if (!exists) {
+            process.stdout.write(`(nothing to uninstall at ${ruleFile})\n`);
+            return 0;
+        }
+        const probe = await isOurRuleFile(ruleFile);
+        if (!probe.ours) {
+            throw new Error(`refusing to remove ${ruleFile} - missing '${_shared_1.SKILL_NAME}' provenance marker. Move/rename the file or remove it manually if intentional.`);
+        }
+        await fs.unlink(ruleFile);
+        process.stdout.write(`uninstalled ${_shared_1.SKILL_NAME} from ${ruleFile}\n`);
+        return 0;
+    });
+}
+async function update(opts) {
+    return (0, _shared_1.withFatalReturn)(async () => {
+        const targetDir = await resolveTarget(opts.target ?? defaultTarget());
+        const ruleFile = path.join(targetDir, RULE_BASENAME);
+        const base = (0, _shared_1.baseUrl)(opts.version);
+        // Already-at-version short-circuit (parity with the folder-install
+        // adapters). Read the installed .mdc, extract version from the
+        // provenance marker, compare to the upstream manifest's version.
+        const probe = await isOurRuleFile(ruleFile);
+        if (probe.ours && probe.version) {
+            const manifest = await (0, _shared_1.fetchManifest)(base);
+            if (manifest.name !== _shared_1.SKILL_NAME) {
+                throw new Error(`manifest name mismatch: expected '${_shared_1.SKILL_NAME}', got '${manifest.name}'. CLI and bundle are out of sync.`);
+            }
+            if (probe.version === manifest.version) {
+                process.stdout.write(`${_shared_1.SKILL_NAME} already at version ${manifest.version} (no-op)\n`);
+                return 0;
+            }
+        }
+        // Otherwise, overwriting install.
+        return install({ ...opts, overwrite: true });
+    });
+}
+async function list(opts) {
+    return (0, _shared_1.withFatalReturn)(async () => {
+        const targetDir = await resolveTarget(opts.target ?? defaultTarget());
+        const ruleFile = path.join(targetDir, RULE_BASENAME);
+        const probe = await isOurRuleFile(ruleFile);
+        if (!probe.ours) {
+            process.stdout.write("(no skills installed)\n");
+            return 0;
+        }
+        process.stdout.write(`${_shared_1.SKILL_NAME}\t${probe.version ?? "?"}\n`);
+        return 0;
+    });
+}
+exports.cursorAdapter = { install, uninstall, update, list };

package/dist/adapters/registry.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_TARGETS = exports.ALL_TARGET = exports.SUPPORTED_AGENTS = exports.ADAPTERS = void 0;
+const claude_code_1 = require("./claude-code");
+const codex_1 = require("./codex");
+const cursor_1 = require("./cursor");
+// Single source of truth for the supported-agent set. Add a new adapter by
+// importing it here and adding one entry below; both `src/index.ts` (CLI
+// dispatch + --agent help text) and `adapters-roundtrip.test.ts` (test loop)
+// read from this map directly.
+exports.ADAPTERS = {
+    "claude-code": claude_code_1.claudeCodeAdapter,
+    "codex": codex_1.codexAdapter,
+    "cursor": cursor_1.cursorAdapter,
+};
+exports.SUPPORTED_AGENTS = Object.keys(exports.ADAPTERS);
+/** Sentinel value for `--agent=all` — iterate every adapter under one command. */
+exports.ALL_TARGET = "all";
+/** Full target set the CLI's `--agent` flag accepts. */
+exports.SUPPORTED_TARGETS = [...exports.SUPPORTED_AGENTS, exports.ALL_TARGET];

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/all.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOverAll = runOverAll;
+const registry_1 = require("./adapters/registry");
+async function runOverAll(sub, opts) {
+    if (registry_1.SUPPORTED_AGENTS.length === 0) {
+        throw new Error("no adapters loaded in registry (registry.ts ADAPTERS is empty)");
+    }
+    const completed = [];
+    const successes = [];
+    const failures = [];
+    const isTransactional = sub === "install" || sub === "update";
+    for (const agent of registry_1.SUPPORTED_AGENTS) {
+        const adapter = registry_1.ADAPTERS[agent];
+        const outcome = await runOne(adapter, agent, sub, opts);
+        if (outcome.exit === 0) {
+            successes.push(agent);
+            if (isTransactional)
+                completed.push(agent);
+        }
+        else {
+            failures.push(outcome);
+            if (isTransactional)
+                break; // halt + roll back below
+            // uninstall / list: best-effort, keep going
+        }
+    }
+    const rolledBack = [];
+    if (isTransactional && failures.length > 0) {
+        for (const agent of completed.slice().reverse()) {
+            try {
+                const exit = await registry_1.ADAPTERS[agent].uninstall(opts);
+                if (exit === 0) {
+                    rolledBack.push(agent);
+                }
+                else {
+                    process.stderr.write(`fatal: rollback failed for ${agent}: uninstall exited ${exit}\n`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`fatal: rollback failed for ${agent}: ${msg}\n`);
+                // continue with the rest (best-effort cleanup)
+            }
+        }
+    }
+    process.stderr.write(formatSummary(sub, successes, failures, rolledBack, isTransactional));
+    return failures.length > 0 ? 1 : 0;
+}
+async function runOne(adapter, agent, sub, opts) {
+    try {
+        // All four Adapter methods now accept the same AdapterOpts shape (see types.ts).
+        const exit = await adapter[sub](opts);
+        return { agent, exit };
+    }
+    catch (err) {
+        return { agent, exit: 1, error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}
+function formatSummary(sub, successes, failures, rolledBack, isTransactional) {
+    const fmt = (list, fallback) => `[${list.length > 0 ? list.join(", ") : fallback}]`;
+    const succLabel = fmt(successes, "(none)");
+    const failLabel = fmt(failures.map(f => f.agent), "(none)");
+    const rbLabel = isTransactional ? fmt(rolledBack, "(none)") : "[(n/a)]";
+    return `--agent=all (${sub}): succeeded=${succLabel} failed=${failLabel} rolled-back=${rbLabel}\n`;
+}

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const package_json_1 = __importDefault(require("../package.json"));
+const registry_1 = require("./adapters/registry");
+const all_1 = require("./all");
+const program = new commander_1.Command()
+    .name("arch-skill")
+    .description("Install the architecture diagram skill into your AI coding agent.")
+    // Top-level flag uses `--cli-version` (not `--version`) so subcommand
+    // `--version <semver>` (skill pin) dispatches correctly. Earlier shipping
+    // cycles bound both at `--version`; Commander short-circuited to the
+    // top-level printer before invoking the subcommand action, breaking
+    // documented tag-pin examples.
+    .version(package_json_1.default.version, "-V, --cli-version");
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+function defineSubcommand(name, description) {
+    program
+        .command(name)
+        .description(description)
+        .requiredOption("--agent <name>", `target AI agent (${registry_1.SUPPORTED_TARGETS.join("|")})`)
+        .option("--target <dir>", "override target directory (validation use)")
+        // Subcommand-scoped `--version <semver>` pins which skill bundle to
+        // fetch. Distinct from the top-level `--cli-version` flag which prints
+        // the CLI tool's own version. The two are namespaced cleanly now that
+        // the top-level flag is renamed.
+        .option("--version <semver>", "pin to a specific skill version (X.Y.Z); default = latest from main")
+        .action(async (opts) => {
+        // Validate --version pre-dispatch as defense-in-depth; baseUrl() in
+        // _shared.ts also rejects malformed values when it builds the URL.
+        if (opts.version !== undefined && !VERSION_RE.test(opts.version)) {
+            throw new Error(`--version must match X.Y.Z (got: ${opts.version})`);
+        }
+        const optsForAdapter = { target: opts.target, version: opts.version };
+        if (opts.agent === registry_1.ALL_TARGET) {
+            process.exitCode = await (0, all_1.runOverAll)(name, optsForAdapter);
+            return;
+        }
+        if (!registry_1.SUPPORTED_AGENTS.includes(opts.agent)) {
+            throw new Error(`unknown agent: ${opts.agent} (supported: ${registry_1.SUPPORTED_AGENTS.join(", ")})`);
+        }
+        process.exitCode = await registry_1.ADAPTERS[opts.agent][name](optsForAdapter);
+    });
+}
+defineSubcommand("install", "Install the skill into an AI agent's skill folder.");
+defineSubcommand("uninstall", "Remove a previously installed skill.");
+defineSubcommand("update", "Update an installed skill to the latest version.");
+defineSubcommand("list", "List installed skills and their versions.");
+// Top-level catch: setting process.exitCode (instead of process.exit(1)) lets
+// any pending async cleanup (file handles, the override-warning stderr write)
+// drain before the event loop empties. Both this path and adapter-internal
+// failures emit a single '^fatal: ' prefix line on stderr — log-parsers can
+// rely on the prefix.
+program.parseAsync(process.argv).catch(err => {
+    process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -1,13 +1,47 @@
 {
   "name": "@hanv89/arch-skill",
-  "version": "0.0.0",
-  "description": "Placeholder to bootstrap npm trusted publishing (OIDC). Real releases begin at 0.1.0.",
+  "version": "0.2.0",
+  "description": "Install the architecture-diagram skill into your AI coding agent (Claude Code, Codex CLI, Cursor).",
+  "bin": {
+    "arch-skill": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "tsc && node --test dist/**/*.test.js dist/*.test.js",
+    "test:coverage": "tsc && node --test --experimental-test-coverage dist/**/*.test.js dist/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "license": "MIT",
-  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanv89/archicon.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hanv89/archicon/issues"
+  },
+  "homepage": "https://github.com/hanv89/archicon#readme",
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "commander": "14.0.3",
+    "js-yaml": "4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "22.18.0",
+    "typescript": "5.9.3"
+  }
 }

package/README.md

@@ -1,7 +0,0 @@
-# @hanv89/arch-skill
-
-Placeholder release to bootstrap npm **trusted publishing (OIDC)**. npm cannot
-publish a package's first version via OIDC and cannot configure a trusted
-publisher until the package exists, so this `0.0.0` placeholder is published
-once manually to create the package. Real releases begin at `0.1.0` and are
-published from CI via OIDC — see the project repository.