@mediamonks/canopy-cli 0.5.1 → 0.7.0

package/dist/{db-BW1ZolWn.mjs → db-BkUmbGgx.mjs}

@@ -1,5 +1,6 @@
-import { a as projectFlagArgs, s as resolveProject } from "./site-BJjoePQS.mjs";
-import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-DThlyHgo.mjs";
+import { c as resolveProject, o as projectFlagArgs } from "./site-BUlQR117.mjs";
+import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-D8HxX0Ng.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-I1adj0z2.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";
@@ -12,15 +13,24 @@ import * as p from "@clack/prompts";
 * snapshot  store a dump server-side (restorable from CLI or dashboard)
 * snapshots list stored snapshots
 * restore   replace ALL project data from a snapshot or a local .sql file
+* migrate   apply pending schema migrations (docs/13-migrations-and-drizzle.md)
 *
 * The project comes from canopy.json in the current directory, or
 * --project <slug>.
 */
+/** Shared flag: operate on the staging channel's database (docs/14). */
+const stagingFlagArgs = { staging: {
+	type: "boolean",
+	default: false,
+	description: "Target the staging channel's database instead of live"
+} };
+const channelOf = (args) => args.staging ? "staging" : "live";
+const channelNote = (args) => args.staging ? " [staging]" : "";
 const formatSize = (bytes) => bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} kB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 const dbCommand = defineCommand({
 	meta: {
 		name: "db",
-		description: "Data tools: pull, snapshot, snapshots, restore"
+		description: "Data tools: pull, snapshot, snapshots, restore, migrate"
 	},
 	subCommands: {
 		pull: defineCommand({
@@ -30,6 +40,7 @@ const dbCommand = defineCommand({
 			},
 			args: {
 				...projectFlagArgs,
+				...stagingFlagArgs,
 				out: {
 					type: "string",
 					description: "Output file (defaults to <slug>-<timestamp>.sql)"
@@ -39,9 +50,9 @@ const dbCommand = defineCommand({
 				const { slug } = resolveProject(args);
 				const out = args.out ?? `${slug}-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replaceAll(/[:T]/g, "-")}.sql`;
 				const spin = p.spinner();
-				spin.start(`Exporting ${slug}…`);
+				spin.start(`Exporting ${slug}${channelNote(args)}…`);
 				try {
-					const { url } = await apiDataRequest("POST", "/db/export", slug);
+					const { url } = await apiDataRequest("POST", "/db/export", slug, void 0, void 0, channelOf(args));
 					const download = await fetch(url);
 					if (!download.ok) throw new Error(`Download failed (HTTP ${download.status}).`);
 					const sql = Buffer.from(await download.arrayBuffer());
@@ -58,14 +69,17 @@ const dbCommand = defineCommand({
 				name: "snapshot",
 				description: "Store a dump server-side (restorable anytime)"
 			},
-			args: projectFlagArgs,
+			args: {
+				...projectFlagArgs,
+				...stagingFlagArgs
+			},
 			run: reportErrors("db snapshot", async ({ args }) => {
 				const { slug } = resolveProject(args);
 				const spin = p.spinner();
-				spin.start(`Snapshotting ${slug}…`);
+				spin.start(`Snapshotting ${slug}${channelNote(args)}…`);
 				let created;
 				try {
-					({snapshot: created} = await apiDataRequest("POST", "/db/snapshots", slug));
+					({snapshot: created} = await apiDataRequest("POST", "/db/snapshots", slug, void 0, void 0, channelOf(args)));
 				} catch (err) {
 					spin.error("Snapshot failed.");
 					throw err;
@@ -79,10 +93,13 @@ const dbCommand = defineCommand({
 				name: "snapshots",
 				description: "List stored snapshots"
 			},
-			args: projectFlagArgs,
+			args: {
+				...projectFlagArgs,
+				...stagingFlagArgs
+			},
 			run: reportErrors("db snapshots", async ({ args }) => {
 				const { slug } = resolveProject(args);
-				const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug);
+				const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug, void 0, void 0, channelOf(args));
 				if (snapshots.length === 0) {
 					console.log(`No snapshots for ${slug} yet — run \`canopy db snapshot\`.`);
 					return;
@@ -97,6 +114,7 @@ const dbCommand = defineCommand({
 			},
 			args: {
 				...projectFlagArgs,
+				...stagingFlagArgs,
 				file: {
 					type: "positional",
 					description: "Local .sql dump to restore from",
@@ -118,7 +136,7 @@ const dbCommand = defineCommand({
 				let snapshotKey = args.snapshot;
 				if (!snapshotKey && !file) {
 					requireTty("pass a local .sql dump or --snapshot <key>.");
-					const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug);
+					const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug, void 0, void 0, channelOf(args));
 					if (snapshots.length === 0) throw new Error(`No snapshots for ${slug} — run \`canopy db snapshot\` first, or pass a local .sql dump.`);
 					snapshotKey = unwrap(await p.select({
 						message: `Snapshot to restore into ${slug}`,
@@ -131,15 +149,53 @@ const dbCommand = defineCommand({
 				}
 				if (!args.yes) {
 					requireTty("pass --yes to restore without confirmation.");
-					if (unwrap(await p.text({ message: `Restore will REPLACE all current data in "${slug}" with ${snapshotKey ?? file}. Type the slug to confirm.` })).trim() !== slug) {
+					if (unwrap(await p.text({ message: `Restore will REPLACE all current data in "${slug}"${channelNote(args)} with ${snapshotKey ?? file}. Type the slug to confirm.` })).trim() !== slug) {
 						p.cancel("Aborted.");
 						return;
 					}
 				}
 				const restoreContext = { action: `restore "${slug}" from ${snapshotKey ?? file}` };
-				if (snapshotKey) await withContext(apiDataRequest("POST", "/db/restore", slug, { snapshot: snapshotKey }), restoreContext);
-				else if (file) await withContext(apiDataRequest("POST", "/db/restore", slug, readFileSync(file, "utf8"), "application/sql"), restoreContext);
-				p.log.success(`Restored ${slug}.`);
+				if (snapshotKey) await withContext(apiDataRequest("POST", "/db/restore", slug, { snapshot: snapshotKey }, void 0, channelOf(args)), restoreContext);
+				else if (file) await withContext(apiDataRequest("POST", "/db/restore", slug, readFileSync(file, "utf8"), "application/sql", channelOf(args)), restoreContext);
+				p.log.success(`Restored ${slug}${channelNote(args)}.`);
+			})
+		}),
+		migrate: defineCommand({
+			meta: {
+				name: "migrate",
+				description: "Apply pending schema migrations to the project database"
+			},
+			args: {
+				...projectFlagArgs,
+				...stagingFlagArgs,
+				plan: {
+					type: "boolean",
+					default: false,
+					description: "Dry run: list pending migrations without applying anything"
+				}
+			},
+			run: reportErrors("db migrate", async ({ args }) => {
+				const { dir, slug } = resolveProject(args);
+				const files = readMigrationFiles(dir);
+				if (files === void 0) throw new Error("No migrations directory configured — set \"migrations\" in canopy.json (e.g. {\"migrations\": \"./migrations\"}, pointing at your drizzle-kit output).");
+				if (args.plan) {
+					const result = await withContext(migrateProject(slug, files, true, channelOf(args)), { action: `plan migrations for "${slug}"${channelNote(args)}` });
+					if (result.pending.length === 0) console.log(`Nothing pending (${result.applied.length} applied previously).`);
+					else for (const name of result.pending) console.log(`pending ${name}`);
+					for (const line of describeMigrateResult(result)) console.log(line);
+					return;
+				}
+				const spin = p.spinner();
+				spin.start(`Migrating ${slug}${channelNote(args)}…`);
+				let result;
+				try {
+					result = await withContext(migrateProject(slug, files, false, channelOf(args)), { action: `migrate "${slug}"${channelNote(args)}` });
+				} catch (err) {
+					spin.error("Migrate failed.");
+					throw err;
+				}
+				spin.stop(result.appliedNow.length === 0 ? `Nothing pending for ${slug}.` : `Applied ${result.appliedNow.length} migration(s) to ${slug}.`);
+				for (const line of describeMigrateResult(result)) console.log(`  ${line}`);
 			})
 		})
 	}

package/dist/{deploy-alC2--pZ.mjs → deploy-BcczXlSQ.mjs}

@@ -1,5 +1,6 @@
-import { a as projectFlagArgs, c as tryReadCanopyJson, i as projectDirArgs, n as siteConfig, o as projectUrl, s as resolveProject } from "./site-BJjoePQS.mjs";
-import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, s as apiDownload } from "./ui-DThlyHgo.mjs";
+import { a as projectDirArgs, c as resolveProject, l as stagingUrl, n as siteConfig, o as projectFlagArgs, s as projectUrl, u as tryReadCanopyJson } from "./site-BUlQR117.mjs";
+import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, s as apiDownload } from "./ui-D8HxX0Ng.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-I1adj0z2.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -46,6 +47,10 @@ async function bundleWorker(projectDir, entry) {
 *
 * Reads canopy.json in the project root:
 *   { "slug": "my-app", "dist": ".", "build": "npm run build" }
+*
+* A "migrations" dir in canopy.json adds a schema step (docs/13): pending
+* migrations apply after the bundle is staged and before the version flips —
+* schema first, then code. A migration failure aborts the deploy.
 */
 /** Must match apps/api/src/routes/deploys.ts WORKER_BUNDLE_PATH. */
 const WORKER_BUNDLE_PATH = "_canopy/worker.mjs";
@@ -97,12 +102,29 @@ const deployCommand = defineCommand({
 			default: true,
 			description: "Run the canopy.json build command first",
 			negativeDescription: "Skip the build, deploy the output directory as-is"
+		},
+		migrate: {
+			type: "boolean",
+			default: true,
+			description: "Apply pending schema migrations before the version goes live",
+			negativeDescription: "Skip migrations, deploy the code only"
+		},
+		staging: {
+			type: "boolean",
+			default: false,
+			description: "Deploy to the project's staging channel (created on first use, database cloned from live)"
 		}
 	},
 	run: reportErrors("deploy", async ({ args }) => {
 		const { dir, slug } = resolveProject(args);
+		const channel = args.staging ? "staging" : "live";
 		const config = tryReadCanopyJson(dir) ?? {};
 		if (config.build && args.build) await runBuild(config.build, dir);
+		const migrations = args.migrate ? readMigrationFiles(dir) : void 0;
+		if (migrations !== void 0 && config.dialect) try {
+			const { dialect } = await apiDataRequest("GET", "/platform", slug);
+			if (dialect !== config.dialect) p.log.warn(`canopy.json pins dialect "${config.dialect}" but this site's database speaks ${dialect} — the migrations below were probably written for a different target.`);
+		} catch {}
 		const distDir = resolve(dir, config.dist ?? ".");
 		let paths;
 		try {
@@ -138,22 +160,97 @@ const deployCommand = defineCommand({
 		const source = process.env["GITHUB_ACTIONS"] ? { "x-canopy-source": "github-action" } : {};
 		const spin = p.spinner();
 		const workerNote = workerBytes ? " + worker" : "";
-		spin.start(`Deploying ${files.length} files${workerNote} (${(total / 1024).toFixed(0)} kB) → ${slug}`);
+		const channelNote = channel === "staging" ? " [staging]" : "";
+		spin.start(`Deploying ${files.length} files${workerNote} (${(total / 1024).toFixed(0)} kB) → ${slug}${channelNote}`);
 		let result;
+		let migrateResult;
+		let stagingCreated = false;
 		try {
-			const { upload } = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, { worker: workerBytes !== null }, void 0, source), { action: `deploy "${slug}"` });
+			const { upload } = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, {
+				worker: workerBytes !== null,
+				channel
+			}, void 0, source), { action: `deploy "${slug}"` });
+			stagingCreated = upload.stagingCreated === true;
 			const uploads = [...files, ...workerBytes ? [{
 				path: WORKER_BUNDLE_PATH,
 				data: workerBytes
 			}] : []];
 			await uploadFiles(upload.grant, uploads);
+			if (migrations !== void 0 && migrations.length > 0) {
+				spin.message(`Applying schema migrations → ${slug}${channelNote}`);
+				try {
+					migrateResult = await withContext(migrateProject(slug, migrations, false, channel), { action: `migrate "${slug}"${channelNote}` });
+				} catch (err) {
+					spin.error(channel === "staging" ? "Deploy aborted — migrations failed on staging; live is unaffected." : "Deploy aborted — migrations failed; the live version is unchanged.");
+					throw err;
+				}
+			}
 			({deploy: result} = await withContext(apiRequest("POST", `/projects/${slug}/deploys/${upload.version}/complete`, { grant: upload.grant }, void 0, source), { action: `deploy "${slug}"` }));
 		} catch (err) {
 			spin.error("Deploy failed.");
 			throw err;
 		}
 		const backend = result.worker?.serviceUrl ? ` · backend ${result.worker.serviceUrl}` : "";
-		spin.stop(`Live: ${projectUrl(slug)} (v${result.version})${backend}`);
+		if (channel === "staging") {
+			spin.stop(`Staging: ${stagingUrl(slug)} (v${result.version})${backend}`);
+			if (stagingCreated) console.log("  staging channel created — database cloned from live");
+			console.log(`  happy with it? \`canopy promote\` makes v${result.version} live`);
+		} else spin.stop(`Live: ${projectUrl(slug)} (v${result.version})${backend}`);
+		if (migrateResult !== void 0) for (const line of describeMigrateResult(migrateResult)) console.log(`  ${line}`);
+	})
+});
+const promoteCommand = defineCommand({
+	meta: {
+		name: "promote",
+		description: "Make the staged version live (migrations replay against live first)"
+	},
+	args: {
+		version: {
+			type: "positional",
+			description: "Version to promote, e.g. v3 (defaults to the staged version)",
+			required: false
+		},
+		...projectFlagArgs,
+		dir: {
+			type: "string",
+			description: "Project directory (defaults to the current directory)"
+		},
+		yes: {
+			type: "boolean",
+			default: false,
+			description: "Skip the confirmation prompt"
+		}
+	},
+	run: reportErrors("promote", async ({ args }) => {
+		const { slug } = resolveProject(args);
+		let target;
+		if (args.version !== void 0) {
+			if (!/^v?\d+$/.test(args.version)) throw new Error(`Invalid version "${args.version}" — expected a number like 3 or v3.`);
+			target = Number(args.version.replace(/^v/, ""));
+		} else {
+			const { staging } = await apiRequest("GET", `/projects/${slug}/staging`);
+			if (!staging.provisioned || staging.version === null) throw new Error(`Nothing staged for "${slug}" — run \`canopy deploy --staging\` first, or pass a version explicitly.`);
+			target = staging.version;
+		}
+		if (!args.yes && process.stdin.isTTY) {
+			if (!unwrap(await p.confirm({ message: `Promote v${target} of "${slug}" to live? Pending migrations replay against the live database first (snapshot taken automatically).` }))) {
+				p.cancel("Aborted.");
+				return;
+			}
+		}
+		const spin = p.spinner();
+		spin.start(`Promoting ${slug} v${target} → live`);
+		let result;
+		try {
+			({live: result} = await withContext(apiRequest("POST", `/projects/${slug}/deploys/${target}/promote`), { action: `promote "${slug}" v${target}` }));
+		} catch (err) {
+			spin.error("Promote failed — the live version is unchanged.");
+			throw err;
+		}
+		const backend = result.worker?.serviceUrl ? ` · backend ${result.worker.serviceUrl}` : "";
+		spin.stop(`Live: ${projectUrl(slug)} (v${result.version}, was v${result.previous ?? "?"})${backend}`);
+		for (const name of result.migrationsApplied) console.log(`  applied ${name}`);
+		if (result.snapshot !== void 0) console.log(`  pre-promote snapshot: ${result.snapshot} (canopy db restore --snapshot …)`);
 	})
 });
 const UPLOAD_CONCURRENCY = 8;
@@ -191,7 +288,7 @@ async function pickVersion(deploys, live, message, initial) {
 const rollbackCommand = defineCommand({
 	meta: {
 		name: "rollback",
-		description: "Make an earlier deploy live again (pick from history)"
+		description: "Make an earlier deploy live again, backend included (pick from history)"
 	},
 	args: {
 		version: {
@@ -224,7 +321,8 @@ const rollbackCommand = defineCommand({
 		}
 		console.log(`Rolling back ${slug} to v${target}`);
 		const { live: result } = await apiRequest("POST", `/projects/${slug}/deploys/${target}/rollback`);
-		console.log(`Live: ${projectUrl(slug)} (v${result.version}, was v${result.previous ?? "?"})`);
+		const worker = result.worker ? ` · worker v${result.worker.version}` : "";
+		console.log(`Live: ${projectUrl(slug)} (v${result.version}, was v${result.previous ?? "?"})${worker}`);
 	})
 });
 const downloadCommand = defineCommand({
@@ -275,4 +373,4 @@ const downloadCommand = defineCommand({
 	})
 });
 //#endregion
-export { deployCommand, downloadCommand, rollbackCommand };
+export { deployCommand, downloadCommand, promoteCommand, rollbackCommand };

package/dist/dev-CvtoGFW0.mjs

@@ -0,0 +1,2 @@
+import { t as devCommand } from "./dev-DvyKHe2d.mjs";
+export { devCommand };

package/dist/{dev-CQQhMOoD.mjs → dev-DvyKHe2d.mjs}

@@ -1,5 +1,6 @@
-import { i as projectDirArgs, n as siteConfig, s as resolveProject } from "./site-BJjoePQS.mjs";
-import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-DThlyHgo.mjs";
+import { a as projectDirArgs, c as resolveProject, i as projectDialect, n as siteConfig, u as tryReadCanopyJson } from "./site-BUlQR117.mjs";
+import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-D8HxX0Ng.mjs";
+import { r as readMigrationFiles } from "./migrations-I1adj0z2.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { join } from "node:path";
@@ -86,21 +87,34 @@ async function devRemote(flags, slug) {
 	const server = await startVite(flags, { proxy: { "/_api": {
 		target: apiUrl,
 		changeOrigin: true,
-		headers: { authorization: `Bearer ${token}` },
+		headers: {
+			authorization: `Bearer ${token}`,
+			...flags.staging ? { "x-canopy-channel": "staging" } : {}
+		},
 		rewrite: rewriteApiPath
 	} } });
-	console.log(`\n  ${slug} — remote-first dev against LIVE project data`);
-	console.log("  (worried about a risky change? `canopy db snapshot` first, or work");
-	console.log("   on a local copy instead: `canopy dev --local --pull`)\n");
+	if (flags.staging) {
+		console.log(`\n  ${slug} — remote-first dev against the STAGING channel's data`);
+		console.log("  (live data is untouched; `canopy staging sync` re-clones it from live)");
+	} else {
+		console.log(`\n  ${slug} — remote-first dev against LIVE project data`);
+		console.log("  (worried about a risky change? `canopy db snapshot` first, or work");
+		console.log("   on a local copy instead: `canopy dev --local --pull`)");
+	}
+	if (tryReadCanopyJson(flags.dir)?.migrations && !flags.staging) {
+		console.log("  migrations apply on `canopy deploy`, never from dev — use --local");
+		console.log("  while the schema is in flux");
+	}
+	console.log("");
 	server.printUrls();
 	console.log(`\n  Dev token expires ${expires_at} — restart canopy dev after that.`);
 }
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-C5-GWJcx.mjs");
-		console.log(`Pulling a fresh export of ${slug}…`);
-		dump = await fetchProjectDump(slug);
+		const { fetchProjectDump } = await import("./local-C47tmhl7.mjs");
+		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
+		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
 	let remote;
 	try {
@@ -113,16 +127,22 @@ async function devLocal(flags, slug) {
 		const reason = err instanceof ApiError ? err.explain().why : String(err);
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
-	const { createSandbox } = await import("./local-C5-GWJcx.mjs");
+	const { createSandbox } = await import("./local-C47tmhl7.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),
-		email: siteConfig().email
+		email: siteConfig().email,
+		dialect: flags.dialect
 	});
 	if (dump !== void 0) {
 		await sandbox.applyDump(dump);
 		console.log(`Hydrated the sandbox (${(dump.length / 1024).toFixed(1)} kB of SQL).`);
 	}
+	const migrationFiles = readMigrationFiles(flags.dir);
+	if (migrationFiles !== void 0 && migrationFiles.length > 0) {
+		const { applied } = await sandbox.applyMigrations(migrationFiles);
+		if (applied.length > 0) console.log(`Applied ${applied.length} pending migration(s): ${applied.join(", ")}`);
+	}
 	const handleApi = async (req, res) => {
 		const chunks = [];
 		for await (const chunk of req) chunks.push(chunk);
@@ -170,8 +190,10 @@ async function devLocal(flags, slug) {
 		apiServer.close();
 		sandbox.dispose();
 	});
-	console.log(`\n  ${slug} — LOCAL sandbox (PGlite + filesystem blobs in .canopy/local/)`);
+	const engine = flags.dialect === "sqlite" ? "SQLite" : "PGlite";
+	console.log(`\n  ${slug} — LOCAL sandbox (${engine} + filesystem blobs in .canopy/local/)`);
 	console.log("  data is yours alone: db and blob writes never reach the platform");
+	if (flags.dialect === void 0) console.log("  raw sql() speaks postgres here — on a D1 site? lock \"dialect\" in canopy.json");
 	if (dump === void 0) console.log("  (want prod data? restart with --pull to hydrate from a fresh export)");
 	console.log("  blobs are not pulled — the local blob store starts empty");
 	console.log(remote ? "  ai/services pass through to the platform (metered as usual)" : "  ai/services answer 501 until you log in and restart");
@@ -192,24 +214,32 @@ const devCommand = defineCommand({
 		local: {
 			type: "boolean",
 			default: false,
-			description: "Local-data sandbox (PGlite + blobs under .canopy/local/) instead of live data"
+			description: "Local-data sandbox (database + blobs under .canopy/local/) instead of live data"
 		},
 		pull: {
 			type: "boolean",
 			default: false,
 			description: "Hydrate the sandbox from a fresh prod export first (requires --local)"
+		},
+		staging: {
+			type: "boolean",
+			default: false,
+			description: "Point remote dev at the staging channel's data (or pull the staging dump with --local --pull)"
 		}
 	},
 	run: reportErrors("dev", async ({ args }) => {
 		const port = args.port === void 0 ? void 0 : Number(args.port);
 		if (port !== void 0 && !Number.isInteger(port)) throw new Error(`Invalid --port=${args.port}`);
 		if (args.pull && !args.local) throw new Error("--pull only makes sense with --local (remote dev already sees live data).");
+		if (args.staging && args.local && !args.pull) throw new Error("--staging with --local needs --pull (it selects which dump hydrates the sandbox).");
 		const { dir, slug } = resolveProject(args);
 		const flags = {
 			dir,
 			port,
 			local: args.local,
-			pull: args.pull
+			pull: args.pull,
+			staging: args.staging,
+			dialect: projectDialect(dir)
 		};
 		await (flags.local ? devLocal(flags, slug) : devRemote(flags, slug));
 	})

package/dist/docs/ci.md

@@ -1,10 +1,8 @@
 ---
 title: CI and deploy tokens
-summary: Push-to-main deploys using a project-scoped deploy token.
+description: Push-to-main deploys using a project-scoped deploy token.
 ---
 
-# CI and deploy tokens
-
 Interactive `canopy login` is for humans at a terminal. For automated deploys
 (GitHub Actions, etc.) use a **deploy token**: a project-scoped credential that
 can deploy that one project and nothing else.

package/dist/docs/cli.md

@@ -1,12 +1,11 @@
 ---
 title: CLI command reference
-summary: Every canopy command, its flags, and what it does.
+description: Every canopy command, its flags, and what it does.
 ---
 
-# CLI command reference
-
 Run `canopy <command> --help` for the authoritative flags of any command. This
-is the overview.
+is the one-page overview; the docs site's [CLI reference](https://docs.canopy.website/cli) section
+has a full page per command.
 
 ## Auth
 

package/dist/docs/data.md

@@ -1,10 +1,8 @@
 ---
 title: Working with project data
-summary: Pulling, snapshotting, and restoring your project database.
+description: Pulling, snapshotting, and restoring your project database.
 ---
 
-# Working with project data
-
 Each Canopy project gets its own database and blob storage (D1 and R2 on the
 Cloudflare target; Postgres and GCS on GCP). Your app reads and writes them
 through the Canopy SDK at runtime; the CLI gives you tools to manage the data
@@ -65,7 +63,10 @@ risky change.
 
 ## Restore — destructive
 
-Restoring **replaces ALL project data**:
+> **Warning:** Restoring **replaces ALL project data**. Take a snapshot first — a snapshot taken seconds earlier
+> is your undo button.
+
+Restore from either source:
 
 ```bash
 canopy db restore backup.sql          # from a local dump

package/dist/docs/deploy.md

@@ -1,10 +1,8 @@
 ---
 title: Deploying a project
-summary: How canopy deploy builds, uploads, and makes a version live.
+description: How canopy deploy builds, uploads, and makes a version live.
 ---
 
-# Deploying a project
-
 From inside a project directory:
 
 ```bash
@@ -31,6 +29,19 @@ output directory (or the static files as-is for a `static` project):
 canopy deploy --no-build
 ```
 
+## Trying it on staging first
+
+Nervous about a change — especially one with schema migrations or backend
+code? Deploy it to the project's staging channel first, then promote the exact
+same version once it checks out:
+
+```bash
+canopy deploy --staging   # own URL, own database (a copy of live)
+canopy promote            # make that version live
+```
+
+See [Staging & promoting](https://docs.canopy.website/guides/staging).
+
 ## Rolling back
 
 Every deploy is kept, so you can instantly revert:
@@ -40,7 +51,8 @@ canopy rollback          # pick a version from history
 canopy rollback v3       # make v3 live again
 ```
 
-Rollback re-points the live version at an existing deploy — it does not rebuild.
+Rollback re-points the live version at an existing deploy — it does not
+rebuild, and the project's backend rolls back with it.
 
 ## Downloading a version
 

package/dist/docs/dev.md

@@ -1,10 +1,8 @@
 ---
 title: Local development
-summary: Running a project locally against live or sandboxed data.
+description: Running a project locally against live or sandboxed data.
 ---
 
-# Local development
-
 From inside a project directory:
 
 ```bash
@@ -20,14 +18,14 @@ develop against realistic state.
 ## Offline sandbox
 
 To develop without touching live data — for example on a plane, or before you
-trust a destructive change — use a local sandbox backed by PGlite (embedded
-Postgres) and a filesystem blob store:
+trust a destructive change — use a local sandbox backed by an embedded database
+and a filesystem blob store:
 
 ```bash
 canopy dev --local
 ```
 
-This creates local Postgres data and blobs under `.canopy/local/` in your
+This creates a local database and blobs under `.canopy/local/` in your
 project. The sandbox starts empty.
 
 To seed the sandbox from a fresh copy of production data first:
@@ -38,11 +36,15 @@ canopy dev --local --pull
 
 `.canopy/local/` is disposable — delete it to reset the sandbox.
 
-One caveat: the sandbox database is Postgres, so raw `canopy.db.sql()` speaks
-the postgres dialect there, while your deployed project speaks whatever its
-platform target speaks (`canopy.db.dialect()` tells you — sqlite on
-Cloudflare). Collections (`canopy.db.collection(...)`) behave the same in both,
-so this only matters for hand-written SQL — see `canopy docs data`.
+By default the sandbox runs PGlite (embedded Postgres), so raw
+`canopy.db.sql()` speaks the postgres dialect there, while your deployed
+project speaks whatever its platform target speaks (`canopy.db.dialect()`
+tells you — sqlite on Cloudflare). Collections (`canopy.db.collection(...)`)
+behave the same in both, so this only matters for hand-written SQL — see
+`canopy docs data`. If your project's raw SQL targets a sqlite site, lock the
+dialect in `canopy.json` (`"dialect": "sqlite"`) and the sandbox runs an
+embedded SQLite engine instead, so the same SQL works locally and deployed —
+see [canopy dev](https://docs.canopy.website/cli/dev).
 
 ## Which mode should an agent use?
 

package/dist/docs/getting-started.md

@@ -1,10 +1,8 @@
 ---
 title: Getting started
-summary: Install the CLI, sign in with OneLogin, and ship your first project.
+description: Install the CLI, sign in with OneLogin, and ship your first project.
 ---
 
-# Getting started with Canopy
-
 Canopy is Monks' managed platform for vibecoded projects. You build a small web
 app, and Canopy hosts it, gives it a database, blob storage, and AI — no
 infrastructure to manage.