scava-ai 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# Scava
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hosting, sign-in and a database for the apps your AI builds. One command puts the app online, on its own address.
+People open a link and sign in with Google or a code by email: no password, nothing to install. Data stays in the EU.
+
+## Start
+
+In the folder of your app, or tell your AI to run it:
+
+```
+npx -y scava-ai deploy
+```
+
+The first time a browser opens: sign in to Scava and choose Allow. After that it runs without a browser. Any AI with a
+terminal can use it: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity and others. You need Node.js 22
+or newer.
+
+Claude and ChatGPT in the browser have no terminal: add a connector with the address https://scava.ai/mcp.
+
+## Commands
+
+```
+npx -y scava-ai deploy [folder]    put the app online; afterwards a test run in a browser here
+npx -y scava-ai share WHO...       let people open it: someone@company.com, "@company.com", group:leads
+npx -y scava-ai apps               your apps
+npx -y scava-ai requests           change requests you accepted, ready to build
+npx -y scava-ai test               test run of the live app, plus problems from visits
+npx -y scava-ai server             the server part of the app
+npx -y scava-ai pull APP [folder]  the files of an app into a folder
+npx -y scava-ai docs               what an app can use on Scava: data, rules, files, server code
+npx -y scava-ai whoami             which account this computer is signed in as
+npx -y scava-ai login              sign in now
+npx -y scava-ai logout             end the access on this computer
+```
+
+The access stays on your computer, in ~/.scava/credentials.json, and whoever works under your user there acts as you.
+Keys for the server code of an app are set in the browser, never in a terminal.
+
+With a one-time link from the Scava tools in your AI (no sign-in here):
+
+```
+npx -y scava-ai upload <folder> <link>
+npx -y scava-ai test <link>
+npx -y scava-ai pull <link> [folder]
+```
+
+More at https://scava.ai/docs
+
+Version 0.1.0.

package/cli/account.js

