@hobocode/thought-layer 0.5.0 → 0.6.1

package/README.md

@@ -70,7 +70,7 @@ The hosted version of the rigor lives at [weareallproductmanagersnow.com](https:
 - **Phase 3 (done):** a `build` step that turns the hardened PRD into a deploy-ready artifact, built by your own agent (`/tl-build`), with a deterministic `tl_scaffold` tool that writes an instantly-deployable branded static site as the floor.
 - **Phase 4 (done):** a `deploy` step (`/tl-deploy`, the `deploy` tool, or `tl deploy`) that takes the build live to a URL you own, closing the loop. With a Netlify token it deploys into your own account via the file-digest API (owned immediately, no claim step); with no token it delegates to your Netlify CLI - logged in it creates a site in your account, logged out it deploys anonymously with a one-hour claim link. BYOK, no central account, no lock-in. `--dry-run` shows the plan first.
 - **Backend-capable build (done):** when the three-question backend test shows a product genuinely needs a server, `/tl-build` emits a real backend alongside the static front end (serverless functions per backend requirement, a `schema.sql`, a names-only `.env.example`, an updated `netlify.toml`, and a `BACKEND.md` guide), with Neon Postgres as the documented default and overridable to any Postgres. Static stays the default, gated by the same backend test.
-- **Next:** automated backend deploy. `tl deploy` ships the static front end today and points at `BACKEND.md` for the one-time backend steps; teaching the deploy step to provision the database and ship the functions into your own account is the follow-up.
+- **Backend deploy (done):** when `build.json` declares a backend, `/tl-deploy` (the `deploy` tool, or `tl deploy`) ships it automatically alongside the front end: the functions go up via your Netlify CLI and the declared env var names are set on the site (values read only from your environment, BYOK). `DATABASE_URL` is bring-your-own by default; `--provision-db` (your own Neon key) and `--apply-schema` (psql) are opt in, and `--static-only` ships just the front end. Owned, no lock-in.
 
 ## Notes for contributors
 

package/SECURITY.md

@@ -13,7 +13,13 @@ follow from that.
   never written to disk. The `deploy.json` record stores the resulting URLs and
   ids, never the token. When a build emits a backend, the generated `.env.example`
   is a names-only contract (every line is a bare `NAME=`): real values live only
-  in the host environment, never in a committed file.
+  in the host environment, never in a committed file. When the deploy sets those
+  env vars on your site, it reads the VALUES only from the deploy environment and
+  pushes them to your own Netlify account (in the API request body, or a
+  `0600`-mode temp file consumed by the Netlify CLI and deleted after); the
+  database connection string reaches `psql` through child-process environment
+  variables, never a command line. Values are never logged, never placed on a
+  command line, and the `deploy.json` record names env vars only, never values.
 - **Deploys go to your own account.** With a token, the deploy uses Netlify's
   file-digest API to publish into your account. With no token, it delegates to
   your installed Netlify CLI (a site in your account when logged in, or an

package/core/backend-io.ts

@@ -0,0 +1,231 @@
+// Node IO for the backend deploy automation: push env vars to the user's own
+// Netlify site, optionally provision Neon (the user's own key), and optionally
+// apply schema.sql. The deploy orchestration lives in deploy-io.ts; this file
+// holds the backend-specific side effects so deploy-io.ts stays focused and
+// core/backend.ts stays pure.
+//
+// SECRET DISCIPLINE (the whole point): secret VALUES are read ONLY from the
+// process environment inside these functions. A value never arrives as a
+// function/CLI parameter from the user, never lands in a deploy.json field,
+// never appears in a returned message, and never rides on a command line (argv).
+// Env values travel in an HTTPS request body (API) or a 0600 temp file
+// (CLI import); the database URL reaches psql through child-process env vars,
+// not argv. Env vars are recorded by NAME only.
+//
+// Copy rule for any user-facing string here: no em-dashes, no en-dashes, no
+// spaced hyphen dashes.
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EnvVarPlanItem } from "./backend.ts";
+
+const NETLIFY_API = "https://api.netlify.com/api/v1";
+const NEON_API = "https://console.neon.tech/api/v2";
+
+type Env = Record<string, string | undefined>;
+
+export interface EnvPushResult {
+  method: "api" | "cli";
+  set: string[]; // names actually pushed (value present in env)
+  missing: string[]; // names declared but absent from the deploy environment
+  note: string;
+}
+
+// ---- env vars via the account-level Netlify API (token path) -----------------
+
+// GET the site to learn its account_slug, then POST the env vars (values pulled
+// from `env`) to /accounts/{slug}/env. The value lives only in the JSON body.
+export async function pushEnvVarsApi(
+  siteId: string,
+  token: string,
+  plan: EnvVarPlanItem[],
+  env: Env,
+  accountSlug?: string,
+): Promise<EnvPushResult> {
+  const set: string[] = [];
+  const missing: string[] = [];
+  const body = plan
+    .filter((p) => {
+      const has = typeof env[p.name] === "string" && env[p.name] !== "";
+      (has ? set : missing).push(p.name);
+      return has;
+    })
+    .map((p) => ({
+      key: p.name,
+      scopes: p.scopes,
+      is_secret: p.isSecret,
+      values: [{ value: env[p.name] as string, context: p.context }],
+    }));
+
+  if (body.length === 0) {
+    return { method: "api", set, missing, note: "no declared env var had a value in the deploy environment; nothing pushed" };
+  }
+
+  const slug = accountSlug || (await getAccountSlug(siteId, token));
+  const res = await fetch(`${NETLIFY_API}/accounts/${encodeURIComponent(slug)}/env?site_id=${encodeURIComponent(siteId)}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    // Never echo the request body (it holds values); report status + names only.
+    throw new Error(`Netlify env API ${res.status} ${res.statusText} when setting ${set.join(", ")}`);
+  }
+  return { method: "api", set, missing, note: "set via the Netlify API (secret-capable, scoped to builds and functions)" };
+}
+
+async function getAccountSlug(siteId: string, token: string): Promise<string> {
+  const res = await fetch(`${NETLIFY_API}/sites/${encodeURIComponent(siteId)}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) throw new Error(`Netlify site lookup ${res.status} for env push`);
+  const site = (await res.json()) as Record<string, unknown>;
+  const slug = String(site["account_slug"] || site["account_id"] || "");
+  if (!slug) throw new Error("could not resolve the account for env push");
+  return slug;
+}
+
+// ---- env vars via the Netlify CLI (no-token path) ----------------------------
+
+// Write the values to a 0600 temp file (NAME=value), import them, and delete the
+// file in a finally. The CLI cannot mark a var secret and applies all scopes;
+// the API path is preferred when a token is present.
+export function cliImportEnv(plan: EnvVarPlanItem[], env: Env, siteId?: string): EnvPushResult {
+  const set: string[] = [];
+  const missing: string[] = [];
+  const lines: string[] = [];
+  for (const p of plan) {
+    const v = env[p.name];
+    if (typeof v === "string" && v !== "") {
+      set.push(p.name);
+      lines.push(`${p.name}=${v}`);
+    } else {
+      missing.push(p.name);
+    }
+  }
+  if (lines.length === 0) {
+    return { method: "cli", set, missing, note: "no declared env var had a value in the deploy environment; nothing imported" };
+  }
+
+  const dir = mkdtempSync(join(tmpdir(), "tl-env-"));
+  const file = join(dir, ".env.import");
+  try {
+    writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+    const args = ["env:import", "--force", file, ...(siteId ? ["--site", siteId] : [])];
+    const r = spawnSync("netlify", args, { encoding: "utf8", timeout: 60000 });
+    if (r.status !== 0) {
+      throw new Error(`netlify env:import failed (exit ${r.status}) for ${set.join(", ")}`);
+    }
+    return { method: "cli", set, missing, note: "imported via the Netlify CLI (applies all scopes; cannot mark secret)" };
+  } finally {
+    try { unlinkSync(file); } catch { /* best effort */ }
+  }
+}
+
+// ---- database url resolution (BYO, env only) ---------------------------------
+
+export interface DbUrlResult {
+  name: string | null; // which env var name carried the value
+  value: string | null; // the connection string (in memory only, never recorded)
+}
+
+// Prefer the portable DATABASE_URL, then the names Netlify managed Neon injects.
+export function resolveDbUrl(env: Env): DbUrlResult {
+  for (const name of ["DATABASE_URL", "NETLIFY_DATABASE_URL", "NETLIFY_DATABASE_URL_UNPOOLED"]) {
+    const v = env[name];
+    if (typeof v === "string" && v !== "") return { name, value: v };
+  }
+  return { name: null, value: null };
+}
+
+// ---- opt-in Neon provisioning (the user's own key) ---------------------------
+
+export interface ProvisionResult {
+  provisioned: boolean;
+  url: string | null; // connection string in memory only
+  note: string;
+}
+
+// Create a Neon project with the user's OWN NEON_API_KEY (BYOK; no central
+// account). Returns the connection string in memory. The default deploy path
+// does NOT call this; it runs only behind the explicit --provision-db flag.
+export async function provisionNeon(env: Env): Promise<ProvisionResult> {
+  const key = env["NEON_API_KEY"] || "";
+  if (!key) {
+    return { provisioned: false, url: null, note: "set NEON_API_KEY to provision, or set DATABASE_URL to bring your own database" };
+  }
+  try {
+    const res = await fetch(`${NEON_API}/projects`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ project: {} }),
+    });
+    if (!res.ok) {
+      return { provisioned: false, url: null, note: `Neon API ${res.status} ${res.statusText} when creating the project` };
+    }
+    const data = (await res.json()) as Record<string, unknown>;
+    const uris = Array.isArray(data["connection_uris"]) ? (data["connection_uris"] as Array<Record<string, unknown>>) : [];
+    const uri = uris.length ? String(uris[0]?.["connection_uri"] || "") : "";
+    if (!uri) return { provisioned: false, url: null, note: "Neon created the project but returned no connection string" };
+    return { provisioned: true, url: uri, note: "provisioned a Neon project in your account (connection string set for this deploy only)" };
+  } catch (e) {
+    return { provisioned: false, url: null, note: `Neon provisioning error: ${(e as Error).message}` };
+  }
+}
+
+// ---- opt-in schema apply via psql --------------------------------------------
+
+export interface SchemaResult {
+  applied: boolean;
+  note: string;
+}
+
+// Apply schema.sql to the database with psql. The connection string reaches psql
+// through libpq environment variables (PGHOST, PGUSER, ...), never argv, so the
+// value cannot leak onto a command line. Runs only behind the --apply-schema
+// flag. If psql is absent, print the manual command and report applied:false.
+export function applySchema(schemaPath: string, dbUrl: string | null, env: Env): SchemaResult {
+  if (!existsSync(schemaPath)) {
+    return { applied: false, note: `schema file not found at ${schemaPath}` };
+  }
+  if (!dbUrl) {
+    return { applied: false, note: "no database connection string available; set DATABASE_URL or use --provision-db" };
+  }
+  const probe = spawnSync("psql", ["--version"], { encoding: "utf8", timeout: 15000 });
+  if (probe.status !== 0) {
+    return { applied: false, note: `psql is not installed; apply it manually: psql "$DATABASE_URL" -f ${schemaPath}` };
+  }
+  let pg: Env;
+  try {
+    pg = libpqEnv(dbUrl);
+  } catch {
+    return { applied: false, note: "could not parse the database connection string" };
+  }
+  const r = spawnSync("psql", ["-v", "ON_ERROR_STOP=1", "-f", schemaPath], {
+    encoding: "utf8",
+    timeout: 120000,
+    env: { ...env, ...pg },
+  });
+  if (r.status !== 0) {
+    return { applied: false, note: `psql exited ${r.status} applying the schema` };
+  }
+  return { applied: true, note: "applied schema.sql with psql" };
+}
+
+// Split a Postgres connection string into libpq env vars so the secret never
+// touches argv. Throws on an unparseable URL.
+function libpqEnv(dbUrl: string): Env {
+  const u = new URL(dbUrl);
+  const pg: Env = {
+    PGHOST: u.hostname,
+    PGPORT: u.port || "5432",
+    PGDATABASE: decodeURIComponent(u.pathname.replace(/^\//, "")) || "neondb",
+  };
+  if (u.username) pg["PGUSER"] = decodeURIComponent(u.username);
+  if (u.password) pg["PGPASSWORD"] = decodeURIComponent(u.password);
+  const sslmode = u.searchParams.get("sslmode");
+  pg["PGSSLMODE"] = sslmode || "require";
+  return pg;
+}

package/core/backend.ts

@@ -270,3 +270,49 @@ export function normalizeBackendMeta(raw: unknown): BackendMeta | null {
     guide: str(r["guide"], "BACKEND.md"),
   };
 }
+
+// ---- deploy planning (pure; the deploy step's node IO consumes these) --------
+
+// One environment variable the deploy will set on the user's site, expressed as
+// NAME + policy only. There is deliberately no value field: the deploy reads the
+// value from its own process.env at run time and never carries it through here.
+export interface EnvVarPlanItem {
+  name: string;
+  scopes: string[]; // Netlify env scopes; functions need "functions", builds keep "builds"
+  isSecret: boolean; // mark connection strings / keys / tokens as secret in the Netlify API
+  context: string; // Netlify deploy context the value applies to
+}
+
+// Names that should be marked secret on Netlify (write-only there). A coarse,
+// safe-by-default match: anything that looks like a credential is secret.
+const SECRET_NAME_RE = /(KEY|SECRET|TOKEN|PASSWORD|PASSWD|DATABASE_URL|DB_URL|CONN|DSN|CREDENTIAL|PRIVATE|AUTH)/;
+
+function looksSecret(name: string): boolean {
+  return SECRET_NAME_RE.test(name.toUpperCase());
+}
+
+// Plan the env vars to push: the backend's declared names plus the database
+// connection var, deduped and sorted (via dedupeSortEnv, so names are sanitized
+// the same way the .env.example is). Names + policy only, never values.
+export function planEnvVars(backend: BackendMeta): EnvVarPlanItem[] {
+  const dbVar = backend.database?.envVar ? backend.database.envVar : "";
+  const merged: EnvVarSpec[] = [
+    ...(backend.envVars || []),
+    ...(dbVar ? [{ name: dbVar, required: true, description: "" }] : []),
+  ];
+  return dedupeSortEnv(merged).map((v) => ({
+    name: v.name,
+    scopes: ["builds", "functions"],
+    isSecret: looksSecret(v.name),
+    context: "all",
+  }));
+}
+
+export interface FunctionsPlan {
+  functionsDir: string; // relative dir from build.json (e.g. "netlify/functions")
+  runtime: string; // Netlify function runtime; serverless TypeScript bundles as "js"
+}
+
+export function planFunctions(backend: BackendMeta): FunctionsPlan {
+  return { functionsDir: backend.functionsDir || "netlify/functions", runtime: "js" };
+}

package/core/deploy-io.ts

@@ -25,6 +25,10 @@ import {
   buildFileDigests, uploadPath, sanitizeSiteName, parseCliDeployOutput, deployRecord,
   type FileMap, type DeployRecord,
 } from "./deploy.ts";
+import { normalizeBackendMeta, planEnvVars, type BackendMeta } from "./backend.ts";
+import {
+  pushEnvVarsApi, cliImportEnv, resolveDbUrl, provisionNeon, applySchema, type EnvPushResult,
+} from "./backend-io.ts";
 
 const NETLIFY_API = "https://api.netlify.com/api/v1";
 
@@ -34,6 +38,9 @@ export interface DeployRunOptions {
   anonymous?: boolean; // force the no-account CLI path even if a token is set
   siteName?: string;   // create the site under this name (else Netlify auto-names)
   siteId?: string;     // deploy to an existing site (re-deploy) instead of creating one
+  staticOnly?: boolean;   // ship only the front end even when build.json has a backend
+  provisionDb?: boolean;  // opt in: provision Neon with the user's own NEON_API_KEY
+  applySchema?: boolean;  // opt in: apply schema.sql with psql after the DB is reachable
 }
 
 // ---- locate + read the build manifest ----------------------------------------
@@ -241,6 +248,78 @@ function cliDeploy(publishDirAbs: string, opts: { siteName?: string; siteId?: st
   return { url: parsed.url, claimUrl: loggedIn ? null : parsed.claimUrl, owned: loggedIn, siteName, raw };
 }
 
+// ---- backend deploy helpers (functions ship via the user's Netlify CLI) ------
+
+// Resolve the functions dir from build.json (relative to the project root, then
+// cwd). Returns null when it is not on disk so the caller can ship the front end
+// only and say so, rather than failing.
+function resolveFunctionsDir(functionsDir: string, projectRoot: string): string | null {
+  const candidates = [resolve(projectRoot, functionsDir), resolve(process.cwd(), functionsDir)];
+  for (const c of candidates) if (existsSync(c)) return c;
+  return null;
+}
+
+// Count the top-level function entries (each file or directory is one function),
+// for the dry-run plan only.
+function countFunctionFiles(dir: string): number {
+  try {
+    return readdirSync(dir).filter((n) => !n.startsWith(".")).length;
+  } catch {
+    return 0;
+  }
+}
+
+// Create a site in the user's own account via the API (token path).
+async function createSiteApi(token: string, name?: string): Promise<{ id: string; slug: string; adminUrl: string; url: string }> {
+  const body = name ? JSON.stringify({ name: sanitizeSiteName(name) }) : JSON.stringify({});
+  const site = await netlifyJson(`${NETLIFY_API}/sites`, { method: "POST", headers: { "Content-Type": "application/json" }, body }, token);
+  return {
+    id: String(site["id"] || ""),
+    slug: String(site["account_slug"] || site["account_id"] || ""),
+    adminUrl: String(site["admin_url"] || ""),
+    url: String(site["ssl_url"] || site["url"] || ""),
+  };
+}
+
+// Create a site via the Netlify CLI's own stored auth (no-token path), so the
+// site id is known before env import and deploy.
+function createSiteCli(name?: string): { id: string } {
+  const payload = JSON.stringify(name ? { name: sanitizeSiteName(name) } : {});
+  const r = spawnSync("netlify", ["api", "createSite", "--data", payload], { encoding: "utf8", timeout: 60000 });
+  if (r.status !== 0) {
+    throw new Error(`netlify api createSite failed (exit ${r.status}): ${(r.stderr || r.stdout || "").slice(0, 300)}`);
+  }
+  let id = "";
+  try { id = String((JSON.parse(r.stdout || "{}") as Record<string, unknown>)["id"] || ""); } catch { /* unparseable */ }
+  if (!id) throw new Error("could not parse the new site id from the Netlify CLI");
+  return { id };
+}
+
+// Deploy the static dir plus the functions in one CLI invocation, targeting a
+// known site id. Drives functions explicitly with --functions (independent of
+// netlify.toml). --no-build keeps the CLI from re-running a framework build of
+// the already built static dir. NOTE (live-verify gate): if a real run shows
+// --no-build suppresses function bundling, drop it for backend deploys.
+function cliDeployWithFunctions(
+  publishDirAbs: string,
+  functionsDirAbs: string | null,
+  siteId: string,
+  token: string,
+): { url: string | null; raw: string } {
+  const args = [
+    "deploy", "--prod", "--dir", publishDirAbs, "--no-build",
+    ...(functionsDirAbs ? ["--functions", functionsDirAbs] : []),
+    "--site", siteId,
+  ];
+  const childEnv = token ? { ...process.env, NETLIFY_AUTH_TOKEN: token } : process.env;
+  const r = spawnSync("netlify", args, { encoding: "utf8", timeout: 300000, env: childEnv });
+  const raw = `${r.stdout || ""}\n${r.stderr || ""}`.trim();
+  if (r.status !== 0) {
+    throw new Error(`netlify ${args.join(" ")} failed (exit ${r.status}). Output:\n${raw.slice(0, 800)}`);
+  }
+  return { url: parseCliDeployOutput(raw).url, raw };
+}
+
 // ---- the orchestrator (mirrors runScaffold's result shape) -------------------
 
 export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: string }): Promise<StateOpResult> {
@@ -257,20 +336,28 @@ export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: strin
     return { ok: false, message: `Publish dir ${publishDirAbs} is empty - nothing to deploy.`, details: {} };
   }
 
