clivly 0.9.2 → 0.9.4

package/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-kUHri9yA.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-B74SPOUZ.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-DXV8M_Io.mjs";
+import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-DYBDR939.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
@@ -291,10 +291,37 @@ function addCommand(pm, packages) {
 	};
 }
 //#endregion
+//#region src/tick-route.ts
+/**
+* The tick route's public URL path, and the template `clivly login` writes for
+* it.
+*
+* Every framework the CLI scaffolds mounts the tick handler at the same URL —
+* the *files* differ (`app/api/clivly/tick/route.ts`,
+* `src/routes/api/clivly/tick.ts`, `app/routes/api.clivly.tick.ts`, …) but each
+* one resolves to `/api/clivly/tick`. So this is a constant, not a per-framework
+* lookup, and `clivly dev`, the generated config and the `.env` template can all
+* read from one place instead of repeating the string and drifting.
+*/
+const CLIVLY_TICK_PATH = "/api/clivly/tick";
+/**
+* What `clivly login` writes into `.env` for `CLIVLY_SYNC_TRIGGER_URL`.
+*
+* A visible template beats an empty line: the developer sees the shape they
+* eventually need — a public origin plus the tick path — instead of an unhelpful
+* `CLIVLY_SYNC_TRIGGER_URL=` they have to go and look up.
+*
+* It is safe to ship a truthy non-address here only because the SDK refuses to
+* treat a bracketed value as configured (`isPlaceholderUrl` in
+* `@clivly/sdk/trigger-url`). Change the brackets here and that guard stops
+* matching, so the two must stay in step.
+*/
+const TRIGGER_URL_PLACEHOLDER = `https://<yourDomain.com>${CLIVLY_TICK_PATH}`;
+//#endregion
 //#region src/dev-tunnel.ts
 const CLOUDFLARE_QUICK_TUNNEL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const DEFAULT_PORT = "3000";
