@instafy/cli 0.2.4 → 0.3.0

package/dist/bind/src/config.mjs

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { credentialFreeEnv } from "./detached-env.mjs";
 
 export const DEFAULT_CONTROLLER_URL = "http://127.0.0.1:8788";
 
@@ -145,7 +146,6 @@ export function agentUsesOwnerConversation(config) {
 
 /** Credential names the binder itself reads as the owner's login (above). */
 const BINDER_LOGIN_ENV = ["INSTAFY_ACCESS_TOKEN", "SUPABASE_ACCESS_TOKEN"];
-const CREDENTIAL_ENV_RE = /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|(^|_)KEY$|_KEY_|API_?KEY)/;
 
 /**
  * Why --agent-executor is refused here, or null. It treats a click from this machine's loopback as the owner's own,
@@ -158,23 +158,12 @@ export function agentExecutorRefusal(env = process.env) {
 }
 
 /**
- * The environment of a binder started with `serve --detach`. It outlives the Octo turn that started it and every
- * process in a runtime can read its /proc/<pid>/environ, so it keeps no credential it does not need: no runtime job
- * token or other CONTROLLER_* secret, no SUPABASE_* service values, no credential-like names (space secrets) except
- * names passed with --allow-env, and the owner's login only with `keepLogin` (--agent-executor, the one mode that
+ * The environment of a binder started with `serve --detach`: `credentialFreeEnv` (no runtime job token or other
+ * CONTROLLER_* secret, no SUPABASE_* service values, no credential-like names such as space secrets), except names
+ * passed with --allow-env, and the owner's login only with `keepLogin` (--agent-executor, the one mode that
  * dispatches Octo turns itself). Everything else (PATH, HOME, the space and conversation ids, plain settings a
  * handler may declare in `env`) is kept.
  */
 export function detachedBinderEnv(env = process.env, allowEnv = [], { keepLogin = false } = {}) {
-  const out = {};
-  for (const [name, value] of Object.entries(env)) {
-    if (value === undefined) continue;
-    const keep =
-      (keepLogin && BINDER_LOGIN_ENV.includes(name)) ||
-      allowEnv.includes(name) ||
-      name === "CONTROLLER_BASE_URL" ||
-      (!/^(CONTROLLER|SUPABASE)_/.test(name) && !CREDENTIAL_ENV_RE.test(name));
-    if (keep) out[name] = value;
-  }
-  return out;
+  return credentialFreeEnv(env, [...allowEnv, ...(keepLogin ? BINDER_LOGIN_ENV : [])]);
 }

package/dist/bind/src/detached-env.mjs

@@ -0,0 +1,27 @@
+// The environment of a process started to outlive the command (or Octo turn) that started it.
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// Shared by `instafy bind serve --detach` and `instafy preview open --start` (the CLI loads this file from its bundled
+// copy of the binder), so both strip the same credentials.
+
+const CREDENTIAL_ENV_RE = /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|(^|_)KEY$|_KEY_|API_?KEY)/;
+
+/**
+ * `env` without credentials a long-lived process does not need. Such a process outlives the job that started it, and
+ * every process in a runtime can read its /proc/<pid>/environ, so it keeps no runtime job token or other CONTROLLER_*
+ * value (except CONTROLLER_BASE_URL, which is not secret), no SUPABASE_* value and no credential-like name (space
+ * secrets, logins). Names in `keep` are kept anyway. Everything else (PATH, HOME, the space and conversation ids,
+ * plain settings) is kept.
+ */
+export function credentialFreeEnv(env = process.env, keep = []) {
+  const out = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) continue;
+    const kept =
+      keep.includes(name) ||
+      name === "CONTROLLER_BASE_URL" ||
+      (!/^(CONTROLLER|SUPABASE)_/.test(name) && !CREDENTIAL_ENV_RE.test(name));
+    if (kept) out[name] = value;
+  }
+  return out;
+}

package/dist/cli.js

