sdocs-dev 1.6.1 → 1.12.0

package/lib/agent-block.js

@@ -0,0 +1,245 @@
+// Pure data model for the SmallDocs agent integration block.
+//
+// IMPORTANT: keep AGENT_BLOCK_BODY in sync with the per-agent setup
+// snippets in public/sdoc.md (the "Set up your agent" section). If you
+// reword one, reword the other.
+//
+// Release checklist when AGENT_BLOCK_BODY changes:
+//   1. Bump AGENT_BLOCK_VERSION below.
+//   2. Set AGENT_BLOCK_REASON to a one-line summary of what changed.
+//   3. Prepend a new section to public/agent-changes.md.
+//   4. Reword public/sdoc.md per-agent snippets to match.
+//
+// This module also owns the on-disk schema for ~/.sdocs/setup.json
+// (read/write/migrate). The tests cover both the block format and the
+// state migration, so they live together as one cohesive module.
+
+const fs   = require('fs');
+const path = require('path');
+const { SETUP_CACHE } = require('./constants');
+
+const AGENT_BLOCK_VERSION = 10;
+const AGENT_BLOCK_REASON  = 'Documents `sdoc bridge file.md`: a live editing session for iterating on a file with the user (browser edits autosave to disk, file edits push to the page). Notes that it parks the terminal so it should run in the background, and that the browser asks for local-process / "Apps on device" permission the user must accept. Reframes plain `sdoc file.md` as the default way to open a file for comfortable reading or quick sharing. Renames the block heading from SDocs to SmallDocs, the project\'s new name and home, and spells out that "sdoc it" / "sdoc me the plan" / "make me a smalldoc" all mean: write the .md and open it with sdoc.';
+
+const AGENT_BLOCK_BODY = `## SmallDocs
+
+The \`sdoc\` CLI (\`sdoc path/to/file.md\`) is installed globally and renders local Markdown files securely in the browser (at https://smalldocs.org) in a way that's comfortable for your user to read and share. Nothing hits a server unless the user explicitly saves the file to the SmallDocs cloud or runs \`sdoc share\`.
+
+When the user says "sdoc it", "sdoc me the plan", or asks for a smalldoc, they mean this: write (or locate) the \`.md\` file and open it with \`sdoc\`.
+
+Use it (or offer it) when the user wants to read, share, or export a \`.md\` file, or when a styled / interactive artifact will land harder than chat prose. Skip it for quick Q&A that already fits in a reply - SmallDocs adds friction without value when there's no document, no rendering opportunity, and nothing to share.
+
+### Basic \`sdoc\` usage
+
+- \`sdoc file.md\` - the default way to open a file, for comfortable reading or quick sharing.
+- \`sdoc bridge file.md\` - open a live editing session while you iterate on a file with the user: edits in the browser autosave to the file on disk, and your edits to the file push to the open page. It parks the terminal until the tab closes, so run it in the background when you want to keep working. The first time the page connects, the browser asks to reach a local process (Chrome calls this "Apps on device" / Local Network Access) - the user has to accept, or the page stays read-only. Reach for this when you and the user are working a file back and forth, not for a one-off open.
+- \`sdoc library\` - opens a library view in the browser. SmallDocs automatically indexes every \`.md\` under the user's home directory; filter by directory, date, or tags (the index doesn't search file content - fall back to \`grep\` for that). Opt out per-directory with \`.sdocsignore\` or per-file with \`sdocs-library: false\` in front matter. (\`sdoc library --help\` for the full reference.)
+- \`sdoc file.md +tag1 +tag2\` - open the file and inject tags into its YAML front matter which persist. The \`+\` prefix is shell-safe. Tag files when they're worth rediscovering - the library filters by tag, not by content.
+- \`sdoc library ls --tags\` - print the tags (tag - count) for the current project directory. If you think you might tag the file, run this first so you reuse the project's existing tag vocabulary instead of inventing parallel ones.
+- \`sdoc share file.md\` - copy an encrypted short URL to the clipboard for sending to someone else. The link decrypts in the recipient's browser; the server only sees ciphertext. The agent can't actually deliver - paste the link into wherever the user talks to that person.
+- \`sdoc --help\` - full reference.
+
+### SmallDocs expands what you can create with Markdown
+
+SmallDocs uses the browser to extend what Markdown can be: a styled doc, a chart, a diagram, a slide deck, or an interactive form whose answers come back to you. Reach for one of these when a visual or interactive artifact will land harder than prose - not as a default for every reply. To create something new, write the \`.md\` file first, then \`sdoc path/to/file.md\`.
+
+Each command below prints its reference when run with no arguments - run it before writing the matching fenced block. The JSON / DSL shapes are specific and easy to get wrong from memory.
+
+- \`sdoc charts\` - rendering inline charts (\`\`\`chart blocks)
+- \`sdoc diagrams\` - rendering inline Mermaid diagrams (\`\`\`mermaid blocks; has full-screen mode for zoom). Reach for this when drawing system or architectural diagrams (sequence, flow, component layout) - a diagram often communicates the shape of something faster than the equivalent prose.
+- \`sdoc slides\` - inline slide decks (\`\`\`slide / ~~~slide blocks; has full-screen presentation mode). Slides can be standalone exported as \`.pdf\` or \`.pptx\`. \`sdoc present file.md\` - open file directly in fullscreen presentation mode.
+- \`sdoc cells\` - rendering spreadsheets (\`\`\`cells blocks): CSV rows where plain values and =formulas (SUM, AVERAGE, IF, ROUND...) sit in the same grid and compute live. The reader can sort, select ranges for quick stats, edit a scratch copy fullscreen, and download the sheet as Excel (.xlsx) with the formulas still working. Reach for this when handing the user numbers they will want to check or play with - totals, budgets, projections. \`sdoc report.csv\` opens a CSV file directly as a sheet.
+- \`sdoc schema\` - styling Markdown (fonts, colors, spacing). The default styles are already comfortable to read; reach for this only when they aren't enough - client-facing polish or a bit of fun.
+- \`sdoc feedback\` - rendering interactive elements (\`\`\`form blocks) to receive structured input from the user. Run \`sdoc feedback file.md\` and the user's submission lands as a JSON line on stdout. Good for eliciting complex/subtle feedback. All standard interactive HTML elements with prefilled (but editable) content of your choosing.
+`;
+
+const AGENT_BLOCK_START_PREFIX = '<!-- sdocs-agent-block:start v=';
+const AGENT_BLOCK_START_RE     = /<!-- sdocs-agent-block:start v=(\d+) -->/;
+const AGENT_BLOCK_END_MARKER   = '<!-- sdocs-agent-block:end -->';
+const AGENT_BLOCK_LEGACY_OPEN  = '<!-- sdocs-agent-block -->';
+
+// `detectDir` (optional) is the directory whose existence signals "this agent
+// is installed". It defaults to `dir`. pi keeps its global instructions one
+// level down (`~/.pi/agent/AGENTS.md`), so we detect on the parent `~/.pi`
+// the installer creates and let writeBookendedBlock mkdir the `agent` subdir.
+const AGENT_TARGETS = [
+  { name: 'Claude Code', dir: '.claude',                file: 'CLAUDE.md'  },
+  { name: 'Codex',       dir: '.codex',                 file: 'AGENTS.md'  },
+  { name: 'Gemini CLI',  dir: '.gemini',                file: 'GEMINI.md'  },
+  { name: 'opencode',    dir: path.join('.config', 'opencode'), file: 'AGENTS.md' },
+  { name: 'pi',          dir: path.join('.pi', 'agent'), file: 'AGENTS.md', detectDir: '.pi' },
+  { name: 'CodeWhale',   dir: '.codewhale',             file: 'AGENTS.md'  },
+];
+
+function formatAgentBlock(version, body) {
+  return `${AGENT_BLOCK_START_PREFIX}${version} -->\n${body}${AGENT_BLOCK_END_MARKER}\n`;
+}
+
+// Find a current bookended block. Returns { start, end, version, body } | null.
+// Bails on ambiguity (multiple start markers).
+function findBookendedBlock(content) {
+  const startMatch = AGENT_BLOCK_START_RE.exec(content);
+  if (!startMatch) return null;
+  const startIdx = startMatch.index;
+  const startLineEnd = content.indexOf('\n', startIdx);
+  if (startLineEnd < 0) return null;
+  const endIdx = content.indexOf(AGENT_BLOCK_END_MARKER, startLineEnd);
+  if (endIdx < 0) return null;
+  const endMarkerEnd = endIdx + AGENT_BLOCK_END_MARKER.length;
+  const trailingNewline = content[endMarkerEnd] === '\n' ? 1 : 0;
+  const second = content.indexOf(AGENT_BLOCK_START_PREFIX, endMarkerEnd);
+  if (second >= 0) return null;
+  return {
+    start: startIdx,
+    end: endMarkerEnd + trailingNewline,
+    version: parseInt(startMatch[1], 10),
+    body: content.slice(startLineEnd + 1, endIdx),
+  };
+}
+
+// Find a legacy open-only block (1.4.x format). Returns { start, end, version } | null.
+// Only matches bodies whose terminator is the JoshInLisbon URL line, which is the
+// known shape of v1 (1.4.0/1.4.1) and v2 (1.4.2). Hand-edited bodies return null.
+function findLegacyBlock(content) {
+  const idx = content.indexOf(AGENT_BLOCK_LEGACY_OPEN);
+  if (idx < 0) return null;
+  const second = content.indexOf(AGENT_BLOCK_LEGACY_OPEN, idx + AGENT_BLOCK_LEGACY_OPEN.length);
+  if (second >= 0) return null;
+  const terminator = 'Source: https://github.com/JoshInLisbon/SDocs\n';
+  const termIdx = content.indexOf(terminator, idx);
+  if (termIdx < 0) return null;
+  const blockEnd = termIdx + terminator.length;
+  const region = content.slice(idx, blockEnd);
+  // Heuristic to recover from-version: v2 added the copy-code line, v1 didn't.
+  const version = region.includes('Also handy for copying specific code') ? 2 : 1;
+  return { start: idx, end: blockEnd, version };
+}
+
+// Pure: takes content, returns refresh result.
+//   { changed: false, reason: 'absent'|'current'|'newer'|'hand_edited' }
+//   { changed: true, content, fromVersion, toVersion }
+function refreshContent(content) {
+  const bookended = findBookendedBlock(content);
+  if (bookended) {
+    if (bookended.version === AGENT_BLOCK_VERSION) {
+      return { changed: false, reason: 'current' };
+    }
+    if (bookended.version > AGENT_BLOCK_VERSION) {
+      return { changed: false, reason: 'newer' };
+    }
+    return {
+      changed: true,
+      content: content.slice(0, bookended.start)
+             + formatAgentBlock(AGENT_BLOCK_VERSION, AGENT_BLOCK_BODY)
+             + content.slice(bookended.end),
+      fromVersion: bookended.version,
+      toVersion: AGENT_BLOCK_VERSION,
+    };
+  }
+  const legacy = findLegacyBlock(content);
+  if (!legacy) {
+    return { changed: false, reason: content.includes(AGENT_BLOCK_LEGACY_OPEN) ? 'hand_edited' : 'absent' };
+  }
+  return {
+    changed: true,
+    content: content.slice(0, legacy.start)
+           + formatAgentBlock(AGENT_BLOCK_VERSION, AGENT_BLOCK_BODY)
+           + content.slice(legacy.end),
+    fromVersion: legacy.version,
+    toVersion: AGENT_BLOCK_VERSION,
+  };
+}
+
+function compareVersions(a, b) {
+  const A = String(a || '0.0.0').split('.').map(n => parseInt(n, 10) || 0);
+  const B = String(b || '0.0.0').split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((A[i] || 0) > (B[i] || 0)) return 1;
+    if ((A[i] || 0) < (B[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+// ── Setup state (~/.sdocs/setup.json) ───────────────────────
+
+const SETUP_SCHEMA_VERSION = 1;
+
+// Pre-1.5.0 setup.json had no `schemaVersion`. Existing users wrote the block
+// (so they want it kept current) but were never asked about auto-install.
+function migrateSetupState(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  if (raw.schemaVersion === SETUP_SCHEMA_VERSION) return raw;
+  if (raw.schemaVersion && raw.schemaVersion > SETUP_SCHEMA_VERSION) {
+    return null;
+  }
+  if (!raw.setupCompleted) return null;
+  return {
+    schemaVersion: SETUP_SCHEMA_VERSION,
+    setupCompleted: raw.setupCompleted,
+    writtenTo: raw.writtenTo || [],
+    declined: !!raw.declined,
+    autoRefreshAgentFiles: !raw.declined,
+    autoInstallUpdates: false,
+    lastRunVersion: null,
+  };
+}
+
+function readSetupState() {
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(SETUP_CACHE, 'utf-8')); }
+  catch (_) { return null; }
+  if (raw && raw.schemaVersion === SETUP_SCHEMA_VERSION) return raw;
+  const migrated = migrateSetupState(raw);
+  if (migrated) {
+    writeSetupState(migrated);
+    return migrated;
+  }
+  return null;
+}
+
+function writeSetupState(state) {
+  try {
+    fs.mkdirSync(path.dirname(SETUP_CACHE), { recursive: true });
+    const payload = { schemaVersion: SETUP_SCHEMA_VERSION, ...state };
+    payload.schemaVersion = SETUP_SCHEMA_VERSION;
+    fs.writeFileSync(SETUP_CACHE, JSON.stringify(payload, null, 2));
+  } catch (_) {}
+}
+
+// Pure: given a batch of refresh results plus the current binary version,
+// decide whether a missing setup.json should be lazily populated. Returns the
+// state object to write, or null to leave state untouched.
+function implicitConsentState(results, version, now = new Date()) {
+  const changed = results.filter(r => r.changed);
+  if (changed.length === 0) return null;
+  if (results.some(r => r.error)) return null;
+  return {
+    setupCompleted: now.toISOString(),
+    writtenTo: changed.map(r => r.path),
+    declined: false,
+    autoRefreshAgentFiles: true,
+    autoInstallUpdates: false,
+    lastRunVersion: version,
+  };
+}
+
+module.exports = {
+  AGENT_BLOCK_VERSION,
+  AGENT_BLOCK_REASON,
+  AGENT_BLOCK_BODY,
+  AGENT_BLOCK_START_PREFIX,
+  AGENT_BLOCK_START_RE,
+  AGENT_BLOCK_END_MARKER,
+  AGENT_BLOCK_LEGACY_OPEN,
+  AGENT_TARGETS,
+  SETUP_SCHEMA_VERSION,
+  formatAgentBlock,
+  findBookendedBlock,
+  findLegacyBlock,
+  refreshContent,
+  compareVersions,
+  migrateSetupState,
+  readSetupState,
+  writeSetupState,
+  implicitConsentState,
+};

package/lib/agent-files.js

@@ -0,0 +1,162 @@
+// Per-file refresh of the SDocs agent block.
+//
+// Operates on AGENT_TARGETS in $HOME. Atomic writes via tmp + rename,
+// short-lived exclusive locks to avoid two `sdoc` runs stomping on each
+// other, and a backup file beside each agent file before we modify it.
+// Symlinks are skipped unless explicitly followed.
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const {
+  AGENT_BLOCK_VERSION,
+  AGENT_BLOCK_BODY,
+  AGENT_BLOCK_LEGACY_OPEN,
+  AGENT_TARGETS,
+  formatAgentBlock,
+  findBookendedBlock,
+  refreshContent,
+} = require('./agent-block');
+
+const { AGENT_CHANGES_URL } = require('./constants');
+
+function detectAgents() {
+  const home = os.homedir();
+  return AGENT_TARGETS
+    .map(t => ({ ...t, dirPath: path.join(home, t.detectDir || t.dir), filePath: path.join(home, t.dir, t.file) }))
+    .filter(t => fs.existsSync(t.dirPath));
+}
+
+function fileHasBlock(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return findBookendedBlock(content) !== null
+        || content.includes(AGENT_BLOCK_LEGACY_OPEN);
+  } catch (_) { return false; }
+}
+
+function isSymlink(filePath) {
+  try { return fs.lstatSync(filePath).isSymbolicLink(); }
+  catch (_) { return false; }
+}
+
+// Atomic write: tmp file in the SAME directory (so rename can't hit EXDEV),
+// then rename. Cleans up the tmp on any error.
+function atomicWrite(filePath, content) {
+  const dir  = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tmp  = path.join(dir, `.${base}.sdocs.tmp.${process.pid}.${Date.now()}`);
+  fs.writeFileSync(tmp, content);
+  try { fs.renameSync(tmp, filePath); }
+  catch (e) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw e;
+  }
+}
+
+function backupFile(filePath) {
+  try {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    fs.copyFileSync(filePath, `${filePath}.sdocs.bak.${stamp}`);
+  } catch (_) {}
+}
+
+// Best-effort exclusive lock. Returns a release function or null on contention.
+// Stale locks (>60s) are reaped.
+function acquireLock(filePath) {
+  const lockPath = `${filePath}.sdocs.lock`;
+  try {
+    const fd = fs.openSync(lockPath, 'wx');
+    try { fs.writeSync(fd, String(process.pid)); } catch (_) {}
+    fs.closeSync(fd);
+    return () => { try { fs.unlinkSync(lockPath); } catch (_) {} };
+  } catch (e) {
+    if (e.code !== 'EEXIST') return null;
+    try {
+      const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+      if (age > 60000) {
+        fs.unlinkSync(lockPath);
+        return acquireLock(filePath);
+      }
+    } catch (_) {}
+    return null;
+  }
+}
+
+function writeBookendedBlock(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const block = formatAgentBlock(AGENT_BLOCK_VERSION, AGENT_BLOCK_BODY);
+  if (!fs.existsSync(filePath)) {
+    atomicWrite(filePath, block);
+    return;
+  }
+  const existing = fs.readFileSync(filePath, 'utf-8');
+  const prefix = existing.endsWith('\n') ? '\n' : '\n\n';
+  atomicWrite(filePath, existing + prefix + block);
+}
+
+// Refresh a single agent file.
+// Returns { path, name?, changed, fromVersion?, toVersion?, reason?, error? }.
+function refreshAgentFile(filePath, opts = {}) {
+  if (!fs.existsSync(filePath))                    return { path: filePath, changed: false, reason: 'absent' };
+  if (isSymlink(filePath) && !opts.followSymlinks) return { path: filePath, changed: false, reason: 'symlink' };
+
+  const release = acquireLock(filePath);
+  if (!release)                                    return { path: filePath, changed: false, reason: 'locked' };
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const result  = refreshContent(content);
+    if (!result.changed) return { path: filePath, changed: false, reason: result.reason };
+    backupFile(filePath);
+    atomicWrite(filePath, result.content);
+    return {
+      path: filePath, changed: true,
+      fromVersion: result.fromVersion, toVersion: result.toVersion,
+    };
+  } catch (e) {
+    return { path: filePath, changed: false, error: e.message };
+  } finally {
+    release();
+  }
+}
+
+function refreshAllAgentFiles(opts = {}) {
+  const home = os.homedir();
+  return AGENT_TARGETS.map(t => {
+    const filePath = path.join(home, t.dir, t.file);
+    return { name: t.name, ...refreshAgentFile(filePath, opts) };
+  });
+}
+
+function printRefreshSummary(results) {
+  const changed = results.filter(r => r.changed);
+  if (changed.length > 0) {
+    const n = changed.length;
+    console.log(`✓ SDocs agent block updated to v${AGENT_BLOCK_VERSION} in ${n} ${n === 1 ? 'file' : 'files'}`);
+    console.log(`  Changes: ${AGENT_CHANGES_URL}#v${AGENT_BLOCK_VERSION}`);
+  }
+  for (const r of results.filter(r => r.error)) {
+    console.log(`! ${r.path}: ${r.error}`);
+  }
+  for (const r of results.filter(r => r.reason === 'symlink')) {
+    console.log(`! ${r.path}: symlink, skipped (run \`sdoc setup --follow-symlinks\` to follow)`);
+  }
+  for (const r of results.filter(r => r.reason === 'hand_edited')) {
+    console.log(`! ${r.path}: local edits detected, run \`sdoc setup\` to refresh manually`);
+  }
+}
+
+module.exports = {
+  detectAgents,
+  fileHasBlock,
+  isSymlink,
+  atomicWrite,
+  backupFile,
+  acquireLock,
+  writeBookendedBlock,
+  refreshAgentFile,
+  refreshAllAgentFiles,
+  printRefreshSummary,
+};

