sdocs-dev 1.6.1 → 1.12.0

package/lib/io.js

@@ -0,0 +1,173 @@
+// CLI I/O helpers: argv parsing, content reading, browser opening.
+
+const fs   = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { transcludeCells, isWrappedFile, wrapForDisplay } = require('./cells-transclude');
+
+const SUBCOMMANDS = new Set([
+  'new', 'share', 'schema', 'defaults', 'help', 'version',
+  'charts', 'diagrams', 'cells', 'comments',
+  'setup', 'safe', 'auto-update', 'refresh', 'upgrade',
+  'bridge', 'feedback',
+  'slides', 'present',
+  'library',
+  'color-analysis',
+]);
+
+// CLI tag arguments are `+tag` (shell-safe, no quoting). Tags written
+// this way are injected into the file's YAML front matter at open time;
+// front matter is the only place SDocs stores tags.
+const TAG_ARG = /^\+[A-Za-z][\w-]{0,63}$/;
+
+function parseArgs(argv) {
+  const args = argv || process.argv.slice(2);
+  let file = null;
+  let extra = null;
+  let mode = null;
+  let url = null;
+  let subcommand = null;
+  let section = null;
+  let theme = null;
+  let resetFlag = false;
+  let shortFlag = false;
+  let jsonFlag = false;
+  let auditFlag = false;
+  let waitFlag = false;
+  let messageText = null;
+  let connectTimeoutS = null;
+  let idleTimeoutS = null;
+  let reconnectGraceMs = null;
+  let keepOpenFlag = false;
+  let logFile = null;
+  let tagsFlag = false;
+  let helpFlag = false;
+  let yesFlag = false;
+  const addTags = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    // `--help` before a subcommand prints the global help. After a
+    // subcommand, it is a flag the subcommand handler reads (library
+    // uses this to print its own help).
+    if (arg === '--help' || arg === '-h') {
+      if (subcommand) helpFlag = true; else subcommand = 'help';
+      continue;
+    }
+    if (arg === '--schema')               { subcommand = 'schema'; continue; }
+    if (arg === '--version' || arg === '-v' || arg === '-V') { subcommand = 'version'; continue; }
+
+    if (arg === '--write')   { mode = 'write'; continue; }
+    if (arg === '--style')   { mode = 'style'; continue; }
+    if (arg === '--raw')     { mode = 'raw';   continue; }
+    if (arg === '--read')    { mode = 'read';  continue; }
+    if (arg === '--comment') { mode = 'comment'; continue; }
+    if (arg === '--light')   { theme = 'light'; continue; }
+    if (arg === '--dark')    { theme = 'dark';  continue; }
+
+    if (arg === '--mode' || arg === '-m') {
+      mode = args[++i];
+      if (!['read', 'write', 'style', 'raw', 'comment'].includes(mode)) {
+        console.error(`sdoc: unknown mode "${mode}" — use read, write, style, raw, or comment`);
+        process.exit(1);
+      }
+      continue;
+    }
+
+    if (arg === '--url') { url = args[++i]; continue; }
+    if (arg === '--section' || arg === '-s') { section = args[++i]; continue; }
+    if (arg === '--reset') { resetFlag = true; continue; }
+    if (arg === '--short') { shortFlag = true; continue; }
+    if (arg === '--json')  { jsonFlag  = true; continue; }
+    if (arg === '--audit') { auditFlag = true; continue; }
+    if (arg === '--wait')  { waitFlag  = true; continue; }
+
+    // Note: `--mode` already owns `-m` for editor-mode selection, so the
+    // bridge message flag is `--message` with no short alias.
+    if (arg === '--message')                         { messageText      = args[++i]; continue; }
+    if (arg === '--connect-timeout')                 { connectTimeoutS  = Number(args[++i]); continue; }
+    if (arg === '--idle-timeout')                    { idleTimeoutS     = Number(args[++i]); continue; }
+    if (arg === '--reconnect-grace')                 { reconnectGraceMs = Number(args[++i]); continue; }
+    if (arg === '--keep-open')                       { keepOpenFlag     = true; continue; }
+    if (arg === '--log-file')                        { logFile          = args[++i]; continue; }
+    if (arg === '--tags')                            { tagsFlag         = true; continue; }
+    if (arg === '--yes' || arg === '-y')             { yesFlag          = true; continue; }
+
+    if (!subcommand && SUBCOMMANDS.has(arg)) {
+      subcommand = arg;
+      continue;
+    }
+
+    // Tag arguments anywhere on the command line: collected into
+    // addTags, used by the library tap to inject tags into the file's
+    // front matter at open time.
+    if (TAG_ARG.test(arg)) { addTags.push(arg.slice(1).toLowerCase()); continue; }
+
+    if (!file) { file = arg; continue; }
+    // Second positional is captured as `extra` so `sdoc slides icons heart`
+    // gets {subcommand: 'slides', file: 'icons', extra: 'heart'}.
+    if (extra === null) { extra = arg; continue; }
+  }
+
+  return {
+    file, extra, mode, url, subcommand, section, theme,
+    resetFlag, shortFlag, jsonFlag, auditFlag, waitFlag,
+    messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
+    keepOpenFlag, logFile,
+    tagsFlag, helpFlag, yesFlag,
+    addTags,
+  };
+}
+
+async function readContent(file) {
+  if (file) {
+    const resolved = path.resolve(file);
+    if (!fs.existsSync(resolved)) {
+      console.error(`sdoc: file not found: ${file}`);
+      process.exit(1);
+    }
+    let raw = fs.readFileSync(resolved, 'utf-8');
+    // .csv / .mmd / .mermaid files are wrapped in their fenced block so the
+    // renderer picks them up (a standalone .csv opens directly as a sheet).
+    // The same transform runs in the bridge for live sessions - if you change
+    // one, change the other (both call wrapForDisplay).
+    if (isWrappedFile(file)) {
+      raw = wrapForDisplay(raw, file);
+    } else {
+      // Bake any {{path/to/file.csv}} cells references into the doc, resolving
+      // paths relative to the markdown file. Self-contained docs share safely.
+      raw = transcludeCells(raw, path.dirname(resolved));
+    }
+    return raw;
+  }
+
+  if (!process.stdin.isTTY) {
+    return new Promise((resolve, reject) => {
+      let data = '';
+      process.stdin.setEncoding('utf-8');
+      process.stdin.on('data', chunk => data += chunk);
+      process.stdin.on('end', () => resolve(data));
+      process.stdin.on('error', reject);
+    });
+  }
+
+  return null; // no content — just open studio
+}
+
+function openBrowser(url) {
+  try {
+    if (process.platform === 'darwin')      execFileSync('open', [url]);
+    else if (process.platform === 'win32')  execFileSync('cmd', ['/c', 'start', '', url]);
+    else                                    execFileSync('xdg-open', [url]);
+  } catch {
+    console.log(`Open in browser: ${url}`);
+  }
+}
+
+module.exports = {
+  SUBCOMMANDS,
+  parseArgs,
+  readContent,
+  openBrowser,
+};