-  // build.json may predate the backend block, so read it defensively.
-  const backend = manifest.backend ?? null;
-  const backendWarn = manifest.hasBackend
+  // build.json may predate the backend block, so normalize defensively.
+  const backend = normalizeBackendMeta(manifest.backend);
+  // Ship the backend automatically when the build declares a serverless one,
+  // unless the caller forced a static-only deploy. Static deploys with no
+  // backend are byte-for-byte unchanged (backend is null, shipBackend false).
+  const shipBackend = manifest.hasBackend && backend?.backendKind === "serverless" && !opts.staticOnly;
+
+  // The note shown only when there is a backend that this deploy will NOT ship
+  // (static-only by request, or a non-serverless backend we cannot automate).
+  const backendWarn = manifest.hasBackend && !shipBackend
     ? (() => {
         const guide = backend?.guide || "BACKEND.md";
         const dbEnv = backend?.database?.envVar || "DATABASE_URL";
         const names = (backend?.envVars || []).map((v) => v.name).filter(Boolean);
         const others = names.filter((n) => n !== dbEnv);
         const envList = others.length ? `${dbEnv} plus ${others.join(", ")}` : dbEnv;
+        const lead = opts.staticOnly
+          ? `\n\nStatic only: the front end is live, the backend was not shipped (you passed --static-only). Re-run without it to ship the backend.`
+          : `\n\nStatic deploy: the front end is live. This build also declares a backend that this deploy cannot ship automatically.`;
         return (
-          `\n\nStatic deploy: the front end goes live now. This project also has a backend ` +
-          `(build.json hasBackend is true${manifest.backendNote ? `: ${manifest.backendNote}` : ""}). ` +
-          `The backend artifact (serverless functions, schema.sql, a names-only .env.example) is built but not auto-deployed yet; backend deploy automation is a follow-up. ` +
-          `To run it yourself, follow ${guide}: provision Neon Postgres, set ${envList} in your host environment, then run netlify deploy with the functions present.`
+          `${lead} To run the backend, follow ${guide}: provision Neon Postgres, set ${envList} in your host environment, ` +
+          `then run netlify deploy with the functions present.`
         );
       })()
     : "";
