@starlove/orbit 1.2.0 → 1.3.0

package/src/cli/orbit.js

@@ -4,8 +4,9 @@
  * copies managed SKILL-ORBIT.md into the target repo. Does not import board.js.
  */
 
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { removeOrbitAgentsSection, syncAgentsMd, syncSkillOrbitMd } from "../core/agents-md.js";
@@ -17,20 +18,23 @@ function printUsage() {
   orbit -v, --version      Print the Orbit CLI version
   orbit init  [options]    Provision .orbit/board.db + SKILL-ORBIT.md + AGENTS.md
   orbit reset [options]    Delete .orbit/ + SKILL-ORBIT.md + registry row
-  orbit serve [options]    Start the Orbit web app + HTTP API
+  orbit run   [options]    Start the Orbit web app + HTTP API
   orbit docker [options]   Build/run Orbit's web app in Docker
   orbit mcp   [options]    Start the stdio MCP server (for agent clients)
   orbit dispatch [options] Dispatch a Hermes profile on a ticket
 
-Options (init / reset / serve / docker / mcp / dispatch):
+Options (init / reset / run / docker / mcp / dispatch):
   --cwd <dir>           Project root (default: process.cwd())
 
 Options (init only):
   --no-ai               Create the board with AI collaboration disabled
   --example             Create example onboarding tickets
 
-Options (serve / docker):
-  --port <n>            HTTP port (default: 3337, or $PORT)
+Options (run / docker):
+  --port <n>            HTTP port (run auto-starts at 13701; --port/$PORT is exact)
+
+Options (run):
+  -d, --detach          Run in the background and print the child PID/log path
 
 Options (dispatch):
   --board <slug-or-id>  Local board to dispatch against (default: board for --cwd)
@@ -173,6 +177,7 @@ function parseArgs(argv) {
     ai: true,
     example: false,
     port: null,
+    detachRequested: false,
     image: "starscape-orbit:local",
     dataDir: null,
     containerName: null,
@@ -301,6 +306,7 @@ function parseArgs(argv) {
       args.buildImage = false;
     } else if (a === "-d" || a === "--detach") {
       args.detach = true;
+      args.detachRequested = true;
     } else if (a === "--foreground") {
       args.detach = false;
       args.foreground = true;
@@ -461,6 +467,37 @@ async function runServe(options) {
   await import("../server.js");
 }
 
+function orbitDataDir() {
+  return process.env.DATA_DIR || join(homedir(), ".orbit");
+}
+
+function startDetachedRun(options) {
+  const dataDir = orbitDataDir();
+  mkdirSync(dataDir, { recursive: true });
+  const logPath = join(dataDir, "orbit-run.log");
+  const logFd = openSync(logPath, "a");
+  const cliPath = fileURLToPath(import.meta.url);
+  const childArgs = [cliPath, "run", "--cwd", resolve(options.cwd)];
+  if (options.port) childArgs.push("--port", String(options.port));
+  const child = spawn(process.execPath, childArgs, {
+    cwd: process.cwd(),
+    detached: true,
+    env: { ...process.env },
+    stdio: ["ignore", logFd, logFd]
+  });
+  child.unref();
+  closeSync(logFd);
+  const port = options.port || process.env.PORT || 13701;
+  console.log("Started Orbit in detached mode.");
+  console.log(`PID: ${child.pid}`);
+  console.log(`Log: ${logPath}`);
+  console.log(
+    options.port || process.env.PORT
+      ? `URL: http://localhost:${port}`
+      : `URL: starts at http://localhost:${port} (auto-increments if busy; see log)`
+  );
+}
+
 function containerPathFor(hostPath, fallbackPath) {
   // Linux/macOS Docker can mount the same absolute path into the container,
   // which keeps existing Orbit board metadata meaningful. Windows paths are
@@ -473,7 +510,7 @@ function buildDockerPlan(options) {
   const dataDir = resolve(options.dataDir || resolve(projectRoot, ".orbit", "docker-data"));
   const containerProjectRoot = containerPathFor(projectRoot, "/workspace");
   const containerDataDir = containerPathFor(dataDir, "/data");
-  const port = String(options.port || process.env.PORT || 3337);
+  const port = String(options.port || process.env.PORT || 13701);
 
   if (!existsSync(projectRoot)) {
     throw new Error(`Project root does not exist: ${projectRoot}`);
@@ -508,7 +545,7 @@ function buildDockerPlan(options) {
     "-w",
     containerProjectRoot,
     options.image,
-    "serve",
+    "run",
     "--cwd",
     containerProjectRoot,
     "--port",
@@ -595,8 +632,9 @@ async function main() {
       await runInit(args);
     } else if (args.command === "reset") {
       await runReset(args);
-    } else if (args.command === "serve") {
-      await runServe(args);
+    } else if (args.command === "run" || args.command === "serve") {
+      if (args.detachRequested && args.detach) startDetachedRun(args);
+      else await runServe(args);
     } else if (args.command === "docker") {
       await runDocker(args);
     } else if (args.command === "mcp") {

package/src/core/agents-md.js

@@ -33,6 +33,21 @@ export function syncSkillOrbitMd(projectRoot, skillSrc) {
   return { ok: true, status: "written", source: skillSrc, path: skillDest };
 }
 
+/**
+ * Write both Orbit helper files (SKILL-ORBIT.md + the AGENTS.md Orbit section)
+ * into a project root. This is the shared core behind `orbit init` and the
+ * web-UI "Generate AI helper files" checkbox, so the two flows stay identical.
+ * Never throws — returns a result the caller can log or ignore.
+ */
+export function generateHelperFiles(projectRoot, skillSrc, logger = console.log) {
+  if (!existsSync(skillSrc)) {
+    return { ok: false, status: "missing_source", source: skillSrc };
+  }
+  const skill = syncSkillOrbitMd(projectRoot, skillSrc);
+  syncAgentsMd(projectRoot, {}, logger);
+  return { ok: true, status: skill.status, skill };
+}
+
 export function syncAgentsMd(projectRoot, _options = {}, logger = console.log) {
   const agentsPath = resolve(projectRoot, "AGENTS.md");
   const section = orbitAgentsSection();

package/src/core/board.js

@@ -8,7 +8,7 @@
 //   3. Iterate every registry board, ensuring the per-board schema exists
 //      and reindexing FTS for that board's DB. No "active board" singleton:
 //      each iteration opens its own connection.
-//   4. When launched through `orbit serve`, refresh Orbit-managed
+//   4. When launched through `orbit run`, refresh Orbit-managed
 //      SKILL-ORBIT.md copies for registered repo paths.
 //
 // Beyond startup this module just re-exports per-domain functions for
@@ -67,6 +67,9 @@ function syncManagedSkillOrbitFiles() {
   const skillSrc = resolve(ROOT_DIR, "SKILL-ORBIT.md");
   for (const row of listBoards()) {
     if (!row.repo_path) continue;
+    // Respect boards created without "Generate AI helper files" — don't
+    // re-push SKILL-ORBIT.md into a repo the user opted out of.
+    if (row.manage_helper_files === 0) continue;
     try {
       const result = syncSkillOrbitMd(row.repo_path, skillSrc);
       if (result.status === "missing_source") {
@@ -107,10 +110,10 @@ export const boardRuntime = {
   port: PORT
 };
 
-export function startupSummary() {
+export function startupSummary(port = PORT) {
   const rows = listBoards();
   return {
-    url: `http://localhost:${PORT}`,
+    url: `http://localhost:${port}`,
     registryPath: REGISTRY_DB_PATH,
     boardCount: rows.length,
     boardPaths: rows.map((row) => row.db_path)

package/src/core/boards.js

@@ -9,8 +9,10 @@ import {
 import { requireBoardAccess, requirePermission } from "./auth.js";
 import { recordEvent } from "./events.js";
 import { buildBoardFromRepo } from "./seed.js";
+import { generateHelperFiles } from "./agents-md.js";
 import { httpError, id, now, normalizePath, normalizeProjectEntryType, requiredString, slugify } from "./util.js";
 import { DATA_DIR, MCP_SERVER_PATH, ROOT_DIR } from "./paths.js";
+import { resolve } from "node:path";
 
 /** Create a brand-new board on disk + register it. Does not require an
  *  existing ctx.board / ctx.db: this is registry-only. */
@@ -20,7 +22,13 @@ export function createBoard(body, ctx) {
 
   const name = requiredString(body.name, "name");
   const slug = slugify(body.slug || name);
-  const repoPath = normalizePath(requiredString(body.repo_path || body.system_path, "repo_path"));
+  // Folder is optional: a board without a repo_path is a pure kanban board (no
+  // agent dispatch, no managed helper files). When present it is the coding
+  // project where SKILL-ORBIT.md / AGENTS.md live for the AI agent's reference.
+  const repoPath = normalizePath(body.repo_path || body.system_path || "");
+  // Only meaningful with a folder; default on so the common "link my repo" path
+  // keeps writing the docs. Stored so the serve-time refresh respects opt-out.
+  const manageHelperFiles = repoPath ? body.manage_helper_files !== false : false;
   const reg = getRegistry();
   if (reg.prepare("SELECT id FROM boards WHERE slug = ?").get(slug)) {
     throw httpError(409, "board_slug_taken");
@@ -31,7 +39,7 @@ export function createBoard(body, ctx) {
 
   const boardId = id();
   const time = now();
-  const sniff = buildBoardFromRepo(repoPath);
+  const sniff = repoPath ? buildBoardFromRepo(repoPath) : { repoUrl: "", defaultBranch: "main" };
 
   const aiEnabled = body.ai_enabled === undefined ? true : Boolean(body.ai_enabled);
   const defaultStates = body.states || (aiEnabled ? [
@@ -92,11 +100,23 @@ export function createBoard(body, ctx) {
     db_path: dbPath,
     repo_url: body.repo_url || sniff.repoUrl || "",
     default_branch: body.default_branch || sniff.defaultBranch || "main",
+    manage_helper_files: manageHelperFiles ? 1 : 0,
     last_active_at: time,
     created_at: time,
     updated_at: time
   });
 
+  // Mirror `orbit init`: write SKILL-ORBIT.md + the AGENTS.md Orbit section into
+  // the project so the browser flow leaves the same files on disk. Best-effort —
+  // a board is still created if the files can't be written.
+  if (manageHelperFiles) {
+    try {
+      generateHelperFiles(repoPath, resolve(ROOT_DIR, "SKILL-ORBIT.md"));
+    } catch (error) {
+      console.warn(`[orbit] Could not write helper files in ${repoPath}: ${error.message}`);
+    }
+  }
+
   return boardById(db, boardId);
 }
 
@@ -232,25 +252,47 @@ export function updateBoard(boardId, body, ctx) {
     values.push(body.ai_enabled ? 1 : 0);
   }
 
-  if (sets.length === 0) return innerBoard;
-  sets.push("updated_at = ?");
-  values.push(now(), boardId);
-  tx(db, () => {
-    db.prepare(`UPDATE boards SET ${sets.join(", ")} WHERE id = ?`).run(...values);
-    if (aiTurningOn) ensureAgentLanes(db, boardId);
-    recordEvent(db, boardId, "board_updated", null, actor.name, { board_id: boardId, fields: Object.keys(body) });
-  });
+  // manage_helper_files lives on the registry row (not the per-board DB), so it
+  // is handled separately from `sets`. A request that only toggles it must
+  // still be processed even when no per-board columns change.
+  const manageHelperFiles =
+    body.manage_helper_files === undefined ? undefined : Boolean(body.manage_helper_files);
+
+  if (sets.length === 0 && manageHelperFiles === undefined) return innerBoard;
+
+  if (sets.length > 0) {
+    sets.push("updated_at = ?");
+    values.push(now(), boardId);
+    tx(db, () => {
+      db.prepare(`UPDATE boards SET ${sets.join(", ")} WHERE id = ?`).run(...values);
+      if (aiTurningOn) ensureAgentLanes(db, boardId);
+      recordEvent(db, boardId, "board_updated", null, actor.name, { board_id: boardId, fields: Object.keys(body) });
+    });
+  }
 
   // Mirror the changed fields into the registry row so cross-board listings
   // stay coherent without needing a second source of truth.
   const after = boardById(db, boardId);
+  const repoPath = normalizePath(after.system_path || "");
   updateBoardMeta(boardId, {
     name: after.name,
     repo_url: after.repo_url,
     default_branch: after.default_branch,
-    repo_path: normalizePath(after.system_path || "")
+    repo_path: repoPath,
+    ...(manageHelperFiles === undefined ? {} : { manage_helper_files: manageHelperFiles ? 1 : 0 })
   });
 
+  // Generating the helper files is the active half of turning the toggle on:
+  // write them now rather than waiting for the next `orbit run` refresh.
+  // Turning it off just stops the managed refresh; existing files are left.
+  if (manageHelperFiles && repoPath) {
+    try {
+      generateHelperFiles(repoPath, resolve(ROOT_DIR, "SKILL-ORBIT.md"));
+    } catch (error) {
+      console.warn(`[orbit] Could not write helper files in ${repoPath}: ${error.message}`);
+    }
+  }
+
   return after;
 }
 
@@ -284,6 +326,7 @@ export function boardManual(boardId, ctx, options = {}) {
       project_notes: innerBoard.project_notes,
       agent_instructions: innerBoard.agent_instructions,
       ai_enabled: innerBoard.ai_enabled,
+      manage_helper_files: ctx.board.manage_helper_files,
       created_at: innerBoard.created_at,
       updated_at: innerBoard.updated_at
     },

package/src/core/db.js

@@ -103,6 +103,15 @@ export function getRegistry() {
   return openConnection(REGISTRY_DB_PATH);
 }
 
+/** Add a column to an existing table only if it is missing. Idempotent: safe to
+ *  call on every startup. SQLite has no `ADD COLUMN IF NOT EXISTS`, so we probe
+ *  `PRAGMA table_info` first. */
+function ensureColumn(reg, table, column, definition) {
+  const cols = reg.prepare(`PRAGMA table_info(${table})`).all();
+  if (cols.some((c) => c.name === column)) return;
+  reg.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition};`);
+}
+
 /** Registry metadata table (not the per-board `boards` content row). */
 export function createRegistrySchema(reg = getRegistry()) {
   reg.exec(`
@@ -120,6 +129,10 @@ export function createRegistrySchema(reg = getRegistry()) {
     );
     CREATE INDEX IF NOT EXISTS idx_registry_boards_repo_path ON boards(repo_path);
   `);
+  // Whether Orbit keeps SKILL-ORBIT.md / AGENTS.md in sync inside repo_path.
+  // Defaults to 1 so pre-existing boards (created when files were always
+  // written) keep their managed copies refreshed on startup.
+  ensureColumn(reg, "boards", "manage_helper_files", "INTEGER NOT NULL DEFAULT 1");
 }
 
 /** Full Kanban schema on a per-board database connection. */

package/src/core/migrate.js

@@ -178,7 +178,7 @@ export function migrateInRepoBoards() {
     console.error(`\n[orbit] ⚠ Could not auto-migrate ${n} board${n > 1 ? "s" : ""} to central storage.`);
     console.error(`${sep} These boards continue to work from their current paths.`);
     console.error(`${sep} To complete the migration manually, run the commands below and`);
-    console.error(`${sep} restart orbit serve:\n`);
+    console.error(`${sep} restart orbit run:\n`);
     for (const r of failed) {
       const slash = process.platform === "win32" ? "\\" : "/";
       const destDir = dirname(r.newPath).replace(/\//g, slash);

package/src/core/paths.js

@@ -22,7 +22,7 @@ export const EXPORT_DIR = join(DATA_DIR, "exports");
 export const BACKUP_DIR = join(DATA_DIR, "backups");
 /** Central directory for dispatch run artifacts: DATA_DIR/dispatch-runs/<board-slug>/<run-id>/ */
 export const DISPATCH_RUNS_DIR = join(DATA_DIR, "dispatch-runs");
-export const PORT = Number(process.env.PORT || 3337);
+export const PORT = Number(process.env.PORT || 13701);
 
 mkdirSync(DATA_DIR, { recursive: true });
 mkdirSync(BOARDS_DIR, { recursive: true });

package/src/core/registry.js

@@ -60,8 +60,8 @@ export function insertBoard(row) {
   const t = row.created_at || now();
   getRegistry()
     .prepare(
-      `INSERT INTO boards (id, slug, name, repo_path, db_path, repo_url, default_branch, last_active_at, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      `INSERT INTO boards (id, slug, name, repo_path, db_path, repo_url, default_branch, manage_helper_files, last_active_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     )
     .run(
       row.id,
@@ -71,6 +71,7 @@ export function insertBoard(row) {
       row.db_path,
       row.repo_url || "",
       row.default_branch || "main",
+      row.manage_helper_files === undefined ? 1 : row.manage_helper_files ? 1 : 0,
       row.last_active_at || t,
       t,
       row.updated_at || t
@@ -80,7 +81,7 @@ export function insertBoard(row) {
 export function updateBoardMeta(boardId, patch) {
   const sets = [];
   const vals = [];
-  for (const k of ["slug", "name", "repo_path", "db_path", "repo_url", "default_branch"]) {
+  for (const k of ["slug", "name", "repo_path", "db_path", "repo_url", "default_branch", "manage_helper_files"]) {
     if (patch[k] !== undefined) {
       sets.push(`${k} = ?`);
       vals.push(patch[k]);

package/src/server.js

@@ -40,8 +40,30 @@ const server = createServer(async (req, res) => {
   }
 });
 
-const summary = startupSummary();
-server.listen(boardRuntime.port, () => {
+const requestedPort = boardRuntime.port;
+const hasExplicitPort = Boolean(process.env.PORT);
+const maxAutoPort = requestedPort + 99;
+let currentPort = requestedPort;
+
+server.on("error", (error) => {
+  if (!hasExplicitPort && error?.code === "EADDRINUSE" && currentPort < maxAutoPort) {
+    currentPort += 1;
+    console.warn(`[orbit] Port ${currentPort - 1} is in use; trying ${currentPort}.`);
+    server.listen(currentPort);
+    return;
+  }
+
+  console.error(error);
+  closeAllConnections();
+  process.exit(1);
+});
+
+server.listen(currentPort);
+
+server.on("listening", () => {
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : currentPort;
+  const summary = startupSummary(port);
   console.log(`Starscape Orbit listening on ${summary.url}`);
   console.log(`Registry: ${summary.registryPath}`);
   console.log(`Boards (${summary.boardCount}):`);