db-drifter-cli 0.3.0 → 0.3.1

package/README.md

@@ -18,7 +18,7 @@ node cli/src/index.js --help
 ```sh
 dbd auth                    # browser sign-in; auto-selects your workspace (prompts if you have several)
 
-dbd use staging             # pick the source database (auto if the workspace has just one)
+dbd use staging             # pick the source DB (auto if the workspace has just one)
 
 dbd branch pr-42            # create an isolated, writable database and print its DSN
 # postgresql://you@wire.db-drifter.com/ws1.staging.pr-42?sslmode=require
@@ -28,17 +28,17 @@ dbd branch rm pr-42                         # throw it away
 ```
 
 `dbd auth` auto-selects your workspace when you have one (and prompts a
-radio list when you have several), then remembers a single source database.
-`dbd branch <name>` creates an isolated overlay on that source and prints its
+radio list when you have several), then remembers a single source DB.
+`dbd branch <name>` creates an isolated overlay on that source DB and prints its
 connection string — hand it straight to your app, tests or an agent. Run
-`dbd add-source <name> <url>` first if you're an admin connecting a database.
+`dbd add-source-db <name> <url>` first if you're an admin connecting a database.
 
 ```sh
 dbd conn staging                           # the `main` branch DSN
 dbd conn staging --branch pr-42
 dbd sql staging "select count(*) from orders"
 dbd branch ls
-dbd use staging                            # default source database for `dbd branch`
+dbd use staging                            # default source DB for `dbd branch`
 ```
 
 ## All commands
@@ -46,12 +46,12 @@ dbd use staging                            # default source database for `dbd br
 ```
 auth [--username U] [--password P] [--token T]   log in (device flow by default)
 logout | whoami
-use <source-db>                                  set the default source database
+use <source-db>                                  set the default source DB
 
-add-source <name> <url>                          connect a source database (admin)
+add-source-db <name> <url>                          connect a source DB (admin)
 source-db ls | add <name> <url> | rm <name> | reset <name>
 
-branch <name> [--source S] [--ttl-days N]        create a branch, print its DSN
+branch <name> [--source-db S] [--ttl-days N]        create a branch, print its DSN
 branch ls | rm <name>
 
 conn <source-db> [--branch <name>]               print a connection string
@@ -95,6 +95,37 @@ as `DATABASE_URL`, and deletes it on PR close. Ephemeral branches also carry a
 TTL; the server's nightly cleanup removes expired branches and drops their
 overlays.
 
-The token can create/delete branches (scope `branch`) but not add source
-databases (scope `admin`) — CI can provision its own database without being able
+The token can create/delete branches (scope `branch`) but not add source DBs (scope `admin`) — CI can provision its own database without being able
 to widen access.
+
+## Releasing
+
+The package lives in `cli/` and is published as **`db-drifter-cli`** (it installs
+the `dbd` command). Publishing needs your npm 2FA:
+
+```sh
+cd cli
+npm version patch            # or minor / major — bumps package.json + tags
+npm publish --otp=<6-digit code>
+git push --follow-tags
+```
+
+`publishConfig` pins the public registry and `access: public`, so no extra flags
+are needed. After publishing, `latest` follows the highest version — check with:
+
+```sh
+npm view db-drifter-cli dist-tags
+```
+
+Sanity-check the tarball before releasing (it should include `src/index.js`):
+
+```sh
+npm pack --dry-run
+```
+
+If you ever need to publish from a repo checkout before npm has it:
+
+```sh
+npm i -g ./cli          # installs `dbd` from the local folder
+node ./cli/src/index.js --help
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "db-drifter-cli",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "db_drifter command-line client — connect a source database, create isolated branches, print connection strings.",
 	"type": "module",
 	"bin": { "dbd": "src/index.js" },

