svcloud 0.1.4 → 0.1.6

package/README.md

@@ -57,7 +57,9 @@ svcloud init                  Connect a repo (defaults to the one in your workin
 svcloud runs <app>            Show or watch an app's provisioning run
 svcloud secrets <cmd>         Manage an app's keys & settings (list/set/remove)
 svcloud db <cmd>              Browse and edit an app's database (see `svcloud db` for subcommands)
+svcloud storage presign       Get a direct URL for one file in an app's file storage
 svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
+svcloud bundle <cmd>          Keep an app's starter current (status/update/done)
 svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
 svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
 svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
@@ -75,6 +77,33 @@ to skip what it would otherwise infer or ask about; `runs` reads `--id
 
 `logs` and `dev` are still on the way.
 
+### Keeping an app's starter current
+
+SV Cloud's starter gets better over time, and an app that never catches up
+keeps working but stops being able to do things the platform can now do. It can
+also keep a deploy step that fails for reasons nothing in the repo explains.
+
+```bash
+svcloud bundle status <app>   # is this app behind?
+svcloud bundle update <app>   # stage the update for review
+svcloud bundle done <app>     # record it, after you commit
+```
+
+`update` writes the new versions into `sv-cloud-bundle/` along with an
+`UPDATE.md` explaining what to do with each file. It changes nothing in your
+app's own source, and it does not commit or push — you read the diff, and
+`git` stays the undo. Most people will hand this to their coding agent
+instead: it can read the same plan through SV Cloud's tools, and it knows
+which files it may replace outright and which ones it has to merge into work
+you did.
+
+`update` refuses to run with uncommitted changes, so that the diff it produces
+means exactly one thing.
+
+Run `svcloud bundle done` once the changes are committed. Skipping it does no
+damage, but the app keeps reporting itself out of date and the next update
+starts from the wrong place.
+
 ## Connect your coding agent
 
 `svcloud mcp` runs a local MCP server that your coding agent — Antigravity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svcloud",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The SV Cloud CLI. Alpha: login, logout, status, open, projects list, mcp, init, and runs are built; see PLANNING.md for what's still missing.",
   "type": "module",
   "license": "UNLICENSED",

package/src/commands/bundle.ts

@@ -0,0 +1,224 @@
+/**
+ * `svcloud bundle` — PLANNING.md §4 Step 8, apps/cloud F27. Brings a connected
+ * repo up to a newer starter template.
+ *
+ * The merge rules are the platform's, not the CLI's: `GET /bundle/plan`
+ * returns the base version's bytes, the new version's bytes, and a per-file
+ * action, and everything here is staging and presentation. That is deliberate,
+ * for the same reason the MCP bridge holds no tool registry — a rule that
+ * lives on the server cannot drift against the version of the CLI somebody
+ * happens to have installed.
+ *
+ * `update` writes into `sv-cloud-bundle/` and stops. It does not `git add`,
+ * commit, or push, and it never touches `src/`: the owner reads a diff, and
+ * git stays the undo. `done` is a separate command precisely because it has to
+ * run AFTER a human commits — folding it into `update` would mean recording
+ * that the update landed before it had.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { gitWorkingState } from "../lib/git";
+import { die, printJson, printTable } from "../lib/output";
+
+const STAGE_DIR = "sv-cloud-bundle";
+
+interface BundleStatus {
+  project_id: string;
+  current_version: string | null;
+  latest_version: string;
+  update_available: boolean;
+  legacy: boolean;
+  base_unavailable_reason: string | null;
+  workflow_stale: boolean;
+  workflow_warning: string | null;
+}
+
+interface PlannedFile {
+  src: string;
+  path: string;
+  class: string;
+  action: string;
+  target?: string;
+  base?: string;
+  guidance: string;
+  retirement?: { src: string; replaced_by?: string | null; note: string };
+}
+
+interface BundlePlan extends BundleStatus {
+  framework: string;
+  migrate_once: boolean;
+  files: PlannedFile[];
+  migration_notes: string | null;
+  manifest_merge: unknown;
+  instructions: string;
+}
+
+/** Human-facing one-liners. The wire's `action` stays machine-readable. */
+const ACTION_LABEL: Record<string, string> = {
+  skip: "unchanged",
+  "fast-forward": "replace",
+  conflict: "merge (you edited it)",
+  create: "new file",
+  retire: "delete",
+  "retire-conflict": "retired, you use it",
+  locate: "find it first",
+  "merge-manifest": "merge fields",
+  "report-only": "yours, unchanged",
+};
+
+async function resolve(slug: string | undefined): Promise<{ id: string; name: string }> {
+  if (!slug) die("Usage: svcloud bundle <status|update|done> <app>");
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+  return { id: project.id, name: project.name };
+}
+
+async function statusCmd(slug: string | undefined, json: boolean): Promise<void> {
+  const project = await resolve(slug);
+  const status = await apiFetch<BundleStatus>(`/api/v1/projects/${project.id}/bundle`);
+  if (json) {
+    printJson(status);
+    return;
+  }
+  console.log(`App:      ${project.name}`);
+  console.log(`Starter:  ${status.current_version ?? "not recorded"}`);
+  console.log(`Newest:   ${status.latest_version}`);
+  if (status.workflow_warning) console.log(`\n! ${status.workflow_warning}`);
+  if (!status.update_available) {
+    console.log("\nUp to date.");
+    return;
+  }
+  if (status.legacy) {
+    console.log(
+      "\nThis app was set up before starter versions were recorded, so the first update " +
+        "has no starting point to compare against. Review every change it proposes.",
+    );
+  }
+  console.log("\nAn update is available. Run `svcloud bundle update " + (slug ?? "") + "`.");
+}
+
+async function updateCmd(slug: string | undefined, json: boolean): Promise<void> {
+  const project = await resolve(slug);
+
+  // Same preconditions as `deploy`, for the same reason: this writes files
+  // into the working tree, and a dirty tree makes the resulting diff
+  // impossible for the owner to read as "what the update did".
+  const state = await gitWorkingState();
+  if (!state) {
+    die("Run this from the app's local git repository (no repo found, or `git` isn't on PATH).");
+  }
+  if (state.dirty) {
+    die(
+      "Working tree has uncommitted changes. Commit or stash them first, so the update's own " +
+        "changes are the only thing in the diff.",
+    );
+  }
+
+  const plan = await apiFetch<BundlePlan>(`/api/v1/projects/${project.id}/bundle/plan`);
+  if (json) {
+    printJson(plan);
+    return;
+  }
+
+  if (!plan.update_available) {
+    console.log(`${project.name} is already on the newest starter (${plan.latest_version}).`);
+    return;
+  }
+
+  const actionable = plan.files.filter((f) => f.action !== "skip");
+  const cwd = process.cwd();
+  const written: string[] = [];
+
+  for (const f of actionable) {
+    if (f.target === undefined) continue;
+    const staged = join(cwd, STAGE_DIR, "files", f.src);
+    await mkdir(dirname(staged), { recursive: true });
+    await writeFile(staged, f.target, "utf8");
+    written.push(f.src);
+  }
+
+  const notes = [
+    `# Starter update: ${plan.current_version ?? "unrecorded"} to ${plan.latest_version}`,
+    "",
+    plan.instructions,
+    "",
+    plan.base_unavailable_reason ? `**Note.** ${plan.base_unavailable_reason}\n` : "",
+    "## Files",
+    "",
+    ...actionable.map((f) => {
+      const head = `### ${f.path} — ${ACTION_LABEL[f.action] ?? f.action}`;
+      const staged =
+        f.target === undefined ? "" : `\nNew version staged at \`${STAGE_DIR}/files/${f.src}\`.`;
+      const retired = f.retirement
+        ? `\nRetired${f.retirement.replaced_by ? `, superseded by ${f.retirement.replaced_by}` : ""}. ${f.retirement.note}`
+        : "";
+      return `${head}\n\n${f.guidance}${staged}${retired}\n`;
+    }),
+    plan.migration_notes ? `## Migration notes\n\n${plan.migration_notes}\n` : "",
+  ].join("\n");
+
+  await writeFile(join(cwd, STAGE_DIR, "UPDATE.md"), notes, "utf8");
+
+  printTable(
+    actionable.map((f) => ({
+      file: f.path,
+      what: ACTION_LABEL[f.action] ?? f.action,
+    })),
+    ["file", "what"],
+  );
+
+  console.log(`\nStaged ${written.length} file(s) under ${STAGE_DIR}/ — nothing in src/ changed.`);
+  console.log(`Read ${STAGE_DIR}/UPDATE.md, or open this repo with your coding agent and ask it`);
+  console.log("to apply the starter update; it can read the same plan through SV Cloud's tools.");
+  console.log(`\nWhen the changes are committed, run \`svcloud bundle done ${slug ?? ""}\`.`);
+}
+
+async function doneCmd(slug: string | undefined, json: boolean): Promise<void> {
+  const project = await resolve(slug);
+  const result = await apiFetch<{
+    version: string;
+    marker_path: string;
+    marker_contents: string;
+    changed: boolean;
+  }>(`/api/v1/projects/${project.id}/bundle/applied`, { method: "POST", body: {} });
+
+  // The marker is written HERE rather than by the server, because the server
+  // does not touch repos — same rule the rest of this feature follows.
+  const target = join(process.cwd(), result.marker_path);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, result.marker_contents, "utf8");
+
+  if (json) {
+    printJson(result);
+    return;
+  }
+  console.log(`Recorded ${project.name} as running starter ${result.version}.`);
+  console.log(`Wrote ${result.marker_path}. Commit it — it is how the next update knows where to`);
+  console.log("start, and an app whose marker disagrees with its files updates badly.");
+}
+
+export async function bundleCommand(argv: string[], json: boolean): Promise<void> {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case "status":
+      await statusCmd(rest[0], json);
+      return;
+    case "update":
+      await updateCmd(rest[0], json);
+      return;
+    case "done":
+      await doneCmd(rest[0], json);
+      return;
+    default:
+      die(
+        [
+          "Usage:",
+          "  svcloud bundle status <app>   Is this app running an out-of-date starter?",
+          "  svcloud bundle update <app>   Stage the update under sv-cloud-bundle/ for review",
+          "  svcloud bundle done <app>     Record the update after you have committed it",
+        ].join("\n"),
+      );
+  }
+}

