gipity 1.0.400 → 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/claude-setup.js

@@ -0,0 +1,87 @@
+/**
+ * Claude Code install + detection helpers, shared by `gipity claude` (which
+ * auto-ensures Claude Code before launching) and `gipity doctor` (which reports
+ * Claude state). Centralizing here means a GUI/installer — e.g. the desktop
+ * onboarding client — drives Claude setup through the CLI instead of
+ * re-implementing it.
+ *
+ * The plan (`claudeInstallPlan`) is pure + unit-tested; actually running
+ * `which`/`npm` happens in the helpers below and in the command layer.
+ */
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+export const CLAUDE_PACKAGE = '@anthropic-ai/claude-code';
+/** Pure: the platform-appropriate detect + install commands. Unit-tested. */
+export function claudeInstallPlan(platformOverride) {
+    const plat = platformOverride ?? process.platform;
+    return {
+        checkCmd: plat === 'win32' ? 'where claude' : 'which claude',
+        installArgv: ['npm', 'install', '-g', CLAUDE_PACKAGE],
+    };
+}
+/** Whether the `claude` binary resolves on PATH. */
+export function isClaudeInstalled(platformOverride) {
+    try {
+        execSync(claudeInstallPlan(platformOverride).checkCmd, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort, positive-evidence-only check for "Claude Code is logged in."
+ *
+ * NOTE: on macOS the OAuth token can live in the Keychain, which we can't read
+ * non-interactively — so a `false` here may be a false-negative. Callers should
+ * treat `false` as "offer the login step" rather than "definitely logged out."
+ * (Tracked as an open question in the desktop onboarding spec.)
+ */
+export function isClaudeAuthenticated() {
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY)
+        return true;
+    return existsSync(join(homedir(), '.claude', '.credentials.json'));
+}
+/**
+ * Definitive auth check: actually run a tiny headless `claude -p` ping. If it
+ * returns output, Claude Code is authenticated. This is the reliable check
+ * (unlike `isClaudeAuthenticated`'s file/env heuristic) but it's **billed** (a
+ * real LLM call) and slow (network + model latency), so it's opt-in — use it at
+ * a decision point (e.g. confirming the login step took), not on every poll.
+ */
+export function probeClaudeAuthenticated() {
+    if (!isClaudeInstalled())
+        return false;
+    try {
+        const out = execSync('claude -p "Reply with the single word: PONG"', {
+            timeout: 60_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        return typeof out === 'string' && out.trim().length > 0;
+    }
+    catch {
+        // Non-zero exit (unauthenticated, network error, etc.) → treat as not auth'd.
+        return false;
+    }
+}
+/**
+ * Install Claude Code via npm if it isn't already on PATH. Idempotent: a no-op
+ * (beyond the PATH check) when already present, unless `force`. `quiet`
+ * suppresses npm's output (for headless/GUI callers); default streams it.
+ */
+export function ensureClaudeInstalled(opts = {}) {
+    if (!opts.force && isClaudeInstalled())
+        return { installed: true, alreadyPresent: true };
+    const { installArgv } = claudeInstallPlan();
+    try {
+        execSync(installArgv.join(' '), { stdio: opts.quiet ? 'ignore' : 'inherit' });
+    }
+    catch {
+        // Fall through to a definitive PATH re-check rather than trusting the throw.
+    }
+    return { installed: isClaudeInstalled(), alreadyPresent: false };
+}
+//# sourceMappingURL=claude-setup.js.map

package/dist/commands/claude.js

@@ -1,11 +1,11 @@
 import { Command } from 'commander';
 import { join, dirname, resolve, basename } from 'path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync } from 'fs';
-import { execSync, spawn } from 'child_process';
+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';
@@ -18,6 +18,7 @@ import { brand, bold, info, success, warning, error as clrError, muted } from '.
 import { createProgressReporter } from '../progress.js';
 import { printBanner } from '../banner.js';
 import { scanForAdoption, isLikelyEmpty, canAdoptCwd, formatCwdLabel, formatBytes, adoptCurrentDir, ADOPT_THRESHOLDS, } from '../adopt-cwd.js';
+import { isClaudeInstalled, ensureClaudeInstalled, CLAUDE_PACKAGE } from '../claude-setup.js';
 const __clDir = dirname(fileURLToPath(import.meta.url));
 const __clPkg = JSON.parse(readFileSync(resolve(__clDir, '../../package.json'), 'utf-8'));
 /** Report a sync run to the user. Beyond the applied-changes line, this SURFACES
@@ -246,6 +247,21 @@ export const claudeCommand = new Command('claude')
         // a human at the terminal. Requires an existing .gipity.json - we
         // can't interactively pick or create a project in this mode.
         const rawArgs = process.argv.slice(process.argv.indexOf('claude') + 1);
+        // `gipity claude install` - explicit, GUI-callable Claude Code install.
+        // Handled here (leading positional) rather than as a Commander subcommand
+        // because this command uses allowUnknownOption/allowExcessArguments to
+        // pass everything through to `claude`; a real subcommand would risk that
+        // passthrough (which the relay daemon's `gipity claude -p` depends on).
+        if (rawArgs[0] === 'install') {
+            const r = ensureClaudeInstalled({ force: rawArgs.includes('--force') });
+            if (r.alreadyPresent)
+                console.log(`  ${success('Claude Code already installed.')}`);
+            else if (r.installed)
+                console.log(`  ${success('Claude Code installed.')}`);
+            else
+                console.log(`  ${clrError('Could not install Claude Code.')} Install manually: npm install -g ${CLAUDE_PACKAGE}`);
+            process.exit(r.installed ? 0 : 1);
+        }
         const nonInteractive = rawArgs.some(a => a === '-p' || a === '--print' || a.startsWith('--print=') || a.startsWith('-p='));
         // Headless progress emitter: routes to stderr (stdout stays clean for
         // the child's result), drops the interactive 2-space indent, collapses
@@ -291,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();
         }
@@ -608,15 +648,18 @@ export const claudeCommand = new Command('claude')
             console.log(`  Done. cd ${process.cwd()} && gipity claude`);
             return;
         }
-        // Check claude is installed
-        try {
-            const checkCmd = process.platform === 'win32' ? 'where claude' : 'which claude';
-            execSync(checkCmd, { stdio: 'ignore' });
-        }
-        catch {
-            console.log('  Claude Code not found. Install it: npm install -g @anthropic-ai/claude-code');
-            console.log(`  Then: cd ${process.cwd()} && claude`);
-            return;
+        // Ensure Claude Code is installed - install it ourselves if missing so a
+        // GUI/installer (and terminal users) get it for free, rather than being
+        // told to run npm by hand.
+        if (!isClaudeInstalled()) {
+            console.log('  Claude Code not found - installing it now...');
+            const r = ensureClaudeInstalled();
+            if (!r.installed) {
+                console.log(`  ${clrError('Could not install Claude Code.')} Install manually: npm install -g ${CLAUDE_PACKAGE}`);
+                console.log(`  Then: cd ${process.cwd()} && claude`);
+                return;
+            }
+            console.log(`  ${success('Claude Code installed.')}`);
         }
         // Ensure the Gipity plugin is actually installed at user scope (not just
         // enabled declaratively) so its capture + file-sync hooks load in this

package/dist/commands/doctor.js

@@ -3,6 +3,12 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { LOCAL_PKG_DIR, LOCAL_ENTRY, STATE_FILE, SETTINGS_FILE, UPDATE_LOG, readState, readSettings, updatesDisabled } from '../updater/state.js';
 import { bold, dim, success, warning, error as clrError, muted } from '../colors.js';
+import { getAuth, sessionExpired } from '../auth.js';
+import { isClaudeInstalled, isClaudeAuthenticated, probeClaudeAuthenticated } from '../claude-setup.js';
+import * as relayState from '../relay/state.js';
+import { planFor, UnsupportedPlatformError } from '../relay/installers.js';
+import { resolveCliPath } from '../relay/setup.js';
+const NODE_MIN_MAJOR = 18;
 function localVersion() {
     const pkgPath = join(LOCAL_PKG_DIR, 'package.json');
     if (!existsSync(pkgPath))
@@ -38,16 +44,94 @@ function rel(t) {
         return `${Math.floor(s / 3600)}h ago`;
     return `${Math.floor(s / 86400)}d ago`;
 }
+/** Whether the relay's OS login-service unit file exists. Reflects "autostart
+ *  has been installed" (by `relay setup`/`relay install`); cheap and poll-safe.
+ *  null on an unsupported platform. */
+function relayAutostartInstalled() {
+    try {
+        return existsSync(planFor({ cliPath: resolveCliPath() }).path);
+    }
+    catch (err) {
+        if (err instanceof UnsupportedPlatformError)
+            return null;
+        return null;
+    }
+}
+/**
+ * Snapshot of the local environment a GUI/installer needs to drive onboarding:
+ * Node, the Gipity CLI + login state, Claude Code install + auth, and the relay
+ * pairing/daemon state. The single "state of the world" the desktop onboarding
+ * client polls (`gipity doctor --json`).
+ */
+export function gatherEnv(opts = {}) {
+    const nodeMajor = parseInt(process.versions.node.split('.')[0], 10) || 0;
+    const auth = getAuth();
+    const expired = auth ? sessionExpired() : false;
+    const device = relayState.getDevice();
+    const node = { ok: nodeMajor >= NODE_MIN_MAJOR, version: process.versions.node };
+    const gipity = {
+        installed: true, // we're running it
+        version: shimVersion(),
+        logged_in: !!auth && !expired,
+        email: auth?.email ?? null,
+        session_expired: expired,
+    };
+    const claude = { installed: isClaudeInstalled(), authenticated: false };
+    // Default: cheap heuristic (poll-safe). With --probe-claude: a real (billed)
+    // `claude -p` ping for a definitive answer.
+    claude.authenticated = claude.installed && (opts.probeClaude ? probeClaudeAuthenticated() : isClaudeAuthenticated());
+    const relay = {
+        paired: !!device,
+        running: relayState.isDaemonRunning(),
+        paused: relayState.isPaused(),
+        autostart: relayAutostartInstalled(),
+        device: device ? { name: device.name, guid: device.guid } : null,
+    };
+    const dis = updatesDisabled();
+    const updState = readState();
+    const cli = {
+        shim_version: shimVersion(),
+        local_version: localVersion(),
+        local_install_ok: existsSync(LOCAL_ENTRY),
+        auto_updates: !dis.disabled,
+        updates_disabled_reason: dis.disabled ? (dis.reason ?? null) : null,
+        last_check_at: updState.lastCheckAt,
+        last_error: updState.lastError,
+    };
+    const ready = node.ok && gipity.logged_in && claude.installed && claude.authenticated && relay.paired && relay.running;
+    return { ready, node, gipity, claude, relay, cli };
+}
+function yn(v) {
+    return v ? success('yes') : warning('no');
+}
 export const doctorCommand = new Command('doctor')
-    .description('Check install health')
-    .action(() => {
+    .description('Check install + environment health')
+    .option('--json', 'Machine-readable environment report (for installers/GUIs)')
+    .option('--probe-claude', 'Verify Claude Code auth with a real (billed) `claude -p` ping instead of the cheap heuristic')
+    .action((opts) => {
+    const env = gatherEnv({ probeClaude: opts.probeClaude });
+    if (opts.json) {
+        console.log(JSON.stringify(env, null, 2));
+        return;
+    }
+    // ── Environment (what onboarding cares about) ──────────────────────
+    console.log(bold('Gipity - doctor'));
+    console.log('');
+    console.log(bold('Environment'));
+    console.log(`${muted('node            ')} ${env.node.version}  ${env.node.ok ? success('✓') : clrError(`(need ${NODE_MIN_MAJOR}+)`)}`);
+    console.log(`${muted('gipity login    ')} ${env.gipity.logged_in ? success(`logged in as ${env.gipity.email}`) : (env.gipity.session_expired ? warning(`session expired (${env.gipity.email})`) : warning('not logged in'))}`);
+    console.log(`${muted('claude code     ')} installed ${yn(env.claude.installed)} · authenticated ${yn(env.claude.authenticated)}`);
+    const autostartLabel = env.relay.autostart === null ? muted('n/a') : yn(env.relay.autostart);
+    console.log(`${muted('relay           ')} paired ${yn(env.relay.paired)} · running ${yn(env.relay.running)} · autostart ${autostartLabel}${env.relay.paused ? warning(' · paused') : ''}${env.relay.device ? muted(`  (${env.relay.device.name})`) : ''}`);
+    console.log(`${muted('ready           ')} ${env.ready ? success('yes') : warning('no - run `gipity claude` (or the desktop app) to finish setup')}`);
+    // ── CLI install / update health ────────────────────────────────────
     const state = readState();
     const settings = readSettings();
     const dis = updatesDisabled();
     const local = localVersion();
     const localOk = existsSync(LOCAL_ENTRY);
-    console.log(bold('Gipity CLI - doctor'));
     console.log('');
+    console.log(bold('CLI install'));
     console.log(`${muted('shim version    ')} ${shimVersion()}`);
     console.log(`${muted('local version   ')} ${local ?? dim('not installed')}  ${localOk ? success('✓') : warning('(running from shim fallback)')}`);
     console.log(`${muted('local install   ')} ${LOCAL_PKG_DIR}`);
@@ -60,6 +144,5 @@ export const doctorCommand = new Command('doctor')
     console.log(`${muted('update log      ')} ${existsSync(UPDATE_LOG) ? `${UPDATE_LOG} (${statSync(UPDATE_LOG).size} bytes)` : dim('(none yet)')}`);
     console.log('');
     console.log(dim('Force an update with: gipity update'));
-    console.log(dim('Disable auto-update:  export DISABLE_AUTOUPDATER=1  (or set autoUpdates: false in settings.json)'));
 });
 //# sourceMappingURL=doctor.js.map

package/dist/commands/payments.js

@@ -0,0 +1,54 @@
+import { Command } from 'commander';
+import { get, post } from '../api.js';
+import { requireConfig } from '../config.js';
+import { brand, bold, dim, muted } from '../colors.js';
+import { run } from '../helpers/index.js';
+function renderStatus(status) {
+    if (!status.connected) {
+        console.log('Stripe: not connected. Run `gipity payments connect` to set it up.');
+        return;
+    }
+    const charges = status.charges_enabled ? brand('enabled') : dim('disabled');
+    const payouts = status.payouts_enabled ? brand('enabled') : dim('disabled');
+    console.log(`Stripe: ${bold('connected')}`);
+    console.log(`  Charges:  ${charges}`);
+    console.log(`  Payouts:  ${payouts}`);
+    console.log(`  Onboarding: ${status.details_submitted ? 'complete' : 'incomplete'}`);
+    if (!status.charges_enabled) {
+        console.log(muted('\nCharges are not enabled yet — finish Stripe onboarding via `gipity payments connect`.'));
+    }
+}
+export const paymentsCommand = new Command('payments')
+    .description('Connect Stripe so your app can charge its users (one-time + subscriptions)');
+paymentsCommand
+    .command('connect')
+    .description('Start (or resume) Stripe onboarding for this app — prints a link to finish in your browser')
+    .option('--return-url <url>', 'Where Stripe redirects after onboarding')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Payments', async () => {
+    const config = requireConfig();
+    const body = opts.returnUrl ? { returnUrl: opts.returnUrl } : {};
+    const res = await post(`/api/${config.projectGuid}/services/payments/connect`, body);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    console.log('Open this link to connect your Stripe account (bank + identity; no API keys to paste):\n');
+    console.log(brand(res.data.url));
+    console.log(muted('\nMoney lands in your Stripe account; Gipity takes a small platform fee.'));
+    console.log(muted('When done, run `gipity payments status` to confirm charges are enabled.'));
+}));
+paymentsCommand
+    .command('status', { isDefault: true })
+    .description('Show whether this app can take payments yet')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Payments', async () => {
+    const config = requireConfig();
+    const res = await get(`/api/${config.projectGuid}/services/payments/status`);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    renderStatus(res.data);
+}));
+//# sourceMappingURL=payments.js.map

