jaitus 0.3.0

package/src/commands/login.js

@@ -0,0 +1,201 @@
+// ─── jaitus login ───────────────────────────────────────────────────────────────
+//
+// The loopback-redirect flow from RFC 8252 (OAuth 2.0 for Native Apps) with PKCE
+// (RFC 7636), which is what `gh auth login`, Codex and the cloud CLIs use:
+//
+//   1. Start an HTTP server on a random port, bound to 127.0.0.1 only, and make a PKCE
+//      verifier that never leaves this process.
+//   2. Open the browser at /cli-auth?port=…&state=…&challenge=…&device=… on the website.
+//   3. The user signs in there — this CLI never sees a password.
+//   4. The browser is redirected back to the loopback with a one-time CODE.
+//   5. Exchange the code AND the verifier for this device's session, over HTTPS.
+//
+// No credential ever travels in a URL, so none can end up in browser history, a referrer
+// header or a local proxy's log — and an intercepted code is useless without the
+// verifier. `state` is compared on return, so a page the user happens to have open
+// cannot drive this flow from the side.
+
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { endpoints, saveCredentials, loadCredentials } from '../config.js';
+import { deviceId, deviceName } from '../session.js';
+import { c, out, ok, fail, info, spinner, ask, glyph } from '../ui.js';
+import { openUrl } from '../open.js';
+
+// Five minutes is the real budget: long enough to find the right browser profile and
+// sign in, short enough that a forgotten terminal does not hold a listening socket open
+// all afternoon. Overridable because the test that proves a mismatched `state` never
+// completes a sign-in has to wait out this exact timer, and a suite that takes five
+// minutes to make one assertion is a suite nobody runs.
+// The launcher lives in ../open.js: one copy of the Windows quoting, because two
+// copies means one of them is wrong.
+const openBrowser = openUrl;
+
+const LOGIN_TIMEOUT_MS = Number(process.env.JAITUS_LOGIN_TIMEOUT_MS) || 5 * 60 * 1000;
+
+
+const PAGE = (title, body, accent) => `<!doctype html><meta charset="utf-8">
+<title>${title}</title>
+<style>
+  body{margin:0;height:100vh;display:grid;place-items:center;background:#faf8f5;
+       font:16px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif;color:#1a2332}
+  .card{max-width:420px;padding:40px;text-align:center}
+  h1{font-size:22px;margin:0 0 8px;color:#0f141c}
+  p{margin:0;color:#526077;font-size:14px}
+  .dot{width:44px;height:44px;border-radius:14px;margin:0 auto 20px;
+       display:grid;place-items:center;background:${accent}1a;color:${accent};font-size:22px}
+  @media (prefers-color-scheme:dark){
+    body{background:#0b0f16;color:#e6edf6} h1{color:#fff} p{color:#94a3b8}
+  }
+</style>
+<div class="card"><div class="dot">${accent === '#ff6b4a' ? '✓' : '✕'}</div>
+<h1>${title}</h1><p>${body}</p></div>`;
+
+/** Wait for the browser to come back with a code. Resolves { code } or rejects. */
+function awaitCallback(server, expectedState) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('Timed out waiting for the browser. Run `jaitus login` again.'));
+    }, LOGIN_TIMEOUT_MS);
+
+    server.on('request', (req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404).end();
+        return;
+      }
+
+      const finish = (status, page) => {
+        res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(page);
+        clearTimeout(timer);
+      };
+
+      // Checked before anything else: a mismatched state means this callback did not
+      // come from the page this process opened.
+      //
+      // Deliberately does NOT give up. An ephemeral port gets reused quickly, so a tab
+      // left open from an earlier `jaitus login` can land here and would otherwise kill
+      // a sign-in the user is in the middle of completing correctly. Tell that tab it is
+      // stale and keep waiting for the right one.
+      if (url.searchParams.get('state') !== expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(PAGE(
+          'This tab is out of date',
+          'It came from an earlier sign-in attempt. Go back to your terminal and open the newest link.',
+          '#e84f2e'
+        ));
+        return; // still listening
+      }
+      if (url.searchParams.get('error')) {
+        finish(200, PAGE('Sign-in cancelled', 'You can close this tab and go back to your terminal.', '#e84f2e'));
+        return reject(new Error('Cancelled in the browser.'));
+      }
+      const code = url.searchParams.get('code');
+      if (!code) {
+        finish(400, PAGE('Something went wrong', 'No authorisation code came back. Please try again.', '#e84f2e'));
+        return reject(new Error('No code returned.'));
+      }
+
+      finish(200, PAGE('You‘re signed in', 'You can close this tab and go back to your terminal.', '#ff6b4a'));
+      resolve({ code });
+    });
+  });
+}
+
+export default async function login(argv) {
+  const { baseUrl, siteUrl } = endpoints();
+
+  const existing = loadCredentials();
+  if (existing?.refreshToken && !argv.includes('--force')) {
+    out(`Already signed in as ${c.bold(existing.user?.email || 'your account')}.`);
+    const again = await ask(`${c.dim('Sign in again? [y/N] ')}`);
+    if (again.toLowerCase() !== 'y') return 0;
+  }
+
+  const state = crypto.randomBytes(24).toString('base64url');
+  // PKCE (S256): the challenge goes out through the browser, the verifier stays here and
+  // is only ever sent in the final exchange.
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+  const device = deviceId();
+  const server = http.createServer();
+
+  // Port 0 lets the OS pick a free one; 127.0.0.1 keeps it off the network entirely.
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const port = server.address().port;
+
+  // Appended, not resolved from the root: `new URL('/cli-auth', 'https://x/app')` throws
+  // away the `/app` prefix, so a site hosted under a path would be sent to a page that
+  // does not exist.
+  const url = new URL(`${siteUrl}/cli-auth`);
+  url.searchParams.set('port', String(port));
+  url.searchParams.set('state', state);
+  url.searchParams.set('name', deviceName());
+  url.searchParams.set('challenge', challenge);
+  url.searchParams.set('device', device);
+  url.searchParams.set('platform', process.platform);
+
+  out('');
+  out(`  ${c.brand('Jaitus')} — sign in`);
+  out('');
+  out(`  Opening ${c.cyan(siteUrl + '/cli-auth')} in your browser.`);
+  out(`  ${c.dim('If it does not open, paste this link:')}`);
+  out(`  ${c.dim(url.toString())}`);
+  out('');
+
+  openBrowser(url.toString());
+  const spin = spinner(glyph('Waiting for you to authorise in the browser…', 'Waiting for you to authorise in the browser...'));
+
+  let code;
+  try {
+    ({ code } = await awaitCallback(server, state));
+  } catch (e) {
+    spin.stop();
+    server.close();
+    fail(e.message);
+    return 1;
+  }
+  spin.update(glyph('Finishing sign-in…', 'Finishing sign-in...'));
+
+  try {
+    const res = await fetch(`${baseUrl}/api/auth/cli/exchange`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ code, verifier }),
+    });
+    const body = await res.json().catch(() => ({}));
+    spin.stop();
+    server.close();
+
+    if (!res.ok || !body?.data?.accessToken || !body?.data?.refreshToken) {
+      // Our own sign-in endpoint's wording, or a plain fallback — never a raw body.
+      fail(typeof body?.message === 'string' && body.message ? body.message : 'Sign-in did not complete. Run `jaitus login` again.');
+      return 1;
+    }
+
+    saveCredentials({
+      accessToken: body.data.accessToken,
+      refreshToken: body.data.refreshToken,
+      accessExpiresAt: body.data.accessExpiresAt,
+      deviceId: device,
+      user: body.data.user || null,
+      baseUrl,
+      createdAt: new Date().toISOString(),
+    });
+
+    const who = body.data.user;
+    ok(`Signed in as ${c.bold(who?.email || 'your account')}${who?.isPaid ? '' : c.dim(' (free plan)')}`);
+    info(`Run ${c.bold('jaitus')} in a project to start, or ${c.bold('jaitus --help')} to see everything.`);
+    return 0;
+  } catch (e) {
+    spin.stop();
+    server.close();
+    fail('Could not reach Jaitus. Check your connection and run `jaitus login` again.');
+    return 1;
+  }
+}

