@rbbtsn0w/adg 0.1.1 → 0.2.0

package/dist/bin/adg.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkForUpdate, formatUpdateNotice } from "../src/update-check.js";
 import { ADAPTER_TARGETS } from "../src/adapters/index.js";
 import { initScaffold } from "../src/commands/init.js";
 import { adaptPlugin } from "../src/commands/adapt.js";
@@ -659,12 +660,43 @@ function runSkills(verb, rest) {
     const r = spawnSync(process.execPath, skillsChildArgv(entry, args), { stdio: "inherit" });
     process.exit(r.status ?? 1);
 }
+/**
+ * Read the package version from package.json.
+ *
+ * Works in both source mode (`bin/adg.ts` → package.json is 1 level up) and
+ * compiled mode (`dist/bin/adg.js` → package.json is 2 levels up).
+ */
+export function getVersion() {
+    const self = fileURLToPath(import.meta.url);
+    // Source: bin/adg.ts  → up 1 level reaches the repo root.
+    // Compiled: dist/bin/adg.js → up 2 levels reaches the repo root.
+    const up = self.endsWith(".ts") ? ".." : join("..", "..");
+    const pkg = JSON.parse(readFileSync(join(dirname(self), up, "package.json"), "utf8"));
+    return pkg.version;
+}
 async function main(argv) {
     const [domain, verb, ...rest] = argv;
+    // --version / -v at the root level: print version and exit.
+    // Note: `-v` is also the short flag for `--verbose` in subcommands, but only
+    // when it appears *after* a domain (e.g. `adg plugins list -v`). Checking
+    // argv[0] here means we only intercept `adg -v` / `adg --version`, never
+    // a subcommand's own flags.
+    if (domain === "--version" || domain === "-v") {
+        console.log(getVersion());
+        return;
+    }
     if (!domain || domain === "help" || domain === "--help" || domain === "-h") {
         console.log(TOP_USAGE);
         return;
     }
+    // Check for an available update (reads local cache; schedules a background
+    // network refresh when the cache is stale — the refresh uses an unreffed
+    // socket so it cannot delay process exit).
+    const currentVersion = getVersion();
+    const latestVersion = checkForUpdate(currentVersion);
+    if (latestVersion) {
+        process.stderr.write(formatUpdateNotice(currentVersion, latestVersion));
+    }
     switch (domain) {
         case "plugins":
         case "plugin": // tolerated alias

package/dist/src/update-check.js

@@ -0,0 +1,118 @@
+/**
+ * Non-blocking update check for the ADG CLI.
+ *
+ * On every invocation we read a local cache file to decide whether to show an
+ * "update available" notice. When the cache is stale (older than 24 h) we
+ * schedule a background HTTP request — using an unreffed socket so it cannot
+ * block the process from exiting — that refreshes the cache for the *next* run.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import https from "node:https";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { compare, parseVersion } from "./semver.js";
+const PACKAGE_NAME = "@rbbtsn0w/adg";
+// URL-encode the slash in the scoped package name for the npm registry API.
+const REGISTRY_URL = `https://registry.npmjs.org/@rbbtsn0w%2Fadg/latest`;
+const CACHE_FILENAME = "update-check.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+/** Resolve the directory that holds the update-check cache file. */
+export function updateCacheDir(env = process.env) {
+    const stateHome = env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(stateHome, "adg");
+}
+function cachePath(env = process.env) {
+    return join(updateCacheDir(env), CACHE_FILENAME);
+}
+/** Read the on-disk cache, returning null on any error. */
+export function readUpdateCache(env = process.env) {
+    try {
+        const raw = readFileSync(cachePath(env), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the cache, creating the directory if needed. Silently ignores errors. */
+export function writeUpdateCache(cache, env = process.env) {
+    try {
+        const dir = updateCacheDir(env);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(cachePath(env), JSON.stringify(cache), "utf8");
+    }
+    catch {
+        // Ignore write errors (read-only FS, permissions, etc.)
+    }
+}
+/**
+ * Fire-and-forget background fetch of the latest version from the npm registry.
+ * The socket is unreffed so Node can exit naturally without waiting for the
+ * request to complete — the cache will be refreshed on the *next* run.
+ */
+export function scheduleUpdateCacheRefresh(currentVersion, env = process.env) {
+    try {
+        const req = https.get(REGISTRY_URL, { headers: { "User-Agent": `adg/${currentVersion}`, Accept: "application/json" } }, (res) => {
+            let body = "";
+            res.on("data", (chunk) => { body += String(chunk); });
+            res.on("end", () => {
+                try {
+                    const data = JSON.parse(body);
+                    if (typeof data.version === "string") {
+                        writeUpdateCache({ latestVersion: data.version, checkedAt: new Date().toISOString() }, env);
+                    }
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            });
+            res.resume(); // drain the response so the socket is released
+        });
+        // Destroy the request after 5 s to avoid a long-running socket that
+        // could delay the next run's check (not the current run — the socket is
+        // unreffed so the process exits freely).
+        req.setTimeout(5000, () => req.destroy());
+        req.on("error", () => { }); // Ignore network errors
+        // Unref as soon as the underlying socket is assigned so the request does
+        // not keep the event loop alive after the command finishes.
+        req.on("socket", (socket) => socket.unref());
+    }
+    catch {
+        // If https.get itself throws, ignore it silently.
+    }
+}
+/**
+ * Check whether an update is available and print a notice if so.
+ *
+ * Reads the local cache synchronously (fast, no network) and, when the cache
+ * is stale, schedules a background refresh for the next invocation.
+ *
+ * @param currentVersion  The version string from package.json (e.g. "0.1.1").
+ * @returns The newer version string if an update is available, otherwise undefined.
+ */
+export function checkForUpdate(currentVersion, env = process.env, refresh = scheduleUpdateCacheRefresh) {
+    const cache = readUpdateCache(env);
+    const now = Date.now();
+    const checkedAt = cache ? new Date(cache.checkedAt).getTime() : 0;
+    const checkedAtMs = Number.isFinite(checkedAt) ? checkedAt : 0;
+    const isStale = !cache || now - checkedAtMs > CACHE_TTL_MS;
+    if (isStale) {
+        refresh(currentVersion, env);
+    }
+    if (!cache)
+        return undefined;
+    try {
+        const current = parseVersion(currentVersion);
+        const latest = parseVersion(cache.latestVersion);
+        return compare(latest, current) > 0 ? cache.latestVersion : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Format an update notice for display on stderr. */
+export function formatUpdateNotice(currentVersion, latestVersion) {
+    return (`\n  Update available: ${currentVersion} → ${latestVersion}\n` +
+        `  Run: npm install -g ${PACKAGE_NAME}@latest\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbbtsn0w/adg",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Agent Directory Group (ADG) toolkit — two domains: plugins and skills.",
   "type": "module",
   "license": "MIT",