@aria_asi/cli 0.2.3 → 0.2.4

package/bin/aria.js

@@ -8,6 +8,16 @@ import { AriaChat } from '../dist/aria-connector/src/chat.js';
 import { checkHarnessHealth } from '../dist/aria-connector/src/harness-client.js';
 import { login, status, logout, revoke } from '../dist/aria-connector/src/auth-commands.js';
 import { installHooks } from '../dist/aria-connector/src/install-hooks.js';
+import { maybePrintUpdateNotice, checkForUpdate } from '../dist/aria-connector/src/self-update.js';
+
+// ── Self-update notice (non-blocking, rate-limited once per 24h) ──
+// Fires-and-forgets — the registry check runs in parallel with command
+// dispatch and prints a one-line notice on stderr if newer version available.
+// Hamza 2026-04-26: continuous overnight improvement reaches clients via
+// this primitive. Kill-switch: ARIA_SELF_UPDATE=off env.
+if (process.env.ARIA_SELF_UPDATE !== 'off') {
+  maybePrintUpdateNotice().catch(() => {});
+}
 
 // ── Auth + install subcommands — handled BEFORE the chat flow.
 // Hamza 2026-04-26: license-aware CLI for client-tonight ship +
@@ -16,7 +26,24 @@ import { installHooks } from '../dist/aria-connector/src/install-hooks.js';
 const command = process.argv[2];
 const args = process.argv.slice(3);
 
