@airig/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JD Solanki
+
+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,51 @@
+# airig
+
+Distribute and manage AI setups across coding agents from one project-local `.ai/` directory.
+
+## Usage
+
+Install the CLI globally to use the short `airig` command:
+
+```sh
+npm install --global airig
+```
+
+```sh
+airig add <owner/repo>[@version]
+airig add .
+airig update <owner/repo>@<version>
+airig remove [owner/repo|.]
+airig publish [tag]
+```
+
+For one-off usage without a global install, run the npm package directly:
+
+```sh
+npx airig add <owner/repo>[@version]
+npx airig add .
+npx airig update <owner/repo>@<version>
+npx airig remove [owner/repo|.]
+npx airig publish [tag]
+```
+
+The package is named `airig`; the installed binary is `airig`.
+
+## What It Does
+
+airig installs selected AI setup artifacts from immutable GitHub releases into `.ai/`, then links them into provider-specific config paths. It supports local author dogfooding with `add .`, explicit version updates, interactive removal, and publishing `.ai/` as an `ai.zip` release asset.
+
+Remote setup releases are pinned to exact versions in `.ai/ai.json`. `add` and `update` verify GitHub release immutability before writing remote content.
+
+## Author Workflow
+
+1. Create setup artifacts under `.ai/`.
+2. Run `airig add .` to wire local artifacts into your repo.
+3. Tag a release with your normal git tooling.
+4. Run `airig publish` to upload `ai.zip` to an immutable GitHub release.
+5. Share `airig add yourname/repo`.
+
+## Requirements
+
+- Node.js `24.11.0` or newer in the Node 24 release line.
+- GitHub immutable releases enabled for repositories that publish setup releases.
+- `GITHUB_TOKEN` with repository write access when running `publish`.

package/dist/index.js

