gipity 1.0.401 → 1.0.402

package/dist/api.js

@@ -158,6 +158,18 @@ export async function downloadStream(path) {
     }
     return Readable.fromWeb(res.body);
 }
+// A presigned PUT has no built-in deadline: `fetch` will wait forever if S3
+// accepts the connection then stalls mid-body. That can't surface as a retry
+// (a hang never throws), so one stalled PUT wedges an entire deploy/sync while
+// it holds the project lock. Bound every PUT with a throughput-scaled deadline:
+// a generous floor for tiny files plus time for the body at a conservative
+// assumed-minimum rate, so a genuinely-progressing large upload survives but a
+// true stall aborts and lets withRetry() retry it.
+const PUT_TIMEOUT_FLOOR_MS = 120_000; // 2 min minimum, regardless of size
+const PUT_MIN_BYTES_PER_SEC = 256 * 1024; // assume the link sustains ≥256 KB/s
+export function putTimeoutMs(contentLength) {
+    return Math.max(PUT_TIMEOUT_FLOOR_MS, Math.ceil(contentLength / PUT_MIN_BYTES_PER_SEC) * 1000);
+}
 /**
  * PUT raw bytes to a presigned URL (no auth header - the URL is signed).
  * Supports a Buffer or a Readable stream body. Returns the response ETag header
@@ -174,12 +186,25 @@ export async function putToPresignedUrl(url, body, contentLength, contentType) {
     const fetchBody = isStream
         ? Readable.toWeb(body)
         : new Uint8Array(body);
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers,
-        body: fetchBody,
-        ...(isStream ? { duplex: 'half' } : {}),
-    });
+    const timeoutMs = putTimeoutMs(contentLength);
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'PUT',
+            headers,
+            body: fetchBody,
+            signal: AbortSignal.timeout(timeoutMs),
+            ...(isStream ? { duplex: 'half' } : {}),
+        });
+    }
+    catch (err) {
+        // A timeout aborts with a TimeoutError/AbortError. Surface it as a 408 so
+        // withRetry() treats it as transient and retries the PUT.
+        if (err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+            throw new ApiError(408, 'S3_UPLOAD_TIMEOUT', `S3 PUT stalled (no completion in ${Math.round(timeoutMs / 1000)}s)`);
+        }
+        throw err;
+    }
     if (!res.ok) {
         const text = await res.text().catch(() => res.statusText);
         throw new ApiError(res.status, 'S3_UPLOAD', `S3 PUT failed: ${res.status} ${text.slice(0, 200)}`);

package/dist/auth.js

@@ -70,6 +70,24 @@ export function sessionExpired() {
         return false; // undecodable - let the refresh path decide
     return Date.now() > exp * 1000;
 }
+/** True when the access token is currently past its expiry. Unlike
+ *  sessionExpired() (which only inspects the refresh token's lifetime), this
+ *  reflects whether the NEXT authenticated request can actually succeed right
+ *  now. Meaningful only when read AFTER refreshTokenIfNeeded(): a normal
+ *  expired access token gets silently renewed, so a token that is STILL expired
+ *  after a refresh attempt means the renewal failed — the refresh token was
+ *  rejected (genuinely lapsed, or rotated away by a sibling process sharing this
+ *  auth.json) — and re-login is required. Used to keep the up-front "Logged in"
+ *  message from contradicting a 401 on the very next call. */
+export function accessTokenExpired() {
+    const auth = getAuth();
+    if (!auth)
+        return true;
+    const t = new Date(auth.expiresAt).getTime();
+    if (isNaN(t))
+        return false; // unparseable - let the live 401 path decide
+    return Date.now() >= t;
+}
 const delay = (ms) => new Promise(r => setTimeout(r, ms));
 // ─── Cross-process refresh lock ────────────────────────────────
 // Serializes token refreshes across every `gipity` process that shares this

package/dist/commands/claude.js