@@ -1717,7 +1717,7 @@ var init_hardware = __esm({
 
 // src/index.ts
 import { Command, Option } from "commander";
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { pathToFileURL as pathToFileURL3 } from "node:url";
 import { createRequire as createRequire4 } from "node:module";
 import kleur20 from "kleur";
 
@@ -5770,10 +5770,75 @@ async function tailTunnelLogs(options) {
 }
 
 // src/preview.ts
-import fs8 from "node:fs";
+import { spawn as spawn5 } from "node:child_process";
+import fs9 from "node:fs";
 import os5 from "node:os";
-import path9 from "node:path";
+import path10 from "node:path";
 import kleur8 from "kleur";
+
+// src/bind.ts
+import { spawn as spawn4 } from "node:child_process";
+import fs8 from "node:fs";
+import path9 from "node:path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+var BIN_REL = path9.join("bin", "instafy-bind.mjs");
+function resolveBindBin(env = process.env) {
+  const fromEnv = env.INSTAFY_BIND_BIN?.trim();
+  if (fromEnv) return fs8.existsSync(fromEnv) ? path9.resolve(fromEnv) : null;
+  const here = path9.dirname(fileURLToPath2(import.meta.url));
+  for (const candidate of [path9.join(here, "bind", BIN_REL), path9.resolve(here, "..", "..", "instafy-bind", BIN_REL)]) {
+    if (fs8.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+function bundledBindRoot() {
+  const here = path9.dirname(fileURLToPath2(import.meta.url));
+  for (const candidate of [path9.join(here, "bind"), path9.resolve(here, "..", "..", "instafy-bind")]) {
+    if (fs8.existsSync(path9.join(candidate, BIN_REL))) return candidate;
+  }
+  return null;
+}
+async function loadCredentialFreeEnv() {
+  const root = bundledBindRoot();
+  const file = root ? path9.join(root, "src", "detached-env.mjs") : null;
+  if (!file || !fs8.existsSync(file)) {
+    throw new Error("the bundled binder (dist/bind) was not found, so a site cannot be started without credentials; rebuild the CLI");
+  }
+  const module = await import(pathToFileURL(file).href);
+  if (typeof module.credentialFreeEnv !== "function") {
+    throw new Error(`${file} does not export credentialFreeEnv; rebuild the CLI`);
+  }
+  return module.credentialFreeEnv;
+}
+function runBind(args) {
+  const bin = resolveBindBin();
+  if (!bin) {
+    process.stderr.write(
+      "instafy bind: the bundled binder (dist/bind) was not found; rebuild the CLI, or set INSTAFY_BIND_BIN to packages/instafy-bind/bin/instafy-bind.mjs, or run it directly: node packages/instafy-bind/bin/instafy-bind.mjs <command>\n"
+    );
+    return Promise.resolve(1);
+  }
+  return new Promise((resolve) => {
+    const child = spawn4(process.execPath, [bin, ...args], { stdio: "inherit", env: process.env });
+    const forward = (signal) => {
+      if (!child.killed) child.kill(signal);
+    };
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    child.on("error", (error) => {
+      process.stderr.write(`instafy bind: ${error.message}
+`);
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      resolve(code ?? (signal ? 130 : 1));
+    });
+  });
+}
+
+// src/preview.ts
 init_controller_fetch();
 init_errors();
 
@@ -5907,19 +5972,19 @@ var MAX_PATH_LENGTH = 512;
 var STATE_LOCK_WAIT_MS = 12e4;
 var STATE_LOCK_STALE_MS = 10 * 6e4;
 function instafyDir() {
-  return path9.join(os5.homedir(), ".instafy");
+  return path10.join(os5.homedir(), ".instafy");
 }
 function previewStateFile() {
-  return path9.join(instafyDir(), "cli-preview-state.json");
+  return path10.join(instafyDir(), "cli-preview-state.json");
 }
 function previewStateLockFile() {
-  return path9.join(instafyDir(), "cli-preview-state.lock");
+  return path10.join(instafyDir(), "cli-preview-state.lock");
 }
 function workdirsRoot() {
-  return path9.join(instafyDir(), "cli-preview-workdirs");
+  return path10.join(instafyDir(), "cli-preview-workdirs");
 }
 function workdirFor(previewId) {
-  return path9.join(workdirsRoot(), safePathSegment2(previewId));
+  return path10.join(workdirsRoot(), safePathSegment2(previewId));
 }
 var HOST_SUFFIX_RE = /^[a-z0-9-]+(?:\.[a-z0-9-]+)*(?::\d{1,5})?$/;
 function parseViewerHostSuffix(raw) {
@@ -5972,7 +6037,7 @@ function parsePreviewPath(raw) {
 }
 function readStateFile2() {
   try {
-    const parsed = JSON.parse(fs8.readFileSync(previewStateFile(), "utf8"));
+    const parsed = JSON.parse(fs9.readFileSync(previewStateFile(), "utf8"));
     if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.previews)) {
       return { version: 1, previews: [] };
     }
@@ -5982,8 +6047,8 @@ function readStateFile2() {
   }
 }
 function writeStateFile2(state) {
-  fs8.mkdirSync(instafyDir(), { recursive: true });
-  fs8.writeFileSync(previewStateFile(), JSON.stringify(state, null, 2), { encoding: "utf8", mode: 384 });
+  fs9.mkdirSync(instafyDir(), { recursive: true });
+  fs9.writeFileSync(previewStateFile(), JSON.stringify(state, null, 2), { encoding: "utf8", mode: 384 });
 }
 function upsertPreviewState(entry) {
   const state = readStateFile2();
@@ -5998,7 +6063,7 @@ function removePreviewState(previewId) {
   return existing;
 }
 function removeWorkdir(previewId) {
-  fs8.rmSync(workdirFor(previewId), { recursive: true, force: true });
+  fs9.rmSync(workdirFor(previewId), { recursive: true, force: true });
 }
 function forgetPreview(previewId) {
   const entry = removePreviewState(previewId);
@@ -6010,9 +6075,9 @@ function sleep(ms) {
 }
 function lockHolderIsGone(lockFile) {
   try {
-    const stat = fs8.statSync(lockFile);
+    const stat = fs9.statSync(lockFile);
     if (Date.now() - stat.mtimeMs > STATE_LOCK_STALE_MS) return true;
-    const pid = Number.parseInt(fs8.readFileSync(lockFile, "utf8").trim(), 10);
+    const pid = Number.parseInt(fs9.readFileSync(lockFile, "utf8").trim(), 10);
     if (!Number.isInteger(pid) || pid <= 0) return Date.now() - stat.mtimeMs > 5e3;
     try {
       process.kill(pid, 0);
@@ -6026,18 +6091,18 @@ function lockHolderIsGone(lockFile) {
 }
 async function withStateLock(fn) {
   const lockFile = previewStateLockFile();
-  fs8.mkdirSync(instafyDir(), { recursive: true });
+  fs9.mkdirSync(instafyDir(), { recursive: true });
   const deadline = Date.now() + STATE_LOCK_WAIT_MS;
   for (; ; ) {
     try {
-      const fd = fs8.openSync(lockFile, "wx", 384);
-      fs8.writeSync(fd, String(process.pid));
-      fs8.closeSync(fd);
+      const fd = fs9.openSync(lockFile, "wx", 384);
+      fs9.writeSync(fd, String(process.pid));
+      fs9.closeSync(fd);
       break;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       if (lockHolderIsGone(lockFile)) {
-        fs8.rmSync(lockFile, { force: true });
+        fs9.rmSync(lockFile, { force: true });
         continue;
       }
       if (Date.now() > deadline) {
@@ -6049,11 +6114,11 @@ async function withStateLock(fn) {
   try {
     return await fn();
   } finally {
-    fs8.rmSync(lockFile, { force: true });
+    fs9.rmSync(lockFile, { force: true });
   }
 }
 function configPathFor(workdir) {
-  return path9.join(workdir, "rathole.toml");
+  return path10.join(workdir, "rathole.toml");
 }
 async function stopClient(entry) {
   await stopRatholeClient(entry.pid, configPathFor(entry.workdir), entry.binary);
@@ -6185,7 +6250,7 @@ async function resolveRathole(ratholeBin, log) {
 }
 function readFileOrNull(file) {
   try {
-    return fs8.readFileSync(file, "utf8");
+    return fs9.readFileSync(file, "utf8");
   } catch {
     return null;
   }
@@ -6293,8 +6358,8 @@ function parseServeCommand(raw) {
 }
 function realDir(dir) {
   try {
-    const resolved = fs8.realpathSync(dir);
-    return fs8.statSync(resolved).isDirectory() ? resolved : null;
+    const resolved = fs9.realpathSync(dir);
+    return fs9.statSync(resolved).isDirectory() ? resolved : null;
   } catch {
     return null;
   }
@@ -6304,22 +6369,22 @@ function resolveWorkspaceRoot(env, projectId2) {
   if (explicit) return realDir(explicit);
   const base = env["WORKSPACE_DIR"]?.trim();
   if (!base || !projectId2) return null;
-  return realDir(path9.join(base, projectId2));
+  return realDir(path10.join(base, projectId2));
 }
 function workspaceRelativeDir(root, dir) {
   const resolved = realDir(dir);
   if (!resolved) return null;
-  const relative = path9.relative(root, resolved);
+  const relative = path10.relative(root, resolved);
   if (relative === "") return ".";
-  if (relative.startsWith("..") || path9.isAbsolute(relative)) return null;
-  return relative.split(path9.sep).join("/");
+  if (relative.startsWith("..") || path10.isAbsolute(relative)) return null;
+  return relative.split(path10.sep).join("/");
 }
 function listeningSocketInodes(procRoot, port) {
   const inodes = /* @__PURE__ */ new Set();
   for (const table of ["net/tcp", "net/tcp6"]) {
     let text2 = "";
     try {
-      text2 = fs8.readFileSync(path9.join(procRoot, table), "utf8");
+      text2 = fs9.readFileSync(path10.join(procRoot, table), "utf8");
     } catch {
       continue;
     }
@@ -6340,20 +6405,20 @@ function detectListeningProcess(port, procRoot = "/proc") {
   if (inodes.size === 0) return null;
   let pids = [];
   try {
-    pids = fs8.readdirSync(procRoot).filter((name) => /^\d+$/.test(name)).map(Number).sort((a, b) => a - b);
+    pids = fs9.readdirSync(procRoot).filter((name) => /^\d+$/.test(name)).map(Number).sort((a, b) => a - b);
   } catch {
     return null;
   }
   for (const pid of pids) {
     let fds = [];
     try {
-      fds = fs8.readdirSync(path9.join(procRoot, String(pid), "fd"));
+      fds = fs9.readdirSync(path10.join(procRoot, String(pid), "fd"));
     } catch {
       continue;
     }
     const holds = fds.some((fd) => {
       try {
-        const target = fs8.readlinkSync(path9.join(procRoot, String(pid), "fd", fd));
+        const target = fs9.readlinkSync(path10.join(procRoot, String(pid), "fd", fd));
         const match = /^socket:\[(\d+)\]$/.exec(target);
         return Boolean(match && inodes.has(match[1]));
       } catch {
@@ -6362,9 +6427,9 @@ function detectListeningProcess(port, procRoot = "/proc") {
     });
     if (!holds) continue;
     try {
-      const argv = fs8.readFileSync(path9.join(procRoot, String(pid), "cmdline"), "utf8").split("\0");
+      const argv = fs9.readFileSync(path10.join(procRoot, String(pid), "cmdline"), "utf8").split("\0");
       while (argv.length > 0 && argv[argv.length - 1] === "") argv.pop();
-      const cwd = fs8.readlinkSync(path9.join(procRoot, String(pid), "cwd"));
+      const cwd = fs9.readlinkSync(path10.join(procRoot, String(pid), "cwd"));
       if (argv.length === 0) continue;
       return { pid, argv, cwd };
     } catch {
@@ -6445,6 +6510,66 @@ function resolvePreviewServe(params) {
   }
   return { serve: { argv: found.argv, cwd } };
 }
+var START_PORT_WAIT_MS = 6e4;
+var START_POLL_MS = 300;
+var START_PROBE_TIMEOUT_MS = 2e3;
+var START_LOGS_DIR = path10.join(".instafy", "agent", "logs");
+function displayPath(file, cwd = process.cwd()) {
+  const relative = path10.relative(cwd, file);
+  return relative && !relative.startsWith("..") && !path10.isAbsolute(relative) ? relative : file;
+}
+async function startPreviewSite(params) {
+  const { port, sitePath, serve, root } = params;
+  const credentialFreeEnv = await loadCredentialFreeEnv();
+  const env = credentialFreeEnv(params.env ?? process.env);
+  const cwd = path10.join(root, serve.cwd);
+  const logFile = path10.join(root, START_LOGS_DIR, `preview-${port}.log`);
+  fs9.mkdirSync(path10.dirname(logFile), { recursive: true });
+  const fd = fs9.openSync(logFile, "a", 384);
+  let exit = null;
+  let spawnError = null;
+  let pid;
+  try {
+    fs9.writeSync(fd, `
+[instafy preview open --start] ${(/* @__PURE__ */ new Date()).toISOString()} ${JSON.stringify(serve.argv)} in ${serve.cwd}
+`);
+    const child = spawn5(serve.argv[0], serve.argv.slice(1), {
+      cwd,
+      env,
+      detached: true,
+      stdio: ["ignore", fd, fd]
+    });
+    child.on("error", (error) => {
+      spawnError = error.code ?? error.message;
+    });
+    child.on("exit", (code, signal) => {
+      exit = signal ? `signal ${signal}` : `exit status ${code}`;
+    });
+    child.unref();
+    pid = child.pid;
+  } finally {
+    fs9.closeSync(fd);
+  }
+  await new Promise((resolve) => setImmediate(resolve));
+  const shownLog = displayPath(logFile);
+  const fail = (why) => new PreviewCommandError(`The site ${why} and did not answer on 127.0.0.1:${port}; log: ${shownLog}`, PREVIEW_EXIT_NOT_LISTENING);
+  const deadline = Date.now() + (params.timeoutMs ?? START_PORT_WAIT_MS);
+  for (; ; ) {
+    if (spawnError || pid === void 0) throw fail(`could not be started (${spawnError ?? "no process"})`);
+    if (exit) throw fail(`started with --serve-cmd exited (${exit})`);
+    const probe = await probeLocalSite(port, sitePath, START_PROBE_TIMEOUT_MS, RATHOLE_LOCAL_HOSTS);
+    if (probe.listening) return { pid, logFile };
+    if (exit) throw fail(`started with --serve-cmd exited (${exit})`);
+    if (Date.now() >= deadline) {
+      try {
+        process.kill(-pid, "SIGTERM");
+      } catch {
+      }
+      throw fail(`started with --serve-cmd was stopped after ${Math.round((params.timeoutMs ?? START_PORT_WAIT_MS) / 1e3)} s`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, START_POLL_MS));
+  }
+}
 async function createAndStartClient(params) {
   const { opts, port, title, sitePath, projectId: projectId2, retryCommand, auth, controllerUrl, serverUrl, log, serve } = params;
   const conversationId = opts.conversationId?.trim() || void 0;
@@ -6472,7 +6597,7 @@ async function createAndStartClient(params) {
     throw new Error("Preview response is missing previewId.");
   }
   const workdir = workdirFor(previewId);
-  const logFile = path9.join(instafyDir(), "cli-preview-logs", `preview-${safePathSegment2(previewId)}.log`);
+  const logFile = path10.join(instafyDir(), "cli-preview-logs", `preview-${safePathSegment2(previewId)}.log`);
   const configPath2 = configPathFor(workdir);
   const hostSuffix = parseViewerHostSuffix(grant["viewerHostSuffix"]);
   const studioOrigin = parseStudioOrigin(grant["studioOrigin"]);
@@ -6483,8 +6608,8 @@ async function createAndStartClient(params) {
   try {
     const credentials = grant["credentials"] && typeof grant["credentials"] === "object" ? grant["credentials"] : {};
     const configBody = buildRatholeConfig(credentials, port);
-    fs8.mkdirSync(workdir, { recursive: true });
-    fs8.mkdirSync(path9.dirname(logFile), { recursive: true });
+    fs9.mkdirSync(workdir, { recursive: true });
+    fs9.mkdirSync(path10.dirname(logFile), { recursive: true });
     if (current && readFileOrNull(configPath2) === configBody && isRatholeClientFor(current.pid, configPath2, current.binary)) {
       pid = current.pid;
     }
@@ -6503,7 +6628,7 @@ async function createAndStartClient(params) {
     }
     if (pid === null) {
       const rathole = await resolveRathole(opts.ratholeBin, log);
-      fs8.writeFileSync(configPath2, configBody, { encoding: "utf8", mode: 384 });
+      fs9.writeFileSync(configPath2, configBody, { encoding: "utf8", mode: 384 });
       binary = rathole;
       const started = await spawnRatholeDetached({ rathole, configPath: configPath2, workdir, logFile });
       if (started.exit !== null) {
@@ -6556,7 +6681,24 @@ async function previewOpen(opts) {
   const { auth, controllerUrl } = resolveAuth(opts, retryCommand);
   const serverUrl = cleanUrl(controllerUrl);
   const log = (message) => console.error(kleur8.cyan(message));
-  const probe = await probeLocalSite(port, sitePath, void 0, RATHOLE_LOCAL_HOSTS);
+  const explicitServe = opts.start && opts.serveCmd?.trim() ? resolvePreviewServe({ port, serveCmd: opts.serveCmd, projectId: projectId2, cwd: opts.cwd }).serve : null;
+  let probe = await probeLocalSite(port, sitePath, void 0, RATHOLE_LOCAL_HOSTS);
+  let started = null;
+  if (!probe.listening && opts.start && probe.status === null && !probe.timedOut) {
+    const ipv6 = await probeLocalSite(port, sitePath, void 0, ["::1"]);
+    if (ipv6.status === null && !ipv6.timedOut) {
+      if (!explicitServe) {
+        throw new PreviewCommandError(
+          `Nothing answers on 127.0.0.1:${port}, and --start needs --serve-cmd "<command>" to start the site.`,
+          PREVIEW_EXIT_NOT_LISTENING
+        );
+      }
+      const root = resolveWorkspaceRoot(process.env, projectId2);
+      started = await startPreviewSite({ port, sitePath, serve: explicitServe, root, timeoutMs: opts.startTimeoutMs });
+      log(`Started the site (pid ${started.pid}); log: ${displayPath(started.logFile)}`);
+      probe = await probeLocalSite(port, sitePath, void 0, RATHOLE_LOCAL_HOSTS);
+    }
+  }
   if (!probe.listening) {
     throw await notListeningError(port, sitePath, probe);
   }
@@ -6595,7 +6737,8 @@ async function previewOpen(opts) {
     messageId: stringField(readyBody, "messageId"),
     viewerHostSuffix: parseViewerHostSuffix(grant["viewerHostSuffix"]) ?? null,
     restartable,
-    ...restartable ? {} : { restartNote: restartNote ?? "the server did not record a start command" }
+    ...restartable ? {} : { restartNote: restartNote ?? "the server did not record a start command" },
+    ...opts.start ? { startedPid: started?.pid ?? null, logFile: started?.logFile ?? null } : {}
   };
 }
 function toPreviewSummary(raw) {
@@ -6608,7 +6751,8 @@ function toPreviewSummary(raw) {
     title: stringField(record2, "title") ?? "",
     port: numberField(record2, "port", "localPort") ?? 0,
     path: stringField(record2, "path") ?? "/",
-    status: stringField(record2, "status") ?? "unknown"
+    status: stringField(record2, "status") ?? "unknown",
+    ...typeof record2["restartable"] === "boolean" ? { restartable: record2["restartable"] } : {}
   };
 }
 async function previewList(opts) {
@@ -6656,10 +6800,19 @@ function printPreviewOpen(result, json) {
   }
   const label = result.status === "live" ? kleur8.green("Ready to preview") : result.status === "not_responding" ? kleur8.yellow("Not responding yet") : kleur8.yellow("Preview opened (the server did not report whether the site answers)");
   console.log(`${label}: ${result.title} (port ${result.port}). Open it from the card in the conversation.`);
+  if (result.startedPid) {
+    console.log(kleur8.gray(`Started the site in the background (pid ${result.startedPid}); log: ${displayPath(result.logFile ?? "")}`));
+  } else if (result.startedPid === null) {
+    console.log(kleur8.gray("The site was already running; nothing was started."));
+  }
   if (result.restartable) {
-    console.log(kleur8.gray("Open starts the site again after the space sleeps."));
+    console.log(kleur8.gray("Open starts the site again when the process that started it exits, or the space sleeps."));
   } else {
-    console.log(kleur8.yellow(`After the space sleeps, Open cannot start the site by itself: ${result.restartNote}.`));
+    console.log(
+      kleur8.yellow(
+        `When the process that started it exits, or the space sleeps, Open cannot start the site by itself: ${result.restartNote}.`
+      )
+    );
   }
   console.log(kleur8.gray(`previewId=${result.previewId}`));
   if (result.httpStatus !== null && result.httpStatus >= 400) {
@@ -6678,15 +6831,23 @@ function printPreviewList(previews, json) {
     console.log(JSON.stringify(previews, null, 2));
     return;
   }
+  const stoppedNote = "A preview whose machine stopped or restarted is not listed; its card reads Stopped, and Open on a restartable card starts the site again.";
   if (previews.length === 0) {
-    console.log(kleur8.yellow("No previews found."));
+    console.log(kleur8.yellow("No open previews."));
+    console.log(kleur8.gray(stoppedNote));
     return;
   }
   for (const preview of previews) {
+    const restart = preview.restartable === void 0 ? "" : preview.restartable ? " \xB7 restartable" : " \xB7 not restartable";
     console.log(
-      `${preview.previewId} \xB7 ${preview.title || "(untitled)"} \xB7 port=${preview.port}${preview.path === "/" ? "" : ` \xB7 path=${preview.path}`} \xB7 ${preview.status}`
+      `${preview.previewId} \xB7 ${preview.title || "(untitled)"} \xB7 port=${preview.port}${preview.path === "/" ? "" : ` \xB7 path=${preview.path}`} \xB7 preview ${preview.status}${restart}`
     );
   }
+  console.log(
+    kleur8.gray(
+      `This lists open previews; it does not check whether a site answers (${kleur8.cyan("instafy preview check --port <port>")} does). ${stoppedNote}`
+    )
+  );
 }
 
 // src/config-command.ts
@@ -6810,27 +6971,27 @@ init_config();
 // src/git-wrapper.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
 import { randomUUID as randomUUID2 } from "node:crypto";
-import fs9 from "node:fs";
-import path10 from "node:path";
+import fs10 from "node:fs";
+import path11 from "node:path";
 import kleur10 from "kleur";
 function pathExists(candidate) {
   try {
-    fs9.statSync(candidate);
+    fs10.statSync(candidate);
     return true;
   } catch {
     return false;
   }
 }
 function findInstafyGitContext(startDir) {
-  let current = path10.resolve(startDir);
-  const root = path10.parse(current).root;
+  let current = path11.resolve(startDir);
+  const root = path11.parse(current).root;
   while (true) {
-    const gitDir = path10.join(current, ".instafy", ".git");
+    const gitDir = path11.join(current, ".instafy", ".git");
     if (pathExists(gitDir)) {
       return { workTree: current, gitDir };
     }
     if (current === root) break;
-    current = path10.dirname(current);
+    current = path11.dirname(current);
   }
   return null;
 }
@@ -6986,7 +7147,7 @@ function collectDirtyPaths(context, options) {
   return unique;
 }
 function findEmbeddedGitDirs(context, pathSpecs) {
-  const instafyGitDir = path10.resolve(context.gitDir);
+  const instafyGitDir = path11.resolve(context.gitDir);
   const seen = /* @__PURE__ */ new Set();
   for (const rawPath of pathSpecs) {
     const normalized = normalizePathSpec(rawPath).replace(/\/+$/, "");
@@ -6995,11 +7156,11 @@ function findEmbeddedGitDirs(context, pathSpecs) {
     }
     let cursor = normalized;
     while (cursor && cursor !== ".") {
-      const candidate = path10.join(context.workTree, ...cursor.split("/"), ".git");
-      if (pathExists(candidate) && path10.resolve(candidate) !== instafyGitDir) {
-        seen.add(path10.resolve(candidate));
+      const candidate = path11.join(context.workTree, ...cursor.split("/"), ".git");
+      if (pathExists(candidate) && path11.resolve(candidate) !== instafyGitDir) {
+        seen.add(path11.resolve(candidate));
       }
-      const next = path10.posix.dirname(cursor);
+      const next = path11.posix.dirname(cursor);
       if (next === "." || next === cursor) {
         break;
       }
@@ -7008,8 +7169,8 @@ function findEmbeddedGitDirs(context, pathSpecs) {
   }
   const candidates = Array.from(seen);
   candidates.sort((a, b) => {
-    const depthA = a.split(path10.sep).length;
-    const depthB = b.split(path10.sep).length;
+    const depthA = a.split(path11.sep).length;
+    const depthB = b.split(path11.sep).length;
     return depthB - depthA;
   });
   return candidates;
@@ -7019,16 +7180,16 @@ function hideEmbeddedGitDirs(context, pathSpecs) {
   if (candidates.length === 0) {
     return [];
   }
-  const stagingBase = path10.join(context.workTree, ".instafy", "origin-staging", "embedded-git");
-  fs9.mkdirSync(stagingBase, { recursive: true });
+  const stagingBase = path11.join(context.workTree, ".instafy", "origin-staging", "embedded-git");
+  fs10.mkdirSync(stagingBase, { recursive: true });
   const renames = [];
   for (const candidate of candidates) {
-    let hidden = path10.join(stagingBase, randomUUID2());
+    let hidden = path11.join(stagingBase, randomUUID2());
     for (let attempt = 0; attempt < 8; attempt += 1) {
       if (!pathExists(hidden)) break;
-      hidden = path10.join(stagingBase, randomUUID2());
+      hidden = path11.join(stagingBase, randomUUID2());
     }
-    fs9.renameSync(candidate, hidden);
+    fs10.renameSync(candidate, hidden);
     renames.push({ original: candidate, hidden });
   }
   return renames;
@@ -7038,7 +7199,7 @@ function restoreEmbeddedGitDirs(renames) {
     const rename = renames[index];
     if (!rename) continue;
     try {
-      fs9.renameSync(rename.hidden, rename.original);
+      fs10.renameSync(rename.hidden, rename.original);
     } catch {
     }
   }
@@ -7597,49 +7758,6 @@ function saveReportJson(report, notSaved) {
   };
 }
 
-// src/bind.ts
-import { spawn as spawn4 } from "node:child_process";
-import fs10 from "node:fs";
-import path11 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-var BIN_REL = path11.join("bin", "instafy-bind.mjs");
-function resolveBindBin(env = process.env) {
-  const fromEnv = env.INSTAFY_BIND_BIN?.trim();
-  if (fromEnv) return fs10.existsSync(fromEnv) ? path11.resolve(fromEnv) : null;
-  const here = path11.dirname(fileURLToPath2(import.meta.url));
-  for (const candidate of [path11.join(here, "bind", BIN_REL), path11.resolve(here, "..", "..", "instafy-bind", BIN_REL)]) {
-    if (fs10.existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-function runBind(args) {
-  const bin = resolveBindBin();
-  if (!bin) {
-    process.stderr.write(
-      "instafy bind: the bundled binder (dist/bind) was not found; rebuild the CLI, or set INSTAFY_BIND_BIN to packages/instafy-bind/bin/instafy-bind.mjs, or run it directly: node packages/instafy-bind/bin/instafy-bind.mjs <command>\n"
-    );
-    return Promise.resolve(1);
-  }
-  return new Promise((resolve) => {
-    const child = spawn4(process.execPath, [bin, ...args], { stdio: "inherit", env: process.env });
-    const forward = (signal) => {
-      if (!child.killed) child.kill(signal);
-    };
-    process.on("SIGINT", forward);
-    process.on("SIGTERM", forward);
-    child.on("error", (error) => {
-      process.stderr.write(`instafy bind: ${error.message}
-`);
-      resolve(1);
-    });
-    child.on("exit", (code, signal) => {
-      process.off("SIGINT", forward);
-      process.off("SIGTERM", forward);
-      resolve(code ?? (signal ? 130 : 1));
-    });
-  });
-}
-
 // src/site-check.ts
 import { spawnSync as spawnSync5 } from "node:child_process";
 import { once } from "node:events";
@@ -10990,7 +11108,7 @@ async function teamRevokeLink(options) {
 init_project_manifest();
 import fs15 from "node:fs";
 import path16 from "node:path";
-import { pathToFileURL } from "node:url";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
 import kleur16 from "kleur";
 function resolveBindingContext(startDir) {
   const lookup = findProjectManifest(path16.resolve(startDir));
@@ -11110,7 +11228,7 @@ function grantProviderBinding(options) {
   const record2 = {
     providerId,
     projectId: context.projectId,
-    rootUri: pathToFileURL(context.projectRoot).toString(),
+    rootUri: pathToFileURL2(context.projectRoot).toString(),
     grantedCapabilities: capabilities,
     grantedPrefix: options.prefix?.trim() || `.instafy/providers/${providerId}/`,
     purpose: options.purpose?.trim() || null,
@@ -13489,7 +13607,10 @@ addServerUrlOptions(previewOpenCommand);
 addAccessTokenOptions(previewOpenCommand, "Instafy access token (defaults to the job token, then the saved `instafy login` token)");
 previewOpenCommand.option("--conversation <id>", "Conversation for the card (only needed without a job token)").option("--rathole-bin <path>", "Path to rathole binary (or set RATHOLE_BIN)").option(
   "--serve-cmd <command>",
-  "How to start the site again after the space sleeps, run from the current directory (one command, no shell); default: read from the process listening on the port"
+  "How to start the site again when the process that started it exits, or the space sleeps, run from the current directory (one command, no shell); default: read from the process listening on the port"
+).option(
+  "--start",
+  "Start --serve-cmd in the background, in its own session, without Instafy credentials, logging to .instafy/agent/logs, and wait for the port (nothing is started when the port already answers)"
 ).option("--json", "Output JSON").action(async (opts) => {
   try {
     const result = await previewOpen({
@@ -13501,14 +13622,15 @@ previewOpenCommand.option("--conversation <id>", "Conversation for the card (onl
       title: opts.title,
       path: opts.path,
       ratholeBin: opts.ratholeBin,
-      serveCmd: opts.serveCmd
+      serveCmd: opts.serveCmd,
+      start: Boolean(opts.start)
     });
     printPreviewOpen(result, Boolean(opts.json));
   } catch (error) {
     exitWithPreviewError(error);
   }
 });
-var previewListCommand = previewCommand.command("list").description("List this space's previews");
+var previewListCommand = previewCommand.command("list").description("List this space's open previews (it does not check the sites: `instafy preview check` does)");
 addSpaceOption(previewListCommand, "Space UUID (defaults to .instafy/space.json or SPACE_ID)");
 addServerUrlOptions(previewListCommand);
 addAccessTokenOptions(previewListCommand, "Instafy access token (defaults to the job token, then the saved `instafy login` token)");
@@ -13956,7 +14078,7 @@ async function runCli(argv = process.argv) {
   }
   await program.parseAsync(argv);
 }
-if (import.meta.url === pathToFileURL2(process.argv[1] ?? "").href) {
+if (import.meta.url === pathToFileURL3(process.argv[1] ?? "").href) {
   void runCli(process.argv);
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instafy/cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "description": "Run Instafy spaces locally, link folders to Studio, and share previews/webhooks via tunnels.",
   "private": false,