package/src/index.js

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 const DEFAULT_API = "https://app.db-drifter.com";
-const VERSION = "0.3.0";
+const VERSION = "0.3.1";
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -137,7 +137,7 @@ async function workspaceDetail(api, ws) {
 async function findSourceDb(api, ws, name) {
 	const v = await workspaceDetail(api, ws);
 	const found = (v?.source_dbs ?? []).find((s) => s.name === name);
-	if (!found) throw new Error(`source database "${name}" not found`);
+	if (!found) throw new Error(`source DB "${name}" not found`);
 	return found;
 }
 
@@ -148,15 +148,15 @@ async function resolveSourceDb(cfg, api, ws, explicit) {
 	const v = await workspaceDetail(api, ws);
 	const names = (v?.source_dbs ?? []).map((s) => s.name);
 	if (names.length === 1) return names[0];
-	if (names.length === 0) throw new Error("no source database yet; run `dbd add-source <name> <url>`");
+	if (names.length === 0) throw new Error("no source DB yet; run `dbd add-source-db <name> <url>`");
 	const sds = v.source_dbs;
-	const picked = await chooseRadio("Select a source database:", sds, (s) => s.name);
+	const picked = await chooseRadio("Select a source DB:", sds, (s) => s.name);
 	if (picked) {
 		cfg.source_db = picked.name;
 		saveConfig(cfg);
 		return picked.name;
 	}
-	throw new Error(`which source database? pass --source <name> (available: ${names.join(", ")})`);
+	throw new Error(`which source DB? pass --source-db <name> (available: ${names.join(", ")})`);
 }
 
 async function connFor(api, ws, sourceDb, branch) {
@@ -169,6 +169,9 @@ async function connFor(api, ws, sourceDb, branch) {
 
 const enc = (s) => encodeURIComponent(s);
 
+/** The source DB flag: `--source-db` (with `--source` accepted for back-compat). */
+const sourceFlag = (args) => str(args.flags["source-db"]) ?? sourceFlag(args);
+
 // ---------------------------------------------------------------------------
 // Args
 // ---------------------------------------------------------------------------
@@ -293,7 +296,7 @@ async function chooseRadio(question, items, label) {
 
 /**
  * After login, pick a workspace (auto if there is only one, otherwise prompt)
- * and remember a single source database when the workspace has exactly one.
+ * and remember a single source DB when the workspace has exactly one.
  */
 async function settleContext(cfg, api) {
 	try {
@@ -321,7 +324,7 @@ async function settleContext(cfg, api) {
 		if (sds.length === 1) {
 			cfg.source_db = sds[0].name;
 			saveConfig(cfg);
-			console.log(`using source database "${sds[0].name}"`);
+			console.log(`using source DB "${sds[0].name}"`);
 		}
 	} catch {
 		/* best effort — never fail a login over this */
@@ -410,7 +413,7 @@ async function cmdWorkspace(cfg, args) {
 	throw new Error("usage: dbd workspace ls | use <id>");
 }
 
-/** `dbd source-db …` and the `dbd add-source` / `dbd use` aliases. */
+/** `dbd source-db …` and the `dbd add-source-db` / `dbd use` aliases. */
 async function cmdSourceDb(cfg, args, verb) {
 	const api = apiFor(cfg);
 	const ws = await resolveWorkspace(cfg, api);
@@ -425,19 +428,19 @@ async function cmdSourceDb(cfg, args, verb) {
 		return;
 	}
 	if (sub === "add") {
-		// `dbd add-source <name> <url>` or `dbd source-db add <name> <url>`
+		// `dbd add-source-db <name> <url>` or `dbd source-db add <name> <url>`
 		const name = verb ? args.pos[0] : args.pos[1];
 		const url = verb ? args.pos[1] : args.pos[2];
 		await api.post(`/api/workspaces/${ws}/source-dbs`, { name, url });
 		cfg.source_db = name;
 		saveConfig(cfg);
-		console.log(`source database "${name}" added (with a \`main\` branch)`);
+		console.log(`source DB "${name}" added (with a \`main\` branch)`);
 		return;
 	}
 	if (sub === "rm") {
 		const name = verb ? args.pos[0] : args.pos[1];
 		await api.del(`/api/workspaces/${ws}/source-dbs/${enc(name)}`);
-		console.log(`source database "${name}" deleted`);
+		console.log(`source DB "${name}" deleted`);
 		return;
 	}
 	if (sub === "reset") {
@@ -449,7 +452,7 @@ async function cmdSourceDb(cfg, args, verb) {
 	throw new Error("usage: dbd source-db ls | add <name> <url> | rm <name> | reset <name>");
 }
 
-/** `dbd use <source-db>` — set the default source database. */
+/** `dbd use <source-db>` — set the default source DB. */
 async function cmdUse(cfg, args) {
 	const api = apiFor(cfg);
 	const ws = await resolveWorkspace(cfg, api);
@@ -458,14 +461,14 @@ async function cmdUse(cfg, args) {
 		const sds = (await workspaceDetail(api, ws))?.source_dbs ?? [];
 		if (sds.length === 1) name = sds[0].name;
 		else if (sds.length > 1) {
-			name = (await chooseRadio("Select a source database:", sds, (s) => s.name))?.name;
+			name = (await chooseRadio("Select a source DB:", sds, (s) => s.name))?.name;
 		}
 	}
 	if (!name) throw new Error("usage: dbd use <source-db>");
 	await findSourceDb(api, ws, name); // validate
 	cfg.source_db = name;
 	saveConfig(cfg);
-	console.log(`current source database: ${name}`);
+	console.log(`current source DB: ${name}`);
 }
 
 async function cmdBranch(cfg, args) {
@@ -475,7 +478,7 @@ async function cmdBranch(cfg, args) {
 
 	// `dbd branch ls`
 	if (sub === "ls") {
-		const src = await resolveSourceDb(cfg, api, ws, str(args.flags.source));
+		const src = await resolveSourceDb(cfg, api, ws, sourceFlag(args));
 		const sd = await findSourceDb(api, ws, src);
 		for (const b of sd.branches ?? []) {
 			console.log(
@@ -486,7 +489,7 @@ async function cmdBranch(cfg, args) {
 	}
 	// `dbd branch rm <name>`
 	if (sub === "rm") {
-		const src = await resolveSourceDb(cfg, api, ws, str(args.flags.source));
+		const src = await resolveSourceDb(cfg, api, ws, sourceFlag(args));
 		await api.del(`/api/workspaces/${ws}/source-dbs/${enc(src)}/branches/${enc(args.pos[1])}`);
 		console.log(`branch "${args.pos[1]}" deleted`);
 		return;
@@ -495,7 +498,7 @@ async function cmdBranch(cfg, args) {
 	const explicitCreate = sub === "create";
 	const name = explicitCreate ? args.pos[1] : args.pos[0];
 	if (!name) throw new Error("usage: dbd branch <name>  (or: dbd branch ls | rm <name>)");
-	const src = await resolveSourceDb(cfg, api, ws, str(args.flags.source));
+	const src = await resolveSourceDb(cfg, api, ws, sourceFlag(args));
 	const body = { name };
 	const ttl = num(args.flags["ttl-days"]);
 	if (ttl !== undefined) body.ttl_days = ttl;
@@ -560,12 +563,12 @@ Usage: dbd [--api-url <url>] <command> [args]
 
   auth [--username U] [--password P] [--token T]   log in (device flow by default)
   whoami
-  use <source-db>                                  set the default source database
+  use <source-db>                                  set the default source DB
 
-  add-source <name> <url>                          connect a source database (admin)
+  add-source-db <name> <url>                       connect a source DB (admin)
   source-db ls | add <name> <url> | rm <name> | reset <name>
 
-  branch <name> [--source S] [--ttl-days N]        create a branch, print its DSN
+  branch <name> [--source-db S] [--ttl-days N]     create a branch, print its DSN
   branch ls | rm <name>
 
   conn <source-db> [--branch <name>]               print a connection string
@@ -613,11 +616,11 @@ async function main() {
 		case "workspace":
 			await cmdWorkspace(cfg, rest);
 			break;
+		case "add-source-db":
 		case "add-source":
 			await cmdSourceDb(cfg, rest, "add");
 			break;
 		case "source-db":
-		case "source":
 			await cmdSourceDb(cfg, rest);
 			break;
 		case "branch":