package/src/commands/promote.ts

@@ -0,0 +1,85 @@
+/**
+ * `svcloud promote <app>` — put the commit staging is running onto the live app.
+ *
+ * All this does is create a `prod-*` tag and push it. The promotion itself is
+ * GitHub Actions calling SV Cloud, exactly as it would if somebody tagged by
+ * hand — this is a convenience over `git tag`, not a second way in, for the
+ * same reason `svcloud deploy` pushes a branch rather than uploading a build.
+ *
+ * A NEW TAG EVERY TIME, never a moving `prod`. A moving tag needs a force-push
+ * and makes "which commit is live" a question nobody can answer; the server
+ * refuses to point one at a second commit. The date-plus-counter name is picked
+ * here so nobody has to think about it.
+ */
+import type { ProjectSummary } from "@sv/cloud-contracts";
+import { findProjectBySlug } from "../lib/find-project";
+import { existingPromotionTags, gitWorkingState, headSha, pushTag } from "../lib/git";
+import { die, printJson } from "../lib/output";
+
+const USAGE = `Usage: svcloud promote <app> [--commit <sha>] [--tag <name>]
+
+Tags a commit and pushes it, which promotes it to your live app.
+With no --commit, promotes the commit currently checked out.`;
+
+export async function promoteCommand(argv: string[], json: boolean): Promise<void> {
+  const slug = argv.find((a) => !a.startsWith("--"));
+  if (!slug) die(USAGE);
+
+  const project = await findProjectBySlug(slug as string);
+  if (!project) die(`No app named "${slug}".`);
+  assertStaged(project);
+
+  const explicitSha = flagValue(argv, "--commit");
+  const sha = explicitSha ?? (await headSha());
+  if (!sha) {
+    die("Could not work out which commit to promote. Run this inside the app's git repository, or pass --commit <sha>.");
+  }
+
+  // A dirty tree is not fatal here the way it is for `deploy` — the tag names a
+  // commit, and uncommitted work simply is not in it — but somebody who thinks
+  // their latest edit is going live should hear otherwise before it does not.
+  const state = await gitWorkingState();
+  if (state?.dirty && !explicitSha) {
+    console.warn("You have uncommitted changes. They are NOT part of this promotion.");
+  }
+
+  const tag = flagValue(argv, "--tag") ?? (await nextTagName());
+
+  await pushTag(tag, sha as string);
+
+  if (json) {
+    return printJson({ tag, commit_sha: sha, project: project.slug });
+  }
+  console.log(`Tagged ${(sha as string).slice(0, 7)} as ${tag} and pushed it.`);
+  console.log("");
+  console.log("GitHub Actions is promoting it now. Watch it in your repository's Actions tab;");
+  console.log(`your live app is at ${project.web_address ?? "its web address"}.`);
+}
+
+function assertStaged(project: ProjectSummary): void {
+  if (project.deploy_mode === "staged") return;
+  die(
+    `"${project.slug}" does not use a staging environment, so there is nothing to promote — ` +
+      "pushing to its default branch already updates it.\n" +
+      "To start using staging: svcloud staging create <app>",
+  );
+}
+
+/**
+ * `prod-<today>.<n>`, where n is the next free counter for today. Reads the
+ * repo's existing tags rather than assuming, so re-promoting twice in one day
+ * does not collide with a tag the server would refuse to reuse.
+ */
+async function nextTagName(): Promise<string> {
+  const today = new Date().toISOString().slice(0, 10);
+  const prefix = `prod-${today}.`;
+  const used = new Set(await existingPromotionTags());
+  let n = 1;
+  while (used.has(`${prefix}${n}`)) n++;
+  return `${prefix}${n}`;
+}
+
+function flagValue(argv: string[], flag: string): string | undefined {
+  const i = argv.indexOf(flag);
+  return i === -1 ? undefined : argv[i + 1];
+}

