@dashclaw/cli 0.4.0 → 0.5.0

package/lib/up/db.js

@@ -0,0 +1,160 @@
+// cli/lib/up/db.js
+//
+// Database mode selection and provisioning for `dashclaw up`.
+//
+// Three modes:
+//   docker   — starts/reuses a `dashclaw-pg` Docker container (port 5433)
+//   embedded — downloads and runs embedded Postgres via embedded-postgres (~40 MB, first run)
+//   url      — prompts for a postgresql:// connection string from the user
+
+import { join } from 'node:path';
+import { existsSync, rmSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+// Keep this in sync with the "embedded-postgres" version in cli/package.json.
+const EMBEDDED_PG_VERSION = 'embedded-postgres@18.4.0-beta.17';
+
+export const LOCAL_DB_URL = 'postgresql://dashclaw:dashclaw@localhost:5433/dashclaw';
+
+const CONTAINER = 'dashclaw-pg';
+
+/** Returns true when the `docker` binary is available and responsive. */
+export function dockerAvailableSync() {
+  return spawnSync('docker', ['--version'], { stdio: 'ignore' }).status === 0;
+}
+
+/**
+ * Determines which database mode to use.
+ *
+ * Priority:
+ *   1. Explicit --db flag
+ *   2. Non-interactive (--yes): docker if available, otherwise embedded
+ *   3. Interactive prompt
+ *
+ * @param {object} opts
+ * @param {string|null} opts.flagDb   - explicit --db value or null
+ * @param {boolean}     opts.dockerAvailable
+ * @param {boolean}     [opts.yes]    - non-interactive mode
+ * @param {Function}    [opts.promptFn] - async (message) => string
+ * @returns {Promise<'docker'|'embedded'|'url'>}
+ */
+export async function chooseDbMode({ flagDb, dockerAvailable, yes = false, promptFn }) {
+  if (flagDb) return flagDb;
+  if (yes) return dockerAvailable ? 'docker' : 'embedded';
+
+  const lines = [
+    'Database — pick one:',
+    dockerAvailable
+      ? '  1. Docker Postgres (Docker detected)   [default]'
+      : '  1. Docker Postgres (Docker NOT detected)',
+    `  2. Embedded Postgres (no Docker needed, ~40 MB download)${dockerAvailable ? '' : '   [default]'}`,
+    '  3. I have a postgresql:// URL',
+  ];
+  const def = dockerAvailable ? '1' : '2';
+  const answer = (await promptFn(`${lines.join('\n')}\nChoice [${def}]: `)).trim() || def;
+  return { 1: 'docker', 2: 'embedded', 3: 'url' }[answer] ?? (dockerAvailable ? 'docker' : 'embedded');
+}
+
+/**
+ * Returns the docker run command that starts a local Postgres container.
+ * Mirrors the repo's docker-compose.yml: postgres:16-alpine, host port 5433,
+ * dashclaw/dashclaw/dashclaw credentials, named volume dashclaw_pgdata.
+ */
+export function dockerCommandFor() {
+  return {
+    cmd: 'docker',
+    args: [
+      'run', '-d', '--name', CONTAINER,
+      '-e', 'POSTGRES_USER=dashclaw',
+      '-e', 'POSTGRES_PASSWORD=dashclaw',
+      '-e', 'POSTGRES_DB=dashclaw',
+      '-p', '5433:5432',
+      '-v', 'dashclaw_pgdata:/var/lib/postgresql/data',
+      'postgres:16-alpine',
+    ],
+  };
+}
+
+/** Starts the dashclaw-pg container, reusing it if it already exists. */
+function dockerStartOrRun(logger) {
+  const ps = spawnSync(
+    'docker', ['ps', '-aq', '--filter', `name=^${CONTAINER}$`],
+    { encoding: 'utf8' },
+  );
+  if ((ps.stdout || '').trim()) {
+    execFileSync('docker', ['start', CONTAINER], { stdio: 'ignore' });
+  } else {
+    const { cmd, args } = dockerCommandFor();
+    execFileSync(cmd, args, { stdio: 'ignore' });
+  }
+  logger.error('[ok] Docker Postgres running (container dashclaw-pg, port 5433)');
+}
+
+/**
+ * Provisions the database according to `mode` and returns { databaseUrl, stop }.
+ *
+ * @param {object}   opts
+ * @param {'docker'|'embedded'|'url'} opts.mode
+ * @param {string}   opts.baseDir   - base dir for embedded data (e.g. ~/.dashclaw)
+ * @param {Function} [opts.promptFn] - async (message) => string (required for mode=url)
+ * @param {object}   [opts.logger]  - object with .error(); defaults to console
+ * @returns {Promise<{ databaseUrl: string, stop: () => Promise<void> }>}
+ */
+export async function provisionDatabase({ mode, baseDir, promptFn, logger = console }) {
+  if (mode === 'url') {
+    const url = (await promptFn('postgresql:// connection string: ')).trim();
+    if (!url.startsWith('postgresql://')) throw new Error('That is not a postgresql:// URL.');
+    return { databaseUrl: url, stop: async () => {} };
+  }
+
+  if (mode === 'docker') {
+    dockerStartOrRun(logger);
+    await waitForPort(5433, 30_000);
+    return { databaseUrl: LOCAL_DB_URL, stop: async () => {} };
+  }
+
+  // mode === 'embedded'
+  const { default: EmbeddedPostgres } = await import('embedded-postgres');
+  const pgDir = join(baseDir, 'pg');
+  // Record whether the data dir existed BEFORE this run.
+  // Only clean up on failure when WE created it (a pre-existing dir means
+  // a working prior install whose data we must not delete).
+  const dirPreExisted = existsSync(pgDir);
+  const pg = new EmbeddedPostgres({
+    databaseDir: pgDir,
+    user: 'dashclaw',
+    password: 'dashclaw',
+    port: 5433,
+    persistent: true,
+  });
+  try {
+    await pg.initialise();
+    await pg.start();
+  } catch (e) {
+    if (!dirPreExisted) {
+      rmSync(pgDir, { recursive: true, force: true });
+    }
+    throw new Error(
+      `Embedded Postgres (${EMBEDDED_PG_VERSION}) failed: ${e.message}. Retry with --db docker or --db url.`,
+    );
+  }
+  try { await pg.createDatabase('dashclaw'); } catch { /* already exists on resume — fine */ }
+  logger.error('[ok] Embedded Postgres running (port 5433, data in ~/.dashclaw/pg)');
+  return { databaseUrl: LOCAL_DB_URL, stop: () => pg.stop() };
+}
+
+/** Polls :port until it accepts TCP connections, or throws on timeout. */
+async function waitForPort(port, timeoutMs) {
+  const net = await import('node:net');
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const ok = await new Promise((resolve) => {
+      const s = net.connect(port, '127.0.0.1');
+      s.once('connect', () => { s.destroy(); resolve(true); });
+      s.once('error', () => resolve(false));
+    });
+    if (ok) return;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error(`Postgres did not accept connections on :${port} within ${timeoutMs / 1000}s.`);
+}

package/lib/up/fetch-app.js

@@ -0,0 +1,82 @@
+// cli/lib/up/fetch-app.js
+//
+// Version resolve + tarball fetch/extract for `dashclaw up`.
+// Fetches the latest platform version from npm and downloads the corresponding
+// GitHub release tarball, extracting it into ${baseDir}/app/${version}/.
+
+import { mkdirSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import * as tar from 'tar';
+
+const REPO = 'ucsandman/DashClaw';
+
+/**
+ * Fetch the latest published platform version from the npm registry.
+ * The `dashclaw` npm package version mirrors the platform version (unified versioning).
+ *
+ * @param {typeof fetch} fetchImpl - injectable for tests
+ * @returns {Promise<string>} semver string e.g. '4.21.0'
+ */
+export async function resolveAppVersion(fetchImpl = fetch) {
+  const res = await fetchImpl('https://registry.npmjs.org/dashclaw/latest');
+  if (!res.ok) {
+    throw new Error(`npm registry lookup failed (${res.status}) — check your network and retry.`);
+  }
+  const { version } = await res.json();
+  if (!version) throw new Error('npm registry returned no version for dashclaw.');
+  return version;
+}
+
+/**
+ * Build the GitHub codeload tarball URL for a given version tag.
+ *
+ * @param {string} version - semver string e.g. '4.21.0'
+ * @returns {string}
+ */
+export function tarballUrl(version) {
+  return `https://codeload.github.com/${REPO}/tar.gz/refs/tags/v${version}`;
+}
+
+/**
+ * Download and extract the app tarball for `version` into `${baseDir}/app/${version}`.
+ * The GitHub tarball wraps everything in a `DashClaw-<version>/` folder —
+ * strip 1 level so the app root lands directly in the target dir.
+ * Skips cleanly if the target already exists (resume case).
+ *
+ * @param {object} opts
+ * @param {string} opts.version
+ * @param {string} opts.baseDir
+ * @param {typeof fetch} opts.fetchImpl
+ * @param {{ error: (...args: any[]) => void }} opts.logger
+ * @returns {Promise<string>} absolute path to the extracted app dir
+ */
+export async function downloadAndExtract({ version, baseDir, fetchImpl = fetch, logger = console }) {
+  const target = join(baseDir, 'app', version);
+  if (existsSync(join(target, 'package.json'))) {
+    // Resume-skip: a pre-existing package.json means a prior successful extract.
+    logger.error(`[ok] App ${version} already present at ${target}`);
+    return target;
+  }
+  mkdirSync(target, { recursive: true });
+  const res = await fetchImpl(tarballUrl(version));
+  if (!res.ok || !res.body) {
+    rmSync(target, { recursive: true, force: true });
+    throw new Error(
+      `Download failed (${res.status}) for ${tarballUrl(version)} — does tag v${version} exist?`,
+    );
+  }
+  try {
+    await pipeline(Readable.fromWeb(res.body), tar.x({ cwd: target, strip: 1 }));
+    if (!existsSync(join(target, 'package.json'))) {
+      throw new Error('Extracted tarball did not contain package.json — aborting.');
+    }
+  } catch (e) {
+    rmSync(target, { recursive: true, force: true });
+    throw e;
+  }
+  // Invariant: a target dir with package.json present can only result from a
+  // successful prior extract because every failure path above removes the dir.
+  return target;
+}

package/lib/up/index.js

@@ -0,0 +1,325 @@
+// cli/lib/up/index.js
+//
+// Orchestrator for `npx dashclaw up` — composes the up/ primitives into the
+// full pipeline (fetch → deps → db → setup → build → start → connect → open),
+// checkpointed and resumable via instance.json.
+//
+// Three operating modes fall out of the same loop:
+//   fresh   — no instance.json: run every step.
+//   resume  — partial completed[]: skip done steps, continue from the first gap.
+//   boot    — all six steps done: skip everything up to start, then start+open.
+//
+// Every effect is injectable via `deps` so the orchestrator is unit-testable
+// without touching the network, Docker, or a real Next server.
+
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { STEPS, loadInstance, saveInstance, checkpoint } from './instance.js';
+import { resolveAppVersion, downloadAndExtract } from './fetch-app.js';
+import { dockerAvailableSync, chooseDbMode, provisionDatabase } from './db.js';
+import { installDeps, buildApp, startServer, waitForHealth, openBrowser } from './run.js';
+import { installClaude } from '../claude/install.js';
+import { parseUpArgs } from './args.js';
+import { ask } from '../config.js';
+
+/**
+ * Kill a process and its entire child tree. On Windows, `process.kill` only
+ * terminates the cmd.exe shell wrapper that `shell:true` spawns — taskkill /T
+ * reaches the actual Next server underneath.
+ */
+export function killTree(pid) {
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+  } else {
+    process.kill(pid);
+  }
+}
+
+/**
+ * Resolve the base state directory from parsed args.
+ * Exported so upCommand + cmdDown can unit-test the wiring without spawning.
+ */
+export function resolveBaseDir(args) {
+  return args.dir ?? join(homedir(), '.dashclaw');
+}
+
+/**
+ * Run the app's setup script in-process via spawnSync, contract:
+ *   node --import tsx scripts/setup.mjs --yes --json --database-url <url>
+ * prints EXACTLY ONE JSON line: {ok:true, apiKey, adminPassword} or
+ * {ok:false, error} with a non-zero exit. We parse the LAST stdout line.
+ *
+ * @param {object} opts
+ * @param {string} opts.appDir
+ * @param {string} opts.databaseUrl
+ * @param {object} [opts.logger]
+ * @param {Function} [opts.spawn]  injectable spawnSync for testing (default: spawnSync)
+ */
+export function runSetupScriptReal({ appDir, databaseUrl, logger = console, spawn: spawnFn = spawnSync }) {
+  logger.error('-> Running setup (migrations + first admin) ...');
+  const res = spawnFn(
+    'node',
+    [
+      '--import', 'tsx', 'scripts/setup.mjs',
+      '--yes', '--json', '--database-url', databaseUrl,
+      // The orchestrator owns install (step 2) and build (step 5); skip them
+      // inside setup.mjs to avoid doing both twice on a fresh install.
+      '--skip-install', '--skip-build',
+    ],
+    // stdin MUST be 'ignore': the default open pipe makes any stray readline
+    // prompt in the child hang forever (observed: 12-minute silent hang).
+    { cwd: appDir, encoding: 'utf8', shell: process.platform === 'win32', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const stdout = res.stdout || '';
+  const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+  let parsed = null;
+  if (lines.length) {
+    try { parsed = JSON.parse(lines[lines.length - 1]); } catch {
+      throw new Error(`Setup output was not parseable JSON. Last line: ${lines[lines.length - 1]}`);
+    }
+  }
+  if (res.status !== 0 || parsed?.ok === false) {
+    const detail = parsed?.error
+      || (res.stderr || '').slice(-2000).trim()
+      || `setup exited ${res.status}`;
+    throw new Error(`Setup failed: ${detail}`);
+  }
+  if (!parsed) throw new Error('Setup produced no parseable JSON output.');
+  return parsed;
+}
+
+/** Default process-liveness probe: signal 0 succeeds iff the pid exists. */
+export function defaultProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+/** The real effect wiring — swapped wholesale by tests. */
+export function realDeps() {
+  return {
+    resolveAppVersion,
+    downloadAndExtract,
+    installDeps,
+    chooseDbMode,
+    provisionDatabase,
+    runSetupScript: runSetupScriptReal,
+    buildApp,
+    startServer,
+    waitForHealth,
+    installClaude,
+    openBrowser,
+    promptFn: ask,
+    logger: console,
+    dockerAvailable: dockerAvailableSync(),
+    processAlive: defaultProcessAlive,
+  };
+}
+
+/**
+ * Run (or resume, or boot) a local DashClaw instance.
+ *
+ * @param {object} opts
+ * @param {object} opts.args      parsed up args (yes, noBrowser, db, port, sourceDir, update)
+ * @param {string} [opts.baseDir] state + data dir (default ~/.dashclaw)
+ * @param {object} [opts.deps]    injected effects (default realDeps())
+ * @returns {Promise<{ child, stopDb, baseUrl, reusedServer }>}
+ */
+export async function runUp({ args, baseDir = join(homedir(), '.dashclaw'), deps = realDeps() }) {
+  const { logger } = deps;
+
+  let inst = loadInstance(baseDir) ?? { completed: [] };
+  if (args.update) {
+    inst = saveInstance(baseDir, { completed: [] });
+  }
+  const done = (step) => inst.completed.includes(step);
+
+  const port = args.port ?? inst.port ?? 3000;
+  const baseUrl = `http://localhost:${port}`;
+
+  // 1. app_fetched ----------------------------------------------------------
+  let appDir = inst.appDir;
+  if (!done('app_fetched')) {
+    const version = args.sourceDir ? 'source' : await deps.resolveAppVersion();
+    appDir = args.sourceDir ?? await deps.downloadAndExtract({ version, baseDir, logger });
+    inst = saveInstance(baseDir, { version, appDir, port });
+    inst = checkpoint(baseDir, 'app_fetched');
+  }
+
+  // 2. deps_installed -------------------------------------------------------
+  if (!done('deps_installed')) {
+    deps.installDeps(appDir, logger);
+    inst = checkpoint(baseDir, 'deps_installed');
+  }
+
+  // 3. db_ready -------------------------------------------------------------
+  // provisionDatabase is idempotent and restarts a stopped DB, so we call it
+  // every run (including boot) for docker/embedded — but url-mode has no DB
+  // process to start, and re-prompting on every resume (or under --yes/non-TTY)
+  // is both wrong and hangs. Reuse the saved URL when db_ready is already
+  // checkpointed and inst.databaseUrl is set.
+  const dbMode = inst.dbMode ?? await deps.chooseDbMode({
+    flagDb: args.db, dockerAvailable: deps.dockerAvailable, yes: args.yes, promptFn: deps.promptFn,
+  });
+  const db = (dbMode === 'url' && done('db_ready') && inst.databaseUrl)
+    ? { databaseUrl: inst.databaseUrl, stop: async () => {} }
+    : await deps.provisionDatabase({ mode: dbMode, baseDir, promptFn: deps.promptFn, logger });
+  if (!done('db_ready')) {
+    inst = saveInstance(baseDir, { dbMode, databaseUrl: db.databaseUrl });
+    inst = checkpoint(baseDir, 'db_ready');
+  }
+  const databaseUrl = inst.databaseUrl ?? db.databaseUrl;
+
+  // 4. setup_done -----------------------------------------------------------
+  let apiKey = inst.apiKey;
+  if (!done('setup_done')) {
+    const out = await deps.runSetupScript({ appDir, databaseUrl, logger });
+    if (out.ok === false) throw new Error(out.error || 'Setup failed.');
+    apiKey = out.apiKey;
+    inst = saveInstance(baseDir, { apiKey });
+    // setup.mjs already prints the password once (to stderr) and writes it to
+    // .env.local; we deliberately do NOT echo it again here — no secrets twice.
+    if (out.adminPassword) {
+      logger.error('[ok] First admin created — credentials written to .env.local (printed once).');
+    }
+    inst = checkpoint(baseDir, 'setup_done');
+  }
+
+  // 5. built ----------------------------------------------------------------
+  if (!done('built')) {
+    deps.buildApp(appDir, logger);
+    inst = checkpoint(baseDir, 'built');
+  }
+
+  // 6. start (skipped when a previously-recorded server pid is still live)
+  // Without this check, a second `dashclaw up` would spawn a duplicate
+  // `next start` on the same port; the duplicate fails to bind, waitForHealth
+  // passes against the ORIGINAL, and upCommand's child.on('exit') fires
+  // immediately → stopDb → exits, orphaning the original server.
+  let child;
+  let reusedServer = false;
+  if (inst.pid && deps.processAlive(inst.pid)) {
+    try {
+      await deps.waitForHealth({ baseUrl });
+      // Original server is alive and healthy — reuse it.
+      logger.log(`[ok] Reusing server already running on :${port} (pid ${inst.pid})`);
+      child = { pid: inst.pid, on: () => {} };
+      reusedServer = true;
+    } catch {
+      // Pid alive but health check failed — fall through to a fresh start.
+    }
+  }
+  if (!reusedServer) {
+    child = deps.startServer({ appDir, port, logger });
+    inst = saveInstance(baseDir, { pid: child.pid });
+    try {
+      await deps.waitForHealth({ baseUrl });
+    } catch (e) {
+      // Health timeout: kill the orphaned server and clear the stale pid so the
+      // next `dashclaw up` doesn't try to resume a dead process.
+      try { killTree(child.pid); } catch { /* already gone */ }
+      saveInstance(baseDir, { pid: null });
+      throw e;
+    }
+  }
+  logger.log(`[ok] Server running at ${baseUrl}   (Ctrl+C stops it; \`dashclaw up\` restarts it)`);
+
+  // 7. connected ------------------------------------------------------------
+  if (!done('connected')) {
+    let connect = true;
+    if (!args.yes) {
+      const answer = (await deps.promptFn('Connect Claude Code now? [Y/n] ')).trim().toLowerCase();
+      connect = answer !== 'n' && answer !== 'no';
+    }
+    if (connect) {
+      await deps.installClaude({ endpoint: baseUrl, apiKey });
+    }
+    inst = checkpoint(baseDir, 'connected'); // declining is still a completed decision
+  }
+
+  // 8. open -----------------------------------------------------------------
+  if (!args.noBrowser) {
+    deps.openBrowser(`${baseUrl}/setup`, logger);
+  }
+  logger.log(`Done. First steps: ${baseUrl}/connect`);
+
+  return { child, stopDb: db.stop, baseUrl, reusedServer };
+}
+
+/**
+ * Stop the local instance: kill the server child (if recorded) and stop the
+ * Docker container if we started one. Embedded Postgres dies with the up
+ * process, so there is nothing to stop for that mode.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.baseDir]     state dir (default ~/.dashclaw)
+ * @param {object} [opts.logger]      logger (default console)
+ * @param {Function} [opts.kill]      injectable kill fn for testing (default killTree)
+ * @param {Function} [opts.dockerStop] injectable docker-stop fn for testing
+ */
+export async function runDown({
+  baseDir = join(homedir(), '.dashclaw'),
+  logger = console,
+  kill = killTree,
+  dockerStop = (container) => spawnSync('docker', ['stop', container], { stdio: 'ignore' }),
+} = {}) {
+  const inst = loadInstance(baseDir);
+  if (!inst) {
+    logger.log('No local DashClaw instance recorded — nothing to stop.');
+    return;
+  }
+  if (inst.pid) {
+    try {
+      kill(inst.pid);
+      logger.log(`[ok] Stopped server (pid ${inst.pid}).`);
+    } catch {
+      logger.log('Server was not running.');
+    }
+    saveInstance(baseDir, { pid: null });
+  }
+  if (inst.dbMode === 'docker') {
+    // No shell — house decision (see db.js): docker args are passed directly.
+    dockerStop('dashclaw-pg');
+    logger.log('[ok] Stopped Docker Postgres (container dashclaw-pg).');
+  }
+}
+
+/**
+ * `dashclaw up` entry point: parse args, run the pipeline, and keep the process
+ * alive until the server child exits or the user interrupts. SIGINT/SIGTERM
+ * stop the DB cleanly before exiting.
+ */
+export async function upCommand(argv) {
+  const args = parseUpArgs(argv);
+  const baseDir = resolveBaseDir(args);
+  const { child, stopDb, reusedServer } = await runUp({ args, baseDir });
+
+  let stopping = false;
+  const shutdown = async () => {
+    if (stopping) return;
+    stopping = true;
+    // Kill the server child first — on Windows the recorded pid is a cmd.exe
+    // wrapper; killTree reaches the actual Next process via taskkill /T /F.
+    // When reusing an existing server we deliberately do NOT kill it: the user
+    // did not start it in this session and Ctrl+C should only stop THIS process.
+    if (!reusedServer) {
+      try { killTree(child.pid); } catch { /* already gone */ }
+    }
+    await stopDb();
+    // Hard exit is intentional here: stopDb has resolved, and we need to
+    // ensure the process doesn't linger on SIGINT (especially on Windows where
+    // the event loop may keep running after the child exits).
+    process.exit(0); // eslint-disable-line no-process-exit
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  if (reusedServer) {
+    // The reused child stub has a no-op .on(); wait for a signal instead of an
+    // exit event that will never fire.
+    await new Promise(() => {}); // resolved only by SIGINT/SIGTERM above
+  } else {
+    await new Promise((resolve) => child.on('exit', resolve));
+    await stopDb();
+  }
+}

package/lib/up/instance.js

@@ -0,0 +1,46 @@
+// cli/lib/up/instance.js
+//
+// Checkpointed instance state for `dashclaw up`.
+//
+// ~/.dashclaw/instance.json is the resume contract: a fresh run executes steps
+// in STEPS order, checkpointing each; a re-run skips completed steps; corrupt
+// or missing state means a fresh install.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Canonical step order — the orchestrator re-runs from the first step NOT in `completed`. */
+export const STEPS = ['app_fetched', 'deps_installed', 'db_ready', 'setup_done', 'built', 'connected'];
+
+const fileFor = (dir) => join(dir, 'instance.json');
+
+/** Returns the parsed instance object, or null if missing or corrupt. */
+export function loadInstance(dir) {
+  try {
+    const raw = readFileSync(fileFor(dir), 'utf8');
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? parsed : null;
+  } catch {
+    return null; // missing or corrupt — caller treats as fresh install
+  }
+}
+
+/** Merges `data` into the existing instance (or creates it) and writes to disk. */
+export function saveInstance(dir, data) {
+  mkdirSync(dir, { recursive: true });
+  const current = loadInstance(dir) ?? { completed: [] };
+  const next = { ...current, ...data, completed: data.completed ?? current.completed ?? [] };
+  // mode 0o600: instance.json stores apiKey + possibly a postgresql:// URL with
+  // credentials. No-op on Windows; protects Linux/macOS (matches config.json).
+  writeFileSync(fileFor(dir), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  return next;
+}
+
+/** Appends `step` to `completed` (idempotent) and writes to disk. */
+export function checkpoint(dir, step) {
+  mkdirSync(dir, { recursive: true });
+  const inst = loadInstance(dir) ?? { completed: [] };
+  if (!inst.completed.includes(step)) inst.completed.push(step);
+  writeFileSync(fileFor(dir), JSON.stringify(inst, null, 2) + '\n', { mode: 0o600 });
+  return inst;
+}

package/lib/up/run.js

@@ -0,0 +1,52 @@
+// cli/lib/up/run.js
+//
+// Build, start, health-wait, and open-browser primitives for `npx dashclaw up`.
+
+import { spawn, spawnSync } from 'node:child_process';
+
+const shell = process.platform === 'win32';
+
+function npm(args, cwd, logger, runner = spawnSync) {
+  logger.error(`-> npm ${args.join(' ')}`);
+  const res = runner('npm', args, { cwd, stdio: ['ignore', 'inherit', 'inherit'], shell });
+  if (res.status !== 0) throw new Error(`npm ${args[0]} failed (exit ${res.status}). Re-run \`npx dashclaw up\` to resume from this step.`);
+}
+
+export function installDeps(appDir, logger = console, runner = spawnSync) {
+  try { npm(['ci', '--no-audit', '--no-fund'], appDir, logger, runner); }
+  catch { npm(['install', '--no-audit', '--no-fund'], appDir, logger, runner); } // lockfile mismatch fallback
+}
+
+export function buildApp(appDir, logger = console, runner = spawnSync) {
+  npm(['run', 'build'], appDir, logger, runner);
+}
+
+/** Start `next start` as a child; .env.local in appDir is loaded by Next itself. */
+export function startServer({ appDir, port, logger = console }) {
+  logger.error(`-> Starting server on :${port}`);
+  const child = spawn('npx', ['next', 'start', '-p', String(port)], {
+    cwd: appDir, stdio: ['ignore', 'inherit', 'inherit'], shell,
+  });
+  return child;
+}
+
+export async function waitForHealth({ baseUrl, fetchImpl = fetch, timeoutMs = 60_000, intervalMs = 1000 }) {
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = 'no response';
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetchImpl(`${baseUrl}/api/health`);
+      if (res.status === 200) return;
+      lastStatus = res.status;
+    } catch { lastStatus = 'connection refused'; }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(`Server health check failed: /api/health last answered ${lastStatus}. Check the server output above.`);
+}
+
+export function openBrowser(url, logger = console) {
+  const cmd = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  try { spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true }).unref(); }
+  catch { logger.error(`Open ${url} in your browser.`); }
+}