package/lib/bridge-commands.js

@@ -0,0 +1,171 @@
+// CLI bridge integration. Two entry points:
+//
+//   - `runBridgedOpen(opts)`  — invoked by the default `sdoc <file>` handler
+//     when a file path is present. Starts a bridge in 'open' mode so the
+//     browser is connected to the live file on disk. Closing the tab exits 0.
+//
+//   - `feedbackCommand(opts)` — `sdoc feedback FILE [--message "..."]`.
+//     Starts a bridge in 'feedback' mode. The browser shows a Done button and
+//     the optional message as a banner above the document. Done exits 0,
+//     closing the tab without Done exits 2, no browser within the connect
+//     timeout exits 3.
+//
+// Both go through `runBridge` so the timeout flags, signal handling, and
+// terminal-bound await are shared.
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const { startBridge } = require('../bin/sdocs-bridge');
+const { DEFAULT_URL } = require('./constants');
+const { openBrowser } = require('./io');
+const { stripAndCompress } = require('./url');
+
+function baseUrlFor(opts) {
+  return opts.url || process.env.SDOCS_URL || DEFAULT_URL;
+}
+
+// Wrapped files (.csv, .mmd, .mermaid) render a derived view the bridge builds
+// on connect, not the raw bytes, so we don't embed a static snapshot for them -
+// they keep the pre-existing connect-or-blank behaviour. Everything else gets a
+// `md=` snapshot so the page renders read-only before the socket connects and
+// falls back to read-only if it never does.
+const WRAPPED_EXT = new Set(['.csv', '.mmd', '.mermaid']);
+
+// The compressed `md=` snapshot for the bridged file, or null when we can't /
+// shouldn't embed one (wrapped file, unreadable, etc.). Failure is non-fatal:
+// without `md=` the page just behaves as it did before this change.
+function bridgeSnapshot(file) {
+  if (!file) return null;
+  if (WRAPPED_EXT.has(path.extname(file).toLowerCase())) return null;
+  try {
+    return stripAndCompress(fs.readFileSync(file, 'utf-8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function buildBridgeUrl(opts, bridge) {
+  const base = baseUrlFor(opts);
+  const params = new URLSearchParams();
+  params.set('bridge', '127.0.0.1:' + bridge.port);
+  params.set('token',  bridge.token);
+  if (opts.file) params.set('file', path.basename(opts.file));
+  // Progressive enhancement: embed the document so the page can render it
+  // (read-only) before the live socket connects, and fall back to it if the
+  // socket never does, instead of showing a blank page.
+  const snapshot = bridgeSnapshot(opts.file);
+  if (snapshot) params.set('md', snapshot);
+  // `sdoc present <file>` triggers fullscreen slide view on load.
+  if (opts.present) params.set('present', '0');
+  return base + '/#' + params.toString();
+}
+
+// Resolve timeout flags into the bridge's millisecond API. Negative or NaN
+// inputs throw — better to fail loudly than silently disable a guard.
+function timeoutOpts(opts) {
+  const out = {};
+  if (opts.connectTimeoutS != null) {
+    if (!Number.isFinite(opts.connectTimeoutS) || opts.connectTimeoutS < 0) {
+      throw new Error('--connect-timeout must be a non-negative number of seconds (0 = wait forever)');
+    }
+    out.noConnectTimeoutMs = Math.round(opts.connectTimeoutS * 1000);
+  }
+  if (opts.idleTimeoutS != null) {
+    if (!Number.isFinite(opts.idleTimeoutS) || opts.idleTimeoutS < 0) {
+      throw new Error('--idle-timeout must be a non-negative number of seconds (0 = off)');
+    }
+    out.idleTimeoutMs = Math.round(opts.idleTimeoutS * 1000);
+  }
+  if (opts.reconnectGraceMs != null) {
+    if (!Number.isFinite(opts.reconnectGraceMs) || opts.reconnectGraceMs < 0) {
+      throw new Error('--reconnect-grace must be a non-negative number of milliseconds');
+    }
+    out.reconnectGraceMs = opts.reconnectGraceMs;
+  }
+  return out;
+}
+
+async function runBridge(opts, mode, label) {
+  if (!opts.file) {
+    // `sdoc feedback` (no args) prints the form DSL reference. Other
+    // bridge commands still require a file.
+    if (mode === 'feedback') {
+      const { FORM_DSL_REFERENCE } = require('./constants');
+      process.stdout.write(FORM_DSL_REFERENCE);
+      process.exit(0);
+    }
+    console.error('sdoc: ' + (opts.subcommand || 'open') + ' needs a file path');
+    process.exit(1);
+  }
+
+  let bridge;
+  try {
+    bridge = await startBridge(Object.assign(
+      { files: [opts.file], mode },
+      mode === 'feedback' && opts.messageText ? { message: opts.messageText } : {},
+      opts.keepOpenFlag ? { keepOpen: true } : {},
+      opts.logFile         ? { logFile: opts.logFile } : {},
+      timeoutOpts(opts),
+    ));
+  } catch (e) {
+    console.error('sdoc: could not start bridge -', e.message);
+    process.exit(1);
+  }
+
+  const url = buildBridgeUrl(opts, bridge);
+  const onSignal = () => { bridge.close(); };
+  process.on('SIGINT',  onSignal);
+  process.on('SIGTERM', onSignal);
+
+  openBrowser(url);
+  // Startup chatter goes to stderr so stdout stays a clean event
+  // channel (one JSON line per submit) in --keep-open mode.
+  console.error(`${label} ${path.basename(opts.file)} in browser. Close the tab or press Ctrl-C to stop.`);
+
+  // Loud warning if the parent isn't going to notice the submit. The
+  // form's whole protocol assumes the spawning agent waits for this
+  // process to exit. If stdout isn't a TTY AND we're in feedback mode,
+  // the caller is probably an agent harness - flag the wrong shape
+  // (shell `&` fire-and-forget) before the user wastes time filling in
+  // a form whose answer no one's listening for.
+  if (mode === 'feedback' && !process.stdout.isTTY) {
+    console.error(
+      'sdoc feedback: stdout is not a TTY. If your agent harness uses\n' +
+      '  shell `&` to background this process, the parent will NOT be\n' +
+      '  notified when the user submits. Use your harness\'s\n' +
+      '  run-in-background primitive instead (e.g. Claude Code\'s Bash\n' +
+      '  `run_in_background: true` flag), or run foreground and capture\n' +
+      '  stdout directly. See `sdoc feedback` (no args) for details.'
+    );
+  }
+
+  const result = await bridge.awaitTerminal();
+  process.off('SIGINT',  onSignal);
+  process.off('SIGTERM', onSignal);
+
+  if (result.kind === 'no-connect') {
+    console.error('sdoc: no browser connected within the connect timeout.');
+  } else if (result.kind === 'cancel') {
+    console.error('sdoc: cancelled (tab closed without clicking Done).');
+  } else if (result.kind === 'submit') {
+    // Belt-and-braces confirmation on stderr. The submit JSON already
+    // went to stdout (clean event channel); this line is for harnesses
+    // that merge stderr/stdout to a single log and need a human-
+    // readable "yes the submit happened, look in stdout" marker.
+    console.error('sdoc feedback: submission received - JSON line on stdout, exiting 0.');
+  }
+  process.exit(result.code || 0);
+}
+
+function runBridgedOpen(opts)   { return runBridge(opts, 'open',     'Open'); }
+function feedbackCommand(opts)  { return runBridge(opts, 'feedback', 'Feedback on'); }
+
+module.exports = {
+  runBridgedOpen,
+  feedbackCommand,
+  buildBridgeUrl, // for tests
+  timeoutOpts,    // for tests
+};