package/src/commands/logout.js

@@ -0,0 +1,25 @@
+// ─── jaitus logout ──────────────────────────────────────────────────────────────
+//
+// Ends this device's session ON THE SERVER, then forgets it here. Signing out used to
+// only delete the local file and leave a working key behind in the account; now the
+// tokens stop working the moment this runs. Offline, the local copy still goes and the
+// session lapses on its own — and that is said, not hidden.
+
+import { endpoints } from '../config.js';
+import { signOut } from '../session.js';
+import { ok, info, warn } from '../ui.js';
+
+export default async function logout() {
+  const { hadSession, server } = await signOut();
+  if (!hadSession) {
+    info('You were not signed in.');
+    return 0;
+  }
+  if (server) {
+    ok('Signed out of this device.');
+  } else {
+    ok('Signed out here.');
+    warn(`Could not reach Jaitus to end the session on the server. It will expire on its own, or sign it out at ${endpoints().siteUrl}/gateway.`);
+  }
+  return 0;
+}

package/src/commands/research.js

@@ -0,0 +1,60 @@
+// ─── /research — agentic web research with citations ────────────────────────────
+//
+// A /agent side-task with a research-grade brief: the model plans queries, runs
+// web_search/web_fetch itself, reads what it needs, and returns a cited brief.
+// Read-only by decree (plan-mode permissions), so it can never touch your files.
+//
+// Usage: /research <question>
+//        /research --deep <question>      more rounds, for a question worth the tokens
+//        /research --rounds 5 <question>  the same knob, named
+import { runAgent } from '../agent/loop.js';
+import { createPermissions } from '../agent/permissions.js';
+import { c, ok, warn } from '../ui.js';
+
+export default async function research(args, ctx) {
+  let rounds = 3;
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--rounds') rounds = Math.max(1, Math.min(8, Number(args[++i]) || 3));
+    // `--deep` was a separate /deep-research command, which is two names for one thing
+    // in a list that already had too many names in it.
+    else if (args[i] === '--deep') rounds = 5;
+    else rest.push(args[i]);
+  }
+  const question = rest.join(' ').trim();
+  if (!question) {
+    warn('Usage: /research [--deep] [--rounds 1-8] <question>');
+    return null;
+  }
+
+  const brief = [
+    `Research this question and return a brief with citations.`,
+    ``,
+    `Question: ${question}`,
+    ``,
+    `Method — do this, not a single-shot answer:`,
+    `1. Decompose the question into 2-5 concrete sub-queries.`,
+    `2. web_search each one; open the 2-4 most promising results with web_fetch.`,
+    `3. Cross-check any number, price, date or claim across at least two independent sources before stating it. Say "single source" when you could not.`,
+    `4. Iterate up to ${rounds} research rounds; stop early when two rounds agree.`,
+    ``,
+    `Output format — exactly this:`,
+    `## Answer`,
+    `The finding, stated plainly, in 3-8 sentences.`,
+    `## Key facts`,
+    `Bullet list: fact — [source name](url)`,
+    `## Confidence & gaps`,
+    `What is solid, what is thin, what you could not verify.`,
+  ].join('\n');
+
+  const sideMessages = [{ role: 'user', content: brief }];
+  const sidePermissions = createPermissions({ mode: 'plan' }); // read-only: web tools only
+  const side = await runAgent({
+    client: ctx.client, messages: sideMessages, model: ctx.model, cwd: ctx.flags.cwd,
+    permissions: sidePermissions,
+    extraSystem: `You are the Jaitus research agent. You find things out on the web and report back with sources. You never edit files or run commands — web_search and web_fetch only. Be precise about what a source actually says; never invent a URL.`,
+  });
+
+  ok(`Research complete (${side.tools || 0} tool calls, ${((side.input || 0) + (side.output || 0)).toLocaleString()} tokens).`);
+  return null;
+}

