@treeseed/core 0.6.14 → 0.6.16

package/dist/dev.d.ts

@@ -1,10 +1,14 @@
 import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 export declare const TREESEED_DEFAULT_WEB_HOST = "127.0.0.1";
 export declare const TREESEED_DEFAULT_WEB_PORT = 4321;
 export declare const TREESEED_DEFAULT_API_HOST = "127.0.0.1";
 export declare const TREESEED_DEFAULT_API_PORT = 3000;
 export declare const TREESEED_DEFAULT_MANAGER_PORT = 3100;
 export type TreeseedIntegratedDevSurface = 'integrated' | 'services' | 'web' | 'api' | 'manager' | 'worker';
+export type TreeseedIntegratedDevSetupMode = 'auto' | 'check' | 'off';
+export type TreeseedIntegratedDevFeedbackMode = 'live' | 'restart' | 'off';
+export type TreeseedIntegratedDevOpenMode = 'auto' | 'on' | 'off';
 export type TreeseedIntegratedDevOptions = {
     surface?: TreeseedIntegratedDevSurface;
     watch?: boolean;
@@ -16,9 +20,16 @@ export type TreeseedIntegratedDevOptions = {
     apiHost?: string;
     apiPort?: number;
     managerPort?: number;
+    setupMode?: TreeseedIntegratedDevSetupMode;
+    feedbackMode?: TreeseedIntegratedDevFeedbackMode;
+    openMode?: TreeseedIntegratedDevOpenMode;
+    plan?: boolean;
+    json?: boolean;
     includeServices?: boolean;
     projectId?: string;
     teamId?: string;
+    readinessTimeoutMs?: number;
+    processReadyGraceMs?: number;
 };
 export type TreeseedIntegratedDevCommand = {
     id: 'web' | 'api' | 'manager' | 'worker';
@@ -28,18 +39,63 @@ export type TreeseedIntegratedDevCommand = {
     cwd: string;
     env: NodeJS.ProcessEnv;
 };
+export type TreeseedIntegratedDevWatchEntry = {
+    kind: 'tenant' | 'package' | 'sdk';
+    root: string;
+};
+export type TreeseedIntegratedDevSetupStep = {
+    id: string;
+    label: string;
+    required: boolean;
+    command?: string;
+    args?: string[];
+    status: 'planned' | 'completed' | 'skipped' | 'degraded' | 'failed';
+    detail?: string;
+};
+export type TreeseedIntegratedDevReadinessCheck = {
+    id: TreeseedIntegratedDevCommand['id'];
+    label: string;
+    required: boolean;
+    strategy: 'http' | 'process';
+    url?: string;
+};
 export type TreeseedIntegratedDevPlan = {
     surface: TreeseedIntegratedDevSurface;
+    setupMode: TreeseedIntegratedDevSetupMode;
+    feedbackMode: TreeseedIntegratedDevFeedbackMode;
+    openMode: TreeseedIntegratedDevOpenMode;
+    watch: boolean;
     tenantRoot: string;
     apiBaseUrl: string;
+    webUrl: string | null;
+    setupSteps: TreeseedIntegratedDevSetupStep[];
+    readyChecks: TreeseedIntegratedDevReadinessCheck[];
+    watchEntries: TreeseedIntegratedDevWatchEntry[];
     commands: TreeseedIntegratedDevCommand[];
 };
 type SpawnLike = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+type SpawnSyncLike = typeof spawnSync;
 type SignalRegistrar = (signal: NodeJS.Signals, handler: () => void) => () => void;
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type WatchChange = {
+    changedPaths: string[];
+    tenantChanged: boolean;
+    packageChanged: boolean;
+    sdkChanged: boolean;
+};
+type WatchStarter = (input: {
+    watchEntries: TreeseedIntegratedDevWatchEntry[];
+    onChange: (change: WatchChange) => void | Promise<void>;
+}) => () => void;
 type TreeseedIntegratedDevDependencies = {
     spawn: SpawnLike;
+    spawnSync: SpawnSyncLike;
     onSignal: SignalRegistrar;
     prepareEnvironment: (tenantRoot: string) => void;
+    fetch: FetchLike;
+    write: (line: string, stream: 'stdout' | 'stderr') => void;
+    openBrowser: (url: string) => void | Promise<void>;
+    startWatch: WatchStarter;
 };
 export declare function createTreeseedIntegratedDevPlan(options?: TreeseedIntegratedDevOptions): TreeseedIntegratedDevPlan;
 export declare function runTreeseedIntegratedDev(options?: TreeseedIntegratedDevOptions, deps?: Partial<TreeseedIntegratedDevDependencies>): Promise<number>;

package/dist/dev.js

@@ -1,9 +1,16 @@
-import { existsSync } from "node:fs";
-import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { dirname, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyTreeseedEnvironmentToProcess, assertTreeseedCommandEnvironment } from "@treeseed/sdk/workflow-support";
+import { setTimeout as delay } from "node:timers/promises";
+import {
+  applyTreeseedEnvironmentToProcess,
+  assertTreeseedCommandEnvironment,
+  ensureLocalWorkspaceLinks,
+  findNearestTreeseedWorkspaceRoot,
+  resolveTreeseedToolBinary
+} from "@treeseed/sdk/workflow-support";
 const require2 = createRequire(import.meta.url);
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TREESEED_DEFAULT_WEB_HOST = "127.0.0.1";
@@ -11,6 +18,11 @@ const TREESEED_DEFAULT_WEB_PORT = 4321;
 const TREESEED_DEFAULT_API_HOST = "127.0.0.1";
 const TREESEED_DEFAULT_API_PORT = 3e3;
 const TREESEED_DEFAULT_MANAGER_PORT = 3100;
+const DEV_RELOAD_FILE = "public/__treeseed/dev-reload.json";
+const WATCH_INTERVAL_MS = 900;
+const WATCH_DEBOUNCE_MS = 350;
+const DEFAULT_READINESS_TIMEOUT_MS = 9e4;
+const DEFAULT_PROCESS_READY_GRACE_MS = 1200;
 function resolvePackageRoot(packageName, tenantRoot) {
   const resolvedPath = require2.resolve(packageName, {
     paths: [tenantRoot, packageRoot, process.cwd()]
@@ -39,6 +51,24 @@ function resolveNodeEntrypoint(packageDir, sourceRelativePath, distRelativePath)
     args: [resolve(packageDir, distRelativePath)]
   };
 }
+function resolveOptionalScriptEntrypoint(packageDir, sourceRelativePath, distRelativePath) {
+  const sourcePath = resolve(packageDir, sourceRelativePath);
+  const runTsPath = resolve(packageDir, "scripts", "run-ts.mjs");
+  if (existsSync(sourcePath) && existsSync(runTsPath)) {
+    return {
+      command: process.execPath,
+      args: [runTsPath, sourcePath]
+    };
+  }
+  const distPath = resolve(packageDir, distRelativePath);
+  if (existsSync(distPath)) {
+    return {
+      command: process.execPath,
+      args: [distPath]
+    };
+  }
+  return null;
+}
 function resolveTenantApiEntrypoint(tenantRoot, runTsPath) {
   const javascriptCandidates = [
     resolve(tenantRoot, "src", "api", "server.js"),
@@ -67,10 +97,122 @@ function withWatchArgs(args, watchPaths) {
 function normalizePort(value, fallback) {
   return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
 }
+function normalizeSetupMode(value) {
+  return value ?? "auto";
+}
+function normalizeFeedbackMode(value) {
+  return value ?? "live";
+}
+function normalizeOpenMode(value) {
+  return value ?? "auto";
+}
+function browserHost(host) {
+  return host === "0.0.0.0" || host === "::" || host === "[::]" ? "127.0.0.1" : host;
+}
+function webUrlFor(host, port) {
+  return `http://${browserHost(host)}:${port}`;
+}
+function createWatchEntries(tenantRoot, sdkPackageRoot) {
+  const entries = [
+    { kind: "tenant", root: resolve(tenantRoot, "src") },
+    { kind: "tenant", root: resolve(tenantRoot, "public") },
+    { kind: "tenant", root: resolve(tenantRoot, "astro.config.ts") },
+    { kind: "tenant", root: resolve(tenantRoot, "treeseed.site.yaml") }
+  ];
+  if (!packageRoot.split(sep).includes("node_modules")) {
+    entries.push(
+      { kind: "package", root: resolve(packageRoot, "src") },
+      { kind: "package", root: resolve(packageRoot, "scripts") },
+      { kind: "package", root: resolve(packageRoot, "package.json") }
+    );
+  }
+  if (!sdkPackageRoot.split(sep).includes("node_modules")) {
+    entries.push(
+      { kind: "sdk", root: resolve(sdkPackageRoot, "src") },
+      { kind: "sdk", root: resolve(sdkPackageRoot, "scripts") },
+      { kind: "sdk", root: resolve(sdkPackageRoot, "package.json") }
+    );
+  }
+  return entries;
+}
+function isSurfaceIncluded(plan, id) {
+  return plan.commands.some((command) => command.id === id);
+}
+function createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, planLike, env) {
+  if (setupMode === "off") {
+    return [
+      {
+        id: "setup-disabled",
+        label: "Local setup disabled",
+        required: false,
+        status: "skipped",
+        detail: "Run without --setup off to prepare workspace links, local D1 state, and generated dev artifacts."
+      }
+    ];
+  }
+  const coreScripts = [
+    ["starlight-patch", "Patch Starlight content path", "scripts/patch-starlight-content-path.ts", "dist/scripts/patch-starlight-content-path.js"],
+    ["books", "Generate book/public artifacts", "scripts/aggregate-book.ts", "dist/scripts/aggregate-book.js"],
+    ["worker-bundle", "Generate local worker bundle", "scripts/build-tenant-worker.ts", "dist/scripts/build-tenant-worker.js"]
+  ];
+  const steps = [
+    {
+      id: "workspace-links",
+      label: "Ensure local workspace links",
+      required: setupMode === "auto",
+      status: "planned"
+    },
+    {
+      id: "wrangler",
+      label: "Verify Wrangler executable",
+      required: isSurfaceIncluded(planLike, "api"),
+      status: "planned",
+      detail: resolveTreeseedToolBinary("wrangler", { env }) ?? void 0
+    },
+    ...coreScripts.map(([id, label, source, dist]) => {
+      const script = resolveOptionalScriptEntrypoint(packageRoot, source, dist);
+      return {
+        id,
+        label,
+        required: true,
+        command: script?.command,
+        args: script?.args,
+        status: script ? "planned" : "skipped",
+        detail: script ? void 0 : `Script not found at ${source}.`
+      };
+    }),
+    {
+      id: "mailpit",
+      label: "Check optional Mailpit email runtime",
+      required: false,
+      status: "planned"
+    }
+  ];
+  if (isSurfaceIncluded(planLike, "api") && existsSync(resolve(tenantRoot, "migrations"))) {
+    const migrate = resolveOptionalScriptEntrypoint(
+      sdkPackageRoot,
+      "scripts/tenant-d1-migrate-local.ts",
+      "dist/scripts/tenant-d1-migrate-local.js"
+    );
+    steps.push({
+      id: "d1-migrations",
+      label: "Run local D1 migrations",
+      required: true,
+      command: migrate?.command,
+      args: migrate?.args,
+      status: migrate ? "planned" : "failed",
+      detail: migrate ? void 0 : "Unable to resolve the local D1 migration script."
+    });
+  }
+  return steps;
+}
 function createTreeseedIntegratedDevPlan(options = {}) {
   const tenantRoot = resolve(options.cwd ?? process.cwd());
   const surface = options.surface ?? "integrated";
-  const watch = options.watch === true;
+  const setupMode = normalizeSetupMode(options.setupMode);
+  const feedbackMode = normalizeFeedbackMode(options.feedbackMode);
+  const openMode = normalizeOpenMode(options.openMode);
+  const watch = feedbackMode !== "off" || options.watch === true;
   const webHost = options.webHost ?? TREESEED_DEFAULT_WEB_HOST;
   const webPort = normalizePort(options.webPort, TREESEED_DEFAULT_WEB_PORT);
   const apiHost = options.apiHost ?? TREESEED_DEFAULT_API_HOST;
@@ -80,7 +222,8 @@ function createTreeseedIntegratedDevPlan(options = {}) {
   const projectId = options.projectId ?? process.env.TREESEED_PROJECT_ID;
   const teamId = options.teamId ?? process.env.TREESEED_HOSTING_TEAM_ID;
   const mergedEnv = { ...process.env, ...options.env ?? {} };
-  const apiBaseUrl = mergedEnv.TREESEED_API_BASE_URL?.trim() || `http://${apiHost}:${apiPort}`;
+  const apiBaseUrl = options.apiHost != null || options.apiPort != null ? `http://${apiHost}:${apiPort}` : mergedEnv.TREESEED_API_BASE_URL?.trim() || `http://${apiHost}:${apiPort}`;
+  const webUrl = surface === "integrated" || surface === "web" ? webUrlFor(webHost, webPort) : null;
   const sdkPackageRoot = resolvePackageRoot("@treeseed/sdk", tenantRoot);
   const coreRunTsPath = resolve(packageRoot, "scripts", "run-ts.mjs");
   const webEntrypoint = resolveNodeEntrypoint(
@@ -103,9 +246,11 @@ function createTreeseedIntegratedDevPlan(options = {}) {
     "src/services/worker.ts",
     "dist/services/worker.js"
   );
+  const watchEntries = watch ? createWatchEntries(tenantRoot, sdkPackageRoot) : [];
   const watchPaths = [
     resolve(packageRoot, existsSync(resolve(packageRoot, "src")) ? "src" : "dist"),
     resolve(tenantRoot, "src"),
+    resolve(tenantRoot, "public"),
     resolve(tenantRoot, "treeseed.site.yaml"),
     resolve(tenantRoot, "astro.config.ts")
   ];
@@ -115,9 +260,12 @@ function createTreeseedIntegratedDevPlan(options = {}) {
     TREESEED_API_BASE_URL: apiBaseUrl,
     TREESEED_MARKET_API_BASE_URL: mergedEnv.TREESEED_MARKET_API_BASE_URL ?? apiBaseUrl,
     TREESEED_PROJECT_ID: projectId ?? mergedEnv.TREESEED_PROJECT_ID,
-    TREESEED_HOSTING_TEAM_ID: teamId ?? mergedEnv.TREESEED_HOSTING_TEAM_ID
+    TREESEED_HOSTING_TEAM_ID: teamId ?? mergedEnv.TREESEED_HOSTING_TEAM_ID,
+    TREESEED_API_D1_DATABASE_NAME: mergedEnv.TREESEED_API_D1_DATABASE_NAME ?? "SITE_DATA_DB",
+    SITE_DATA_DB: mergedEnv.SITE_DATA_DB ?? "SITE_DATA_DB",
+    TREESEED_API_D1_LOCAL_PERSIST_TO: mergedEnv.TREESEED_API_D1_LOCAL_PERSIST_TO ?? resolve(tenantRoot, ".wrangler", "state", "v3", "d1")
   };
-  if (watch) {
+  if (watch && feedbackMode === "live") {
     sharedEnv.TREESEED_PUBLIC_DEV_WATCH_RELOAD = sharedEnv.TREESEED_PUBLIC_DEV_WATCH_RELOAD || "true";
   }
   const commands = [];
@@ -140,7 +288,7 @@ function createTreeseedIntegratedDevPlan(options = {}) {
       cwd: tenantRoot,
       env: {
         ...sharedEnv,
-        PORT: sharedEnv.PORT ?? String(apiPort)
+        PORT: options.apiPort != null ? String(apiPort) : sharedEnv.PORT ?? String(apiPort)
       }
     });
   }
@@ -153,8 +301,8 @@ function createTreeseedIntegratedDevPlan(options = {}) {
       cwd: tenantRoot,
       env: {
         ...sharedEnv,
-        PORT: sharedEnv.PORT ?? String(managerPort),
-        TREESEED_MANAGER_BASE_URL: sharedEnv.TREESEED_MANAGER_BASE_URL ?? `http://${apiHost}:${managerPort}`
+        PORT: options.managerPort != null ? String(managerPort) : sharedEnv.PORT ?? String(managerPort),
+        TREESEED_MANAGER_BASE_URL: options.managerPort != null ? `http://${apiHost}:${managerPort}` : sharedEnv.TREESEED_MANAGER_BASE_URL ?? `http://${apiHost}:${managerPort}`
       }
     });
   }
@@ -168,10 +316,44 @@ function createTreeseedIntegratedDevPlan(options = {}) {
       env: sharedEnv
     });
   }
+  const readyChecks = commands.map((command) => {
+    if (command.id === "web") {
+      return {
+        id: command.id,
+        label: command.label,
+        required: true,
+        strategy: "http",
+        url: webUrl ?? void 0
+      };
+    }
+    if (command.id === "api") {
+      return {
+        id: command.id,
+        label: command.label,
+        required: true,
+        strategy: "http",
+        url: `${apiBaseUrl.replace(/\/$/u, "")}/readyz`
+      };
+    }
+    return {
+      id: command.id,
+      label: command.label,
+      required: false,
+      strategy: "process"
+    };
+  });
   return {
     surface,
+    setupMode,
+    feedbackMode,
+    openMode,
+    watch,
     tenantRoot,
     apiBaseUrl,
+    webUrl,
+    setupSteps: createSetupSteps(tenantRoot, setupMode, sdkPackageRoot, { commands }, sharedEnv),
+    readyChecks,
+    watchEntries,
     commands
   };
 }
@@ -194,8 +376,370 @@ function stopChildProcess(child, signal = "SIGTERM") {
   } catch {
   }
 }
+function writeDevReloadStamp(projectRoot) {
+  const outputPath = resolve(projectRoot, DEV_RELOAD_FILE);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(
+    outputPath,
+    `${JSON.stringify(
+      {
+        buildId: `${Date.now()}`,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
+  );
+}
+function shouldIgnoreWatchPath(filePath, rootPath) {
+  const rel = relative(rootPath, filePath);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === "..") {
+    return false;
+  }
+  const normalized = rel.split(sep).join("/");
+  return normalized === ".git" || normalized.startsWith(".git/") || normalized === "node_modules" || normalized.startsWith("node_modules/") || normalized === ".astro" || normalized.startsWith(".astro/") || normalized === ".wrangler" || normalized.startsWith(".wrangler/") || normalized === ".local" || normalized.startsWith(".local/") || normalized === ".treeseed" || normalized.startsWith(".treeseed/") || normalized === "dist" || normalized.startsWith("dist/") || normalized === "coverage" || normalized.startsWith("coverage/") || normalized.startsWith("public/books/") || normalized.startsWith("public/__treeseed/");
+}
+function collectRootSnapshot(rootPath, snapshot) {
+  if (!existsSync(rootPath)) {
+    return;
+  }
+  const stats = statSync(rootPath);
+  if (stats.isFile()) {
+    snapshot.set(rootPath, `${stats.mtimeMs}:${stats.size}`);
+    return;
+  }
+  for (const entry of readdirSync(rootPath, { withFileTypes: true })) {
+    const fullPath = resolve(rootPath, entry.name);
+    if (shouldIgnoreWatchPath(fullPath, rootPath)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      collectDirectorySnapshot(fullPath, rootPath, snapshot);
+      continue;
+    }
+    const entryStats = statSync(fullPath);
+    snapshot.set(fullPath, `${entryStats.mtimeMs}:${entryStats.size}`);
+  }
+}
+function collectDirectorySnapshot(directoryPath, rootPath, snapshot) {
+  if (shouldIgnoreWatchPath(directoryPath, rootPath)) {
+    return;
+  }
+  for (const entry of readdirSync(directoryPath, { withFileTypes: true })) {
+    const fullPath = resolve(directoryPath, entry.name);
+    if (shouldIgnoreWatchPath(fullPath, rootPath)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      collectDirectorySnapshot(fullPath, rootPath, snapshot);
+      continue;
+    }
+    const stats = statSync(fullPath);
+    snapshot.set(fullPath, `${stats.mtimeMs}:${stats.size}`);
+  }
+}
+function collectSnapshot(entries) {
+  const snapshot = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    collectRootSnapshot(entry.root, snapshot);
+  }
+  return snapshot;
+}
+function diffSnapshots(previousSnapshot, nextSnapshot) {
+  const changed = /* @__PURE__ */ new Set();
+  for (const [filePath, signature] of nextSnapshot.entries()) {
+    if (previousSnapshot.get(filePath) !== signature) {
+      changed.add(filePath);
+    }
+  }
+  for (const filePath of previousSnapshot.keys()) {
+    if (!nextSnapshot.has(filePath)) {
+      changed.add(filePath);
+    }
+  }
+  return [...changed];
+}
+function classifyChanges(changedPaths, watchEntries) {
+  function matchesEntry(filePath, entry) {
+    return filePath === entry.root || filePath.startsWith(`${entry.root}${sep}`);
+  }
+  return {
+    changedPaths,
+    sdkChanged: changedPaths.some(
+      (filePath) => watchEntries.some((entry) => entry.kind === "sdk" && matchesEntry(filePath, entry))
+    ),
+    packageChanged: changedPaths.some(
+      (filePath) => watchEntries.some((entry) => entry.kind === "package" && matchesEntry(filePath, entry))
+    ),
+    tenantChanged: changedPaths.some(
+      (filePath) => watchEntries.some((entry) => entry.kind === "tenant" && matchesEntry(filePath, entry))
+    )
+  };
+}
+function startPollingWatch({ watchEntries, onChange }) {
+  let previousSnapshot = collectSnapshot(watchEntries);
+  let queuedPaths = [];
+  let debounceTimer = null;
+  let running = false;
+  const intervalId = setInterval(() => {
+    const nextSnapshot = collectSnapshot(watchEntries);
+    const changedPaths = diffSnapshots(previousSnapshot, nextSnapshot);
+    previousSnapshot = nextSnapshot;
+    if (changedPaths.length === 0) {
+      return;
+    }
+    queuedPaths.push(...changedPaths);
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+      void flush();
+    }, WATCH_DEBOUNCE_MS);
+  }, WATCH_INTERVAL_MS);
+  async function flush() {
+    if (running || queuedPaths.length === 0) {
+      return;
+    }
+    const changedPaths = [...new Set(queuedPaths)];
+    queuedPaths = [];
+    running = true;
+    try {
+      await onChange(classifyChanges(changedPaths, watchEntries));
+    } finally {
+      running = false;
+    }
+  }
+  return () => {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    clearInterval(intervalId);
+  };
+}
+function defaultWrite(line, stream) {
+  const target = stream === "stderr" ? process.stderr : process.stdout;
+  target.write(line);
+}
+function emitEvent(options, write, event, stream = event.type === "error" ? "stderr" : "stdout") {
+  if (options.json) {
+    write(`${JSON.stringify({ schemaVersion: 1, kind: "treeseed.dev.event", ...event })}
+`, stream);
+    return;
+  }
+  const surface = event.surface ? `[${event.surface}]` : event.type === "setup" ? "[setup]" : "[dev]";
+  const message = event.message ?? event.detail ?? event.status ?? "";
+  write(`${surface} ${String(message)}
+`, stream);
+}
+function writePlan(plan, options, write) {
+  if (options.json) {
+    write(`${JSON.stringify({ schemaVersion: 1, kind: "treeseed.dev.plan", ok: true, payload: plan }, null, 2)}
+`, "stdout");
+    return;
+  }
+  write(`Treeseed dev plan
+`, "stdout");
+  write(`surface: ${plan.surface}
+`, "stdout");
+  write(`setup: ${plan.setupMode}
+`, "stdout");
+  write(`feedback: ${plan.feedbackMode}
+`, "stdout");
+  if (plan.webUrl) {
+    write(`web: ${plan.webUrl}
+`, "stdout");
+  }
+  write(`api: ${plan.apiBaseUrl}
+`, "stdout");
+  for (const command of plan.commands) {
+    write(`- ${command.id}: ${command.command} ${command.args.join(" ")}
+`, "stdout");
+  }
+}
+function attachPrefixedLogReader(child, surface, options, write) {
+  function attach(stream, name) {
+    if (!stream || typeof stream.on !== "function") {
+      return;
+    }
+    let buffer = "";
+    stream.on("data", (chunk) => {
+      buffer += chunk.toString();
+      for (; ; ) {
+        const newlineIndex = buffer.indexOf("\n");
+        if (newlineIndex < 0) {
+          break;
+        }
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        if (options.json) {
+          emitEvent(options, write, { type: "log", surface, message: line, detail: { stream: name } }, name);
+        } else {
+          write(`[${surface}] ${line}
+`, name);
+        }
+      }
+    });
+    stream.on("end", () => {
+      if (buffer.length > 0) {
+        if (options.json) {
+          emitEvent(options, write, { type: "log", surface, message: buffer, detail: { stream: name } }, name);
+        } else {
+          write(`[${surface}] ${buffer}
+`, name);
+        }
+        buffer = "";
+      }
+    });
+  }
+  attach(child.stdout ?? null, "stdout");
+  attach(child.stderr ?? null, "stderr");
+}
+function runSetupStep(step, plan, deps) {
+  if (!step.command || !step.args) {
+    return {
+      ...step,
+      status: step.status === "failed" ? "failed" : "skipped"
+    };
+  }
+  const result = deps.spawnSync(step.command, step.args, {
+    cwd: plan.tenantRoot,
+    env: {
+      ...process.env,
+      ...plan.commands[0]?.env,
+      TREESEED_LOCAL_DEV_MODE: "cloudflare",
+      TREESEED_PUBLIC_DEV_WATCH_RELOAD: plan.feedbackMode === "live" ? "true" : process.env.TREESEED_PUBLIC_DEV_WATCH_RELOAD
+    },
+    encoding: "utf8"
+  });
+  if ((result.status ?? 1) === 0) {
+    return {
+      ...step,
+      status: "completed",
+      detail: [result.stdout, result.stderr].filter(Boolean).join("\n").trim() || step.detail
+    };
+  }
+  return {
+    ...step,
+    status: step.required ? "failed" : "degraded",
+    detail: [result.stdout, result.stderr].filter(Boolean).join("\n").trim() || `Exited with ${result.status ?? 1}.`
+  };
+}
+function runLocalSetup(plan, options, deps) {
+  const results = [];
+  if (plan.setupMode === "off") {
+    for (const step of plan.setupSteps) {
+      results.push(step);
+      emitEvent(options, deps.write, { type: "setup", status: step.status, message: `${step.label}: ${step.status}`, detail: step.detail });
+    }
+    return results;
+  }
+  for (const step of plan.setupSteps) {
+    let result = step;
+    if (step.id === "workspace-links") {
+      if (plan.setupMode === "check") {
+        result = { ...step, status: "skipped", detail: "Workspace links were checked in non-mutating mode." };
+      } else {
+        const workspaceRoot = findNearestTreeseedWorkspaceRoot(plan.tenantRoot);
+        if (workspaceRoot) {
+          const links = ensureLocalWorkspaceLinks(workspaceRoot, {
+            mode: "auto",
+            env: { ...process.env, ...plan.commands[0]?.env }
+          });
+          result = {
+            ...step,
+            status: links.issues.length > 0 ? "failed" : "completed",
+            detail: links.issues.length > 0 ? links.issues.join("; ") : `Verified ${links.links.length} workspace link${links.links.length === 1 ? "" : "s"}.`
+          };
+        } else {
+          result = { ...step, status: "skipped", detail: "No Treeseed workspace root found." };
+        }
+      }
+    } else if (step.id === "wrangler") {
+      const wrangler = resolveTreeseedToolBinary("wrangler", { env: { ...process.env, ...plan.commands[0]?.env } });
+      result = wrangler ? { ...step, status: "completed", detail: wrangler } : {
+        ...step,
+        status: step.required ? "failed" : "degraded",
+        detail: "Wrangler was not found. Run `npx trsd install --json` and retry `npx trsd dev`."
+      };
+    } else if (step.id === "mailpit") {
+      const docker = resolveTreeseedToolBinary("docker", { env: { ...process.env, ...plan.commands[0]?.env } });
+      result = docker ? { ...step, status: "completed", detail: `Docker detected at ${docker}; Mailpit remains optional for local dev.` } : { ...step, status: "degraded", detail: "Docker is unavailable, so Mailpit email previews are disabled." };
+    } else if (plan.setupMode === "check") {
+      result = { ...step, status: step.status === "failed" ? "failed" : "skipped", detail: step.detail ?? "Skipped in setup check mode." };
+    } else {
+      result = runSetupStep(step, plan, deps);
+    }
+    results.push(result);
+    emitEvent(options, deps.write, {
+      type: "setup",
+      status: result.status,
+      message: `${result.label}: ${result.status}`,
+      detail: result.detail
+    }, result.status === "failed" ? "stderr" : "stdout");
+  }
+  const failedRequired = results.some((step) => step.required && step.status === "failed");
+  if (plan.feedbackMode === "live" && plan.setupMode === "auto" && !failedRequired) {
+    writeDevReloadStamp(plan.tenantRoot);
+    emitEvent(options, deps.write, { type: "reload", message: "Wrote initial browser reload stamp." });
+  }
+  return results;
+}
+async function fetchOk(fetchFn, url, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchFn(url, { signal: controller.signal });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function waitForHttpReady(fetchFn, url, timeoutMs) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await fetchOk(fetchFn, url, 2e3)) {
+      return true;
+    }
+    await delay(500);
+  }
+  return false;
+}
+async function defaultOpenBrowser(url) {
+  const platform = process.platform;
+  const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.unref();
+}
+function shouldOpenBrowser(plan) {
+  if (!plan.webUrl || plan.openMode === "off") {
+    return false;
+  }
+  if (plan.openMode === "on") {
+    return true;
+  }
+  return process.stdout.isTTY === true && process.env.CI !== "true";
+}
+function failedSetupMessage(failed) {
+  return [
+    `${failed.label} failed.`,
+    failed.detail ? String(failed.detail) : null,
+    "Run `npx trsd install --json` if a managed executable is missing, then retry `npx trsd dev --setup auto`."
+  ].filter(Boolean).join(" ");
+}
 async function runTreeseedIntegratedDev(options = {}, deps = {}) {
   const tenantRoot = resolve(options.cwd ?? process.cwd());
+  const write = deps.write ?? defaultWrite;
+  const spawnProcess = deps.spawn ?? spawn;
+  const spawnSyncProcess = deps.spawnSync ?? spawnSync;
+  const onSignal = deps.onSignal ?? defaultSignalRegistrar;
+  const fetchFn = deps.fetch ?? globalThis.fetch.bind(globalThis);
+  const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
+  const startWatch = deps.startWatch ?? startPollingWatch;
   const prepareEnvironment = deps.prepareEnvironment ?? defaultPrepareEnvironment;
   prepareEnvironment(tenantRoot);
   const plan = createTreeseedIntegratedDevPlan({
@@ -206,10 +750,22 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       ...options.env ?? {}
     }
   });
-  const spawnProcess = deps.spawn ?? spawn;
-  const onSignal = deps.onSignal ?? defaultSignalRegistrar;
+  if (options.plan) {
+    writePlan(plan, options, write);
+    return 0;
+  }
+  const setupResults = runLocalSetup(plan, options, { spawnSync: spawnSyncProcess, write });
+  const failedSetup = setupResults.find((step) => step.status === "failed" && step.required);
+  if (failedSetup) {
+    emitEvent(options, write, { type: "error", message: failedSetupMessage(failedSetup), detail: failedSetup });
+    return 1;
+  }
   const children = /* @__PURE__ */ new Map();
+  const commandsById = new Map(plan.commands.map((command) => [command.id, command]));
+  const exited = /* @__PURE__ */ new Map();
+  let stopWatching = null;
   let settled = false;
+  let restarting = false;
   return await new Promise((resolveExitCode) => {
     const disposers = [
       onSignal("SIGINT", () => finalize(130)),
@@ -220,6 +776,10 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
         return;
       }
       settled = true;
+      if (stopWatching) {
+        stopWatching();
+        stopWatching = null;
+      }
       for (const [childId, child] of children.entries()) {
         if (childId !== originId) {
           stopChildProcess(child);
@@ -228,20 +788,149 @@ async function runTreeseedIntegratedDev(options = {}, deps = {}) {
       for (const dispose of disposers) {
         dispose();
       }
+      emitEvent(options, write, { type: "shutdown", exitCode, message: `Dev runtime stopped with exit code ${exitCode}.` }, exitCode === 0 ? "stdout" : "stderr");
       resolveExitCode(exitCode);
     }
-    for (const command of plan.commands) {
+    function spawnCommand(command) {
+      emitEvent(options, write, {
+        type: "spawn",
+        surface: command.id,
+        command: command.command,
+        args: command.args,
+        message: `Starting ${command.label}.`
+      });
       const child = spawnProcess(command.command, command.args, {
         cwd: command.cwd,
         env: command.env,
-        stdio: options.stdio ?? "inherit"
+        stdio: options.stdio ?? ["inherit", "pipe", "pipe"],
+        detached: false
       });
       children.set(command.id, child);
+      attachPrefixedLogReader(child, command.id, options, write);
       child.on("exit", (code, signal) => {
+        children.delete(command.id);
+        exited.set(command.id, { code, signal });
+        if (restarting || settled) {
+          return;
+        }
         const exitCode = signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : code ?? 0;
+        emitEvent(options, write, {
+          type: exitCode === 0 ? "shutdown" : "error",
+          surface: command.id,
+          exitCode,
+          signal,
+          message: `${command.label} exited with ${signal ?? exitCode}.`
+        }, exitCode === 0 ? "stdout" : "stderr");
         finalize(exitCode, command.id);
       });
+      return child;
+    }
+    async function restartCommand(id) {
+      const command = commandsById.get(id);
+      if (!command || settled) {
+        return;
+      }
+      const current = children.get(id);
+      restarting = true;
+      if (current) {
+        stopChildProcess(current);
+        await delay(350);
+      }
+      children.delete(id);
+      exited.delete(id);
+      restarting = false;
+      spawnCommand(command);
+      emitEvent(options, write, { type: "restart", surface: id, message: `Restarted ${command.label}.` });
+    }
+    async function waitForReadiness() {
+      const readinessTimeoutMs = options.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
+      const processReadyGraceMs = options.processReadyGraceMs ?? DEFAULT_PROCESS_READY_GRACE_MS;
+      for (const check of plan.readyChecks) {
+        if (settled) {
+          return;
+        }
+        let ready = false;
+        if (check.strategy === "http" && check.url) {
+          ready = await waitForHttpReady(fetchFn, check.url, readinessTimeoutMs);
+        } else {
+          await delay(processReadyGraceMs);
+          ready = !exited.has(check.id);
+        }
+        if (settled) {
+          return;
+        }
+        if (!ready && check.required) {
+          emitEvent(options, write, {
+            type: "error",
+            surface: check.id,
+            url: check.url,
+            message: `${check.label} did not become ready${check.url ? ` at ${check.url}` : ""}.`
+          });
+          finalize(1, check.id);
+          return;
+        }
+        emitEvent(options, write, {
+          type: "ready",
+          surface: check.id,
+          status: ready ? "ready" : "degraded",
+          url: check.url,
+          message: `${check.label} is ${ready ? "ready" : "degraded"}.`
+        });
+      }
+      if (plan.webUrl) {
+        emitEvent(options, write, { type: "ready", url: plan.webUrl, message: `Treeseed dev ready at ${plan.webUrl}.` });
+      }
+      if (shouldOpenBrowser(plan)) {
+        try {
+          await openBrowser(plan.webUrl);
+          emitEvent(options, write, { type: "open", url: plan.webUrl, message: `Opened ${plan.webUrl}.` });
+        } catch (error) {
+          emitEvent(options, write, {
+            type: "open",
+            status: "degraded",
+            url: plan.webUrl,
+            message: `Could not open ${plan.webUrl}.`,
+            detail: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    }
+    for (const command of plan.commands) {
+      spawnCommand(command);
+    }
+    if (plan.watchEntries.length > 0 && plan.feedbackMode !== "off") {
+      stopWatching = startWatch({
+        watchEntries: plan.watchEntries,
+        onChange: async (change) => {
+          if (settled) {
+            return;
+          }
+          emitEvent(options, write, {
+            type: "restart",
+            message: `Detected ${change.changedPaths.length} change${change.changedPaths.length === 1 ? "" : "s"}.`,
+            detail: {
+              tenantChanged: change.tenantChanged,
+              packageChanged: change.packageChanged,
+              sdkChanged: change.sdkChanged
+            }
+          });
+          if (change.packageChanged || change.sdkChanged) {
+            await Promise.all([
+              restartCommand("api"),
+              restartCommand("manager"),
+              restartCommand("worker")
+            ]);
+          } else if (change.tenantChanged) {
+            await restartCommand("api");
+          }
+          if (plan.feedbackMode === "live") {
+            writeDevReloadStamp(plan.tenantRoot);
+            emitEvent(options, write, { type: "reload", message: "Wrote browser reload stamp." });
+          }
+        }
+      });
     }
+    void waitForReadiness();
   });
 }
 export {

package/dist/scripts/dev-platform.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runTreeseedIntegratedDev } from '../dev.js';
+import { runTreeseedIntegratedDev, } from '../dev.js';
 const args = process.argv.slice(2);
 function readFlag(name) {
     return args.includes(name);
@@ -11,6 +11,14 @@ function readOption(name) {
     }
     return args[index + 1];
 }
+function readNumberOption(name) {
+    const value = readOption(name);
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
 function parseSurface(value) {
     if (value === 'web'
         || value === 'api'
@@ -22,9 +30,37 @@ function parseSurface(value) {
     }
     return 'integrated';
 }
+function parseSetupMode(value) {
+    if (value === 'auto' || value === 'check' || value === 'off') {
+        return value;
+    }
+    return undefined;
+}
+function parseFeedbackMode(value) {
+    if (value === 'live' || value === 'restart' || value === 'off') {
+        return value;
+    }
+    return undefined;
+}
+function parseOpenMode(value) {
+    if (value === 'auto' || value === 'on' || value === 'off') {
+        return value;
+    }
+    return undefined;
+}
 const exitCode = await runTreeseedIntegratedDev({
     surface: parseSurface(readOption('--surface')),
     watch: readFlag('--watch'),
+    webHost: readOption('--host'),
+    webPort: readNumberOption('--port'),
+    apiHost: readOption('--api-host'),
+    apiPort: readNumberOption('--api-port'),
+    managerPort: readNumberOption('--manager-port'),
+    setupMode: parseSetupMode(readOption('--setup')),
+    feedbackMode: parseFeedbackMode(readOption('--feedback')),
+    openMode: parseOpenMode(readOption('--open')),
+    plan: readFlag('--plan'),
+    json: readFlag('--json'),
     projectId: readOption('--project-id'),
     teamId: readOption('--team-id'),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/core",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "Treeseed integrated platform starter for Astro/Starlight web runtimes and Hono API runtimes.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -76,7 +76,7 @@
     "@astrojs/sitemap": "3.7.0",
     "@astrojs/starlight": "0.37.6",
     "@tailwindcss/vite": "^4.1.4",
-    "@treeseed/sdk": "0.6.12",
+    "@treeseed/sdk": "0.6.14",
     "astro": "^5.6.1",
     "esbuild": "^0.28.0",
     "hono": "^4.8.2",