package/src/commands/staging.ts

@@ -0,0 +1,126 @@
+/**
+ * `svcloud staging create|status|on|off <app>` — an app's staging environment.
+ *
+ * The rules all live on the server (apps/cloud's services/staging.ts), for the
+ * same reason `bundle` keeps its merge rules there and the MCP bridge holds no
+ * tool registry: a rule enforced in whatever CLI version somebody happens to
+ * have installed is a rule that drifts.
+ *
+ * What this file owes the person running it is the consequence, said plainly.
+ * `on` is the moment pushes to their default branch stop reaching their live
+ * app, and somebody who does not realise that discovers it when a customer asks
+ * where the fix went.
+ */
+import type { ProjectDetail } from "@sv/cloud-contracts";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson } from "../lib/output";
+
+const USAGE = `Usage:
+  svcloud staging create <app>   Give an app a staging environment
+  svcloud staging status <app>   Show whether it is ready to switch over
+  svcloud staging on <app>       Deploy the default branch to staging from now on
+  svcloud staging off <app>      Go back to deploying the live app from the default branch`;
+
+interface Preflight {
+  staging_ready: boolean;
+  workflow_ok: boolean;
+  workflow_problem: string | null;
+  missing_secret_names: string[];
+  deploy_mode: "direct" | "staged";
+}
+
+export async function stagingCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, slug] = argv;
+  if (!subcommand || !slug) die(USAGE);
+
+  const project = await findProjectBySlug(slug as string);
+  if (!project) die(`No app named "${slug}".`);
+
+  switch (subcommand) {
+    case "create":
+      return create(project.id, json);
+    case "status":
+      return status(project.id, json);
+    case "on":
+      return on(project.id, argv.includes("--force"), json);
+    case "off":
+      return off(project.id, json);
+    default:
+      die(`Unknown subcommand: ${subcommand}\n\n${USAGE}`);
+  }
+}
+
+async function create(projectId: string, json: boolean): Promise<void> {
+  const result = await apiFetch<{
+    staging?: ProjectDetail;
+    already_exists?: boolean;
+    run_id?: string;
+  }>(`/api/v1/projects/${projectId}/staging`, { method: "POST" });
+
+  if (json) return printJson(result);
+
+  if (result.already_exists) {
+    console.log("This app already has a staging environment.");
+    console.log(`  ${result.staging?.web_address ?? ""}`);
+    return;
+  }
+  console.log("Setting up a staging environment.");
+  console.log(`  ${result.staging?.web_address ?? ""}`);
+  console.log("");
+  // Said before they ask: creating it costs money and changes nothing yet.
+  console.log("This is a second copy of your app, with its own database and files.");
+  console.log("Its usage comes out of the same plan allowance as your live app.");
+  console.log("");
+  console.log("Nothing has changed about where your pushes go yet.");
+  console.log("Run `svcloud staging status <app>` to see what is left before switching over.");
+}
+
+async function status(projectId: string, json: boolean): Promise<void> {
+  const result = await apiFetch<Preflight>(`/api/v1/projects/${projectId}/staging/preflight`);
+  if (json) return printJson(result);
+
+  if (result.deploy_mode === "staged") {
+    console.log("Pushes to your default branch deploy staging.");
+    console.log("Your live app changes when you push a prod-* tag.");
+    return;
+  }
+
+  console.log("Pushes to your default branch deploy your live app.");
+  console.log("");
+  console.log(`  staging environment   ${result.staging_ready ? "ready" : "not created yet"}`);
+  console.log(
+    `  deploy workflow       ${result.workflow_ok ? "ready" : (result.workflow_problem ?? "not ready")}`,
+  );
+  if (result.missing_secret_names.length > 0) {
+    console.log(`  settings              ${result.missing_secret_names.length} missing on staging:`);
+    for (const name of result.missing_secret_names) console.log(`      ${name}`);
+    console.log("");
+    // The likeliest reason a first staging build fails, and nothing can copy
+    // them across: SV Cloud never sees a setting's value after it is set.
+    console.log("Add these with `svcloud secrets set` before switching over, or the");
+    console.log("first staging build is likely to fail.");
+  } else {
+    console.log("  settings              ready");
+  }
+}
+
+async function on(projectId: string, force: boolean, json: boolean): Promise<void> {
+  const result = await apiFetch<{ project: ProjectDetail; note: string }>(
+    `/api/v1/projects/${projectId}/staging/enable${force ? "?force=1" : ""}`,
+    { method: "POST" },
+  );
+  if (json) return printJson(result);
+  console.log(result.note);
+  console.log("");
+  console.log("To go back at any time: svcloud staging off <app>");
+}
+
+async function off(projectId: string, json: boolean): Promise<void> {
+  const result = await apiFetch<{ project: ProjectDetail; note: string }>(
+    `/api/v1/projects/${projectId}/staging/disable`,
+    { method: "POST" },
+  );
+  if (json) return printJson(result);
+  console.log(result.note);
+}