package/src/commands/review.js

@@ -0,0 +1,80 @@
+// ─── Review engine — one diff reader, three lenses ──────────────────────────────
+//
+// /code-review, /security-review and /simplify share everything except the
+// brief: read the change, report through one lens, apply with --fix (gated by
+// the session's normal permissions, never silently).
+//
+// Usage: /code-review [--fix] [path|branch]
+//        /security-review [--fix] [path|branch]
+//        /simplify [--fix] [path]
+import { spawnSync } from 'node:child_process';
+import { runAgent } from '../agent/loop.js';
+import { createPermissions } from '../agent/permissions.js';
+import { c, out, ok, warn, fail, glyph } from '../ui.js';
+
+const BRIEFS = {
+  correctness: {
+    title: 'Code review',
+    system: `You are the Jaitus code reviewer. Hunt correctness bugs first (wrong logic, off-by-ones, broken error paths, race conditions, API misuse), then dead code and cleanup. Every finding cites file:line and quotes the offending code. No praise paragraphs, no invented issues — if the diff is clean, say so in one line.`,
+    task: (target) => `Review this change for correctness bugs and cleanup opportunities. Structure: ## Bugs (each: severity high/med/low, file:line, the bad code, the fix) ## Cleanup (nit-level, optional) ## Verdict (one line: ship it / fix first).`,
+  },
+  security: {
+    title: 'Security review',
+    system: `You are the Jaitus security reviewer. Hunt: injection (command/SQL/template), auth/authz gaps, secret or credential exposure, path traversal, SSRF, unsafe deserialization, weak crypto, missing validation on untrusted input. Every finding cites file:line with the vulnerable code and a concrete fix. If nothing is exploitable, say so in one line — never pad with hypotheticals.`,
+    task: (target) => `Security-review this change. Structure: ## Vulnerabilities (each: severity, file:line, exploit sketch in one sentence, fix) ## Hardening notes (optional, low-risk improvements) ## Verdict (one line).`,
+  },
+  simplify: {
+    title: 'Simplify',
+    system: `You are the Jaitus simplifier. You do NOT hunt bugs — only readability: duplication to fold, nesting to flatten, names to clarify, dead branches to cut. Every suggestion shows before/after. If the code is already tight, say so in one line.`,
+    task: (target) => `Simplify this change for readability only. Structure: ## Suggestions (each: file:line, before → after) ## Verdict (one line).`,
+  },
+};
+
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() };
+}
+
+export async function runReview(mode, args, ctx) {
+  const brief = BRIEFS[mode];
+  if (!brief) { fail(`Unknown review lens: ${mode}.`); return null; }
+  const fix = args.includes('--fix');
+  const target = args.filter((a) => a !== '--fix').join(' ').trim();
+
+  if (!git(['rev-parse', '--is-inside-work-tree'], ctx.flags.cwd).ok) {
+    fail('Not a git repository — nothing to review.');
+    return null;
+  }
+  // A path scopes the review, a range (main..branch) compares branches,
+  // otherwise the whole working tree is the subject.
+  const diffArgs = !target
+    ? ['diff', 'HEAD', '--']
+    : target.includes('..')
+      ? ['diff', target, '--']
+      : ['diff', 'HEAD', '--', target];
+  const diff = git(diffArgs, ctx.flags.cwd);
+  if (!diff.ok) { fail(`Could not read the diff: ${diff.err || 'git refused'}.`); return null; }
+  if (!diff.out) { ok(target ? `No changes under ${target} — nothing to review.` : 'Working tree is clean — nothing to review.'); return null; }
+
+  const stat = git(['diff', 'HEAD', '--stat'], ctx.flags.cwd).out.split('\n').slice(0, 8);
+  out(c.dim(`  ${brief.title}${target ? ` — ${target}` : ''} (${diff.out.split('\n').length.toLocaleString()} diff lines):`));
+  for (const line of stat) out(`  ${c.dim(line)}`);
+
+  const messages = [{
+    role: 'user',
+    content: `${brief.task(target)}\n\nDiff${target ? ` (${target})` : ''}:\n${diff.out.slice(0, 30000)}${diff.out.length > 30000 ? `\n${glyph('…', '...')}(truncated)` : ''}`,
+  }];
+  await runAgent({
+    client: ctx.client, messages, model: ctx.model, cwd: ctx.flags.cwd,
+    // Reviewing reads; --fix writes — so the fix pass inherits the session's
+    // own permission mode instead of smuggling in a permissive one.
+    permissions: fix
+      ? createPermissions({ mode: ctx.permissions?.mode || 'default' })
+      : createPermissions({ mode: 'plan' }),
+    extraSystem: fix
+      ? `${brief.system}\n\nAfter reporting, APPLY the fixes you recommended (minimal diffs, same style as the file). Then summarize what changed.`
+      : brief.system,
+  });
+  if (!fix) warn(`Run with --fix to let the agent apply the findings (permissions still ask first).`);
+  return null;
+}

