@hanv89/azure-arch-skill 0.2.2 → 0.3.1

package/dist/adapters/claude-code.js

@@ -37,13 +37,9 @@ const DEFAULT_BASE_RAW_URL = "https://raw.githubusercontent.com/hanv89/azure-ico
 // 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";
-// Hard-coded bundle list. Keep SKILL.md as index 0 — install() relies on
-// BUNDLE_FILES[0] for the frontmatter-parsing precheck.
-const BUNDLE_FILES = [
-    { src: "dist/skill/SKILL.md", dest: "SKILL.md" },
-    { src: "dist/skill/examples/01-context.puml", dest: "examples/01-context.puml" },
-    { src: "dist/skill/examples/02-fabric-data-pipeline.puml", dest: "examples/02-fabric-data-pipeline.puml" },
-];
+// 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}`;
@@ -134,8 +130,9 @@ async function safeResolveTarget(target) {
 /**
  * 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.
+ * 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
@@ -185,6 +182,48 @@ async function headOk(url) {
     const res = await fetchWithTimeout(url, { method: "HEAD" });
     return res.ok;
 }
+/**
+ * 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
@@ -253,8 +292,13 @@ async function install(opts) {
         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.`);
         }
-        // Detect partial vs complete prior installs across BUNDLE_FILES.
-        const presence = await Promise.all(BUNDLE_FILES.map(async ({ dest }) => ({
+        // 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.`);
+        }
+        // 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),
         })));
@@ -265,7 +309,7 @@ async function install(opts) {
                 ? `${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}/${BUNDLE_FILES[0].src}`;
+        const skillUrl = `${base}/${manifest.files[0].src}`;
         const skillMd = await fetchText(skillUrl);
         const fm = parseFrontmatter(skillMd);
         if (!fm.requires_icons) {
@@ -277,11 +321,11 @@ async function install(opts) {
             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 BUNDLE_FILES) {
+        for (const { dest } of manifest.files) {
             await fs.mkdir(path.dirname(path.join(target, dest)), { recursive: true });
         }
-        await fs.writeFile(path.join(target, BUNDLE_FILES[0].dest), skillMd, "utf8");
-        for (const { src, dest } of BUNDLE_FILES.slice(1)) {
+        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");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanv89/azure-arch-skill",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Install the Azure architecture diagram skill into your AI coding agent (Claude Code, Codex CLI, Cursor).",
   "bin": {
     "azure-arch-skill": "dist/index.js"