@hanv89/azure-arch-skill 0.6.0 → 0.7.0

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.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;
@@ -272,6 +294,85 @@ 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, which is fine for icons semver in the foreseeable future.
+ */
+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;
+    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);
+    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.
+ *
+ * - 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.
+ */
+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)`);
+    }
+    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}`);
+    }
+    const iconsTagSemver = lowerMatch[1];
+    if (!satisfiesRequiresIcons(requires, iconsTagSemver)) {
+        throw new Error(`requires_icons constraint ${requires} not satisfied by inferred icons tag ${iconsTagSemver}`);
+    }
+}
+exports.verifyIconsAvailability = verifyIconsAvailability;
 async function withFatalReturn(fn) {
     try {
         return await fn();

package/dist/adapters/claude-code.js

@@ -61,7 +61,7 @@ async function isOurSkillDir(dir) {
 async function install(opts) {
     return (0, _shared_1.withFatalReturn)(async () => {
         const target = await resolveTarget(opts.target ?? defaultTarget());
-        const base = (0, _shared_1.baseUrl)();
+        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.`);
         }
@@ -86,11 +86,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);
         for (const { dest } of manifest.files) {
             await fs.mkdir(path.dirname(path.join(target, dest)), { recursive: true });
         }

package/dist/adapters/codex.js

@@ -61,7 +61,7 @@ async function isOurSkillDir(dir) {
 async function install(opts) {
     return (0, _shared_1.withFatalReturn)(async () => {
         const target = await resolveTarget(opts.target ?? defaultTarget());
-        const base = (0, _shared_1.baseUrl)();
+        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.`);
         }
@@ -86,11 +86,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);
         for (const { dest } of manifest.files) {
             await fs.mkdir(path.dirname(path.join(target, dest)), { recursive: true });
         }

package/dist/adapters/cursor.js

@@ -76,7 +76,7 @@ async function isOurRuleFile(file) {
 async function install(opts) {
     return (0, _shared_1.withFatalReturn)(async () => {
         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 +90,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/index.js

@@ -18,18 +18,23 @@ 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 };
+        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;

package/package.json

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