svcloud 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svcloud",
-  "version": "0.1.5",
+  "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/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/index.ts

@@ -17,6 +17,8 @@ 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";
@@ -38,6 +40,8 @@ Usage:
   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
@@ -109,6 +113,12 @@ async function main(): Promise<void> {
     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 [];
+  }
+}