package/dist/commands/relay-install.js

@@ -1,10 +1,8 @@
-import { spawnSync } from 'child_process';
-import { resolve, dirname } from 'path';
-import { mkdirSync, writeFileSync } from 'fs';
 import { confirm } from '../utils.js';
 import { bold, dim, success, error as clrError, muted, info } from '../colors.js';
 import * as state from '../relay/state.js';
 import { planFor, UnsupportedPlatformError } from '../relay/installers.js';
+import { installAutostart, removeAutostart, resolveCliPath } from '../relay/setup.js';
 function requirePaired() {
     const device = state.getDevice();
     if (!device) {
@@ -13,27 +11,6 @@ function requirePaired() {
     }
     return device;
 }
-/** Absolute path to the currently-running `gipity` CLI. Embedded in the
- *  service unit so the launchd/systemd/Task Scheduler entry re-launches
- *  the same binary even if PATH changes. */
-function resolveCliPath() {
-    return resolve(process.argv[1] ?? 'gipity');
-}
-/** Run a sequence of argv commands directly (no shell). Returns true if all
- *  succeeded. Spawns each command's stdio inherited so the user sees the
- *  service manager's output verbatim. */
-function runArgvSequence(cmds, { failFast }) {
-    let allOk = true;
-    for (const argv of cmds) {
-        const r = spawnSync(argv[0], argv.slice(1), { stdio: 'inherit' });
-        if (r.status !== 0) {
-            allOk = false;
-            if (failFast)
-                return false;
-        }
-    }
-    return allOk;
-}
 export function registerInstallCommands(relayCommand) {
     relayCommand
         .command('install')
@@ -41,10 +18,9 @@ export function registerInstallCommands(relayCommand) {
         .option('--print', 'Print the service-unit file and the commands, but don\'t run them')
         .action(async (opts) => {
         requirePaired();
-        const cliPath = resolveCliPath();
         let plan;
         try {
-            plan = planFor({ cliPath });
+            plan = planFor({ cliPath: resolveCliPath() });
         }
         catch (err) {
             if (err instanceof UnsupportedPlatformError) {
@@ -69,10 +45,11 @@ export function registerInstallCommands(relayCommand) {
             console.log(muted('Cancelled. (Use --print to preview without installing.)'));
             return;
         }
-        mkdirSync(dirname(plan.path), { recursive: true });
-        writeFileSync(plan.path, plan.content);
-        console.log(success(`Wrote ${plan.path}`));
-        if (!runArgvSequence(plan.enableCmds, { failFast: true })) {
+        // Shared helper writes the unit + runs the enable commands; `inherit`
+        // surfaces launchctl/systemctl/schtasks output for this interactive path.
+        const res = installAutostart({ stdio: 'inherit' });
+        console.log(success(`Wrote ${res.path}`));
+        if (!res.ok) {
             console.error(clrError(`Couldn't enable autostart. Try manually: ${plan.enableDisplay}`));
             process.exit(1);
         }
@@ -89,9 +66,21 @@ export function registerInstallCommands(relayCommand) {
             console.error(clrError('Usage: gipity relay autostart <on|off>'));
             process.exit(1);
         }
-        let plan;
         try {
-            plan = planFor({ cliPath: resolveCliPath() });
+            if (want === 'on') {
+                const plan = planFor({ cliPath: resolveCliPath() });
+                console.log(`${info('Running:')} ${dim(plan.enableDisplay)}`);
+                const res = installAutostart({ stdio: 'inherit' });
+                if (!res.ok) {
+                    console.error(clrError('Command failed.'));
+                    process.exit(1);
+                }
+            }
+            else {
+                // Disable is best-effort - the task may already be stopped.
+                const { plan } = removeAutostart({ stdio: 'inherit' });
+                console.log(`${info('Running:')} ${dim(plan.disableDisplay)}`);
+            }
         }
         catch (err) {
             if (err instanceof UnsupportedPlatformError) {
@@ -101,15 +90,6 @@ export function registerInstallCommands(relayCommand) {
             else
                 throw err;
         }
-        const cmds = want === 'on' ? plan.enableCmds : plan.disableCmds;
-        const display = want === 'on' ? plan.enableDisplay : plan.disableDisplay;
-        console.log(`${info('Running:')} ${dim(display)}`);
-        // Disable is best-effort (the task may already be stopped); enable is fail-fast.
-        const ok = runArgvSequence(cmds, { failFast: want === 'on' });
-        if (!ok && want === 'on') {
-            console.error(clrError('Command failed.'));
-            process.exit(1);
-        }
         console.log(success(`Autostart ${want}.`));
     });
 }

package/dist/commands/relay.js

@@ -8,14 +8,98 @@
 import { Command } from 'commander';
 import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { spawn } from 'child_process';
-import { post } from '../api.js';
+import { post, ApiError } from '../api.js';
 import { confirm } from '../utils.js';
-import { bold, brand, success, error as clrError, muted, } from '../colors.js';
+import { bold, brand, dim, success, error as clrError, muted, } from '../colors.js';
 import * as state from '../relay/state.js';
 import * as daemon from '../relay/daemon.js';
+import { UnsupportedPlatformError } from '../relay/installers.js';
+import { pairDevice, startDaemon, installAutostart } from '../relay/setup.js';
 import { registerInstallCommands } from './relay-install.js';
 export const relayCommand = new Command('relay')
     .description('Pair with the web CLI');
+// ─── gipity relay setup ────────────────────────────────────────────────
+// Non-interactive pair + (optionally) start + autostart, for installers and
+// GUIs (e.g. the desktop onboarding client) that can't drive prompts. The
+// interactive equivalent is the first-run block in `gipity claude`.
+relayCommand
+    .command('setup')
+    .description('Pair this machine and start the relay - non-interactive (for installers/GUIs)')
+    .option('--name <name>', 'Device name shown in the web CLI (default: this machine\'s hostname)')
+    .option('--no-start', 'Pair only; do not start the relay daemon now')
+    .option('--no-autostart', 'Skip the OS login service (use when a supervising app owns the daemon)')
+    .option('--force', 'Re-pair even if already paired (revokes the old device first)')
+    .option('--json', 'Machine-readable output')
+    .action(async (opts) => {
+    const fail = (code, message) => {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, code, error: message }));
+        }
+        else {
+            console.error(clrError(message));
+            if (code === 'not_authenticated')
+                console.error(muted('Run `gipity login` first.'));
+        }
+        process.exit(1);
+    };
+    // 1. Pair (idempotent unless --force).
+    let device;
+    try {
+        device = await pairDevice({ name: opts.name, force: opts.force });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.statusCode === 401) {
+            return fail('not_authenticated', 'Not logged in - cannot pair this machine.');
+        }
+        return fail('pair_failed', `Could not pair: ${err?.message || err}`);
+    }
+    // 2. Start the daemon now (unless --no-start).
+    let daemonStarted = false;
+    if (opts.start) {
+        startDaemon();
+        daemonStarted = true;
+    }
+    // 3. Install OS autostart (unless --no-autostart). Option B desktop clients
+    //    pass --no-autostart because the app itself supervises `relay run`.
+    const autostart = { requested: opts.autostart, installed: false, supported: true, summary: '' };
+    if (opts.autostart) {
+        try {
+            const res = installAutostart();
+            autostart.installed = res.ok;
+            autostart.summary = res.summary;
+        }
+        catch (err) {
+            if (err instanceof UnsupportedPlatformError) {
+                autostart.supported = false;
+            }
+            else {
+                return fail('autostart_failed', `Autostart install failed: ${err?.message || err}`);
+            }
+        }
+    }
+    // 4. Report.
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            device: { guid: device.guid, name: device.name, platform: device.platform, reused: device.reused },
+            daemon_started: daemonStarted,
+            autostart,
+        }));
+        return;
+    }
+    console.log(success(`${device.reused ? 'Already paired' : 'Paired'} as ${bold(device.name)} ${muted(`(${device.guid})`)}.`));
+    if (daemonStarted)
+        console.log(success('Relay started.'));
+    if (autostart.requested) {
+        if (!autostart.supported)
+            console.log(muted(`Auto-start not supported on ${process.platform}; skipped.`));
+        else if (autostart.installed)
+            console.log(`${success('Auto-start installed.')} ${dim(autostart.summary)}`);
+        else
+            console.log(muted('Auto-start enable returned non-zero - retry with `gipity relay install`.'));
+    }
+    console.log(dim('In the Gipity web CLI, type `/claude` to dispatch messages to this machine.'));
+});
 // ─── gipity relay status ───────────────────────────────────────────────
 relayCommand
     .command('status')