-const DEFAULT_ROUTE_PATH = "/api/clivly/tick";
+const DEFAULT_ROUTE_PATH = CLIVLY_TICK_PATH;
 function parseTunnelUrl(chunk) {
 	const match = chunk.match(CLOUDFLARE_QUICK_TUNNEL_REGEX);
 	return match ? match[0] : null;
@@ -1001,7 +1028,7 @@ Usage:
   clivly init [options]           Scaffold Clivly (config, routes, env file) for your app
   clivly add widget [options]     Scaffold the chat-session route
   clivly status [options]         Check your setup, step by step
-  clivly push-schema [options]    Report your schema to Clivly without deploying
+  clivly push-schema [options]    Push schema, custom objects and mappings to Clivly
   clivly dev [options]            Tunnel localhost so remote sync can reach you
   clivly login [options]          Pair this machine and write credentials to your env file
   clivly --version                Print the installed clivly version
@@ -1057,7 +1084,9 @@ Options:
 Usage:
   clivly status [--verbose] [--config <path>] [--env-file <path>]
 
-Runs the setup ladder: credential, reachability, config load, edge-safety,
+Prints two sections. "Workspace" is how far setup has got on Clivly's side,
+computed by the server so the terminal and the dashboard agree. "This project"
+runs the local ladder: credential, reachability, config load, edge-safety,
 setup checks, sync trigger. Read-only — writes nothing.
 
 Options:
@@ -1065,13 +1094,23 @@ Options:
   --config <path>   Path to clivly.config.ts
   --env-file <path> Extra env file to load
 `,
-	"push-schema": `clivly push-schema — report your schema without deploying
+	"push-schema": `clivly push-schema — push everything your config declares
 
 Usage:
   clivly push-schema [--config <path>]
 
-Sends your discovered tables to Clivly so the dashboard can offer them for
-mapping. Reads your config; writes nothing locally.
+Pushes three things to Clivly, without deploying your app:
+  1. Your table and column NAMES, so the dashboard can offer them for mapping.
+     Never row data — discovery is names only.
+  2. The custom object types you declared with \`objectType\`.
+  3. The mappings that make those objects actually receive rows.
+
+Reads your config; writes nothing locally. Safe to re-run — it reports what it
+created, updated, or left alone.
+
+Exits 1 if Clivly refuses your config, most often because an entity would
+overwrite a mapping edited in the dashboard. That makes it usable in CI as a
+schema gate.
 `,
 	dev: `clivly dev — tunnel localhost so remote sync can reach you
 
@@ -1387,15 +1426,23 @@ async function confirmWorkspace(deps, credentials) {
 	return await deps.confirm("Write this workspace's credentials to .env? [y/N] ");
 }
 function credentialEntries(credentials) {
-	return [{
-		key: SECRET_KEY_ENV,
-		value: credentials.apiKey,
-		comment: `Org secret key — ${CREDENTIALS_LOCATION}`
-	}, {
-		key: "CLIVLY_SYNC_TRIGGER_SECRET",
-		value: credentials.triggerSecret,
-		comment: `Signing secret — ${SYNC_SECRET_LOCATION}`
-	}];
+	return [
+		{
+			key: SECRET_KEY_ENV,
+			value: credentials.apiKey,
+			comment: `Org secret key — ${CREDENTIALS_LOCATION}`
+		},
+		{
+			key: "CLIVLY_SYNC_TRIGGER_SECRET",
+			value: credentials.triggerSecret,
+			comment: `Signing secret — ${SYNC_SECRET_LOCATION}`
+		},
+		{
+			key: "CLIVLY_SYNC_TRIGGER_URL",
+			value: TRIGGER_URL_PLACEHOLDER,
+			comment: "Public URL of your tick route — replace <yourDomain.com> once deployed. Local dev: run `clivly dev` instead."
+		}
+	];
 }
 function writeCredentials(options, credentials) {
 	const { deps } = options;
@@ -1860,7 +1907,13 @@ export default createClivlySDK({
 ${sources.join(",\n")},
   },
   syncTrigger: {
-    // The public URL Clivly Cloud calls to trigger a sync — your mounted tick route.
+    // Where Clivly Cloud calls to start a sync — your mounted tick route.
+    //
+    // \`path\` lets the SDK build its own public URL from the hosting platform's
+    // environment (VERCEL_URL, CF_PAGES_URL, RAILWAY_PUBLIC_DOMAIN,
+    // RENDER_EXTERNAL_URL, FLY_APP_NAME), so on those platforms you never have
+    // to set the URL by hand. \`url\` overrides that when you do.
+    path: "${CLIVLY_TICK_PATH}",
     url: process.env.CLIVLY_SYNC_TRIGGER_URL,
     secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
   },
@@ -2860,6 +2913,17 @@ function defaultReadConfigSource(path) {
 		return null;
 	}
 }
+/**
+* Ping Clivly at most once per command, memoised on the context.
+*
+* `clivly status` asks two questions of one response — "did this call reach
+* Clivly" and "how far has this workspace got" — and they must come from the
+* same answer, not two calls that could disagree.
+*/
+function pingOnce(ctx) {
+	ctx.pingResult ??= ctx.connect(ctx.apiKey, ctx.apiUrl);
+	return ctx.pingResult;
+}
 const REASON_HINT = {
 	ok: "",
 	invalid_api_key: "The key was rejected (401). Check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY).",
@@ -2871,7 +2935,7 @@ const REASON_HINT = {
 	network_error: "Could not reach Clivly. Check your network or --api-url."
 };
 const apiKeyStage = {
-	id: "credential",
+	id: "api-key",
 	label: "API key present",
 	run(ctx) {
 		if (ctx.apiKey) return Promise.resolve({
@@ -2886,11 +2950,11 @@ const apiKeyStage = {
 	}
 };
 const reachabilityStage = {
-	id: "application",
+	id: "reachable",
 	label: "Clivly reachable",
 	needs: [apiKeyStage.id],
 	async run(ctx) {
-		const result = await ctx.connect(ctx.apiKey, ctx.apiUrl);
+		const result = await pingOnce(ctx);
 		if (result.ok) {
 			const name = result.org?.name ?? "(unnamed org)";
 			const id = result.org?.id ? ` (${result.org.id})` : "";
@@ -2962,14 +3026,15 @@ const triggerUrlStage = {
 	needs: [configStage.id],
 	run(ctx) {
 		const url = ctx.sdk?.syncTrigger?.url;
-		if (url) return Promise.resolve({
+		if (url && !isPlaceholderUrl(url)) return Promise.resolve({
 			state: "pass",
 			detail: url
 		});
+		const isPlaceholder = url !== void 0;
 		return Promise.resolve({
 			state: "warn",
-			detail: "Not set — remote sync cannot call back into this app.",
-			hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. For local development run `clivly dev` — it opens a tunnel and registers the URL for you. Push-only setups can ignore this."
+			detail: isPlaceholder ? `Still the placeholder (${url}) — remote sync cannot call back into this app.` : "Not set — remote sync cannot call back into this app.",
+			hint: "Replace <yourDomain.com> with your deployed origin, or delete the line — on Vercel, Cloudflare Pages, Railway, Render and Fly the SDK derives the URL from the platform. For local development run `clivly dev`: it opens a tunnel and registers the URL for you, outranking whatever is in .env. Push-only setups can ignore this."
 		});
 	}
 };
@@ -3024,19 +3089,57 @@ function defaultLoadSdk(path) {
 	return loadConfigSdk(path, "doctor");
 }
 //#endregion
+//#region src/workspace-section.ts
+const MARK$1 = {
+	active: "⏳",
+	blocked: "🔒",
+	done: "✅",
+	failed: "❌",
+	skipped: "⏭️ "
+};
+/**
+* The workspace half of `clivly status`, rendered from what the server sent.
+*
+* This module decides nothing about a stage's state — it prints the verdict the
+* server computed. A CLI that computed its own would be a second ladder, which
+* is the drift this whole change removes.
+*
+* "Unavailable" and "nothing is set up" are deliberately different outcomes. An
+* old server, a rejected key and a dead network all mean we could not ask; none
+* of them means the workspace is empty.
+*/
+function workspaceSection(result) {
+	if (!result) return {
+		kind: "unavailable",
+		reason: "Could not reach Clivly."
+	};
+	if (!result.ok) return {
+		kind: "unavailable",
+		reason: result.status === null ? "Could not reach Clivly (no response)." : `Clivly rejected the request — ${result.reason} (HTTP ${result.status}).`
+	};
+	if (!result.workspace) return {
+		kind: "unavailable",
+		reason: "This Clivly server does not report setup progress. Upgrade the server to see it here."
+	};
+	return {
+		kind: "ladder",
+		lines: result.workspace.steps.map((step) => `  ${MARK$1[step.state]} ${step.label}${step.evidence ? `        ${step.evidence}` : ""}`)
+	};
+}
+//#endregion
 //#region src/status.ts
 /** Stage ids each legacy command maps onto. */
 const ALIAS_STAGE_IDS = {
 	status: STATUS_STAGES.map((stage) => stage.id),
-	ping: ["credential", "application"],
+	ping: ["api-key", "reachable"],
 	doctor: [
 		"config",
 		"runtime",
 		"setup-checks"
 	],
 	connect: [
-		"credential",
-		"application",
+		"api-key",
+		"reachable",
 		"config",
 		"trigger-url"
 	]
@@ -3092,6 +3195,13 @@ async function runStatus(options) {
 	};
 	out("\nClivly status\n");
 	const results = await runLadder(stages, ctx);
+	if (selected.has("reachable")) {
+		const section = workspaceSection(ctx.pingResult ? await ctx.pingResult : null);
+		out("\nWorkspace\n");
+		if (section.kind === "ladder") for (const line of section.lines) out(`${line}\n`);
+		else out(`  ⚠️  ${section.reason}\n`);
+	}
+	out("\nThis project\n");
 	for (const result of results) renderStage(result, options.verbose ?? false, out);
 	const code = ladderExitCode(results);
 	if (code !== 0 && results.some((result) => result.state === "pending")) out("\nSetup is incomplete — finish the steps above and re-run.\n");
@@ -3121,6 +3231,7 @@ const KNOWN_COMMANDS = [
 	"init",
 	"status",
 	"push-schema",
+	"add",
 	"dev",
 	"login",
 	"help",
@@ -3477,8 +3588,8 @@ function previewMutations(deps, mutations, options) {
 function printNextSteps(out, authComplete, loginRan, envFile) {
 	out("\nNext steps:\n");
 	out(loginRan ? "  1. Credentials written by `clivly login`\n" : `  1. Add CLIVLY_SECRET_KEY to ${envFile} — create one at\n     ${CREDENTIALS_LOCATION}\n     (the legacy CLIVLY_API_KEY is still accepted)\n`);
-	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
-	out("     Local dev? Run `clivly dev` to open a tunnel, or skip this step until you deploy (remote sync is deploy-only locally).\n");
+	out("  2. Local dev: run `clivly dev` for dashboard-triggered sync\n");
+	out("     It tunnels your app and registers the URL for you — remote sync is\n     deploy-only otherwise, so nothing is broken if you skip it. Once deployed\n     to Vercel/Cloudflare/Railway/Render/Fly the URL is detected automatically;\n     set CLIVLY_SYNC_TRIGGER_URL by hand only for a custom domain.\n");
 	const step = authComplete ? 3 : 4;
 	if (!authComplete) out("  3. Finish resolveUser in the auth/verify route\n");
 	out(`  ${step}. Run \`clivly status\` to see where you are\n`);