package/src/commands/storage.ts

@@ -0,0 +1,108 @@
+/**
+ * `svcloud storage` — direct URLs into an app's file storage.
+ *
+ * Only presigning, deliberately. `svcloud storage put` and `get` would put the
+ * CLI in the data path for a file that may be gigabytes, which is the exact
+ * cost presigned URLs exist to avoid; the URL this hands back works with curl,
+ * a browser, or anything else, and moves bytes straight between the caller and
+ * storage.
+ *
+ * A GET URL is a shareable download link for as long as it lives. The server
+ * caps that lifetime and reports what it actually granted, which may be less
+ * than was asked for — so `expires_in` in the output is the truth, not the
+ * `--expires-in` flag.
+ */
+import { statSync } from "node:fs";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson } from "../lib/output";
+
+const USAGE = `Usage:
+  svcloud storage presign <app> <key> [--method GET|PUT] [--expires-in <seconds>]
+                                      [--size <bytes> | --file <path>] [--content-type <type>]
+
+  --method       GET (default) for a download or share link, PUT to upload.
+  --size         Required for PUT. Signed into the URL, so an upload of any
+                 other size is refused.
+  --file         Read the size from a local file instead of passing --size.
+  --expires-in   Seconds. Capped by the server; the output reports what was granted.`;
+
+interface PresignResponse {
+  project_id: string;
+  key: string;
+  method: string;
+  url: string;
+  expires_in: number;
+}
+
+function flagValue(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) die(`${name} needs a value.\n\n${USAGE}`);
+  return value;
+}
+
+export async function storageCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "presign") die(USAGE);
+
+  const [slug, key] = rest;
+  if (!slug || !key) die(USAGE);
+
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+
+  const method = (flagValue(rest, "--method") ?? "GET").toUpperCase();
+  if (method !== "GET" && method !== "PUT") die(`--method must be GET or PUT.\n\n${USAGE}`);
+
+  const body: Record<string, unknown> = { key, method };
+
+  const expiresIn = flagValue(rest, "--expires-in");
+  if (expiresIn !== undefined) {
+    const seconds = Number(expiresIn);
+    if (!Number.isInteger(seconds) || seconds <= 0) die("--expires-in must be a whole number of seconds.");
+    body.expires_in = seconds;
+  }
+
+  const contentType = flagValue(rest, "--content-type");
+  if (contentType) body.content_type = contentType;
+
+  if (method === "PUT") {
+    const size = flagValue(rest, "--size");
+    const file = flagValue(rest, "--file");
+    if (size !== undefined && file !== undefined) die("Pass --size or --file, not both.");
+    if (size !== undefined) {
+      const bytes = Number(size);
+      if (!Number.isInteger(bytes) || bytes < 0) die("--size must be a whole number of bytes.");
+      body.content_length = bytes;
+    } else if (file !== undefined) {
+      try {
+        body.content_length = statSync(file).size;
+      } catch {
+        die(`Could not read "${file}".`);
+      }
+    } else {
+      die(`A PUT needs --size or --file: the size is signed into the URL.\n\n${USAGE}`);
+    }
+  }
+
+  const result = await apiFetch<PresignResponse>(
+    `/api/v1/projects/${project.id}/storage/presign`,
+    { method: "POST", body: JSON.stringify(body) },
+  );
+
+  if (json) {
+    printJson(result);
+    return;
+  }
+
+  console.log(result.url);
+  console.error("");
+  console.error(`${result.method} ${result.key} — valid for ${result.expires_in}s.`);
+  if (result.method === "GET") {
+    console.error("Anybody with this link can download the file until it expires.");
+  } else {
+    console.error(`Upload with: curl -X PUT --upload-file <file> "<url>"`);
+  }
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  * few that need subcommands (`secrets`, `db`, `mcp`) do their own
  * second-level switch — no subcommand ambiguity worth a parser library yet.
  */