@@ -24,10 +108,13 @@ relayCommand
     .action((opts) => {
     const s = state.loadState();
     if (opts.json) {
-        // Redact the token - no reason for scripts to see it.
+        // Redact the token - no reason for scripts to see it. `daemon_running`
+        // lets a supervising app (the desktop client) poll liveness and decide
+        // whether to (re)spawn `relay run` without parsing the PID file itself.
         const safe = {
             ...s,
             device: s.device ? { ...s.device, token: '***' } : null,
+            daemon_running: state.isDaemonRunning(),
         };
         console.log(JSON.stringify(safe, null, 2));
         return;
@@ -40,6 +127,7 @@ relayCommand
     console.log(`${bold('Platform:')}    ${s.device.platform}`);
     console.log(`${bold('Paired:')}      ${s.device.paired_at}`);
     console.log(`${bold('Paused:')}      ${s.paused ? 'yes' : 'no'}`);
+    console.log(`${bold('Running:')}     ${state.isDaemonRunning() ? 'yes' : 'no'}`);
 });
 // ─── gipity relay run ──────────────────────────────────────────────────
 relayCommand

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

@@ -35,6 +35,7 @@ import { pageCommand } from './commands/page.js';
 import { recordsCommand } from './commands/records.js';
 import { fnCommand } from './commands/fn.js';
 import { serviceCommand } from './commands/service.js';
+import { paymentsCommand } from './commands/payments.js';
 import { jobCommand } from './commands/job.js';
 import { rbacCommand } from './commands/rbac.js';
 import { auditCommand } from './commands/audit.js';
@@ -124,7 +125,7 @@ const commonGroup = [skillCommand, projectCommand, addCommand, removeCommand, de
 const connectGroup = [claudeCommand, relayCommand];
 const projectGroup = [domainCommand, statusCommand, initCommand];
 const filesGroup = [fileCommand, syncCommand, pushCommand, uploadCommand];
-const appBuildingGroup = [testCommand, fnCommand, serviceCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
+const appBuildingGroup = [testCommand, fnCommand, serviceCommand, paymentsCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
 const utilitiesGroup = [pageCommand, sandboxCommand, generateCommand, emailCommand, gmailCommand, locationCommand, textCommand];
 const agentGroup = [chatCommand, memoryCommand, agentCommand, approvalCommand];
 const setupGroup = [loginCommand, logoutCommand, tokenCommand, creditsCommand, planCommand, doctorCommand, updateCommand, uninstallCommand];
@@ -222,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

@@ -21,6 +21,7 @@ Templates:
     - \`api\` - Backend service, webhook, data pipeline, chatbot, cron job - no frontend
     - \`karaoke-captions\` - Forced-alignment app - karaoke captions, subtitle timing, language learning, dubbing alignment
     - \`outreach-agent\` - AI outreach / drip-email funnel - reach a list of people with personalized, human-approved emails that auto-send on a schedule and a self-improving agent that learns from your edits
+    - \`paid-app\` - App that charges users money - SaaS subscription, paid membership, digital product store, "Pro" upgrade, paywalled content (Stripe one-time + subscriptions)
 When unsure, default to \`web-simple\`. After adding the template, edit the generated files, then \`gipity deploy dev\`.
 Only skip this on a build request if the user explicitly says not to.
 
@@ -38,7 +39,8 @@ Kits are reusable building blocks added to an existing app, not whole templates
     - \`gipity add records\` - Registry-driven records: declare objects/fields as data, get generic CRUD functions with validation, full-text search, soft delete, ACTOR provenance, and an audit event spine - every write is transactional (row + event). Field types include relations ({id,label}), currency, emails/phones/links composites. Ships backend functions + migrations. Needs a database (web-fullstack/api template).
     - \`gipity add views\` - Generic UI over records-kit objects: sortable/filterable table with full-text search, create/edit/delete forms with type-appropriate widgets, kanban board with drag-to-update. Renders entirely from the field registry - zero per-object UI code. Requires the records kit.
     - \`gipity add agent-api\` - Make your app agent-operable: named API keys (kit_api_keys) let agents and scripts write through the records kit's single write path with AGENT/API actor attribution - machine writes land on the same audit spine as human edits. Requires the records kit.
-    - \`gipity add contacts\` - Source-agnostic contact data layer for lead-gen/CRM apps: import people from LinkedIn CSV + Gmail + pasted lists, resolve duplicates into one person while keeping EVERY value from every source with provenance (multi-valued attributes, never overwrites). Exact email/URL auto-merge; fuzzy name+company goes to a human merge-review queue (reversible). Re-imports detect job changes and emit signals. User-definable tags, full-text search, and a transactional event spine. Ships backend functions + migrations. Needs a database (web-fullstack/api template).`;
+    - \`gipity add contacts\` - Source-agnostic contact data layer for lead-gen/CRM apps: import people from LinkedIn CSV + Gmail + pasted lists, resolve duplicates into one person while keeping EVERY value from every source with provenance (multi-valued attributes, never overwrites). Exact email/URL auto-merge; fuzzy name+company goes to a human merge-review queue (reversible). Re-imports detect job changes and emit signals. User-definable tags, full-text search, and a transactional event spine. Ships backend functions + migrations. Needs a database (web-fullstack/api template).
+    - \`gipity add stripe\` - Charge your app's end-users for one-time purchases and subscriptions via Stripe. Owner connects their own Stripe account through Gipity-hosted onboarding (no API keys to paste); money lands in their account, Gipity takes a small platform fee. Ships a buy-button / pricing component, a subscription-status helper for gating UI, a webhook-verified fulfillment function, and the payments/subscriptions tables. The platform brokers checkout + signature-verified webhooks. Needs a database (web-fullstack/api template).`;
 export const SKILLS_CONTENT = `# Gipity Integration
 
 Gipity is the cloud platform your project runs on - hosting, databases, deployment, file storage, code execution, workflows, and monitoring. Gip is the cloud agent that runs on Gipity.
@@ -119,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.
@@ -130,6 +145,7 @@ App services skills (load before calling \`/services/*\` endpoints):
 - \`app-image\` - text-to-image only (no input image / editing); providers, sizes, aspect ratios
 - \`app-llm\` - chat completions, streaming, image input
 - \`app-location\` - user location & reverse geocoding for deployed apps (first-party - no third-party geocoder)
+- \`app-payments\` - charge end-users real money - Stripe one-time purchases & subscriptions, via the stripe kit (gipity add stripe)
 - \`app-realtime\` - Gipity Realtime rooms, relay vs state
 - \`app-tts\` - voices, multi-speaker, languages
 - \`app-video\` - Gipity Video: models, aspect, resolution

package/dist/relay/onboarding.js

@@ -5,43 +5,16 @@
  * daemon that auto-starts on every subsequent `gipity claude` invocation,
  * and - if they said yes to the last question - also starts at OS login.
  */
-import { hostname, platform as osPlatform } from 'os';
-import { spawn, spawnSync } from 'child_process';
-import { resolve, dirname } from 'path';
-import { mkdirSync, writeFileSync } from 'fs';
-import { post } from '../api.js';
+import { hostname } from 'os';
 import { prompt, confirm } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted, info } from '../colors.js';
 import * as state from './state.js';
-import { planFor, UnsupportedPlatformError } from './installers.js';
-import { getMachineId } from './machine-id.js';
-/** Normalize Node's `os.platform()` to what the backend accepts. */
-function mapPlatform(p) {
-    if (p === 'darwin' || p === 'linux' || p === 'win32')
-        return p;
-    return 'linux';
-}
-/** Path to the currently-running `gipity` CLI (for embedding in service units). */
-function resolveCliPath() {
-    return resolve(process.argv[1] ?? 'gipity');
-}
-/** Spawn a fresh `gipity relay run` detached from this process. Fire-and-forget. */
-export function ensureDaemonRunning() {
-    if (state.isDaemonRunning())
-        return;
-    try {
-        // Launch via the current Node binary + the CLI entry script. The previous
-        // `shell: true` on Windows ran the .js path through the shell, where the
-        // file association (Windows Script Host, not Node) would mis-handle it.
-        // process.execPath is cross-platform and needs no shell.
-        const child = spawn(process.execPath, [resolveCliPath(), 'relay', 'run'], {
-            detached: true,
-            stdio: 'ignore',
-        });
-        child.unref();
-    }
-    catch { /* best-effort */ }
-}
+import { UnsupportedPlatformError } from './installers.js';
+import { pairDevice, startDaemon, installAutostart } from './setup.js';
+/** Spawn a fresh `gipity relay run` detached from this process. Fire-and-forget.
+ *  Re-exported from the shared `setup` core so existing importers (`claude.ts`)
+ *  keep their import path. */
+export const ensureDaemonRunning = startDaemon;
 /**
  * First-run prompt block. Idempotent: if the user has already answered
  * (`relay_enabled` is a boolean), this is a no-op. Non-interactive flows
@@ -75,13 +48,11 @@ export async function maybeOfferRelayOn() {
         state.setRelayEnabled(false);
         return;
     }
-    // Create the device directly (user-auth, no pair code).
-    let token;
-    let shortGuid;
+    // Create the device directly (user-auth, no pair code). `pairDevice` writes
+    // the device + flips relay_enabled on; we only have to render the outcome.
+    let device;
     try {
-        const res = await post('/remote-devices', { name, platform: mapPlatform(osPlatform()), machine_id: getMachineId() });
-        token = res.data.token;
-        shortGuid = res.data.short_guid;
+        device = await pairDevice({ name });
     }
     catch (err) {
         console.error(`\n  ${clrError(`Could not create device: ${err?.message || err}`)}`);
@@ -89,41 +60,21 @@ export async function maybeOfferRelayOn() {
         state.setRelayEnabled(false);
         return;
     }
-    state.setDevice({
-        guid: shortGuid,
-        name,
-        platform: mapPlatform(osPlatform()),
-        token,
-        paired_at: new Date().toISOString(),
-    });
-    state.setRelayEnabled(true);
     // Start the daemon for this session.
     const startNow = await confirm('  Start the relay now (and on future `gipity claude` runs)?', { default: 'yes' });
     if (startNow) {
-        ensureDaemonRunning();
+        startDaemon();
     }
     // Offer OS-level autostart (launchd / systemd --user / Task Scheduler).
     const autostartOs = await confirm('  Also start at OS login (auto-start with Windows / macOS / Linux)?', { default: 'yes' });
     if (autostartOs) {
         try {
-            const plan = planFor({ cliPath: resolveCliPath() });
-            mkdirSync(dirname(plan.path), { recursive: true });
-            writeFileSync(plan.path, plan.content);
-            // Run argv directly - no shell - so paths with spaces / shell metas
-            // can't break out. Fail-fast on the first non-zero exit.
-            let allOk = true;
-            for (const argv of plan.enableCmds) {
-                const r = spawnSync(argv[0], argv.slice(1), { stdio: 'ignore' });
-                if (r.status !== 0) {
-                    allOk = false;
-                    break;
-                }
-            }
-            if (!allOk) {
+            const res = installAutostart();
+            if (!res.ok) {
                 console.log(`  ${muted('Autostart install returned non-zero - you can run')} ${brand('gipity relay install')} ${muted('later.')}`);
             }
             else {
-                console.log(`  ${success('Auto-start installed.')} ${dim(plan.summary)}`);
+                console.log(`  ${success('Auto-start installed.')} ${dim(res.summary)}`);
             }
         }
         catch (err) {
@@ -136,7 +87,7 @@ export async function maybeOfferRelayOn() {
         }
     }
     console.log('');
-    console.log(`  ${success(`Registered as ${bold(name)} (${shortGuid}).`)}`);
+    console.log(`  ${success(`Registered as ${bold(device.name)} (${device.guid}).`)}`);
     console.log(`  ${dim('In the Gipity web CLI, type `/claude` to dispatch messages to this PC.')}`);
     console.log('');
     void info;

package/dist/relay/setup.js

@@ -0,0 +1,142 @@
+/**
+ * Headless relay setup primitives — the non-interactive core shared by:
+ *   - the first-run `gipity claude` onboarding (`onboarding.ts`),
+ *   - the `gipity relay setup` command (installer/GUI entry point),
+ *   - `gipity relay install` / `gipity relay autostart` (`relay-install.ts`).
+ *
+ * Keeping pairing + autostart here means a supervising app (e.g. the desktop
+ * onboarding client) can drive the whole relay through one code path —
+ * `pairDevice()` → `startDaemon()` / `installAutostart()` — without replaying
+ * the interactive prompts that live in `onboarding.ts`. No `console` output
+ * and no `process.exit` in this module: callers own all UX.
+ */
+import { spawn, spawnSync } from 'child_process';
+import { hostname, platform as osPlatform } from 'os';
+import { resolve, dirname } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { post } from '../api.js';
+import * as state from './state.js';
+import { planFor } from './installers.js';
+import { getMachineId } from './machine-id.js';
+/** Normalize Node's `os.platform()` to what the backend accepts. */
+export function mapPlatform(p) {
+    if (p === 'darwin' || p === 'linux' || p === 'win32')
+        return p;
+    return 'linux';
+}
+/** Absolute path to the currently-running `gipity` CLI. Embedded in service
+ *  units so launchd/systemd/Task Scheduler re-launch the same binary even if
+ *  PATH changes. */
+export function resolveCliPath() {
+    return resolve(process.argv[1] ?? 'gipity');
+}
+/**
+ * Create + persist a relay device, marking the relay opted-in. Idempotent
+ * unless `force`: if this machine is already paired and `!force`, the
+ * existing device is returned untouched (no server call). With `force`, the
+ * old device is revoked server-side (best-effort) before re-pairing.
+ *
+ * Throws on a bad name or if the `/remote-devices` call fails (e.g. 401 when
+ * the user isn't logged in) — callers translate that into their own UX.
+ */
+export async function pairDevice(opts = {}) {
+    const existing = state.getDevice();
+    if (existing && !opts.force) {
+        state.setRelayEnabled(true);
+        return {
+            guid: existing.guid,
+            name: existing.name,
+            platform: mapPlatform(existing.platform),
+            reused: true,
+        };
+    }
+    if (existing && opts.force) {
+        try {
+            await post(`/remote-devices/${encodeURIComponent(existing.guid)}/revoke`, {});
+        }
+        catch {
+            // Best-effort: a stale server-side device is harmless; proceed to re-pair.
+        }
+        state.clearDevice();
+    }
+    const name = (opts.name?.trim() || hostname() || 'my-pc').trim();
+    if (!name || name.length > 100) {
+        throw new Error('Device name must be 1–100 non-whitespace characters.');
+    }
+    const plat = mapPlatform(osPlatform());
+    const res = await post('/remote-devices', { name, platform: plat, machine_id: getMachineId() });
+    state.setDevice({
+        guid: res.data.short_guid,
+        name,
+        platform: plat,
+        token: res.data.token,
+        paired_at: new Date().toISOString(),
+    });
+    state.setRelayEnabled(true);
+    return { guid: res.data.short_guid, name, platform: plat, reused: false };
+}
+/**
+ * Spawn a fresh `gipity relay run` detached from this process. No-op if the
+ * daemon is already running. Fire-and-forget — best-effort, never throws.
+ *
+ * Launches via the current Node binary + CLI entry script (not a shell): the
+ * previous `shell: true` on Windows ran the `.js` path through Windows Script
+ * Host instead of Node. `process.execPath` is cross-platform and needs no shell.
+ */
+export function startDaemon() {
+    if (state.isDaemonRunning())
+        return;
+    try {
+        const child = spawn(process.execPath, [resolveCliPath(), 'relay', 'run'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Write the platform service-unit and enable it (start at OS login,
+ * auto-restart on crash). Throws `UnsupportedPlatformError` from `planFor` on
+ * an OS we don't generate a unit for. Returns `ok: false` if a service-manager
+ * command exits non-zero (the file is still written, so the caller can point
+ * the user at a manual retry).
+ *
+ * `stdio` defaults to `'ignore'` (silent, for headless/GUI callers); the
+ * interactive `relay install` passes `'inherit'` so the user sees
+ * launchctl/systemctl/schtasks output verbatim.
+ */
+export function installAutostart(opts = {}) {
+    const stdio = opts.stdio ?? 'ignore';
+    const plan = planFor({ cliPath: resolveCliPath() });
+    mkdirSync(dirname(plan.path), { recursive: true });
+    writeFileSync(plan.path, plan.content);
+    let ok = true;
+    for (const argv of plan.enableCmds) {
+        const r = spawnSync(argv[0], argv.slice(1), { stdio });
+        if (r.status !== 0) {
+            ok = false;
+            break;
+        }
+    }
+    return { ok, summary: plan.summary, path: plan.path };
+}
+/**
+ * Best-effort removal of the OS autostart unit. Disable is not fail-fast (the
+ * service may already be stopped); we run every command and report whether all
+ * succeeded. Throws `UnsupportedPlatformError` on an unsupported OS.
+ */
+export function removeAutostart(opts = {}) {
+    const stdio = opts.stdio ?? 'ignore';
+    const plan = planFor({ cliPath: resolveCliPath() });
+    let ok = true;
+    for (const argv of plan.disableCmds) {
+        const r = spawnSync(argv[0], argv.slice(1), { stdio });
+        if (r.status !== 0)
+            ok = false;
+    }
+    return { ok, plan };
+}
+//# sourceMappingURL=setup.js.map

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.400",
+  "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",
@@ -13,7 +13,7 @@
     "postbuild": "node scripts/gen-build-info.mjs",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
+    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
     "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-live.test.js dist/__tests__/cli-e2e-sync-live.test.js dist/__tests__/cli-e2e-services-media-live.test.js dist/__tests__/cli-e2e-workflow-live.test.js dist/__tests__/cli-e2e-sandbox-live.test.js dist/__tests__/cli-e2e-page-fetch-live.test.js dist/__tests__/cli-e2e-page-test-live.test.js",
     "test:e2e:sync": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sync-live.test.js",
     "test:e2e:sandbox": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sandbox-live.test.js"