@airig/cli 0.0.1 → 0.0.5

package/README.md

@@ -7,7 +7,7 @@ Distribute and manage AI setups across coding agents from one project-local `.ai
 Install the CLI globally to use the short `airig` command:
 
 ```sh
-npm install --global airig
+npm install --global @airig/cli
 ```
 
 ```sh
@@ -18,34 +18,68 @@ airig remove [owner/repo|.]
 airig publish [tag]
 ```
 
-For one-off usage without a global install, run the npm package directly:
+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]
+npx @airig/cli add <owner/repo>[@version]
+npx @airig/cli add .
+npx @airig/cli update <owner/repo>@<version>
+npx @airig/cli remove [owner/repo|.]
+npx @airig/cli publish [tag]
 ```
 
-The package is named `airig`; the installed binary is `airig`.
+The Package is named `@airig/cli`; 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.
+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.
+Remote Setup Releases are pinned to exact versions in `.ai/ai.json`. `add` and `update` verify GitHub release immutability before writing remote content.
+
+## Maintainer Releases
+
+Use Package releases to publish the `@airig/cli` npm Package, which provides the `airig` CLI:
+
+```sh
+pnpm release
+```
+
+The release script is maintainer-facing. It uses `bumpp` to choose the next Package version, update Package metadata, create the release commit, create a `v<version>` tag, and push the commit and tag. Pushed `v*` tags trigger `.github/workflows/publish-package.yml`, which installs dependencies, runs tests, builds the CLI, and publishes the Package to npm.
+
+npm publishing uses trusted publishing with GitHub Actions OIDC. Do not add a long-lived npm token for Package releases.
+
+Package releases are separate from Setup Releases. `airig publish [tag]` creates a GitHub immutable Setup Release containing `ai.zip` from `.ai/`; it does not publish the npm Package.
 
 ## Author Workflow
 
-1. Create setup artifacts under `.ai/`.
+1. Create AI 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.
+4. Run `airig publish` to upload `ai.zip` to an immutable GitHub Setup Release.
 5. Share `airig add yourname/repo`.
 
+For AI Setup repositories, use [`bumpp`](https://github.com/antfu-collective/bumpp)
+to create and push release tags from a package script:
+
+```json
+{
+  "scripts": {
+    "release": "bumpp"
+  }
+}
+```
+
+To publish Setup Releases from your AI Setup repository with GitHub Actions, copy
+`resources/templates/publish.yml` to `.github/workflows/publish.yml` in that
+repository. The workflow publishes when `bumpp` pushes a `v*` tag and expects an
+`AIRIG_PUBLISH_TOKEN` repository secret. Create that secret from a fine-grained
+GitHub PAT scoped only to the Setup Release repository with:
+
+- `Contents`: Read and write
+- `Administration`: Read-only
+
 ## 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`.
+- GitHub immutable releases enabled for repositories that publish Setup Releases.
+- `GITHUB_TOKEN` when running `publish`. For local use or custom GitHub Actions workflows, use a fine-grained GitHub PAT scoped to the Setup Release repository with `Contents` read/write access to create releases and `Administration` read-only access so `airig publish` can verify immutable releases are enabled before publishing.

package/dist/index.js

@@ -1,20 +1,21 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { execSync } from "node:child_process";
+import { execSync, spawn } 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 { ZipArchive } from "archiver";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { Octokit } from "@octokit/rest";
 import { checkbox } from "@inquirer/prompts";
 import os from "node:os";
 import extractZip from "extract-zip";
+import { fileURLToPath } from "node:url";
 //#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 archive = new ZipArchive({ zlib: { level: 9 } });
 		const sourceBaseName = path.basename(sourceDir);
 		output.on("close", resolve);
 		archive.on("error", reject);
@@ -871,12 +872,196 @@ const updateCommand = new Command("update").description("Refresh an installed Se
 	}
 });
 //#endregion
