clivly 0.9.2 → 0.9.4

package/drizzle.mjs

@@ -1,6 +1,77 @@
+import { t as BASE_REF } from "./projection-CSGJbZlZ.mjs";
 import { t as DRIZZLE_META } from "./drizzle-meta-D-5k3n0i.mjs";
+import { a as quoteIdent, n as compileProjectionIdentity, r as compileProjectionJoins, t as compileProjectionFrom } from "./projection-sql-BgnfiGqF.mjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-3kvhkwO7.mjs";
 import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
+//#region ../sdk/src/drizzle-projection.ts
+/** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
+function refToken(ref) {
+	return `${ref.table}.${ref.column}`;
+}
+function refSql(ref) {
+	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
+}
+function parseRef(value) {
+	if (typeof value !== "string") return value;
+	const dot = value.indexOf(".");
+	if (dot <= 0 || dot === value.length - 1) throw new Error(`fromDrizzleProjection: cursorField "${value}" must be a ref token like "base.updated_at".`);
+	return {
+		table: value.slice(0, dot),
+		column: value.slice(dot + 1)
+	};
+}
+/**
+* Refs address tables symbolically — `base` or a join key — never by table name,
+* which is what stops a projection reaching a table it did not declare. An
+* unresolvable ref would otherwise compile to SQL referencing a missing alias
+* and fail at the database with a message that never mentions the config.
+*/
+function assertKnownRef(ref, known, context) {
+	if (!known.has(ref.table)) throw new Error(`fromDrizzleProjection: ${context} names unknown ref "${ref.table}" — expected "${[...known].join("\", \"")}".`);
+}
+function normalizeRows(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("fromDrizzleProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+function fromDrizzleProjection(db, projection, opts) {
+	const client = db;
+	const known = /* @__PURE__ */ new Set([BASE_REF, ...projection.joins.map((j) => j.key)]);
+	if (projection.identity.kind === "base_pk" && projection.identity.column === void 0 && opts.basePkColumn === void 0) throw new Error(`fromDrizzleProjection: projection "${projection.entityKey}" has a base_pk identity with no column — pass { basePkColumn }.`);
+	const cursorRef = parseRef(opts.cursorField);
+	assertKnownRef(cursorRef, known, "cursorField");
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) assertKnownRef(binding.from, known, `field "${field}"`);
+	const identityExpr = compileProjectionIdentity(projection, opts.basePkColumn ?? "");
+	const cursorToken = refToken(cursorRef);
+	const cursorExpr = `CAST(${refSql(cursorRef)} AS timestamptz)`;
+	const cursorRead = `to_char(${cursorExpr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+	const selectItems = [`${identityExpr} AS ${quoteIdent("id")}`, `${cursorRead} AS ${quoteIdent(cursorToken)}`];
+	const emitted = /* @__PURE__ */ new Set([cursorToken]);
+	for (const binding of Object.values(projection.fieldBindings)) {
+		const token = refToken(binding.from);
+		if (emitted.has(token)) continue;
+		emitted.add(token);
+		selectItems.push(`${refSql(binding.from)} AS ${quoteIdent(token)}`);
+	}
+	const head = [
+		`select ${selectItems.join(", ")}`,
+		compileProjectionFrom(projection),
+		...compileProjectionJoins(projection)
+	].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: cursorToken,
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? sql` where (${sql.raw(cursorExpr)}, ${sql.raw(identityExpr)}) > (${since.time.toISOString()}::timestamptz, ${since.id})` : sql``;
+			const query = sql`${sql.raw(head)}${where} order by ${sql.raw(cursorExpr)} asc, ${sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
 //#region ../sdk/src/drizzle.ts
 function inferIdField(table) {
 	const columns = getTableColumns(table);
@@ -13,14 +84,6 @@ function inferIdField(table) {
 	const kind = primaryKeys.length === 0 ? "no" : "a composite";
 	throw new Error(`fromDrizzle: table "${getTableName(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
 }
-/**
-* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
-* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
-* `idField` defaults to the table's single-column primary key.
-*
-* `drizzle-orm` is an optional peer dependency — installed only when you import
-* `@clivly/sdk/drizzle`.
-*/
 function fromDrizzle(db, table, opts) {
 	const drizzleDb = db;
 	const idField = opts.idField ?? inferIdField(table);
@@ -37,7 +100,8 @@ function fromDrizzle(db, table, opts) {
 		entity: opts.entity,
 		cursorField: cursorColumnName,
 		idField: idColumnName,
-		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit),
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType }
 	};
 	const uniqueConstraints = buildUniqueConstraints(table);
 	const meta = {
@@ -74,4 +138,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };

package/{entity-config-DtBsl2MQ.cjs → entity-config-7sGCk_nw.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-C5244vGa.cjs");
+const require_projection = require("./projection-Dz6_i1-w.cjs");
 //#region ../core/src/schema-meta.ts
 /**
 * Accessors over a discovered table's schema-v2 metadata.

package/{entity-config-kUHri9yA.mjs → entity-config-B74SPOUZ.mjs}

@@ -1,4 +1,4 @@
-import { a as _enum, c as literal, d as strictObject, f as string, i as projectionSchema, l as number, o as array, p as union, r as identityRefs, s as boolean, t as BASE_REF, u as record } from "./projection-D7xmQP4S.mjs";
+import { a as _enum, c as literal, d as strictObject, f as string, i as projectionSchema, l as number, o as array, p as union, r as identityRefs, s as boolean, t as BASE_REF, u as record } from "./projection-CSGJbZlZ.mjs";
 //#region ../core/src/schema-meta.ts
 /**
 * Accessors over a discovered table's schema-v2 metadata.

package/index.cjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 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");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-D4Wp_uxb.cjs");
+const require_sdk = require("./sdk-CM1UO-I7.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -292,10 +292,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;
@@ -1002,7 +1029,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
@@ -1058,7 +1085,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:
@@ -1066,13 +1095,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
 
@@ -1388,15 +1427,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;
@@ -1861,7 +1908,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,
   },
@@ -2861,6 +2914,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).",
@@ -2872,7 +2936,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({
@@ -2887,11 +2951,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})` : "";
@@ -2963,14 +3027,15 @@ const triggerUrlStage = {
 	needs: [configStage.id],
 	run(ctx) {
 		const url = ctx.sdk?.syncTrigger?.url;
-		if (url) return Promise.resolve({
+		if (url && !require_sdk.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."
 		});
 	}
 };
@@ -3025,19 +3090,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"
 	]
@@ -3093,6 +3196,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");
@@ -3122,6 +3232,7 @@ const KNOWN_COMMANDS = [
 	"init",
 	"status",
 	"push-schema",
+	"add",
 	"dev",
 	"login",
 	"help",
@@ -3478,8 +3589,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`);
@@ -3889,6 +4000,7 @@ if (isEntrypoint(process.argv[1], require("url").pathToFileURL(__filename).href)
 	process.exitCode = code;
 });
 //#endregion
+exports.KNOWN_COMMANDS = KNOWN_COMMANDS;
 exports.credentialsMissing = credentialsMissing;
 exports.main = main;
 exports.nearestCommand = nearestCommand;

package/index.d.cts

@@ -58,6 +58,7 @@ interface ProbeHit {
 }
 //#endregion
 //#region src/index.d.ts
+declare const KNOWN_COMMANDS: readonly ["init", "status", "push-schema", "add", "dev", "login", "help", "ping", "doctor", "connect"];
 declare function nearestCommand(input: string): string | undefined;
 interface AddDeps {
   fileExists: (path: string) => boolean;
@@ -117,4 +118,4 @@ declare function runInit(options: RunInitOptions): Promise<number>;
 declare function runInitFromArgv(argv: string[], cwd: string): Promise<number>;
 declare function main(argv: string[]): Promise<number>;
 //#endregion
-export { AddDeps, RunInitOptions, credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };
+export { AddDeps, KNOWN_COMMANDS, RunInitOptions, credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };

package/index.d.mts

@@ -58,6 +58,7 @@ interface ProbeHit {
 }
 //#endregion
 //#region src/index.d.ts
+declare const KNOWN_COMMANDS: readonly ["init", "status", "push-schema", "add", "dev", "login", "help", "ping", "doctor", "connect"];
 declare function nearestCommand(input: string): string | undefined;
 interface AddDeps {
   fileExists: (path: string) => boolean;
@@ -117,4 +118,4 @@ declare function runInit(options: RunInitOptions): Promise<number>;
 declare function runInitFromArgv(argv: string[], cwd: string): Promise<number>;
 declare function main(argv: string[]): Promise<number>;
 //#endregion
-export { AddDeps, RunInitOptions, credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };
+export { AddDeps, KNOWN_COMMANDS, RunInitOptions, credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };