gipity 1.1.3 → 1.1.5

package/dist/knowledge.js

@@ -37,12 +37,10 @@ Kits are reusable building blocks added to an existing app, not whole templates
     - \`gipity add chatbot\` - Drop-in chatbot - configurable persona, scope guardrails, static knowledge (20k budget), streaming responses. Headless engine + bubble widget; bring your own UI if you want. Works in any app.
     - \`gipity add audio-align\` - Audio + lyrics -> word-level timing JSON. Demucs vocal isolation + MMS_FA forced alignment, runs as a Modal L4 GPU job (~$0.01 per 3-min song). For karaoke captions, subtitling, language learning, dubbing alignment.
     - \`gipity add i18n\` - Multi-language for web apps - language picker, locale persistence, RTL, plural/translation lookup. Scaffolds src/js/strings.js and wires it up; move your copy there and read it with t('key'). Web only.
-    - \`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). See the \`app-records\` skill.
-    - \`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. See the \`app-records\` skill.
-    - \`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. See the \`app-records\` skill.
     - \`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).
-    - \`gipity add notify\` - Web push notifications for any web app, including iOS home-screen web apps (iOS 16.4+). The platform owns the VAPID keys, encryption, and delivery — no keys to paste, no crypto, no server. Ships a <gipity-notify-button>, a service worker, and a PWA manifest; the device subscribes itself and self-heals stale subscriptions. Send from a function with the injected notify() service (one flat credit per send, owner-billed) or test with \`gipity notify test\`. Works in any template — no database required.`;
+    - \`gipity add notify\` - Web push notifications for any web app, including iOS home-screen web apps (iOS 16.4+). The platform owns the VAPID keys, encryption, and delivery — no keys to paste, no crypto, no server. Ships a <gipity-notify-button>, a service worker, and a PWA manifest; the device subscribes itself and self-heals stale subscriptions. Send from a function with the injected notify() service (one flat credit per send, owner-billed) or test with \`gipity notify test\`. Works in any template — no database required.
+    - \`gipity add servicenow\` - Use ServiceNow tables as a data source: OAuth (client-credentials) authenticated polling pull into a local Postgres mirror (sn_records, any table, configurable), plus write-back into ServiceNow via the Table API. Optional real-time sync layers a ServiceNow Business Rule + Script Include on top, pushing changes to a webhook the instant they happen. Ships a cron workflow for the pull cycle, sn-pull/sn-write/sn-webhook functions, and setup scripts that automate the ServiceNow-side configuration. 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.
@@ -150,12 +148,14 @@ Write files locally - Gipity's editor hooks (installed into Claude Code, Grok, a
 
 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.
 
+**WSL trap: user-dropped files may be in a Windows-side twin.** On WSL, a same-named folder often exists at \`C:\\Users\\<name>\\GipityProjects\\<project>\` (visible as \`/mnt/c/Users/<name>/GipityProjects/<project>\`) - from Windows Explorer it looks like "the project folder", so users drop new files (audio, images) there. Nothing syncs from it. If the user says files are "in the project" but you can't find them, check that path before searching wider; \`gipity sync\` prints a notice when such a twin exists.
+
 ### 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.) Because it never syncs, \`tmp/\` is also never mirrored into the sandbox: **don't stage \`gipity sandbox run\` inputs here** - the sandbox won't see them. Stage inputs under \`src/\`/\`docs/\` and delete them after.
+- **\`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. Leave scratch files where they are when you're done; there's nothing to clean up (no \`rm\` turn) - they're invisible to sync and deploy. (\`*_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.) Because it never syncs, \`tmp/\` is also never mirrored into the sandbox: **don't stage \`gipity sandbox run\` inputs here** - the sandbox won't see them. Stage inputs under \`src/\`/\`docs/\` and delete them after.
 - **\`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. \`gipity test list [path]\` lists the test files (and what a filter selects) without running them.
 
@@ -171,7 +171,7 @@ App services skills (load before calling \`/services/*\` endpoints):
 - \`app-audio\` - sound effects, music, transcription
 - \`app-auth\` - sign in with Gipity, popup vs redirect
 - \`app-files\` - uploads, variants, file listing
-- \`app-image\` - text-to-image only (no input image / editing); providers, sizes, aspect ratios
+- \`app-image\` - text-to-image AND instruction editing (pass \`images\` to edit an uploaded photo); 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-notify\` - web push notifications for deployed apps (incl. iOS home-screen web apps) - notify kit + injected notify() service, platform owns the keys
@@ -186,6 +186,7 @@ App development skills:
 - \`app-debugging\` - debug a deployed app: page inspect/eval, screenshots, function logs
 - \`app-development\` - functions, database, and API
 - \`app-import\` - import apps from GitHub/.gip bundles (incl. Vercel/Replit/Lovable porting) and export any project as a portable .gip - app_import tool, gipity save/load
+- \`app-records\` - Gipity Records: declared tables → validated CRUD, provenance, workflows, auto UI
 - \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the isolated test DB)
 - \`deploy\` - the deploy pipeline & gipity.yaml manifest
 - \`jobs\` - long-running CPU + GPU compute jobs (Python / Node / bash)
@@ -194,7 +195,6 @@ App development skills:
 - \`web-ui-patterns\` - default Gipity look (theme tokens) + web UI recipes - feeds, copy-to-clipboard
 
 Kit skills (reusable building blocks - \`gipity add <kit>\`):
-- \`app-records\` - the records + views kits: registry-driven CRUD with search + audit history, and generated tables/kanban/forms (gipity add records)
 - \`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
 

package/dist/login-flow.js

@@ -10,9 +10,48 @@
  */
 import { publicPost } from './api.js';
 import { getAuth, saveAuth } from './auth.js';
+import { getConfig } from './config.js';
 import { prompt, decodeJwtExp } from './utils.js';
-import { success, error as clrError, muted } from './colors.js';
+import { success, error as clrError, warning, muted } from './colors.js';
 import { flushBugQueue } from './bug-queue.js';
+/** True when a fresh-account result would be a SURPRISE worth warning about:
+ *  either this directory is linked to an existing project, or this machine
+ *  already held a session for this exact email. A genuine first-time signup
+ *  (nothing linked, no prior session) must stay silent. */
+function newAccountWouldBeUnexpected(email, priorAuth) {
+    return !!getConfig() || priorAuth?.email.toLowerCase() === email.toLowerCase().trim();
+}
+/** Called right after `/auth/login` (send-code), before the code is entered -
+ *  the server already knows at this point whether the email matches an
+ *  existing account (bug cli#S2: logging into the wrong/new account was
+ *  previously silent until a later "not found" error). */
+export function warnBeforeCodeIfUnexpectedNewAccount(isNewUser, email, indent = '') {
+    if (isNewUser !== true)
+        return;
+    const priorAuth = getAuth();
+    if (!newAccountWouldBeUnexpected(email, priorAuth))
+        return;
+    const config = getConfig();
+    console.log(`${indent}${warning(`No existing Gipity account for ${email} — entering the code will CREATE a new one.`)}`);
+    if (config) {
+        console.log(`${indent}${muted(`This directory is linked to project ${config.projectSlug} (account ${config.accountSlug}). If you meant to log into that account, stop and re-check the email before entering the code.`)}`);
+    }
+}
+/** Called right after `/auth/verify` succeeds. `priorAuth` must be captured
+ *  BEFORE `saveAuth()` overwrites the cache - it's the only way to tell "this
+ *  machine already had a session for this email" from "first login ever". */
+export function warnIfUnexpectedNewAccount(isNewUser, email, priorAuth, indent = '') {
+    if (isNewUser !== true)
+        return;
+    if (!newAccountWouldBeUnexpected(email, priorAuth))
+        return;
+    const config = getConfig();
+    console.log(`${indent}${warning(`Logged into a NEW, empty account for ${email} — no prior account existed for this email.`)}`);
+    if (config) {
+        console.log(`${indent}${muted(`This directory is linked to project ${config.projectSlug} (account ${config.accountSlug}), which the new account does not own — project / skill / sync commands will fail with "not found".`)}`);
+    }
+    console.log(`${indent}${muted('If you expected an existing account, run: gipity status  — then gipity login again with the correct email.')}`);
+}
 /** Prompt for email + 6-digit code, persist the tokens, and return the new
  *  auth. Exits the process on empty input or a bad token (the caller can't
  *  proceed without a session). */
@@ -22,13 +61,15 @@ export async function interactiveLogin() {
         console.error(`\n  ${clrError('Email required.')}`);
         process.exit(1);
     }
-    await publicPost('/auth/login', { email });
+    const sendRes = await publicPost('/auth/login', { email });
     console.log('  Check your email for a 6-digit code.\n');
+    warnBeforeCodeIfUnexpectedNewAccount(sendRes.isNewUser, email, '  ');
     const code = await prompt('  Code: ');
     if (!code) {
         console.error(`\n  ${clrError('Code required.')}`);
         process.exit(1);
     }
+    const priorAuth = getAuth();
     const res = await publicPost('/auth/verify', { email, code });
     const exp = decodeJwtExp(res.accessToken);
     if (!exp) {
@@ -38,6 +79,7 @@ export async function interactiveLogin() {
     const expiresAt = new Date(exp * 1000).toISOString();
     saveAuth({ accessToken: res.accessToken, refreshToken: res.refreshToken, email, expiresAt });
     console.log(`  ${success(`Logged in (${email}).`)}`);
+    warnIfUnexpectedNewAccount(res.isNewUser, email, priorAuth, '  ');
     const delivered = await flushBugQueue().catch(() => 0);
     if (delivered > 0) {
         console.log(`  ${muted(`Delivered ${delivered} queued bug report${delivered === 1 ? '' : 's'}.`)}`);

package/dist/relay/onboarding.js

@@ -12,8 +12,7 @@
  * All the non-interactive primitives live in `setup.ts` (`pairDevice`,
  * `startDaemon`, `installAutostart`); this module is only the prompts + copy.
  */
-import { readFileSync } from 'node:fs';
-import { prompt, confirm } from '../utils.js';
+import { prompt, confirm, isWsl } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as state from './state.js';
 import { UnsupportedPlatformError } from './installers.js';
@@ -27,21 +26,6 @@ export const ensureDaemonRunning = startDaemon;
  * ended up enabled (or was already), `false` if the user declined or a step
  * failed. Non-interactive flows (e.g. `gipity claude -p`) must not call this.
  */
-/** True inside Windows Subsystem for Linux (either env marker or kernel
- *  string). Used to explain autostart failures accurately - WSL ships without
- *  a systemd user session unless the user opts in via /etc/wsl.conf. */
-function isWsl() {
-    if (process.platform !== 'linux')
-        return false;
-    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP)
-        return true;
-    try {
-        return /microsoft/i.test(readFileSync('/proc/version', 'utf-8'));
-    }
-    catch {
-        return false;
-    }
-}
 export async function runRelaySetup(opts) {
     const alreadyAnswered = state.getRelayEnabled() !== undefined;
     // `gipity claude` first-run: honor the user's prior choice and don't re-ask.
@@ -66,13 +50,13 @@ export async function runRelaySetup(opts) {
             console.log('');
             console.log(`  ${success('Registered as')} ${bold(existingDevice.name)} ${muted(`(${existingDevice.guid})`)}`);
             if (state.isPaused()) {
-                console.log(`  ${dim('The relay is paused — resume it with')} ${brand('gipity relay resume')}${dim('.')}`);
+                console.log(`  ${dim('The relay is paused - resume it with')} ${brand('gipity relay resume')}${dim('.')}`);
             }
             else {
                 console.log(`  ${dim('The relay is running. Open')} ${brand('gipity.ai')}${dim(' and type `/claude` to drive Claude Code here.')}`);
             }
             console.log('');
-            console.log(`  ${dim('To register this computer again — for example under a different name —')}`);
+            console.log(`  ${dim('To register this computer again (for example under a different name),')}`);
             console.log(`  ${dim('unregister it first, then re-run setup:')}`);
             console.log(`      ${brand('gipity relay revoke')}   ${dim('# unpairs this computer and removes the login service')}`);
             console.log(`      ${brand('gipity connect')}        ${dim('# register it again (asks for a new name)')}`);
@@ -82,34 +66,36 @@ export async function runRelaySetup(opts) {
     }
     // Header. `gipity setup` frames it as the deliberate action it is; the
     // `gipity claude` first-run frames it as an optional add-on it's offering.
+    // Lines are pre-wrapped short so they never rewrap in a normal terminal.
     if (opts.mode === 'run-now') {
         console.log(`  ${bold('Set up this computer as a relay')}`);
-        console.log(`  ${dim('A relay runs your coding agent (Claude Code, Codex, or Grok) here so you can drive it from the web (')}${brand('gipity.ai')}${dim(') on any browser.')}`);
-        console.log(`  ${dim('It uses your Claude, Codex, or Grok subscription — the cheapest way to pay for tokens.')}`);
+        console.log(`  ${dim('Gipity drives the coding agents on this computer from the web (')}${brand('gipity.ai')}${dim(')')}`);
+        console.log(`  ${dim('on any browser, desktop or phone. Uses your Claude, Codex, or Grok')}`);
+        console.log(`  ${dim('subscription - the cheapest way to pay for tokens.')}`);
     }
     else {
-        console.log(`  ${bold('Remote control of your coding agent')}`);
-        console.log(`  ${dim('Drive your coding agent on this computer from the web (')}${brand('gipity.ai')}${dim(') on any browser (desktop or phone).')}`);
-        console.log('');
-        console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity connect')}`);
+        console.log(`  ${bold('Optional:')} ${dim('Gipity can drive the coding agents on this computer from the')}`);
+        console.log(`  ${dim('web (')}${brand('gipity.ai')}${dim(') on any browser, desktop or phone. Like Claude Code remote')}`);
+        console.log(`  ${dim('control, but one pane for all your coding agents.')}`);
     }
     console.log('');
     const promptText = opts.mode === 'run-now'
