@hanv89/azure-arch-skill 0.3.0 → 0.4.0

package/dist/adapters/_shared.js

@@ -0,0 +1,270 @@
+"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;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFatalReturn = 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"));
+// Shared adapter plumbing. Helpers here must be agent-agnostic — anything
+// Claude-Code-specific (default install path, allowed root) lives in the
+// 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";
+// 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
+// (uninstall's allow-list refuses folders whose SKILL.md `name` differs).
+exports.SKILL_NAME = "azure-architecture-diagram";
+// Fetched at install/update time from dist/skill/manifest.json. files[0] MUST
+// be SKILL.md so the frontmatter precheck has a stable target.
+exports.MANIFEST_PATH = "dist/skill/manifest.json";
+exports.CANARY_ICON_PATH = "dist/Azure/Compute/AzureVirtualMachine.png";
+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() {
+    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 (!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(/\/$/, "");
+}
+exports.baseUrl = baseUrl;
+let envTargetRootWarned = false;
+/**
+ * Resolve `target` and assert it lives inside an allowed root. Resolution
+ * follows symlinks (via fs.realpath on the deepest existing ancestor) so
+ * a symlink inside an allowed root that points outside cannot bypass the
+ * check.
+ *
+ * `defaultAllowedRoot` is supplied by the adapter (e.g. `~/.claude` for the
+ * Claude Code adapter, `~/.codex` for a future Codex adapter). Setting the
+ * `AZURE_ARCH_SKILL_TARGET_ROOT` env var widens the allow-list to include
+ * that root (intended for validation/CI use against a `mktemp -d` directory).
+ * Production users should never set the env var.
+ *
+ * `displayName` controls how the default root appears in error messages
+ * when the check fails (e.g. `~/.claude` instead of `/home/user/.claude`).
+ * Defaults to the resolved absolute path.
+ */
+async function safeResolveTarget(target, defaultAllowedRoot, displayName = defaultAllowedRoot) {
+    const lexicallyResolved = path.resolve(target);
+    let probe = lexicallyResolved;
+    let realProbe = null;
+    while (true) {
+        try {
+            realProbe = await fs.realpath(probe);
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw err;
+            const parent = path.dirname(probe);
+            if (parent === probe) {
+                throw new Error(`unable to resolve target ${target}`);
+            }
+            probe = parent;
+        }
+    }
+    const tail = lexicallyResolved.slice(probe.length);
+    const realResolved = path.resolve(realProbe + tail);
+    const explicit = process.env.AZURE_ARCH_SKILL_TARGET_ROOT;
+    if (explicit && !envTargetRootWarned) {
+        process.stderr.write(`warn: AZURE_ARCH_SKILL_TARGET_ROOT override active: ${explicit}\n`);
+        envTargetRootWarned = true;
+    }
+    const allowedRoots = [
+        path.resolve(defaultAllowedRoot),
+        explicit ? path.resolve(explicit) : null,
+    ].filter((r) => r !== null);
+    const inside = allowedRoots.some(root => realResolved === root || realResolved.startsWith(root + path.sep));
+    if (!inside) {
+        const allowList = `${displayName}${explicit ? `, $AZURE_ARCH_SKILL_TARGET_ROOT=${explicit}` : ""}`;
+        throw new Error(`refusing to operate on ${realResolved} (resolved from ${target}) - outside allowed roots (${allowList})`);
+    }
+    return realResolved;
+}
+exports.safeResolveTarget = safeResolveTarget;
+/**
+ * Fetch with timeout and 2-retry exponential backoff on transient 5xx
+ * responses. Used by `fetchText` and `headOk`; both inherit the retry
+ * behavior. The 2-retry default was added to absorb transient 5xx upstream
+ * errors — future agent adapters reusing this helper get the retry path
+ * for free.
+ *
+ * Backoff schedule: 500ms after attempt 0, 1s after attempt 1, 2s after
+ * attempt 2. Network errors (AbortError, DNS failures) re-throw only
+ * after the final attempt.
+ *
+ * @internal — exported only so unit tests can mock `globalThis.fetch`
+ *             around it. Not part of the public adapter API.
+ */
+async function fetchWithTimeout(url, init = {}, retries = 2) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), exports.FETCH_TIMEOUT_MS);
+        try {
+            const res = await fetch(url, {
+                ...init,
+                signal: ctrl.signal,
+                headers: { ...(init.headers || {}), "User-Agent": exports.USER_AGENT },
+            });
+            if (res.status < 500 || attempt === retries) {
+                return res;
+            }
+        }
+        catch (e) {
+            lastError = e;
+            if (attempt === retries)
+                throw e;
+        }
+        finally {
+            clearTimeout(t);
+        }
+        await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
+    }
+    throw lastError ?? new Error("fetchWithTimeout: exhausted retries");
+}
+exports.fetchWithTimeout = fetchWithTimeout;
+async function fetchText(url) {
+    const res = await fetchWithTimeout(url);
+    if (!res.ok)
+        throw new Error(`fetch ${url} returned HTTP ${res.status}`);
+    return res.text();
+}
+exports.fetchText = fetchText;
+async function headOk(url) {
+    const res = await fetchWithTimeout(url, { method: "HEAD" });
+    return res.ok;
+}
+exports.headOk = headOk;
+/**
+ * Fetch + parse the bundle manifest. Validates required fields and the
+ * SKILL.md-at-index-0 invariant. Throws with a clear error on any issue —
+ * callers should not silently fall back.
+ */
+async function fetchManifest(base) {
+    const url = `${base}/${exports.MANIFEST_PATH}`;
+    const body = await fetchText(url);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (err) {
+        throw new Error(`manifest ${url} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`manifest ${url} did not parse to an object`);
+    }
+    const m = parsed;
+    for (const key of ["name", "version", "requires_icons"]) {
+        if (typeof m[key] !== "string" || !m[key]) {
+            throw new Error(`manifest ${url} missing required field: ${key}`);
+        }
+    }
+    if (!Array.isArray(m.files) || m.files.length === 0) {
+        throw new Error(`manifest ${url} files[] missing or empty`);
+    }
+    for (const [i, f] of m.files.entries()) {
+        if (!f || typeof f !== "object") {
+            throw new Error(`manifest ${url} files[${i}] not an object`);
+        }
+        for (const key of ["src", "dest", "role"]) {
+            if (typeof f[key] !== "string") {
+                throw new Error(`manifest ${url} files[${i}].${key} missing`);
+            }
+        }
+    }
+    if (m.files[0].dest !== "SKILL.md" || m.files[0].role !== "skill") {
+        throw new Error(`manifest ${url} files[0] must be SKILL.md (role=skill); got dest=${m.files[0].dest} role=${m.files[0].role}`);
+    }
+    return m;
+}
+exports.fetchManifest = fetchManifest;
+/**
+ * Minimal YAML frontmatter parser — supports only single-line scalar `key: value`
+ * pairs with optional `"` or `'` quoting. Multi-line scalars (`|`, `>`), nested
+ * mappings, lists, comments after `#`, and YAML null/booleans are NOT handled
+ * and may silently mis-parse.
+ *
+ * Intentional: SKILL.md frontmatter currently has 4 single-line scalar keys
+ * (name, description, version, requires_icons). Swap in `js-yaml` when the
+ * format grows beyond that.
+ */
+function parseFrontmatter(md) {
+    const text = md.replace(/^/, "");
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const out = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = line.match(/^(\w+):\s*(.*?)\s*$/);
+        if (!kv)
+            continue;
+        const [, key] = kv;
+        let rawValue = kv[2];
+        if (!rawValue.startsWith('"') && !rawValue.startsWith("'")) {
+            rawValue = rawValue.replace(/\s+#.*$/, "");
+        }
+        const value = rawValue.replace(/^["']|["']$/g, "");
+        if (key === "name" || key === "version" || key === "requires_icons") {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+exports.parseFrontmatter = parseFrontmatter;
+async function withFatalReturn(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+exports.withFatalReturn = withFatalReturn;

package/dist/adapters/claude-code.js

@@ -22,242 +22,27 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": 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 package_json_1 = __importDefault(require("../../package.json"));
-const DEFAULT_BASE_RAW_URL = "https://raw.githubusercontent.com/hanv89/azure-icons-for-architecture-diagrams/main";
-// 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
-// (uninstall's allow-list refuses folders whose SKILL.md `name` differs).
-const SKILL_NAME = "azure-architecture-diagram";
-// Fetched at install/update time from dist/skill/manifest.json. files[0] MUST
-// be SKILL.md so the frontmatter precheck has a stable target.
-const MANIFEST_PATH = "dist/skill/manifest.json";
-const CANARY_ICON_PATH = "dist/Azure/Compute/AzureVirtualMachine.png";
-const FETCH_TIMEOUT_MS = 30_000;
-const 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() {
-    const override = process.env.AZURE_ARCH_SKILL_BASE_URL;
-    if (!override)
-        return 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 (!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(/\/$/, "");
+const _shared_1 = require("./_shared");
+Object.defineProperty(exports, "fetchWithTimeout", { enumerable: true, get: function () { return _shared_1.fetchWithTimeout; } });
+Object.defineProperty(exports, "parseFrontmatter", { enumerable: true, get: function () { return _shared_1.parseFrontmatter; } });
+function claudeRootDir() {
+    return path.join(os.homedir(), ".claude");
 }
 function defaultTarget() {
-    return path.join(os.homedir(), ".claude", "skills", SKILL_NAME);
+    return path.join(claudeRootDir(), "skills", _shared_1.SKILL_NAME);
 }
 function defaultSkillsRoot() {
-    return path.join(os.homedir(), ".claude", "skills");
-}
-let envTargetRootWarned = false;
-/**
- * Resolve `target` and assert it lives inside an allowed root. Resolution
- * follows symlinks (via fs.realpath on the deepest existing ancestor) so
- * a symlink inside an allowed root that points outside cannot bypass the
- * check.
- *
- * The default allow-list is `~/.claude/` only. Setting the
- * `AZURE_ARCH_SKILL_TARGET_ROOT` env var widens it to include that root
- * (intended for validation/CI use against a `mktemp -d` directory).
- * Production users should never set the env var.
- */
-async function safeResolveTarget(target) {
-    const lexicallyResolved = path.resolve(target);
-    // Walk up to the deepest existing ancestor and realpath it — install creates
-    // a not-yet-existing target so we can't realpath the leaf directly.
-    let probe = lexicallyResolved;
-    let realProbe = null;
-    while (true) {
-        try {
-            realProbe = await fs.realpath(probe);
-            break;
-        }
-        catch (err) {
-            const code = err.code;
-            if (code !== "ENOENT" && code !== "ENOTDIR")
-                throw err;
-            const parent = path.dirname(probe);
-            if (parent === probe) {
-                throw new Error(`unable to resolve target ${target}`);
-            }
-            probe = parent;
-        }
-    }
-    const tail = lexicallyResolved.slice(probe.length);
-    const realResolved = path.resolve(realProbe + tail);
-    const home = os.homedir();
-    const explicit = process.env.AZURE_ARCH_SKILL_TARGET_ROOT;
-    if (explicit && !envTargetRootWarned) {
-        process.stderr.write(`warn: AZURE_ARCH_SKILL_TARGET_ROOT override active: ${explicit}\n`);
-        envTargetRootWarned = true;
-    }
-    const allowedRoots = [
-        path.resolve(path.join(home, ".claude")),
-        explicit ? path.resolve(explicit) : null,
-    ].filter((r) => r !== null);
-    const inside = allowedRoots.some(root => realResolved === root || realResolved.startsWith(root + path.sep));
-    if (!inside) {
-        const allowList = `~/.claude${explicit ? `, $AZURE_ARCH_SKILL_TARGET_ROOT=${explicit}` : ""}`;
-        throw new Error(`refusing to operate on ${realResolved} (resolved from ${target}) - outside allowed roots (${allowList})`);
-    }
-    return realResolved;
-}
-/**
- * Fetch with timeout and 2-retry exponential backoff on transient 5xx
- * responses. Used by `fetchText` and `headOk`; both inherit the retry
- * behavior. Default `retries = 2` matches the R30 fix (Phase 1.0) —
- * future agent adapters reusing this helper get the retry path for free.
- *
- * Backoff schedule: 500ms after attempt 0, 1s after attempt 1, 2s after
- * attempt 2. Network errors (AbortError, DNS failures) re-throw only
- * after the final attempt.
- *
- * @internal — exported only so unit tests can mock `globalThis.fetch`
- *             around it. Not part of the public adapter API.
- */
-async function fetchWithTimeout(url, init = {}, retries = 2) {
-    let lastError;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
-        try {
-            const res = await fetch(url, {
-                ...init,
-                signal: ctrl.signal,
-                headers: { ...(init.headers || {}), "User-Agent": USER_AGENT },
-            });
-            if (res.status < 500 || attempt === retries) {
-                return res;
-            }
-            // 5xx with retries remaining: fall through to backoff.
-        }
-        catch (e) {
-            lastError = e;
-            if (attempt === retries)
-                throw e;
-        }
-        finally {
-            clearTimeout(t);
-        }
-        // Exponential backoff: 500ms, 1s, 2s.
-        await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
-    }
-    // Unreachable: the loop body always returns or throws on the final attempt.
-    throw lastError ?? new Error("fetchWithTimeout: exhausted retries");
-}
-exports.fetchWithTimeout = fetchWithTimeout;
-async function fetchText(url) {
-    const res = await fetchWithTimeout(url);
-    if (!res.ok)
-        throw new Error(`fetch ${url} returned HTTP ${res.status}`);
-    return res.text();
+    return path.join(claudeRootDir(), "skills");
 }
-async function headOk(url) {
-    const res = await fetchWithTimeout(url, { method: "HEAD" });
-    return res.ok;
+const CLAUDE_ROOT_DISPLAY = "~/.claude";
+async function resolveTarget(target) {
+    return (0, _shared_1.safeResolveTarget)(target, claudeRootDir(), CLAUDE_ROOT_DISPLAY);
 }
-/**
- * Fetch + parse the bundle manifest. Validates required fields and the
- * SKILL.md-at-index-0 invariant. Throws with a clear error on any issue —
- * callers should not silently fall back.
- */
-async function fetchManifest(base) {
-    const url = `${base}/${MANIFEST_PATH}`;
-    const body = await fetchText(url);
-    let parsed;
-    try {
-        parsed = JSON.parse(body);
-    }
-    catch (err) {
-        throw new Error(`manifest ${url} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (!parsed || typeof parsed !== "object") {
-        throw new Error(`manifest ${url} did not parse to an object`);
-    }
-    const m = parsed;
-    for (const key of ["name", "version", "requires_icons"]) {
-        if (typeof m[key] !== "string" || !m[key]) {
-            throw new Error(`manifest ${url} missing required field: ${key}`);
-        }
-    }
-    if (!Array.isArray(m.files) || m.files.length === 0) {
-        throw new Error(`manifest ${url} files[] missing or empty`);
-    }
-    for (const [i, f] of m.files.entries()) {
-        if (!f || typeof f !== "object") {
-            throw new Error(`manifest ${url} files[${i}] not an object`);
-        }
-        for (const key of ["src", "dest", "role"]) {
-            if (typeof f[key] !== "string") {
-                throw new Error(`manifest ${url} files[${i}].${key} missing`);
-            }
-        }
-    }
-    if (m.files[0].dest !== "SKILL.md" || m.files[0].role !== "skill") {
-        throw new Error(`manifest ${url} files[0] must be SKILL.md (role=skill); got dest=${m.files[0].dest} role=${m.files[0].role}`);
-    }
-    return m;
-}
-/**
- * Minimal YAML frontmatter parser — supports only single-line scalar `key: value`
- * pairs with optional `"` or `'` quoting. Multi-line scalars (`|`, `>`), nested
- * mappings, lists, comments after `#`, and YAML null/booleans are NOT handled
- * and may silently mis-parse.
- *
- * Intentional: SKILL.md frontmatter currently has 4 single-line scalar keys
- * (name, description, version, requires_icons). Swap in `js-yaml` when the
- * format grows beyond that.
- */
-function parseFrontmatter(md) {
-    // Strip optional UTF-8 BOM (some editors emit it on save).
-    const text = md.replace(/^/, "");
-    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (!match)
-        return {};
-    const out = {};
-    for (const line of match[1].split(/\r?\n/)) {
-        const kv = line.match(/^(\w+):\s*(.*?)\s*$/);
-        if (!kv)
-            continue;
-        const [, key] = kv;
-        let rawValue = kv[2];
-        // Strip trailing ` # comment` from unquoted scalars.
-        if (!rawValue.startsWith('"') && !rawValue.startsWith("'")) {
-            rawValue = rawValue.replace(/\s+#.*$/, "");
-        }
-        const value = rawValue.replace(/^["']|["']$/g, "");
-        if (key === "name" || key === "version" || key === "requires_icons") {
-            out[key] = value;
-        }
-    }
-    return out;
-}
-exports.parseFrontmatter = parseFrontmatter;
 /**
  * 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
@@ -266,37 +51,24 @@ exports.parseFrontmatter = parseFrontmatter;
 async function isOurSkillDir(dir) {
     try {
         const skillMd = await fs.readFile(path.join(dir, "SKILL.md"), "utf8");
-        const fm = parseFrontmatter(skillMd);
-        return fm.name === SKILL_NAME;
+        const fm = (0, _shared_1.parseFrontmatter)(skillMd);
+        return fm.name === _shared_1.SKILL_NAME;
     }
     catch {
         return false;
     }
 }
-async function withFatalReturn(fn) {
-    try {
-        return await fn();
-    }
-    catch (err) {
-        process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
-    }
-}
 async function install(opts) {
-    return withFatalReturn(async () => {
-        const target = await safeResolveTarget(opts.target ?? defaultTarget());
-        const base = baseUrl();
-        // Strict install path: target must end with the canonical skill folder name
-        // unless the caller has opted into a wider AZURE_ARCH_SKILL_TARGET_ROOT.
-        if (!process.env.AZURE_ARCH_SKILL_TARGET_ROOT && path.basename(target) !== SKILL_NAME) {
-            throw new Error(`refusing to install at ${target} - target basename must be '${SKILL_NAME}' (default ~/.claude/skills/${SKILL_NAME}/). Set AZURE_ARCH_SKILL_TARGET_ROOT to install into a custom test root.`);
+    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.`);
         }
-        // Fetch the bundle manifest FIRST. Anything downstream relies on it.
-        const manifest = await fetchManifest(base);
-        if (manifest.name !== SKILL_NAME) {
-            throw new Error(`manifest name mismatch: expected '${SKILL_NAME}', got '${manifest.name}'. CLI and bundle are out of sync.`);
+        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.`);
         }
-        // Detect partial vs complete prior installs across manifest.files.
         const presence = await Promise.all(manifest.files.map(async ({ dest }) => ({
             dest,
             exists: await fs.stat(path.join(target, dest)).then(() => true).catch(() => false),
@@ -309,32 +81,31 @@ async function install(opts) {
                 : `${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 fetchText(skillUrl);
-        const fm = parseFrontmatter(skillMd);
+        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}/${CANARY_ICON_PATH}`;
-        const reachable = await headOk(canaryUrl);
+        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)`);
         }
-        // Mkdir the parent of every bundle dest so future deeper-nested entries work.
         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}`);
+            const body = await (0, _shared_1.fetchText)(`${base}/${src}`);
             await fs.writeFile(path.join(target, dest), body, "utf8");
         }
-        process.stdout.write(`installed ${SKILL_NAME} to ${target}\n`);
+        process.stdout.write(`installed ${_shared_1.SKILL_NAME} to ${target}\n`);
         return 0;
     });
 }
 async function uninstall(opts) {
-    return withFatalReturn(async () => {
-        const target = await safeResolveTarget(opts.target ?? defaultTarget());
+    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`);
@@ -355,7 +126,7 @@ async function uninstall(opts) {
             }
             throw err;
         }
-        process.stdout.write(`uninstalled ${SKILL_NAME} from ${target}\n`);
+        process.stdout.write(`uninstalled ${_shared_1.SKILL_NAME} from ${target}\n`);
         return 0;
     });
 }
@@ -363,8 +134,8 @@ async function update(opts) {
     return install({ ...opts, overwrite: true });
 }
 async function list(opts) {
-    return withFatalReturn(async () => {
-        const root = await safeResolveTarget(opts.target ?? defaultSkillsRoot());
+    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");
@@ -378,7 +149,7 @@ async function list(opts) {
             const skillMdPath = path.join(root, e.name, "SKILL.md");
             try {
                 const md = await fs.readFile(skillMdPath, "utf8");
-                const fm = parseFrontmatter(md);
+                const fm = (0, _shared_1.parseFrontmatter)(md);
                 rows.push(`${fm.name ?? e.name}\t${fm.version ?? "?"}`);
             }
             catch {

package/dist/adapters/codex.js

@@ -0,0 +1,163 @@
+"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.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");
+Object.defineProperty(exports, "fetchWithTimeout", { enumerable: true, get: function () { return _shared_1.fetchWithTimeout; } });
+Object.defineProperty(exports, "parseFrontmatter", { enumerable: true, get: function () { return _shared_1.parseFrontmatter; } });
+function codexRootDir() {
+    const explicit = process.env.CODEX_HOME;
+    if (explicit)
+        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 };

package/dist/index.js

@@ -7,8 +7,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const package_json_1 = __importDefault(require("../package.json"));
 const claude_code_1 = require("./adapters/claude-code");
+const codex_1 = require("./adapters/codex");
 const ADAPTERS = {
     "claude-code": claude_code_1.claudeCodeAdapter,
+    "codex": codex_1.codexAdapter,
 };
 const SUPPORTED_AGENTS = Object.keys(ADAPTERS);
 function pickAdapter(agent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanv89/azure-arch-skill",
-  "version": "0.3.0",
+  "version": "0.4.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"