fix(appkit): non-blocking typegen on Analytics

[atilafassina]

Summary

Makes type generation warehouse-aware and non-blocking by default.

Previously typegen ran DESCRIBE QUERY blind to the warehouse's lifecycle state and to the SDK's real error shapes, producing two wrong outcomes — a STOPPED warehouse was misread as "empty" (every query emitted result: unknown and the known-good types were discarded), and an unreachable host was treated as a fatal build failure. On top of that it blocked npm install / npm dev on a cold warehouse and could crash uncaught.

After this PR:

• Non-blocking is the default (appkit generate-types, the dev server, postinstall / predev). Typegen writes the best types it can immediately — the last-known-good cached type where the SQL is unchanged, otherwise result: unknown — and never blocks on, or fails because of, the warehouse. Real types then refresh in the background.
• --block (CI / prebuild) waits for readiness and produces accurate types, failing fast only when the warehouse genuinely can't serve them (deleted) or the SQL is wrong.

Behavior

A pure policy function maps (warehouse state × mode) to an action; the orchestration executes it.

Warehouse state	non-blocking (default)	blocking (--block)
RUNNING	degrade now; describe in background	describe
STARTING	degrade now; wait → describe in background	wait → describe
STOPPED / STOPPING	degrade now; start → wait → describe in background	start → wait → describe
DELETED / DELETING	degrade, leave as-is (no error)	fatal (exit 1)
Unreachable (connectivity)	degrade (reuse cache or unknown)	degrade — never fatal
SQL error (DESCRIBE … FAILED)	unknown; reported	throws → fails build

• Degrading reuses the last-known-good cached type when the SQL hash is unchanged, else emits result: unknown. Degraded types are never persisted, so a transient outage can't poison the cache and a fixed query recovers on the next run.
• The generated .d.ts is always written before any throw.
• The background refresh mechanism differs by host: the dev Vite plugin runs an in-process, single-flight, abortable watch (covering a RUNNING warehouse too); the CLI spawns a detached --block worker behind a single-flight lock (stale-stealable after 6 min), so postinstall returns instantly and types refresh once the worker finishes.

Key pieces

• preflight.ts — pure decidePreflight(state, mode) policy; fully table-tested, no I/O.
• warehouse-status.ts — getWarehouseState, startWarehouse, and a bounded, abortable waitUntilRunning (exp backoff; treatStoppedAsTransient so it polls through the STOPPED → STARTING transition right after a start).
• query-registry.ts — pre-flight orchestration + per-query classification (ok / syntax / connectivity / non-terminal → degrade), with a per-query backstop so a mid-run state change can't resurface the "empty" misclassification.
• vite-plugin.ts — dev: instant degrade in the foreground, background lifecycle (including a RUNNING warehouse) with single-flight coalescing and abort-on-shutdown.
• cli/commands/generate-types.ts + spawn-lock.ts — non-blocking CLI degrades then spawns the detached worker behind the lock; positive --block flag (replaces --no-block); hidden internal --worker-lock.
• Connectivity classifier now recognizes the SDK's DNS wrapper ("Can't connect to <url>" carrying numeric code 500) → degrade, not fatal.
• template/package.json — postinstall / predev → non-blocking default; prebuild → --block; dropped the redundant typegen:no-block script.
• Docs — type-generation.md documents the non-blocking default and --block.

Testing

• Exhaustive table-driven tests for the pure policy (every state × mode).
• Warehouse-status: state mapping, connectivity-vs-fatal classification, bounded-wait backoff / timeout via fake timers.
• Orchestration: degrade-all skips describes; wait-then-proceed; start → wait → describe; fatal throws after the .d.ts is written; the per-query non-terminal backstop.
• Dev plugin: instant degrade, background-describes RUNNING / STARTING / STOPPED, swallows DELETED, aborts on shutdown.
• CLI: spawns exactly one detached worker; the single-flight lock prevents stacking; a stale lock is stolen; spawn failure is non-fatal; the worker releases the lock.
• Full suite green (appkit + shared); build:package + publint clean.

---

This pull request and its description were written by Isaac.

[Copilot]

Pull request overview

This PR prevents analytics type generation from crashing when the SQL warehouse is unreachable by distinguishing connectivity failures (non-fatal; reuse cached types or emit unknown) from genuine SQL errors (warehouse reachable but DESCRIBE QUERY returns FAILED, which can be treated as fatal by callers).

Changes:

• Classifies per-query DESCRIBE QUERY outcomes into success, syntax error (FAILED), connectivity error (request rejected), and empty result; only successful results are cached.
• Updates the typegen entrypoint to throw a typed TypegenSyntaxError only when genuine SQL errors occur, and only after writing the .d.ts output.
• Adds/updates tests to cover “warehouse down doesn’t crash” and caching behavior during connectivity vs syntax failures.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/appkit/src/type-generator/types.ts	Adds QuerySyntaxError and QueryGenerationResult types to represent non-fatal vs fatal describe outcomes.
packages/appkit/src/type-generator/query-registry.ts	Implements failure classification, prevents caching unknown, reuses prior cached types on connectivity failures, and returns {schemas, syntaxErrors}.
packages/appkit/src/type-generator/index.ts	Introduces TypegenSyntaxError and gates throwing on syntaxErrors after emitting .d.ts.
packages/appkit/src/type-generator/tests/index.test.ts	Adds tests asserting syntax errors throw (after writing output) while connectivity failures do not throw.
packages/appkit/src/type-generator/tests/generate-queries.test.ts	Expands coverage for caching rules, offline behavior, empty result handling, and syntax error reporting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.