-        ? '  Set up remote control on this computer?'
-        : '  Enable remote control?';
+        ? '  Set up remote control on this computer'
+        : '  Enable remote control';
     const enable = await confirm(promptText, { default: 'yes' });
     if (!enable) {
         state.setRelayEnabled(false);
-        console.log(`  ${muted('Skipped.')}`);
+        console.log(`  ${muted('Skipped. Turn on later with')} ${brand('gipity connect')}${muted('.')}`);
         console.log('');
         return false;
     }
+    console.log('');
     // Device name - show a friendly default (owner + device kind); Enter accepts.
     const defaultName = friendlyDeviceName();
     const rawName = await prompt(`  Device name [${bold(defaultName)}]: `);
     const name = (rawName || defaultName).trim();
     if (!name || name.length > 100) {
-        console.error(`  ${clrError('Device name must be 1–100 non-whitespace characters. Skipping.')}`);
+        console.error(`  ${clrError('Device name must be 1-100 non-whitespace characters. Skipping.')}`);
         state.setRelayEnabled(false);
         return false;
     }
@@ -128,13 +114,12 @@ export async function runRelaySetup(opts) {
         // run instead of silently opting the user out forever.
         return false;
     }
-    // Start the daemon for this session.
-    const startNow = await confirm('  Start the relay now (and on future `gipity build` runs)?', { default: 'yes' });
-    if (startNow) {
-        startDaemon();
-    }
+    // The user said yes to remote control - start the daemon now, no extra
+    // question. `gipity build` keeps it running on future runs.
+    startDaemon();
+    console.log('');
     // 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' });