@@ -3888,4 +3999,4 @@ if (isEntrypoint(process.argv[1], import.meta.url)) main(process.argv.slice(2)).
 	process.exitCode = code;
 });
 //#endregion
-export { credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };
+export { KNOWN_COMMANDS, credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };

package/integration-state-BK-riZnm.d.cts

@@ -0,0 +1,130 @@
+//#region ../core/src/integration-state.d.ts
+declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+type StepId = (typeof INTEGRATION_STEPS)[number];
+/** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
+type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+/**
+ * @deprecated No longer derived. Liveness is its own dimension — read
+ * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
+ * backwards just because an app stopped running.
+ */
+"disconnected";
+interface RunFact {
+  at: number;
+  message?: string;
+  ok: boolean;
+}
+/**
+ * Where the reporting app is running, as the app itself understands it.
+ *
+ * `unknown` is a real value, not an absence: `detectHostEnvironment` refuses to
+ * guess when nothing places the app, and a bare `node server.js` with no
+ * NODE_ENV must still be able to connect and be shown as itself. Defaulting
+ * such a host to `local_dev` would file a production box's faults under local
+ * development, where nobody would look for them.
+ */
+type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
+interface IntegrationFacts {
+  discoveredTableCount: number;
+  /** The environment the app reported on its last heartbeat. */
+  environment?: HostEnvironment | null;
+  /**
+   * Has this app ever checked in? Distinguishes "never installed" from "was
+   * working, now silent" — the same absent heartbeat means different things,
+   * and only one of them is diagnosed rather than set up.
+   */
+  everConnected: boolean;
+  hasCredential: boolean;
+  /**
+   * The cadence the app said it heartbeats at. Liveness windows are multiples
+   * of this rather than a fixed constant, so an app that deliberately reports
+   * slowly is not called dead for obeying its own configuration.
+   */
+  heartbeatIntervalMs?: number | null;
+  lastHeartbeatAt: number | null;
+  lastRun: RunFact | null;
+  mappedEntityCount: number;
+  now: number;
+  /**
+   * Deployment presence, when this deployment has one. Absent or `http`
+   * transport keeps the cadence-derived behaviour every SDK in the field uses.
+   */
+  presence?: DeploymentPresence | null;
+  /**
+   * Faults the running app diagnosed about itself on its last heartbeat — an
+   * unreadable database, a secret missing from the process environment. These
+   * are what make a reachable app `live_with_issues`; unfinished setup is not.
+   */
+  reportedIssues?: StepProblem[];
+  syncInFlight: boolean;
+  /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
+  triggerConfigured: boolean;
+  warnings: string[];
+  widgetInstalled: boolean;
+}
+interface StepProblem {
+  code: string;
+  fix: string;
+  message: string;
+}
+interface IntegrationStep {
+  blockedBy: StepId | null;
+  evidence: string | null;
+  id: StepId;
+  label: string;
+  problem: StepProblem | null;
+  state: StepState;
+}
+type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+/** Which algorithm decides whether this deployment is up. */
+type PresenceTransport = "websocket" | "http";
+type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+/**
+ * A deployment's connection state as its `PresenceRoom` last persisted it.
+ *
+ * This exists because a socket has an explicit state and a timestamp does not.
+ * Deriving WebSocket liveness from heartbeat age would leave a disconnected app
+ * shown as live for 150 seconds and offline only after ten minutes, which is
+ * the whole reason this transport exists.
+ */
+interface DeploymentPresence {
+  /** Sockets currently accepted in the room. */
+  activeInstanceCount: number;
+  connectionState: PresenceConnectionState;
+  transport: PresenceTransport;
+}
+interface ConnectionLiveness {
+  /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
+  ageLabel: string;
+  ageMs: number | null;
+  environment: HostEnvironment | null;
+  health: ConnectionHealth;
+  /**
+   * Faults on a reachable app. Empty unless `health` is `live_with_issues`.
+   */
+  issues: StepProblem[];
+  /** Present when a deployment-presence record supplied this liveness result. */
+  presence?: Pick<DeploymentPresence, "connectionState" | "transport">;
+  /** Is a heartbeat recent enough to speak for the app as it is right now? */
+  reachable: boolean;
+}
+interface NextAction {
+  command: string | null;
+  envFile: string | null;
+  label: string;
+}
+interface IntegrationState {
+  /**
+   * Is the app running right now. Deliberately alongside `status` rather than
+   * folded into it: a surface must be able to say "setup reached mapping" and
+   * "the app is offline" in the same breath without either overwriting the
+   * other.
+   */
+  liveness: ConnectionLiveness;
+  next: NextAction | null;
+  status: IntegrationStatus;
+  steps: IntegrationStep[];
+}
+//#endregion
+export { IntegrationStep as a, StepProblem as c, IntegrationStatus as i, StepState as l, IntegrationFacts as n, NextAction as o, IntegrationState as r, StepId as s, ConnectionLiveness as t };

