@hanv89/azure-arch-skill 0.6.0 → 0.8.0

package/dist/__test_fixtures__/synthetic-bundle.js

@@ -0,0 +1,137 @@
+"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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silenceStderr = exports.rmTmpdir = exports.mkTmpdir = exports.failOnNthHeadFetchMock = exports.installFetchMock = exports.SYNTHETIC_MANIFEST = exports.SYNTHETIC_EXAMPLE = exports.SYNTHETIC_SKILL_MD = exports.SYNTHETIC_ICONS_VERSION = exports.SYNTHETIC_REQUIRES_ICONS = exports.SYNTHETIC_VERSION = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+// Synthetic skill bundle used by every test suite that mocks the network.
+// Keeping all three suites (adapters-roundtrip, all, version) on the same
+// fixture eliminates per-file drift (e.g. SKILL.md version: 0.5.0 vs 0.6.0
+// landed in earlier test files because the fixture was copy-pasted).
+exports.SYNTHETIC_VERSION = "0.5.0";
+exports.SYNTHETIC_REQUIRES_ICONS = ">=0.2.2";
+exports.SYNTHETIC_ICONS_VERSION = "0.2.2";
+exports.SYNTHETIC_SKILL_MD = [
+    "---",
+    "name: azure-architecture-diagram",
+    "description: test fixture",
+    `version: ${exports.SYNTHETIC_VERSION}`,
+    `requires_icons: "${exports.SYNTHETIC_REQUIRES_ICONS}"`,
+    "---",
+    "# Test skill body",
+    "",
+    "This is a synthetic SKILL.md used only by the test fixtures.",
+].join("\n");
+exports.SYNTHETIC_EXAMPLE = "@startuml\ntitle Test\n@enduml\n";
+exports.SYNTHETIC_MANIFEST = {
+    $schema: "./manifest.schema.json",
+    name: "azure-architecture-diagram",
+    version: exports.SYNTHETIC_VERSION,
+    requires_icons: exports.SYNTHETIC_REQUIRES_ICONS,
+    icons_version: exports.SYNTHETIC_ICONS_VERSION,
+    files: [
+        { src: "dist/skill/SKILL.md", dest: "SKILL.md", role: "skill" },
+        { src: "dist/skill/examples/01-context.puml", dest: "examples/01-context.puml", role: "example" },
+    ],
+};
+const realFetch = globalThis.fetch;
+/**
+ * Returns 200 for the manifest, SKILL.md, and the one bundled example;
+ * 200 for any HEAD; 404 otherwise.
+ */
+function installFetchMock() {
+    globalThis.fetch = (async (url, init) => {
+        const u = url.toString();
+        const method = (init?.method ?? "GET").toUpperCase();
+        if (method === "HEAD") {
+            return new Response(null, { status: 200 });
+        }
+        if (u.endsWith("/dist/skill/manifest.json")) {
+            return new Response(JSON.stringify(exports.SYNTHETIC_MANIFEST), { status: 200, headers: { "Content-Type": "application/json" } });
+        }
+        if (u.endsWith("/dist/skill/SKILL.md")) {
+            return new Response(exports.SYNTHETIC_SKILL_MD, { status: 200 });
+        }
+        if (u.endsWith("/dist/skill/examples/01-context.puml")) {
+            return new Response(exports.SYNTHETIC_EXAMPLE, { status: 200 });
+        }
+        return new Response("not found", { status: 404 });
+    });
+    return { restore: () => { globalThis.fetch = realFetch; } };
+}
+exports.installFetchMock = installFetchMock;
+/**
+ * Like `installFetchMock` but the Nth HEAD request returns 404. Used by
+ * the rollback test to fail the third adapter's canary while the first
+ * two have already installed.
+ */
+function failOnNthHeadFetchMock(failOnHeadIndex) {
+    let headCount = 0;
+    globalThis.fetch = (async (url, init) => {
+        const u = url.toString();
+        const method = (init?.method ?? "GET").toUpperCase();
+        if (method === "HEAD") {
+            headCount++;
+            if (headCount === failOnHeadIndex) {
+                return new Response(null, { status: 404 });
+            }
+            return new Response(null, { status: 200 });
+        }
+        if (u.endsWith("/dist/skill/manifest.json")) {
+            return new Response(JSON.stringify(exports.SYNTHETIC_MANIFEST), { status: 200, headers: { "Content-Type": "application/json" } });
+        }
+        if (u.endsWith("/dist/skill/SKILL.md")) {
+            return new Response(exports.SYNTHETIC_SKILL_MD, { status: 200 });
+        }
+        if (u.endsWith("/dist/skill/examples/01-context.puml")) {
+            return new Response(exports.SYNTHETIC_EXAMPLE, { status: 200 });
+        }
+        return new Response("not found", { status: 404 });
+    });
+    return {
+        restore: () => { globalThis.fetch = realFetch; },
+        headCount: () => headCount,
+    };
+}
+exports.failOnNthHeadFetchMock = failOnNthHeadFetchMock;
+function mkTmpdir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "azure-arch-skill-test-"));
+}
+exports.mkTmpdir = mkTmpdir;
+function rmTmpdir(dir) {
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+exports.rmTmpdir = rmTmpdir;
+// Silence stderr summary lines so the test reporter's output stays readable.
+// IMPORTANT: do NOT silence stdout. Hijacking process.stdout.write inside a
+// node:test test confuses the runner's buffered reporter — other tests' ✔
+// lines get eaten by the capture buffer and silently drop from the count.
+function silenceStderr() {
+    const orig = process.stderr.write.bind(process.stderr);
+    process.stderr.write = (_chunk) => true;
+    return { restore: () => { process.stderr.write = orig; } };
+}
+exports.silenceStderr = silenceStderr;

package/dist/adapters/_shared.js

@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withFatalReturn = exports.stripFrontmatter = exports.parseFrontmatter = exports.fetchManifest = exports.headOk = exports.fetchText = exports.fetchWithTimeout = exports.safeResolveTarget = exports.baseUrl = exports.USER_AGENT = exports.FETCH_TIMEOUT_MS = exports.CANARY_ICON_PATH = exports.MANIFEST_PATH = exports.SKILL_NAME = exports.DEFAULT_BASE_RAW_URL = void 0;
+exports.makeFolderInstallAdapter = exports.withFatalReturn = exports.verifyIconsAvailability = exports.satisfiesRequiresIcons = exports.stripFrontmatter = exports.parseFrontmatter = exports.fetchManifest = exports.headOk = exports.fetchText = exports.fetchWithTimeout = exports.safeResolveTarget = exports.baseUrl = exports.USER_AGENT = exports.FETCH_TIMEOUT_MS = exports.CANARY_ICON_PATH = exports.MANIFEST_PATH = exports.SKILL_NAME = exports.DEFAULT_BASE_RAW_URL = void 0;
 const fs = __importStar(require("node:fs/promises"));
 const path = __importStar(require("node:path"));
 const package_json_1 = __importDefault(require("../../package.json"));
@@ -35,6 +35,10 @@ const package_json_1 = __importDefault(require("../../package.json"));
 // adapter file that imports from here. Codex / Cursor / future adapters
 // re-use these helpers via the same import path.
 exports.DEFAULT_BASE_RAW_URL = "https://raw.githubusercontent.com/hanv89/azure-icons-for-architecture-diagrams/main";
+// Same repo root without the ref segment; baseUrl() appends `main` (default)
+// or `skill-vX.Y.Z` when --version is supplied.
+const RAW_BASE_NO_REF = "https://raw.githubusercontent.com/hanv89/azure-icons-for-architecture-diagrams";
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
 // SKILL_NAME must stay in lockstep with dist/skill/SKILL.md frontmatter `name`.
 // Renaming the skill is a breaking change requiring a coordinated CLI release;
 // existing installs become un-uninstallable until users upgrade the CLI
@@ -48,28 +52,46 @@ exports.FETCH_TIMEOUT_MS = 30_000;
 exports.USER_AGENT = `azure-arch-skill/${package_json_1.default.version}`;
 const ALLOWED_BASE_URL_HOSTS = new Set(["raw.githubusercontent.com"]);
 const ALLOWED_BASE_URL_PATH_PREFIX = "/hanv89/azure-icons-for-architecture-diagrams/";
-function baseUrl() {
+/**
+ * Resolve the base URL for fetching the skill bundle.
+ *
+ * - `version` undefined → `<RAW_BASE>/main` (default, tracks the upstream main branch).
+ * - `version="X.Y.Z"`   → `<RAW_BASE>/skill-vX.Y.Z` (tag-pinned fetch).
+ * - `AZURE_ARCH_SKILL_BASE_URL` env set → env override wins; `version` is ignored
+ *   (the env exists only for validation harnesses).
+ *
+ * `version` is validated against the strict X.Y.Z regex here as defense-in-depth;
+ * `src/index.ts` also rejects malformed values pre-dispatch.
+ */
+function baseUrl(version) {
     const override = process.env.AZURE_ARCH_SKILL_BASE_URL;
-    if (!override)
-        return exports.DEFAULT_BASE_RAW_URL;
-    let u;
-    try {
-        u = new URL(override);
-    }
-    catch {
-        throw new Error(`AZURE_ARCH_SKILL_BASE_URL is not a valid URL: ${override}`);
-    }
-    if (u.protocol !== "https:") {
-        throw new Error(`AZURE_ARCH_SKILL_BASE_URL must use https; got ${u.protocol}`);
-    }
-    if (!ALLOWED_BASE_URL_HOSTS.has(u.hostname)) {
-        throw new Error(`AZURE_ARCH_SKILL_BASE_URL host '${u.hostname}' not in allow-list (${[...ALLOWED_BASE_URL_HOSTS].join(", ")})`);
+    if (override) {
+        let u;
+        try {
+            u = new URL(override);
+        }
+        catch {
+            throw new Error(`AZURE_ARCH_SKILL_BASE_URL is not a valid URL: ${override}`);
+        }
+        if (u.protocol !== "https:") {
+            throw new Error(`AZURE_ARCH_SKILL_BASE_URL must use https; got ${u.protocol}`);
+        }
+        if (!ALLOWED_BASE_URL_HOSTS.has(u.hostname)) {
+            throw new Error(`AZURE_ARCH_SKILL_BASE_URL host '${u.hostname}' not in allow-list (${[...ALLOWED_BASE_URL_HOSTS].join(", ")})`);
+        }
+        if (!u.pathname.startsWith(ALLOWED_BASE_URL_PATH_PREFIX)) {
+            throw new Error(`AZURE_ARCH_SKILL_BASE_URL path must start with ${ALLOWED_BASE_URL_PATH_PREFIX}`);
+        }
+        process.stderr.write(`warn: AZURE_ARCH_SKILL_BASE_URL override active: ${override}\n`);
+        return override.replace(/\/$/, "");
     }
-    if (!u.pathname.startsWith(ALLOWED_BASE_URL_PATH_PREFIX)) {
-        throw new Error(`AZURE_ARCH_SKILL_BASE_URL path must start with ${ALLOWED_BASE_URL_PATH_PREFIX}`);
+    if (version !== undefined) {
+        if (!VERSION_RE.test(version)) {
+            throw new Error(`--version must match X.Y.Z (got: ${version})`);
+        }
+        return `${RAW_BASE_NO_REF}/skill-v${version}`;
     }
-    process.stderr.write(`warn: AZURE_ARCH_SKILL_BASE_URL override active: ${override}\n`);
-    return override.replace(/\/$/, "");
+    return exports.DEFAULT_BASE_RAW_URL;
 }
 exports.baseUrl = baseUrl;
 let envTargetRootWarned = false;
@@ -206,6 +228,11 @@ async function fetchManifest(base) {
             throw new Error(`manifest ${url} missing required field: ${key}`);
         }
     }
+    if (m.icons_version !== undefined) {
+        if (typeof m.icons_version !== "string" || !/^\d+\.\d+\.\d+$/.test(m.icons_version)) {
+            throw new Error(`manifest ${url} icons_version malformed (must match X.Y.Z): ${String(m.icons_version)}`);
+        }
+    }
     if (!Array.isArray(m.files) || m.files.length === 0) {
         throw new Error(`manifest ${url} files[] missing or empty`);
     }
@@ -272,6 +299,105 @@ function stripFrontmatter(md) {
     return match ? text.slice(match[0].length) : text;
 }
 exports.stripFrontmatter = stripFrontmatter;
+/**
+ * Test whether an icons-tag semver satisfies the SKILL.md's `requires_icons`
+ * constraint. Hand-rolled to keep the runtime dep tree minimal (commander +
+ * nothing else; pulling in `semver` would add transitive deps for a feature
+ * that today only needs `>=X.Y.Z` matching).
+ *
+ * Supported constraint forms:
+ *   - "X.Y.Z"     (exact match)
+ *   - ">=X.Y.Z"   (tag >= constraint)
+ *   - "^X.Y.Z"    (same major, tag >= constraint — npm caret semantics)
+ *   - "~X.Y.Z"    (same major.minor, tag.patch >= constraint.patch)
+ *
+ * Throws on any other input. The project's SKILL.md frontmatter only ships
+ * `>=X.Y.Z` today; the other 3 forms exist for future-proofing.
+ *
+ * Numeric encoding `maj * 1e6 + min * 1e3 + pat` rules out individual segments
+ * >= 1000 — if a future icons release ever bumps any segment to 4 digits the
+ * encoding silently collides (e.g. 1.0.1000 vs 1.1.0). We hard-fail on that
+ * input rather than mis-compare.
+ */
+const SEMVER_SEGMENT_MAX = 999;
+function satisfiesRequiresIcons(constraint, iconsSemver) {
+    const tagParts = iconsSemver.split(".").map(Number);
+    if (tagParts.length !== 3 || tagParts.some(n => isNaN(n))) {
+        throw new Error(`icons semver malformed: ${iconsSemver}`);
+    }
+    const [tagMaj, tagMin, tagPat] = tagParts;
+    if (tagMaj > SEMVER_SEGMENT_MAX || tagMin > SEMVER_SEGMENT_MAX || tagPat > SEMVER_SEGMENT_MAX) {
+        throw new Error(`icons semver segment exceeds matcher capacity (${SEMVER_SEGMENT_MAX}): ${iconsSemver}`);
+    }
+    const trimmed = constraint.trim().replace(/^["']|["']$/g, "");
+    const m = trimmed.match(/^(>=|\^|~|)(\d+)\.(\d+)\.(\d+)$/);
+    if (!m) {
+        throw new Error(`requires_icons constraint form not supported: ${constraint}`);
+    }
+    const [, op, majS, minS, patS] = m;
+    const maj = Number(majS);
+    const min = Number(minS);
+    const pat = Number(patS);
+    if (maj > SEMVER_SEGMENT_MAX || min > SEMVER_SEGMENT_MAX || pat > SEMVER_SEGMENT_MAX) {
+        throw new Error(`requires_icons segment exceeds matcher capacity (${SEMVER_SEGMENT_MAX}): ${constraint}`);
+    }
+    const tag = tagMaj * 1e6 + tagMin * 1e3 + tagPat;
+    const ref = maj * 1e6 + min * 1e3 + pat;
+    if (op === "")
+        return tag === ref;
+    if (op === ">=")
+        return tag >= ref;
+    if (op === "^")
+        return tagMaj === maj && tag >= ref;
+    if (op === "~")
+        return tagMaj === maj && tagMin === min && tagPat >= pat;
+    throw new Error(`unreachable constraint op: ${op}`);
+}
+exports.satisfiesRequiresIcons = satisfiesRequiresIcons;
+/**
+ * Verify the icon set the skill bundle references is reachable AND its
+ * semver satisfies SKILL.md's requires_icons.
+ *
+ * Source of the icons-tag, in priority order:
+ *   1. `manifest.icons_version` — exact tag (preferred).
+ *   2. Lower-bound parse of `manifest.requires_icons` — fallback for
+ *      bundles published before the field landed (cannot be edited
+ *      retroactively on a tag).
+ *
+ * The fallback path makes the gate trivially pass by construction (a
+ * lower bound always satisfies its own constraint), preserving install
+ * behaviour for older tags. New bundles ship the field, so the gate
+ * becomes a real cross-track compatibility check going forward.
+ */
+async function verifyIconsAvailability(base, manifest, requestedVersion) {
+    const requires = manifest.requires_icons;
+    const canaryUrl = `${base}/${exports.CANARY_ICON_PATH}`;
+    const reachable = await headOk(canaryUrl);
+    if (!reachable) {
+        throw new Error(`icon-set unreachable - HEAD ${canaryUrl} failed (skill declares requires_icons=${requires})`);
+    }
+    if (!requestedVersion) {
+        return;
+    }
+    let iconsTagSemver;
+    let source;
+    if (manifest.icons_version) {
+        iconsTagSemver = manifest.icons_version;
+        source = `manifest icons_version`;
+    }
+    else {
+        const lowerMatch = requires.match(/(\d+\.\d+\.\d+)/);
+        if (!lowerMatch) {
+            throw new Error(`SKILL.md requires_icons has no parseable lower bound: ${requires}`);
+        }
+        iconsTagSemver = lowerMatch[1];
+        source = `requires_icons lower-bound (bundle has no icons_version field)`;
+    }
+    if (!satisfiesRequiresIcons(requires, iconsTagSemver)) {
+        throw new Error(`requires_icons constraint ${requires} not satisfied by ${source} ${iconsTagSemver}`);
+    }
+}
+exports.verifyIconsAvailability = verifyIconsAvailability;
 async function withFatalReturn(fn) {
     try {
         return await fn();
@@ -282,3 +408,117 @@ async function withFatalReturn(fn) {
     }
 }
 exports.withFatalReturn = withFatalReturn;
+function makeFolderInstallAdapter(cfg) {
+    const defaultTarget = () => path.join(cfg.rootDir(), "skills", exports.SKILL_NAME);
+    const defaultSkillsRoot = () => path.join(cfg.rootDir(), "skills");
+    const resolve = (target) => safeResolveTarget(target, cfg.rootDir(), cfg.rootDisplay());
+    const isOurSkillDir = async (dir) => {
+        try {
+            const skillMd = await fs.readFile(path.join(dir, "SKILL.md"), "utf8");
+            return parseFrontmatter(skillMd).name === exports.SKILL_NAME;
+        }
+        catch {
+            return false;
+        }
+    };
+    async function install(opts) {
+        return withFatalReturn(async () => {
+            const target = await resolve(opts.target ?? defaultTarget());
+            const base = baseUrl(opts.version);
+            if (!process.env.AZURE_ARCH_SKILL_TARGET_ROOT && path.basename(target) !== exports.SKILL_NAME) {
+                throw new Error(`refusing to install at ${target} - target basename must be '${exports.SKILL_NAME}' (default ${cfg.rootDisplay()}/skills/${exports.SKILL_NAME}/). Set AZURE_ARCH_SKILL_TARGET_ROOT to install into a custom test root.`);
+            }
+            const manifest = await fetchManifest(base);
+            if (manifest.name !== exports.SKILL_NAME) {
+                throw new Error(`manifest name mismatch: expected '${exports.SKILL_NAME}', got '${manifest.name}'. CLI and bundle are out of sync.`);
+            }
+            const presence = await Promise.all(manifest.files.map(async ({ dest }) => ({
+                dest,
+                exists: await fs.stat(path.join(target, dest)).then(() => true).catch(() => false),
+            })));
+            const someExist = presence.some(p => p.exists);
+            const allExist = presence.every(p => p.exists);
+            if (someExist && !opts.overwrite) {
+                throw new Error(allExist
+                    ? `${target} already contains an install. Run 'azure-arch-skill update --agent=${cfg.agentFlag}' to refresh.`
+                    : `${target} contains a partial install (${presence.filter(p => !p.exists).map(p => p.dest).join(", ")} missing). Run 'azure-arch-skill update --agent=${cfg.agentFlag}' to repair.`);
+            }
+            const skillUrl = `${base}/${manifest.files[0].src}`;
+            const skillMd = await fetchText(skillUrl);
+            const fm = parseFrontmatter(skillMd);
+            if (!fm.requires_icons) {
+                throw new Error("SKILL.md missing requires_icons frontmatter");
+            }
+            await verifyIconsAvailability(base, manifest, opts.version);
+            for (const { dest } of manifest.files) {
+                await fs.mkdir(path.dirname(path.join(target, dest)), { recursive: true });
+            }
+            await fs.writeFile(path.join(target, manifest.files[0].dest), skillMd, "utf8");
+            for (const { src, dest } of manifest.files.slice(1)) {
+                const body = await fetchText(`${base}/${src}`);
+                await fs.writeFile(path.join(target, dest), body, "utf8");
+            }
+            process.stdout.write(`installed ${exports.SKILL_NAME} to ${target}\n`);
+            return 0;
+        });
+    }
+    async function uninstall(opts) {
+        return withFatalReturn(async () => {
+            const target = await resolve(opts.target ?? defaultTarget());
+            const exists = await fs.stat(target).then(() => true).catch(() => false);
+            if (!exists) {
+                process.stdout.write(`(nothing to uninstall at ${target})\n`);
+                return 0;
+            }
+            const ours = await isOurSkillDir(target);
+            if (!ours) {
+                throw new Error(`refusing to remove ${target} - not an azure-architecture-diagram skill folder (no matching SKILL.md). Move/rename the directory or remove it manually if intentional.`);
+            }
+            try {
+                await fs.rm(target, { recursive: true, force: false });
+            }
+            catch (err) {
+                const stillExists = await fs.stat(target).then(() => true).catch(() => false);
+                if (stillExists) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new Error(`uninstall partially failed at ${target}: ${msg}; manual cleanup may be required`);
+                }
+                throw err;
+            }
+            process.stdout.write(`uninstalled ${exports.SKILL_NAME} from ${target}\n`);
+            return 0;
+        });
+    }
+    async function update(opts) {
+        return install({ ...opts, overwrite: true });
+    }
+    async function list(opts) {
+        return withFatalReturn(async () => {
+            const root = await resolve(opts.target ?? defaultSkillsRoot());
+            const exists = await fs.stat(root).then(() => true).catch(() => false);
+            if (!exists) {
+                process.stdout.write("(no skills installed)\n");
+                return 0;
+            }
+            const entries = await fs.readdir(root, { withFileTypes: true });
+            const rows = [];
+            for (const e of entries) {
+                if (!e.isDirectory())
+                    continue;
+                const skillMdPath = path.join(root, e.name, "SKILL.md");
+                try {
+                    const md = await fs.readFile(skillMdPath, "utf8");
+                    const fm = parseFrontmatter(md);
+                    rows.push(`${fm.name ?? e.name}\t${fm.version ?? "?"}`);
+                }
+                catch {
+                    // not a skill folder; skip silently
+                }
+            }
+            process.stdout.write(rows.length ? rows.join("\n") + "\n" : "(no skills installed)\n");
+            return 0;
+        });
+    }
+    return { install, uninstall, update, list };
+}
+exports.makeFolderInstallAdapter = makeFolderInstallAdapter;

package/dist/adapters/claude-code.js

@@ -24,7 +24,6 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeAdapter = exports.parseFrontmatter = exports.fetchWithTimeout = void 0;
-const fs = __importStar(require("node:fs/promises"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const _shared_1 = require("./_shared");
@@ -33,131 +32,8 @@ Object.defineProperty(exports, "parseFrontmatter", { enumerable: true, get: func
 function claudeRootDir() {
     return path.join(os.homedir(), ".claude");
 }
-function defaultTarget() {
-    return path.join(claudeRootDir(), "skills", _shared_1.SKILL_NAME);
-}
-function defaultSkillsRoot() {
-    return path.join(claudeRootDir(), "skills");
-}
-const CLAUDE_ROOT_DISPLAY = "~/.claude";
-async function resolveTarget(target) {
-    return (0, _shared_1.safeResolveTarget)(target, claudeRootDir(), CLAUDE_ROOT_DISPLAY);
-}
-/**
- * Returns true iff `dir` contains a SKILL.md whose frontmatter `name` field
- * matches our skill. Used by uninstall to refuse deleting paths that aren't
- * our skill folder.
- */
-async function isOurSkillDir(dir) {
-    try {
-        const skillMd = await fs.readFile(path.join(dir, "SKILL.md"), "utf8");
-        const fm = (0, _shared_1.parseFrontmatter)(skillMd);
-        return fm.name === _shared_1.SKILL_NAME;
-    }
-    catch {
-        return false;
-    }
-}
-async function install(opts) {
-    return (0, _shared_1.withFatalReturn)(async () => {
-        const target = await resolveTarget(opts.target ?? defaultTarget());
-        const base = (0, _shared_1.baseUrl)();
-        if (!process.env.AZURE_ARCH_SKILL_TARGET_ROOT && path.basename(target) !== _shared_1.SKILL_NAME) {
-            throw new Error(`refusing to install at ${target} - target basename must be '${_shared_1.SKILL_NAME}' (default ~/.claude/skills/${_shared_1.SKILL_NAME}/). Set AZURE_ARCH_SKILL_TARGET_ROOT to install into a custom test root.`);
-        }
-        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 presence = await Promise.all(manifest.files.map(async ({ dest }) => ({
-            dest,
-            exists: await fs.stat(path.join(target, dest)).then(() => true).catch(() => false),
-        })));
-        const someExist = presence.some(p => p.exists);
-        const allExist = presence.every(p => p.exists);
-        if (someExist && !opts.overwrite) {
-            throw new Error(allExist
-                ? `${target} already contains an install. Run 'azure-arch-skill update --agent=claude-code' to refresh.`
-                : `${target} contains a partial install (${presence.filter(p => !p.exists).map(p => p.dest).join(", ")} missing). Run 'azure-arch-skill update --agent=claude-code' to repair.`);
-        }
-        const skillUrl = `${base}/${manifest.files[0].src}`;
-        const skillMd = await (0, _shared_1.fetchText)(skillUrl);
-        const fm = (0, _shared_1.parseFrontmatter)(skillMd);
-        if (!fm.requires_icons) {
-            throw new Error("SKILL.md missing requires_icons frontmatter");
-        }
-        const canaryUrl = `${base}/${_shared_1.CANARY_ICON_PATH}`;
-        const reachable = await (0, _shared_1.headOk)(canaryUrl);
-        if (!reachable) {
-            throw new Error(`icon-set unreachable - HEAD ${canaryUrl} failed (skill declares requires_icons=${fm.requires_icons}; this release verifies reachability only, strict semver match planned)`);
-        }
-        for (const { dest } of manifest.files) {
-            await fs.mkdir(path.dirname(path.join(target, dest)), { recursive: true });
-        }
-        await fs.writeFile(path.join(target, manifest.files[0].dest), skillMd, "utf8");
-        for (const { src, dest } of manifest.files.slice(1)) {
-            const body = await (0, _shared_1.fetchText)(`${base}/${src}`);
-            await fs.writeFile(path.join(target, dest), body, "utf8");
-        }
-        process.stdout.write(`installed ${_shared_1.SKILL_NAME} to ${target}\n`);
-        return 0;
-    });
-}
-async function uninstall(opts) {
-    return (0, _shared_1.withFatalReturn)(async () => {
-        const target = await resolveTarget(opts.target ?? defaultTarget());
-        const exists = await fs.stat(target).then(() => true).catch(() => false);
-        if (!exists) {
-            process.stdout.write(`(nothing to uninstall at ${target})\n`);
-            return 0;
-        }
-        const ours = await isOurSkillDir(target);
-        if (!ours) {
-            throw new Error(`refusing to remove ${target} - not an azure-architecture-diagram skill folder (no matching SKILL.md). Move/rename the directory or remove it manually if intentional.`);
-        }
-        try {
-            await fs.rm(target, { recursive: true, force: false });
-        }
-        catch (err) {
-            const stillExists = await fs.stat(target).then(() => true).catch(() => false);
-            if (stillExists) {
-                const msg = err instanceof Error ? err.message : String(err);
-                throw new Error(`uninstall partially failed at ${target}: ${msg}; manual cleanup may be required`);
-            }
-            throw err;
-        }
-        process.stdout.write(`uninstalled ${_shared_1.SKILL_NAME} from ${target}\n`);
-        return 0;
-    });
-}
-async function update(opts) {
-    return install({ ...opts, overwrite: true });
-}
-async function list(opts) {
-    return (0, _shared_1.withFatalReturn)(async () => {
-        const root = await resolveTarget(opts.target ?? defaultSkillsRoot());
-        const exists = await fs.stat(root).then(() => true).catch(() => false);
-        if (!exists) {
-            process.stdout.write("(no skills installed)\n");
-            return 0;
-        }
-        const entries = await fs.readdir(root, { withFileTypes: true });
-        const rows = [];
-        for (const e of entries) {
-            if (!e.isDirectory())
-                continue;
-            const skillMdPath = path.join(root, e.name, "SKILL.md");
-            try {
-                const md = await fs.readFile(skillMdPath, "utf8");
-                const fm = (0, _shared_1.parseFrontmatter)(md);
-                rows.push(`${fm.name ?? e.name}\t${fm.version ?? "?"}`);
-            }
-            catch {
-                // not a skill folder; skip silently
-            }
-        }
-        process.stdout.write(rows.length ? rows.join("\n") + "\n" : "(no skills installed)\n");
-        return 0;
-    });
-}
-exports.claudeCodeAdapter = { install, uninstall, update, list };
+exports.claudeCodeAdapter = (0, _shared_1.makeFolderInstallAdapter)({
+    rootDir: claudeRootDir,
+    rootDisplay: () => "~/.claude",
+    agentFlag: "claude-code",
+});

package/dist/adapters/codex.js

@@ -24,7 +24,6 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codexAdapter = exports.parseFrontmatter = exports.fetchWithTimeout = void 0;
-const fs = __importStar(require("node:fs/promises"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const _shared_1 = require("./_shared");
@@ -36,128 +35,11 @@ function codexRootDir() {
         return path.resolve(explicit);
     return path.join(os.homedir(), ".codex");
 }
-function defaultTarget() {
-    return path.join(codexRootDir(), "skills", _shared_1.SKILL_NAME);
-}
-function defaultSkillsRoot() {
-    return path.join(codexRootDir(), "skills");
-}
 function codexRootDisplay() {
     return process.env.CODEX_HOME ? `$CODEX_HOME=${process.env.CODEX_HOME}` : "~/.codex";
 }
-async function resolveTarget(target) {
-    return (0, _shared_1.safeResolveTarget)(target, codexRootDir(), codexRootDisplay());
-}
-async function isOurSkillDir(dir) {
-    try {
-        const skillMd = await fs.readFile(path.join(dir, "SKILL.md"), "utf8");
-        const fm = (0, _shared_1.parseFrontmatter)(skillMd);
-        return fm.name === _shared_1.SKILL_NAME;
-    }
-    catch {
-        return false;
-    }
-}
-async function install(opts) {
-    return (0, _shared_1.withFatalReturn)(async () => {
-        const target = await resolveTarget(opts.target ?? defaultTarget());
-        const base = (0, _shared_1.baseUrl)();
-        if (!process.env.AZURE_ARCH_SKILL_TARGET_ROOT && path.basename(target) !== _shared_1.SKILL_NAME) {
-            throw new Error(`refusing to install at ${target} - target basename must be '${_shared_1.SKILL_NAME}' (default ${codexRootDisplay()}/skills/${_shared_1.SKILL_NAME}/). Set AZURE_ARCH_SKILL_TARGET_ROOT to install into a custom test root.`);
-        }
-        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 presence = await Promise.all(manifest.files.map(async ({ dest }) => ({
-            dest,
-            exists: await fs.stat(path.join(target, dest)).then(() => true).catch(() => false),
-        })));
-        const someExist = presence.some(p => p.exists);
-        const allExist = presence.every(p => p.exists);
-        if (someExist && !opts.overwrite) {
-            throw new Error(allExist
-                ? `${target} already contains an install. Run 'azure-arch-skill update --agent=codex' to refresh.`
-                : `${target} contains a partial install (${presence.filter(p => !p.exists).map(p => p.dest).join(", ")} missing). Run 'azure-arch-skill update --agent=codex' to repair.`);
-        }
-        const skillUrl = `${base}/${manifest.files[0].src}`;
-        const skillMd = await (0, _shared_1.fetchText)(skillUrl);
-        const fm = (0, _shared_1.parseFrontmatter)(skillMd);
-        if (!fm.requires_icons) {
-            throw new Error("SKILL.md missing requires_icons frontmatter");
-        }
-        const canaryUrl = `${base}/${_shared_1.CANARY_ICON_PATH}`;
-        const reachable = await (0, _shared_1.headOk)(canaryUrl);
-        if (!reachable) {
-            throw new Error(`icon-set unreachable - HEAD ${canaryUrl} failed (skill declares requires_icons=${fm.requires_icons}; this release verifies reachability only, strict semver match planned)`);
-        }
-        for (const { dest } of manifest.files) {
-            await fs.mkdir(path.dirname(path.join(target, dest)), { recursive: true });
-        }
-        await fs.writeFile(path.join(target, manifest.files[0].dest), skillMd, "utf8");
-        for (const { src, dest } of manifest.files.slice(1)) {
-            const body = await (0, _shared_1.fetchText)(`${base}/${src}`);
-            await fs.writeFile(path.join(target, dest), body, "utf8");
-        }
-        process.stdout.write(`installed ${_shared_1.SKILL_NAME} to ${target}\n`);
-        return 0;
-    });
-}
-async function uninstall(opts) {
-    return (0, _shared_1.withFatalReturn)(async () => {
-        const target = await resolveTarget(opts.target ?? defaultTarget());
-        const exists = await fs.stat(target).then(() => true).catch(() => false);
-        if (!exists) {
-            process.stdout.write(`(nothing to uninstall at ${target})\n`);
-            return 0;
-        }
-        const ours = await isOurSkillDir(target);
-        if (!ours) {
-            throw new Error(`refusing to remove ${target} - not an azure-architecture-diagram skill folder (no matching SKILL.md). Move/rename the directory or remove it manually if intentional.`);
-        }
-        try {
-            await fs.rm(target, { recursive: true, force: false });
-        }
-        catch (err) {
-            const stillExists = await fs.stat(target).then(() => true).catch(() => false);
-            if (stillExists) {
-                const msg = err instanceof Error ? err.message : String(err);
-                throw new Error(`uninstall partially failed at ${target}: ${msg}; manual cleanup may be required`);
-            }
-            throw err;
-        }
-        process.stdout.write(`uninstalled ${_shared_1.SKILL_NAME} from ${target}\n`);
-        return 0;
-    });
-}
-async function update(opts) {
-    return install({ ...opts, overwrite: true });
-}
-async function list(opts) {
-    return (0, _shared_1.withFatalReturn)(async () => {
-        const root = await resolveTarget(opts.target ?? defaultSkillsRoot());
-        const exists = await fs.stat(root).then(() => true).catch(() => false);
-        if (!exists) {
-            process.stdout.write("(no skills installed)\n");
-            return 0;
-        }
-        const entries = await fs.readdir(root, { withFileTypes: true });
-        const rows = [];
-        for (const e of entries) {
-            if (!e.isDirectory())
-                continue;
-            const skillMdPath = path.join(root, e.name, "SKILL.md");
-            try {
-                const md = await fs.readFile(skillMdPath, "utf8");
-                const fm = (0, _shared_1.parseFrontmatter)(md);
-                rows.push(`${fm.name ?? e.name}\t${fm.version ?? "?"}`);
-            }
-            catch {
-                // not a skill folder; skip silently
-            }
-        }
-        process.stdout.write(rows.length ? rows.join("\n") + "\n" : "(no skills installed)\n");
-        return 0;
-    });
-}
-exports.codexAdapter = { install, uninstall, update, list };
+exports.codexAdapter = (0, _shared_1.makeFolderInstallAdapter)({
+    rootDir: codexRootDir,
+    rootDisplay: codexRootDisplay,
+    agentFlag: "codex",
+});

package/dist/adapters/cursor.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cursorAdapter = exports.parseFrontmatter = exports.fetchWithTimeout = void 0;
+exports.cursorAdapter = exports.PROVENANCE_RE = exports.provenanceMarker = exports.parseFrontmatter = exports.fetchWithTimeout = void 0;
 const fs = __importStar(require("node:fs/promises"));
 const path = __importStar(require("node:path"));
 const _shared_1 = require("./_shared");
@@ -33,6 +33,11 @@ const RULE_BASENAME = "azure-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\", \"create deployment diagram\", \"Lakehouse + Notebook + Warehouse diagram\", " +
     "\"vẽ Azure\", \"PlantUML diagram for [project]\".";
+// 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");
 }
@@ -40,15 +45,15 @@ const CWD_DISPLAY = "<cwd>/.cursor/rules";
 async function resolveTarget(target) {
     return (0, _shared_1.safeResolveTarget)(target, process.cwd(), CWD_DISPLAY);
 }
-/**
- * Provenance marker emitted into the rendered .mdc body so `list` / `uninstall`
- * can recognise our rule without re-fetching upstream. The marker is the first
- * non-frontmatter line after the closing `---`.
- */
+// `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}) -->`;
 }
+exports.provenanceMarker = provenanceMarker;
 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 [
         "---",
@@ -75,8 +80,11 @@ async function isOurRuleFile(file) {
 }
 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)();
+        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.
@@ -90,11 +98,7 @@ async function install(opts) {
         if (!fm.requires_icons) {
             throw new Error("SKILL.md missing requires_icons frontmatter");
         }
-        const canaryUrl = `${base}/${_shared_1.CANARY_ICON_PATH}`;
-        const reachable = await (0, _shared_1.headOk)(canaryUrl);
-        if (!reachable) {
-            throw new Error(`icon-set unreachable - HEAD ${canaryUrl} failed (skill declares requires_icons=${fm.requires_icons}; this release verifies reachability only, strict semver match planned)`);
-        }
+        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);

package/dist/all.js

@@ -50,6 +50,7 @@ async function runOverAll(sub, opts) {
 exports.runOverAll = runOverAll;
 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 };
     }

package/dist/index.js

@@ -8,42 +8,44 @@ const commander_1 = require("commander");
 const package_json_1 = __importDefault(require("../package.json"));
 const registry_1 = require("./adapters/registry");
 const all_1 = require("./all");
-function pickAdapter(agent) {
-    if (!(agent in registry_1.ADAPTERS)) {
-        throw new Error(`unknown agent: ${agent} (supported: ${registry_1.SUPPORTED_TARGETS.join(", ")})`);
-    }
-    return registry_1.ADAPTERS[agent];
-}
 const program = new commander_1.Command()
     .name("azure-arch-skill")
     .description("Install the Azure architecture diagram skill into your AI coding agent.")
     .version(package_json_1.default.version, "-V, --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)")
+        .option("--version <semver>", "pin to a specific skill version (X.Y.Z); default = latest from main")
         .action(async (opts) => {
-        // Set process.exitCode so any pending async cleanup (file handles, the
-        // override-warning stderr write) drains before the event loop empties.
-        // Both this top-level path and adapter-internal failures emit a single
-        // '^fatal: ' prefix line on stderr — log-parsers can rely on the prefix.
-        const optsForAdapter = { target: opts.target };
+        // 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_TARGETS.join(", ")})`);
+            throw new Error(`unknown agent: ${opts.agent} (supported: ${registry_1.SUPPORTED_AGENTS.join(", ")})`);
         }
-        process.exitCode = await pickAdapter(opts.agent)[name](optsForAdapter);
+        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,6 +1,6 @@
 {
   "name": "@hanv89/azure-arch-skill",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Install the Azure architecture diagram skill into your AI coding agent (Claude Code, Codex CLI, Cursor).",
   "bin": {
     "azure-arch-skill": "dist/index.js"