@@ -287,15 +374,45 @@ export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: strin
   // --- dry run: plan only, no network, no spawn ---
   if (opts.dryRun) {
     const { digests } = buildFileDigests(files);
+    let backendPlanMsg = backendWarn;
+    let backendPlan: Record<string, unknown> | null = null;
+    if (shipBackend && backend) {
+      // Names + counts only; never read or print an env value.
+      const fnDir = resolveFunctionsDir(backend.functionsDir, dirname(dirname(stateFile)));
+      const fnCount = fnDir ? countFunctionFiles(fnDir) : 0;
+      const plan = planEnvVars(backend);
+      const names = plan.map((p) => p.name);
+      const missing = names.filter((n) => !(typeof process.env[n] === "string" && process.env[n] !== ""));
+      const db = resolveDbUrl(process.env);
+      const path = token ? "Netlify CLI for functions plus the token API for env" : "Netlify CLI (logged in) for functions and env import";
+      backendPlanMsg =
+        `\n\nBackend plan: ship ${fnCount} function${fnCount === 1 ? "" : "s"} from ${backend.functionsDir} via the ${path}. ` +
+        `Env var names (${names.length}): ${names.join(", ") || "none"}.` +
+        `${missing.length ? ` Missing from this environment: ${missing.join(", ")}.` : ""}` +
+        `${db.name ? ` Database url from ${db.name}.` : " No database url found (set DATABASE_URL, or use --provision-db)."}` +
+        `${opts.provisionDb ? " Would provision Neon (--provision-db)." : ""}` +
+        `${opts.applySchema ? " Would apply schema.sql (--apply-schema)." : ""}`;
+      backendPlan = { functionsDir: backend.functionsDir, functionCount: fnCount, envVarNames: names, envVarsMissing: missing, dbUrlFrom: db.name, provisionDb: !!opts.provisionDb, applySchema: !!opts.applySchema };
+    }
     return {
       ok: true,
       message:
         `Dry run: would deploy ${fileCount} files from ${publishDirAbs} (entry ${manifest.entry}) to Netlify ` +
-        `via the ${token && !opts.anonymous ? "BYO-token digest" : "Netlify CLI (logged in -> a site in your account; logged out -> an anonymous claimable site)"} path.${backendWarn}`,
-      details: { dryRun: true, publishDir: publishDirAbs, entry: manifest.entry, fileCount, files: Object.keys(digests), hasBackend: manifest.hasBackend },
+        `via the ${token && !opts.anonymous ? "BYO-token digest" : "Netlify CLI (logged in -> a site in your account; logged out -> an anonymous claimable site)"} path.${backendPlanMsg}`,
+      details: { dryRun: true, publishDir: publishDirAbs, entry: manifest.entry, fileCount, files: Object.keys(digests), hasBackend: manifest.hasBackend, shipBackend, backendPlan },
     };
   }
 