+import { bundleCommand } from "./commands/bundle";
 import { dbCommand } from "./commands/db";
 import { deployCommand } from "./commands/deploy";
 import { initCommand } from "./commands/init";
@@ -15,6 +16,9 @@ import { openCommand } from "./commands/open";
 import { projectsCommand } from "./commands/projects";
 import { runsCommand } from "./commands/runs";
 import { secretsCommand } from "./commands/secrets";
+import { storageCommand } from "./commands/storage";
+import { promoteCommand } from "./commands/promote";
+import { stagingCommand } from "./commands/staging";
 import { statusCommand } from "./commands/status";
 import { whoamiCommand } from "./commands/whoami";
 import { AuthRequiredError, ApiError } from "./lib/api";
@@ -33,8 +37,12 @@ Usage:
   svcloud init                  Connect a local repo as a new app
   svcloud runs <app>            Show or watch an app's provisioning run
   svcloud secrets <cmd>         Manage an app's keys & settings (list/set/remove)
+  svcloud storage presign       Get a direct URL for one file in an app's storage
   svcloud db <cmd>              Browse and edit an app's database (see 'svcloud db' for subcommands)
   svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
+  svcloud staging <cmd>         An app's staging environment (create/status/on/off)
+  svcloud promote <app>         Tag the current commit and put it on the live app
+  svcloud bundle <cmd>          Keep an app's starter current (status/update/done)
   svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
   svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
   svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
