scava-ai 0.1.0 → 0.2.0

package/cli/check.js

@@ -39,7 +39,7 @@ const HINTS = {
   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).',
+  empty: 'The page shows nothing after loading. Usually a script failed, or the page loads files that are not in the uploaded folder: publish the output folder of the build (for example dist) as it is.',
 };
 
 function blockedHint(directive) {

package/cli/lib.js

@@ -1,195 +1,252 @@
-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');
-}
+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} setup ${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. Build tools empty their output folder on every
+// build (Vite everything but .git), so a folder inside a project, such as its dist folder, is remembered in the project
+// folder: its .scava-app holds the folder's path and the app (07.11.2026: a rebuilt dist made a second app). A folder
+// that is a project itself, or lies in none, keeps the plain file in itself, as before.
+const PROJECT_MARKS = ['package.json', '.git'];
+const isProject = (dir) => PROJECT_MARKS.some((m) => fs.existsSync(path.join(dir, m)));
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+// The nearest project folder above `root`, at most three levels up and below the home folder; null when `root` is a
+// project itself or there is none.
+function projectAbove(root) {
+  if (isProject(root)) return null;
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  let dir = root;
+  for (let i = 0; i < 3; i++) {
+    const up = path.dirname(dir);
+    if (up === dir || (home && samePath(up, path.resolve(home)))) return null;
+    if (isProject(up)) return up;
+    dir = up;
+  }
+  return null;
+}
+
+// What a .scava-app holds: { '.': app } for the folder it lies in, the paths of folders below it for theirs.
+function readLinks(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8').trim();
+  } catch {
+    return {};
+  }
+  if (!text.startsWith('{')) return text ? { '.': text } : {};
+  try {
+    const links = JSON.parse(text);
+    return links && typeof links === 'object' && !Array.isArray(links) ? links : {};
+  } catch {
+    return {};
+  }
+}
+
+const keyIn = (project, root) => path.relative(project, root).split(path.sep).join('/');
+
+export function appOfFolder(dir = '.') {
+  const root = path.resolve(dir);
+  const own = readLinks(path.join(root, '.scava-app'))['.'];
+  if (typeof own === 'string' && own) return own;
+  const project = projectAbove(root);
+  const app = project ? readLinks(path.join(project, '.scava-app'))[keyIn(project, root)] : '';
+  return typeof app === 'string' ? app : '';
+}
+
+// Remembers the app of a folder and returns the file it is in: the project's for a folder inside a project, else the
+// folder's own. Other entries of that file stay.
+export function rememberApp(dir, slug) {
+  const root = path.resolve(dir);
+  const project = projectAbove(root);
+  const file = path.join(project ?? root, '.scava-app');
+  const links = readLinks(file);
+  links[project ? keyIn(project, root) : '.'] = slug;
+  const keys = Object.keys(links);
+  fs.writeFileSync(file, keys.length === 1 && keys[0] === '.' ? `${slug}\n` : `${JSON.stringify(links, null, 2)}\n`);
+  return file;
+}
+
+// --- 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 {
+    rememberApp(root, r.slug);
+  } 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);
+  if (fs.existsSync(root)) {
+    if (!fs.statSync(root).isDirectory()) throw new ScavaError(`${root} is a file, not a folder.`);
+    const mine = appOfFolder(root) === 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);
+  }
+  rememberApp(root, src.slug);
+  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');
+}