@hanv89/azure-arch-skill 0.7.0 → 0.9.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.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;
+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"));
@@ -228,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`);
     }
@@ -310,14 +315,20 @@ exports.stripFrontmatter = stripFrontmatter;
  * `>=X.Y.Z` today; the other 3 forms exist for future-proofing.
  *
  * Numeric encoding `maj * 1e6 + min * 1e3 + pat` rules out individual segments
- * >= 1000, which is fine for icons semver in the foreseeable future.
+ * >= 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) {
@@ -327,6 +338,9 @@ function satisfiesRequiresIcons(constraint, iconsSemver) {
     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 === "")
@@ -344,32 +358,43 @@ exports.satisfiesRequiresIcons = satisfiesRequiresIcons;
  * Verify the icon set the skill bundle references is reachable AND its
  * semver satisfies SKILL.md's requires_icons.
  *
- * - Always: HEAD the canary icon URL (`CANARY_ICON_PATH` at the current base).
- *   Unreachable → throw with the URL in the message.
- * - If `requestedVersion` is provided: additionally infer the icons-tag from
- *   `manifest.requires_icons`'s lower bound and assert it satisfies the
- *   constraint via `satisfiesRequiresIcons`. The inference is intentionally
- *   simple: `requires_icons` lower bound IS the icons-tag the skill was
- *   built against. Future work: record an exact `icons_version` field in
- *   `manifest.json` and read it here directly.
+ * 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}; this release verifies reachability only, strict semver match planned)`);
+        throw new Error(`icon-set unreachable - HEAD ${canaryUrl} failed (skill declares requires_icons=${requires})`);
     }
     if (!requestedVersion) {
         return;
     }
-    const lowerMatch = requires.match(/(\d+\.\d+\.\d+)/);
-    if (!lowerMatch) {
-        throw new Error(`SKILL.md requires_icons has no parseable lower bound: ${requires}`);
+    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)`;
     }
-    const iconsTagSemver = lowerMatch[1];
     if (!satisfiesRequiresIcons(requires, iconsTagSemver)) {
-        throw new Error(`requires_icons constraint ${requires} not satisfied by inferred icons tag ${iconsTagSemver}`);
+        throw new Error(`requires_icons constraint ${requires} not satisfied by ${source} ${iconsTagSemver}`);
     }
 }
 exports.verifyIconsAvailability = verifyIconsAvailability;
@@ -383,3 +408,190 @@ async function withFatalReturn(fn) {
     }
 }
 exports.withFatalReturn = withFatalReturn;
+// Persisted at install time so uninstall can iterate the file list without
+// re-fetching the manifest over the network. Hidden filename so it doesn't
+// clutter the user-visible skill folder.
+const PERSISTED_MANIFEST_BASENAME = ".azure-arch-skill-manifest.json";
+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");
+            }
+            // Persist the manifest so uninstall can iterate the file list without
+            // re-fetching from the network.
+            await fs.writeFile(path.join(target, PERSISTED_MANIFEST_BASENAME), JSON.stringify(manifest, null, 2) + "\n", "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.`);
+            }
+            // Manifest-scoped removal: read the persisted manifest at install time
+            // and remove only its files + the manifest itself. Leaves any
+            // user-authored content under the same folder in place (with a note).
+            // Fallback: bundles installed before 0.9.0 have no persisted manifest;
+            // legacy whole-folder rm preserves the pre-0.9.0 behaviour.
+            const persistedPath = path.join(target, PERSISTED_MANIFEST_BASENAME);
+            const manifestBody = await fs.readFile(persistedPath, "utf8").catch(() => null);
+            if (!manifestBody) {
+                // Legacy uninstall: rm -rf whole folder.
+                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;
+                }
+            }
+            else {
+                let persistedManifest;
+                try {
+                    persistedManifest = JSON.parse(manifestBody);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new Error(`persisted manifest at ${persistedPath} is not valid JSON: ${msg}. Remove the file manually then retry.`);
+                }
+                for (const f of persistedManifest.files) {
+                    await fs.unlink(path.join(target, f.dest)).catch(() => null);
+                }
+                await fs.unlink(persistedPath).catch(() => null);
+                // Recursively prune empty directories under target. Stop at target
+                // itself — only rmdir target if no user-authored files remain.
+                const pruneEmptyDirs = async (dir) => {
+                    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+                    for (const e of entries) {
+                        if (e.isDirectory()) {
+                            await pruneEmptyDirs(path.join(dir, e.name));
+                            const subEntries = await fs.readdir(path.join(dir, e.name)).catch(() => []);
+                            if (subEntries.length === 0) {
+                                await fs.rmdir(path.join(dir, e.name)).catch(() => null);
+                            }
+                        }
+                    }
+                };
+                await pruneEmptyDirs(target);
+                const remaining = await fs.readdir(target).catch(() => []);
+                if (remaining.length === 0) {
+                    await fs.rmdir(target).catch(() => null);
+                }
+                else {
+                    process.stdout.write(`note: ${target} contains files outside the skill manifest; left in place. Remove manually if intentional.\n`);
+                }
+            }
+            process.stdout.write(`uninstalled ${exports.SKILL_NAME} from ${target}\n`);
+            return 0;
+        });
+    }
+    async function update(opts) {
+        return withFatalReturn(async () => {
+            const target = await resolve(opts.target ?? defaultTarget());
+            const base = baseUrl(opts.version);
+            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.`);
+            }
+            // Already-at-version short-circuit: read the on-disk SKILL.md
+            // frontmatter version and compare to manifest. Equal -> no-op.
+            const installedSkillMdPath = path.join(target, "SKILL.md");
+            const installedBody = await fs.readFile(installedSkillMdPath, "utf8").catch(() => null);
+            if (installedBody) {
+                const fmInstalled = parseFrontmatter(installedBody);
+                if (fmInstalled.version && fmInstalled.version === manifest.version) {
+                    process.stdout.write(`${exports.SKILL_NAME} already at version ${manifest.version} (no-op)\n`);
+                    return 0;
+                }
+            }
+            // Otherwise proceed with overwriting install (the existing path).
+            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,127 +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)(opts.version);
-        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");
-        }
-        await (0, _shared_1.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 (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,124 +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)(opts.version);
-        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");
-        }
-        await (0, _shared_1.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 (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,6 +80,9 @@ 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)(opts.version);
         const ruleFile = path.join(targetDir, RULE_BASENAME);

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,12 +8,6 @@ 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.")
@@ -27,10 +21,8 @@ function defineSubcommand(name, description) {
         .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.
+        // 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})`);
         }
@@ -40,15 +32,20 @@ function defineSubcommand(name, description) {
             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.7.0",
+  "version": "0.9.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"