@@ -5,7 +5,7 @@ import { spawn } from 'child_process';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { resolveCommand } from '../platform.js';
-import { getAuth, saveAuth, sessionExpired } from '../auth.js';
+import { getAuth, saveAuth, sessionExpired, accessTokenExpired, refreshTokenIfNeeded } from '../auth.js';
 import { get, post, publicPost, ApiError, getAccountSlug } from '../api.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, DEFAULT_API_BASE, getConfigPath } from '../config.js';
 import { sync } from '../sync.js';
@@ -307,11 +307,35 @@ export const claudeCommand = new Command('claude')
         if (!nonInteractive) {
             printBanner({ version: __clPkg.version, email: auth?.email, cwd: process.cwd() });
         }
-        if (auth && sessionExpired()) {
-            // The cached auth.json exists but its refresh token has lapsed, so the
-            // first API call below would 401 anyway. Re-login up front instead of
-            // printing "Logged in" and immediately contradicting it with "session
-            // expired" once the projects fetch fails.
+        // A GIPITY_TOKEN env token authenticates every request on its own, so the
+        // saved session's expiry is irrelevant when one is set — never re-login or
+        // warn about expiry in that case.
+        const hasEnvToken = Boolean(process.env.GIPITY_TOKEN?.trim());
+        // For an interactive saved-session run, renew the access token UP FRONT so
+        // the login line we're about to print is actually true. A saved session
+        // can look valid locally (refresh token not past its JWT expiry, so
+        // sessionExpired() is false) yet be dead on the server — most often because
+        // a sibling process sharing this auth.json already consumed the single-use
+        // refresh token (GipRunner runs many gipity processes against one auth dir).
+        // refreshTokenIfNeeded() attempts the rotation here; if it fails, the
+        // access token stays expired and accessTokenExpired() catches it below.
+        if (auth && !hasEnvToken && !nonInteractive && !sessionExpired()) {
+            await refreshTokenIfNeeded();
+            auth = getAuth();
+        }
+        // Re-login is genuinely required when the refresh token has lapsed, OR the
+        // proactive renewal above could not produce a still-valid access token
+        // (refresh token rejected/rotated away). The access-token check is gated to
+        // interactive runs: headless runs can't prompt, and their downstream API
+        // call renews the token itself. Never triggered while a GIPITY_TOKEN env
+        // token is supplying auth.
+        const reloginRequired = auth != null && !hasEnvToken &&
+            (sessionExpired() || (!nonInteractive && accessTokenExpired()));
+        if (auth && reloginRequired) {
+            // The saved session is dead (refresh token lapsed, or rotated away by a
+            // sibling process), so the first API call below would 401. Re-login up
+            // front instead of printing "Logged in" and immediately contradicting it
+            // with "session expired" once the projects fetch fails.
             console.log(`  ${muted('Your session expired. Let\'s sign you back in.')}\n`);
             auth = await interactiveLogin();
         }

package/dist/flag-aliases.js

@@ -24,6 +24,7 @@ export const FLAG_ALIASES = {
     '--ratio': '--aspect-ratio',
     '--res': '--resolution',
     '--desc': '--description',
+    '--body': '--data',
     '--src': '--source-dir',
     '--srcdir': '--source-dir',
     '--parallel': '--concurrency',

package/dist/index.js

@@ -223,16 +223,47 @@ function fullCommandName(cmd) {
         parts.unshift(c.name());
     return parts.join(' ');
 }
+// Resolve the deepest (sub)command the user actually targeted by walking the
+// command tree against the leading positional tokens of argv (skipping flags,
+// and a root value-option's value). Used at error time to render the RIGHT
+// command's help — see enableHelpAfterError below for why we can't just capture
+// the command in a closure.
+function resolveTargetCommand(argv) {
+    const args = argv.slice(2);
+    const rootValueFlags = new Set(program.options.filter(o => o.long && o.required).map(o => o.long));
+    let cmd = program;
+    for (let i = 0; i < args.length; i++) {
+        const tok = args[i];
+        if (tok.startsWith('-')) {
+            if (!tok.includes('=') && rootValueFlags.has(tok))
+                i++; // consume its value
+            continue;
+        }
+        const next = cmd.commands.find(c => c.name() === tok || c.aliases().includes(tok));
+        if (!next)
+            break; // first non-subcommand operand ends the command chain
+        cmd = next;
+    }
+    return cmd;
+}
 function enableHelpAfterError(cmd) {
     cmd.configureOutput({
-        // Commander calls this on the offending (sub)command. We render that exact
-        // command's full help (via outputHelp, so addHelpText blocks are included)
-        // FIRST, then write the one-line error LAST. Both go to the same writeErr
-        // stream synchronously, so the order holds. We do NOT call
+        // Render the offending command's full help (via outputHelp, so addHelpText
+        // blocks are included) FIRST, then the one-line error LAST. Both go to the
+        // same writeErr stream synchronously, so the order holds. We do NOT call
         // showHelpAfterError - that would render help a second time, before the error.
+        //
+        // We must resolve the target command from argv rather than capturing `cmd`
+        // here: commander shares ONE _outputConfiguration object across a command
+        // and all its subcommands (copyInheritedSettings copies it by reference, and
+        // configureOutput mutates it in place). So every subcommand's closure would
+        // clobber its siblings', leaving only the last-registered subcommand's — and
+        // an unknown option on `fn call` would print `fn delete`'s help. Installing
+        // one identical, self-resolving handler everywhere sidesteps the clobber.
         outputError: (str, write) => {
-            write(`Showing \`${fullCommandName(cmd)} --help\`:\n\n`);
-            cmd.outputHelp({ error: true });
+            const target = resolveTargetCommand(process.argv);
+            write(`Showing \`${fullCommandName(target)} --help\`:\n\n`);
+            target.outputHelp({ error: true });
             write(`\n${str.replace(/\n+$/, '')}\n`);
         },
     });

package/dist/knowledge.js

@@ -121,6 +121,19 @@ Write files locally - the Gipity Claude Code plugin's hooks auto-push every save
 
 To keep local-only material (research clones, scratch data, vendored references) in the project directory without syncing or deploying it, list it in a \`.gipityignore\` at the project root - gitignore-style, one pattern per line, \`#\` comments. Ignored paths are invisible to sync in both directions; anything that already synced before being ignored stays on the server until you delete it.
 
+### Where files go: deploy only ships \`src/\`
+
+Deploy is opt-in, not opt-out: the \`files\` phase uploads **only** what's under \`src/\` (plus \`functions/\` and \`migrations/\` as backend, not CDN files). Anything else at the project root is kept but never deployed. Put each kind of file in the right bucket so scratch and reference material can't bloat a deploy:
+
+- **\`src/\`** - the app itself. Synced **and** deployed to the CDN. Only app code, assets, and pages belong here.
+- **\`tmp/\`** - ephemeral scratch: file conversions, intermediate outputs, design staging. **Already ignored** (never synced, never deployed) - the one place to do throwaway work. Use this single root. (\`*_tmp/\` dirs and \`.gipityscratch/\` are auto-ignored too, as a safety net, so legacy scattered scratch like \`_vsd_tmp/\` can't leak - but write new scratch to \`tmp/\`, not scattered dirs.)
+- **\`docs/\`** - reference material you want to keep: UI/architecture diagrams, design decks, notes, ADRs. Synced and versioned on the server (backed up, rollback-able) but **never deployed**, because it's outside \`src/\`. This is the home for "keep forever, don't ship" artifacts.
+- **\`tests/\`** - \`*.test.js\` suites. Synced, run by \`gipity test\`, never deployed.
+
+Rule of thumb: shipping to users → \`src/\`; keep as reference → \`docs/\`; throwaway → \`tmp/\`.
+
+Watch for **bulky output dirs dropped loose at the root** (e.g. \`out/\`, \`vsd_out/\`, \`renders/\`). Unlike scratch, those are NOT ignored - they sync on every push and re-hash on every deploy, which is the classic cause of a slow, bloated deploy. Move them into \`docs/\` if you want to keep them or \`tmp/\` if they're disposable.
+
 ## Skills (detailed documentation)
 
 Run \`gipity skill list\` to see every skill. Run \`gipity skill read <name>\` to read one. Load the relevant skill before starting a task - they have the correct API patterns, code examples, and common mistakes.

package/dist/setup.js

@@ -39,8 +39,23 @@ export const PRIMER_FILES = {
 /** Aider's config file. We write/merge a `read:` entry into it so aider loads
  *  AGENTS.md - a per-workstation artifact like the primers, never synced. */
 export const AIDER_CONF_FILE = '.aider.conf.yml';
+/** Project-local scratch namespaces: file conversions, intermediate outputs,
+ *  design staging - work the agent wants on disk but should never sync or
+ *  deploy. These MUST mirror the sandbox's `isEphemeralSandboxPath` denylist
+ *  (`platform/server/src/services/sandbox/no-persist.ts`) so the same dirs are
+ *  treated as throwaway everywhere: a sandbox run refuses to persist them, and
+ *  `gipity sync`/deploy refuses to upload them. Keeping the two in lockstep is
+ *  what makes scratch coherent across the platform - update both together.
+ *  `tmp/` is the one we teach agents to use (see knowledge.ts "Files and sync");
+ *  `*_tmp/` and `.gipityscratch/` are caught defensively so legacy/scattered
+ *  scratch (the `_vsd_tmp/`/`_convert_tmp/` dirs that bloated past deploys)
+ *  can't leak in either. Reference material to KEEP (diagrams, decks, ADRs) goes
+ *  in `docs/` instead - synced and versioned, but outside `src/` so it's never
+ *  deployed. Gitignore-glob form, matched by the `ignore` package in config.ts. */
+export const SCRATCH_IGNORE = ['tmp/', '.tmp/', '*_tmp/', '.gipityscratch/'];
 export const DEFAULT_SYNC_IGNORE = [
     'node_modules', '.git', '.gipity.json', '.gipity/', '.claude/', '.gitignore', AIDER_CONF_FILE,
+    ...SCRATCH_IGNORE,
     ...new Set(Object.values(PRIMER_FILES)),
 ];
 /** True if `name` (a top-level dir entry) is a workstation artifact that
@@ -480,7 +495,9 @@ export const SUPPORTED_TOOLS = [
 export const DEFAULT_TOOLS = SUPPORTED_TOOLS.filter(t => !t.optIn);
 export function setupGitignore() {
     const gitignorePath = resolve(process.cwd(), '.gitignore');
-    const entries = ['.gipity/', '.gipity.json'];
+    // Sync already skips the scratch namespaces (DEFAULT_SYNC_IGNORE); ignore them
+    // in git too so ephemeral conversion/staging work never gets committed.
+    const entries = ['.gipity/', '.gipity.json', ...SCRATCH_IGNORE];
     if (existsSync(gitignorePath)) {
         let content = readFileSync(gitignorePath, 'utf-8');
         // Split on \r?\n so a CRLF .gitignore (the Windows default) doesn't leave a

package/dist/sync.js

@@ -21,7 +21,7 @@
  * `name (conflict from <host> YYYY-MM-DD-HHMMSS).ext` and then uploaded on
  * the next pass so every client sees it. No content merging, ever.
  */
-import { writeFileSync, mkdirSync, existsSync, statSync, unlinkSync, readdirSync, rmdirSync, readFileSync, renameSync, openSync, closeSync } from 'fs';
+import { writeFileSync, mkdirSync, existsSync, statSync, unlinkSync, readdirSync, rmdirSync, readFileSync, renameSync, openSync, closeSync, utimesSync } from 'fs';
 import { join, relative, dirname, extname, resolve, sep } from 'path';
 import { hostname } from 'os';
 import { get, del, downloadStream, ApiError } from './api.js';
@@ -54,6 +54,41 @@ function projectDir() {
 // ─── Advisory lock ─────────────────────────────────────────────
 const LOCK_WAIT_MS = 30_000;
 const LOCK_POLL_MS = 500;
+// While a holder works it refreshes the lock's mtime on this cadence; a lock
+// whose mtime is older than the stale window is treated as abandoned and
+// reclaimed even if a process with its PID still exists. This catches the two
+// cases a dead-PID check misses: a CPU-wedged holder that stopped heartbeating,
+// and PID reuse (some unrelated process now owns the old holder's PID). The
+// stale window must stay comfortably larger than the heartbeat so a briefly
+// busy holder isn't robbed mid-run.
+const LOCK_HEARTBEAT_MS = 15_000;
+export const LOCK_STALE_MS = 90_000;
+/** Decide whether an existing lock file is reclaimable. Exported for tests.
+ *  Reclaim when: the file is empty/garbage (holder crashed between creating the
+ *  lock and writing its PID), the holder PID is dead, or the lock's heartbeat
+ *  went silent past {@link LOCK_STALE_MS}. A live, freshly-heartbeating holder
+ *  is never reclaimed. */
+export function isLockReclaimable(path, now = Date.now()) {
+    let raw;
+    let mtimeMs;
+    try {
+        raw = readFileSync(path, 'utf-8').trim();
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return false; // can't read it (likely already gone / racing) - retry, don't steal
+    }
+    const pid = parseInt(raw, 10);
+    if (!raw || !pid || isNaN(pid))
+        return true; // empty/garbage = crashed mid-create
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return true;
+    } // holder PID is dead
+    return now - mtimeMs > LOCK_STALE_MS; // alive but heartbeat went silent
+}
 /** Acquire the per-project sync lock. Returns a release function. Exported for tests. */
 export async function acquireLock() {
     const path = lockPath();
@@ -64,30 +99,30 @@ export async function acquireLock() {
             const fd = openSync(path, 'wx');
             writeFileSync(fd, String(process.pid));
             closeSync(fd);
-            return () => { try {
+            // Heartbeat: keep the lock's mtime fresh so peers can distinguish a live
+            // holder from an abandoned one. unref() so it never holds the process open.
+            const beat = setInterval(() => {
+                try {
+                    utimesSync(path, new Date(), new Date());
+                }
+                catch { /* lock gone */ }
+            }, LOCK_HEARTBEAT_MS);
+            beat.unref?.();
+            return () => { clearInterval(beat); try {
                 unlinkSync(path);
             }
             catch { /* already gone */ } };
         }
         catch {
-            // Either lock exists, or the race gave us a transient error. Check for
-            // staleness (holder PID is dead → treat as unlocked).
-            try {
-                const pid = parseInt(readFileSync(path, 'utf-8').trim(), 10);
-                if (pid && !isNaN(pid)) {
-                    try {
-                        process.kill(pid, 0);
-                    }
-                    catch {
-                        try {
-                            unlinkSync(path);
-                        }
-                        catch { /* race */ }
-                        continue;
-                    }
+            // Lock exists (or the race gave a transient error). Reclaim it if the
+            // holder is dead/abandoned; otherwise wait and retry.
+            if (isLockReclaimable(path)) {
+                try {
+                    unlinkSync(path);
                 }
+                catch { /* race - someone else got it */ }
+                continue;
             }
-            catch { /* couldn't read - retry */ }
             if (Date.now() - start > LOCK_WAIT_MS) {
                 throw new Error(`Another sync is in progress (${path}). Waited ${LOCK_WAIT_MS / 1000}s. ` +
                     `Remove the file manually if you're sure no sync is running.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.401",
+  "version": "1.0.402",
   "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",