@hanv89/azure-arch-skill 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hanv89
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @hanv89/azure-arch-skill
+
+> **Status**: pre-publish. The package is not yet on npmjs.com — the `npx` command below works once the first release ships.
+
+CLI installer for the Azure architecture diagram skill. Drops the skill bundle (`SKILL.md` + worked PlantUML examples) into your AI coding agent's skill folder so that prompts like *"draw an Azure context diagram"* produce diagrams that use official Microsoft Azure architecture icons.
+
+## Requirements
+
+- Node.js ≥ 20
+
+## Install
+
+```sh
+npx @hanv89/azure-arch-skill install --agent=claude-code
+```
+
+Supported agents:
+
+- Claude Code — `~/.claude/skills/azure-architecture-diagram/`
+
+Planned (later releases): Codex CLI, Cursor.
+
+## Subcommands
+
+- `install --agent=<name>` — copy the skill bundle into the agent's skill folder.
+- `uninstall --agent=<name>` — remove the skill from the agent's skill folder.
+- `update --agent=<name>` — refresh an installed skill to the latest version.
+- `list` — list installed skills and their versions.
+
+The icons themselves stay in this repository and are referenced from PlantUML via public `raw.githubusercontent.com` URLs — no additional download or hosting required.
+
+## Environment overrides
+
+Two environment variables exist for validation / CI use. Production users should not set them.
+
+- **`AZURE_ARCH_SKILL_BASE_URL`** — override the bundle source. Restricted to `https://raw.githubusercontent.com/hanv89/azure-icons-for-architecture-diagrams/...` paths; any other host or scheme is rejected. The CLI emits `warn: AZURE_ARCH_SKILL_BASE_URL override active: <value>` to stderr whenever the override fires.
+- **`AZURE_ARCH_SKILL_TARGET_ROOT`** — widen the `--target` allow-list beyond the default `~/.claude/`. Setting this lets `install` / `uninstall` / `list` operate on directories outside the user's Claude config tree, so it MUST point at a directory you control (e.g. `mktemp -d` output in a test script). The CLI emits `warn: AZURE_ARCH_SKILL_TARGET_ROOT override active: <value>` once per command when honored. Never set this in a production shell — a stray `--target=$HOME` invocation against a widened allow-list could remove unrelated files.
+
+## Repository
+
+See the [project README](https://github.com/hanv89/azure-icons-for-architecture-diagrams#readme) for icon source, licensing, and the full skill specification.

package/dist/adapters/claude-code.js

@@ -0,0 +1,316 @@
+"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.claudeCodeAdapter = exports.parseFrontmatter = 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";
+const BUNDLE_FILES = [
+    { src: "dist/skill/SKILL.md", dest: "SKILL.md" },
+    { src: "dist/skill/examples/01-context.puml", dest: "examples/01-context.puml" },
+];
+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(/\/$/, "");
+}
+function defaultTarget() {
+    return path.join(os.homedir(), ".claude", "skills", 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;
+}
+async function fetchWithTimeout(url, init = {}) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+        return await fetch(url, {
+            ...init,
+            signal: ctrl.signal,
+            headers: { ...(init.headers || {}), "User-Agent": USER_AGENT },
+        });
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+async function fetchText(url) {
+    const res = await fetchWithTimeout(url);
+    if (!res.ok)
+        throw new Error(`fetch ${url} returned HTTP ${res.status}`);
+    return res.text();
+}
+async function headOk(url) {
+    const res = await fetchWithTimeout(url, { method: "HEAD" });
+    return res.ok;
+}
+/**
+ * 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
+ * our skill folder.
+ */
+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;
+    }
+    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.`);
+        }
+        // Detect partial vs complete prior installs across BUNDLE_FILES.
+        const presence = await Promise.all(BUNDLE_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}/${BUNDLE_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");
+        }
+        const canaryUrl = `${base}/${CANARY_ICON_PATH}`;
+        const reachable = await 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 BUNDLE_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)) {
+            const body = await fetchText(`${base}/${src}`);
+            await fs.writeFile(path.join(target, dest), body, "utf8");
+        }
+        process.stdout.write(`installed ${SKILL_NAME} to ${target}\n`);
+        return 0;
+    });
+}
+async function uninstall(opts) {
+    return withFatalReturn(async () => {
+        const target = await safeResolveTarget(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 ${SKILL_NAME} from ${target}\n`);
+        return 0;
+    });
+}
+async function update(opts) {
+    return install({ ...opts, overwrite: true });
+}
+async function list(opts) {
+    return withFatalReturn(async () => {
+        const root = await safeResolveTarget(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;
+    });
+}
+exports.claudeCodeAdapter = { install, uninstall, update, list };

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 ADAPTERS = {
+    "claude-code": claude_code_1.claudeCodeAdapter,
+};
+const SUPPORTED_AGENTS = Object.keys(ADAPTERS);
+function pickAdapter(agent) {
+    if (!(agent in ADAPTERS)) {
+        throw new Error(`unknown agent: ${agent} (supported: ${SUPPORTED_AGENTS.join(", ")})`);
+    }
+    return ADAPTERS[agent];
+}
+const program = new commander_1.Command()
+    .name("azure-arch-skill")
+    .description("Install the Azure architecture diagram skill into your AI coding agent.")
+    .version(package_json_1.default.version, "-V, --version");
+function defineSubcommand(name, description) {
+    program
+        .command(name)
+        .description(description)
+        .requiredOption("--agent <name>", `target AI agent (${SUPPORTED_AGENTS.join("|")})`)
+        .option("--target <dir>", "override target directory (validation use)")
+        .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.
+        process.exitCode = await pickAdapter(opts.agent)[name]({ target: opts.target });
+    });
+}
+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.");
+program.parseAsync(process.argv).catch(err => {
+    process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hanv89/azure-arch-skill",
+  "version": "0.1.0-rc.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"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "tsc && node --test dist/adapters/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanv89/azure-icons-for-architecture-diagrams.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hanv89/azure-icons-for-architecture-diagrams/issues"
+  },
+  "homepage": "https://github.com/hanv89/azure-icons-for-architecture-diagrams#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "20.11.30",
+    "typescript": "5.4.5"
+  }
+}