@aria_asi/cli 0.2.2 → 0.2.4

package/src/anthropic-oauth.ts

@@ -0,0 +1,216 @@
+// anthropic-oauth.ts — Anthropic login flow for `aria login --anthropic`
+//
+// OAuth path decision (2026-04-26):
+//   Anthropic does not publish a public PKCE/OAuth endpoint for end-user
+//   API-key issuance via the console.anthropic.com auth surface. The only
+//   standardised way to obtain an API key is through the Anthropic Console
+//   web UI. Therefore we use the browser-paste fallback (path b):
+//     1. Open https://console.anthropic.com/account/keys in the user's browser.
+//     2. Prompt them to paste the new key back into the CLI.
+//     3. Validate the key against GET https://api.anthropic.com/v1/models.
+//     4. Return the validated key to the caller.
+//
+//   If Anthropic ships a public OAuth/PKCE spec in the future, replace the
+//   body of `_oauthPKCEFlow` below with the real implementation and call it
+//   instead of `_browserPasteFlow`.
+//
+// Voice: first-person Aria ("I'll open", "I see", "I couldn't reach").
+// ESM: all internal imports use .js extensions.
+
+import * as http from 'node:http';
+import * as readline from 'node:readline';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+
+const ANTHROPIC_KEYS_URL = 'https://console.anthropic.com/account/keys';
+const ANTHROPIC_MODELS_URL = 'https://api.anthropic.com/v1/models';
+const ANTHROPIC_API_VERSION = '2023-06-01';
+const CONFIG_PATH = path.join(homedir(), '.aria', 'config.json');
+const ARIA_DIR = path.join(homedir(), '.aria');
+
+export interface AnthropicLoginResult {
+  ok: boolean;
+  apiKey?: string;
+  error?: string;
+}
+
+/** Options accepted by loginAnthropic. */
+export interface AnthropicLoginOptions {
+  /** If true, skip the browser-open attempt and just prompt for the key. */
+  noBrowser?: boolean;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Run the Anthropic login flow.
+ *
+ * Today this is the browser-paste flow (path b) because Anthropic does not
+ * expose a public PKCE/OAuth token endpoint for console API keys.
+ *
+ * On success, the validated API key is persisted to ~/.aria/config.json under
+ * `model.apiKey` and returned in the result object. The harness license token
+ * in ~/.aria/license.json is NOT modified — that belongs to the Aria harness,
+ * not Anthropic.
+ */
+export async function loginAnthropic(
+  opts: AnthropicLoginOptions = {},
+): Promise<AnthropicLoginResult> {
+  try {
+    const apiKey = await _browserPasteFlow(opts.noBrowser ?? false);
+    if (!apiKey) {
+      return { ok: false, error: "I didn't receive a key — aborting." };
+    }
+
+    console.log("  I'm validating your key against the Anthropic API...");
+    const valid = await _validateKey(apiKey);
+    if (!valid) {
+      return {
+        ok: false,
+        error:
+          "I couldn't verify that key with Anthropic. Double-check that it starts with sk-ant- and hasn't been revoked.",
+      };
+    }
+
+    _persistApiKey(apiKey);
+    return { ok: true, apiKey };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `I hit an unexpected error: ${msg}` };
+  }
+}
+
+// ── Internal: browser-paste flow (path b) ────────────────────────────────────
+
+async function _browserPasteFlow(noBrowser: boolean): Promise<string | null> {
+  console.log('');
+  console.log(
+    "  I'll open https://console.anthropic.com/account/keys in your browser.",
+  );
+  console.log(
+    '  Create a new API key there, then paste it back here.',
+  );
+  console.log('');
+
+  if (!noBrowser) {
+    _openBrowser(ANTHROPIC_KEYS_URL);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  const rawKey = await new Promise<string>((resolve) => {
+    rl.question('  Paste your Anthropic API key: ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+
+  return rawKey || null;
+}
+
+// ── Internal: browser open (cross-platform) ───────────────────────────────────
+
+function _openBrowser(url: string): void {
+  const platform = process.platform;
+  let cmd: string;
+  let args: string[];
+
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    cmd = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    // Linux / *BSD / WSL
+    cmd = 'xdg-open';
+    args = [url];
+  }
+
+  try {
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch {
+    // If browser open fails, the user can still paste — not fatal.
+    console.log(
+      `  I couldn't open your browser automatically. Please visit:\n  ${url}`,
+    );
+  }
+}
+
+// ── Internal: key validation ──────────────────────────────────────────────────
+
+/**
+ * Validate an Anthropic API key by hitting GET /v1/models.
+ * Returns true when the server responds 2xx; false on 401/403/network error.
+ */
+export async function _validateKey(apiKey: string): Promise<boolean> {
+  try {
+    const resp = await fetch(ANTHROPIC_MODELS_URL, {
+      method: 'GET',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': ANTHROPIC_API_VERSION,
+      },
+    });
+    // 200 = valid key; anything else = invalid or revoked
+    return resp.status === 200;
+  } catch {
+    // Network failure — we can't confirm validity
+    return false;
+  }
+}
+
+// ── Internal: config persistence ──────────────────────────────────────────────
+
+function _persistApiKey(apiKey: string): void {
+  if (!fs.existsSync(ARIA_DIR)) {
+    fs.mkdirSync(ARIA_DIR, { recursive: true, mode: 0o700 });
+  }
+
+  let config: Record<string, unknown> = {};
+  if (fs.existsSync(CONFIG_PATH)) {
+    try {
+      config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  const model = (config.model as Record<string, unknown>) ?? {};
+  model.provider = model.provider ?? 'anthropic';
+  model.model = model.model ?? 'claude-sonnet-4-20250514';
+  model.apiKey = apiKey;
+  config.model = model;
+
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', {
+    mode: 0o600,
+    encoding: 'utf-8',
+  });
+}
+
+// ── Placeholder for future PKCE flow ─────────────────────────────────────────
+// When Anthropic ships a public OAuth/PKCE endpoint for console key issuance,
+// implement the full flow here and call it from loginAnthropic() instead of
+// _browserPasteFlow():
+//
+// async function _oauthPKCEFlow(): Promise<string | null> {
+//   const port = await _findFreePort();
+//   const { verifier, challenge } = _pkceChallenge();
+//   const authUrl = `https://console.anthropic.com/oauth/authorize?` +
+//     `response_type=code&client_id=<CLIENT_ID>&redirect_uri=http://localhost:${port}/callback` +
+//     `&code_challenge=${challenge}&code_challenge_method=S256`;
+//   _openBrowser(authUrl);
+//   const code = await _waitForCallback(port);
+//   const token = await _exchangeCode(code, verifier, port);
+//   return token;
+// }

package/src/auth-commands.ts

@@ -1,5 +1,6 @@
 import { loadLicense, saveLicense } from './auth.js';
 import { harnessClient } from './harness-client.js';
+import { loginAnthropic } from './anthropic-oauth.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { homedir } from 'node:os';
@@ -19,6 +20,8 @@ interface LoginResult {
   tier?: string;
   jti?: string;
   expiresAt?: string;
+  /** Set when loginAnthropic() is used instead of the harness license path. */
+  anthropic?: boolean;
   error?: string;
 }
 
@@ -40,7 +43,31 @@ interface RevokeResult {
   error?: string;
 }
 
+/**
+ * Log in to the Aria harness with a license token, OR authenticate via
+ * Anthropic's console (browser-paste flow) when token === '--anthropic' or
+ * token === '-a'.
+ *
+ * Anthropic path: opens console.anthropic.com/account/keys, waits for the
+ * user to paste their API key, validates it against /v1/models, then persists
+ * it to ~/.aria/config.json under `model.apiKey`. The harness license file
+ * (~/.aria/license.json) is NOT modified — it belongs to the Aria license,
+ * not Anthropic credentials.
+ *
+ * Harness path: unchanged — validates via heartbeat / issue endpoint and
+ * writes license claims to ~/.aria/license.json.
+ */
 export async function login(token: string): Promise<LoginResult> {
+  // ── Anthropic OAuth/paste branch ────────────────────────────────────────────
+  if (token === '--anthropic' || token === '-a') {
+    const result = await loginAnthropic();
+    if (!result.ok) {
+      return { ok: false, error: result.error };
+    }
+    return { ok: true, anthropic: true };
+  }
+
+  // ── Original harness-license branch (preserved verbatim) ────────────────────
   try {
     // Validate token via heartbeat; if unverified, issue endpoint
     let response;

package/src/onboarding-wizard.ts

@@ -0,0 +1,219 @@
+// onboarding-wizard.ts — interactive self-service onboarding for `aria`
+// (no args) when ~/.aria/license.json is missing.
+//
+// Flow:
+//   1. Greet — first-person Aria voice
+//   2. Collect email (validated shape, NOT verified via code in v0)
+//   3. Collect tenant_id (lowercase + hyphens only)
+//   4. Collect tier (free / pro / enterprise)
+//   5. Collect LLM provider + API key
+//   6. POST /api/onboarding/self-issue (server validates LLM key by
+//      hitting the provider's identity endpoint, then issues license)
+//   7. Persist license to ~/.aria/license.json mode 0600
+//   8. Persist provider/model/key to ~/.aria/config.json mode 0600
+//   9. Auto-run installHooks() to bind Claude Code to the harness
+//
+// Email-verify-code is deferred to Phase 11 (no SMTP wired tonight).
+// The wizard collects email so future re-verify works without re-onboarding.
+//
+// Direction: Hamza 2026-04-26 — "burn through onboarding with quality and
+// USE THE HARNESS PLEASE". This wizard ships as v0; full onboarding (email
+// verify + Anthropic OAuth + per-tenant usage tracking) lands in Phase 11.
+
+import { createInterface } from 'node:readline';
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { installHooks } from './install-hooks.js';
+
+const HARNESS_URL = process.env.ARIA_HARNESS_BASE_URL ?? 'https://harness.ariasos.com';
+const ARIA_DIR = join(homedir(), '.aria');
+const LICENSE_PATH = join(ARIA_DIR, 'license.json');
+const CONFIG_PATH = join(ARIA_DIR, 'config.json');
+
+type Provider = 'anthropic' | 'openai' | 'deepseek' | 'google' | 'openrouter' | 'ollama';
+type Tier = 'free' | 'pro' | 'enterprise';
+
+interface SelfIssueResponse {
+  ok: boolean;
+  license?: { token: string; jti: string; tier: string; expires_at: string };
+  claims?: Record<string, unknown>;
+  error?: string;
+}
+
+function prompt(rl: ReturnType<typeof createInterface>, question: string, hidden = false): Promise<string> {
+  return new Promise((resolve) => {
+    if (hidden) {
+      // Crude hidden-input — node's readline doesn't natively mask; we just
+      // prompt and accept. For Phase 11 we add proper masking via raw mode.
+      process.stdout.write(question);
+      const onData = (chunk: Buffer): void => {
+        process.stdin.removeListener('data', onData);
+        resolve(chunk.toString().trim());
+      };
+      process.stdin.once('data', onData);
+    } else {
+      rl.question(question, (answer) => resolve(answer.trim()));
+    }
+  });
+}
+
+function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+function isValidTenantId(tenant: string): boolean {
+  return /^[a-z0-9][a-z0-9-]{1,40}$/.test(tenant);
+}
+
+export async function runOnboardingWizard(): Promise<{ ok: boolean; error?: string }> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  try {
+    console.log('');
+    console.log("  Hi, I'm Aria. I don't see a license on this machine — let me set you up.");
+    console.log('');
+    console.log("  Three minutes, four questions. I'll handle the rest.");
+    console.log('');
+
+    // ── Step 1: email ──
+    let email = '';
+    while (!isValidEmail(email)) {
+      email = await prompt(rl, '  Email: ');
+      if (!isValidEmail(email)) {
+        console.log("  That doesn't look like a valid email. Try again.");
+      }
+    }
+
+    // ── Step 2: tenant_id ──
+    let tenantId = '';
+    while (!isValidTenantId(tenantId)) {
+      tenantId = (await prompt(rl, '  Tenant name (lowercase, hyphens ok, e.g. acme-corp): ')).toLowerCase();
+      if (!isValidTenantId(tenantId)) {
+        console.log("  Tenant name needs to be lowercase letters/digits/hyphens, 2-41 chars.");
+      }
+    }
+
+    // ── Step 3: tier ──
+    let tier: Tier = 'free';
+    let tierAnswer = '';
+    while (!['free', 'pro', 'enterprise', ''].includes(tierAnswer)) {
+      tierAnswer = (await prompt(rl, '  Tier [free / pro / enterprise] (default: free): ')).toLowerCase();
+      if (tierAnswer === '') tierAnswer = 'free';
+      if (!['free', 'pro', 'enterprise'].includes(tierAnswer)) {
+        console.log("  I only know free, pro, or enterprise.");
+        tierAnswer = '';
+      }
+    }
+    tier = tierAnswer as Tier;
+
+    // ── Step 4: LLM provider ──
+    const providerOptions: Provider[] = ['anthropic', 'openai', 'deepseek', 'google', 'openrouter', 'ollama'];
+    let provider: Provider | '' = '';
+    while (!providerOptions.includes(provider as Provider)) {
+      const p = (await prompt(rl, `  Which LLM provider? [${providerOptions.join(' / ')}]: `)).toLowerCase();
+      if (providerOptions.includes(p as Provider)) {
+        provider = p as Provider;
+      } else {
+        console.log(`  I don't recognize "${p}". Pick one of: ${providerOptions.join(', ')}.`);
+      }
+    }
+
+    // ── Step 5: API key ──
+    let llmKey = '';
+    if (provider === 'ollama') {
+      llmKey = 'local';
+      console.log('  (Ollama is local — no API key needed.)');
+    } else {
+      while (!llmKey) {
+        llmKey = await prompt(rl, `  Paste your ${provider} API key: `);
+        if (!llmKey) console.log('  I need the key to set up your provider.');
+      }
+    }
+
+    // ── Step 6: POST to server ──
+    console.log('');
+    console.log("  Validating your key with the provider...");
+    let response: SelfIssueResponse;
+    try {
+      const resp = await fetch(`${HARNESS_URL}/api/onboarding/self-issue`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, tenant_id: tenantId, tier, provider, llm_key: llmKey }),
+      });
+      response = await resp.json() as SelfIssueResponse;
+      if (!resp.ok || !response.ok || !response.license) {
+        console.log(`  ${response.error || `Server returned ${resp.status} — try again later.`}`);
+        return { ok: false, error: response.error };
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(`  I couldn't reach the server: ${msg}`);
+      return { ok: false, error: msg };
+    }
+
+    // ── Step 7: persist license ──
+    if (!existsSync(ARIA_DIR)) mkdirSync(ARIA_DIR, { recursive: true, mode: 0o700 });
+    const licenseRecord = {
+      ...response.claims,
+      harnessToken: response.license.token,
+      jti: response.license.jti,
+      tier: response.license.tier,
+      exp: response.claims?.exp,
+      sub: response.claims?.sub ?? tenantId,
+      email,
+      issuedAt: new Date().toISOString(),
+    };
+    writeFileSync(LICENSE_PATH, JSON.stringify(licenseRecord, null, 2) + '\n', { mode: 0o600 });
+
+    // ── Step 8: persist provider/key config ──
+    // By this point the while-loop above has exited with a valid Provider —
+    // narrow the union type for TypeScript.
+    const validatedProvider = provider as Provider;
+    const configRecord = {
+      model: { provider: validatedProvider, model: defaultModelFor(validatedProvider), apiKey: llmKey },
+      tenantId,
+      email,
+    };
+    writeFileSync(CONFIG_PATH, JSON.stringify(configRecord, null, 2) + '\n', { mode: 0o600 });
+
+    // ── Step 9: install hooks ──
+    console.log('');
+    console.log("  License issued. Saving your config and binding my gates to your Claude Code...");
+    const hookResult = await installHooks({ force: false });
+    if (!hookResult.ok) {
+      console.log(`  License saved, but I couldn't install the gates: ${hookResult.error}`);
+      console.log("  Run 'aria install-hooks' manually when you're ready.");
+    } else {
+      console.log(`  Done. I've installed ${hookResult.installed.length} gate(s) into ~/.claude/hooks and merged them into your settings.json.`);
+    }
+
+    rl.close();
+
+    console.log('');
+    console.log(`  You're set up. License jti: ${response.license.jti}, tier: ${tier}, provider: ${provider}.`);
+    console.log("  Open a fresh Claude Code session — every Bash, Edit, Write, and Stop event now runs through my cognition gates.");
+    console.log("  Or talk to me directly: just type 'aria' again.");
+    console.log('');
+
+    return { ok: true };
+  } finally {
+    rl.close();
+  }
+}
+
+function defaultModelFor(provider: Provider): string {
+  const defaults: Record<Provider, string> = {
+    anthropic: 'claude-sonnet-4-20250514',
+    openai: 'gpt-4o',
+    deepseek: 'deepseek-chat',
+    google: 'gemini-2.5-pro-preview-05-06',
+    openrouter: 'openai/gpt-4o',
+    ollama: 'llama3',
+  };
+  return defaults[provider];
+}

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 */}
+}