@@ -69,6 +77,9 @@ async function main(): Promise<void> {
     case "logout":
       await logoutCommand();
       return;
+    case "bundle":
+      await bundleCommand(rest, json);
+      return;
     case "whoami":
       await whoamiCommand(json);
       return;
@@ -93,12 +104,21 @@ async function main(): Promise<void> {
     case "secrets":
       await secretsCommand(rest, json);
       return;
+    case "storage":
+      await storageCommand(rest, json);
+      return;
     case "db":
       await dbCommand(rest, json);
       return;
     case "deploy":
       await deployCommand(rest, json);
       return;
+    case "staging":
+      await stagingCommand(rest, json);
+      return;
+    case "promote":
+      await promoteCommand(rest, json);
+      return;
     case "version":
     case "-v":
     case "--version":

package/src/lib/browser.ts

@@ -7,15 +7,49 @@
  */
 import { spawn } from "node:child_process";
 
+export interface LaunchPlan {
+  command: string;
+  args: string[];
+  /** Windows only: pass the args through to cmd.exe exactly as written. */
+  verbatim: boolean;
+}
+
+/**
+ * Split out from `openBrowser` so the Windows quoting can be tested without
+ * spawning anything. The Windows branch is the whole reason this exists:
+ * cmd.exe parses the command line before `start` ever sees it, and `&` is a
+ * command separator there, so an unquoted OAuth URL is truncated at its first
+ * parameter boundary. The browser then opens `...?response_type=code` with
+ * nothing after it and `GET /oauth/authorize` answers `Query parameter
+ * "client_id" is required.` Quoting the URL stops the split, and
+ * `windowsVerbatimArguments` stops Node from re-quoting the quotes we just
+ * added (its own escaping targets the MSVCRT argument parser, which runs
+ * after cmd's, and so never escapes cmd metacharacters). The bare `""` is
+ * `start`'s optional window-title argument: without it, `start` takes the
+ * quoted URL for the title and opens nothing.
+ */
+export function planBrowserLaunch(platform: NodeJS.Platform, url: string): LaunchPlan {
+  if (platform === "darwin") {
+    return { command: "open", args: [url], verbatim: false };
+  }
+  if (platform === "win32") {
+    return {
+      command: "cmd.exe",
+      args: ["/c", "start", '""', `"${url}"`],
+      verbatim: true,
+    };
+  }
+  return { command: "xdg-open", args: [url], verbatim: false };
+}
+
 export function openBrowser(url: string): void {
   try {
-    if (process.platform === "darwin") {
-      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
-    } else if (process.platform === "win32") {
-      spawn("cmd", ["/c", "start", '""', url], { stdio: "ignore", detached: true }).unref();
-    } else {
-      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
-    }
+    const plan = planBrowserLaunch(process.platform, url);
+    spawn(plan.command, plan.args, {
+      stdio: "ignore",
+      detached: true,
+      windowsVerbatimArguments: plan.verbatim,
+    }).unref();
   } catch {
     // The printed URL is the fallback; nothing else to do here.
   }

package/src/lib/git.ts

@@ -75,3 +75,36 @@ export async function gitWorkingState(cwd: string = process.cwd()): Promise<GitW
 export async function pushCurrentBranch(cwd: string = process.cwd()): Promise<void> {
   await run("git", ["push"], { cwd });
 }
+
+/** The commit the current branch points at, for naming and confirming a promotion. */
+export async function headSha(cwd: string = process.cwd()): Promise<string | undefined> {
+  try {
+    const { stdout } = await run("git", ["rev-parse", "HEAD"], { cwd });
+    return stdout.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Create an annotated tag and push it. Throws with git's own stderr on failure. */
+export async function pushTag(
+  tag: string,
+  sha: string,
+  cwd: string = process.cwd(),
+): Promise<void> {
+  await run("git", ["tag", tag, sha], { cwd });
+  await run("git", ["push", "origin", tag], { cwd });
+}
+
+/** The promotion tags already on this repo, newest first, so a new one can avoid colliding. */
+export async function existingPromotionTags(cwd: string = process.cwd()): Promise<string[]> {
+  try {
+    const { stdout } = await run("git", ["tag", "--list", "prod-*"], { cwd });
+    return stdout
+      .split("\n")
+      .map((t) => t.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}