+  // --- backend deploy: ship functions + env into the user's own account ---
+  if (shipBackend && backend) {
+    return runBackendDeploy(
+      { manifest, backend, publishDirAbs, stateFile, fileCount, files },
+      opts,
+      ctx,
+      { token, writeRecord },
+    );
+  }
+
   // --- CLI path: explicit (--anonymous), or the fallback when no env token ---
   const wantCli = opts.anonymous || !token;
   if (wantCli) {
@@ -380,3 +497,143 @@ export async function runDeploy(opts: DeployRunOptions, ctx: { deployedAt: strin
     return { ok: false, message: `Deploy failed: ${(e as Error).message}`, details: { mode: "token" } };
   }
 }
+
+// Ship the backend (functions + env vars) into the user's own account. Functions
+// are bundled and shipped by the user's Netlify CLI (the digest API cannot bundle
+// TypeScript), so this forces the CLI deploy mechanism even when a token is set;
+// the token, when present, is used for the secret-capable env API and to authorize
+// the CLI non-interactively (owned, no claim). Env var VALUES are read only from
+// process.env inside the backend-io helpers and are never recorded or printed.
+async function runBackendDeploy(
+  build: { manifest: BuildManifest; backend: BackendMeta; publishDirAbs: string; stateFile: string; fileCount: number; files: FileMap },
+  opts: DeployRunOptions,
+  ctx: { deployedAt: string },
+  io: { token: string; writeRecord: (rec: DeployRecord) => string },
+): Promise<StateOpResult> {
+  const { manifest, backend, publishDirAbs, stateFile, fileCount, files } = build;
+  const { token, writeRecord } = io;
+  const projectRoot = dirname(dirname(stateFile));
+  const plan = planEnvVars(backend);
+  const guide = backend.guide || "BACKEND.md";
+  const notes: string[] = [];
+
+  // Opt in: provision Neon with the user's own key, so the DB url is known.
+  let dbUrl = resolveDbUrl(process.env).value;
+  let dbProvisioned = false;
+  if (opts.provisionDb) {
+    const pr = await provisionNeon(process.env);
+    notes.push(pr.note);
+    if (pr.provisioned && pr.url) { dbUrl = pr.url; dbProvisioned = true; }
+  }
+
+  const functionsDirAbs = resolveFunctionsDir(backend.functionsDir, projectRoot);
+
+  // No CLI means functions cannot be bundled. Do not half-deploy: with a token,
+  // still take the front end live and push env via the API; without one, stop
+  // and guide. functionsShipped stays false either way.
+  if (!hasNetlifyCli()) {
+    if (!token) {
+      return {
+        ok: false,
+        message:
+          `This build has a backend, which needs the Netlify CLI to bundle and ship the functions, and the CLI is not installed. ` +
+          `Install it (npm i -g netlify-cli@latest) and re-run, or set NETLIFY_AUTH_TOKEN to at least take the front end live, or follow ${guide}.`,
+        details: { backendMode: "static-only-fallback", functionsShipped: false, needs: "netlify-cli" },
+      };
+    }
+    try {
+      const r = await digestDeploy(files, { token, siteName: opts.siteName, siteId: opts.siteId });
+      let env: EnvPushResult | null = null;
+      try { env = await pushEnvVarsApi(r.siteId, token, plan, process.env); }
+      catch (e) { notes.push(`env push failed: ${(e as Error).message}`); }
+      const recPath = writeRecord(deployRecord({
+        deployedAt: ctx.deployedAt, mode: "token", publishDir: manifest.publishDir, fileCount,
+        url: r.url || null, adminUrl: r.adminUrl || null, claimUrl: null, siteId: r.siteId, deployId: r.deployId,
+        hasBackend: true, backendNote: manifest.backendNote, backendKind: backend.backendKind,
+        backendMode: "static-only-fallback", functionsShipped: false, functionsDir: backend.functionsDir,
+        envVarsSet: env?.set ?? [], envVarsMissing: env?.missing ?? plan.map((p) => p.name),
+        dbProvisioned, schemaApplied: false, buildProducer: manifest.producer, stateFile,
+      }));
+      return {
+        ok: true,
+        message:
+          `Deployed the static front end to your Netlify account${r.url ? ` (live: ${r.url})` : ""}. ` +
+          `The functions were NOT shipped: the Netlify CLI bundles them and it is not installed. ` +
+          `Install it (npm i -g netlify-cli@latest) and re-run to ship the backend, or follow ${guide}.` +
+          (env?.set.length ? `\nSet env var names: ${env.set.join(", ")}.` : "") +
+          (env?.missing.length ? `\nDeclared but missing from this environment: ${env.missing.join(", ")}.` : "") +
+          `\nRecorded ${recPath}.${notes.length ? `\n${notes.join("\n")}` : ""}`,
+        details: { mode: "token", backendMode: "static-only-fallback", functionsShipped: false, url: r.url, siteId: r.siteId, envVarsSet: env?.set, envVarsMissing: env?.missing },
+      };
+    } catch (e) {
+      return { ok: false, message: `Static front end deploy failed: ${(e as Error).message}`, details: { backendMode: "static-only-fallback" } };
+    }
+  }
+
+  if (!functionsDirAbs) {
+    notes.push(`functions dir "${backend.functionsDir}" was not found on disk; shipping the front end only`);
+  }
+
+  // Resolve or create the target site so env can be set against a known id.
+  let siteId = opts.siteId || "";
+  let accountSlug: string | undefined;
+  try {
+    if (!siteId) {
+      if (token) { const s = await createSiteApi(token, opts.siteName); siteId = s.id; accountSlug = s.slug; }
+      else { siteId = createSiteCli(opts.siteName).id; }
+    }
+  } catch (e) {
+    return { ok: false, message: `Could not create the Netlify site for the backend deploy: ${(e as Error).message}`, details: {} };
+  }
+
+  // Push env vars (API when a token is present, else CLI import).
+  let env: EnvPushResult;
+  try {
+    env = token
+      ? await pushEnvVarsApi(siteId, token, plan, process.env, accountSlug)
+      : cliImportEnv(plan, process.env, siteId);
+  } catch (e) {
+    env = { method: token ? "api" : "cli", set: [], missing: plan.map((p) => p.name), note: `env push failed: ${(e as Error).message}` };
+    notes.push(env.note);
+  }
+
+  // Opt in: apply schema.sql now that the database url is known.
+  let schemaApplied = false;
+  if (opts.applySchema) {
+    const schemaPath = resolve(projectRoot, backend.database?.schemaFile || "schema.sql");
+    const sr = applySchema(schemaPath, dbUrl, process.env);
+    schemaApplied = sr.applied;
+    notes.push(sr.note);
+  }
+
+  // Deploy the static dir plus the functions in one CLI invocation.
+  let url: string | null = null;
+  try {
+    const d = cliDeployWithFunctions(publishDirAbs, functionsDirAbs, siteId, token);
+    url = d.url;
+  } catch (e) {
+    return { ok: false, message: `Backend deploy failed: ${(e as Error).message}${notes.length ? `\n${notes.join("\n")}` : ""}`, details: { siteId, envVarsSet: env.set } };
+  }
+  const functionsShipped = !!functionsDirAbs;
+
+  const recPath = writeRecord(deployRecord({
+    deployedAt: ctx.deployedAt, mode: "cli", publishDir: manifest.publishDir, fileCount,
+    url, adminUrl: null, claimUrl: null, siteId, deployId: null,
+    hasBackend: true, backendNote: manifest.backendNote, backendKind: backend.backendKind,
+    backendMode: "cli", functionsShipped, functionsDir: backend.functionsDir,
+    envVarsSet: env.set, envVarsMissing: env.missing, dbProvisioned, schemaApplied,
+    buildProducer: manifest.producer, stateFile,
+  }));
+  return {
+    ok: true,
+    message:
+      `Deployed your backend to your Netlify account via the CLI${url ? ` (live: ${url})` : ""}. ` +
+      `${functionsShipped ? `Functions shipped from ${backend.functionsDir}.` : `No functions were found on disk (${backend.functionsDir}); front end only.`} ` +
+      `It is owned by your account, no claim needed. Re-deploy to the same site with --site ${siteId}.` +
+      (env.set.length ? `\nSet env var names (${env.method}): ${env.set.join(", ")}.` : "") +
+      (env.missing.length ? `\nDeclared but missing from this environment (set them, then re-run): ${env.missing.join(", ")}.` : "") +
+      `\nRecorded ${recPath}.${notes.length ? `\n${notes.join("\n")}` : ""}` +
+      (!url ? `\n(Could not parse a live URL from the CLI output; re-run to confirm.)` : ""),
+    details: { mode: "cli", backendMode: "cli", url, siteId, functionsShipped, functionsDir: backend.functionsDir, envVarsSet: env.set, envVarsMissing: env.missing, dbProvisioned, schemaApplied },
+  };
+}

package/core/deploy.ts

@@ -108,9 +108,17 @@ export interface DeployRecord {
   hasBackend: boolean;
   backendNote: string | null;
   // Provenance of the backend payload from build.json (null for a static build).
-  // The static deploy does not ship a backend; this just records what the build
-  // declared, for the deploy-automation follow-up to read.
   backendKind?: BackendKind | null;
+  // Backend deploy provenance (all optional so static deploy.json records, and
+  // records written before this field set existed, round-trip unchanged). NEVER
+  // a secret value: env vars are recorded by NAME only.
+  backendMode?: "none" | "cli" | "static-only-fallback";
+  functionsShipped?: boolean;
+  functionsDir?: string | null;
+  envVarsSet?: string[]; // names only
+  envVarsMissing?: string[]; // names declared but absent from the deploy environment
+  dbProvisioned?: boolean;
+  schemaApplied?: boolean;
   buildProducer: "agent" | "scaffold" | null;
   stateFile: string | null;
 }