package/integration-state-BK-riZnm.d.mts

@@ -0,0 +1,130 @@
+//#region ../core/src/integration-state.d.ts
+declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+type StepId = (typeof INTEGRATION_STEPS)[number];
+/** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
+type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+/**
+ * @deprecated No longer derived. Liveness is its own dimension — read
+ * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
+ * backwards just because an app stopped running.
+ */
+"disconnected";
+interface RunFact {
+  at: number;
+  message?: string;
+  ok: boolean;
+}
+/**
+ * Where the reporting app is running, as the app itself understands it.
+ *
+ * `unknown` is a real value, not an absence: `detectHostEnvironment` refuses to
+ * guess when nothing places the app, and a bare `node server.js` with no
+ * NODE_ENV must still be able to connect and be shown as itself. Defaulting
+ * such a host to `local_dev` would file a production box's faults under local
+ * development, where nobody would look for them.
+ */
+type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
+interface IntegrationFacts {
+  discoveredTableCount: number;
+  /** The environment the app reported on its last heartbeat. */
+  environment?: HostEnvironment | null;
+  /**
+   * Has this app ever checked in? Distinguishes "never installed" from "was
+   * working, now silent" — the same absent heartbeat means different things,
+   * and only one of them is diagnosed rather than set up.
+   */
+  everConnected: boolean;
+  hasCredential: boolean;
+  /**
+   * The cadence the app said it heartbeats at. Liveness windows are multiples
+   * of this rather than a fixed constant, so an app that deliberately reports
+   * slowly is not called dead for obeying its own configuration.
+   */
+  heartbeatIntervalMs?: number | null;
+  lastHeartbeatAt: number | null;
+  lastRun: RunFact | null;
+  mappedEntityCount: number;
+  now: number;
+  /**
+   * Deployment presence, when this deployment has one. Absent or `http`
+   * transport keeps the cadence-derived behaviour every SDK in the field uses.
+   */
+  presence?: DeploymentPresence | null;
+  /**
+   * Faults the running app diagnosed about itself on its last heartbeat — an
+   * unreadable database, a secret missing from the process environment. These
+   * are what make a reachable app `live_with_issues`; unfinished setup is not.
+   */
+  reportedIssues?: StepProblem[];
+  syncInFlight: boolean;
+  /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
+  triggerConfigured: boolean;
+  warnings: string[];
+  widgetInstalled: boolean;
+}
+interface StepProblem {
+  code: string;
+  fix: string;
+  message: string;
+}
+interface IntegrationStep {
+  blockedBy: StepId | null;
+  evidence: string | null;
+  id: StepId;
+  label: string;
+  problem: StepProblem | null;
+  state: StepState;
+}
+type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+/** Which algorithm decides whether this deployment is up. */
+type PresenceTransport = "websocket" | "http";
+type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+/**
+ * A deployment's connection state as its `PresenceRoom` last persisted it.
+ *
+ * This exists because a socket has an explicit state and a timestamp does not.
+ * Deriving WebSocket liveness from heartbeat age would leave a disconnected app
+ * shown as live for 150 seconds and offline only after ten minutes, which is
+ * the whole reason this transport exists.
+ */
+interface DeploymentPresence {
+  /** Sockets currently accepted in the room. */
+  activeInstanceCount: number;
+  connectionState: PresenceConnectionState;
+  transport: PresenceTransport;
+}
+interface ConnectionLiveness {
+  /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
+  ageLabel: string;
+  ageMs: number | null;
+  environment: HostEnvironment | null;
+  health: ConnectionHealth;
+  /**
+   * Faults on a reachable app. Empty unless `health` is `live_with_issues`.
+   */
+  issues: StepProblem[];
+  /** Present when a deployment-presence record supplied this liveness result. */
+  presence?: Pick<DeploymentPresence, "connectionState" | "transport">;
+  /** Is a heartbeat recent enough to speak for the app as it is right now? */
+  reachable: boolean;
+}
+interface NextAction {
+  command: string | null;
+  envFile: string | null;
+  label: string;
+}
+interface IntegrationState {
+  /**
+   * Is the app running right now. Deliberately alongside `status` rather than
+   * folded into it: a surface must be able to say "setup reached mapping" and
+   * "the app is offline" in the same breath without either overwriting the
+   * other.
+   */
+  liveness: ConnectionLiveness;
+  next: NextAction | null;
+  status: IntegrationStatus;
+  steps: IntegrationStep[];
+}
+//#endregion
+export { IntegrationStep as a, StepProblem as c, IntegrationStatus as i, StepState as l, IntegrationFacts as n, NextAction as o, IntegrationState as r, StepId as s, ConnectionLiveness as t };