+//#region src/lib/update-notifier.ts
+const PACKAGE_NAME = "@airig/cli";
+const UPDATE_CHECK_INTERVAL_MS = 1440 * 60 * 1e3;
+const UPDATE_NOTIFICATION_INTERVAL_MS = 1440 * 60 * 1e3;
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@airig%2fcli/latest";
+function maybeNotifyForUpdate(options = {}) {
+	const env = options.env ?? process.env;
+	const stderr = options.stderr ?? process.stderr;
+	if (shouldSkipUpdateNotifier(env, stderr)) return;
+	const packageJsonPath = options.packageJsonPath ?? findOwnPackageJsonPath();
+	if (!isGlobalInstall(path.dirname(packageJsonPath), options.cwd ?? process.cwd())) return;
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const currentVersion = readPackageVersion(packageJsonPath);
+	const statePath = path.join(options.stateDir ?? defaultStateDir(env), "update-notifier.json");
+	let state = readUpdateState(statePath);
+	if (isUpdateCheckDue(state, now)) {
+		state = {
+			...state,
+			lastUpdateCheck: now.toUTCString()
+		};
+		writeUpdateState(statePath, state);
+		(options.spawnUpdateCheck ?? spawnUpdateCheck)(statePath);
+	}
+	if (!state.latestVersion || !isVersionGreater(state.latestVersion, currentVersion)) return;
+	if (!isNotificationDue(state, now)) return;
+	stderr.write(formatUpdateMessage({
+		currentVersion,
+		latestVersion: state.latestVersion
+	}));
+	writeUpdateState(statePath, {
+		...state,
+		lastNotifiedAt: now.toUTCString()
+	});
+}
+function shouldSkipUpdateNotifier(env, stderr) {
+	return Boolean(env.NO_UPDATE_NOTIFIER || env.AIRIG_NO_UPDATE_NOTIFIER || env.CI || env.NODE_ENV === "test" || !stderr.isTTY);
+}
+function readPackageVersion(packageJsonPath) {
+	const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	if (!parsed.version) throw new Error(`Could not read ${PACKAGE_NAME} version from ${packageJsonPath}`);
+	return parsed.version;
+}
+function defaultStateDir(env) {
+	if (env.AIRIG_STATE_DIR) return env.AIRIG_STATE_DIR;
+	if (env.XDG_STATE_HOME) return path.join(env.XDG_STATE_HOME, "airig");
+	return path.join(os.homedir(), ".local", "state", "airig");
+}
+function readUpdateState(statePath) {
+	try {
+		return JSON.parse(readFileSync(statePath, "utf8"));
+	} catch {
+		return {};
+	}
+}
+function writeUpdateState(statePath, state) {
+	mkdirSync(path.dirname(statePath), { recursive: true });
+	writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+function isUpdateCheckDue(state, now) {
+	return isIntervalDue(state.lastUpdateCheck, now, UPDATE_CHECK_INTERVAL_MS);
+}
+function isNotificationDue(state, now) {
+	return isIntervalDue(state.lastNotifiedAt, now, UPDATE_NOTIFICATION_INTERVAL_MS);
+}
+function isIntervalDue(previous, now, intervalMs) {
+	if (!previous) return true;
+	const previousTime = new Date(previous).valueOf();
+	if (Number.isNaN(previousTime)) return true;
+	return now.valueOf() - previousTime >= intervalMs;
+}
+function spawnUpdateCheck(statePath) {
+	spawn(process.execPath, [
+		"--input-type=module",
+		"--eval",
+		UPDATE_CHECK_SCRIPT
+	], {
+		detached: true,
+		stdio: "ignore",
+		env: {
+			...process.env,
+			AIRIG_UPDATE_STATE_PATH: statePath,
+			AIRIG_UPDATE_REGISTRY_URL: REGISTRY_LATEST_URL
+		}
+	}).unref();
+}
+const UPDATE_CHECK_SCRIPT = `
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const statePath = process.env.AIRIG_UPDATE_STATE_PATH
+const registryUrl = process.env.AIRIG_UPDATE_REGISTRY_URL
+const now = new Date().toUTCString()
+
+async function readState() {
+  try {
+    return JSON.parse(await readFile(statePath, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+async function writeState(state) {
+  await mkdir(path.dirname(statePath), { recursive: true })
+  await writeFile(statePath, JSON.stringify(state, null, 2) + '\\n')
+}
+
+const state = await readState()
+
+try {
+  const response = await fetch(registryUrl, { signal: AbortSignal.timeout(3000) })
+  const data = response.ok ? await response.json() : undefined
+  await writeState({ ...state, lastUpdateCheck: now, latestVersion: data?.version ?? state.latestVersion })
+} catch {
+  await writeState({ ...state, lastUpdateCheck: now })
+}
+`;
+function isVersionGreater(candidate, current) {
+	const candidateVersion = parseSemver(candidate);
+	const currentVersion = parseSemver(current);
+	if (!candidateVersion || !currentVersion) return candidate !== current;
+	for (let i = 0; i < 3; i += 1) {
+		const diff = candidateVersion.numbers[i] - currentVersion.numbers[i];
+		if (diff !== 0) return diff > 0;
+	}
+	if (candidateVersion.prerelease === currentVersion.prerelease) return false;
+	if (!candidateVersion.prerelease) return Boolean(currentVersion.prerelease);
+	if (!currentVersion.prerelease) return false;
+	return candidateVersion.prerelease.localeCompare(currentVersion.prerelease, void 0, { numeric: true }) > 0;
+}
+function parseSemver(version) {
+	const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+	if (!match) return void 0;
+	return {
+		numbers: [
+			Number(match[1]),
+			Number(match[2]),
+			Number(match[3])
+		],
+		prerelease: match[4] ?? ""
+	};
+}
+function isGlobalInstall(packageRoot, cwd) {
+	if (isOneOffInstallPath(packageRoot)) return false;
+	if (findProjectRootForLocalInstall(packageRoot, cwd)) return false;
+	return true;
+}
+function findOwnPackageJsonPath() {
+	let currentDir = path.dirname(fileURLToPath(import.meta.url));
+	while (true) {
+		const candidate = path.join(currentDir, "package.json");
+		try {
+			if (JSON.parse(readFileSync(candidate, "utf8")).name === PACKAGE_NAME) return candidate;
+		} catch {}
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) break;
+		currentDir = parentDir;
+	}
+	throw new Error(`Could not locate ${PACKAGE_NAME} package metadata`);
+}
+function isOneOffInstallPath(packageRoot) {
+	const normalizedRoot = packageRoot.split(path.sep).join("/");
+	return normalizedRoot.includes("/_npx/") || normalizedRoot.includes("/.npm/_npx/");
+}
+function findProjectRootForLocalInstall(packageRoot, cwd) {
+	const segments = packageRoot.split(path.sep);
+	for (let index = segments.length - 1; index > 0; index -= 1) {
+		if (segments[index] !== "node_modules") continue;
+		const projectRoot = segments.slice(0, index).join(path.sep) || path.sep;
+		if (existsSync(path.join(projectRoot, "package.json")) && isSameOrInside(cwd, projectRoot)) return projectRoot;
+	}
+}
+function isSameOrInside(candidate, parent) {
+	const relative = path.relative(parent, candidate);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function formatUpdateMessage(opts) {
+	return `\nA new airig version is available: ${opts.currentVersion} -> ${opts.latestVersion}.\nYour installed airig package is outdated. Please upgrade to the latest version.\n\n`;
+}
+//#endregion
 //#region src/index.ts
-const program = new Command("airig").description("Manage project-scoped AI Setup artifacts");
+const program = new Command("airig").description("Manage project-scoped AI Setup artifacts").version("0.0.5");
 program.addCommand(publishCommand);
 program.addCommand(addCommand);
 program.addCommand(updateCommand);
 program.addCommand(removeCommand);
-program.parse();
+program.hook("postAction", () => {
+	try {
+		maybeNotifyForUpdate();
+	} catch {}
+});
+await program.parseAsync();
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@airig/cli",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "description": "Distribute and manage AI setups across providers",
   "license": "MIT",
   "type": "module",
@@ -38,12 +38,12 @@
   "dependencies": {
     "@inquirer/prompts": "^7.5.2",
     "@octokit/rest": "^21.1.1",
-    "archiver": "^7.0.1",
+    "archiver": "^8.0.0",
     "commander": "^14.0.0",
     "extract-zip": "^2.0.1"
   },
   "devDependencies": {
-    "@types/archiver": "^6.0.3",
+    "@types/archiver": "^8.0.0",
     "@types/node": "^22.15.21",
     "bumpp": "^11.1.0",
     "tsdown": "^0.12.6",