+    const autostartOs = await confirm('  Also start at OS login', { default: 'yes' });
     if (autostartOs) {
         try {
             const res = installAutostart();
@@ -152,9 +137,7 @@ export async function runRelaySetup(opts) {
                     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(res.summary)}`);
-            }
+            // Success is silent - the Done line below covers it.
         }
         catch (err) {
             if (err instanceof UnsupportedPlatformError) {
@@ -166,16 +149,15 @@ export async function runRelaySetup(opts) {
         }
     }
     // Diagnostics consent - default on, clearly opt-out. Only ask once.
+    // (No personal data or file paths are ever sent; `gipity relay diagnostics
+    // on|off` flips it later.)
     if (state.getDiagnosticsConsent() === undefined) {
-        const diag = await confirm('  Share anonymous diagnostics (CPU/GPU/memory/disk/versions) to improve reliability?', { default: 'yes' });
+        console.log('');
+        const diag = await confirm('  Share anonymous diagnostics info', { default: 'yes' });
         state.setDiagnosticsConsent(diag);
-        console.log(`  ${dim(diag
-            ? 'Thanks - no personal data or file paths are ever sent. Turn off anytime with `gipity relay diagnostics off`.'
-            : 'Diagnostics off. Turn on anytime with `gipity relay diagnostics on`.')}`);
     }
     console.log('');
-    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(`  ${success(`Done! ${bold(device.name)} is set up. New chats from gipity.ai can now execute here.`)}`);
     console.log('');
     return true;
 }

package/dist/sync.js

@@ -154,7 +154,7 @@ export async function acquireLock(progress) {
             // First time we're forced to wait: open the spinner so the wait is visible
             // (with an elapsed timer) rather than reading as a frozen process.
             if (!waitSpinner) {
-                waitSpinner = progress?.spinner('Waiting for another sync to finish…') ?? null;
+                waitSpinner = progress?.spinner('Waiting for another sync to finish...') ?? null;
             }
             await new Promise(r => setTimeout(r, LOCK_POLL_MS));
         }
@@ -735,9 +735,9 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
     const config = { projectGuid, ignore };
     const p = opts.progress;
     const baseline = readBaseline(projectGuid);
-    p?.phase('Scanning local files…');
+    p?.phase('Scanning local files...');
     const local = walkLocal(root, ignore, baseline.files);
-    p?.phase('Checking Gipity for changes…');
+    p?.phase('Checking Gipity for changes...');
     const remote = await fetchRemote(projectGuid);
     // Ignored paths are invisible on BOTH sides: filtering only the local walk
     // would classify a remote copy as "added" (pull it), then next pass as a
@@ -761,7 +761,7 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
             needHash.push(path);
     }
     if (needHash.length)
