clivly 0.3.0-next.2 → 0.3.0-next.4

package/README.md

@@ -12,12 +12,15 @@ For the full integration path, including when to use `start()` versus
 ```bash
 npm install clivly
 
-npx clivly init          # detect your Drizzle schema and print the config plan
-npx clivly init --write  # write clivly.config.ts
-npx clivly ping          # verify CLIVLY_API_KEY + reachability
-npx clivly doctor        # verify clivly.config.ts end-to-end
+npx clivly init          # scaffold config, routes and .env, then pair this machine
+npx clivly login         # pair this machine and write your credentials to .env
+npx clivly status        # check your setup, step by step
+npx clivly dev           # tunnel localhost so remote sync can reach you
+npx clivly push-schema   # report your schema to Clivly without deploying
 ```
 
+`ping` and `doctor` remain as aliases that run subsets of the `status` ladder.
+
 ## Imports
 
 `clivly` is the consolidated public package. The CLI remains available as
@@ -45,6 +48,87 @@ Kysely projects should use a hand-written `fetchPage` source for now.
 Use `--schema <path>` when your Drizzle schema is not in a common location or in
 `drizzle.config.ts`. Re-run with `--force` to overwrite an existing config.
 
+First-class route scaffolding currently exists for:
+
+- Next.js
+- TanStack Start
+- SvelteKit
+- Remix
+- Nuxt
+
+Vue.js apps can still integrate Clivly, but they usually need a manual server
+layer for the tick and verify routes unless they are using Nuxt.
+
+When `init` finishes and `CLIVLY_API_KEY` is still empty, it hands you straight
+into `clivly login` so you don't end up staring at a blank `.env`. That step is
+interactive, so it is skipped automatically when there is no TTY or when `CI` is
+set — and you can always turn it off yourself:
+
+```bash
+npx clivly init --no-login     # scaffold only; pair later with `clivly login`
+npx clivly init --no-browser   # pair, but print the URL instead of opening it
+```
+
+## `clivly login`
+
+```bash
+npx clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
+```
+
+Pairs this machine with a Clivly workspace and writes `CLIVLY_API_KEY` and
+`CLIVLY_SYNC_TRIGGER_SECRET` into your project's `.env`. It creates a pairing
+session, prints (and by default opens) an approval link, and waits while you
+approve it in a signed-in browser. The approval link is always printed, so an
+SSH or headless session can be approved by opening the link elsewhere.
+
+- `--no-browser` — print the approval URL without opening a browser.
+- `--force` — overwrite `.env` values that already have a real value. Without
+  it, existing values are kept and reported as skipped; an empty placeholder
+  (`CLIVLY_API_KEY=`) is always filled in.
+- `--rotate` — rotate the workspace's remote-sync trigger secret instead of
+  revealing the current one. Your already-deployed host app will stop receiving
+  sync triggers until you redeploy it with the new secret.
+
+Before anything is written, the CLI prints which workspace approved the pairing
+and asks you to confirm. Declining writes nothing and exits non-zero. In a
+non-interactive run (no TTY, or `CI` set) the workspace is still printed but
+you are not prompted, so scripted pairing cannot hang.
+
+The pairing endpoints are feature-flagged server-side
+(`CLIVLY_CLI_PAIRING_ENABLED`); if the backend you point at has not enabled
+them, `clivly login` says so and exits non-zero.
+
+> **Running your own Clivly backend?** `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` (a
+> 32-byte hex key) is a **hard production prerequisite** for pairing. The
+> trigger secret is stored encrypted with it, so without the key set on the
+> server, `clivly login` fails with a 500 at the moment it would hand over
+> credentials. Set it before enabling `CLIVLY_CLI_PAIRING_ENABLED`.
+
+## `clivly status`
+
+```bash
+npx clivly status [--verbose] [--config <path>]
+```
+
+Walks your setup one rung at a time — credentials, config, schema, sources,
+connectivity — and stops at the first thing that isn't ready, telling you what
+to do about it. This is the command to reach for when something isn't working.
+
+## `clivly dev`
+
+```bash
+npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
+```
+
+Opens a `cloudflared` tunnel to your local app and registers it with Clivly for
+the length of the session, so remote sync can reach `localhost` while you
+develop. Your dev server is detected from `package.json` scripts, or pass it
+explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_API_KEY` set.
+The override is cleared when the process exits; remote sync is otherwise
+deploy-only.
+
+## `clivly ping` / `clivly doctor`
+
 `clivly ping` reads `CLIVLY_API_KEY` from the environment, sends one heartbeat, and prints a clear ✅/❌ with the resolved org or the failure reason — so you can confirm a connection from the terminal without writing any code. Point it at a non-default backend with `--api-url <url>` (or `CLIVLY_API_URL`).
 
 ```bash

package/core-entity-heuristics.cjs

@@ -22,7 +22,20 @@ const TABLE_PATTERNS = [
 			"attendees",
 			"people",
 			"members",
-			"contacts"
+			"contacts",
+			"students",
+			"pupils",
+			"learners",
+			"patients",
+			"subscribers",
+			"donors",
+			"guests",
+			"residents",
+			"tenants",
+			"applicants",
+			"candidates",
+			"leads",
+			"prospects"
 		]
 	},
 	{

package/core-entity-heuristics.mjs

@@ -21,7 +21,20 @@ const TABLE_PATTERNS = [
 			"attendees",
 			"people",
 			"members",
-			"contacts"
+			"contacts",
+			"students",
+			"pupils",
+			"learners",
+			"patients",
+			"subscribers",
+			"donors",
+			"guests",
+			"residents",
+			"tenants",
+			"applicants",
+			"candidates",
+			"leads",
+			"prospects"
 		]
 	},
 	{

package/drizzle.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_drizzle_meta = require("./drizzle-meta-CM5M73Z4.cjs");
+const require_drizzle_meta = require("./drizzle-meta-BVR1qiyu.cjs");
 let drizzle_orm = require("drizzle-orm");
 let drizzle_orm_pg_core = require("drizzle-orm/pg-core");
 //#region ../sdk/src/drizzle.ts

package/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-BtS0nXcr.cjs";
+import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-CcYne5Je.cjs";
 import { Table } from "drizzle-orm";
 
 //#region ../sdk/src/drizzle.d.ts

package/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-CYMie-BI.mjs";
+import { d as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-DjWzU9gG.mjs";
 import { Table } from "drizzle-orm";
 
 //#region ../sdk/src/drizzle.d.ts

package/drizzle.mjs

@@ -1,4 +1,4 @@
-import { t as DRIZZLE_META } from "./drizzle-meta-1z6Apnt-.mjs";
+import { t as DRIZZLE_META } from "./drizzle-meta-DpMKataU.mjs";
 import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
 import { getTableConfig } from "drizzle-orm/pg-core";
 //#region ../sdk/src/drizzle.ts