passcontrol 0.9.4 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -36,6 +36,7 @@ import {
36
36
  formatProxyError,
37
37
  globalConfigPath,
38
38
  mergeConfigFile,
39
+ localActivationPatch,
39
40
  mergeConfigFileAtomic,
40
41
  muted,
41
42
  heading,
@@ -47,6 +48,7 @@ import {
47
48
  probeGatewayOrigin,
48
49
  requirePassportGateway,
49
50
  requirePassport,
51
+ shellQuotingHint,
50
52
  step,
51
53
  warn,
52
54
  writeConfigFile,
@@ -68,7 +70,19 @@ import {
68
70
  supportsWrite,
69
71
  } from "../cli/presets.mjs";
70
72
  import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
71
- import { checkForUpdate } from "../cli/update-check.mjs";
73
+ import { checkForUpdate, fetchLatest, REGISTRY_URL } from "../cli/update-check.mjs";
74
+ import {
75
+ clearMarker,
76
+ detectInstall,
77
+ dirtyBlockers,
78
+ expectedProjectId,
79
+ formatPlan,
80
+ isPublicRepoUrl,
81
+ planUpdate,
82
+ readMarker,
83
+ stackFromConfig,
84
+ writeMarker,
85
+ } from "../cli/update.mjs";
72
86
  import { startSidecar } from "../cli/sidecar.mjs";
73
87
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
74
88
  import { loginCommand } from "../cli/login.mjs";
@@ -185,6 +199,7 @@ ${heading("Operate")}
185
199
  ${cmd} status [--no-network] [--json]
186
200
  show active config and instance state
187
201
  ${cmd} version [--json] CLI, gateway and database schema versions
202
+ ${cmd} update [--check] [--yes] update this CLI and the local self-host app (code, dependencies, migrations)
188
203
  ${cmd} doctor [--deep] [--fix] diagnose setup and repair a stopped dashboard
189
204
  ${cmd} open open the Control Tower in a browser
190
205
  ${cmd} logout [--revoke-agent] revoke this machine's key and clear its credentials
@@ -790,6 +805,7 @@ async function prepareLocalActivation(target, opts = {}) {
790
805
  storageMarker,
791
806
  previousGateway: config.gateway,
792
807
  globalPath: globalConfigPath(),
808
+ globalValues: values,
793
809
  };
794
810
  }
795
811
 
@@ -806,16 +822,21 @@ function restoreFileAtomically(file, contents) {
806
822
  }
807
823
 
808
824
  function commitLocalActivation(prepared) {
809
- if (!prepared.switching) return;
825
+ const patch = localActivationPatch({
826
+ switching: prepared.switching,
827
+ globalValues: prepared.globalValues,
828
+ targetUrl: prepared.target.url,
829
+ });
830
+ if (!patch) return;
810
831
  const existed = fs.existsSync(prepared.globalPath);
811
832
  const previous = existed ? fs.readFileSync(prepared.globalPath, "utf8") : null;
812
- mergeConfigFileAtomic(prepared.globalPath, {
813
- PASSCONTROL_GATEWAY: prepared.target.url,
814
- PASSPORT_ID: "",
815
- PASSPORT_SECRET: "",
816
- PASSPORT_KEY_STORAGE: "",
817
- PASSCONTROL_API_KEY: "",
818
- });
833
+ mergeConfigFileAtomic(prepared.globalPath, patch);
834
+ if (!prepared.switching) {
835
+ // A fresh machine: nothing to forget, only the gateway to record so that
836
+ // `login` targets this stack instead of Cloud.
837
+ ok(`active gateway set to ${prepared.target.url}`);
838
+ return;
839
+ }
819
840
 
820
841
  if (prepared.storageMarker === PASSPORT_KEY_STORAGE_OS && prepared.passportId) {
821
842
  const removed = createPassportCredentialStore().delete(prepared.passportId);
@@ -1072,16 +1093,65 @@ function removeDashboardState() {
1072
1093
  fs.rmSync(dashboardStatePath(), { force: true });
1073
1094
  }
1074
1095
 
1096
+ /**
1097
+ * The command line of a live process, or null when it cannot be read.
1098
+ *
1099
+ * `ps -o command=` on macOS and Linux; on Windows, the CIM process record via
1100
+ * PowerShell (present on every supported Windows). Bounded, never throws.
1101
+ */
1102
+ function processCommandLine(pid) {
1103
+ try {
1104
+ if (process.platform === "win32") {
1105
+ const out = execFileSync(
1106
+ "powershell.exe",
1107
+ ["-NoProfile", "-NonInteractive", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`],
1108
+ { encoding: "utf8", timeout: 10_000, windowsHide: true }
1109
+ );
1110
+ return out.trim() || null;
1111
+ }
1112
+ const out = execFileSync("ps", ["-o", "command=", "-p", String(Number(pid))], { encoding: "utf8", timeout: 5_000 });
1113
+ return out.trim() || null;
1114
+ } catch {
1115
+ return null;
1116
+ }
1117
+ }
1118
+
1119
+ /**
1120
+ * Whether the recorded PID is still the supervisor this CLI spawned (C7).
1121
+ *
1122
+ * A live PID alone is not proof: after a crash or reboot the state file
1123
+ * survives and the OS reuses the number, and `stop` then signalled the new
1124
+ * owner's whole process group — or, on Windows, `taskkill /T` its tree. The
1125
+ * state records the script the supervisor runs; the PID is ours only while its
1126
+ * command line still names it. Older state files without `script` fall back to
1127
+ * the launcher's file name.
1128
+ *
1129
+ * "unknown" (the command line could not be read) is not "ours": status still
1130
+ * reports it, but nothing is killed on an unverified PID.
1131
+ */
1132
+ function managedDashboardIdentity(state) {
1133
+ const command = processCommandLine(state.pid);
1134
+ if (command === null) return "unknown";
1135
+ const expected = typeof state.script === "string" && state.script ? state.script : "dev-docker.mjs";
1136
+ return command.includes(expected) ? "ours" : "other";
1137
+ }
1138
+
1075
1139
  function runningManagedDashboard() {
1076
1140
  const state = readDashboardState();
1077
1141
  if (!state) return null;
1078
1142
  try {
1079
1143
  process.kill(state.pid, 0);
1080
- return state;
1081
1144
  } catch (error) {
1082
1145
  if (error.code === "ESRCH") removeDashboardState();
1083
1146
  return null;
1084
1147
  }
1148
+ const identity = managedDashboardIdentity(state);
1149
+ if (identity === "other") {
1150
+ // The PID now belongs to something else. The dashboard we started is gone.
1151
+ removeDashboardState();
1152
+ return null;
1153
+ }
1154
+ return { ...state, verified: identity === "ours" };
1085
1155
  }
1086
1156
 
1087
1157
  function dashboardStatusLabel(gateway, noNetwork, target = managedDashboardTarget()) {
@@ -1248,13 +1318,28 @@ async function startDashboard(opts = {}) {
1248
1318
  // work (that is all the npm script is now), minus npm/cmd wrappers. Next's CLI
1249
1319
  // still forks its HTTP worker, so this pid is deliberately the SUPERVISOR.
1250
1320
  // Unix stops its process group; Windows uses taskkill /T for the whole tree.
1321
+ //
1322
+ // `detached` is set on BOTH platforms, and the two reasons are different.
1323
+ // Unix needs it for the process group `stopDashboard` signals with kill(-pid).
1324
+ // Windows needs it for something else entirely: it is what lets the child
1325
+ // outlive us at all. This read `process.platform !== "win32"` — detached only
1326
+ // on Unix, on the reasoning that Windows takes its tree from taskkill and so
1327
+ // has no use for a process group. True, and it answered the wrong question.
1328
+ //
1329
+ // `child.unref()` below only lets the PARENT exit; it does not let the child
1330
+ // survive. So on Windows `passcontrol start` raised the dashboard, waited for
1331
+ // it, truthfully printed "dashboard online" — waitForGateway requires a live
1332
+ // pid and an answering gateway on the same poll — and then killed it by
1333
+ // returning. `setup` did the same, which is worse: a first-run self-hoster is
1334
+ // handed a URL that stops working as they read it, with an empty log and no
1335
+ // error anywhere. Reported and reproduced on Windows 11, 2026-09-13.
1251
1336
  const devServer = path.join(appRoot, "scripts", "dev-docker.mjs");
1252
1337
  if (!fs.existsSync(devServer)) {
1253
1338
  throw new Error(`${devServer} is missing — this checkout is incomplete or predates the local-stack launcher. Re-clone, or run \`npm run dev:docker\` from ${appRoot} by hand.`);
1254
1339
  }
1255
1340
  const child = spawn(process.execPath, [devServer], {
1256
1341
  cwd: appRoot,
1257
- detached: process.platform !== "win32",
1342
+ detached: true,
1258
1343
  env: { ...process.env, PORT: String(dashboard.port) },
1259
1344
  stdio: ["ignore", logFd, logFd],
1260
1345
  });
@@ -1262,7 +1347,8 @@ async function startDashboard(opts = {}) {
1262
1347
  child.unref();
1263
1348
  fs.writeFileSync(
1264
1349
  statePath,
1265
- `${JSON.stringify({ pid: child.pid, gateway: dashboard.url, port: dashboard.port, logPath, startedAt: new Date().toISOString() })}\n`,
1350
+ // `script` is the identity check's anchor — see managedDashboardIdentity.
1351
+ `${JSON.stringify({ pid: child.pid, script: devServer, gateway: dashboard.url, port: dashboard.port, logPath, startedAt: new Date().toISOString() })}\n`,
1266
1352
  { mode: 0o600 }
1267
1353
  );
1268
1354
 
@@ -1275,41 +1361,76 @@ async function startDashboard(opts = {}) {
1275
1361
  return dashboard;
1276
1362
  }
1277
1363
 
1364
+ /**
1365
+ * Take down pid and everything below it on Windows. Reports, never throws.
1366
+ *
1367
+ * `taskkill /T` WITHOUT `/F` asks politely, and asking needs somewhere to ask:
1368
+ * a `DETACHED_PROCESS` child has no console and no window, so Windows answers
1369
+ * "This process can only be terminated forcefully (with /F option)" and taskkill
1370
+ * exits NON-ZERO. `execFileSync` turns a non-zero exit into a throw.
1371
+ *
1372
+ * That throw is why `passcontrol stop --dashboard-only` refused on Windows the
1373
+ * moment the dashboard started being spawned detached: the catch around it only
1374
+ * rescued `ESRCH`, a POSIX errno a failing taskkill cannot produce, so it
1375
+ * rethrew and abandoned the stop eight lines above the `/F` escalation the
1376
+ * function already had. The two-stage design was right; the throw jumped stage
1377
+ * two. Reported from a Windows 11 box, 2026-09-13.
1378
+ *
1379
+ * So a non-zero exit is an ANSWER here, not an exception — it is how Windows
1380
+ * says "use /F" — and the caller decides what to do about it. Whether the
1381
+ * dashboard is actually down is settled by the port, not by this.
1382
+ */
1383
+ function windowsTaskkillTree(pid, { force }) {
1384
+ const args = ["/PID", String(pid), "/T", ...(force ? ["/F"] : [])];
1385
+ try {
1386
+ execFileSync("taskkill.exe", args, { encoding: "utf8", timeout: 10_000, windowsHide: true });
1387
+ return true;
1388
+ } catch {
1389
+ return false;
1390
+ }
1391
+ }
1392
+
1278
1393
  async function stopDashboard() {
1279
1394
  const state = runningManagedDashboard();
1280
1395
  if (!state) {
1281
1396
  ok("No CLI-managed local dashboard is running.");
1282
1397
  return;
1283
1398
  }
1399
+ if (!state.verified) {
1400
+ // Refuse rather than guess: signalling a process group we cannot identify
1401
+ // is exactly the failure this check exists to prevent.
1402
+ throw new Error(
1403
+ `Could not confirm that PID ${state.pid} is the dashboard this CLI started, so it was not stopped. ` +
1404
+ `Stop it yourself if it is, then delete ${dashboardStatePath()}.`
1405
+ );
1406
+ }
1284
1407
 
1285
- try {
1286
- if (process.platform === "win32") {
1287
- execFileSync("taskkill.exe", ["/PID", String(state.pid), "/T"], {
1288
- encoding: "utf8",
1289
- timeout: 10_000,
1290
- windowsHide: true,
1291
- });
1292
- } else process.kill(-state.pid, "SIGTERM");
1293
- } catch (error) {
1294
- if (error.code === "ESRCH") {
1295
- removeDashboardState();
1296
- ok("No CLI-managed local dashboard is running.");
1297
- return;
1408
+ if (process.platform === "win32") {
1409
+ // Politely first — it lets Next flush if anything is listening for it — but
1410
+ // escalate the instant taskkill says it cannot, rather than waiting out a
1411
+ // port that a refused kill is never going to release. The port check below
1412
+ // is still the authority, and still escalates on its own.
1413
+ if (!windowsTaskkillTree(state.pid, { force: false })) {
1414
+ windowsTaskkillTree(state.pid, { force: true });
1415
+ }
1416
+ } else {
1417
+ try {
1418
+ process.kill(-state.pid, "SIGTERM");
1419
+ } catch (error) {
1420
+ if (error.code === "ESRCH") {
1421
+ removeDashboardState();
1422
+ ok("No CLI-managed local dashboard is running.");
1423
+ return;
1424
+ }
1425
+ throw error;
1298
1426
  }
1299
- throw error;
1300
1427
  }
1301
1428
 
1302
1429
  if (!await waitForPortRelease(state.port)) {
1303
- if (process.platform === "win32") {
1304
- execFileSync("taskkill.exe", ["/PID", String(state.pid), "/T", "/F"], {
1305
- encoding: "utf8",
1306
- timeout: 10_000,
1307
- windowsHide: true,
1308
- });
1309
- }
1430
+ if (process.platform === "win32") windowsTaskkillTree(state.pid, { force: true });
1310
1431
  else process.kill(-state.pid, "SIGKILL");
1311
1432
  if (!await waitForPortRelease(state.port)) {
1312
- throw new Error(`Dashboard process group ${state.pid} did not release port ${state.port}.`);
1433
+ throw new Error(`Dashboard (PID ${state.pid}) did not release port ${state.port}.`);
1313
1434
  }
1314
1435
  }
1315
1436
  removeDashboardState();
@@ -1504,6 +1625,188 @@ async function resetLocalStack(opts = {}) {
1504
1625
  ok("Local stack recreated. Run `passcontrol start` to launch the dashboard.");
1505
1626
  }
1506
1627
 
1628
+ // ── passcontrol update ───────────────────────────────────────────────────────
1629
+ //
1630
+ // The decisions live in cli/update.mjs (pure, tested); this is the half that
1631
+ // runs git, npm and the stack. Order matters and is the whole design: read
1632
+ // everything, show the plan, ask once, update the CLI, then hand the app phase
1633
+ // to the NEW CLI so the version doing the work is the one that knows the steps.
1634
+
1635
+ function gitIn(root, args, timeout = 60_000, { raw = false } = {}) {
1636
+ const out = execFileSync("git", args, { cwd: root, encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] });
1637
+ // `raw` for porcelain output, whose leading space is a status column.
1638
+ return raw ? out : out.trim();
1639
+ }
1640
+
1641
+ /** The self-host checkout's state, or why it is left alone. Fetches origin/main. */
1642
+ function analyzeAppForUpdate({ fetchRemote = true } = {}) {
1643
+ let source;
1644
+ try {
1645
+ source = resolveAppRootSource();
1646
+ } catch (error) {
1647
+ return { status: "refuse", reason: error.message };
1648
+ }
1649
+ if (!source) return { status: "none" };
1650
+ const root = source.path;
1651
+ const marker = readMarker();
1652
+ const resume = marker && path.resolve(marker.appRoot) === root ? marker : null;
1653
+ const refuse = (reason) => ({ status: "refuse", root, reason, resume });
1654
+
1655
+ if (!fs.existsSync(path.join(root, ".git"))) {
1656
+ return refuse(`${root} is not a git checkout (a downloaded archive?), so it cannot be fast-forwarded. Update it by hand, or replace it with a fresh \`${cliCommand("setup")}\` clone.`);
1657
+ }
1658
+ let origin = "";
1659
+ try {
1660
+ origin = gitIn(root, ["config", "--get", "remote.origin.url"]);
1661
+ } catch {
1662
+ // No origin: refused just below.
1663
+ }
1664
+ if (!isPublicRepoUrl(origin, PUBLIC_REPO_URL)) {
1665
+ return refuse(`${root} is not a clone of the public PassControl repo (origin: ${origin || "none"}), so it is its owner's to update.`);
1666
+ }
1667
+ let branch = "";
1668
+ try {
1669
+ branch = gitIn(root, ["symbolic-ref", "--short", "HEAD"]);
1670
+ } catch {
1671
+ // Detached HEAD: refused just below.
1672
+ }
1673
+ if (branch !== "main") return refuse(`${root} is on ${branch || "a detached HEAD"}, not main.`);
1674
+ const blockers = dirtyBlockers(gitIn(root, ["status", "--porcelain", "--untracked-files=no"], 60_000, { raw: true }));
1675
+ if (blockers.length) {
1676
+ return refuse(`${root} has local changes (${blockers.join(", ")}). Commit or discard them, then rerun.`);
1677
+ }
1678
+ const configPath = path.join(root, "supabase", "config.toml");
1679
+ const stack = fs.existsSync(configPath) ? stackFromConfig(fs.readFileSync(configPath, "utf8")) : null;
1680
+ if (!stack) return refuse(`the local stack was never set up in ${root}; run \`${cliCommand("setup")}\` first.`);
1681
+ const expected = expectedProjectId(path.basename(root), stack.offset);
1682
+ if (stack.projectId !== expected) {
1683
+ return refuse(
1684
+ `supabase/config.toml names the project "${stack.projectId}", but this directory would now run as "${expected}". ` +
1685
+ "Was the checkout moved or renamed? Re-running the stack here would start an EMPTY database, so it is left alone. Move it back, then rerun."
1686
+ );
1687
+ }
1688
+ if (fetchRemote) {
1689
+ try {
1690
+ gitIn(root, ["fetch", "--quiet", "origin", "main"], 120_000);
1691
+ } catch (error) {
1692
+ return refuse(`could not fetch the public repo (${String(error.message).split("\n")[0]}).`);
1693
+ }
1694
+ }
1695
+ const head = gitIn(root, ["rev-parse", "HEAD"]);
1696
+ const target = gitIn(root, ["rev-parse", "origin/main"]);
1697
+ const ahead = Number(gitIn(root, ["rev-list", "--count", "origin/main..HEAD"]));
1698
+ if (ahead > 0) return refuse(`${root} has ${ahead} commit(s) that are not in the public repo, so it cannot be fast-forwarded.`);
1699
+ const behind = Number(gitIn(root, ["rev-list", "--count", "HEAD..origin/main"]));
1700
+ const base = { root, offset: stack.offset, head, target, resume, lockfileDirty: gitIn(root, ["status", "--porcelain", "--untracked-files=no", "--", "package-lock.json"]) !== "" };
1701
+ if (behind === 0) return { status: "current", ...base };
1702
+ const migrations = gitIn(root, ["diff", "--name-only", "--diff-filter=A", head, target, "--", "db/migrations"]).split("\n").filter(Boolean);
1703
+ return { status: "behind", behind, from: head.slice(0, 7), to: target.slice(0, 7), migrations, ...base };
1704
+ }
1705
+
1706
+ async function applyAppUpdate(app) {
1707
+ appRoot = app.root;
1708
+ const npm = process.platform === "win32" ? "npm.cmd" : "npm";
1709
+ const dashboard = managedDashboardTarget();
1710
+ const managed = runningManagedDashboard();
1711
+ // A dashboard the CLI did not start (\`npm run dev\` by hand) would have its
1712
+ // dependencies and env rewritten underneath it — the same trap as building
1713
+ // while dev runs. Refuse rather than break it.
1714
+ if (!managed && await portIsListening(dashboard.port)) {
1715
+ throw new Error(
1716
+ `Port ${dashboard.port} is served by something this CLI did not start (a dashboard run by hand?). Stop it, then rerun \`${cliCommand("update")}\`. Nothing was changed.`
1717
+ );
1718
+ }
1719
+ const restart = app.resume?.wasRunning ?? Boolean(managed);
1720
+ const from = app.resume?.from ?? app.head;
1721
+ writeMarker({ appRoot: app.root, from, to: app.target, wasRunning: restart, startedAt: new Date().toISOString() });
1722
+ try {
1723
+ if (managed) {
1724
+ step("Stopping the dashboard…");
1725
+ await stopDashboard();
1726
+ }
1727
+ if (app.status === "behind") {
1728
+ // npm's own rewrite of the lockfile (see dirtyBlockers); \`npm ci\` below
1729
+ // installs exactly what the new lockfile says.
1730
+ if (app.lockfileDirty) gitIn(app.root, ["checkout", "--", "package-lock.json"]);
1731
+ step(`Fast-forwarding ${app.from} → ${app.to}…`);
1732
+ await runCommand("git", ["merge", "--ff-only", "origin/main"], { cwd: app.root });
1733
+ }
1734
+ step("Installing dependencies (npm ci)…");
1735
+ await runCommand(npm, ["ci"], { cwd: app.root });
1736
+ step("Applying migrations and refreshing the local stack…");
1737
+ await runCommand(npm, ["run", "dev:stack"], {
1738
+ cwd: app.root,
1739
+ env: { ...process.env, PASSCONTROL_PORT_OFFSET: String(app.offset), PASSCONTROL_SKIP_SEED: "1", PASSCONTROL_VIA_CLI: "1" },
1740
+ });
1741
+ if (restart) await startDashboard({ dashboardOnly: true });
1742
+ } catch (error) {
1743
+ throw new Error(
1744
+ `The update stopped part way: ${error.message}\n` +
1745
+ `Fix the cause, then run \`${cliCommand("update --app-only")}\` to finish (install, migrations${restart ? ", restart" : ""}). ` +
1746
+ "The dashboard is stopped until then."
1747
+ );
1748
+ }
1749
+ clearMarker();
1750
+ ok(`App updated to ${String(app.target).slice(0, 7)}.`);
1751
+ step(`To roll back the code: git -C ${app.root} checkout ${from}. Database migrations only go forward.`);
1752
+ }
1753
+
1754
+ async function updateCommand(opts = {}) {
1755
+ const appOnly = Boolean(opts.appOnly);
1756
+ if (appOnly && opts.expectVersion && String(opts.expectVersion) !== CLI_VERSION) {
1757
+ throw new Error(
1758
+ `Expected the updated CLI ${opts.expectVersion}, but this is ${CLI_VERSION}. The CLI update did not land where this command runs from; nothing in the app was changed.`
1759
+ );
1760
+ }
1761
+ const latest = appOnly ? CLI_VERSION : await fetchLatest(REGISTRY_URL, 10_000);
1762
+ const install = detectInstall({
1763
+ scriptPath: fs.realpathSync(CLI_ENTRY),
1764
+ isSourceCheckout: isRepoCheckout(PACKAGE_ROOT) && process.env.PASSCONTROL_FORCE_INSTALLED !== "1",
1765
+ version: latest ?? CLI_VERSION,
1766
+ });
1767
+ const app = analyzeAppForUpdate();
1768
+ const plan = planUpdate({ current: CLI_VERSION, latest, install, app });
1769
+ if (opts.json) {
1770
+ console.log(JSON.stringify(plan, null, 2));
1771
+ return;
1772
+ }
1773
+ for (const line of formatPlan(plan)) console.log(line);
1774
+ if (opts.check) return;
1775
+ if (plan.nothingToDo) {
1776
+ ok("Nothing to update.");
1777
+ return;
1778
+ }
1779
+ if (!opts.yes) {
1780
+ if (!(process.stdin.isTTY && process.stdout.isTTY)) {
1781
+ throw new Error("Refusing to update without a terminal to confirm. Rerun with --yes, or --check to only see the plan.");
1782
+ }
1783
+ if (!await confirmYes("\nProceed? [Y/n] ")) {
1784
+ step("Nothing was changed.");
1785
+ return;
1786
+ }
1787
+ }
1788
+ const appWork = plan.app.status === "behind" || Boolean(plan.app.resume);
1789
+ if (plan.cli.needed && plan.cli.command) {
1790
+ step(`Updating the CLI: ${plan.cli.command.join(" ")}`);
1791
+ try {
1792
+ await runCommand(plan.cli.command[0], plan.cli.command.slice(1), { cwd: os.homedir() });
1793
+ } catch (error) {
1794
+ throw new Error(
1795
+ `The CLI update failed (${error.message}). If npm reported EACCES, run it yourself with the permissions your install needs:\n ${plan.cli.manual}\nNothing else was changed.`
1796
+ );
1797
+ }
1798
+ ok(`CLI updated to ${plan.cli.to}.`);
1799
+ if (!appWork) return;
1800
+ // Hand the app phase to the NEW CLI and do nothing else here: any lazy import
1801
+ // after npm replaced these files would load the new code into the old process.
1802
+ const child = spawn(process.execPath, [CLI_ENTRY, "update", "--app-only", "--yes", "--expect-version", String(plan.cli.to)], { stdio: "inherit" });
1803
+ process.exitCode = await new Promise((resolve) => child.once("exit", (code) => resolve(code ?? 1)));
1804
+ return;
1805
+ }
1806
+ if (plan.cli.needed) step(`Update the CLI yourself: ${plan.cli.manual}`);
1807
+ if (appWork) await applyAppUpdate(plan.app);
1808
+ }
1809
+
1507
1810
  async function setupLocal(opts = {}) {
1508
1811
  const dashboard = canonicalLocalDashboard();
1509
1812
  const activation = await prepareLocalActivation(dashboard, opts);
@@ -1517,6 +1820,7 @@ async function setupLocal(opts = {}) {
1517
1820
  await runLocalCommand(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:stack"], {
1518
1821
  ...process.env,
1519
1822
  PASSCONTROL_PORT_OFFSET: String(offset),
1823
+ PASSCONTROL_VIA_CLI: "1",
1520
1824
  });
1521
1825
  // dev:stack has just brought Supabase and Redis up (and would have exited
1522
1826
  // non-zero if it hadn't), so skip start's own service pass rather than print
@@ -2742,7 +3046,13 @@ async function passportCommand(rest, opts = {}) {
2742
3046
  const gateway = bareGatewayOrigin(opts.gateway, "--gateway");
2743
3047
  const passportId = opts.id.trim();
2744
3048
  if (!isEncodedEd25519Key(passportId)) {
2745
- throw new Error("--id must be a 32-byte Ed25519 public key encoded as unpadded base64url.");
3049
+ // Same hint as --gateway above, because it is the same operator on the same
3050
+ // line: cmd.exe hands both flags their quotes. The id at least refuses a
3051
+ // quoted value rather than storing one — base64url has no quote character —
3052
+ // so this only ever needed the explanation, never a repair.
3053
+ throw new Error(
3054
+ `--id must be a 32-byte Ed25519 public key encoded as unpadded base64url.${shellQuotingHint(passportId)}`
3055
+ );
2746
3056
  }
2747
3057
 
2748
3058
  const project = config.sources.find((source) =>
@@ -3463,6 +3773,9 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
3463
3773
  case "reset":
3464
3774
  await resetLocalStack(opts);
3465
3775
  break;
3776
+ case "update":
3777
+ await updateCommand(opts);
3778
+ break;
3466
3779
  case "setup":
3467
3780
  await setupLocal(opts);
3468
3781
  break;