svcloud 0.1.4 → 0.1.5

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.5",
   "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/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,7 @@ 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 { statusCommand } from "./commands/status";
 import { whoamiCommand } from "./commands/whoami";
 import { AuthRequiredError, ApiError } from "./lib/api";
@@ -33,8 +35,10 @@ 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 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 +73,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,6 +100,9 @@ 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;