package/{internal-Df-PtOH_.mjs → internal-CykXpEGk.mjs}

@@ -1,5 +1,5 @@
-import { n as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-D7xmQP4S.mjs";
-import { h as fanOutJoins, m as validateProjection } from "./entity-config-kUHri9yA.mjs";
+import { n as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-CSGJbZlZ.mjs";
+import { h as fanOutJoins, m as validateProjection } from "./entity-config-B74SPOUZ.mjs";
 //#region ../core/src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
 	return {

package/{internal-CwnEG6Wl.cjs → internal-DqduZU3l.cjs}

@@ -1,5 +1,5 @@
-const require_projection = require("./projection-C5244vGa.cjs");
-const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
+const require_projection = require("./projection-Dz6_i1-w.cjs");
+const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
 //#region ../core/src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
 	return {

package/internal-entity-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
+const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;

package/internal-entity-config.mjs

@@ -1,2 +1,2 @@
-import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-kUHri9yA.mjs";
+import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-B74SPOUZ.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/internal-entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
+const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
 const require_mapping_score = require("./mapping-score-CaB3F4Uu.cjs");
 //#region ../core/src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/internal-entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { a as MATERIALIZING_CONCEPTS } from "./entity-config-kUHri9yA.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-B74SPOUZ.mjs";
 import { a as W, c as isTextLike, i as RELATIONSHIP_TIERS, l as isTimestampLike, n as CONCEPT_TIERS, o as isAmbiguous, r as FIELD_TIERS, s as isNumericLike, u as tierFor } from "./mapping-score-C68uAqGB.mjs";
 //#region ../core/src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/internal-mappings-config.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mappings_config = require("./mappings-config-B0RqFLxu.cjs");
+const require_mappings_config = require("./mappings-config-CLyEg0sf.cjs");
 exports.entitiesToMappings = require_mappings_config.entitiesToMappings;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;

package/internal-mappings-config.mjs

@@ -1,2 +1,2 @@
-import { n as mappingsToEntitiesConfig, t as entitiesToMappings } from "./mappings-config-B1b1HVBg.mjs";
+import { n as mappingsToEntitiesConfig, t as entitiesToMappings } from "./mappings-config-DQS_s4dg.mjs";
 export { entitiesToMappings, mappingsToEntitiesConfig };

package/{internal-CDY8g9Ic.d.mts → internal-o2M7FGlR.d.mts}

@@ -36,6 +36,34 @@ declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredS
   joinKey: string;
 }>;
 //#endregion
+//#region ../core/src/projection-sql.d.ts
+/**
+ * SQL generation for projection-backed entities.
+ *
+ * Base and joins are aliased by their ref key (`base`, then each join's `key`),
+ * which is what allows the same table to be joined twice and keeps generated
+ * SQL independent of host table names.
+ *
+ * Pure string generation — no DB access. Identifiers are escaped so output is
+ * deterministic and injection-safe.
+ */
+/** Quote a single identifier part, escaping embedded double-quotes. */
+declare function quoteIdent(name: string): string;
+/**
+ * The identity expression. Composite identities concatenate their parts with
+ * `::`; validation guarantees every part is NOT NULL and non-text, which is
+ * what makes the concatenation collision-free.
+ *
+ * Exported unaliased because two paths need the same expression under different
+ * names: the view compiler aliases it `id`, and the SDK's projection push source
+ * also orders and keyset-paginates by it. Sharing one definition is what keeps
+ * a pushed row's `id` identical to the one the view would have produced.
+ */
+declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionJoins(projection: ProjectionMapping): string[];
+/** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
+declare function compileProjectionFrom(projection: ProjectionMapping): string;
+//#endregion
 //#region ../core/src/projection-validate.d.ts
 /**
  * Validate a projection against the discovered schema. Returns every error
@@ -69,4 +97,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { validateProjection as a, draftErrors as c, suggestJoinConditions as d, fanOutJoins as f, primaryKeyColumns as i, draftToProjection as l, coversUniqueKey as n, ProjectionDraft as o, joinFansOut as p, hasRichMeta as r, describeCardinality as s, columnMetaFor as t, emptyProjectionDraft as u };
+export { joinFansOut as _, validateProjection as a, compileProjectionJoins as c, describeCardinality as d, draftErrors as f, fanOutJoins as g, suggestJoinConditions as h, primaryKeyColumns as i, quoteIdent as l, emptyProjectionDraft as m, coversUniqueKey as n, compileProjectionFrom as o, draftToProjection as p, hasRichMeta as r, compileProjectionIdentity as s, columnMetaFor as t, ProjectionDraft as u };