package/src/commands/security-review.js

@@ -0,0 +1,8 @@
+// ─── /security-review — vulnerabilities in the change, with --fix ────────────────
+//
+// Usage: /security-review [--fix] [path|branch..range]
+import { runReview } from './review.js';
+
+export default async function securityReview(args, ctx) {
+  return runReview('security', args, ctx);
+}

package/src/commands/simplify.js

@@ -0,0 +1,8 @@
+// ─── /simplify — readability-only pass over the change, with --fix ───────────────
+//
+// Usage: /simplify [--fix] [path]
+import { runReview } from './review.js';
+
+export default async function simplify(args, ctx) {
+  return runReview('simplify', args, ctx);
+}

package/src/commands/test.js

@@ -0,0 +1,68 @@
+// ─── /test — run the project's tests, then FIX what fails (with your ok) ────────
+//
+// Detects the runner (package.json scripts, pytest, go test, cargo), runs it,
+// streams the tail, and on failures offers a focused fix loop: the agent sees
+// the failing output and the files it points at, proposes fixes, applies them
+// only after permission, and re-runs until green or you stop it.
+//
+// Usage: /test [anything forwarded to the runner]
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ok, warn, fail, out, c } from '../ui.js';
+
+/** Pick a command from package.json scripts, or fall back to ecosystem defaults. */
+function detectRunner(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const s = pkg.scripts || {};
+    if (s.test) return { cmd: 'npm', args: ['test', ...(process.platform === 'win32' ? [] : [])], label: `npm test` };
+  } catch { /* not a node project */ }
+  if (fs.existsSync(path.join(cwd, 'pytest.ini')) || fs.existsSync(path.join(cwd, 'pyproject.toml'))) {
+    return { cmd: 'python', args: ['-m', 'pytest', '-x', '-q'], label: 'pytest' };
+  }
+  if (fs.existsSync(path.join(cwd, 'go.mod'))) return { cmd: 'go', args: ['test', './...'], label: 'go test' };
+  if (fs.existsSync(path.join(cwd, 'Cargo.toml'))) return { cmd: 'cargo', args: ['test'], label: 'cargo test' };
+  return null;
+}
+
+export default async function test(args, ctx) {
+  const forward = args.filter((a) => a !== '--fix');
+  const wantsFix = args.includes('--fix');
+  const runner = detectRunner(ctx.flags.cwd);
+  if (!runner) { warn('No test runner found (package.json scripts, pytest, go, cargo).'); return null; }
+
+  out(c.dim(`  Running: ${runner.label}${forward.length ? ` ${forward.join(' ')}` : ''}`));
+  const r = spawnSync(runner.cmd, [...runner.args, ...forward], {
+    cwd: ctx.flags.cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+  });
+  const output = `${r.stdout || ''}\n${r.stderr || ''}`.trim();
+
+  // Show the tail — enough to see failures, not the whole log.
+  const lines = output.split('\n');
+  for (const line of lines.slice(-40)) out(`  ${line}`);
+
+  if (r.status === 0) { ok('All tests passed.'); return null; }
+  fail(`Tests failed (exit ${r.status}).`);
+
+  if (!wantsFix) {
+    warn('Run /test --fix to let the agent fix the failures.');
+    return null;
+  }
+
+  // The fix loop: hand the failure output to the agent, let it work through
+  // the code (permissions still gate every write), then re-run the suite.
+  const { runAgent } = await import('../agent/loop.js');
+  const { createPermissions } = await import('../agent/permissions.js');
+  const fixMessages = [{
+    role: 'user',
+    content: `These tests are failing in ${ctx.flags.cwd}. Diagnose and FIX them: read the failing code, make the minimal correct changes, then run \`${runner.label}\` again. Do not weaken assertions to make tests pass unless the test itself is provably wrong.\n\nFailure output (tail):\n${output.slice(-12000)}`,
+  }];
+  await runAgent({
+    client: ctx.client, messages: fixMessages, model: ctx.model, cwd: ctx.flags.cwd,
+    permissions: createPermissions({ mode: ctx.permissions?.mode || 'default' }),
+    extraSystem: `You are fixing failing tests. Minimal, correct changes. Never delete a failing test to go green; fix the code (or fix the test only if the test is wrong).`,
+  });
+  return null;
+}

