gipity 1.0.387 → 1.0.388

package/README.md

@@ -8,27 +8,33 @@ This CLI connects [Claude Code](https://claude.ai/claude-code) to Gipity's cloud
 
 ## Getting Started
 
-You need **Node.js 18+** (which includes npm) and **Claude Code**.
+One line installs everything. It sets up Node 18+ (if you don't already have it) and the Gipity CLI, with no sudo required:
 
 ```bash
-# 1. Install Node.js (if you don't have it)
+# macOS / Linux / WSL
+curl -fsSL https://gipity.ai/install.sh | bash
 
-# macOS
-brew install node
+# Windows (PowerShell)
+irm https://gipity.ai/install.ps1 | iex
+```
+
+Then launch your coding agent wired into Gipity:
+
+```bash
+gipity claude
+```
 
-# Windows - download the installer from https://nodejs.org
+`gipity claude` walks you through login, project setup, and launches Claude Code. Using Codex, Gemini, or Cursor instead? Run `gipity init`.
 
-# Linux (Ubuntu/Debian)
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
+### Prefer npm
 
-# 2. Install Gipity CLI and Claude Code
-npm install -g gipity @anthropic-ai/claude-code
+If you already have **Node.js 18+** you can install directly:
 
-# 3. Go
-gipity claude
+```bash
+npm install -g gipity
 ```
 
-That's it. `claude` walks you through login, project setup, and launches Claude Code.
+If that fails with `EACCES`, your npm global prefix is root-owned. Don't reach for `sudo`: point npm at a user-owned prefix instead (`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to your `PATH`), or just use the one-line installer above, which does this for you. See https://docs.npmjs.com/resolving-eacces-permissions-errors.
 
 ## Updates
 

package/dist/banner.js

@@ -1,6 +1,6 @@
 // ── Gipity CLI Startup Banner ──────────────────────────────────────────
 // Two-panel box showing all AI models, platform tools, and sandbox capabilities.
-import { brand, bold, faint, muted } from './colors.js';
+import { brand, bold, faint, muted, fg } from './colors.js';
 // ── Static content ─────────────────────────────────────────────────────
 // ── Feature groups ────────────────────────────────────────────────────
 const AI_MODELS = [
@@ -38,11 +38,13 @@ const INFRASTRUCTURE = [
     'Deploy', 'Uploads', 'Rollback',
 ];
 // ── Egg color palette (shared) - gradient built around #FEA60E ───────
-const _hi = (s) => `\x1b[38;2;255;215;80m${s}\x1b[39m`; // golden highlight
-const _lt = (s) => `\x1b[38;2;254;190;45m${s}\x1b[39m`; // light
-const _br = (s) => `\x1b[38;2;254;166;14m${s}\x1b[39m`; // base - #FEA60E
-const _md = (s) => `\x1b[38;2;218;112;8m${s}\x1b[39m`; // medium-dark
-const _sh = (s) => `\x1b[38;2;170;68;4m${s}\x1b[39m`; // shadow
+// Colors route through fg() so they downgrade (256 / 16 / none) on terminals
+// without truecolor support instead of rendering as misparsed garbage.
+const _hi = fg(255, 215, 80); // golden highlight
+const _lt = fg(254, 190, 45); // light
+const _br = fg(254, 166, 14); // base - #FEA60E
+const _md = fg(218, 112, 8); // medium-dark
+const _sh = fg(170, 68, 4); // shadow
 // Wobbly egg - asymmetric left/right, organic feel (8 rows)
 // Widths: 6 → 8 → 10 → 12 → 14 → 12 → 10 → 8  |  Widest at row 5/8 (62%)
 function eggWobbly() {
@@ -76,8 +78,8 @@ function eggSym() {
 // Edge pairs: ▗/▖ cap → ▟/▙ expand → ▐/▌ straight → ▜/▛ contract → ▝/▘ cap
 function eggTall() {
     // Extra intermediate tones for a smoother gradient
-    const _m1 = (s) => `\x1b[38;2;238;138;10m${s}\x1b[39m`; // base → medium
-    const _dk = (s) => `\x1b[38;2;195;88;6m${s}\x1b[39m`; // medium → shadow
+    const _m1 = fg(238, 138, 10); // base to medium
+    const _dk = fg(195, 88, 6); // medium to shadow
     return [
         _lt('▗▄') + _br('██') + _md('▄▖'), //  6 - top cap
         _lt('▟') + _hi('█') + _br('████') + _m1('█▙'), //  8 - expanding, highlight
@@ -161,7 +163,7 @@ function buildLeftPanel(opts, panelW) {
     const nameDisplay = opts.email
         ? opts.email.split('@')[0].replace(/^./, c => c.toUpperCase())
         : null;
-    const white = (s) => `\x1b[38;2;255;255;255m${s}\x1b[39m`;
+    const white = fg(255, 255, 255);
     const welcome = nameDisplay
         ? white(bold(`Welcome back ${nameDisplay}!`))
         : white(bold('Welcome to Gipity'));

package/dist/colors.js

@@ -1,27 +1,127 @@
 // ── Gipity CLI Color System ─────────────────────────────────────────────
 // Centralized color definitions matching the Gipity platform palette.
 // All command files should import from here - no inline ANSI codes.
+//
+// Color depth is detected once at load. RGB colors automatically downgrade:
+//   level 3 → 24-bit truecolor   \x1b[38;2;R;G;Bm
+//   level 2 → 256-color          \x1b[38;5;Nm
+//   level 1 → 16-color           \x1b[3Xm / \x1b[9Xm
+//   level 0 → no color (plain text)
+// This avoids the failure mode where a terminal that does not understand the
+// 24-bit escape misparses it and renders garbage (e.g. the orange egg coming
+// out purple on consoles without truecolor support).
 const ESC = '\x1b';
-// Detect whether colors should be suppressed
-const noColor = !!process.env['NO_COLOR'] || !process.stdout.isTTY;
+// ── Color-depth detection ───────────────────────────────────────────────
+// 0 = none, 1 = 16-color, 2 = 256-color, 3 = truecolor. Mirrors the common
+// supports-color / chalk heuristics, biased toward NOT emitting truecolor
+// unless the terminal advertises it, so unknown terminals get a safe 256 or
+// 16-color approximation instead of a misparsed 24-bit sequence.
+function detectColorLevel() {
+    if (process.env['NO_COLOR'])
+        return 0;
+    // FORCE_COLOR overrides detection (matches Node / chalk semantics).
+    const force = process.env['FORCE_COLOR'];
+    if (force !== undefined) {
+        if (force === '0' || force === 'false')
+            return 0;
+        if (force === '3')
+            return 3;
+        if (force === '2')
+            return 2;
+        // '1', 'true', '' → at least basic color
+        if (force === '1' || force === 'true' || force === '')
+            return 1;
+    }
+    if (!process.stdout.isTTY)
+        return 0;
+    const term = (process.env['TERM'] || '').toLowerCase();
+    if (term === 'dumb')
+        return 0;
+    const colorterm = (process.env['COLORTERM'] || '').toLowerCase();
+    if (colorterm === 'truecolor' || colorterm === '24bit')
+        return 3;
+    const termProgram = process.env['TERM_PROGRAM'] || '';
+    if (termProgram === 'iTerm.app' || termProgram === 'vscode')
+        return 3;
+    if (termProgram === 'Apple_Terminal')
+        return 2;
+    if (/-256(color)?$/.test(term) || term.includes('256'))
+        return 2;
+    // Modern Windows consoles set COLORTERM (caught above). Older cmd.exe /
+    // conhost only do 16-color reliably.
+    if (process.platform === 'win32')
+        return 1;
+    if (term)
+        return 1;
+    return 0;
+}
+const COLOR_LEVEL = detectColorLevel();
 // Identity function for when colors are disabled
 const identity = (s) => s;
+// ── RGB downgrade helpers ───────────────────────────────────────────────
+// RGB → nearest xterm-256 palette index (6x6x6 cube + grayscale ramp).
+function rgbTo256(r, g, b) {
+    if (r === g && g === b) {
+        if (r < 8)
+            return 16;
+        if (r > 248)
+            return 231;
+        return Math.round(((r - 8) / 247) * 24) + 232;
+    }
+    return (16 +
+        36 * Math.round((r / 255) * 5) +
+        6 * Math.round((g / 255) * 5) +
+        Math.round((b / 255) * 5));
+}
+// RGB → nearest 16-color SGR foreground code (30-37 / 90-97).
+function rgbTo16(r, g, b) {
+    const value = Math.round((Math.max(r, g, b) / 255) * 3);
+    if (value === 0)
+        return 30;
+    let code = 30 +
+        ((Math.round(b / 255) << 2) |
+            (Math.round(g / 255) << 1) |
+            Math.round(r / 255));
+    if (value === 3)
+        code += 60; // bright variant
+    return code;
+}
 // ── Low-level builders ──────────────────────────────────────────────────
-function makeFg(r, g, b) {
-    if (noColor)
+export function makeFg(r, g, b) {
+    if (COLOR_LEVEL === 0)
         return identity;
-    return (s) => `${ESC}[38;2;${r};${g};${b}m${s}${ESC}[39m`;
+    if (COLOR_LEVEL === 3) {
+        return (s) => `${ESC}[38;2;${r};${g};${b}m${s}${ESC}[39m`;
+    }
+    if (COLOR_LEVEL === 2) {
+        const n = rgbTo256(r, g, b);
+        return (s) => `${ESC}[38;5;${n}m${s}${ESC}[39m`;
+    }
+    const code = rgbTo16(r, g, b);
+    return (s) => `${ESC}[${code}m${s}${ESC}[39m`;
 }
-function makeBg(r, g, b) {
-    if (noColor)
+export function makeBg(r, g, b) {
+    if (COLOR_LEVEL === 0)
         return identity;
-    return (s) => `${ESC}[48;2;${r};${g};${b}m${s}${ESC}[49m`;
+    if (COLOR_LEVEL === 3) {
+        return (s) => `${ESC}[48;2;${r};${g};${b}m${s}${ESC}[49m`;
+    }
+    if (COLOR_LEVEL === 2) {
+        const n = rgbTo256(r, g, b);
+        return (s) => `${ESC}[48;5;${n}m${s}${ESC}[49m`;
+    }
+    const code = rgbTo16(r, g, b) + 10; // fg 30-97 → bg 40-107
+    return (s) => `${ESC}[${code}m${s}${ESC}[49m`;
 }
 function makeStyle(open, close) {
-    if (noColor)
+    if (COLOR_LEVEL === 0)
         return identity;
     return (s) => `${ESC}[${open}m${s}${ESC}[${close}m`;
 }
+// Convenience alias for callers that just want an RGB foreground (e.g. banner).
+export const fg = makeFg;
+// The detected level, exported for callers that want to branch on it.
+export const colorLevel = COLOR_LEVEL;
 // ── Text style helpers ──────────────────────────────────────────────────
 export const bold = makeStyle(1, 22);
 export const dim = makeStyle(2, 22);

package/dist/commands/approval.js

@@ -58,11 +58,21 @@ approvalCommand
 approvalCommand
     .command('answer <guid> [selection...]')
     .description('Answer an approval: a = approve, b = deny, c = ignore, or free text for text-type')
+    .option('--deny', 'Resolve as denied; any trailing text is sent as feedback (e.g. requested edits)')
     .option('--json', 'Output as JSON')
     .action((guid, selectionParts, opts) => run('Answer', async () => {
     if (!guid.startsWith('ap_')) {
         throw new Error('Expected approval guid like ap_xxxxxxxx');
     }
+    // Deny with optional free-text feedback works for every response type -
+    // it's how a workflow gate's revision loop gets the user's edits
+    // ({{gate.action}} == rejected + {{gate.human_response}}).
+    if (opts.deny) {
+        const feedback = selectionParts.join(' ').trim();
+        await post(`/approvals/${guid}/resolve`, { status: 'denied', response: feedback || undefined });
+        printResult(`Denied${feedback ? `: ${feedback}` : '.'}`, opts, { guid, status: 'denied' });
+        return;
+    }
     const detailRes = await get(`/approvals/${guid}`);
     const detail = detailRes.data;
     const first = selectionParts[0];

package/dist/commands/claude.js

@@ -219,6 +219,10 @@ export const claudeCommand = new Command('claude')
     .option('--project <slug>', 'Open an existing project by slug or id')
     .option('--here', 'Use the current directory instead of ~/GipityProjects/<slug>/')
     .option('--quiet', "Suppress Claude's live progress output (headless --new-project/--project runs)")
+    // Forwarded to `claude` via the unknown-arg passthrough below (NOT in the
+    // gipity strip lists). Declared here only so it shows up in --help — without
+    // this, callers can't discover that the session model is selectable.
+    .option('--model <model>', 'Model for the Claude session, forwarded to claude (e.g. sonnet, opus, or a full id like claude-sonnet-4-6)')
     .allowUnknownOption(true)
     .allowExcessArguments(true)
     .action(async (opts) => {

package/dist/commands/fn.js

@@ -1,8 +1,9 @@
 import { Command } from 'commander';
-import { get, post } from '../api.js';
+import { get, post, del } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, bold, muted, success } from '../colors.js';
 import { run, printList } from '../helpers/index.js';
+import { confirm } from '../utils.js';
 export const fnCommand = new Command('fn')
     .description('Manage functions');
 fnCommand
@@ -45,4 +46,24 @@ fnCommand
     const res = await post(`/api/${config.projectGuid}/fn/${encodeURIComponent(name)}`, body);
     console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
 }));
+fnCommand
+    .command('delete <name>')
+    .alias('rm')
+    .description('Delete a function')
+    .option('--yes', 'Skip confirmation')
+    .option('--json', 'Output as JSON')
+    .action((name, opts) => run('Delete', async () => {
+    const config = requireConfig();
+    if (!await confirm(`Delete function '${name}'? This cannot be undone.`, { skip: opts.yes })) {
+        console.log('Cancelled.');
+        return;
+    }
+    await del(`/projects/${config.projectGuid}/functions/${encodeURIComponent(name)}`);
+    if (opts.json) {
+        console.log(JSON.stringify({ name, deleted: true }));
+    }
+    else {
+        console.log(success(`Deleted function '${name}'.`));
+    }
+}));
 //# sourceMappingURL=fn.js.map

package/dist/commands/skill.js

@@ -1,8 +1,21 @@
 import { Command } from 'commander';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
 import { get } from '../api.js';
-import { resolveProjectContext } from '../config.js';
+import { resolveProjectContext, getProjectRoot } from '../config.js';
 import { error as clrError, bold, muted } from '../colors.js';
 import { run, printList } from '../helpers/index.js';
+/** Many kits ship a README but no skill doc. When `skill read <name>` misses
+ *  the server catalog, fall back to an installed kit's README so the canonical
+ *  lookup doesn't dead-end. Returns the README text, or null if no such kit. */
+function readInstalledKitReadme(name) {
+    const root = getProjectRoot() ?? process.cwd();
+    const kitDir = join(root, 'src', 'packages', name);
+    if (!existsSync(join(kitDir, 'package.json')))
+        return null;
+    const readme = join(kitDir, 'README.md');
+    return existsSync(readme) ? readFileSync(readme, 'utf-8') : null;
+}
 export const skillCommand = new Command('skill')
     .description('Read platform docs');
 skillCommand
@@ -32,6 +45,19 @@ skillCommand
     const listRes = await get(`/skills?agent=${config.agentGuid}`);
     const match = listRes.data.find(s => s.name.toLowerCase() === name.toLowerCase());
     if (!match) {
+        // No catalog skill — but if a kit by this name is installed, its README is
+        // the guidance the agent is after. Surface it instead of dead-ending.
+        const readme = readInstalledKitReadme(name);
+        if (readme) {
+            if (opts.json) {
+                console.log(JSON.stringify({ name, source: 'kit-readme', content: readme }, null, 2));
+            }
+            else {
+                console.log(muted(`No skill doc for "${name}"; showing the installed kit's README (src/packages/${name}/README.md):\n`));
+                console.log(readme);
+            }
+            return;
+        }
         console.error(clrError(`Skill "${name}" not found. Run: gipity skill list`));
         process.exit(1);
     }

package/dist/commands/test.js

@@ -3,6 +3,9 @@ import { get, post } from '../api.js';
 import { requireConfig } from '../config.js';
 import { success, error as clrError, warning, muted, bold, dim } from '../colors.js';
 import { run, syncBeforeAction } from '../helpers/index.js';
+// Absolute poll ceiling - the server reaps stalled runs (~65 min) well before
+// this, so hitting it means even the reaper is unreachable.
+const POLL_HARD_CAP_MS = 75 * 60_000;
 function statusIcon(status) {
     if (status === 'passed')
         return success('✓');
@@ -42,6 +45,9 @@ async function pollTestStatus(projectGuid, runGuid, opts) {
     let lastHeartbeat = 0; // 0 => emit the first heartbeat immediately (non-TTY)
     let longRunHintShown = false;
     while (true) {
+        if (Date.now() - startTime > POLL_HARD_CAP_MS) {
+            throw new Error(`Test run ${runGuid} still not finished after ${Math.round(POLL_HARD_CAP_MS / 60000)} minutes - giving up on the poll. Check it later with \`gipity test status ${runGuid}\` or re-run.`);
+        }
         const res = await get(`/projects/${projectGuid}/test/status/${runGuid}`);
         const data = res.data;
         // Show progress for new results (non-JSON mode)
@@ -162,6 +168,10 @@ export const testCommand = new Command('test')
         console.log(clrError(`No tests matched filter: ${filterPath}`));
         process.exit(1);
     }
+    if (data.status === 'failed' && data.errorMessage) {
+        console.log(clrError(`Run failed: ${data.errorMessage}`));
+        console.log('');
+    }
     // Summary
     const parts = [];
     if (data.passed > 0)

package/dist/commands/workflow.js

@@ -29,6 +29,35 @@ function formatRunLine(r) {
     const statusColor = r.status === 'completed' ? success : r.status === 'failed' ? clrError : muted;
     return `${muted(r.short_guid)}  ${statusColor(r.status)}  ${dur}  ${runTokens(r)} tokens  ${muted(fmtTime(r.started_at))}`;
 }
+const TERMINAL_RUN_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * Poll a workflow's runs until the run triggered after `prevGuid` reaches a
+ * terminal state, returning it. Throws on timeout so the `run()` wrapper reports
+ * it. Two phases: wait for the new run row to appear, then poll it to terminal.
+ */
+async function waitForRun(wfGuid, prevGuid, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    let runGuid;
+    while (!runGuid) {
+        if (Date.now() > deadline)
+            throw new Error(`Timed out after ${timeoutSec}s waiting for the run to start.`);
+        const latest = await get(`/workflows/${wfGuid}/runs?limit=1`);
+        const g = latest.data[0]?.short_guid;
+        if (g && g !== prevGuid)
+            runGuid = g;
+        else
+            await sleep(1500);
+    }
+    while (true) {
+        const res = await get(`/workflows/${wfGuid}/runs/${runGuid}`);
+        if (TERMINAL_RUN_STATUSES.has(res.data.status))
+            return res.data;
+        if (Date.now() > deadline)
+            throw new Error(`Timed out after ${timeoutSec}s; run ${runGuid} is still ${res.data.status}. Check: gipity workflow runs ${wfGuid} ${runGuid}`);
+        await sleep(2000);
+    }
+}
 async function listWorkflows(opts) {
     const res = await get('/workflows');
     if (opts.json) {
@@ -73,6 +102,8 @@ workflowCommand
         console.log(`GUID:    ${w.short_guid}`);
         console.log(`Active:  ${w.is_active ? 'yes' : 'no'}`);
         console.log(`Trigger: ${w.trigger_type}${w.cron_expression ? ` (${w.cron_expression})` : ''}${w.trigger_table ? ` (table: ${w.trigger_table})` : ''}`);
+        if (w.webhook_url)
+            console.log(`Webhook: ${w.webhook_url}`);
         if (w.description)
             console.log(`Desc:    ${w.description}`);
         if (w.steps && w.steps.length > 0) {
@@ -85,13 +116,36 @@ workflowCommand
 }));
 workflowCommand
     .command('run <name>')
-    .description('Trigger a workflow')
+    .description('Trigger a workflow (add --wait to block until it finishes)')
     .option('--json', 'Output as JSON')
+    .option('--wait', 'Block until the triggered run reaches a terminal state, then print it')
+    .option('--timeout <s>', 'Max seconds to wait with --wait', '120')
     .action((name, _opts, cmd) => run('Run', async () => {
     const opts = mergedOpts(cmd);
     const wf = await resolveWorkflow(name);
-    const res = await post(`/workflows/${wf.short_guid}/run`, {});
-    printResult(`Triggered "${wf.name}".`, opts, res.data);
+    if (!opts.wait) {
+        const res = await post(`/workflows/${wf.short_guid}/run`, {});
+        printResult(`Triggered "${wf.name}".`, opts, res.data);
+        return;
+    }
+    // The trigger endpoint is fire-and-forget — it returns the workflow guid,
+    // not a run guid (the run row is created asynchronously inside the executor).
+    // So capture the latest run guid BEFORE triggering, then wait for a newer one
+    // to appear and poll it to a terminal state. Avoids matching a concurrent run.
+    const before = await get(`/workflows/${wf.short_guid}/runs?limit=1`);
+    const prevGuid = before.data[0]?.short_guid;
+    await post(`/workflows/${wf.short_guid}/run`, {});
+    const r = await waitForRun(wf.short_guid, prevGuid, Number(opts.timeout) || 120);
+    if (opts.json) {
+        console.log(JSON.stringify(r));
+    }
+    else {
+        console.log(formatRunLine(r));
+        if (r.error_message)
+            console.log(`  ${clrError(r.error_message)}`);
+    }
+    if (r.status !== 'completed')
+        process.exit(1);
 }));
 workflowCommand
     .command('runs <name> [runGuid]')

package/dist/config.js

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { dirname, resolve } from 'path';
+import ignore from 'ignore';
 const CONFIG_FILE = '.gipity.json';
 export const DEFAULT_API_BASE = 'https://a.gipity.ai';
 let cached = null;
@@ -211,23 +212,31 @@ export function saveConfigAt(dir, data) {
     cached = data;
     cachedPath = path;
 }
+/** Compiled matchers cached by their pattern set so the per-file `shouldIgnore`
+ *  call in the sync loop doesn't rebuild the matcher every time. */
+const ignoreMatcherCache = new Map();
+/**
+ * True if filePath (a POSIX-relative path under the project root) is excluded
+ * by the given .gipityignore / config ignore patterns. Uses real gitignore
+ * semantics via the "ignore" package, so all documented forms work: bare names
+ * match in any directory (node_modules), a trailing slash means directory
+ * (.gipity/), star-dot matches any depth (*.log), and the previously
+ * unsupported forms (data/*.csv, anchored /build, double-star, and negation
+ * with a leading bang) now behave as users expect.
+ */
 export function shouldIgnore(filePath, ignorePatterns) {
-    for (const pattern of ignorePatterns) {
-        // Simple glob matching: exact match, prefix match, or extension match
-        if (filePath === pattern)
-            return true;
-        if (filePath.startsWith(pattern + '/'))
-            return true;
-        if (pattern.startsWith('*.') && filePath.endsWith(pattern.slice(1)))
-            return true;
-        if (pattern.endsWith('/') && filePath.startsWith(pattern))
-            return true;
-        // Directory name match anywhere in path
-        if (!pattern.includes('*') && !pattern.includes('/')) {
-            if (filePath.split('/').includes(pattern))
-                return true;
-        }
+    if (ignorePatterns.length === 0)
+        return false;
+    const key = ignorePatterns.join('\n');
+    let matcher = ignoreMatcherCache.get(key);
+    if (!matcher) {
+        matcher = ignore().add(ignorePatterns);
+        ignoreMatcherCache.set(key, matcher);
     }
-    return false;
+    // `ignore` wants a clean relative path; it rejects absolute paths and '.'.
+    const rel = filePath.replace(/^\.\//, '').replace(/\/+$/, '');
+    if (!rel || rel === '.')
+        return false;
+    return matcher.ignores(rel);
 }
 //# sourceMappingURL=config.js.map

package/dist/index.js

@@ -216,10 +216,17 @@ function enableHelpAfterError(cmd) {
         enableHelpAfterError(sub);
 }
 enableHelpAfterError(program);
-// Auto-fetch related skill docs when --help is run on mapped commands
+// Auto-fetch related skill docs when --help is run on a doc-bearing TOP-LEVEL
+// command (e.g. `gipity fn --help`, `gipity db --help`). It must NOT fire for a
+// subcommand's help: `gipity db query --help` should render commander's own
+// usage for `db query`, not the parent's help plus a skill doc. So only trigger
+// when the first token is a mapped command and nothing after it is a subcommand
+// (every remaining token is a flag).
 const argv = process.argv.slice(2);
 const hasHelp = argv.includes('--help') || argv.includes('-h');
-const mappedCmd = hasHelp ? argv.find(a => a in HELP_SKILL_MAP) : undefined;
+const topCmd = argv[0];
+const targetsTopCmdOnly = argv.slice(1).every(a => a.startsWith('-'));
+const mappedCmd = hasHelp && targetsTopCmdOnly && topCmd in HELP_SKILL_MAP ? topCmd : undefined;
 if (mappedCmd) {
     const cmdObj = program.commands.find(c => c.name() === mappedCmd);
     if (cmdObj) {

package/dist/knowledge.js

@@ -92,6 +92,8 @@ Run \`gipity --help\` for the full list. Use \`--help\` on any command for detai
 
 Function return shape: \`gipity fn call\`, the in-test \`ctx.fn.call\`/\`callAs\`, and the client \`Gipity.fn\` all return your function's value **unwrapped** — read/assert \`result.field\`. Only raw HTTP/\`curl\` wraps it as \`{ data: ... }\`; never write \`result.data.field\` in a test.
 
+Tests write to your real DB: \`gipity test\` runs the test code sandboxed, but \`ctx.fn.call\`/\`callAs\` hit your actual deployed functions, which write to the same project database the app reads from — rows a test creates persist and surface on the live page. Register \`ctx.cleanup(fn)\` in any write-test to delete what it made; the harness runs every cleanup after the suite (even on failure).
+
 ## Tool output is complete and synchronous
 
 Every tool call returns its full output with that call. There is no output buffer to flush. Never run no-op commands (echo, date, sleep, repeated reads) to "retrieve" or "flush" lagged output - if a result looks empty or delayed, treat it as the actual result and move on, or re-run the real command once.
@@ -130,6 +132,7 @@ App development skills:
 
 Kit skills (reusable building blocks - \`gipity add <kit>\`):
 - \`audio-align\` - the audio-align kit: forced alignment of audio + lyrics into word-level timing JSON
+- \`chatbot\` - the chatbot kit: persona + scope guardrails + static knowledge, bubble widget or headless engine
 
 Other key skills:
 - \`sandbox-tools\` - cloud sandbox capabilities and pre-installed tools

package/dist/sync.js

@@ -27,7 +27,7 @@ import { hostname } from 'os';
 import { get, del, downloadStream, ApiError } from './api.js';
 import { requireConfig, shouldIgnore, getConfigPath } from './config.js';
 import { formatSize, prompt, getAutoConfirm } from './utils.js';
-import { uploadOneFile, hashFile, UploadConflictError } from './upload.js';
+import { uploadOneFile, hashFile, guessMime, transferToS3, uploadInitBatch, uploadCompleteBatch, UploadConflictError, UPLOAD_CONCURRENCY, UPLOAD_INIT_BATCH_SIZE, UPLOAD_MAX_BYTES, UPLOAD_MAX_PATH_CHARS, } from './upload.js';
 import { DEFAULT_SYNC_IGNORE } from './setup.js';
 const CONFIG_FILE = '.gipity.json';
 import * as tar from 'tar-stream';
@@ -38,7 +38,6 @@ import * as tar from 'tar-stream';
  *  project probably are intentional. */
 const BULK_DELETE_COUNT = 10;
 const BULK_DELETE_FRACTION = 0.25;
-const UPLOAD_CONCURRENCY = 4;
 // ─── Paths ─────────────────────────────────────────────────────
 function syncStatePath() {
     const configPath = getConfigPath();
@@ -497,20 +496,6 @@ async function bulkDeleteGuard(p, knownFiles, opts) {
     const answer = await prompt(`\nPlan deletes ${totalDeletes} files (${Math.round(fraction * 100)}% of the tree). Type "delete" to confirm: `);
     return answer.trim().toLowerCase() === 'delete';
 }
-async function applyUpload(projectGuid, root, a, onConflict) {
-    try {
-        const result = await uploadOneFile(projectGuid, join(root, a.path), a.path, {
-            expectedServerVersion: a.expectedServerVersion,
-        });
-        return { ...a, reason: `uploaded serverVersion=${result.serverVersion}` };
-    }
-    catch (err) {
-        if (err instanceof UploadConflictError) {
-            return onConflict(a.path, err.currentServerVersion);
-        }
-        throw err;
-    }
-}
 /** Name of the optional per-project ignore file (gitignore-style: one pattern
  *  per line, blank lines and `#` comments skipped). Patterns use the same
  *  matcher as the config `ignore` list (see shouldIgnore) and let research
@@ -720,9 +705,14 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
         }
         applied++;
     }
-    // Uploads: bounded concurrency. On 409, rewrite as a conflict inline.
-    // A single byte bar tracks the whole batch (workers share the counter; JS is
-    // single-threaded so the += is race-free).
+    // Uploads: batched. Each chunk of UPLOAD_INIT_BATCH_SIZE files costs one
+    // upload-init-batch call (the server answers per file: already-have-it /
+    // conflict / presigned URL), then the S3 PUTs run UPLOAD_CONCURRENCY wide,
+    // then one upload-complete-batch call registers everything that landed.
+    // A single byte bar tracks the whole run (workers share the counter; JS is
+    // single-threaded so the += is race-free). Files the server already has -
+    // identical content at the same path, or dedup-linked from another path -
+    // transfer nothing but still count their bytes, so the bar reaches 100%.
     const uploadLabel = `Uploading ${uploadQueue.length} file${uploadQueue.length === 1 ? '' : 's'}`;
     const totalUploadBytes = uploadQueue.reduce((sum, a) => sum + (a.localSize ?? 0), 0);
     let sentBytes = 0;
@@ -731,90 +721,190 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
     const onBytes = p
         ? (delta) => { sentBytes += delta; p.transfer(uploadLabel, sentBytes, totalUploadBytes); }
         : undefined;
-    let cursor = 0;
-    const workers = [];
-    for (let w = 0; w < Math.min(UPLOAD_CONCURRENCY, uploadQueue.length); w++) {
-        workers.push((async () => {
-            while (true) {
-                const idx = cursor++;
-                if (idx >= uploadQueue.length)
-                    return;
-                const a = uploadQueue[idx];
-                let full;
-                try {
-                    full = resolveInRoot(root, a.path);
-                }
-                catch (e) {
-                    errors.push(e.message);
+    // Conflict downgrade shared by init-time and complete-time CAS rejections:
+    // remote moved under us, so remote wins the canonical path - rename local,
+    // restore the server copy, re-upload the rename as a brand-new path.
+    const downgradeToConflict = async (a, full, currentServerVersion) => {
+        const currentBytes = await fetchOne(config.projectGuid, a.path);
+        const renamedRel = conflictedCopyName(a.path);
+        let renamedFull;
+        try {
+            renamedFull = resolveInRoot(root, renamedRel);
+        }
+        catch (e) {
+            errors.push(e.message);
+            return;
+        }
+        try {
+            renameSync(full, renamedFull);
+        }
+        catch (e) {
+            errors.push(`Rename failed for ${a.path}: ${e.message}`);
+            return;
+        }
+        if (currentBytes) {
+            mkdirSync(dirname(full), { recursive: true });
+            writeFileSync(full, currentBytes);
+            const stat = statSync(full);
+            baseline.files[a.path] = {
+                size: stat.size, mtime: stat.mtime.toISOString(),
+                sha256: '', // will re-hash on next sync
+                serverVersion: currentServerVersion ?? 0,
+            };
+        }
+        try {
+            const result = await uploadOneFile(config.projectGuid, renamedFull, renamedRel, { expectedServerVersion: null });
+            const stat = statSync(renamedFull);
+            const { sha256 } = await hashFile(renamedFull);
+            baseline.files[renamedRel] = {
+                size: stat.size, mtime: stat.mtime.toISOString(),
+                sha256, serverVersion: result.serverVersion,
+            };
+        }
+        catch (e) {
+            errors.push(`Conflict-copy upload failed for ${renamedRel}: ${e.message}`);
+        }
+        applied++;
+    };
+    for (let chunkStart = 0; chunkStart < uploadQueue.length; chunkStart += UPLOAD_INIT_BATCH_SIZE) {
+        const chunk = uploadQueue.slice(chunkStart, chunkStart + UPLOAD_INIT_BATCH_SIZE);
+        // Stat + hash once per file; the same numbers feed init, the baseline,
+        // and the bar. Files that vanished or escaped the root drop out here.
+        const prepared = [];
+        for (const a of chunk) {
+            if (a.path.length > UPLOAD_MAX_PATH_CHARS) {
+                errors.push(`Upload failed for ${a.path}: path exceeds ${UPLOAD_MAX_PATH_CHARS} characters`);
+                onBytes?.(a.localSize ?? 0);
+                continue;
+            }
+            let full;
+            try {
+                full = resolveInRoot(root, a.path);
+            }
+            catch (e) {
+                errors.push(e.message);
+                onBytes?.(a.localSize ?? 0);
+                continue;
+            }
+            try {
+                const stat = statSync(full);
+                if (stat.size > UPLOAD_MAX_BYTES) {
+                    errors.push(`Upload failed for ${a.path}: file exceeds the 30 GB upload limit`);
+                    onBytes?.(a.localSize ?? 0);
                     continue;
                 }
-                try {
-                    const result = await uploadOneFile(config.projectGuid, full, a.path, {
-                        expectedServerVersion: a.expectedServerVersion,
-                        onBytes,
-                    });
-                    const stat = statSync(full);
-                    const { sha256 } = await hashFile(full);
-                    baseline.files[a.path] = {
-                        size: stat.size, mtime: stat.mtime.toISOString(),
-                        sha256, serverVersion: result.serverVersion,
+                const sha256 = local.get(a.path)?.sha256 ?? (await hashFile(full)).sha256;
+                prepared.push({ a, full, size: stat.size, mtime: stat.mtime.toISOString(), sha256 });
+            }
+            catch (e) {
+                errors.push(`Upload failed for ${a.path}: ${e.message}`);
+                onBytes?.(a.localSize ?? 0);
+            }
+        }
+        if (!prepared.length)
+            continue;
+        let initResults;
+        try {
+            initResults = await uploadInitBatch(config.projectGuid, prepared.map(pr => ({
+                path: pr.a.path, size: pr.size, sha256: pr.sha256, mime: guessMime(pr.a.path),
+                ...(pr.a.expectedServerVersion !== undefined
+                    ? { expected_server_version: pr.a.expectedServerVersion } : {}),
+            })));
+        }
+        catch (e) {
+            errors.push(`Upload batch failed: ${e.message}`);
+            for (const pr of prepared)
+                onBytes?.(pr.size);
+            continue;
+        }
+        const byPath = new Map(prepared.map(pr => [pr.a.path, pr]));
+        const conflicted = [];
+        const ready = [];
+        for (const r of initResults) {
+            const pr = byPath.get(r.path);
+            if (!pr)
+                continue;
+            switch (r.status) {
+                case 'already_current':
+                    baseline.files[pr.a.path] = {
+                        size: pr.size, mtime: pr.mtime, sha256: pr.sha256, serverVersion: r.server_version,
                     };
+                    onBytes?.(pr.size);
                     applied++;
+                    break;
+                case 'conflict':
+                    // No PUT happens for a file rejected at init - account its bytes now
+                    // so the bar still reaches 100% (the conflict copy is extra work
+                    // outside the byte budget). Complete-time conflicts differ: their PUT
+                    // already reported the bytes, so that branch must NOT re-count.
+                    onBytes?.(pr.size);
+                    conflicted.push({ pr, current: r.current_server_version });
+                    break;
+                case 'error':
+                    errors.push(`Upload failed for ${r.path}: ${r.message}`);
+                    onBytes?.(pr.size);
+                    break;
+                default:
+                    ready.push({ pr, init: r });
+            }
+        }
+        // S3 PUTs, UPLOAD_CONCURRENCY wide; collect upload-complete items as they land.
+        const toComplete = [];
+        let cursor = 0;
+        const workers = [];
+        for (let w = 0; w < Math.min(UPLOAD_CONCURRENCY, ready.length); w++) {
+            workers.push((async () => {
+                while (true) {
+                    const idx = cursor++;
+                    if (idx >= ready.length)
+                        return;
+                    const { pr, init } = ready[idx];
+                    try {
+                        const fields = await transferToS3(pr.full, pr.size, guessMime(pr.a.path), init, { onBytes });
+                        toComplete.push({ pr, item: {
+                                upload_guid: init.upload_guid, ...fields,
+                                ...(pr.a.expectedServerVersion !== undefined
+                                    ? { expected_server_version: pr.a.expectedServerVersion } : {}),
+                            } });
+                    }
+                    catch (err) {
+                        errors.push(`Upload failed for ${pr.a.path}: ${err.message}`);
+                    }
                 }
-                catch (err) {
-                    if (err instanceof UploadConflictError) {
-                        // Remote moved under us. Fetch the current remote bytes and
-                        // downgrade this path to a conflict: rename local, write remote,
-                        // re-upload the rename.
-                        const currentBytes = await fetchOne(config.projectGuid, a.path);
-                        const renamedRel = conflictedCopyName(a.path);
-                        let renamedFull;
-                        try {
-                            renamedFull = resolveInRoot(root, renamedRel);
-                        }
-                        catch (e) {
-                            errors.push(e.message);
-                            continue;
-                        }
-                        try {
-                            renameSync(full, renamedFull);
-                        }
-                        catch (e) {
-                            errors.push(`Rename failed for ${a.path}: ${e.message}`);
-                            continue;
-                        }
-                        if (currentBytes) {
-                            mkdirSync(dirname(full), { recursive: true });
-                            writeFileSync(full, currentBytes);
-                            const stat = statSync(full);
-                            baseline.files[a.path] = {
-                                size: stat.size, mtime: stat.mtime.toISOString(),
-                                sha256: '', // will re-hash on next sync
-                                serverVersion: err.currentServerVersion ?? 0,
-                            };
-                        }
-                        try {
-                            const result = await uploadOneFile(config.projectGuid, renamedFull, renamedRel, { expectedServerVersion: null });
-                            const stat = statSync(renamedFull);
-                            const { sha256 } = await hashFile(renamedFull);
-                            baseline.files[renamedRel] = {
-                                size: stat.size, mtime: stat.mtime.toISOString(),
-                                sha256, serverVersion: result.serverVersion,
+            })());
+        }
+        await Promise.all(workers);
+        if (toComplete.length) {
+            const byGuid = new Map(toComplete.map(c => [c.item.upload_guid, c.pr]));
+            try {
+                for (const r of await uploadCompleteBatch(config.projectGuid, toComplete.map(c => c.item))) {
+                    const pr = byGuid.get(r.upload_guid);
+                    if (!pr)
+                        continue;
+                    switch (r.status) {
+                        case 'completed':
+                            baseline.files[pr.a.path] = {
+                                size: pr.size, mtime: pr.mtime, sha256: pr.sha256, serverVersion: r.server_version,
                             };
-                        }
-                        catch (e) {
-                            errors.push(`Conflict-copy upload failed for ${renamedRel}: ${e.message}`);
-                        }
-                        applied++;
-                    }
-                    else {
-                        errors.push(`Upload failed for ${a.path}: ${err.message}`);
+                            applied++;
+                            break;
+                        case 'conflict':
+                            conflicted.push({ pr, current: r.current_server_version });
+                            break;
+                        default:
+                            errors.push(`Upload failed for ${pr.a.path}: ${r.message}`);
                     }
                 }
             }
-        })());
+            catch (e) {
+                errors.push(`Upload batch failed: ${e.message}`);
+            }
+        }
+        // Conflict downgrades are rare - handle them one at a time.
+        for (const { pr, current } of conflicted) {
+            await downgradeToConflict(pr.a, pr.full, current);
+        }
     }
-    await Promise.all(workers);
     // ── Deletes pass ──
     for (const a of plannedToApply) {
         if (a.kind === 'delete-local') {

package/dist/updater/bootstrap.js

@@ -22,7 +22,10 @@ export function bootstrap(version, quiet = false) {
     }
     if (!quiet)
         process.stderr.write(`Setting up gipity local install at ~/.gipity/local (one-time)...\n`);
-    const res = spawnSync('npm', ['install', '--no-audit', '--no-fund', `gipity@${version}`], {
+    // --ignore-scripts: don't run install lifecycle hooks (gipity ships
+    // precompiled, deps need no build), so a compromised package can't execute
+    // code during this self-managed install.
+    const res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
         cwd: LOCAL_DIR,
         stdio: ['ignore', 'pipe', 'pipe'],
         encoding: 'utf-8',

package/dist/updater/check.js

@@ -34,7 +34,10 @@ async function fetchLatestVersion() {
     return json.version;
 }
 function installVersion(version) {
-    const res = spawnSync('npm', ['install', '--silent', '--no-audit', '--no-fund', `gipity@${version}`], {
+    // --ignore-scripts: this runs unattended in the background, so don't let a
+    // compromised package's install lifecycle hooks execute. gipity ships
+    // precompiled (dist/) and its deps need no build step, so nothing is lost.
+    const res = spawnSync('npm', ['install', '--silent', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
         cwd: LOCAL_DIR,
         stdio: 'ignore',
     });

package/dist/upload.js

@@ -3,8 +3,20 @@ import { extname } from 'path';
 import { createHash } from 'crypto';
 import { post, putToPresignedUrl, ApiError } from './api.js';
 // Concurrency: parallel files in a batch + parallel parts within one multipart file.
-export const UPLOAD_CONCURRENCY = 4;
+// File-level parallelism is high because most files are small: the cost of a
+// small file is round-trip latency, not bandwidth, so wider = proportionally
+// faster. S3 PUTs go direct to S3; the API only sees batched init/complete.
+export const UPLOAD_CONCURRENCY = 16;
 const MULTIPART_PART_CONCURRENCY = 4;
+/** Files per upload-init-batch / upload-complete-batch call. Must not exceed
+ *  the server's UPLOAD_BATCH_MAX_ITEMS (200). */
+export const UPLOAD_INIT_BATCH_SIZE = 100;
+// Server-side per-file caps (PRESIGNED_UPLOAD_MAX_BYTES and the upload-init
+// path length in platform). The batch routes Zod-validate the whole array, so
+// one over-limit file would 400 its entire chunk - pre-check per file instead
+// and fail just that file, matching the old single-endpoint behavior.
+export const UPLOAD_MAX_BYTES = 30 * 1024 * 1024 * 1024;
+export const UPLOAD_MAX_PATH_CHARS = 1000;
 // Keep in sync with server's guessMime in platform/server/src/services/vfs/path-helpers.ts
 const MIME_BY_EXT = {
     '.html': 'text/html', '.htm': 'text/html',
@@ -118,14 +130,44 @@ export async function uploadOneFile(projectGuid, localPath, virtualPath, opts =
         throw err;
     }
     const data = init.data;
-    // Skip-if-identical fast path.
+    // Skip-if-identical fast path. Count the bytes as "done" - the server has
+    // them - so a caller's progress bar still reaches 100%.
     if ('already_current' in data && data.already_current) {
+        opts.onBytes?.(size);
         return { status: 'skipped', size, guid: data.guid, serverVersion: data.server_version };
     }
-    const completeBody = { upload_guid: data.upload_guid };
+    const fields = await transferToS3(localPath, size, mime, data, opts);
+    const completeBody = { upload_guid: data.upload_guid, ...fields };
     if (opts.expectedServerVersion !== undefined) {
         completeBody.expected_server_version = opts.expectedServerVersion;
     }
+    let comp;
+    try {
+        comp = await post(`/projects/${projectGuid}/files/upload-complete`, completeBody);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.statusCode === 409) {
+            const current = typeof err.data?.current_server_version === 'number'
+                ? err.data.current_server_version : null;
+            throw new UploadConflictError(current, virtualPath);
+        }
+        throw err;
+    }
+    return {
+        status: data.resumed ? 'resumed' : 'uploaded',
+        size: comp.data.size,
+        guid: comp.data.guid,
+        version: comp.data.version,
+        serverVersion: comp.data.server_version,
+    };
+}
+/**
+ * Move one file's bytes to S3 for an initialized upload: a single presigned
+ * PUT, or the multipart part fan-out (including server-driven resume).
+ * Returns the field upload-complete needs - `etag` for single-part, `parts`
+ * for multipart. Reports progress through opts.onBytes.
+ */
+export async function transferToS3(localPath, size, mime, data, opts = {}) {
     // Single-part (covers fresh + resumed PUT - single PUT is idempotent on the staging key).
     if (data.method === 'PUT') {
         const etag = await withRetry('PUT', async () => {
@@ -133,26 +175,7 @@ export async function uploadOneFile(projectGuid, localPath, virtualPath, opts =
             return putToPresignedUrl(data.url, stream, size, data.headers?.['Content-Type'] ?? mime);
         });
         opts.onBytes?.(size);
-        completeBody.etag = etag;
-        let comp;
-        try {
-            comp = await post(`/projects/${projectGuid}/files/upload-complete`, completeBody);
-        }
-        catch (err) {
-            if (err instanceof ApiError && err.statusCode === 409) {
-                const current = typeof err.data?.current_server_version === 'number'
-                    ? err.data.current_server_version : null;
-                throw new UploadConflictError(current, virtualPath);
-            }
-            throw err;
-        }
-        return {
-            status: data.resumed ? 'resumed' : 'uploaded',
-            size: comp.data.size,
-            guid: comp.data.guid,
-            version: comp.data.version,
-            serverVersion: comp.data.server_version,
-        };
+        return { etag };
     }
     // Multipart - start with any parts that already landed (resume case).
     const partSize = data.part_size;
@@ -193,25 +216,14 @@ export async function uploadOneFile(projectGuid, localPath, virtualPath, opts =
     }
     // Sort by part_number so server CompleteMultipartUpload sees ascending order.
     completed.sort((a, b) => a.part_number - b.part_number);
-    completeBody.parts = completed;
-    let comp;
-    try {
-        comp = await post(`/projects/${projectGuid}/files/upload-complete`, completeBody);
-    }
-    catch (err) {
-        if (err instanceof ApiError && err.statusCode === 409) {
-            const current = typeof err.data?.current_server_version === 'number'
-                ? err.data.current_server_version : null;
-            throw new UploadConflictError(current, virtualPath);
-        }
-        throw err;
-    }
-    return {
-        status: data.resumed ? 'resumed' : 'uploaded',
-        size: comp.data.size,
-        guid: comp.data.guid,
-        version: comp.data.version,
-        serverVersion: comp.data.server_version,
-    };
+    return { parts: completed };
+}
+export async function uploadInitBatch(projectGuid, files) {
+    const res = await post(`/projects/${projectGuid}/files/upload-init-batch`, { files });
+    return res.data.results;
+}
+export async function uploadCompleteBatch(projectGuid, items) {
+    const res = await post(`/projects/${projectGuid}/files/upload-complete-batch`, { items });
+    return res.data.results;
 }
 //# sourceMappingURL=upload.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.387",
+  "version": "1.0.388",
   "description": "The full-stack platform tuned for AI agents. Database, storage, auth, functions, deploy, and drop-in kits - all agent-tuned. Pair with Claude Code or use standalone.",
   "bin": {
     "gipity": "dist/updater/shim.js",
@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "commander": "^13.0.0",
+    "ignore": "^7.0.5",
     "tar-stream": "^3.1.8"
   },
   "devDependencies": {