@@ -0,0 +1,507 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { CMD, LOOPBACK, ScavaError, openBrowser } from './lib.js';
+
+// Signing in on this computer, the way wrangler does it. The first command that needs an account opens the browser; the
+// person signs in to Scava and chooses Allow; the access then stays in a file in the home folder and renews itself. It is
+// the same sign-in every AI uses at /mcp: OAuth with PKCE and a return address on this computer, so a link someone sends
+// to a Scava user hands nothing to the sender.
+//
+// An AI runs this command in a terminal that may stop it after a few seconds, while the person is still signing in. So
+// the waiting does not happen in the command: a small program of its own listens on this computer, on its own, until the
+// person has decided or 15 minutes are over. The command only watches for the result and can simply be run again.
+
+const CLI = fileURLToPath(new URL('./scava.js', import.meta.url));
+const VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return '0';
+  }
+})();
+const USER_AGENT = `scava-cli/${VERSION}`;
+const MCP_VERSION = '2025-11-25';
+// Any port on this computer counts as the same return address (RFC 8252).
+const RETURN_ADDRESS = 'http://127.0.0.1/callback';
+// As long as Scava keeps the request of the page.
+const SIGN_IN_MS = 15 * 60_000;
+// Below the two minutes many AI terminals give a command, so an AI hears from this command by itself.
+const AI_WAIT_MS = 100_000;
+const RENEW_EARLY_MS = 60_000;
+const LOCK_STALE_MS = 30_000;
+const NOTE = `Your access to Scava on this computer. Do not show, copy or send this file. End it with: ${CMD} logout`;
+
+// SCAVA_HOME: for tests, which must not touch the access of the computer they run on.
+const folder = () => process.env.SCAVA_HOME || path.join(os.homedir(), '.scava');
+export const credentialsPath = () => path.join(folder(), 'credentials.json');
+const originOf = (server) => new URL(server).origin;
+const signInPath = (server) => path.join(folder(), `sign-in-${crypto.createHash('sha256').update(originOf(server)).digest('hex').slice(0, 12)}.json`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const busyFile = (e) => e.code === 'EBUSY' || e.code === 'EPERM' || e.code === 'EACCES';
+
+// --- The files --------------------------------------------------------------------------------------------------------
+
+function readPrivate(file) {
+  for (let i = 0; ; i++) {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (e) {
+      if (e.code === 'ENOENT' || e.code === 'ENOTDIR' || e instanceof SyntaxError) return null;
+      // Windows, for a moment, while another command replaces the file.
+      if (i < 20 && busyFile(e)) pause(50);
+      else throw e;
+    }
+  }
+}
+
+// Many AIs run commands in a sandbox that keeps them out of the home folder. Then this is what they have to know.
+function ensureFolder() {
+  try {
+    fs.mkdirSync(folder(), { recursive: true, mode: 0o700 });
+  } catch (e) {
+    throw new ScavaError(`Cannot write to ${folder()} (${e.code}), where the access to Scava is kept. If an AI runs this in a sandbox, allow this command to use the home folder and the network, or run it yourself.`);
+  }
+}
+
+// Only for this user, and replaced in one step: nobody reads half a file.
+function writePrivate(file, data) {
+  ensureFolder();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  for (let i = 0; ; i++) {
+    try {
+      fs.renameSync(tmp, file);
+      return;
+    } catch (e) {
+      if (i < 20 && busyFile(e)) pause(50);
+      else {
+        fs.rmSync(tmp, { force: true });
+        throw e;
+      }
+    }
+  }
+}
+
+// One access per server: what belongs to one Scava is never sent to another.
+const entryOf = (server) => readPrivate(credentialsPath())?.servers?.[originOf(server)] ?? null;
+
+function setEntry(server, entry) {
+  const servers = { ...(readPrivate(credentialsPath())?.servers ?? {}) };
+  if (entry) servers[originOf(server)] = entry;
+  else delete servers[originOf(server)];
+  if (Object.keys(servers).length) writePrivate(credentialsPath(), { note: NOTE, servers });
+  else fs.rmSync(credentialsPath(), { force: true });
+}
+
+// Refresh tokens are used once. Two commands at the same moment must not both spend the same one.
+async function withLock(fn) {
+  const file = path.join(folder(), 'lock');
+  ensureFolder();
+  const end = Date.now() + LOCK_STALE_MS + 5000;
+  for (;;) {
+    try {
+      fs.closeSync(fs.openSync(file, 'wx', 0o600));
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST' && !busyFile(e)) throw e;
+      try {
+        if (Date.now() - fs.statSync(file).mtimeMs > LOCK_STALE_MS) fs.rmSync(file, { force: true });
+      } catch { /* gone in the meantime */ }
+      if (Date.now() > end) throw new ScavaError(`Another ${CMD} command is busy. Please try again.`);
+      await sleep(50);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(file, { force: true });
+  }
+}
+
+// --- Talking to Scava -------------------------------------------------------------------------------------------------
+
+// Never along a redirect: the access goes to this server and nowhere else.
+async function send(url, init) {
+  try {
+    return await fetch(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(60_000), headers: { 'user-agent': USER_AGENT, ...init.headers } });
+  } catch (e) {
+    const moved = /redirect/i.test(String(e?.cause?.message ?? e?.message));
+    throw new ScavaError(`Cannot reach Scava at ${new URL(url).origin}.${moved ? ' It answered with a redirect, and the access never follows one.' : ' If an AI runs this in a sandbox, allow this command to use the network.'}`);
+  }
+}
+
+const form = (fields) => ({ method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' }, body: new URLSearchParams(fields).toString() });
+const notOpen = (server) => new ScavaError(`Scava at ${originOf(server)} does not take this command yet.`);
+
+// The access only travels encrypted, except to a Scava on this computer.
+function checkServer(server) {
+  let u;
+  try {
+    u = new URL(server);
+  } catch {
+    throw new ScavaError(`${server} is not an address.`);
+  }
+  if (u.protocol === 'https:' || (u.protocol === 'http:' && LOOPBACK.has(u.hostname))) return;
+  throw new ScavaError(`The access to Scava only travels encrypted: ${server} has to start with https, unless it runs on this computer.`);
+}
+
+const fresh = (e) => e.expires_at - RENEW_EARLY_MS > Date.now();
+const toEntry = (d, known) => ({
+  client_id: known.client_id,
+  account: d.account ?? known.account ?? null,
+  access_token: d.access_token,
+  refresh_token: d.refresh_token ?? known.refresh_token,
+  expires_at: Date.now() + (Number(d.expires_in) || 3600) * 1000,
+});
+
+// A new access with the refresh token, or null when that ended: disconnected on the Connect page, 90 days without use,
+// or the token was used elsewhere. Then the next command signs in again. Scava being away ends nothing.
+async function renew(server, failedToken) {
+  return withLock(async () => {
+    const e = entryOf(server);
+    if (!e) return null;
+    if (e.access_token !== failedToken && fresh(e)) return e; // another command just did it
+    const r = await send(`${server}/oauth/token`, form({ grant_type: 'refresh_token', refresh_token: e.refresh_token, client_id: e.client_id, resource: `${server}/mcp` }));
+    const d = await r.json().catch(() => null);
+    if (r.ok && d?.access_token) {
+      const next = toEntry(d, e);
+      setEntry(server, next);
+      return next;
+    }
+    if (r.status === 400 || r.status === 401) {
+      setEntry(server, null);
+      return null;
+    }
+    if (r.status === 404) throw notOpen(server);
+    throw new ScavaError(`Scava answered ${r.status} while renewing the access. Please try again.`);
+  });
+}
+
+async function validEntry(server) {
+  const e = entryOf(server);
+  if (!e) return null;
+  return fresh(e) ? e : renew(server, e.access_token);
+}
+
+const rpc = (server, entry, method, params) => send(`${server}/mcp`, {
+  method: 'POST',
+  headers: { authorization: `Bearer ${entry.access_token}`, 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'mcp-protocol-version': MCP_VERSION },
+  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+});
+
+// Every command that needs an account is one call of the tools every AI gets at /mcp: the rules stay in one place. Returns the text Scava wrote, what it attached for this tool (a one-time link) and whose account it was.
+export async function callTool(server, name, args, signInOptions) {
+  checkServer(server);
+  let entry = (await validEntry(server)) ?? (await signIn(server, signInOptions));
+  for (let attempt = 0; ; attempt++) {
+    const res = await rpc(server, entry, 'tools/call', { name, arguments: args });
+    if (res.status === 401 && attempt < 2) {
+      entry = (await renew(server, entry.access_token)) ?? (await signIn(server, signInOptions));
+      continue;
+    }
+    if (res.status === 404) throw notOpen(server);
+    const d = await res.json().catch(() => null);
+    if (!res.ok || !d?.result) throw new ScavaError(d?.error?.message || `Scava answered ${res.status}.`);
+    const text = (d.result.content ?? []).map((c) => c.text).join('\n');
+    if (d.result.isError) throw new ScavaError(text);
+    return { text, data: d.result.structuredContent ?? {}, account: entry.account };
+  }
+}
+
+// Who this computer is signed in as, checked with Scava. Null when it is not, or no longer.
+export async function whoAmI(server) {
+  checkServer(server);
+  let entry = await validEntry(server);
+  if (!entry) return null;
+  let res = await rpc(server, entry, 'tools/list', {});
+  if (res.status === 401) {
+    entry = await renew(server, entry.access_token);
+    if (!entry) return null;
+    res = await rpc(server, entry, 'tools/list', {});
+  }
+  if (res.status === 404) throw notOpen(server);
+  if (!res.ok) throw new ScavaError(`Scava answered ${res.status}.`);
+  return entry;
+}
+
+// Ends the access at Scava and here. A waiting sign-in ends with it. Other servers stay.
+export async function logout(server) {
+  checkServer(server);
+  fs.rmSync(signInPath(server), { force: true });
+  const e = entryOf(server);
+  if (!e) return { was: false };
+  let reached = false;
+  try {
+    reached = (await send(`${server}/oauth/revoke`, form({ token: e.refresh_token }))).ok;
+  } catch { /* said below */ }
+  await withLock(() => setEntry(server, null));
+  return { was: true, account: e.account, reached };
+}
+
+// --- Signing in -------------------------------------------------------------------------------------------------------
+
+// The name on the page, in the mail and on the Connect page: this computer, so a person can tell their connections apart.
+function clientName() {
+  const host = os.hostname().split('.')[0].replace(/[^\p{L}\p{N}-]/gu, '').slice(0, 40);
+  return host ? `Scava command (${host})` : 'Scava command';
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+// A sign-in that is still waiting on this computer, so a second command does not start another one.
+function pending(server) {
+  const rec = readPrivate(signInPath(server));
+  if (!rec || rec.status || rec.expires_at <= Date.now()) return null;
+  return rec.pid ? (alive(rec.pid) ? rec : null) : (Date.now() - rec.created_at < 10_000 ? rec : null);
+}
+
+function detach(...args) {
+  spawn(process.execPath, [CLI, '__sign-in', ...args], { detached: true, stdio: 'ignore', windowsHide: true, cwd: os.homedir() }).on('error', () => {}).unref();
+}
+
+async function startSignIn(server) {
+  const r = await send(`${server}/oauth/register`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ client_name: clientName(), redirect_uris: [RETURN_ADDRESS], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none' }),
+  });
+  if (r.status === 404) throw notOpen(server);
+  const c = await r.json().catch(() => null);
+  if (!r.ok || !c?.client_id) throw new ScavaError(c?.error_description || `Scava answered ${r.status}.`);
+  const t = Date.now();
+  const rec = {
+    server,
+    client_id: c.client_id,
+    verifier: crypto.randomBytes(48).toString('base64url'),
+    state: crypto.randomBytes(24).toString('base64url'),
+    created_at: t,
+    expires_at: t + SIGN_IN_MS,
+  };
+  writePrivate(signInPath(server), rec);
+  detach(signInPath(server), 'start');
+  return rec;
+}
+
+// What came back from the browser, whichever way: is it the answer to this sign-in, from this server?
+function foreignAnswer(u, rec) {
+  const a = Buffer.from(u.searchParams.get('state') ?? '');
+  const b = Buffer.from(rec.state);
+  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return 'This does not belong to the sign-in that is waiting on this computer.';
+  if (u.searchParams.get('iss') !== originOf(rec.server)) return 'This came from another server than the one this computer asked.';
+  return null;
+}
+
+const refusal = (u) => (u.searchParams.get('error') === 'access_denied'
+  ? 'You chose Cancel, so nothing was connected.'
+  : `Scava did not connect this computer: ${(u.searchParams.get('error_description') || u.searchParams.get('error')).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 200)}`);
+
+async function complete(rec, code) {
+  const r = await send(`${rec.server}/oauth/token`, form({
+    grant_type: 'authorization_code', code, client_id: rec.client_id, redirect_uri: rec.redirect_uri, code_verifier: rec.verifier, resource: `${rec.server}/mcp`,
+  }));
+  const d = await r.json().catch(() => null);
+  if (!r.ok || !d?.access_token) throw new ScavaError(d?.error_description || `Scava answered ${r.status}.`);
+  await withLock(() => {
+    setEntry(rec.server, toEntry(d, { client_id: rec.client_id }));
+    fs.rmSync(signInPath(rec.server), { force: true });
+  });
+}
+
+// A browser on another device cannot come back to this computer. The person copies the address it tried to open.
+export async function finishWithAddress(server, raw) {
+  const rec = readPrivate(signInPath(server));
+  if (!rec?.redirect_uri || rec.status || rec.expires_at <= Date.now()) throw new ScavaError(`No sign-in is waiting on this computer. Start one with: ${CMD} login`);
+  const wrong = 'That is not the address from the browser. It starts with http://127.0.0.1 and holds code= and state=.';
+  let u;
+  try {
+    u = new URL(String(raw).trim().replace(/^["']|["']$/g, ''));
+  } catch {
+    throw new ScavaError(wrong);
+  }
+  if (u.protocol !== 'http:' || !LOOPBACK.has(u.hostname) || u.pathname !== '/callback') throw new ScavaError(wrong);
+  const foreign = foreignAnswer(u, rec);
+  if (foreign) throw new ScavaError(foreign);
+  if (u.searchParams.get('error')) throw new ScavaError(refusal(u));
+  const code = u.searchParams.get('code');
+  if (!code) throw new ScavaError(wrong);
+  await complete(rec, code);
+}
+
+// The command watches for the result; pasted lines count too. Null when it did not come in time.
+async function waitForAllow(server, waitMs, { log, input }) {
+  const end = Date.now() + waitMs;
+  const rl = input ? readline.createInterface({ input }) : null;
+  rl?.on('line', (line) => {
+    if (line.trim()) finishWithAddress(server, line).catch((e) => log(e.message));
+  });
+  try {
+    for (;;) {
+      const e = entryOf(server);
+      if (e) return e;
+      const rec = readPrivate(signInPath(server));
+      if (rec?.status) {
+        fs.rmSync(signInPath(server), { force: true });
+        throw new ScavaError(rec.message);
+      }
+      if (!rec) {
+        const done = entryOf(server); // finished between the two looks
+        if (done) return done;
+        throw new ScavaError(`The sign-in ended. Please run the command again.`);
+      }
+      if (Date.now() >= end) return null;
+      await sleep(150);
+    }
+  } finally {
+    rl?.close();
+  }
+}
+
+export async function signIn(server, { browser = true, waitMs, reopen = false, log = console.log, input = process.stdin } = {}) {
+  checkServer(server);
+  const atTerminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const wait = waitMs ?? (atTerminal ? SIGN_IN_MS : AI_WAIT_MS);
+  let created = false;
+  let rec = await withLock(async () => {
+    const known = pending(server);
+    if (known) return known;
+    created = true;
+    return startSignIn(server);
+  });
+  for (const end = Date.now() + 15_000; !rec?.url; rec = readPrivate(signInPath(server))) {
+    const done = entryOf(server); // another command finished it in the meantime
+    if (done) return done;
+    if (rec?.status) throw new ScavaError(rec.message);
+    if (Date.now() > end) throw new ScavaError('Could not start the sign-in on this computer. Please run the command again.');
+    await sleep(100);
+  }
+
+  const canOpen = browser && !process.env.SSH_CONNECTION && !process.env.SSH_TTY && (process.platform === 'win32' || process.platform === 'darwin' || process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+  if (canOpen && (created || reopen)) openBrowser(rec.url);
+  log(`Scava needs a sign-in on this computer, once. ${canOpen ? 'A browser window opens for it. If not, open this address:' : 'Open this address in a browser, on any device:'}`);
+  log('');
+  log(`  ${rec.url}`);
+  log('');
+  log('Sign in and choose Allow. This continues by itself.');
+  const copy = 'On another device the browser then cannot reach 127.0.0.1. That is normal:';
+  if (atTerminal) log(`${copy} copy the whole address from its address bar and paste it here.`);
+  else {
+    log('');
+    log(`If you are an AI running this: ask the person to sign in in the browser and choose Allow. This command waits ${Math.round(wait / 1000)} seconds. If it ends or your terminal stops it, run it again once they have allowed it: the sign-in keeps waiting for ${Math.ceil((rec.expires_at - Date.now()) / 60_000)} minutes.`);
+    log(`${copy} ask for the whole address from its address bar, then run: ${CMD} login --paste "<address>"`);
+  }
+  log('');
+
+  const entry = await waitForAllow(server, wait, { log, input });
+  if (!entry) throw new ScavaError(`Not signed in yet: the sign-in is waiting in the browser. Once the person has chosen Allow, run this command again.`);
+  log(`Signed in to Scava as ${entry.account ?? 'your account'}. The access stays on this computer, in ${credentialsPath()}. End it with: ${CMD} logout`);
+  log('');
+  return entry;
+}
+
+// --- The small program that waits -------------------------------------------------------------------------------------
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const pageOf = (title, text) => `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)} · Scava</title>
+<style>body{margin:0;min-height:100vh;display:grid;place-items:center;padding:1rem;box-sizing:border-box;background:#131518;color:#f2f3f5;font:16px/1.5 system-ui,sans-serif}main{max-width:26rem}h1{font-size:1.4rem;margin:0 0 .5rem}p{margin:0;color:#a9afb8}</style>
+<main><h1>${esc(title)}</h1><p>${esc(text)}</p></main></html>`;
+
+// Started by the command, and started once more by itself, so it is nobody's child: a terminal that ends the command
+// and everything below it does not end the waiting. It holds no connection to the terminal. It ends with the sign-in.
+export async function signInHelper(file, step) {
+  if (step === 'start') {
+    detach(file);
+    return;
+  }
+  const rec = readPrivate(file);
+  if (!rec) return;
+  const fail = (status, message) => {
+    const now = readPrivate(file);
+    if (now) writePrivate(file, { ...now, status, message });
+  };
+  const answer = (s, status, title, text, then) => {
+    s.writeHead(status, {
+      'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', connection: 'close',
+      'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'",
+    });
+    s.end(pageOf(title, text), then);
+  };
+  const finished = () => setTimeout(() => process.exit(0), 100);
+  let current = null;
+  let busy = false;
+
+  const server = http.createServer(async (q, s) => {
+    let u = null;
+    try {
+      u = new URL(q.url, 'http://127.0.0.1');
+    } catch { /* nothing this program sent anyone to */ }
+    if (q.method !== 'GET' || u?.pathname !== '/callback' || !current) {
+      answer(s, 404, 'Nothing here', 'This page belongs to the sign-in of the Scava command.');
+      return;
+    }
+    // Something else knocking does not end the waiting.
+    const foreign = foreignAnswer(u, current);
+    if (foreign) {
+      answer(s, 400, 'Not connected', foreign);
+      return;
+    }
+    if (busy) {
+      answer(s, 409, 'One moment', 'This sign-in is being finished already.');
+      return;
+    }
+    busy = true;
+    if (u.searchParams.get('error')) {
+      fail('refused', refusal(u));
+      answer(s, 200, 'Not connected', 'Nothing was connected. You can close this window.', finished);
+      return;
+    }
+    try {
+      await complete(current, u.searchParams.get('code') ?? '');
+      answer(s, 200, 'Connected', 'You can close this window and go back to your terminal or your AI.', finished);
+    } catch (e) {
+      fail('failed', e.message);
+      answer(s, 200, 'Not connected', e.message, finished);
+    }
+  });
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const redirect = `http://127.0.0.1:${server.address().port}/callback`;
+    const challenge = crypto.createHash('sha256').update(rec.verifier).digest('base64url');
+    const q = new URLSearchParams({
+      response_type: 'code', client_id: rec.client_id, redirect_uri: redirect, state: rec.state,
+      code_challenge: challenge, code_challenge_method: 'S256', scope: 'scava', resource: `${rec.server}/mcp`,
+    });
+    current = { ...rec, redirect_uri: redirect, url: `${rec.server}/oauth/authorize?${q}`, pid: process.pid };
+    writePrivate(file, current);
+  } catch (e) {
+    fail('failed', `Could not wait for the browser on this computer: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Over when the time is up, or when it was finished another way (a pasted address, logout, a newer sign-in).
+  setInterval(() => {
+    const now = readPrivate(file);
+    if (!now || now.pid !== process.pid || now.status) process.exit(0);
+    if (now.expires_at <= Date.now()) {
+      fs.rmSync(file, { force: true });
+      process.exit(0);
+    }
+  }, 1000);
+}

package/cli/check.js

@@ -0,0 +1,250 @@
+// Test run: opens a published app once in Chrome or Edge without a window, with exactly the rules it has
+// online, and collects what goes wrong: errors in the code, calls Scava blocks, files that are missing,
+// data calls that fail, a page that stays empty. Every problem comes with a hint for the agent.
+// Runs on the creator's computer (no extra packages, DevTools protocol over Node's own WebSocket).
+// Scava never judges what the app does, only whether it runs under Scava's rules.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const BROWSERS = [
+  process.env.SCAVA_CHROME,
+  'C:/Program Files/Google/Chrome/Application/chrome.exe',
+  'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+  'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe',
+  'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+  '/usr/bin/microsoft-edge',
+];
+
+export const findBrowser = () => BROWSERS.find((p) => p && fs.existsSync(p)) || null;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// What an agent should do about each kind of problem.
+const HINTS = {
+  error: 'Fix this error in the app code.',
+  blockedConnect: 'Apps on Scava can only talk to their own address. Save and load data with scava.db, or remove this call.',
+  blockedImage: 'Images must be part of the app: put the file into the folder and refer to it with a relative path.',
+  blockedScript: 'Scripts may only come from the app itself or from cdnjs, jsDelivr, unpkg, esm.sh or the Tailwind CDN. Put the file into the folder.',
+  blockedStyle: 'Stylesheets and fonts may only come from the app itself or from the same CDNs and Google Fonts. Put the file into the folder.',
+  blockedFrame: 'Apps cannot embed other websites. Link to them instead.',
+  blockedCode: 'Do not run code from text (eval, new Function, setTimeout with a string). Write it as normal code.',
+  blockedOther: 'Scava blocked this. Keep everything the app needs inside its own folder.',
+  missing: 'The app refers to a file that is not in the uploaded folder. Check the path (relative to the page) and publish again.',
+  data: 'A scava.db call was refused. Check the rules in scava.json and the size of the entry.',
+  empty: 'The page shows nothing after loading. Usually a script failed or a build refers to wrong paths (use relative paths, e.g. base: "./" in Vite).',
+};
+
+function blockedHint(directive) {
+  const d = String(directive || '');
+  if (d.startsWith('connect')) return HINTS.blockedConnect;
+  if (d.startsWith('img') || d.startsWith('media')) return HINTS.blockedImage;
+  if (d.startsWith('script')) return HINTS.blockedScript;
+  if (d.startsWith('style') || d.startsWith('font')) return HINTS.blockedStyle;
+  if (d.startsWith('frame') || d.startsWith('child')) return HINTS.blockedFrame;
+  if (d.includes('trusted-types') || d.includes('unsafe-eval')) return HINTS.blockedCode;
+  return HINTS.blockedOther;
+}
+
+const trim = (s, n = 300) => {
+  const t = String(s ?? '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+
+// Opens `url` (a one-time link that signs the browser in as the app's creator) and returns the problems.
+// Returns { ran: false, reason } when no browser is installed.
+// Every question to the browser has a deadline (`answer`): a browser that goes away or a page that never stops working
+// (an endless loop) ends the test run with a reason, and the command waiting for it goes on.
+export async function testRun(url, { wait = 3500, timeout = 30000, answer = 15000, browser = findBrowser() } = {}) {
+  if (!browser) return { ran: false, reason: 'No Chrome or Edge found on this computer, so the test run was skipped.' };
+  const appOrigin = new URL(url).origin;
+  const silent = `the browser did not answer for ${Math.round(answer / 1000)} seconds. A script of the app may keep the page busy (an endless loop), or the app loads very slowly`;
+  const gone = 'the browser closed during the test run';
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'scava-check-'));
+  // Port 0: the browser takes a free port and writes it into its profile. A port of our own choosing can be taken, and two
+  // test runs at the same time could end up in one browser, where the first to finish closes it under the other.
+  const proc = spawn(browser, ['--headless=new', '--remote-debugging-port=0', `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check', '--disable-extensions', 'about:blank'], { stdio: 'ignore' });
+  const problems = [];
+  const seen = new Set();
+  const add = (p) => {
+    const key = `${p.kind}|${p.message}|${p.source || ''}|${p.line || 0}`;
+    if (seen.has(key) || problems.length >= 50) return;
+    seen.add(key);
+    problems.push(p);
+  };
+  let ws;
+  try {
+    let target;
+    const end = Date.now() + 10000;
+    while (!target && Date.now() < end) {
+      try {
+        const port = Number(fs.readFileSync(path.join(profile, 'DevToolsActivePort'), 'utf8').split('\n')[0]);
+        target = (await (await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(2000) })).json()).find((t) => t.type === 'page');
+      } catch {
+        /* not up yet */
+      }
+      if (!target) await sleep(200);
+    }
+    if (!target) return { ran: false, reason: 'The browser did not start, so the test run was skipped.' };
+    ws = new WebSocket(target.webSocketDebuggerUrl);
+    await new Promise((res, rej) => {
+      const timer = setTimeout(() => rej(new Error(silent)), answer);
+      ws.onopen = () => {
+        clearTimeout(timer);
+        res();
+      };
+      ws.onerror = () => {
+        clearTimeout(timer);
+        rej(new Error('the browser refused the connection'));
+      };
+    });
+    let id = 0;
+    const pending = new Map();
+    const requests = new Map();
+    let loaded = false;
+    // A browser that goes away ends every open question at once.
+    ws.onclose = () => {
+      for (const call of pending.values()) {
+        clearTimeout(call.timer);
+        call.rej(new Error(gone));
+      }
+      pending.clear();
+    };
+    ws.onmessage = (m) => {
+      const msg = JSON.parse(m.data);
+      if (msg.id && pending.has(msg.id)) {
+        const call = pending.get(msg.id);
+        pending.delete(msg.id);
+        clearTimeout(call.timer);
+        call.res(msg);
+        return;
+      }
+      const p = msg.params || {};
+      switch (msg.method) {
+        case 'Page.loadEventFired':
+          loaded = true;
+          break;
+        case 'Runtime.exceptionThrown': {
+          const d = p.exceptionDetails || {};
+          const text = d.exception?.description?.split('\n')[0] || d.text || 'Error';
+          add({ kind: 'error', message: trim(text), source: shortSource(d.url, appOrigin), line: (d.lineNumber ?? -1) + 1, hint: HINTS.error });
+          break;
+        }
+        case 'Runtime.consoleAPICalled':
+          if (p.type === 'error') {
+            const text = (p.args || []).map((a) => a.value ?? a.description ?? '').join(' ');
+            // Messages from the browser about blocked content arrive as Log entries; this is the app's own.
+            if (text) add({ kind: 'console', message: trim(text), source: '', line: 0, hint: 'The app logged an error. Check whether something failed.' });
+          }
+          break;
+        case 'Log.entryAdded': {
+          const e = p.entry || {};
+          if (e.level !== 'error') break;
+          const text = e.text || '';
+          if (/Content Security Policy|Trusted ?Type|evaluate a string/i.test(text)) {
+            // e.g. Refused to connect to 'https://api.example.com/x' because it violates ... directive: "connect-src 'self'".
+            const directive = (text.match(/directive:?\s*"([^"]+)"/i) || [])[1] || '';
+            const blocked = (text.match(/'(https?:[^']+)'/) || [])[1] || e.url || '';
+            const fromText = /unsafe-eval|evaluate a string|Trusted ?Type/i.test(text);
+            add({
+              kind: 'blocked',
+              message: trim(blocked ? `Blocked: ${shortSource(blocked, appOrigin)}` : text, 200),
+              source: fromText ? 'code from text' : directive.split(' ')[0] || '',
+              line: 0,
+              hint: fromText ? HINTS.blockedCode : blockedHint(directive),
+            });
+          }
+          break;
+        }
+        case 'Network.requestWillBeSent':
+          requests.set(p.requestId, p.request?.url || '');
+          break;
+        case 'Network.responseReceived': {
+          const r = p.response || {};
+          const u = r.url || requests.get(p.requestId) || '';
+          if (r.status >= 400 && u.startsWith(appOrigin)) {
+            const rel = shortSource(u, appOrigin);
+            if (rel.startsWith('/_scava/api/data')) add({ kind: 'data', message: trim(`${r.status} on ${rel.split('?')[0]}`), source: '', line: 0, hint: HINTS.data });
+            // The browser asks for /favicon.ico on its own; that is not something the app refers to.
+            else if (!rel.startsWith('/_scava/') && r.status === 404 && rel.split('?')[0] !== '/favicon.ico') {
+              add({ kind: 'missing', message: `Not found: ${rel.split('?')[0]}`, source: '', line: 0, hint: HINTS.missing });
+            }
+          }
+          break;
+        }
+        default:
+      }
+    };
+    const send = (method, params = {}) =>
+      new Promise((res, rej) => {
+        if (ws.readyState !== WebSocket.OPEN) {
+          rej(new Error(gone));
+          return;
+        }
+        const i = ++id;
+        const timer = setTimeout(() => {
+          pending.delete(i);
+          rej(new Error(silent));
+        }, answer);
+        pending.set(i, { res, rej, timer });
+        ws.send(JSON.stringify({ id: i, method, params }));
+      });
+    await Promise.all([send('Page.enable'), send('Runtime.enable'), send('Log.enable'), send('Network.enable')]);
+    await send('Page.navigate', { url });
+    const until = Date.now() + timeout;
+    while (!loaded && Date.now() < until) await sleep(100);
+    await sleep(wait); // scripts that start after loading, first data calls
+    const empty = await send('Runtime.evaluate', {
+      expression: `location.origin === ${JSON.stringify(appOrigin)} && document.body && !document.body.innerText.trim() && !document.querySelector('img,svg,canvas,video,iframe,input,button')`,
+      returnByValue: true,
+    });
+    if (empty.result?.result?.value === true) add({ kind: 'empty', message: 'The page stays empty after loading', source: '', line: 0, hint: HINTS.empty });
+    const where = await send('Runtime.evaluate', { expression: 'location.origin + location.pathname', returnByValue: true });
+    const landed = String(where.result?.result?.value || '');
+    if (!landed.startsWith(appOrigin)) {
+      return { ran: false, reason: `The test run could not open the app (ended at ${trim(landed, 120)}).` };
+    }
+    return { ran: true, problems };
+  } catch (err) {
+    return { ran: false, reason: `The test run failed: ${trim(err.message, 200)}` };
+  } finally {
+    try {
+      ws?.close();
+    } catch {
+      /* closed */
+    }
+    proc.kill();
+    for (let i = 0; i < 10; i++) {
+      try {
+        fs.rmSync(profile, { recursive: true, force: true });
+        break;
+      } catch {
+        await sleep(200);
+      }
+    }
+  }
+}
+
+function shortSource(u, origin) {
+  if (!u) return '';
+  return String(u).startsWith(origin) ? String(u).slice(origin.length) || '/' : trim(String(u).replace(/[?#].*$/, ''), 160);
+}
+
+// Text for the agent and the terminal.
+export function describe(result) {
+  if (!result.ran) return result.reason;
+  if (!result.problems.length) return 'Test run: the app loaded without errors, blocked calls or missing files.';
+  const lines = [`Test run found ${result.problems.length} problem${result.problems.length === 1 ? '' : 's'}:`];
+  for (const p of result.problems) {
+    const at = p.source && p.kind === 'error' ? ` (${p.source}${p.line > 0 ? `:${p.line}` : ''})` : '';
+    lines.push(`- [${p.kind}] ${p.message}${at}`, `  ${p.hint}`);
+  }
+  return lines.join('\n');
+}

package/cli/lib.js

@@ -0,0 +1,195 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+// The small tool on a person's computer (npm package "scava"): one command for every AI with a terminal, like wrangler.
+// This file holds what needs no account: reading a folder, carrying out a one-time link from Scava.
+// Signing in and the access on this computer are in account.js.
+
+// Online Scava. Locally: --server http://localhost:8787 or SCAVA_SERVER.
+export const DEFAULT_SERVER = 'https://scava.ai';
+// How this tool is called, in everything it tells a person or an AI to run next.
+export const CMD = process.env.SCAVA_CLI_COMMAND || 'npx -y scava-ai';
+const MAX_BYTES = 25 * 1024 * 1024;
+const MAX_FILES = 2000;
+const SKIP_DIRS = new Set(['node_modules', '.git', '.svn', '.hg', '.next', '.cache', '.vscode', '.idea', '__pycache__']);
+const BUILD_DIRS = ['dist', 'build', 'out', 'public', 'www'];
+export const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+export class ScavaError extends Error {
+  constructor(message, data = null) {
+    super(message);
+    this.data = data;
+  }
+}
+
+export function serverUrl(explicit) {
+  return (explicit || process.env.SCAVA_SERVER || DEFAULT_SERVER).replace(/\/+$/, '');
+}
+
+// The default browser. On Windows through rundll32: an address with & would end the command in cmd. A computer without
+// a browser is no error, the address is always printed as well.
+export function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+  } catch {
+    /* the address is printed as well */
+  }
+}
+
+export function readFolder(dir) {
+  const root = path.resolve(dir || '.');
+  let st;
+  try {
+    st = fs.statSync(root);
+  } catch {
+    throw new ScavaError(`${root} does not exist.`);
+  }
+  if (!st.isDirectory()) throw new ScavaError(`${root} is not a folder.`);
+  const files = [];
+  let total = 0;
+  (function walk(d, rel) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name.startsWith('.') && e.name !== '.well-known') continue;
+      const p = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(path.join(d, e.name), p);
+      } else if (e.isFile()) {
+        const buf = fs.readFileSync(path.join(d, e.name));
+        total += buf.length;
+        if (total > MAX_BYTES) throw new ScavaError('The folder is larger than 25 MB.');
+        files.push({ path: p, data: buf.toString('base64') });
+        if (files.length > MAX_FILES) throw new ScavaError('The folder has more than 2,000 files.');
+      }
+    }
+  })(root, '');
+  if (!files.some((f) => f.path === 'index.html')) {
+    const built = BUILD_DIRS.find((d) => fs.existsSync(path.join(root, d, 'index.html')));
+    const hint = built
+      ? ` There is one in ${built}/. If that is your app: ${CMD} deploy ${built}`
+      : fs.existsSync(path.join(root, 'package.json'))
+        ? ' This looks like a project that needs a build step. Build it and publish the output folder (often dist/ or build/).'
+        : '';
+    throw new ScavaError(`There is no index.html in ${root}.${hint}`);
+  }
+  return { root, files, total };
+}
+
+// Name of a new app: from scava.json, else the title of index.html, else the folder.
+export function guessName(root) {
+  try {
+    const c = JSON.parse(fs.readFileSync(path.join(root, 'scava.json'), 'utf8'));
+    if (typeof c.name === 'string' && c.name.trim()) return c.name.trim();
+  } catch { /* no scava.json */ }
+  try {
+    const m = fs.readFileSync(path.join(root, 'index.html'), 'utf8').match(/<title>([^<]{1,80})<\/title>/i);
+    if (m && m[1].trim()) return m[1].trim();
+  } catch { /* no title */ }
+  const base = path.basename(root);
+  return BUILD_DIRS.includes(base.toLowerCase()) ? path.basename(path.dirname(root)) : base;
+}
+
+// A path from the server, safe to write below the folder: no absolute paths, no "..", no drive letters, no names
+// Windows reserves. The server checked them on upload already; this is the second line on the builder's computer.
+function safeRelative(p) {
+  if (typeof p !== 'string' || !p || p.length > 300 || p.startsWith('/') || p.includes('\\')) return null;
+  const parts = p.split('/');
+  for (const part of parts) {
+    if (!part || part === '.' || part === '..' || /[\x00-\x1f<>:"|?*]/.test(part) || /[. ]$/.test(part)) return null;
+    if (/^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i.test(part)) return null;
+  }
+  return parts;
+}
+
+// The app a folder belongs to (written after publishing or pulling).
+export function appOfFolder(dir = '.') {
+  const file = path.join(path.resolve(dir), '.scava-app');
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').trim() : '';
+}
+
+// --- One-time links -------------------------------------------------------------------------------------------------
+
+// A link an agent passes on. Files only ever go to Scava itself, or to this computer when someone runs Scava locally:
+// a text the agent read cannot talk it into sending a folder somewhere else with this command.
+export function parseLink(raw, server) {
+  let u;
+  try {
+    u = new URL(String(raw));
+  } catch {
+    throw new ScavaError('That is not a Scava link. Ask your AI for a new one.');
+  }
+  const own = new URL(serverUrl(server)).origin;
+  const here = u.protocol === 'http:' && LOOPBACK.has(u.hostname);
+  if (u.origin !== own && !here) throw new ScavaError(`This link does not lead to Scava (${own}), so nothing was sent.`);
+  if (!/^\/up\/[A-Za-z0-9_-]{20,100}$/.test(u.pathname)) throw new ScavaError('That is not a Scava link. Ask your AI for a new one.');
+  return u;
+}
+
+async function useLink(u, body) {
+  let r;
+  try {
+    r = await fetch(u, { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json', 'x-scava': '1' }, body: JSON.stringify(body ?? {}) });
+  } catch {
+    throw new ScavaError(`Cannot reach Scava at ${u.origin}.`);
+  }
+  const text = await r.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { error: text.slice(0, 200) };
+  }
+  if (!r.ok) throw new ScavaError(data?.error || `${r.status} ${r.statusText}`, data);
+  return data;
+}
+
+// Uploads a folder as a new version. The folder remembers its app in .scava-app, for the next time. `folder`: when the
+// caller has read it already. The link is checked first: nothing is read for a link that leads somewhere else.
+export async function uploadFolder(link, dir, { server, folder } = {}) {
+  const u = parseLink(link, server);
+  const { root, files } = folder ?? readFolder(dir);
+  const r = await useLink(u, { files, app: appOfFolder(root) || undefined, name: guessName(root) });
+  try {
+    fs.writeFileSync(path.join(root, '.scava-app'), `${r.slug}\n`);
+  } catch { /* read-only folder: the app's name is printed anyway */ }
+  return r;
+}
+
+// What a test run needs: a link that opens the live app once, and what browsers reported so far.
+export const testLink = (link, { server } = {}) => useLink(parseLink(link, server));
+
+// The files of an app's live version into a folder. The folder is new or empty, or already belongs to the same app
+// (then the files of the version overwrite what is there; other files stay). It remembers the app.
+export async function pullLink(link, dir, { server } = {}) {
+  const src = await useLink(parseLink(link, server));
+  const root = path.resolve(dir || src.slug);
+  const linkFile = path.join(root, '.scava-app');
+  if (fs.existsSync(root)) {
+    if (!fs.statSync(root).isDirectory()) throw new ScavaError(`${root} is a file, not a folder.`);
+    const mine = fs.existsSync(linkFile) && fs.readFileSync(linkFile, 'utf8').trim() === src.slug;
+    if (!mine && fs.readdirSync(root).length) {
+      throw new ScavaError(`${root} is not empty and belongs to no app or another one. Pull into a new folder, or into the folder of ${src.slug}.`);
+    }
+  }
+  const files = src.files.map((f) => {
+    const parts = safeRelative(f.path);
+    if (!parts) throw new ScavaError(`Scava sent a file with a path this computer will not write: ${String(f.path).slice(0, 120)}`);
+    return { target: path.join(root, ...parts), bytes: Buffer.from(f.data, 'base64') };
+  });
+  for (const f of files) {
+    fs.mkdirSync(path.dirname(f.target), { recursive: true });
+    fs.writeFileSync(f.target, f.bytes);
+  }
+  fs.writeFileSync(linkFile, `${src.slug}\n`);
+  return { slug: src.slug, name: src.name, version: src.version, dir: root, fileCount: files.length };
+}
+
+// Why something was refused, each problem with its file and line.
+export function formatProblems(err) {
+  const lines = [err.message];
+  for (const p of err.data?.problems || []) lines.push(`  x ${p.file ? `${p.file}${p.line ? `:${p.line}` : ''}: ` : ''}${p.message}`);
+  for (const w of err.data?.warnings || []) lines.push(`  ! ${w.file ? `${w.file}${w.line ? `:${w.line}` : ''}: ` : ''}${w.message}`);
+  return lines.join('\n');
+}

package/cli/scava.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { CMD, serverUrl, openBrowser, formatProblems, ScavaError, appOfFolder, readFolder, uploadFolder, testLink, pullLink } from './lib.js';
+import { callTool, whoAmI, logout, signIn, finishWithAddress, signInHelper, credentialsPath } from './account.js';
+import { testRun, describe as describeRun } from './check.js';
+
+// "scava dev" needs Scava's own server code. That is only in the repo, never in the npm package: there the command is
+// not listed and says so.
+const HAS_DEV = fs.existsSync(new URL('./dev.js', import.meta.url));
+const DEV_HELP = `${CMD} dev [folder] [--port 8788] [--no-browser]
+    The app with its server code on this computer, before it goes online: published again on every save, secrets
+    from .env, type "run <schedule>" to run a schedule.
+
+`;
+
+const HELP = `Scava: hosting, sign-in and a database for the apps your AI builds. One command, for you and for any AI with a terminal.
+
+${CMD} deploy [folder]
+    Puts the app in this folder online, on its own address. A new app the first time, a new version after that.
+    The folder needs an index.html; for a build, deploy the output folder. Afterwards it opens the app once in a
+    browser here and lists what went wrong.
+    --name NAME  --message TEXT  --resolves 1,2 (change requests this version builds)  --app APP  --no-check
+
+${CMD} share WHO...
+    Lets people open the app: someone@company.com, "@company.com", group:leads. --remove WHO takes them out.
+    Without WHO: who can open it now.
+${CMD} apps
+    Your apps, the apps you co-edit, the apps shared with you.
+${CMD} requests
+    Change requests you accepted, ready to build. --done: the ones already built.
+${CMD} requests done ID
+    Marks one as done (deploy --resolves does that too). --note TEXT
+${CMD} test
+    Opens the live app once in a browser here, lists what goes wrong and what visitors reported.
+${CMD} server
+    The server part of the app: state, usage, secrets, schedules, outside services.
+${CMD} pull APP [folder]
+    The files of an app into a folder, to work on it here.
+${CMD} docs
+    What an app can use on Scava: data, rules, files, server code.
+${CMD} secret set NAME [--host HOST]
+    Where to set a key: the browser, so its value never passes through a terminal an AI can read.
+
+Inside a folder you deployed or pulled the app is known. Elsewhere add --app APP.
+
+The first command that needs your account opens a browser: sign in to Scava and choose Allow. After that it runs
+without a browser. The access stays on this computer, and whoever works under your user here acts as you.
+
+${CMD} whoami
+    Which account this computer is signed in as.
+${CMD} login
+    Signs in now. --no-browser prints the address, --wait SECONDS, --paste ADDRESS (from a browser on another device).
+${CMD} logout
+    Ends the access on this computer.
+
+${HAS_DEV ? DEV_HELP : ''}With a one-time link from the Scava tools in your AI (no sign-in here):
+
+  ${CMD} upload <folder> <link> [--no-check]
+  ${CMD} test <link>
+  ${CMD} pull <link> [folder]
+
+Claude or ChatGPT in the browser have no terminal: add a connector with the address https://scava.ai/mcp.
+All of it: https://scava.ai/docs
+`;
+
+// Options without a value, and options that may come several times. Everything else takes the next word as its value.
+const FLAGS = new Set(['no-check', 'no-browser', 'done', 'help', 'version']);
+const LISTS = new Set(['remove']);
+
+function parse(argv) {
+  const pos = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) {
+      pos.push(a);
+      continue;
+    }
+    const eq = a.indexOf('=');
+    const k = eq === -1 ? a.slice(2) : a.slice(2, eq);
+    let v = eq === -1 ? undefined : a.slice(eq + 1);
+    if (v === undefined && !FLAGS.has(k) && argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) v = argv[++i];
+    v ??= true;
+    if (LISTS.has(k)) (opts[k] ||= []).push(v);
+    else opts[k] = v;
+  }
+  return { pos, opts };
+}
+
+const text = (v) => (typeof v === 'string' && v ? v : undefined);
+const isLink = (s) => /^https?:\/\//i.test(s ?? '');
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  // The small program that waits for the browser (account.js), started by the commands below.
+  if (cmd === '__sign-in') {
+    await signInHelper(rest[0], rest[1]);
+    return;
+  }
+  const { pos, opts } = parse(rest);
+  // "deploy --help" is a question, not a deploy.
+  if (opts.help || rest.includes('-h')) {
+    console.log(HELP);
+    return;
+  }
+  const server = serverUrl(text(opts.server));
+  const signInOptions = {
+    browser: !opts['no-browser'],
+    ...(opts.wait !== undefined && Number.isFinite(Number(opts.wait)) ? { waitMs: Math.max(0, Number(opts.wait)) * 1000 } : {}),
+  };
+
+  // Which account a command acts for, once. Under one user on a computer that may not be who you think.
+  let named = false;
+  const tool = async (name, args) => {
+    const r = await callTool(server, name, args, signInOptions);
+    if (!named && r.account) console.log(`Account: ${r.account}`);
+    named = true;
+    return r;
+  };
+  const appHere = () => {
+    const app = text(opts.app) || appOfFolder('.');
+    if (!app) throw new ScavaError(`Which app? This folder was not deployed. Add --app APP (${CMD} apps lists them), or run this in the folder of the app.`);
+    return app;
+  };
+
+  switch (cmd) {
+    case 'deploy':
+    case 'publish': {
+      // Before anything else: is there an app here at all? Nobody signs in for nothing.
+      const folder = readFolder(pos[0] || '.');
+      const remembered = appOfFolder(folder.root);
+      const app = text(opts.app) || remembered || undefined;
+      const resolves = text(opts.resolves)?.split(',').map(Number).filter(Number.isInteger);
+      let asked;
+      try {
+        // No path of this computer leaves it: the answer is a one-time link for this upload.
+        asked = await tool('publish_app', { path: '.', app, name: text(opts.name), message: text(opts.message), resolves });
+      } catch (e) {
+        if (remembered && !text(opts.app)) e.message += `\nThis folder remembers the app ${remembered} (in the file .scava-app). If it belongs to another account, delete that file to start a new app.`;
+        throw e;
+      }
+      const r = await uploadFolder(asked.data.link, folder.root, { server, folder });
+      for (const line of r.lines) console.log(line);
+      if (!opts['no-check'] && r.check_url) {
+        console.log('');
+        console.log(describeRun(await testRun(r.check_url)));
+      }
+      console.log('');
+      console.log('Next:');
+      console.log(`  ${CMD} share someone@company.com "@company.com"   let people open it`);
+      console.log(`  ${CMD} requests                                   change requests you accepted, ready to build`);
+      console.log(`  ${CMD} docs                                       what an app can use on Scava: data, rules, files, server code`);
+      return;
+    }
+    case 'share': {
+      const r = await tool('share_app', { app: appHere(), add: pos, remove: opts.remove?.filter((x) => typeof x === 'string') });
+      console.log(r.text);
+      return;
+    }
+    case 'apps':
+      console.log((await tool('list_apps', {})).text);
+      return;
+    case 'requests': {
+      if (pos[0] === 'done') {
+        const id = Number(pos[1]);
+        if (!Number.isInteger(id)) throw new ScavaError(`Usage: ${CMD} requests done ID [--note TEXT]`);
+        console.log((await tool('update_change_request', { id, status: 'done', note: text(opts.note) })).text);
+        return;
+      }
+      console.log((await tool('list_change_requests', { app: text(opts.app), status: opts.done ? 'done' : 'accepted' })).text);
+      return;
+    }
+    case 'server':
+      console.log((await tool('get_server_info', { app: appHere() })).text);
+      return;
+    case 'test': {
+      const link = isLink(pos[0]) ? pos[0] : (await tool('get_app_problems', { app: pos[0] || appHere(), test_run: true })).data.link;
+      const r = await testLink(link, { server });
+      console.log(describeRun(await testRun(r.url)));
+      console.log('');
+      console.log(r.problems);
+      return;
+    }
+    case 'pull': {
+      const [first, folder] = pos;
+      if (!first) throw new ScavaError(`Usage: ${CMD} pull APP [folder]. ${CMD} apps lists your apps.`);
+      const link = isLink(first) ? first : (await tool('pull_app', { app: first, path: '.' })).data.link;
+      const r = await pullLink(link, folder, { server });
+      console.log(`Pulled "${r.name}" v${r.version} (${r.fileCount} file${r.fileCount === 1 ? '' : 's'}) into ${r.dir}`);
+      console.log(`Change the files there, then run ${CMD} deploy in that folder: it goes to the same app.`);
+      return;
+    }
+    case 'upload': {
+      const [folder, link] = pos;
+      if (!folder || !link) throw new ScavaError(`Usage: ${CMD} upload <folder> <link>. Your AI gets the link from publish_app. Without a link: ${CMD} deploy`);
+      const r = await uploadFolder(link, folder, { server });
+      for (const line of r.lines) console.log(line);
+      if (opts['no-check'] || !r.check_url) return;
+      console.log('');
+      console.log(describeRun(await testRun(r.check_url)));
+      return;
+    }
+    case 'login': {
+      if (typeof opts.paste === 'string') {
+        await finishWithAddress(server, opts.paste);
+        const me = await whoAmI(server);
+        console.log(`Signed in to Scava as ${me?.account ?? 'your account'}. The access stays on this computer, in ${credentialsPath()}.`);
+        console.log(`Next: ${CMD} deploy`);
+        return;
+      }
+      const me = await whoAmI(server);
+      if (me) {
+        console.log(`Already signed in to Scava as ${me.account ?? 'your account'}. To use another account: ${CMD} logout`);
+        return;
+      }
+      await signIn(server, { ...signInOptions, reopen: true });
+      console.log(`Next: ${CMD} deploy`);
+      return;
+    }
+    case 'whoami': {
+      const me = await whoAmI(server);
+      if (!me) {
+        console.log(`Not signed in to Scava at ${server}. The next command that needs your account opens the browser.`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log(`Signed in to Scava as ${me.account ?? 'your account'} (${server}). The access is in ${credentialsPath()}. End it with: ${CMD} logout`);
+      return;
+    }
+    case 'logout': {
+      const r = await logout(server);
+      if (!r.was) console.log('This computer was not signed in.');
+      else if (r.reached) console.log(`Signed out ${r.account ?? 'your account'} on this computer. The connection at Scava has ended too.`);
+      else console.log(`Removed the access of ${r.account ?? 'your account'} from this computer. Scava could not be reached, so disconnect it on the Connect page as well: ${server}/#/connect`);
+      return;
+    }
+    case 'secret': {
+      const [action, name] = pos;
+      if (action !== 'set') throw new ScavaError(`Usage: ${CMD} secret set NAME [--host api.example.com] [--app APP]`);
+      const slug = text(opts.app) || appOfFolder('.');
+      const page = `${server}/#/${slug ? `apps/${encodeURIComponent(slug)}` : ''}`;
+      console.log('Keys are set in the browser, so the value never passes through a terminal an AI can read.');
+      console.log(`Open ${page} and go to "Server code"${slug ? '' : ' of your app'}.`);
+      if (name) console.log(`Name: ${name}${text(opts.host) ? `, only for: ${opts.host}` : ''}`);
+      if (!opts['no-browser']) openBrowser(page);
+      return;
+    }
+    case 'dev': {
+      let dev;
+      try {
+        ({ dev } = await import('./dev.js'));
+      } catch (e) {
+        if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
+        throw new ScavaError('scava dev is not part of the scava package. Test the app online instead: deploying runs a test run.');
+      }
+      await dev({ dir: pos[0] || '.', port: Number(opts.port) || 8788, browser: !opts['no-browser'], email: text(opts.email) });
+      return;
+    }
+    case 'docs': {
+      const r = await fetch(`${server}/llms.txt`).catch(() => null);
+      if (!r?.ok) throw new ScavaError(`Cannot reach Scava at ${server}`);
+      console.log(await r.text());
+      return;
+    }
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(HELP);
+      return;
+    case '--version':
+    case '-v':
+      console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+      return;
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.log(HELP);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((e) => {
+  console.error(e instanceof ScavaError ? formatProblems(e) : e.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "scava-ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Hosting, login and a database for the internal tools your AI agent builds, with sharing and change requests. One command: npx -y scava-ai deploy.",
+  "type": "module",
+  "bin": {
+    "scava": "cli/scava.js"
+  },
+  "files": [
+    "cli/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "homepage": "https://scava.ai",
+  "license": "UNLICENSED",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "codex",
+    "cursor",
+    "agents",
+    "hosting",
+    "deploy",
+    "login",
+    "authentication",
+    "database",
+    "permissions",
+    "internal-tools",
+    "vibe-coding",
+    "sharing"
+  ]
+}