-if (command === 'install-hooks') {
+if (command === 'check-update') {
+  // Force a check + print result, bypassing the 24h rate limit
+  checkForUpdate({ force: true }).then((result) => {
+    if (!result.ok) {
+      console.error(`I couldn't check for updates: ${result.reason}`);
+      process.exit(1);
+    }
+    if (result.updateAvailable) {
+      console.log(`  ${result.message}`);
+    } else {
+      console.log(`  You're on the latest version (${result.current}). Nothing to do.`);
+    }
+    process.exit(0);
+  }).catch((err) => {
+    console.error(`I hit an unexpected error checking for updates: ${err && err.message ? err.message : err}`);
+    process.exit(1);
+  });
+} else if (command === 'install-hooks') {
   const force = args.includes('--force');
   const harnessUrlIdx = args.indexOf('--harness-url');
   const harnessUrl = harnessUrlIdx >= 0 && args[harnessUrlIdx + 1] ? args[harnessUrlIdx + 1] : undefined;

package/dist/aria-connector/src/self-update.d.ts

@@ -0,0 +1,22 @@
+export interface UpdateCheckResult {
+    ok: boolean;
+    current?: string;
+    latest?: string;
+    updateAvailable?: boolean;
+    message?: string;
+    reason?: string;
+}
+/**
+ * Check the registry for the latest @aria_asi/cli version. Rate-limited
+ * to once per CHECK_INTERVAL_MS (24h) via a timestamp file in ~/.aria.
+ * Caller can pass force=true to bypass the rate limit (used by `aria check-update`).
+ */
+export declare function checkForUpdate(opts?: {
+    force?: boolean;
+}): Promise<UpdateCheckResult>;
+/**
+ * Convenience: check + print the notice if available. Non-blocking, silent
+ * on errors. Called from bin/aria.js on startup.
+ */
+export declare function maybePrintUpdateNotice(): Promise<void>;
+//# sourceMappingURL=self-update.d.ts.map

package/dist/aria-connector/src/self-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update.d.ts","sourceRoot":"","sources":["../../../src/self-update.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiDD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqD/F;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ5D"}

package/dist/aria-connector/src/self-update.js

@@ -0,0 +1,162 @@
+// self-update — checks the npm registry for newer @aria_asi/cli versions
+// and surfaces a one-line notice. Doesn't auto-install (clients control
+// their tooling); just informs.
+//
+// Direction: Hamza 2026-04-26 — "does the package auto update when we
+// enhance it on our enhance? so we can continually improve all night using
+// arias background work we should imrpove to do that once we finish".
+// This is the primitive that closes the overnight-improvement loop:
+// Aria publishes 0.2.5 / 0.3.0 / etc.; clients see the notice on their
+// next `aria <cmd>` invocation; they upgrade with one command.
+//
+// Doctrine bindings:
+//   - feedback_no_demos.md — real overnight evolution, real registry check
+//   - feedback_no_timeouts_doctrine.md — fetch with no AbortSignal.timeout;
+//     use bare try/catch, real-error-driven backpressure
+//   - project_phase_10_endless_army_orchestration.md — continuous shipping
+//     is the Phase 10 north star; self-update is its delivery mechanism
+//
+// Behavior:
+//   - Reads installed version from package.json (resolved via import.meta.url
+//     walk to find the package root)
+//   - Reads ~/.aria/last-update-check timestamp; if checked <24h ago, skip
+//   - GET registry.npmjs.org/@aria_asi/cli for latest dist-tag
+//   - semver-compare; if newer, return {updateAvailable: true, latest, current, message}
+//   - Write timestamp on every check (success or skip-due-to-rate-limit)
+//   - Failures are silent (network down, registry blip — never block CLI startup)
+//
+// Privacy: the request to npmjs only sends User-Agent (npm registry public).
+// No client identity, no telemetry beyond what the public registry already logs.
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const ARIA_DIR = join(homedir(), '.aria');
+const LAST_CHECK_PATH = join(ARIA_DIR, 'last-update-check');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+const REGISTRY_URL = 'https://registry.npmjs.org/@aria_asi%2Fcli';
+/**
+ * Find the package's own version by walking up from this file's runtime
+ * path until we hit the package.json with name @aria_asi/cli.
+ */
+function findInstalledVersion() {
+    try {
+        const here = fileURLToPath(import.meta.url);
+        let cur = dirname(here);
+        for (let i = 0; i < 8; i++) {
+            const pkgPath = join(cur, 'package.json');
+            if (existsSync(pkgPath)) {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === '@aria_asi/cli' && typeof pkg.version === 'string') {
+                    return pkg.version;
+                }
+            }
+            const parent = dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+    }
+    catch { /* fall through */ }
+    return null;
+}
+/**
+ * Compare semver strings — returns 1 if a>b, -1 if a<b, 0 if equal.
+ * Pre-release suffixes (e.g. 0.2.4-beta) sort lower than the same base.
+ */
+function compareSemver(a, b) {
+    const parse = (s) => {
+        const [main, ...preParts] = s.split('-');
+        const nums = main.split('.').map((n) => parseInt(n, 10));
+        while (nums.length < 3)
+            nums.push(0);
+        return { nums, pre: preParts.join('-') };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        if (pa.nums[i] > pb.nums[i])
+            return 1;
+        if (pa.nums[i] < pb.nums[i])
+            return -1;
+    }
+    // Equal numerics — pre-release sorts before release
+    if (pa.pre && !pb.pre)
+        return -1;
+    if (!pa.pre && pb.pre)
+        return 1;
+    return pa.pre.localeCompare(pb.pre);
+}
+/**
+ * Check the registry for the latest @aria_asi/cli version. Rate-limited
+ * to once per CHECK_INTERVAL_MS (24h) via a timestamp file in ~/.aria.
+ * Caller can pass force=true to bypass the rate limit (used by `aria check-update`).
+ */
+export async function checkForUpdate(opts = {}) {
+    const current = findInstalledVersion();
+    if (!current) {
+        return { ok: false, reason: 'could not resolve installed version' };
+    }
+    // Rate-limit check
+    if (!opts.force && existsSync(LAST_CHECK_PATH)) {
+        try {
+            const ts = parseInt(readFileSync(LAST_CHECK_PATH, 'utf-8').trim(), 10);
+            if (!isNaN(ts) && Date.now() - ts < CHECK_INTERVAL_MS) {
+                return { ok: true, current, reason: 'rate-limited (checked within last 24h)' };
+            }
+        }
+        catch { /* malformed timestamp — re-check */ }
+    }
+    // Fetch registry
+    let latest;
+    try {
+        const resp = await fetch(REGISTRY_URL, {
+            headers: { 'Accept': 'application/json' },
+        });
+        if (!resp.ok) {
+            // Don't update timestamp on failure — retry next invocation
+            return { ok: false, current, reason: `registry returned ${resp.status}` };
+        }
+        const data = await resp.json();
+        latest = data['dist-tags']?.latest ?? '';
+        if (!latest) {
+            return { ok: false, current, reason: 'registry response missing dist-tags.latest' };
+        }
+    }
+    catch (err) {
+        return { ok: false, current, reason: `network error: ${err.message}` };
+    }
+    // Update timestamp on successful check
+    try {
+        if (!existsSync(ARIA_DIR))
+            mkdirSync(ARIA_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(LAST_CHECK_PATH, String(Date.now()) + '\n', { mode: 0o600 });
+    }
+    catch { /* timestamp write is best-effort */ }
+    const cmp = compareSemver(latest, current);
+    if (cmp <= 0) {
+        return { ok: true, current, latest, updateAvailable: false };
+    }
+    return {
+        ok: true,
+        current,
+        latest,
+        updateAvailable: true,
+        message: `I have an update: v${latest} (you're on v${current}). Run 'npm update -g @aria_asi/cli' when you have a minute.`,
+    };
+}
+/**
+ * Convenience: check + print the notice if available. Non-blocking, silent
+ * on errors. Called from bin/aria.js on startup.
+ */
+export async function maybePrintUpdateNotice() {
+    try {
+        const result = await checkForUpdate();
+        if (result.ok && result.updateAvailable && result.message) {
+            // Print to stderr so it doesn't pollute stdout-piped CLI output
+            process.stderr.write(`  ${result.message}\n`);
+        }
+    }
+    catch { /* never block startup */ }
+}
+//# sourceMappingURL=self-update.js.map

package/dist/aria-connector/src/self-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update.js","sourceRoot":"","sources":["../../../src/self-update.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria_asi/cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Aria Smart CLI — the world's first harness-powered terminal companion",
   "bin": {
     "aria": "./bin/aria.js"

package/src/self-update.ts

@@ -0,0 +1,169 @@
+// self-update — checks the npm registry for newer @aria_asi/cli versions
+// and surfaces a one-line notice. Doesn't auto-install (clients control
+// their tooling); just informs.
+//
+// Direction: Hamza 2026-04-26 — "does the package auto update when we
+// enhance it on our enhance? so we can continually improve all night using
+// arias background work we should imrpove to do that once we finish".
+// This is the primitive that closes the overnight-improvement loop:
+// Aria publishes 0.2.5 / 0.3.0 / etc.; clients see the notice on their
+// next `aria <cmd>` invocation; they upgrade with one command.
+//
+// Doctrine bindings:
+//   - feedback_no_demos.md — real overnight evolution, real registry check
+//   - feedback_no_timeouts_doctrine.md — fetch with no AbortSignal.timeout;
+//     use bare try/catch, real-error-driven backpressure
+//   - project_phase_10_endless_army_orchestration.md — continuous shipping
+//     is the Phase 10 north star; self-update is its delivery mechanism
+//
+// Behavior:
+//   - Reads installed version from package.json (resolved via import.meta.url
+//     walk to find the package root)
+//   - Reads ~/.aria/last-update-check timestamp; if checked <24h ago, skip
+//   - GET registry.npmjs.org/@aria_asi/cli for latest dist-tag
+//   - semver-compare; if newer, return {updateAvailable: true, latest, current, message}
+//   - Write timestamp on every check (success or skip-due-to-rate-limit)
+//   - Failures are silent (network down, registry blip — never block CLI startup)
+//
+// Privacy: the request to npmjs only sends User-Agent (npm registry public).
+// No client identity, no telemetry beyond what the public registry already logs.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ARIA_DIR = join(homedir(), '.aria');
+const LAST_CHECK_PATH = join(ARIA_DIR, 'last-update-check');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+const REGISTRY_URL = 'https://registry.npmjs.org/@aria_asi%2Fcli';
+
+export interface UpdateCheckResult {
+  ok: boolean;
+  current?: string;
+  latest?: string;
+  updateAvailable?: boolean;
+  message?: string;
+  reason?: string;
+}
+
+/**
+ * Find the package's own version by walking up from this file's runtime
+ * path until we hit the package.json with name @aria_asi/cli.
+ */
+function findInstalledVersion(): string | null {
+  try {
+    const here = fileURLToPath(import.meta.url);
+    let cur = dirname(here);
+    for (let i = 0; i < 8; i++) {
+      const pkgPath = join(cur, 'package.json');
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg.name === '@aria_asi/cli' && typeof pkg.version === 'string') {
+          return pkg.version;
+        }
+      }
+      const parent = dirname(cur);
+      if (parent === cur) break;
+      cur = parent;
+    }
+  } catch {/* fall through */}
+  return null;
+}
+
+/**
+ * Compare semver strings — returns 1 if a>b, -1 if a<b, 0 if equal.
+ * Pre-release suffixes (e.g. 0.2.4-beta) sort lower than the same base.
+ */
+function compareSemver(a: string, b: string): number {
+  const parse = (s: string): { nums: number[]; pre: string } => {
+    const [main, ...preParts] = s.split('-');
+    const nums = main.split('.').map((n) => parseInt(n, 10));
+    while (nums.length < 3) nums.push(0);
+    return { nums, pre: preParts.join('-') };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] > pb.nums[i]) return 1;
+    if (pa.nums[i] < pb.nums[i]) return -1;
+  }
+  // Equal numerics — pre-release sorts before release
+  if (pa.pre && !pb.pre) return -1;
+  if (!pa.pre && pb.pre) return 1;
+  return pa.pre.localeCompare(pb.pre);
+}
+
+/**
+ * Check the registry for the latest @aria_asi/cli version. Rate-limited
+ * to once per CHECK_INTERVAL_MS (24h) via a timestamp file in ~/.aria.
+ * Caller can pass force=true to bypass the rate limit (used by `aria check-update`).
+ */
+export async function checkForUpdate(opts: { force?: boolean } = {}): Promise<UpdateCheckResult> {
+  const current = findInstalledVersion();
+  if (!current) {
+    return { ok: false, reason: 'could not resolve installed version' };
+  }
+
+  // Rate-limit check
+  if (!opts.force && existsSync(LAST_CHECK_PATH)) {
+    try {
+      const ts = parseInt(readFileSync(LAST_CHECK_PATH, 'utf-8').trim(), 10);
+      if (!isNaN(ts) && Date.now() - ts < CHECK_INTERVAL_MS) {
+        return { ok: true, current, reason: 'rate-limited (checked within last 24h)' };
+      }
+    } catch {/* malformed timestamp — re-check */}
+  }
+
+  // Fetch registry
+  let latest: string;
+  try {
+    const resp = await fetch(REGISTRY_URL, {
+      headers: { 'Accept': 'application/json' },
+    });
+    if (!resp.ok) {
+      // Don't update timestamp on failure — retry next invocation
+      return { ok: false, current, reason: `registry returned ${resp.status}` };
+    }
+    const data = await resp.json() as { 'dist-tags'?: Record<string, string> };
+    latest = data['dist-tags']?.latest ?? '';
+    if (!latest) {
+      return { ok: false, current, reason: 'registry response missing dist-tags.latest' };
+    }
+  } catch (err) {
+    return { ok: false, current, reason: `network error: ${(err as Error).message}` };
+  }
+
+  // Update timestamp on successful check
+  try {
+    if (!existsSync(ARIA_DIR)) mkdirSync(ARIA_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(LAST_CHECK_PATH, String(Date.now()) + '\n', { mode: 0o600 });
+  } catch {/* timestamp write is best-effort */}
+
+  const cmp = compareSemver(latest, current);
+  if (cmp <= 0) {
+    return { ok: true, current, latest, updateAvailable: false };
+  }
+
+  return {
+    ok: true,
+    current,
+    latest,
+    updateAvailable: true,
+    message: `I have an update: v${latest} (you're on v${current}). Run 'npm update -g @aria_asi/cli' when you have a minute.`,
+  };
+}
+
+/**
+ * Convenience: check + print the notice if available. Non-blocking, silent
+ * on errors. Called from bin/aria.js on startup.
+ */
+export async function maybePrintUpdateNotice(): Promise<void> {
+  try {
+    const result = await checkForUpdate();
+    if (result.ok && result.updateAvailable && result.message) {
+      // Print to stderr so it doesn't pollute stdout-piped CLI output
+      process.stderr.write(`  ${result.message}\n`);
+    }
+  } catch {/* never block startup */}
+}