package/lib/library-autostart.js

@@ -0,0 +1,145 @@
+// Optional, opt-in autostart for the library agent.
+//
+// macOS: writes a LaunchAgent plist to ~/Library/LaunchAgents/ and
+// loads it via launchctl. Linux/Windows: not yet implemented; the
+// CLI prints "not supported on your platform" and exits.
+//
+// The plist points at the current Node binary plus the resolved CLI
+// script path, so the OS can spawn the agent on login without relying
+// on PATH or shell init.
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const LABEL = 'dev.sdocs.library';
+
+function launchAgentsDir() {
+  if (process.env.SDOCS_LAUNCHAGENTS_DIR) return process.env.SDOCS_LAUNCHAGENTS_DIR;
+  return path.join(os.homedir(), 'Library', 'LaunchAgents');
+}
+
+function plistPath() {
+  return path.join(launchAgentsDir(), LABEL + '.plist');
+}
+
+function logPath() {
+  if (process.env.SDOCS_HOME) return path.join(process.env.SDOCS_HOME, 'library-autostart.log');
+  return path.join(os.homedir(), '.sdocs', 'library-autostart.log');
+}
+
+function isSupported() {
+  return process.platform === 'darwin';
+}
+
+function isEnabled() {
+  if (!isSupported()) return false;
+  return fs.existsSync(plistPath());
+}
+
+// Pure: builds the plist XML from the given paths. Exported for tests.
+function buildPlist({ nodePath, scriptPath, logPath: lp }) {
+  const escape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escape(nodePath)}</string>
+    <string>${escape(scriptPath)}</string>
+    <string>library</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${escape(lp)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escape(lp)}</string>
+</dict>
+</plist>
+`;
+}
+
+// Resolve the CLI script the OS should run. process.argv[1] is the JS
+// entrypoint the user invoked. Falls back to a path relative to this
+// module if argv[1] isn't usable (e.g. test runners).
+function resolveScriptPath() {
+  const candidate = process.argv[1];
+  if (candidate && fs.existsSync(candidate)) return path.resolve(candidate);
+  return path.resolve(__dirname, '..', 'bin', 'sdocs-dev.js');
+}
+
+function writePlist() {
+  fs.mkdirSync(launchAgentsDir(), { recursive: true });
+  const content = buildPlist({
+    nodePath:   process.execPath,
+    scriptPath: resolveScriptPath(),
+    logPath:    logPath(),
+  });
+  fs.writeFileSync(plistPath(), content);
+  return plistPath();
+}
+
+function removePlist() {
+  try { fs.unlinkSync(plistPath()); } catch (_) {}
+}
+
+function launchctl(verb) {
+  if (process.env.SDOCS_AUTOSTART_DRY_RUN === '1') return { ok: true, dryRun: true };
+  try {
+    execFileSync('launchctl', [verb, plistPath()], { stdio: 'pipe' });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, message: (e.stderr ? e.stderr.toString() : e.message).trim() };
+  }
+}
+
+function enable() {
+  if (!isSupported()) {
+    return { ok: false, message: 'autostart is only supported on macOS for now.' };
+  }
+  const wrote = writePlist();
+  // Unload any prior copy so reload picks up the fresh plist if node path changed.
+  launchctl('unload');
+  const r = launchctl('load');
+  if (!r.ok) {
+    return { ok: false, message: 'wrote plist but launchctl load failed: ' + r.message };
+  }
+  return { ok: true, path: wrote };
+}
+
+function disable() {
+  if (!isSupported()) {
+    return { ok: false, message: 'autostart is only supported on macOS for now.' };
+  }
+  if (!isEnabled()) return { ok: true, alreadyDisabled: true };
+  launchctl('unload');
+  removePlist();
+  return { ok: true };
+}
+
+function status() {
+  return {
+    supported: isSupported(),
+    enabled:   isEnabled(),
+    plistPath: plistPath(),
+  };
+}
+
+module.exports = {
+  LABEL,
+  isSupported, isEnabled,
+  enable, disable, status,
+  buildPlist, plistPath, logPath, resolveScriptPath,
+};

package/lib/library-commands.js

@@ -0,0 +1,307 @@
+// CLI handlers for the `sdoc library ...` verbs and the on-open
+// indexing tap used by the default `sdoc <file>` command.
+
+const fs   = require('fs');
+const path = require('path');
+
+const store      = require('./library-store');
+const libIndex   = require('./library-index');
+const libServer  = require('./library-server');
+const autostart  = require('./library-autostart');
+const helpText   = require('./help-text');
+const { openBrowser } = require('./io');
+const { DEFAULT_URL } = require('./constants');
+const http       = require('http');
+
+function libraryEnable() {
+  const s = store.loadState();
+  s.enabled = true;
+  store.saveState(s);
+  console.log('library: enabled');
+}
+
+function libraryDisable() {
+  const s = store.loadState();
+  s.enabled = false;
+  store.saveState(s);
+  console.log('library: disabled (existing index left in place)');
+}
+
+function libraryStatus() {
+  const s = store.loadState();
+  const idx = store.loadIndex();
+  const last = s.lastScanAt ? new Date(s.lastScanAt).toISOString() : 'never';
+  console.log(`library: ${s.enabled === false ? 'disabled' : 'enabled'}`);
+  console.log(`entries: ${idx.entries.length}`);
+  console.log(`last scan: ${last}`);
+}
+
+function libraryRebuild() {
+  console.log('library: rebuilding...');
+  const result = libIndex.rebuild();
+  console.log(`library: scanned ${result.scanned}, added ${result.added}, updated ${result.updated}`);
+}
+
+// Walk up from a directory looking for `.git/`. Falls back to the start
+// directory if no repo root is found. Matches the rule the agent's
+// /api/library/project-tags endpoint uses, so CLI output is consistent
+// with what the browser shows.
+function resolveProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 30; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(startDir);
+}
+
+// Resolve the scope for `sdoc library ls`. Explicit path arg wins;
+// otherwise walk up from cwd to a git root, fall back to cwd. Returns
+// the absolute path that will be both the preamble label and the
+// prefix filter against indexed entries.
+function resolveLsScope(explicitArg) {
+  if (explicitArg) {
+    const abs = path.resolve(explicitArg);
+    if (!fs.existsSync(abs)) {
+      console.error(`sdoc library ls: path not found: ${explicitArg}`);
+      process.exit(1);
+    }
+    return abs;
+  }
+  return resolveProjectRoot(process.cwd());
+}
+
+// Return entries whose user-visible path (rescuedFrom when ephemeral,
+// otherwise path) is at or under the scope. Compares both the literal
+// path and its realpath against both the literal scope and the realpath
+// of the scope, so a symlinked /var on macOS doesn't make an entry
+// disappear from `sdoc library ls`.
+function entriesUnderScope(scope) {
+  const root = path.resolve(scope);
+  let rootReal = root;
+  try { rootReal = fs.realpathSync(root); } catch (_) {}
+  const sep = path.sep;
+  function under(p) {
+    if (!p) return false;
+    if (p === root || p.startsWith(root + sep)) return true;
+    if (rootReal !== root && (p === rootReal || p.startsWith(rootReal + sep))) return true;
+    return false;
+  }
+  const out = [];
+  for (const e of store.loadIndex().entries) {
+    const p = e.rescued && e.rescuedFrom ? e.rescuedFrom : e.path;
+    let pReal = p;
+    try { pReal = fs.realpathSync(p); } catch (_) {}
+    if (under(p) || under(pReal)) {
+      out.push(Object.assign({}, e, { userPath: p }));
+    }
+  }
+  out.sort((a, b) => a.userPath.localeCompare(b.userPath));
+  return out;
+}
+
+// `sdoc library ls [path]` and `sdoc library ls [path] --tags`.
+// Designed for agents: every output starts with a preamble line that
+// states the resolved scope, and ends with a count line. Same shape
+// whether the result set is large, small, or empty - so an agent can
+// always tell what it queried without guessing.
+function libraryLs(opts) {
+  const scope = resolveLsScope(opts.extra);
+
+  if (opts.tagsFlag) {
+    const tags = libIndex.tagsUnderPrefix(scope);
+    if (!tags.length) {
+      console.log(`no tagged markdown files indexed under ${scope} yet`);
+      console.log(`(tip: run \`sdoc library rebuild\` if you expected results, or open a file with \`sdoc <file> +tag\` to start tagging)`);
+      return;
+    }
+    console.log(`most frequent tags for tagged markdown files under ${scope} (tag - count):`);
+    for (const { tag, count } of tags) {
+      console.log(`  ${tag} - ${count}`);
+    }
+    // taggedFiles is the count of entries (under scope) that have at
+    // least one tag; tags.length is the count of distinct tags.
+    const entries = entriesUnderScope(scope);
+    const taggedFiles = entries.filter(e => (e.tags || []).length > 0).length;
+    console.log(`(${tags.length} distinct ${tags.length === 1 ? 'tag' : 'tags'} across ${taggedFiles} tagged ${taggedFiles === 1 ? 'file' : 'files'})`);
+    return;
+  }
+
+  const entries = entriesUnderScope(scope);
+  if (!entries.length) {
+    console.log(`library has no markdown indexed under ${scope} yet`);
+    console.log(`(tip: run \`sdoc library rebuild\` to scan, or open a file with \`sdoc <file>\` to index it)`);
+    return;
+  }
+
+  console.log(`library files for ${scope}:`);
+  // Column width: longest relative path, capped at 60 so very deep paths
+  // don't push the tags column off-screen. Aligned padding helps a
+  // human skim AND keeps the columns parseable for an agent.
+  const rels = entries.map(e => {
+    const rel = path.relative(scope, e.userPath);
+    return rel === '' ? path.basename(e.userPath) : rel;
+  });
+  const colWidth = Math.min(60, Math.max(...rels.map(r => r.length)));
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const rel = rels[i];
+    const pad = rel.length < colWidth ? ' '.repeat(colWidth - rel.length) : '';
+    const tagBox = (e.tags && e.tags.length)
+      ? '[' + e.tags.join(', ') + ']'
+      : '[no tags]';
+    console.log(`  ${rel}${pad}  ${tagBox}`);
+  }
+  console.log(`(${entries.length} ${entries.length === 1 ? 'file' : 'files'})`);
+}
+
+function libraryHelp() {
+  console.log(helpText.LIBRARY_HELP);
+}
+
+// Ping the canonical agent port; resolves true if it answers OK.
+function pingAgent(port, timeoutMs = 400) {
+  return new Promise((resolve) => {
+    const req = http.get({ hostname: '127.0.0.1', port, path: '/api/library/health', timeout: timeoutMs }, (res) => {
+      resolve(res.statusCode === 200);
+      res.resume();
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+// Default-on autostart: silently enable the OS auto-launch the first
+// time the user runs `sdoc library`, unless they've explicitly disabled
+// it before. The user can always turn it off with `sdoc library
+// autostart disable`. Stays quiet on platforms that don't support it.
+function ensureAutostart() {
+  if (!autostart.isSupported()) return;
+  const state = store.loadState();
+  if (state.autostartUserDisabled) return;
+  if (autostart.isEnabled()) return;
+  const r = autostart.enable();
+  if (r.ok) {
+    console.log('library: auto-start on login is on (run `sdoc library autostart disable` to turn off)');
+  }
+}
+
+async function libraryOpen() {
+  const state = store.loadState();
+  const siteUrl = process.env.SDOCS_URL || DEFAULT_URL;
+  const idx = store.loadIndex();
+
+  // If an agent is already listening on the canonical port (likely
+  // because autostart is enabled), don't start another - just open the
+  // page and exit. Avoids a port conflict and avoids the user having
+  // two agents.
+  const existing = await pingAgent(libServer.DEFAULT_PORT);
+  if (existing) {
+    const pageUrl = `${siteUrl}/library`;
+    console.log(`library: ${pageUrl} (using already-running agent)`);
+    console.log(`library: ${idx.entries.length} entries indexed`);
+    openBrowser(pageUrl);
+    return;
+  }
+
+  const { agentUrl } = await libServer.createServer();
+  const pageUrl = `${siteUrl}/library?agent=${encodeURIComponent(agentUrl)}`;
+  console.log(`library: ${pageUrl}`);
+  console.log(`library: ${idx.entries.length} entries indexed` + (state.enabled === false ? ' (scanning disabled)' : ''));
+  if (!idx.entries.length) console.log('library: click "rescan" in the UI to walk your home for markdown.');
+  ensureAutostart();
+  console.log(`library: agent at ${agentUrl} (ctrl-c to stop)`);
+  openBrowser(pageUrl);
+}
+
+function autostartEnable() {
+  const r = autostart.enable();
+  if (!r.ok) { console.error('library autostart: ' + r.message); process.exit(1); }
+  // Clear the "user explicitly disabled" flag so future `sdoc library`
+  // invocations don't tip-toe around the preference.
+  const s = store.loadState();
+  s.autostartUserDisabled = false;
+  store.saveState(s);
+  console.log('library autostart: enabled (plist at ' + r.path + ')');
+}
+
+function autostartDisable() {
+  const r = autostart.disable();
+  if (!r.ok) { console.error('library autostart: ' + r.message); process.exit(1); }
+  // Record the explicit-disable so the default-on logic in libraryOpen
+  // doesn't quietly re-enable it next time.
+  const s = store.loadState();
+  s.autostartUserDisabled = true;
+  store.saveState(s);
+  console.log(r.alreadyDisabled ? 'library autostart: was not enabled' : 'library autostart: disabled');
+}
+
+function autostartStatus() {
+  const s = autostart.status();
+  if (!s.supported) {
+    console.log('library autostart: not supported on ' + process.platform + ' yet (macOS only for now)');
+    return;
+  }
+  console.log('library autostart: ' + (s.enabled ? 'enabled' : 'disabled'));
+  console.log('  plist: ' + s.plistPath);
+}
+
+// The library verb dispatches on opts.file (which io.parseArgs put the
+// sub-sub-verb into - it's the next positional after 'library').
+// `sdoc library autostart enable` carries the second sub-arg in opts.extra.
+async function libraryCommand(opts) {
+  // `sdoc library --help` and `sdoc library help` both print the
+  // library-specific long help (LIBRARY_HELP).
+  if (opts.helpFlag) { libraryHelp(); return; }
+  const sub = (opts.file || '').toLowerCase();
+  switch (sub) {
+    case '':         await libraryOpen();    break;
+    case 'help':     libraryHelp();          break;
+    case 'ls':       libraryLs(opts);        break;
+    case 'enable':   libraryEnable();        break;
+    case 'disable':  libraryDisable();       break;
+    case 'status':   libraryStatus();        break;
+    case 'rebuild':  libraryRebuild();       break;
+    case 'autostart': {
+      const action = (opts.extra || '').toLowerCase();
+      if (action === 'enable')       autostartEnable();
+      else if (action === 'disable') autostartDisable();
+      else if (action === '' || action === 'status') autostartStatus();
+      else {
+        console.error(`sdoc library autostart: unknown action "${action}"`);
+        console.error('usage: sdoc library autostart [enable|disable|status]');
+        process.exit(1);
+      }
+      break;
+    }
+    default:
+      console.error(`sdoc library: unknown subcommand "${sub}"`);
+      console.error('usage: sdoc library [ls|enable|disable|status|rebuild|autostart|help]');
+      process.exit(1);
+  }
+}
+
+// Hook called from the default open command. Fires after the file has
+// been resolved but before (or alongside) the browser open. Best-effort:
+// any failure is swallowed so a bad library doesn't break opening a file.
+function tapOpen(opts) {
+  try {
+    const s = store.loadState();
+    if (s.enabled === false) return;
+    if (!opts.file) return;
+    const abs = path.resolve(opts.file);
+    libIndex.indexFile(abs, { addTags: opts.addTags || [] });
+  } catch (_) {
+    // intentional: never break the open flow
+  }
+}
+
+module.exports = {
+  libraryCommand,
+  libraryEnable, libraryDisable, libraryStatus, libraryRebuild, libraryOpen,
+  libraryLs, libraryHelp,
+  resolveProjectRoot, resolveLsScope, entriesUnderScope,
+  tapOpen,
+};