-        p?.phase(`Hashing ${needHash.length} file${needHash.length === 1 ? '' : 's'}…`);
+        p?.phase(`Hashing ${needHash.length} file${needHash.length === 1 ? '' : 's'}...`);
     await ensureLocalHashes(root, local, needHash);
     const planned = plan(local, remote, baseline.files);
     if (opts.plan) {
@@ -890,7 +890,7 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
             // Either way we fall through to the single-file recovery below rather than
             // proceeding on a half-empty tree - a partial download must never be
             // mistaken for a complete one.
-            errors.push(`Bulk download incomplete (${err.message}); recovering files individually…`);
+            errors.push(`Bulk download incomplete (${err.message}); recovering files individually...`);
         }
         finally {
             // Settle the bar even if the extracted-byte tally fell short of the
@@ -903,7 +903,7 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
         // an earlier truncated pull.
         const missing = wantedDownloads.filter(a => !downloadedBytes.has(a.path));
         if (missing.length) {
-            p?.phase(`Recovering ${missing.length} file${missing.length === 1 ? '' : 's'} the bulk download dropped…`);
+            p?.phase(`Recovering ${missing.length} file${missing.length === 1 ? '' : 's'} the bulk download dropped...`);
             for (const a of missing) {
                 // Verify against the remote's content hash: the downloads pass records
                 // this sha into the baseline, so bytes that don't match it must be

package/dist/updater/bootstrap.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { LOCAL_DIR, LOCAL_ENTRY, LOCAL_PKG_DIR, writeState, readState } from './state.js';
-import { resolveCommand, spawnSyncCommand } from '../platform.js';
+import { npmInstallGipity, isWedged, resetLocalTree, acquireUpdateLock, releaseUpdateLock } from './install.js';
 export function isBootstrapped() {
     return existsSync(LOCAL_ENTRY);
 }
@@ -20,28 +20,39 @@ export function bootstrap(version, quiet = false) {
     if (!existsSync(pkgJsonPath)) {
         writeFileSync(pkgJsonPath, JSON.stringify({ name: 'gipity-local', private: true, version: '0.0.0' }, null, 2));
     }
+    if (!acquireUpdateLock()) {
+        // A background updater is mid-install; run from the current build now and
+        // pick up the local install on a later invocation.
+        if (!quiet)
+            process.stderr.write(`gipity: another update is in progress - using the currently installed build.\n`);
+        return false;
+    }
     if (!quiet)
         process.stderr.write(`Setting up gipity local install at ~/.gipity/local (one-time)...\n`);
-    // --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 = spawnSyncCommand(resolveCommand('npm'), ['install', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
-        cwd: LOCAL_DIR,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        encoding: 'utf-8',
-    });
-    if (res.status !== 0 || !existsSync(LOCAL_ENTRY)) {
+    let res;
+    try {
+        res = npmInstallGipity(version);
+        if (!res.ok && !res.spawnError && isWedged(res.stderr)) {
+            // Interrupted-install corruption fails every npm run in the dir forever;
+            // wipe the tree and retry once.
+            resetLocalTree();
+            res = npmInstallGipity(version);
+        }
+    }
+    finally {
+        releaseUpdateLock();
+    }
+    if (!res.ok) {
         if (!quiet) {
-            const stderr = (res.stderr || '').toString();
-            const notPublished = /E404|No matching version|notarget/i.test(stderr);
+            const notPublished = /E404|No matching version|notarget/i.test(res.stderr);
             if (notPublished) {
                 process.stderr.write(`gipity v${version} is not yet published to npm - using the currently installed build.\n`);
             }
             else {
-                // res.error (e.g. ENOENT when npm can't be launched) carries the real
-                // cause; res.status is null in that case, so prefer the error message.
-                const firstLine = stderr.split('\n').map(l => l.trim()).find(l => l.length > 0)
-                    || (res.error ? res.error.message : `npm exit ${res.status}`);
+                // res.spawnError (e.g. ENOENT when npm can't be launched) carries the
+                // real cause; res.status is null in that case, so prefer its message.
+                const firstLine = res.stderr.split('\n').map(l => l.trim()).find(l => l.length > 0)
+                    || (res.spawnError ? res.spawnError.message : `npm exit ${res.status}`);
                 const reason = firstLine.length > 160 ? firstLine.slice(0, 157) + '...' : firstLine;
                 process.stderr.write(`gipity: could not set up local install (${reason}). Using the currently installed build.\n`);
             }

package/dist/updater/check.js

@@ -3,7 +3,7 @@ import { createRequire as __cliCreateRequire } from 'module';
 const require = __cliCreateRequire(import.meta.url);
 
 // src/updater/check.ts
-import { appendFileSync, existsSync as existsSync2 } from "fs";
+import { appendFileSync } from "fs";
 
 // src/updater/state.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
@@ -55,6 +55,10 @@ function updatesDisabled() {
   return { disabled: false };
 }
 
+// src/updater/install.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+
 // src/platform.ts
 import { execSync, spawn, spawnSync } from "child_process";
 function resolveCommand(cmd) {
@@ -83,6 +87,56 @@ function spawnSyncCommand(cmd, args = [], options = {}) {
   return spawnSync(cmd, [...args], { windowsHide: true, ...options });
 }
 
+// src/updater/install.ts
+var UPDATE_LOCK = join2(GIPITY_DIR, "update.lock");
+var LOCK_STALE_MS = 10 * 60 * 1e3;
+function npmInstallGipity(version) {
+  const res = spawnSyncCommand(resolveCommand("npm"), ["install", "--no-audit", "--no-fund", "--ignore-scripts", `gipity@${version}`], {
+    cwd: LOCAL_DIR,
+    stdio: ["ignore", "ignore", "pipe"],
+    encoding: "utf-8"
+  });
+  return {
+    ok: res.status === 0 && existsSync2(LOCAL_ENTRY),
+    status: res.status,
+    stderr: (res.stderr || "").toString(),
+    spawnError: res.error
+  };
+}
+var WEDGE_CODES = /\b(ENOTEMPTY|EEXIST|ENOTDIR|EISDIR|EJSONPARSE)\b/;
+function isWedged(stderr) {
+  return WEDGE_CODES.test(stderr);
+}
+function resetLocalTree(dir = LOCAL_DIR) {
+  mkdirSync2(dir, { recursive: true });
+  rmSync(join2(dir, "node_modules"), { recursive: true, force: true });
+  rmSync(join2(dir, "package-lock.json"), { force: true });
+  writeFileSync2(join2(dir, "package.json"), JSON.stringify({ name: "gipity-local", private: true, version: "0.0.0" }, null, 2));
+}
+function acquireUpdateLock(lockPath = UPDATE_LOCK) {
+  mkdirSync2(dirname(lockPath), { recursive: true });
+  try {
+    writeFileSync2(lockPath, String(process.pid), { flag: "wx" });
+    return true;
+  } catch {
+    try {
+      if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+        unlinkSync(lockPath);
+        writeFileSync2(lockPath, String(process.pid), { flag: "wx" });
+        return true;
+      }
+    } catch {
+    }
+    return false;
+  }
+}
+function releaseUpdateLock(lockPath = UPDATE_LOCK) {
+  try {
+    unlinkSync(lockPath);
+  } catch {
+  }
+}
+
 // src/updater/check.ts
 var CHECK_INTERVAL_MS = 4 * 60 * 60 * 1e3;
 function log(line) {
@@ -112,12 +166,24 @@ async function fetchLatestVersion() {
   return json.version;
 }
 function installVersion(version) {
-  const res = spawnSyncCommand(resolveCommand("npm"), ["install", "--silent", "--no-audit", "--no-fund", "--ignore-scripts", `gipity@${version}`], {
-    cwd: LOCAL_DIR,
-    stdio: "ignore"
-  });
-  if (res.error) log(`npm spawn failed: ${res.error.message}`);
-  return res.status === 0 && existsSync2(LOCAL_ENTRY);
+  let res = npmInstallGipity(version);
+  if (!res.ok && !res.spawnError && isWedged(res.stderr)) {
+    log(`wedged install tree detected; wiping node_modules and retrying:
+${res.stderr.trim().slice(-2e3)}`);
+    resetLocalTree();
+    res = npmInstallGipity(version);
+    if (res.ok) log("clean reinstall succeeded");
+  }
+  if (res.ok) return { ok: true };
+  if (res.spawnError) {
+    log(`npm spawn failed: ${res.spawnError.message}`);
+    return { ok: false, detail: res.spawnError.message };
+  }
+  if (res.stderr.trim()) log(`npm stderr (exit ${res.status}):
+${res.stderr.trim().slice(-2e3)}`);
+  if (res.status === 0) return { ok: false, detail: "npm succeeded but the installed package is missing dist/index.js" };
+  const firstLine = res.stderr.split("\n").map((l) => l.trim()).find((l) => l.length > 0) || `npm exit ${res.status}`;
+  return { ok: false, detail: firstLine.length > 160 ? firstLine.slice(0, 157) + "..." : firstLine };
 }
 async function runCheck(opts = {}) {
   const state = readState();
@@ -150,17 +216,27 @@ async function runCheck(opts = {}) {
     log(`up-to-date (current=${current}, latest=${latest})`);
     return { updated: false, reason: "up-to-date" };
   }
+  if (!acquireUpdateLock()) {
+    log("skipped: another update is already in progress");
+    return { updated: false, reason: "another update is already in progress" };
+  }
   log(`upgrading ${current} \u2192 ${latest}`);
-  const ok = installVersion(latest);
   state.lastCheckAt = Date.now();
-  if (ok) {
+  writeState(state);
+  let install;
+  try {
+    install = installVersion(latest);
+  } finally {
+    releaseUpdateLock();
+  }
+  if (install.ok) {
     state.installedVersion = latest;
     state.lastError = null;
     writeState(state);
     log(`upgraded to ${latest}`);
     return { updated: true, from: current, to: latest };
   }
-  state.lastError = `npm install gipity@${latest} failed`;
+  state.lastError = `npm install gipity@${latest} failed` + (install.detail ? `: ${install.detail}` : "");
   writeState(state);
   log(state.lastError);
   return { updated: false, reason: state.lastError };

package/dist/updater/install.js

@@ -0,0 +1,82 @@
+// Shared npm-install runner for the bootstrap and background-update paths,
+// plus recovery for the wedged-tree failure mode and a lock that keeps two
+// updaters out of ~/.gipity/local at the same time.
+import { existsSync, mkdirSync, rmSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { GIPITY_DIR, LOCAL_DIR, LOCAL_ENTRY } from './state.js';
+import { resolveCommand, spawnSyncCommand } from '../platform.js';
+export const UPDATE_LOCK = join(GIPITY_DIR, 'update.lock');
+const LOCK_STALE_MS = 10 * 60 * 1000;
+/**
+ * Run `npm install gipity@<version>` in ~/.gipity/local with stderr captured
+ * so failures carry the real cause (npm --silent suppresses even its error
+ * report, so it is deliberately absent).
+ *
+ * --ignore-scripts: this can run 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.
+ */
+export function npmInstallGipity(version) {
+    const res = spawnSyncCommand(resolveCommand('npm'), ['install', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
+        cwd: LOCAL_DIR,
+        stdio: ['ignore', 'ignore', 'pipe'],
+        encoding: 'utf-8',
+    });
+    return {
+        ok: res.status === 0 && existsSync(LOCAL_ENTRY),
+        status: res.status,
+        stderr: (res.stderr || '').toString(),
+        spawnError: res.error,
+    };
+}
+// An interrupted install (shutdown mid-upgrade, an overlapping npm process)
+// leaves node_modules half-renamed, after which npm fails every install in
+// the dir with one of these until the tree is wiped. Reproduced: ENOTEMPTY
+// renaming node_modules/gipity over a leftover node_modules/.gipity-<hash>
+// staging dir. Deliberately narrow - transient failures (network, registry,
+// E404) must NOT wipe a still-working tree.
+const WEDGE_CODES = /\b(ENOTEMPTY|EEXIST|ENOTDIR|EISDIR|EJSONPARSE)\b/;
+export function isWedged(stderr) {
+    return WEDGE_CODES.test(stderr);
+}
+/** Wipe the local install tree back to a pristine, installable state.
+ *  `dir` is overridable for tests only. */
+export function resetLocalTree(dir = LOCAL_DIR) {
+    mkdirSync(dir, { recursive: true });
+    rmSync(join(dir, 'node_modules'), { recursive: true, force: true });
+    rmSync(join(dir, 'package-lock.json'), { force: true });
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'gipity-local', private: true, version: '0.0.0' }, null, 2));
+}
+/**
+ * Take the cross-process update lock. The shim spawns a detached updater on
+ * every gipity command, so during a long install another invocation would
+ * otherwise start a second npm install in the same dir (a reproduced way to
+ * corrupt it). A lock older than LOCK_STALE_MS is from a dead updater
+ * (machine shutdown mid-install) and is taken over.
+ * `lockPath` is overridable for tests only.
+ */
+export function acquireUpdateLock(lockPath = UPDATE_LOCK) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    try {
+        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+        return true;
+    }
+    catch {
+        try {
+            if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                unlinkSync(lockPath);
+                writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+                return true;
+            }
+        }
+        catch { /* lost the race to another process */ }
+        return false;
+    }
+}
+export function releaseUpdateLock(lockPath = UPDATE_LOCK) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch { /* already gone */ }
+}
+//# sourceMappingURL=install.js.map