@@ -0,0 +1,882 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { execSync } from "node:child_process";
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import path, { join } from "node:path";
+import { parseEnv } from "node:util";
+import archiver from "archiver";
+import { createWriteStream, existsSync } from "node:fs";
+import { Octokit } from "@octokit/rest";
+import { checkbox } from "@inquirer/prompts";
+import os from "node:os";
+import extractZip from "extract-zip";
+//#region src/lib/zip.ts
+function create(sourceDir, outputPath) {
+	return new Promise((resolve, reject) => {
+		const output = createWriteStream(outputPath);
+		const archive = archiver("zip", { zlib: { level: 9 } });
+		const sourceBaseName = path.basename(sourceDir);
+		output.on("close", resolve);
+		archive.on("error", reject);
+		archive.pipe(output);
+		archive.directory(sourceDir, sourceBaseName, (entry) => {
+			if (entry.name === "ai.json" && entry.prefix === sourceBaseName) return false;
+			return entry;
+		});
+		archive.finalize();
+	});
+}
+//#endregion
+//#region src/lib/github.ts
+async function fetchReleaseInfo(owner, repo, tag, octokit) {
+	let releaseTag;
+	let immutable;
+	let assets;
+	if (tag) {
+		const { data } = await octokit.repos.getReleaseByTag({
+			owner,
+			repo,
+			tag
+		});
+		releaseTag = data.tag_name;
+		immutable = data.immutable === true;
+		assets = data.assets;
+	} else {
+		const { data } = await octokit.repos.getLatestRelease({
+			owner,
+			repo
+		});
+		releaseTag = data.tag_name;
+		immutable = data.immutable === true;
+		assets = data.assets;
+	}
+	const asset = assets.find((a) => a.name === "ai.zip");
+	if (!asset) throw new Error(`No ai.zip asset found in release "${tag ?? "latest"}" of ${owner}/${repo}`);
+	return {
+		tag: releaseTag,
+		assetDownloadUrl: asset.browser_download_url,
+		immutable
+	};
+}
+async function downloadAsset(url) {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to download asset: HTTP ${response.status} ${response.statusText}`);
+	return Buffer.from(await response.arrayBuffer());
+}
+function createOctokit(token) {
+	return new Octokit({ auth: token });
+}
+async function getImmutableReleasesStatus(owner, repo, octokit) {
+	try {
+		const { data } = await octokit.request("GET /repos/{owner}/{repo}/immutable-releases", {
+			owner,
+			repo
+		});
+		return data;
+	} catch (err) {
+		if (err && typeof err === "object" && "status" in err) {
+			const status = err.status;
+			if (status === 404) return {
+				enabled: false,
+				enforced_by_owner: false
+			};
+			if (status === 401) throw new Error("Verifying release immutability requires a GitHub token (even for public repos).\n  Set GITHUB_TOKEN and retry:  export GITHUB_TOKEN=ghp_...\n  Generate a token at: https://github.com/settings/tokens");
+		}
+		throw err;
+	}
+}
+function isOctokitError(err) {
+	return err != null && typeof err === "object" && "status" in err;
+}
+function interpretError(err, step, ctx) {
+	if (!isOctokitError(err)) return err instanceof Error ? err : new Error(String(err));
+	const { status } = err;
+	const firstValidationError = err.response?.data?.errors?.[0];
+	if (status === 401) return /* @__PURE__ */ new Error("GITHUB_TOKEN is invalid or expired.\n  Generate a new token at: https://github.com/settings/tokens");
+	if (status === 403) return /* @__PURE__ */ new Error(`Token lacks write access to ${ctx.owner}/${ctx.repo}.\n  Classic PAT needs the "repo" scope.
+  Fine-grained PAT needs "Contents: Read and write".`);
+	if (status === 404 && step === "create-release") return /* @__PURE__ */ new Error(`Repository ${ctx.owner}/${ctx.repo} not found or the token has no access to it.\n  Check the git remote URL and token permissions.`);
+	if (status === 422 && firstValidationError?.code === "already_exists" && firstValidationError?.field === "tag_name") return /* @__PURE__ */ new Error(`A release for tag ${ctx.tag} already exists in ${ctx.owner}/${ctx.repo}.\n  Immutable releases cannot be deleted or have their tag reused.
+  Bump the version, push a new tag, and retry.`);
+	if (status === 422 && step === "upload-asset" && firstValidationError?.code === "already_exists") return /* @__PURE__ */ new Error(`An asset named ai.zip already exists on a stale draft release (leftover from a previous failed publish).
+  Delete stale drafts at: https://github.com/${ctx.owner}/${ctx.repo}/releases`);
+	const apiMessage = err.response?.data?.message ?? String(err);
+	return /* @__PURE__ */ new Error(`GitHub API error (HTTP ${status}): ${apiMessage}`);
+}
+async function deleteDraft(octokit, owner, repo, releaseId) {
+	await octokit.repos.deleteRelease({
+		owner,
+		repo,
+		release_id: releaseId
+	}).catch(() => {});
+}
+async function publishRelease(opts) {
+	const { owner, repo, tag, assetPath, octokit } = opts;
+	const ctx = {
+		owner,
+		repo,
+		tag
+	};
+	let draftId;
+	try {
+		const { data: draft } = await octokit.repos.createRelease({
+			owner,
+			repo,
+			tag_name: tag,
+			draft: true
+		});
+		draftId = draft.id;
+	} catch (err) {
+		throw interpretError(err, "create-release", ctx);
+	}
+	try {
+		const assetData = await readFile(assetPath);
+		await octokit.repos.uploadReleaseAsset({
+			owner,
+			repo,
+			release_id: draftId,
+			name: path.basename(assetPath),
+			data: assetData
+		});
+	} catch (err) {
+		await deleteDraft(octokit, owner, repo, draftId);
+		throw interpretError(err, "upload-asset", ctx);
+	}
+	try {
+		const { data: published } = await octokit.repos.updateRelease({
+			owner,
+			repo,
+			release_id: draftId,
+			draft: false
+		});
+		return published.html_url;
+	} catch (err) {
+		await deleteDraft(octokit, owner, repo, draftId);
+		throw interpretError(err, "publish-release", ctx);
+	}
+}
+//#endregion
+//#region src/commands/publish.ts
+function resolveTag(tagArg) {
+	if (tagArg) return tagArg;
+	try {
+		return execSync("git describe --tags --abbrev=0", { encoding: "utf8" }).trim();
+	} catch {
+		console.error("✖ No tag found. Pass a tag argument or create a git tag first.");
+		process.exit(1);
+	}
+}
+function parseRemoteUrl(remote) {
+	const match = remote.match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+	if (!match) return null;
+	return {
+		owner: match[1],
+		repo: match[2]
+	};
+}
+function resolveOwnerRepo() {
+	let remote;
+	try {
+		remote = execSync("git remote get-url origin", { encoding: "utf8" }).trim();
+	} catch {
+		console.error("✖ Could not read git remote origin. Is this a git repository with a remote?");
+		process.exit(1);
+	}
+	const parsed = parseRemoteUrl(remote);
+	if (!parsed) {
+		console.error(`✖ Could not parse owner/repo from remote: ${remote}`);
+		process.exit(1);
+	}
+	return parsed;
+}
+function createPublishZip(zipPath = path.join(process.cwd(), "ai.zip")) {
+	return create(".ai", zipPath);
+}
+function isNodeErrorWithCode(err, code) {
+	return err instanceof Error && "code" in err && err.code === code;
+}
+async function loadPublishGithubTokenFromCwd() {
+	if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+	try {
+		const token = parseEnv(await readFile(path.join(process.cwd(), ".env"), "utf8")).GITHUB_TOKEN;
+		if (token) process.env.GITHUB_TOKEN = token;
+		return token;
+	} catch (err) {
+		if (isNodeErrorWithCode(err, "ENOENT")) return void 0;
+		throw err;
+	}
+}
+const publishCommand = new Command("publish").description("Publish project .ai artifacts as an immutable ai.zip release").argument("[tag]", "Git tag to release (defaults to latest local tag)").action(async (tagArg) => {
+	try {
+		const token = await loadPublishGithubTokenFromCwd();
+		if (!token) {
+			console.error("✖ GITHUB_TOKEN is not set. Add it to .env in this directory or export it before running publish.");
+			console.error("  GITHUB_TOKEN=ghp_...");
+			process.exit(1);
+		}
+		const tag = resolveTag(tagArg);
+		const { owner, repo } = resolveOwnerRepo();
+		const octokit = createOctokit(token);
+		if (!(await getImmutableReleasesStatus(owner, repo, octokit)).enabled) {
+			console.error(`✖ Immutable releases are not enabled for ${owner}/${repo}.`);
+			console.error(`  Enable it at: https://github.com/${owner}/${repo}/settings`);
+			console.error("  Docs: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository");
+			process.exit(1);
+		}
+		const zipPath = path.join(process.cwd(), "ai.zip");
+		await createPublishZip(zipPath);
+		const url = await publishRelease({
+			owner,
+			repo,
+			tag,
+			assetPath: zipPath,
+			octokit
+		});
+		await rm(zipPath, { force: true });
+		console.log(`✔ Published: ${url}`);
+	} catch (err) {
+		console.error(`✖ ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+});
+//#endregion
+//#region src/lib/ai-json.ts
+const AI_JSON_PATH = ".ai/ai.json";
+function validate(data) {
+	if (typeof data !== "object" || data === null || typeof data.packages !== "object" || data.packages === null) throw new Error(`${AI_JSON_PATH} is malformed: expected { "packages": {} }\n  Fix: restore the missing top-level keys, or delete ${AI_JSON_PATH} to reset it.`);
+	const packages = {};
+	for (const [key, rawEntry] of Object.entries(data.packages)) {
+		if (typeof rawEntry !== "object" || rawEntry === null) throw new Error(`${AI_JSON_PATH} is malformed: package "${key}" must be an object.`);
+		const entry = rawEntry;
+		if (typeof entry.version !== "string" || entry.version.length === 0) throw new Error(`${AI_JSON_PATH} is malformed: package "${key}" must have a version string.`);
+		if (key === "." && entry.version !== "*") throw new Error(`${AI_JSON_PATH} is malformed: local package "." must use version "*".`);
+		if (key !== "." && entry.version === "*") throw new Error(`${AI_JSON_PATH} is malformed: remote package "${key}" must use an exact version.`);
+		if (entry.linked !== void 0 && (!Array.isArray(entry.linked) || entry.linked.some((label) => typeof label !== "string" || label.length === 0))) throw new Error(`${AI_JSON_PATH} is malformed: package "${key}" linked must be a string array.`);
+		packages[key] = {
+			version: entry.version,
+			linked: entry.linked === void 0 ? [] : [...entry.linked]
+		};
+	}
+	return { packages };
+}
+async function readAiJson() {
+	if (!existsSync(AI_JSON_PATH)) return { packages: {} };
+	const raw = await readFile(AI_JSON_PATH, "utf-8");
+	return validate(JSON.parse(raw));
+}
+async function writeAiJson(data) {
+	await mkdir(path.dirname(AI_JSON_PATH), { recursive: true });
+	await writeFile(AI_JSON_PATH, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function addPackage(data, key, entry) {
+	data.packages[key] = entry;
+}
+function removePackage(data, key) {
+	delete data.packages[key];
+}
+//#endregion
+//#region src/lib/package-ref.ts
+function parsePackageRef(pkg) {
+	const atIdx = pkg.lastIndexOf("@");
+	let ref = pkg;
+	let tag;
+	if (atIdx > 0) {
+		tag = pkg.slice(atIdx + 1);
+		ref = pkg.slice(0, atIdx);
+	}
+	const slashIdx = ref.indexOf("/");
+	if (slashIdx < 1 || slashIdx === ref.length - 1) throw new Error(`Invalid package reference "${pkg}". Expected: owner/repo or owner/repo@version`);
+	return {
+		owner: ref.slice(0, slashIdx),
+		repo: ref.slice(slashIdx + 1),
+		tag
+	};
+}
+function parseExactPackageRef(pkg) {
+	const parsed = parsePackageRef(pkg);
+	if (!parsed.tag) throw new Error(`Invalid package reference "${pkg}". Expected exact version: owner/repo@version`);
+	return parsed;
+}
+//#endregion
+//#region src/lib/setup-release.ts
+async function findSkillDirs(dir) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	if (entries.some((e) => e.isFile() && e.name === "SKILL.md")) return [dir];
+	const results = [];
+	for (const entry of entries) if (entry.isDirectory()) results.push(...await findSkillDirs(path.join(dir, entry.name)));
+	return results;
+}
+async function flattenSkills(skillsDir) {
+	const skillDirs = await findSkillDirs(skillsDir);
+	const names = /* @__PURE__ */ new Map();
+	for (const dir of skillDirs) {
+		const name = path.basename(dir);
+		if (names.has(name)) throw new Error(`Skill name collision: "${name}" appears at "${names.get(name)}" and "${dir}" in the package`);
+		names.set(name, dir);
+	}
+	for (const dir of skillDirs) {
+		const dest = path.join(skillsDir, path.basename(dir));
+		if (dir !== dest) await cp(dir, dest, { recursive: true });
+	}
+	const topEntries = await readdir(skillsDir, { withFileTypes: true });
+	for (const entry of topEntries) if (entry.isDirectory() && !names.has(entry.name)) await rm(path.join(skillsDir, entry.name), {
+		recursive: true,
+		force: true
+	});
+}
+async function withExtractedReleaseAi(assetBuffer, tmpPrefix, fn) {
+	const tmpDir = await mkdtemp(path.join(os.tmpdir(), tmpPrefix));
+	try {
+		const zipPath = path.join(tmpDir, "ai.zip");
+		await writeFile(zipPath, assetBuffer);
+		const extractDir = path.join(tmpDir, "extracted");
+		await mkdir(extractDir);
+		await extractZip(zipPath, { dir: extractDir });
+		const extractedAiDir = path.join(extractDir, ".ai");
+		if (!existsSync(extractedAiDir)) throw new Error("The release zip does not contain an .ai/ directory");
+		const skillsSrc = path.join(extractedAiDir, "skills");
+		if (existsSync(skillsSrc)) await flattenSkills(skillsSrc);
+		return await fn(extractedAiDir);
+	} finally {
+		await rm(tmpDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function copyReleaseArtifactsToLocal(extractedAiDir, artifacts) {
+	await mkdir(".ai", { recursive: true });
+	const artifactsToCopy = await expandReleaseArtifactsWithSymlinkDependencies(extractedAiDir, artifacts);
+	for (const artifact of artifactsToCopy) {
+		const sourcePath = path.join(extractedAiDir, artifact);
+		const targetPath = path.join(".ai", artifact);
+		await mkdir(path.dirname(targetPath), { recursive: true });
+		await rm(targetPath, {
+			recursive: true,
+			force: true
+		});
+		await cp(sourcePath, targetPath, {
+			recursive: true,
+			force: true,
+			verbatimSymlinks: true
+		});
+	}
+}
+async function expandReleaseArtifactsWithSymlinkDependencies(extractedAiDir, artifacts) {
+	const expanded = /* @__PURE__ */ new Set();
+	async function visit(artifact) {
+		if (expanded.has(artifact)) return;
+		expanded.add(artifact);
+		const sourcePath = path.join(extractedAiDir, artifact);
+		if (!(await lstatIfExists(sourcePath))?.isSymbolicLink()) return;
+		const linkTarget = await readlink(sourcePath);
+		if (path.isAbsolute(linkTarget)) return;
+		const dependency = path.relative(extractedAiDir, path.resolve(path.dirname(sourcePath), linkTarget));
+		if (dependency.startsWith("..") || dependency === "") return;
+		if (existsSync(path.join(extractedAiDir, dependency))) await visit(dependency);
+	}
+	for (const artifact of artifacts) await visit(artifact);
+	return [...expanded];
+}
+async function lstatIfExists(filePath) {
+	try {
+		return await lstat(filePath);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/lib/provider-registry.ts
+const PROVIDER_REGISTRY = {
+	claude: {
+		name: "claude",
+		rules: [
+			{
+				source: ".ai/CLAUDE.md",
+				target: "CLAUDE.md"
+			},
+			{
+				source: ".ai/.claude/agents",
+				target: ".claude/agents"
+			},
+			{
+				source: ".ai/.claude/commands",
+				target: ".claude/commands"
+			}
+		]
+	},
+	codex: {
+		name: "codex",
+		rules: [
+			{
+				source: ".ai/AGENTS.md",
+				target: "AGENTS.md"
+			},
+			{
+				source: ".ai/.codex/agents",
+				target: ".codex/agents"
+			},
+			{
+				source: ".ai/.codex/commands",
+				target: ".codex/prompts"
+			}
+		]
+	}
+};
+const SKILLS_RULE = {
+	source: ".ai/skills",
+	target: ".agents/skills"
+};
+function rulesFor(providers) {
+	return [...providers.flatMap((p) => PROVIDER_REGISTRY[p].rules), SKILLS_RULE];
+}
+function targetPathsForArtifact(artifact, providers = Object.keys(PROVIDER_REGISTRY)) {
+	const targets = /* @__PURE__ */ new Set();
+	for (const rule of rulesFor(providers)) {
+		const relSource = rule.source.startsWith(".ai/") ? rule.source.slice(4) : rule.source;
+		if (artifact === relSource) targets.add(rule.target);
+		else if (artifact.startsWith(relSource + "/")) targets.add(join(rule.target, artifact.slice(relSource.length + 1)));
+	}
+	return [...targets];
+}
+async function listArtifacts(rootDir, providers = Object.keys(PROVIDER_REGISTRY)) {
+	const artifacts = /* @__PURE__ */ new Set();
+	for (const rule of rulesFor(providers)) {
+		const relSource = rule.source.startsWith(".ai/") ? rule.source.slice(4) : rule.source;
+		const sourcePath = join(rootDir, relSource);
+		let sourceStat;
+		try {
+			sourceStat = await lstat(sourcePath);
+		} catch {
+			continue;
+		}
+		if (!sourceStat.isDirectory()) {
+			artifacts.add(relSource);
+			continue;
+		}
+		const entries = await readdir(sourcePath);
+		for (const e of entries) artifacts.add(`${relSource}/${e}`);
+	}
+	return [...artifacts];
+}
+//#endregion
+//#region src/lib/linker.ts
+function deriveTargetOwnership(aiJson) {
+	const ownership = /* @__PURE__ */ new Map();
+	for (const [packageKey, entry] of Object.entries(aiJson.packages)) for (const artifact of entry.linked) for (const targetPath of targetPathsForArtifact(artifact)) {
+		const owners = ownership.get(targetPath) ?? [];
+		owners.push({
+			packageKey,
+			version: entry.version,
+			artifact,
+			targetPath
+		});
+		ownership.set(targetPath, owners);
+	}
+	return ownership;
+}
+async function unlinkFiles(targetPaths) {
+	for (const targetPath of targetPaths) try {
+		if ((await lstat(targetPath)).isSymbolicLink()) await unlink(targetPath);
+	} catch {}
+}
+async function createSymlink(sourcePath, targetPath, result) {
+	let targetStat;
+	try {
+		targetStat = await lstat(targetPath);
+	} catch {}
+	if (targetStat) {
+		if (targetStat.isSymbolicLink()) {
+			const existing = await readlink(targetPath);
+			if (path.resolve(path.dirname(targetPath), existing) === path.resolve(sourcePath)) {
+				result.skipped.push({
+					path: targetPath,
+					reason: "already-linked"
+				});
+				return;
+			}
+			result.skipped.push({
+				path: targetPath,
+				reason: "conflict-wrong-symlink"
+			});
+		} else result.skipped.push({
+			path: targetPath,
+			reason: "conflict-real-file"
+		});
+		return;
+	}
+	await symlink(path.relative(path.dirname(targetPath), sourcePath), targetPath);
+	result.linked.push(targetPath);
+}
+async function linkPackageArtifacts(providers, artifactLabels) {
+	const result = {
+		linked: [],
+		skipped: []
+	};
+	const allowedTargets = /* @__PURE__ */ new Map();
+	for (const artifact of artifactLabels) for (const targetPath of targetPathsForArtifact(artifact, providers)) allowedTargets.set(targetPath, `.ai/${artifact}`);
+	for (const [targetPath, sourcePath] of allowedTargets) {
+		await mkdir(path.dirname(targetPath), { recursive: true });
+		await createSymlink(sourcePath, targetPath, result);
+	}
+	return result;
+}
+async function targetConflictFor$1(sourcePath, targetPath) {
+	let targetStat;
+	try {
+		targetStat = await lstat(targetPath);
+	} catch {
+		return;
+	}
+	if (!targetStat.isSymbolicLink()) return {
+		targetPath,
+		reason: "real-file"
+	};
+	const existing = await readlink(targetPath);
+	if (path.resolve(path.dirname(targetPath), existing) === path.resolve(sourcePath)) return void 0;
+	return {
+		targetPath,
+		reason: "wrong-symlink"
+	};
+}
+async function assertNoTargetConflicts$1(providers, artifactLabels) {
+	const conflicts = [];
+	const allowedTargets = /* @__PURE__ */ new Map();
+	for (const artifact of artifactLabels) for (const targetPath of targetPathsForArtifact(artifact, providers)) allowedTargets.set(targetPath, `.ai/${artifact}`);
+	for (const [targetPath, sourcePath] of allowedTargets) {
+		const conflict = await targetConflictFor$1(sourcePath, targetPath);
+		if (conflict) conflicts.push(conflict);
+	}
+	if (conflicts.length === 0) return;
+	throw new Error(`Conflicts detected — the following target paths are already occupied:\n` + conflicts.map((conflict) => `  ${conflict.targetPath}  (${conflict.reason})`).join("\n") + "\n  Remove or move the conflicting files, then run the command again.");
+}
+function assertNoBlockingSkips(skipped) {
+	const conflicts = skipped.filter((entry) => entry.reason !== "already-linked");
+	if (conflicts.length === 0) return;
+	throw new Error(`Conflicts detected — the following target paths could not be linked:\n` + conflicts.map((conflict) => `  ${conflict.path}  (${conflict.reason})`).join("\n") + "\n  Remove or move the conflicting files, then run the command again.");
+}
+function findRemotePackageConflicts(aiJson, packageKey, providers, artifactLabels) {
+	const ownership = deriveTargetOwnership(aiJson);
+	const conflicts = [];
+	for (const artifact of artifactLabels) for (const targetPath of targetPathsForArtifact(artifact, providers)) for (const owner of ownership.get(targetPath) ?? []) {
+		if (owner.packageKey === packageKey || owner.packageKey === ".") continue;
+		if (packageKey === ".") continue;
+		conflicts.push({
+			targetPath,
+			owner
+		});
+	}
+	return conflicts;
+}
+async function reconcilePackageLinks(aiJson, packageKey, providers, selectedLabels, scopedLabels = selectedLabels) {
+	if (!aiJson.packages[packageKey]) throw new Error(`Package "${packageKey}" is not installed.`);
+	const selected = [...new Set(selectedLabels)];
+	const selectedSet = new Set(selected);
+	const scopedSet = new Set(scopedLabels);
+	const currentLinked = aiJson.packages[packageKey].linked;
+	const preserved = currentLinked.filter((label) => !scopedSet.has(label));
+	const removed = currentLinked.filter((label) => scopedSet.has(label) && !selectedSet.has(label));
+	const conflicts = findRemotePackageConflicts(aiJson, packageKey, providers, selected);
+	if (conflicts.length > 0) throw new Error(`Conflicts detected — the following symlinks are already owned by another package:\n` + conflicts.map(({ targetPath, owner }) => `  ${targetPath}  (owned by ${owner.packageKey}@${owner.version})`).join("\n") + "\n  Remove the conflicting package first with: airig remove <owner/repo>");
+	await assertNoTargetConflicts$1(providers, selected);
+	const ownership = deriveTargetOwnership(aiJson);
+	const targetPathsToUnlink = /* @__PURE__ */ new Set();
+	for (const artifact of removed) for (const targetPath of targetPathsForArtifact(artifact, providers)) if ((ownership.get(targetPath) ?? []).filter((owner) => owner.packageKey !== packageKey).length === 0) targetPathsToUnlink.add(targetPath);
+	await unlinkFiles([...targetPathsToUnlink]);
+	const localOverrides = /* @__PURE__ */ new Set();
+	const localOverrideArtifacts = /* @__PURE__ */ new Set();
+	if (packageKey !== ".") {
+		for (const artifact of selected) for (const targetPath of targetPathsForArtifact(artifact, providers)) for (const owner of ownership.get(targetPath) ?? []) if (owner.packageKey === ".") {
+			localOverrides.add(targetPath);
+			localOverrideArtifacts.add(owner.artifact);
+		}
+	}
+	if (localOverrideArtifacts.size > 0 && aiJson.packages["."]) aiJson.packages["."].linked = aiJson.packages["."].linked.filter((artifact) => !localOverrideArtifacts.has(artifact));
+	const { linked, skipped } = await linkPackageArtifacts(providers, selected);
+	assertNoBlockingSkips(skipped);
+	aiJson.packages[packageKey].linked = [...new Set([...preserved, ...selected])];
+	return {
+		linked,
+		skipped,
+		unlinked: [...targetPathsToUnlink],
+		localOverrides: [...localOverrides]
+	};
+}
+//#endregion
+//#region src/commands/add.ts
+async function runAdd(pkg) {
+	if (pkg === ".") {
+		await runAddLocal();
+		return;
+	}
+	const { owner, repo, tag: inputTag } = parsePackageRef(pkg);
+	const packageKey = `${owner}/${repo}`;
+	const aiJson = await readAiJson();
+	const existingEntry = aiJson.packages[packageKey];
+	if (existingEntry && inputTag && inputTag !== existingEntry.version) throw new Error(`${packageKey} is already installed at ${existingEntry.version}.\n  Use airig update <owner/repo>@<version> to move versions.`);
+	const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+	const { tag: resolvedTag, assetDownloadUrl, immutable } = await fetchReleaseInfo(owner, repo, existingEntry ? existingEntry.version : inputTag, octokit);
+	if (!immutable) throw new Error(`Security restriction: release ${resolvedTag} of ${owner}/${repo} is not immutable.\n  Installing mutable releases is unsafe — assets can be swapped after you review them.
+  Ask the package author to enable immutable releases in their repo settings.`);
+	console.log(`  Downloading ${owner}/${repo}@${resolvedTag}...`);
+	await withExtractedReleaseAi(await downloadAsset(assetDownloadUrl), "airig-add-", async (extractedAiDir) => {
+		const providers = await promptProviders();
+		if (providers.length === 0) {
+			console.log("No providers selected.");
+			return;
+		}
+		const currentLinked = existingEntry?.linked ?? [];
+		const selectable = (await listArtifacts(extractedAiDir, providers)).filter((artifact) => !currentLinked.includes(artifact));
+		if (selectable.length === 0) {
+			console.log(`No new files found for ${packageKey}@${resolvedTag}.`);
+			return;
+		}
+		const selectedNew = await checkbox({
+			message: "Select files to add:",
+			choices: selectable.map((label) => ({
+				value: label,
+				name: label,
+				checked: currentLinked.length === 0
+			}))
+		});
+		if (selectedNew.length === 0) {
+			console.log("No files selected.");
+			return;
+		}
+		const artifactsToCopy = await expandReleaseArtifactsWithSymlinkDependencies(extractedAiDir, selectedNew);
+		assertNoRemoteConflicts(aiJson, packageKey, providers, selectedNew);
+		assertNoSourceConflicts(packageKey, currentLinked, artifactsToCopy);
+		await assertNoTargetConflicts(selectedNew, providers);
+		await copyReleaseArtifactsToLocal(extractedAiDir, selectedNew);
+		const entry = {
+			version: resolvedTag,
+			linked: []
+		};
+		if (!existingEntry) addPackage(aiJson, packageKey, entry);
+		const selected = [...new Set([...currentLinked, ...selectedNew])];
+		await reconcilePackageLinks(aiJson, packageKey, providers, selected, selected);
+		await writeAiJson(aiJson);
+		console.log(`\nAdded ${selectedNew.length} file(s) from ${owner}/${repo}@${resolvedTag}.`);
+	});
+}
+function assertNoSourceConflicts(packageKey, currentLinked, artifactsToCopy) {
+	const conflicts = artifactsToCopy.filter((artifact) => !currentLinked.includes(artifact)).filter((artifact) => existsSync(path.join(".ai", artifact)));
+	if (conflicts.length === 0) return;
+	throw new Error(`Conflicts detected — ${packageKey} would overwrite existing .ai source files:\n` + conflicts.map((artifact) => `  .ai/${artifact}`).join("\n") + "\n  Remove the conflicting files, then run add again.");
+}
+async function runAddLocal() {
+	const aiJson = await readAiJson();
+	aiJson.packages["."] ??= {
+		version: "*",
+		linked: []
+	};
+	const providers = await promptProviders();
+	if (providers.length === 0) {
+		console.log("No providers selected.");
+		return;
+	}
+	const currentLinked = aiJson.packages["."].linked;
+	const selectable = (await listArtifacts(".ai", providers)).filter((artifact) => !currentLinked.includes(artifact));
+	if (selectable.length === 0) {
+		console.log("No new local files found.");
+		return;
+	}
+	const selectedNew = await checkbox({
+		message: "Select local files to add:",
+		choices: selectable.map((label) => ({
+			value: label,
+			name: label,
+			checked: true
+		}))
+	});
+	if (selectedNew.length === 0) {
+		console.log("No files selected.");
+		return;
+	}
+	await assertNoTargetConflicts(selectedNew, providers);
+	const selected = [...new Set([...currentLinked, ...selectedNew])];
+	await reconcilePackageLinks(aiJson, ".", providers, selected, selected);
+	await writeAiJson(aiJson);
+	console.log(`\nAdded ${selectedNew.length} local file(s).`);
+}
+async function promptProviders() {
+	return checkbox({
+		message: "Select providers to add:",
+		choices: Object.keys(PROVIDER_REGISTRY).map((p) => ({
+			value: p,
+			name: p
+		}))
+	});
+}
+function assertNoRemoteConflicts(aiJson, packageKey, providers, artifacts) {
+	const conflicts = findRemotePackageConflicts(aiJson, packageKey, providers, artifacts);
+	if (conflicts.length === 0) return;
+	throw new Error(`Conflicts detected — the following symlinks are already owned by another package:\n` + conflicts.map(({ targetPath, owner }) => `  ${targetPath}  (owned by ${owner.packageKey}@${owner.version})`).join("\n") + "\n  Remove the conflicting files first with: airig remove");
+}
+async function assertNoTargetConflicts(artifacts, providers) {
+	const conflicts = [];
+	for (const artifact of artifacts) for (const targetPath of targetPathsForArtifact(artifact, providers)) {
+		const conflict = await targetConflictFor(artifact, targetPath);
+		if (conflict) conflicts.push(conflict);
+	}
+	if (conflicts.length === 0) return;
+	throw new Error(`Conflicts detected — the following target paths are already occupied:\n` + conflicts.map((conflict) => `  ${conflict.targetPath}  (${conflict.reason})`).join("\n") + "\n  Remove or move the conflicting files, then run add again.");
+}
+async function targetConflictFor(artifact, targetPath) {
+	let targetStat;
+	try {
+		targetStat = await lstat(targetPath);
+	} catch {
+		return;
+	}
+	if (!targetStat.isSymbolicLink()) return {
+		targetPath,
+		reason: "real-file"
+	};
+	const existing = await readlink(targetPath);
+	if (path.resolve(path.dirname(targetPath), existing) === path.resolve(`.ai/${artifact}`)) return void 0;
+	return {
+		targetPath,
+		reason: "wrong-symlink"
+	};
+}
+const addCommand = new Command("add").description("Interactively add active AI Setup artifacts").argument("<package>", "Package to add, e.g. owner/repo, owner/repo@1.2.0, or .").action(async (pkg) => {
+	try {
+		await runAdd(pkg);
+	} catch (err) {
+		console.error(`✖ ${err.message}`);
+		process.exit(1);
+	}
+});
+//#endregion
+//#region src/commands/remove.ts
+async function runRemove(pkg) {
+	const aiJson = await readAiJson();
+	const packageKeys = pkg ? [pkg] : Object.keys(aiJson.packages);
+	if (packageKeys.length === 0) throw new Error("No AI Setup artifacts are installed.");
+	for (const packageKey of packageKeys) if (!aiJson.packages[packageKey]) throw new Error(`Package "${packageKey}" is not installed.\n  Check installed packages in .ai/ai.json`);
+	const choices = packageKeys.flatMap((packageKey) => aiJson.packages[packageKey].linked.map((artifact) => ({
+		value: {
+			packageKey,
+			artifact
+		},
+		name: `${packageKey} / ${categoryForArtifact(artifact)} / ${artifact}`,
+		checked: false
+	})));
+	if (choices.length === 0) {
+		for (const packageKey of packageKeys) removePackage(aiJson, packageKey);
+		await writeAiJson(aiJson);
+		console.log("No linked files found.");
+		return;
+	}
+	const selected = await checkbox({
+		message: "Select files to remove:",
+		choices
+	});
+	if (selected.length === 0) {
+		console.log("No files selected.");
+		return;
+	}
+	const selectedByPackage = /* @__PURE__ */ new Map();
+	for (const { packageKey, artifact } of selected) {
+		const artifacts = selectedByPackage.get(packageKey) ?? /* @__PURE__ */ new Set();
+		artifacts.add(artifact);
+		selectedByPackage.set(packageKey, artifacts);
+	}
+	let symlinkCount = 0;
+	let sourceCount = 0;
+	for (const [packageKey, artifacts] of selectedByPackage) {
+		const isLocal = packageKey === ".";
+		const targetPaths = [...artifacts].flatMap((artifact) => targetPathsForArtifact(artifact));
+		await unlinkFiles([...new Set(targetPaths)]);
+		symlinkCount += targetPaths.length;
+		if (!isLocal) for (const artifact of artifacts) {
+			await rm(`.ai/${artifact}`, {
+				recursive: true,
+				force: true
+			});
+			sourceCount += 1;
+		}
+		const entry = aiJson.packages[packageKey];
+		entry.linked = entry.linked.filter((artifact) => !artifacts.has(artifact));
+		if (entry.linked.length === 0) removePackage(aiJson, packageKey);
+	}
+	await writeAiJson(aiJson);
+	console.log(`\nRemoved ${selected.length} file(s), ${symlinkCount} symlink target(s), and ${sourceCount} source file(s).`);
+}
+function categoryForArtifact(artifact) {
+	if (artifact === "AGENTS.md" || artifact === "CLAUDE.md") return "Project Instruction Files";
+	if (artifact.startsWith("skills/")) return "Skills";
+	if (artifact.includes("/commands/")) return "Custom Commands";
+	if (artifact.includes("/agents/")) return "Agents";
+	if (artifact.includes("/hooks/")) return "Hooks";
+	return "Other";
+}
+const removeCommand = new Command("remove").description("Interactively remove active AI Setup artifacts").argument("[package]", "Optional package to remove from, e.g. owner/repo or .").action(async (pkg) => {
+	try {
+		await runRemove(pkg);
+	} catch (err) {
+		console.error(`✖ ${err.message}`);
+		process.exit(1);
+	}
+});
+//#endregion
+//#region src/commands/update.ts
+async function runUpdate(pkg) {
+	const { owner, repo, tag } = parseExactPackageRef(pkg);
+	const packageKey = `${owner}/${repo}`;
+	const providers = Object.keys(PROVIDER_REGISTRY);
+	const aiJson = await readAiJson();
+	const entry = aiJson.packages[packageKey];
+	if (!entry) throw new Error(`Package "${packageKey}" is not installed.\n  Install it first with: airig add <owner/repo>[@version]`);
+	const { tag: resolvedTag, assetDownloadUrl, immutable } = await fetchReleaseInfo(owner, repo, tag, new Octokit({ auth: process.env.GITHUB_TOKEN }));
+	if (!immutable) throw new Error(`Security restriction: release ${resolvedTag} of ${owner}/${repo} is not immutable.\n  Updating from mutable releases is unsafe — assets can be swapped after you review them.
+  Ask the package author to enable immutable releases in their repo settings.`);
+	console.log(`  Downloading ${owner}/${repo}@${resolvedTag}...`);
+	await withExtractedReleaseAi(await downloadAsset(assetDownloadUrl), "airig-update-", async (extractedAiDir) => {
+		const newArtifacts = await listArtifacts(extractedAiDir, providers);
+		const newArtifactSet = new Set(newArtifacts);
+		const previousVersion = entry.version;
+		const previousLinked = [...entry.linked];
+		const prunedLinked = previousLinked.filter((artifact) => newArtifactSet.has(artifact));
+		const deletedLinked = previousLinked.filter((artifact) => !newArtifactSet.has(artifact));
+		await copyReleaseArtifactsToLocal(extractedAiDir, prunedLinked);
+		const targetsToUnlink = /* @__PURE__ */ new Set();
+		for (const artifact of deletedLinked) {
+			await rm(`.ai/${artifact}`, {
+				recursive: true,
+				force: true
+			});
+			for (const targetPath of targetPathsForArtifact(artifact, providers)) targetsToUnlink.add(targetPath);
+		}
+		await unlinkFiles([...targetsToUnlink]);
+		entry.version = resolvedTag;
+		entry.linked = prunedLinked;
+		await reconcilePackageLinks(aiJson, packageKey, providers, prunedLinked, prunedLinked);
+		await writeAiJson(aiJson);
+		console.log(`\nUpdated ${owner}/${repo} from ${previousVersion} to ${resolvedTag} (${prunedLinked.length} active file(s) refreshed, ${deletedLinked.length} pruned).`);
+	});
+}
+const updateCommand = new Command("update").description("Refresh an installed Setup Release at an exact immutable version").argument("<package>", "Package to update, e.g. owner/repo@1.2.0").action(async (pkg) => {
+	try {
+		await runUpdate(pkg);
+	} catch (err) {
+		console.error(`✖ ${err.message}`);
+		process.exit(1);
+	}
+});
+//#endregion
+//#region src/index.ts
+const program = new Command("airig").description("Manage project-scoped AI Setup artifacts");
+program.addCommand(publishCommand);
+program.addCommand(addCommand);
+program.addCommand(updateCommand);
+program.addCommand(removeCommand);
+program.parse();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@airig/cli",
+  "version": "0.0.1",
+  "description": "Distribute and manage AI setups across providers",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jd-solanki/airig.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jd-solanki/airig/issues"
+  },
+  "homepage": "https://github.com/jd-solanki/airig#readme",
+  "packageManager": "pnpm@10.19.0",
+  "engines": {
+    "node": "^24.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "airig": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "release": "bumpp",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pkg:link": "pnpm link --global",
+    "pkg:unlink": "pnpm unlink --global airig"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.2",
+    "@octokit/rest": "^21.1.1",
+    "archiver": "^7.0.1",
+    "commander": "^14.0.0",
+    "extract-zip": "^2.0.1"
+  },
+  "devDependencies": {
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^22.15.21",
+    "bumpp": "^11.1.0",
+    "tsdown": "^0.12.6",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.2"
+  }
+}