package/src/commands/update.js

@@ -0,0 +1,97 @@
+// ─── jaitus update ──────────────────────────────────────────────────────────────
+//
+// Checks the registry and tells you. It deliberately does NOT run the install itself:
+// the CLI may have been installed globally, with npx, through a version manager, or
+// vendored into a repo, and a tool that guesses wrong there either fails confusingly or
+// modifies something it was never asked to modify.
+
+import { c, out, ok, info, warn, present } from '../ui.js';
+import { version } from '../config.js';
+
+const REGISTRY = process.env.JAITUS_REGISTRY || 'https://registry.npmjs.org';
+const TIMEOUT_MS = 5000;
+
+/**
+ * Ask the registry what is published.
+ *
+ * "Not published" and "could not reach the registry" are different answers and must not
+ * collapse into one null: reporting an offline machine as "no version published" sends
+ * someone looking for a release that exists, and reporting an unpublished package as a
+ * network fault sends them looking for a firewall that does not exist. A 404 is a real
+ * answer from a registry that is working perfectly.
+ */
+export async function checkRegistry() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${REGISTRY}/jaitus/latest`, {
+      signal: ctrl.signal,
+      headers: { accept: 'application/vnd.npm.install-v1+json, application/json' },
+    });
+    if (res.status === 404) return { version: null, status: 'unpublished' };
+    if (!res.ok) return { version: null, status: 'unreachable' };
+    const body = await res.json();
+    return typeof body?.version === 'string'
+      ? { version: body.version, status: 'ok' }
+      : { version: null, status: 'unreachable' };
+  } catch {
+    return { version: null, status: 'unreachable' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The published version, or null. */
+export async function latestVersion() {
+  return (await checkRegistry()).version;
+}
+
+/**
+ * Plain semver comparison — is `a` newer than `b`?
+ * Prerelease tags are treated as older than the release they lead to, which is what
+ * semver says and what stops a `-beta.1` being offered as an upgrade over the release.
+ */
+export function isNewer(a, b) {
+  const parse = (v) => {
+    const [core, pre] = String(v).split('-');
+    return { nums: core.split('.').map((n) => Number(n) || 0), pre: pre || null };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if ((x.nums[i] || 0) !== (y.nums[i] || 0)) return (x.nums[i] || 0) > (y.nums[i] || 0);
+  }
+  if (x.pre && !y.pre) return false;
+  if (!x.pre && y.pre) return true;
+  if (x.pre && y.pre) return x.pre > y.pre;
+  return false;
+}
+
+export default async function update(argv = [], { json = false } = {}) {
+  const current = version();
+  const { version: latest, status } = await checkRegistry();
+
+  if (!latest) {
+    present(json, { current, latest: null, upToDate: null, status }, () => {
+      if (status === 'unpublished') warn('jaitus is not published on this registry, so there is nothing to update to.');
+      else warn('Could not reach the npm registry to check for updates.');
+      info(`You are running ${c.bold(`v${current}`)}.`);
+    });
+    return 1;
+  }
+
+  const available = isNewer(latest, current);
+  present(json, { current, latest, upToDate: !available, status }, () => {
+    if (!available) {
+      ok(`You are on the latest version (${c.bold(`v${current}`)}).`);
+      return;
+    }
+    out('');
+    out(`  ${c.bold(`v${latest}`)} is available ${c.dim(`— you have v${current}`)}`);
+    out('');
+    out(`  ${c.dim('global install')}   ${c.bold('npm install -g jaitus')}`);
+    out(`  ${c.dim('no install')}       ${c.bold('npx jaitus@latest')}`);
+    out('');
+  });
+  return 0;
+}

package/src/config.js

@@ -0,0 +1,95 @@
+// ─── Where the CLI keeps things ─────────────────────────────────────────────────
+//
+// One directory, `~/.jaitus`, holding credentials and settings. Deliberately NOT the
+// shell profile and NOT the machine environment: a base URL or an auth token written into
+// a user's profile silently reroutes every tool on the machine that reads those
+// variables, including ones they never meant to point here. A tool that does that is a
+// tool nobody can safely run twice.
+//
+// Credentials are written 0600. That is advisory on Windows, where the real protection
+// is the per-user profile directory, but it costs nothing and is correct everywhere else.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const HOME = path.join(os.homedir(), '.jaitus');
+const CREDENTIALS = path.join(HOME, 'credentials.json');
+const SETTINGS = path.join(HOME, 'settings.json');
+export const HISTORY = path.join(HOME, 'history');
+export const SESSIONS = path.join(HOME, 'sessions');
+
+/**
+ * The version, read from package.json rather than kept as a second copy in the source.
+ * Two places to edit is one place to forget, and a CLI reporting a version it is not is
+ * the kind of thing that wastes an afternoon of someone else's bug report.
+ */
+export function version() {
+  try {
+    const pkg = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkg, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export const DEFAULT_BASE_URL = 'https://api.jaitus.com';
+export const DEFAULT_SITE_URL = 'https://www.jaitus.com';
+
+function ensureHome() {
+  fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, data, mode = 0o600) {
+  ensureHome();
+  // Written to a temp file and renamed, so an interrupted write cannot leave a
+  // half-parsed credentials file behind that makes every later command fail.
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode });
+  fs.renameSync(tmp, file);
+  try { fs.chmodSync(file, mode); } catch { /* best effort on Windows */ }
+}
+
+export function loadCredentials() {
+  return readJson(CREDENTIALS, null);
+}
+
+export function saveCredentials(creds) {
+  writeJson(CREDENTIALS, creds, 0o600);
+}
+
+export function clearCredentials() {
+  try { fs.rmSync(CREDENTIALS); return true; } catch { return false; }
+}
+
+export function loadSettings() {
+  return readJson(SETTINGS, {});
+}
+
+export function saveSettings(settings) {
+  writeJson(SETTINGS, settings, 0o644);
+}
+
+/**
+ * Effective endpoints. Environment wins so a developer can point the CLI at a local
+ * backend for one command without editing anything — the deliberate exception to the
+ * "never read env for config" rule, because here it IS per-invocation by design.
+ */
+export function endpoints() {
+  const s = loadSettings();
+  return {
+    baseUrl: (process.env.JAITUS_BASE_URL || s.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+    siteUrl: (process.env.JAITUS_SITE_URL || s.siteUrl || DEFAULT_SITE_URL).replace(/\/+$/, ''),
+  };
+}
+
+// Tokens are read and renewed by session.js, the only code that touches them.