gipity 1.1.5 → 1.1.7

package/dist/commands/page-eval.js

@@ -5,6 +5,7 @@ import { brand, bold, muted, warning, success } from '../colors.js';
 import { run, parseDuration } from '../helpers/index.js';
 import { getAuth } from '../auth.js';
 import { resolveProjectContext } from '../config.js';
+import { createCheckpoint, restoreCheckpoint, resolveDatabase } from '../db-checkpoint.js';
 import { uploadPublicFixture, uploadCameraFeed, assertCameraFile, deleteFixture } from '../page-fixtures.js';
 // Shown when an eval runs cleanly but returns nothing serializable. Turns a
 // bare/opaque `null` into a deterministic, actionable nudge so the agent shapes
@@ -257,6 +258,31 @@ export function budgetOverrunHint(reason, usedBudgetMs) {
         `(up to ${EVAL_SCRIPT_BUDGET_MAX_MS}), e.g. --timeout ${EVAL_SCRIPT_BUDGET_MAX_MS} — ` +
         `or gate on a ready signal instead: --wait-for '<selector>' --wait-timeout ${MAX_WAIT_MS}.`;
 }
+/** The server aborts a script whose page navigated out from under it, and tells
+ *  the caller to "split the check into two evals". For the case that actually
+ *  produces this (seed state, reload, assert the state came back), that advice
+ *  sends the caller down the wrong road: two evals are two independent page
+ *  sessions, so the second one has to re-seed before it can read anything, and
+ *  the thing being verified (a real reload restoring real persisted state) is
+ *  never exercised. `--reload` is the primitive for it: one page load, reloaded
+ *  IN PLACE with storage preserved, second expression against the post-reload
+ *  DOM. Name it here, at the exact moment the caller hand-rolled it. */
+export function navigationAbortHint(reason) {
+    if (!/navigated or reloaded/i.test(reason))
+        return null;
+    return `If you were verifying that state SURVIVES a reload, that is what --reload is for (one command, one page): ` +
+        `gipity page eval "<url>" '<seed/assert expr>' --reload '<assert-restored expr>'. ` +
+        `It reloads the page in place (localStorage/sessionStorage/cookies preserved) and reports the second result ` +
+        `separately. Splitting into two 'page eval' calls does NOT do this: each call is its own browser session, so ` +
+        `the second one starts from empty storage and never exercises the restore path.`;
+}
+/** True when the submitted script already drives the app's clock itself
+ *  (`core.advance(seconds)` on the 3D templates, the imported `advance(seconds)`
+ *  on the 2D one). Such a script does not care what the renderer paints at, so
+ *  the slow-render warning below has nothing to tell it. Exported for tests. */
+export function stepsDeterministically(script) {
+    return /\badvance\s*\(/.test(script);
+}
 /** The headless browser paints slowly, and what that MEANS depends on what the
  *  page is doing — so the one-size warning was actively misleading on a --camera
  *  run. A vision app has no loop to step: its pipeline is driven by camera
@@ -273,6 +299,8 @@ export function budgetOverrunHint(reason, usedBudgetMs) {
  *  deterministic way to wait (--wait-for) instead of inviting a wall-clock
  *  escalation that is guaranteed to be wasted. Exported for tests. */
 export function slowRenderMessage(fps, o) {
+    if (!o.camera && stepsDeterministically(o.script ?? ''))
+        return null;
     if (o.camera) {
         const frames = Math.max(1, Math.round(fps * (o.waitMs / 1000)));
         return `${warning('⚠ Slow render:')} page painted at ${fps} fps, so the app's vision pipeline ran on roughly `
@@ -382,7 +410,7 @@ export const pageEvalCommand = new Command('eval')
     .option('--file <path>', `Read the script body from a file instead of the inline <expr> arg (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<'EOF' ... EOF) with no tmp file. Runs as an async function body, so top-level return/await work. Same post-load budget as <expr> (--timeout).`)
     .option('--step <expr>', `Run another expression against the SAME loaded page, after <expr> (repeat, max ${MAX_EVAL_STEPS}). Whatever that page load paid for — a vision model coming up, a game booting, a socket connecting — stays up for every step, so an N-part check costs ONE page load instead of N. Each step gets its own in-page budget and its own reported result.`, (val, prev) => [...prev, val], [])
     .option('--fixture <path>', 'Host a local file and expose it to the eval as `fixtureUrl` (and under `fixtures` by basename) to fetch in-page. For verifying a render/parse path against a real binary (an MP3, an image) - no size limit, auto-deleted after the run. The hosted URL has permissive CORS, so `new Image(); img.crossOrigin="anonymous"; img.src=fixtureUrl` decodes untainted for a canvas/pixel read - this is the UPLOAD analog of --camera: feed a known photo/video to a file-upload vision app (web-vision-detect) and run its detector, no need to deploy a throwaway test asset into the app. Repeat for several files (single-value so it never swallows the inline <expr>).', (val, prev) => [...prev, val], [])
-    .option('--reload <expr>', 'After the first eval, reload the page IN PLACE (localStorage/sessionStorage/cookies preserved) and evaluate this second expression against the post-reload DOM. One command verifies persisted state survives a reload: seed/assert state with <expr>, then assert the restored UI here.')
+    .option('--reload <expr>', 'After the first eval, reload the page IN PLACE (localStorage/sessionStorage/cookies preserved) and evaluate this second expression against the post-reload DOM. One command verifies persisted state survives a reload ("remember it when I come back"): seed/assert state with <expr>, then assert the restored UI here. This is the ONLY way to check that - reloading inside the body aborts the eval (the result is lost with the old page), and two separate `page eval` calls are two fresh browser profiles, so the second starts from empty storage.')
     .option('--reload-file <path>', 'Read the post-reload expression from a file instead of inline --reload (mutually exclusive)')
     .option('--camera <path>', `Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser's WEBCAM feed, so a camera app's real pipeline (getUserMedia → MediaPipe/YOLOX → your app logic) runs headlessly on a frame you choose. Implies --fake-media and waits ${CAMERA_DEFAULT_WAIT_MS / 1000}s for the vision model to load. No frame handy? gipity generate image "a hand making a closed fist, palm to camera".`)
     .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so a voice/camera app runs headlessly instead of hitting its no-camera path. The feed is a built-in test pattern (and a tone) — nothing a vision model can recognize; to drive a vision app use --camera <path> instead.')
@@ -391,6 +419,7 @@ export const pageEvalCommand = new Command('eval')
     .option('--wait-timeout <ms>', `Max ms to wait for --wait-for before giving up (max ${WAIT_FOR_MAX_MS})`, '5000')
     .option('--timeout <ms>', `How long the script itself may run IN the page. Bare number = MILLISECONDS (so 90s = 90000, NOT 90); or pass an explicit unit that means the same on both this and \`sandbox run --timeout\` — --timeout 90s. Its own await/setTimeout pauses count (default ${EVAL_SCRIPT_BUDGET_MS}, ${EVAL_SCRIPT_BUDGET_CAMERA_MS} with --camera/--fake-media; floor 1000, max ${EVAL_SCRIPT_BUDGET_MAX_MS}). Raise it to trace a sequence that unfolds over time (a game round, an animation). Distinct from --wait, which only sleeps BEFORE the script.`)
     .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
+    .option('--restore-db', "Snapshot the app database before the script runs and roll it back after, so a write-path check (click Approve, submit the form, edit a row) leaves the real data untouched. Use this whenever the eval WRITES - it is the undo for driving the deployed app against real project data. Same snapshot/undo standalone: gipity db checkpoint / gipity db restore.")
     .option('--json', 'Output as JSON')
     .action((url, exprArg, opts) => run('Page eval', async () => {
     // A JS-intent flag guess (captured as a hidden decoy below): redirect to the
@@ -534,7 +563,24 @@ export const pageEvalCommand = new Command('eval')
     // instant error, not an upload plus an opaque browser-side failure.
     if (opts.camera)
         assertCameraFile(opts.camera);
+    // Set when --restore-db took a checkpoint; the finally below rolls the app
+    // database back to it, so a write-path smoke test leaves no residue in the
+    // real data the user is about to look at.
+    let restoreDb;
     try {
+        if (opts.restoreDb) {
+            const { config } = await resolveProjectContext({});
+            projectGuid = config.projectGuid;
+            const database = await resolveDatabase(config.projectGuid);
+            if (!database) {
+                console.error(muted('--restore-db: this project has no database - nothing to roll back.'));
+            }
+            else {
+                const cp = await createCheckpoint(config.projectGuid, database);
+                console.error(muted(`Checkpointed ${cp.tables.length} table(s), ${cp.rows} row(s) in '${database}' - rolled back when this eval finishes.`));
+                restoreDb = { projectGuid: config.projectGuid, database };
+            }
+        }
         if (fixturePaths.length || opts.camera) {
             const { config } = await resolveProjectContext({});
             projectGuid = config.projectGuid;
@@ -589,7 +635,10 @@ export const pageEvalCommand = new Command('eval')
             // raises it — and the flag is what the caller needs next. Name it, with
             // the value THIS run used, so the retry is an edit rather than a guess.
             const msg = err?.message ?? '';
-            const hint = budgetOverrunHint(msg, scriptBudgetMs);
+            const hint = budgetOverrunHint(msg, scriptBudgetMs)
+                // A script aborted by its own reload is nearly always a persistence
+                // check hand-rolled without --reload; point at the flag that does it.
+                ?? (reloadExpr === undefined ? navigationAbortHint(msg) : null);
             if (!hint)
                 throw err;
             throw new Error(`${msg}\n${hint}`);
@@ -632,8 +681,17 @@ export const pageEvalCommand = new Command('eval')
         // page's rAF loop is its clock, and engines cap the per-frame delta, so
         // `setTimeout(2000)` may advance only a fraction of a second of app time.
         // Without this line the eval returns a plausible-looking false negative.
+        // A script that already steps the loop itself is immune to all of that, so
+        // slowRenderMessage returns null for it rather than prescribing the fix it
+        // is already applying.
         if (d.slowRender) {
-            console.log(slowRenderMessage(d.slowRender.fps, { camera: !!camera, waitMs }));
+            const slow = slowRenderMessage(d.slowRender.fps, {
+                camera: !!camera,
+                waitMs,
+                script: [expr, ...steps, reloadExpr ?? ''].join('\n'),
+            });
+            if (slow)
+                console.log(slow);
         }
         // Identity line on EVERY run: without it an agent can't distinguish
         // "signed-in eval" from "--auth silently no-op'd against the anonymous
@@ -676,6 +734,15 @@ export const pageEvalCommand = new Command('eval')
         }
     }
     finally {
+        if (restoreDb) {
+            try {
+                const r = await restoreCheckpoint(restoreDb.projectGuid, restoreDb.database);
+                console.error(muted(`Rolled ${r.tables.length} table(s) back to the checkpoint (${r.rows} row(s)) - nothing this eval wrote survives.`));
+            }
+            catch (err) {
+                console.error(warning(`⚠ Could not roll back the database - the checkpoint is still there, retry with: gipity db restore (${err.message})`));
+            }
+        }
         for (const h of [...hosted, ...(camera ? [camera] : [])]) {
             try {
                 await deleteFixture(projectGuid, h.guid);

package/dist/commands/page-screenshot.js

@@ -1,6 +1,6 @@
 import { Command, Option } from 'commander';
 import { mkdirSync, writeFileSync } from 'fs';
-import { dirname, join, resolve as resolvePath } from 'path';
+import { dirname, extname, join, resolve as resolvePath } from 'path';
 import { postForTarEntries } from '../api.js';
 import { getConfig, getProjectRoot } from '../config.js';
 import { getAuth } from '../auth.js';
@@ -171,6 +171,19 @@ function resolveDevice(name) {
     const available = [...Object.keys(DEVICE_PRESETS), ...TOUCH_DEVICES].join(', ');
     throw new Error(`Unknown --device preset: "${name}" (known: ${available})`);
 }
+/** Slug used to tell one viewport's `-o` file from another's: the device name the
+ *  caller typed (`desktop`, `Pixel 9` → `pixel-9`) or the raw dimensions. */
+function viewportSlug(name) {
+    return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'shot';
+}
+/** Expand an `--output` path into one path per viewport by treating it as a stem:
+ *  `tmp/shot.png` + `mobile` → `tmp/shot-mobile.png`. Keeps the caller's extension
+ *  (defaulting to .png) so a multi-device capture writes every file it took. */
+function stemPath(output, suffix) {
+    const ext = extname(output) || '.png';
+    const base = ext && output.endsWith(ext) ? output.slice(0, -ext.length) : output;
+    return `${base}-${suffix}${ext}`;
+}
 function splitCsv(values) {
     if (!values || values.length === 0)
         return [];
@@ -238,7 +251,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     .option('--action <js>', 'Run JS in the page before capturing - e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs as an async function body, so const/await and app-relative import(\'./...\') work. Runs after the post-load delay, then settles again before the shot. If it throws, the capture still happens and the failure is reported.')
     .option('--file <path>', 'Read the pre-capture script from a file instead of inline --action (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<\'EOF\' ... EOF) with no tmp file. For a multi-step driver - click through a flow, wait for it to render - then capture. Same async-function-body semantics as --action; same --file flag as page eval.')
     .option('--full', 'Capture the full scrollable page (default: viewport only). Scrolls the page through first so scroll-reveal/fade-in-on-scroll (IntersectionObserver) sections render into the shot instead of capturing blank.')
-    .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
+    .option('-o, --output <file>', 'Output path (default .gipity/screenshots/ss-<host>-<timestamp>.png). With several viewports it is a stem: -o tmp/shot.png --device desktop,mobile writes tmp/shot-desktop.png and tmp/shot-mobile.png.')
     .option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
     .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern — to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
     .option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture — so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
@@ -347,9 +360,12 @@ export const pageScreenshotCommand = new Command('screenshot')
         ...deviceNames.map(resolveDevice),
         ...viewportStrs.map(parseViewportString),
     ];
-    if (opts.output && customViewports.length > 1) {
-        throw new Error('--output can only be used with a single viewport');
-    }
+    // Parallel to customViewports: what each capture is called when `--output` has
+    // to name more than one file.
+    const viewportLabels = [
+        ...deviceNames.map(viewportSlug),
+        ...viewportStrs.map(viewportSlug),
+    ];
     // Server defaults to 1280×720 when viewports is omitted - don't send it in
     // the no-flag case so the filename stays unsuffixed (no viewport segment).
     const userSpecifiedViewports = customViewports.length > 0;
@@ -437,9 +453,21 @@ export const pageScreenshotCommand = new Command('screenshot')
     }
     const dir = defaultScreenshotDir();
     const savedFiles = [];
+    // With more than one viewport, `--output` is a stem: every capture gets its own
+    // file (shot.png → shot-desktop.png, shot-mobile.png) instead of overwriting.
+    const usedStems = new Set();
+    const outputPath = (i) => {
+        if (pngs.length === 1)
+            return opts.output;
+        let suffix = viewportLabels[i] ?? dimSuffix(meta.screenshots[i].viewport);
+        while (usedStems.has(suffix))
+            suffix += `-${i + 1}`;
+        usedStems.add(suffix);
+        return stemPath(opts.output, suffix);
+    };
     for (let i = 0; i < pngs.length; i++) {
         const target = opts.output
-            ? opts.output
+            ? outputPath(i)
             : join(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
         // Create the target's parent dir so a `-o` path under a not-yet-existing
         // directory (e.g. .gipity/screenshots/home.png) writes cleanly instead of

package/dist/commands/records.js

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
-import { get, post, put, patch, del } from '../api.js';
+import { get, post, put, patch, del, publicRequest, mintAppToken } from '../api.js';
+import { getAuth } from '../auth.js';
 import { requireConfig } from '../config.js';
 import { bold, muted } from '../colors.js';
 import { run, printList, printResult } from '../helpers/index.js';
@@ -10,6 +11,33 @@ import { confirm } from '../utils.js';
 // /projects/<guid>/records mirror.)
 export const recordsCommand = new Command('records')
     .description('Manage app records (Gipity Records - validated CRUD with audit history)');
+const ANON_FLAG = '--anon';
+const ANON_HELP = 'Call as an anonymous visitor (the public path a signed-out user hits) instead of as your signed-in account';
+/** One HTTP surface for every records subcommand, so `--anon` is a persona
+ *  switch rather than a different code path. Anonymous calls mint the same
+ *  short-lived app token the browser SDK uses and send no owner credentials -
+ *  this is exactly what a signed-out visitor's request looks like, so a 401 here
+ *  is the true answer for an auth-gated table. The persona goes to stderr so
+ *  stdout stays parseable; without it, "verify the anonymous path" silently runs
+ *  as the owner and the public path never gets exercised. */
+async function recordsHttp(opts) {
+    const config = requireConfig();
+    if (!opts.anon) {
+        const who = getAuth()?.email;
+        console.error(muted(`Auth: calling as ${who ?? 'your signed-in account'} (the owner persona; use ${ANON_FLAG} for the public visitor path)`));
+        return { guid: config.projectGuid, get, post, put, patch, del };
+    }
+    console.error(muted('Auth: anonymous visitor (the public path a signed-out user hits)'));
+    const headers = await mintAppToken(config.projectGuid);
+    return {
+        guid: config.projectGuid,
+        get: (path) => publicRequest('GET', path, undefined, headers),
+        post: (path, body) => publicRequest('POST', path, body, headers),
+        put: (path, body) => publicRequest('PUT', path, body, headers),
+        patch: (path, body) => publicRequest('PATCH', path, body, headers),
+        del: (path, body) => publicRequest('DELETE', path, body, headers),
+    };
+}
 recordsCommand
     .command('list')
     .description('List record tables')
@@ -51,25 +79,38 @@ recordsCommand
 }));
 recordsCommand
     .command('query <table>')
-    .description('List records')
-    .option('--filter <filter>', 'Filter string (e.g., "status:eq:active")')
+    .description('List records (full-text search, filter, sort, recycle bin)')
+    .option('-q, --q <text>', 'Full-text search across the table\'s text columns (needs `--searchable true` on the table)')
+    .option('--filter <filter>', 'AND filter string (e.g., "status:eq:active")')
+    .option('--any <filter>', 'OR filter group, same grammar as --filter (e.g., "owner:eq:me,shared:eq:true")')
     .option('--sort <sort>', 'Sort string (e.g., "created_at:desc")')
     .option('--limit <n>', 'Max rows', '20')
     .option('--offset <n>', 'Offset', '0')
     .option('--fields <fields>', 'Comma-separated column names')
+    .option('--include-deleted', 'Include soft-deleted rows (owner/editor)')
+    .option('--only-deleted', 'Only soft-deleted rows - the recycle bin (owner/editor)')
+    .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, opts) => run('Query', async () => {
-    const config = requireConfig();
+    const api = await recordsHttp(opts);
     const params = new URLSearchParams();
+    if (opts.q)
+        params.set('q', opts.q);
     if (opts.filter)
         params.set('filter', opts.filter);
+    if (opts.any)
+        params.set('any', opts.any);
     if (opts.sort)
         params.set('sort', opts.sort);
     params.set('limit', opts.limit);
     params.set('offset', opts.offset);
     if (opts.fields)
         params.set('fields', opts.fields);
-    const res = await get(`/api/${config.projectGuid}/records/${table}?${params}`);
+    if (opts.includeDeleted)
+        params.set('include_deleted', '1');
+    if (opts.onlyDeleted)
+        params.set('only_deleted', '1');
+    const res = await api.get(`/api/${api.guid}/records/${table}?${params}`);
     if (opts.json) {
         console.log(JSON.stringify(res));
     }
@@ -85,21 +126,26 @@ recordsCommand
 recordsCommand
     .command('get <table> <id>')
     .description('Get a record')
+    .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, id, opts) => run('Get', async () => {
-    const config = requireConfig();
-    const res = await get(`/api/${config.projectGuid}/records/${table}/${id}`);
+    const api = await recordsHttp(opts);
+    const res = await api.get(`/api/${api.guid}/records/${table}/${id}`);
     console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
 }));
 recordsCommand
-    .command('history <table> <id>')
-    .description('Audit history for a record (who/what changed it, with English summaries)')
+    .command('history <table> [id]')
+    .description('Audit history (who/what changed it, with English summaries). Omit <id> for the whole table\'s feed.')
     .option('--limit <n>', 'Max events', '20')
+    .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, id, opts) => run('History', async () => {
-    const config = requireConfig();
-    const res = await get(`/api/${config.projectGuid}/records/${table}/${id}/history?limit=${encodeURIComponent(opts.limit)}`);
-    printList(res.data, opts, 'No history for this record.', e => {
+    const api = await recordsHttp(opts);
+    // Table-wide feed when no id is given - the same endpoint an activity/history
+    // view reads, so verifying it needs no hand-built HTTP call.
+    const scope = id ? `${table}/${encodeURIComponent(id)}` : table;
+    const res = await api.get(`/api/${api.guid}/records/${scope}/history?limit=${encodeURIComponent(opts.limit)}`);
+    printList(res.data, opts, id ? 'No history for this record.' : `No history for "${table}".`, e => {
         const summary = e.detail?.summary || `${e.action} ${e.entity_type} ${e.entity_id}`;
         return `${muted(e.created_at)}  ${bold(e.source || '-')}  ${summary}`;
     });
@@ -108,34 +154,58 @@ recordsCommand
     .command('create <table>')
     .description('Create a record')
     .requiredOption('--data <json>', 'JSON object with field values')
+    .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, opts) => run('Create', async () => {
-    const config = requireConfig();
+    const api = await recordsHttp(opts);
     const data = JSON.parse(opts.data);
-    const res = await post(`/api/${config.projectGuid}/records/${table}`, data);
+    const res = await api.post(`/api/${api.guid}/records/${table}`, data);
     printResult(`Created: ${JSON.stringify(res.data)}`, opts, res.data);
 }));
 recordsCommand
     .command('update <table> <id>')
     .description('Update a record')
     .requiredOption('--data <json>', 'JSON object with fields to update')
+    .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, id, opts) => run('Update', async () => {
-    const config = requireConfig();
+    const api = await recordsHttp(opts);
     const data = JSON.parse(opts.data);
-    const res = await put(`/api/${config.projectGuid}/records/${table}/${id}`, data);
+    const res = await api.put(`/api/${api.guid}/records/${table}/${id}`, data);
     printResult(`Updated: ${JSON.stringify(res.data)}`, opts, res.data);
 }));
+// A table that declares `soft_delete_column` only STAMPS the row on delete - it
+// stays queryable via `query --only-deleted` and keeps its audit history. That's
+// right for user data and wrong for a probe row you just minted to test the
+// wiring, so `--purge` (the server's ?purge=1) is the one call that really
+// removes it. The plain success line says which of the two happened and names
+// the escape hatch, so nobody has to go spelunking through gipity.js to find it.
 recordsCommand
     .command('delete <table> <id>')
-    .description('Delete a record')
-    .action((table, id) => run('Delete', async () => {
-    if (!await confirm(`Delete record ${id} from "${table}"?`)) {
-        console.log('Cancelled.');
+    .description('Delete a record (soft-delete when the table declares one; --purge removes it for good)')
+    .option('--purge', 'Hard-delete: remove the row AND erase its audit history (owner/editor). Use it to scrub probe rows.')
+    .option(ANON_FLAG, ANON_HELP)
+    .option('--json', 'Output as JSON')
+    .action((table, id, opts) => run('Delete', async () => {
+    const what = opts.purge ? `Purge record ${id} from "${table}" (also erases its history)?` : `Delete record ${id} from "${table}"?`;
+    if (!await confirm(what)) {
+        printResult('Cancelled.', opts, { table, id, deleted: false, cancelled: true });
         return;
     }
-    const config = requireConfig();
-    await del(`/api/${config.projectGuid}/records/${table}/${id}`);
-    printResult('Deleted.', { json: false });
+    const api = await recordsHttp(opts);
+    const res = await api.del(`/api/${api.guid}/records/${table}/${id}${opts.purge ? '?purge=1' : ''}`);
+    const data = res?.data ?? { table, id, deleted: true, purged: !!opts.purge };
+    printResult(data.purged
+        ? 'Purged - the row and its audit history are gone.'
+        : `Deleted. If "${table}" declares a soft-delete column the row is only stamped deleted (see it with \`gipity records query ${table} --only-deleted\`, bring it back with \`gipity records restore ${table} ${id}\`, remove it for good with \`--purge\`).`, opts, data);
+}));
+recordsCommand
+    .command('restore <table> <id>')
+    .description('Un-delete a soft-deleted record (owner/editor)')
+    .option('--json', 'Output as JSON')
+    .action((table, id, opts) => run('Restore', async () => {
+    const api = await recordsHttp(opts);
+    const res = await api.post(`/api/${api.guid}/records/${table}/${id}/restore`);
+    printResult('Restored.', opts, res?.data ?? { table, id, restored: true });
 }));
 //# sourceMappingURL=records.js.map

package/dist/commands/service.js

@@ -1,8 +1,9 @@
 import { Command } from 'commander';
-import { get, post } from '../api.js';
+import { get, post, publicRequest, mintAppToken, ApiError } from '../api.js';
+import { getAuth } from '../auth.js';
 import { requireConfig } from '../config.js';
 import { bold, muted } from '../colors.js';
-import { run } from '../helpers/index.js';
+import { run, emitField, resolveBody } from '../helpers/index.js';
 /** Known app-service endpoints, shown by `gipity service list` and used to
  *  give a helpful hint on typos. POST endpoints take a JSON body; GET
  *  endpoints (model/voice listings) are reached with `--get`. */
@@ -35,16 +36,41 @@ serviceCommand
     const width = SERVICES.reduce((m, s) => Math.max(m, s.name.length), 0);
     console.log('Call one with `gipity service call <name> \'{"json":"body"}\'`');
     console.log(muted('(GET endpoints like llm/models, tts/voices take --get and no body)'));
+    console.log(muted('Verifying what a signed-out visitor of your deployed app gets? Add --anon.'));
     console.log('');
     for (const s of SERVICES) {
         console.log(`${bold(s.name.padEnd(width))}  ${muted(`[${s.method}] ${s.desc}`)}`);
     }
 }));
+/** A signed-out visitor's 401 on a service is almost never "the caller needs to
+ *  log in" — it is the app's service `billing_mode` still on the `user_pays`
+ *  default, which asks every anonymous visitor of a PUBLIC page to sign in and
+ *  pay from their own credits. The server's raw body says LOGIN_REQUIRED and
+ *  nothing about the manifest, so the fix costs a doc hunt across skills. Name
+ *  the cause and the exact edit here, at the moment it happens. */
+export function anonBillingHint(name, err) {
+    if (!(err instanceof ApiError) || err.statusCode !== 401)
+        return null;
+    // Only the "sign in to use this" refusal is a billing-mode symptom. A missing
+    // credential (the visitor token never minted) is a different failure with a
+    // different fix, and must not be dressed up as one.
+    if (err.code !== 'LOGIN_REQUIRED')
+        return null;
+    const service = name.split('/')[0];
+    return (`An anonymous visitor cannot call '${service}': it is on the user_pays default, so every signed-out ` +
+        `visitor to a public page is asked to sign in and pay from their own credits. If this app serves the ` +
+        `public (a help bubble, a landing page), switch it to owner-pays in gipity.yaml and redeploy:\n` +
+        `  deploy:\n    phases:\n      - services\n  service_definitions:\n    - service: ${service}\n      billing_mode: owner_pays\n` +
+        `  gipity deploy dev --only services`);
+}
 serviceCommand
     .command('call <name> [body]')
-    .description('Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling.')
-    .option('--data <json>', 'JSON request body (alternative to the positional [body])')
+    .description('Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling; --anon calls it as a signed-out visitor instead.')
+    .option('-d, --data <json>', 'JSON request body: inline JSON, @file to read a file, or @- / - for stdin (alternative to the positional [body])')
+    .option('--file <field=@path>', 'Attach a file as { data, media_type } under <field> (the vision/media shape these services expect), repeatable, e.g. --file image=@receipt.png', (v, acc) => (acc || []).concat(v))
+    .option('--anon', 'Call as an anonymous visitor (the public path a signed-out user of your deployed app hits) instead of as your signed-in account')
     .option('--get', 'Issue a GET (for listing endpoints like llm/models, tts/voices)')
+    .option('--field <path>', 'Print only this field of the result (dot path, e.g. choices.0.message.content)')
     .option('--json', 'Output compact JSON')
     .action((name, bodyArg, opts) => run('Call', async () => {
     const config = requireConfig();
@@ -52,9 +78,47 @@ serviceCommand
     // like `location/geocode` and `llm/models` resolve correctly.
     const path = name.split('/').map(encodeURIComponent).join('/');
     const url = `/api/${config.projectGuid}/services/${path}`;
-    const res = opts.get
-        ? await get(url)
-        : await post(url, JSON.parse(bodyArg || opts.data || '{}'));
+    const body = resolveBody(bodyArg || opts.data, opts.file);
+    // Name the calling identity (stderr, so stdout stays parseable). An owner
+    // call always succeeds regardless of billing mode, so without this line a
+    // "the service works" verification silently proves nothing about the
+    // visitors the deployed app actually serves.
+    if (opts.anon) {
+        console.error(muted('Auth: anonymous visitor (the public path a signed-out user of your deployed app hits)'));
+    }
+    else {
+        const who = getAuth()?.email;
+        console.error(muted(`Auth: calling as ${who ?? 'your signed-in account'} (the owner persona - always billed to you and never blocked by billing_mode; use --anon for the public visitor path)`));
+    }
+    let res;
+    try {
+        if (opts.anon) {
+            // The short-lived app token IS the visitor's credential here (unlike a
+            // public function, a service is never callable with no token at all).
+            // If it can't be minted, say so — otherwise the request comes back as a
+            // bare 401 that reads like an app-permissions problem.
+            const headers = await mintAppToken(config.projectGuid);
+            if (!headers) {
+                throw new Error(`Could not mint a visitor token for this project, so there is no anonymous path to call. ` +
+                    `That means the app is not deployed on this API base yet: run \`gipity deploy dev\` first, ` +
+                    `then re-run this command.`);
+            }
+            res = await publicRequest(opts.get ? 'GET' : 'POST', url, opts.get ? undefined : body, headers);
+        }
+        else {
+            res = opts.get ? await get(url) : await post(url, body);
+        }
+    }
+    catch (err) {
+        const hint = opts.anon ? anonBillingHint(name, err) : null;
+        if (!hint)
+            throw err;
+        throw new Error(`${err.message}\n${hint}`);
+    }
+    if (opts.field) {
+        emitField(res, opts.field);
+        return;
+    }
     console.log(opts.json ? JSON.stringify(res) : JSON.stringify(res, null, 2));
 }));
 //# sourceMappingURL=service.js.map

package/dist/commands/token.js

@@ -4,7 +4,12 @@ import { bold, muted, success, warning } from '../colors.js';
 import { run, printList } from '../helpers/index.js';
 export const tokenCommand = new Command('token')
     .description('Manage API tokens')
-    .addHelpText('after', '\nLong-lived agent API tokens (gip_at_*) for headless agents and CI.');
+    .addHelpText('after', `
+Long-lived agent API tokens (gip_at_*) for headless agents and CI - they drive
+the gipity CLI as YOU.
+
+To let a script or cron write to one app instead, mint a project API key:
+gipity key create "my script" --role editor (sent as X-Api-Key).`);
 const fmtDate = (d) => (d ? new Date(d).toLocaleDateString() : 'never');
 tokenCommand
     .command('create')

package/dist/commands/uninstall.js

@@ -19,7 +19,7 @@ import { confirm, getAutoConfirm } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as relayState from '../relay/state.js';
 import { planFor, UnsupportedPlatformError } from '../relay/installers.js';
-import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, stripGipityHooks, grokInstallState, agentSkillsState, AGENTS_SKILLS_DIR } from '../setup.js';
+import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, stripGipityHooks, grokInstallState, agentSkillsState, AGENTS_SKILLS_DIR, agySkillsState, AGY_SKILLS_DIR, } from '../setup.js';
 /** Remove Gipity's entries from the user-scope Claude Code settings: the
  *  plugin enablement, the marketplace registration, and any legacy hook
  *  blocks older CLI versions wrote there. Surgical - everything else in the
@@ -240,6 +240,19 @@ export const uninstallCommand = new Command('uninstall')
         }
         console.log(`${success(`Removed ${agentSkills.skills.length} Gipity skills from ~/.agents/skills.`)}`);
     }
+    // 4c. Remove the skills the CLI copied into Antigravity's own global
+    //     skill root (~/.gemini/config/skills - a different directory from
+    //     Codex's ~/.agents/skills, see setup.ts).
+    const agySkills = agySkillsState();
+    if (agySkills.skills.length) {
+        for (const name of agySkills.skills) {
+            try {
+                rmSync(join(AGY_SKILLS_DIR, name), { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        console.log(`${success(`Removed ${agySkills.skills.length} Gipity skills from ~/.gemini/config/skills.`)}`);
+    }
     // 5. Wipe ~/.gipity/ (this also removes the agent-hooks scripts and the
     //    agent-skills manifest, which live under it).
     if (existsSync(gipityDir)) {