@hanv89/arch-skill 0.0.0 → 0.1.0

package/dist/adapters/_shared.js

@@ -0,0 +1,709 @@
+"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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __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.USER_AGENT = exports.FETCH_TIMEOUT_MS = exports.CANARY_ICON_PATH = exports.MANIFEST_PATH = exports.SKILL_NAME = exports.DEFAULT_BASE_RAW_URL = void 0;
+exports.baseUrl = baseUrl;
+exports.safeResolveTarget = safeResolveTarget;
+exports.joinWithinTarget = joinWithinTarget;
+exports.verifyFileHash = verifyFileHash;
+exports.fetchWithTimeout = fetchWithTimeout;
+exports.fetchText = fetchText;
+exports.headOk = headOk;
+exports.fetchManifest = fetchManifest;
+exports.parseFrontmatter = parseFrontmatter;
+exports.stripFrontmatter = stripFrontmatter;
+exports.satisfiesRequiresIcons = satisfiesRequiresIcons;
+exports.verifyIconsAvailability = verifyIconsAvailability;
+exports.withFatalReturn = withFatalReturn;
+exports.makeFolderInstallAdapter = makeFolderInstallAdapter;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+const js_yaml_1 = require("js-yaml");
+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/archicon/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/archicon";
+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
+// (uninstall's allow-list refuses folders whose SKILL.md `name` differs).
+exports.SKILL_NAME = "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 = `arch-skill/${package_json_1.default.version}`;
+const ALLOWED_BASE_URL_HOSTS = new Set(["raw.githubusercontent.com"]);
+const ALLOWED_BASE_URL_PATH_PREFIX = "/hanv89/archicon/";
+/**
+ * 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).
+ * - `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.ARCH_SKILL_BASE_URL;
+    if (override) {
+        let u;
+        try {
+            u = new URL(override);
+        }
+        catch {
+            throw new Error(`ARCH_SKILL_BASE_URL is not a valid URL: ${override}`);
+        }
+        if (u.protocol !== "https:") {
+            throw new Error(`ARCH_SKILL_BASE_URL must use https; got ${u.protocol}`);
+        }
+        if (!ALLOWED_BASE_URL_HOSTS.has(u.hostname)) {
+            throw new Error(`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(`ARCH_SKILL_BASE_URL path must start with ${ALLOWED_BASE_URL_PATH_PREFIX}`);
+        }
+        process.stderr.write(`warn: ARCH_SKILL_BASE_URL override active: ${override}\n`);
+        return override.replace(/\/$/, "");
+    }
+    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}`;
+    }
+    return exports.DEFAULT_BASE_RAW_URL;
+}
+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
+ * `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.ARCH_SKILL_TARGET_ROOT;
+    if (explicit && !envTargetRootWarned) {
+        process.stderr.write(`warn: 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 ? `, $ARCH_SKILL_TARGET_ROOT=${explicit}` : ""}`;
+        throw new Error(`refusing to operate on ${realResolved} (resolved from ${target}) - outside allowed roots (${allowList})`);
+    }
+    return realResolved;
+}
+/**
+ * Defense-in-depth: assert a manifest `dest` resolves inside `target` before
+ * any write/unlink. `fetchManifest` already rejects absolute / `..` paths at
+ * the trust boundary; this is the second guard at the filesystem-touch site so
+ * a per-file path can never escape the install dir even if the parse-time
+ * check is ever bypassed. Returns the safe absolute path.
+ */
+function joinWithinTarget(target, dest) {
+    const full = path.resolve(target, dest);
+    const root = path.resolve(target);
+    if (full !== root && !full.startsWith(root + path.sep)) {
+        throw new Error(`refusing to operate on ${full} (from dest '${dest}') - outside install target ${root}`);
+    }
+    return full;
+}
+/**
+ * Compute the sha256 of `body` and throw a clear error if it does not match
+ * `expectedSha256` (case-insensitive hex compare). Adapter-agnostic so every
+ * adapter built on the shared helpers inherits verify-before-write integrity.
+ */
+function verifyFileHash(body, expectedSha256) {
+    const actual = crypto.createHash("sha256").update(body).digest("hex");
+    if (actual.toLowerCase() !== expectedSha256.toLowerCase()) {
+        throw new Error(`sha256 mismatch: expected ${expectedSha256}, computed ${actual}`);
+    }
+}
+/**
+ * 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");
+}
+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;
+}
+/**
+ * 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 (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`);
+    }
+    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`);
+            }
+        }
+        // Optional sha256: when present it must be 64 hex chars. A malformed
+        // value is rejected here rather than silently skipped, so a typo in a
+        // published manifest cannot quietly disable integrity checking.
+        const sha = f.sha256;
+        if (sha !== undefined && (typeof sha !== "string" || !/^[0-9a-fA-F]{64}$/.test(sha))) {
+            throw new Error(`manifest ${url} files[${i}].sha256 must be a 64-char hex string (got: ${String(sha)})`);
+        }
+        // Path-traversal guard: dest/src are joined onto the install target +
+        // the fetch base. A manifest from a compromised repo / malicious tag with
+        // an absolute path or a `..` segment could escape the target dir (arbitrary
+        // file write) or fetch off-path. Reject both here, at the trust boundary.
+        for (const key of ["dest", "src"]) {
+            const p = f[key];
+            if (path.isAbsolute(p) || p.split(/[\\/]/).includes("..")) {
+                throw new Error(`manifest ${url} files[${i}].${key} must be a relative path with no '..' segment (got: ${p})`);
+            }
+        }
+    }
+    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;
+}
+/**
+ * YAML frontmatter parser. Uses `js-yaml` to handle the full YAML spec
+ * (folded scalars `>`, literal block scalars `|`, quoted strings, comments,
+ * nested mappings, etc) so SKILL.md frontmatter can grow beyond simple
+ * `key: value` pairs without silent mis-parses.
+ *
+ * Returns only the 3 keys the CLI cares about (`name`, `version`,
+ * `requires_icons`); other top-level keys are ignored.
+ */
+function parseFrontmatter(md) {
+    const text = md.replace(/^/, "");
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    let parsed;
+    try {
+        parsed = (0, js_yaml_1.load)(match[1]);
+    }
+    catch (err) {
+        return {};
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const obj = parsed;
+    const out = {};
+    for (const key of ["name", "version", "requires_icons"]) {
+        const raw = obj[key];
+        if (typeof raw === "string") {
+            out[key] = raw;
+        }
+        else if (typeof raw === "number") {
+            out[key] = String(raw);
+        }
+    }
+    return out;
+}
+/**
+ * Strip the leading `---\n...\n---\n` YAML frontmatter block from a markdown
+ * string. Returns the body unchanged if no frontmatter is detected.
+ *
+ * Used by adapters that re-render the upstream SKILL.md for a different host
+ * (e.g. Cursor's `.mdc` rule files, which carry their own frontmatter shape
+ * and embed the SKILL.md body without its original frontmatter).
+ */
+function stripFrontmatter(md) {
+    const text = md.replace(/^/, "");
+    const match = text.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    return match ? text.slice(match[0].length) : text;
+}
+/**
+ * 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 — 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.
+ */
+// Pre-release suffixes (`1.2.3-rc.1`) are intentionally NOT supported here
+// or in the `VERSION_RE` regex above. The release workflows tag from main
+// only — no rc branches in scope. If pre-release tags ever ship, this
+// matcher needs a re-design (build-metadata + precedence ordering).
+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) {
+        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);
+    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 === "")
+        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}`);
+}
+/**
+ * Verify the icon set the skill bundle references is reachable AND its
+ * semver satisfies SKILL.md's requires_icons.
+ *
+ * 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})`);
+    }
+    if (!requestedVersion) {
+        return;
+    }
+    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)`;
+    }
+    if (!satisfiesRequiresIcons(requires, iconsTagSemver)) {
+        throw new Error(`requires_icons constraint ${requires} not satisfied by ${source} ${iconsTagSemver}`);
+    }
+}
+async function withFatalReturn(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+// 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.
+//
+// LOAD-BEARING: this basename is the only signal uninstall has to
+// distinguish a current-era install from a pre-0.9.0 install (when no
+// manifest was persisted). Renaming this constant is a one-way migration:
+// installs done under the old name fall into the legacy whole-folder
+// `rm -rf` path, which still works but loses the manifest-scoped
+// preservation of user-authored content alongside the skill. If renamed,
+// keep at least one release cycle of dual-read support.
+const PERSISTED_MANIFEST_BASENAME = ".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.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 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 '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 'arch-skill update --agent=${cfg.agentFlag}' to repair.`);
+            }
+            const skillFile = manifest.files[0];
+            const skillUrl = `${base}/${skillFile.src}`;
+            const skillMd = await fetchText(skillUrl);
+            // Integrity gate (verify-before-write) for SKILL.md. See verifyBundleFile.
+            verifyBundleFile(skillFile, skillMd);
+            const fm = parseFrontmatter(skillMd);
+            if (!fm.requires_icons) {
+                throw new Error("SKILL.md missing requires_icons frontmatter");
+            }
+            await verifyIconsAvailability(base, manifest, opts.version);
+            // Fetch + verify every remaining file BEFORE writing any of them, so an
+            // integrity failure aborts the whole install with nothing written.
+            const remaining = manifest.files.slice(1);
+            const remainingBodies = [];
+            for (const f of remaining) {
+                const body = await fetchText(`${base}/${f.src}`);
+                verifyBundleFile(f, body);
+                remainingBodies.push({ dest: f.dest, body });
+            }
+            for (const { dest } of manifest.files) {
+                await fs.mkdir(path.dirname(joinWithinTarget(target, dest)), { recursive: true });
+            }
+            await fs.writeFile(joinWithinTarget(target, skillFile.dest), skillMd, "utf8");
+            for (const { dest, body } of remainingBodies) {
+                await fs.writeFile(joinWithinTarget(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 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) {
+                    // joinWithinTarget guards against a tampered persisted manifest whose
+                    // dest escapes target (which would delete files outside the install).
+                    let victim;
+                    try {
+                        victim = joinWithinTarget(target, f.dest);
+                    }
+                    catch {
+                        continue;
+                    }
+                    await fs.unlink(victim).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 leftover = await fs.readdir(target).catch(() => []);
+                if (leftover.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 };
+}
+/**
+ * Supply-chain integrity gate for a single bundle file, applied AFTER the
+ * body is fetched and BEFORE it is written to disk.
+ *
+ * - manifest entry HAS `sha256` → verify; mismatch throws and aborts install.
+ * - manifest entry has NO `sha256` (back-compat) → print one-line `warn:` and
+ *   proceed, so older manifests keep installing.
+ *
+ * Lives in _shared.ts so every adapter built on makeFolderInstallAdapter (and
+ * future adapters reusing these helpers) inherits the check for free.
+ */
+function verifyBundleFile(file, body) {
+    if (file.sha256) {
+        verifyFileHash(body, file.sha256);
+    }
+    else {
+        process.stderr.write(`warn: manifest entry ${file.dest} has no sha256; skipping integrity check\n`);
+    }
+}

package/dist/adapters/claude-code.js

@@ -0,0 +1,47 @@
+"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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeAdapter = void 0;
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const _shared_1 = require("./_shared");
+function claudeRootDir() {
+    return path.join(os.homedir(), ".claude");
+}
+exports.claudeCodeAdapter = (0, _shared_1.makeFolderInstallAdapter)({
+    rootDir: claudeRootDir,
+    rootDisplay: () => "~/.claude",
+    agentFlag: "claude-code",
+});

package/dist/adapters/registry.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_TARGETS = exports.SUPPORTED_AGENTS = exports.ADAPTERS = void 0;
+const claude_code_1 = require("./claude-code");
+// Single source of truth for the supported-agent set. Add a new adapter by
+// importing it here and adding one entry below; both `src/index.ts` (CLI
+// dispatch + --agent help text) reads from this map directly.
+//
+// Only the Claude Code adapter ships in this phase; Codex / Cursor / the
+// `--agent=all` fan-out land in a later port.
+exports.ADAPTERS = {
+    "claude-code": claude_code_1.claudeCodeAdapter,
+};
+exports.SUPPORTED_AGENTS = Object.keys(exports.ADAPTERS);
+/** Full target set the CLI's `--agent` flag accepts. */
+exports.SUPPORTED_TARGETS = [...exports.SUPPORTED_AGENTS];

package/dist/adapters/types.js

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

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/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 registry_1 = require("./adapters/registry");
+const program = new commander_1.Command()
+    .name("arch-skill")
+    .description("Install the architecture diagram skill into your AI coding agent.")
+    // Top-level flag uses `--cli-version` (not `--version`) so subcommand
+    // `--version <semver>` (skill pin) dispatches correctly. Earlier shipping
+    // cycles bound both at `--version`; Commander short-circuited to the
+    // top-level printer before invoking the subcommand action, breaking
+    // documented tag-pin examples.
+    .version(package_json_1.default.version, "-V, --cli-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)")
+        // Subcommand-scoped `--version <semver>` pins which skill bundle to
+        // fetch. Distinct from the top-level `--cli-version` flag which prints
+        // the CLI tool's own version. The two are namespaced cleanly now that
+        // the top-level flag is renamed.
+        .option("--version <semver>", "pin to a specific skill version (X.Y.Z); default = latest from main")
+        .action(async (opts) => {
+        // 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})`);
+        }
+        const optsForAdapter = { target: opts.target, version: opts.version };
+        if (!registry_1.SUPPORTED_AGENTS.includes(opts.agent)) {
+            throw new Error(`unknown agent: ${opts.agent} (supported: ${registry_1.SUPPORTED_AGENTS.join(", ")})`);
+        }
+        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,13 +1,47 @@
 {
   "name": "@hanv89/arch-skill",
-  "version": "0.0.0",
-  "description": "Placeholder to bootstrap npm trusted publishing (OIDC). Real releases begin at 0.1.0.",
+  "version": "0.1.0",
+  "description": "Install the architecture-diagram skill into your AI coding agent (Claude Code, Codex CLI, Cursor).",
+  "bin": {
+    "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/**/*.test.js",
+    "test:coverage": "tsc && node --test --experimental-test-coverage dist/**/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "license": "MIT",
-  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanv89/archicon.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hanv89/archicon/issues"
+  },
+  "homepage": "https://github.com/hanv89/archicon#readme",
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "commander": "14.0.3",
+    "js-yaml": "4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "22.18.0",
+    "typescript": "5.9.3"
+  }
 }

package/README.md

@@ -1,7 +0,0 @@
-# @hanv89/arch-skill
-
-Placeholder release to bootstrap npm **trusted publishing (OIDC)**. npm cannot
-publish a package's first version via OIDC and cannot configure a trusted
-publisher until the package exists, so this `0.0.0` placeholder is published
-once manually to create the package. Real releases begin at `0.1.0` and are
-published from CI via OIDC — see the project repository.