sdocs-dev 1.6.2 → 1.13.0

package/lib/cells-transclude.js

@@ -0,0 +1,114 @@
+// cells-transclude.js - bake {{path/to/file.csv}} references into ```cells
+// blocks at CLI time.
+//
+// The browser can never read a local file, so a CSV reference only means
+// something while the CLI is involved. On open (and on share), every
+// ```cells block whose body is a bare {{...}} reference is replaced with the
+// file's full contents plus a metadata line the renderer reads:
+//
+//   ```cells                          ```cells
+//   {{data/report.csv}}        ->     sdoc-cells: source=report.csv
+//   ```                               Region,Q1,Q2
+//                                     North,100,150
+//                                     ...
+//                                     ```
+//
+// The whole file is baked in (the user chose "whole CSV always travels"), so
+// the resulting doc is self-contained and a share link never errors. Only the
+// basename is recorded as `source=` - the full local path would leak the
+// author's directory structure into a shared link. A read failure bakes an
+// `error=` directive the renderer surfaces instead.
+
+const fs = require('fs');
+const path = require('path');
+
+// A ```cells fenced block (captures leading boundary, optional fence name, and
+// body). The name (```cells Sales) is preserved on the baked block so a tab
+// loaded from a CSV keeps its identity. Tilde fences and inline-data blocks are
+// left untouched.
+const CELLS_BLOCK = /(^|\n)```cells[ \t]*([^\n]*)\n([\s\S]*?)\n```/g;
+const REFERENCE = /^\{\{\s*([^}]+?)\s*\}\}$/;
+// A trailing :range suffix like :B5:J32 or :B5 (a view hint; data is baked in
+// whole regardless, so we just strip it off the path for now).
+const RANGE_SUFFIX = /:([A-Za-z]+\d+(?::[A-Za-z]+\d+)?)$/;
+
+function directiveValue(s) {
+  return /\s|"/.test(s) ? JSON.stringify(s) : s;
+}
+
+function bakeBlock(boundary, name, ref, baseDir, readFile, preLines) {
+  var range = '';
+  var filePath = ref;
+  var rm = ref.match(RANGE_SUFFIX);
+  if (rm) { range = rm[1]; filePath = ref.slice(0, ref.length - rm[0].length); }
+
+  var fence = '```cells' + (name ? ' ' + name : '');
+  var base = path.basename(filePath);
+  // Author format: lines (e.g. `format: B=$`) sit before the reference and are
+  // preserved verbatim above the baked data.
+  var head = (preLines && preLines.length ? preLines.join('\n') + '\n' : '');
+  var csv;
+  try {
+    csv = readFile(path.resolve(baseDir, filePath));
+  } catch (e) {
+    return boundary + fence + '\n' + head + 'sdoc-cells: error=' +
+      directiveValue('Could not read ' + base) + '\n```';
+  }
+  csv = String(csv).replace(/\s+$/, '');
+  var directive = 'sdoc-cells: source=' + directiveValue(base) +
+    (range ? ' range=' + range : '');
+  return boundary + fence + '\n' + head + directive + '\n' + csv + '\n```';
+}
+
+// Replace every {{file.csv}} cells block in `content` with the baked data.
+// `readFile` is injectable for tests; defaults to fs.readFileSync(utf-8).
+function transcludeCells(content, baseDir, readFile) {
+  if (typeof content !== 'string' || content.indexOf('```cells') === -1) return content;
+  var read = readFile || function (p) { return fs.readFileSync(p, 'utf-8'); };
+  return content.replace(CELLS_BLOCK, function (whole, boundary, name, body) {
+    // Peel any leading author `format:` lines, then require a sole {{ref}}.
+    var lines = body.split('\n');
+    var pre = [];
+    var i = 0;
+    while (i < lines.length && /^\s*format:\s*/i.test(lines[i])) { pre.push(lines[i].trim()); i++; }
+    var rest = lines.slice(i).join('\n').trim();
+    var m = rest.match(REFERENCE);
+    if (!m) return whole;                    // inline data - leave alone
+    return bakeBlock(boundary, (name || '').trim(), m[1], baseDir, read, pre);
+  });
+}
+
+// Wrap a standalone .csv file's contents in a ```cells block (so `sdoc x.csv`
+// opens as a sheet, mirroring the .mmd -> mermaid wrapping).
+function wrapCsvFile(csv, filename) {
+  var base = path.basename(filename);
+  return '```cells\nsdoc-cells: source=' + directiveValue(base) + '\n' +
+    String(csv).replace(/\s+$/, '') + '\n```\n';
+}
+
+// A "wrapped" file is one whose renderable document is DERIVED from the file
+// (its contents inside a fenced block) rather than the file itself. The two
+// open paths (URL snapshot via readContent, live sync via the bridge) both
+// wrap these for display, and the bridge refuses to save the derived view
+// back - that would overwrite the .csv / .mmd with fence markup.
+function isWrappedFile(filePath) {
+  return /\.(csv|mmd|mermaid)$/i.test(String(filePath || ''));
+}
+
+// File contents -> renderable document. Wrapped types get their fence;
+// everything else (markdown) passes through untouched.
+function wrapForDisplay(raw, filePath) {
+  var name = String(filePath || '');
+  if (/\.(mmd|mermaid)$/i.test(name)) {
+    return '```mermaid\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
+  }
+  if (/\.csv$/i.test(name)) return wrapCsvFile(raw, name);
+  return String(raw);
+}
+
+module.exports = {
+  transcludeCells: transcludeCells,
+  wrapCsvFile: wrapCsvFile,
+  isWrappedFile: isWrappedFile,
+  wrapForDisplay: wrapForDisplay,
+};

package/lib/cells-verify.js

@@ -0,0 +1,165 @@
+// cells-verify.js - headless evaluation of a document's ```cells tabs.
+//
+// `sdoc cells verify <file.md>` parses every ```cells block, names the tabs
+// exactly as the browser does, recalculates them together as one workbook
+// (so cross-tab references like Sales!A1 resolve), and prints the COMPUTED
+// values. It is the agent's feedback loop: write formulas, run this, read the
+// numbers back - no browser, same engine the page runs (cli/shared/), so what
+// it prints is what ships.
+//
+// Output:
+//   default   CSV per tab, each under a "# sheet: <name>" banner. Human view;
+//             a data row could itself start with "# sheet:", so this form is
+//             documented as not machine-round-trippable - agents use --json.
+//   --json    { ok, sheets:[{name, values:[[...]]}], errors:[{sheet,cell,code}] }
+//   --sheet N only that tab (case-insensitive). Absent name -> exit 2.
+//
+// Exit: 0 = no cell errors in the emitted tabs; 1 = at least one cell error
+// (#REF!/#CIRC!/#DIV0!/...); 2 = bad usage (no file, --sheet names no tab).
+
+const path = require('path');
+const io = require('./io');
+const CELLS = require('../shared/sdocs-cells.js');
+const FX = require('../shared/sdocs-cells-formula.js');
+
+// Scan ```cells (or ~~~cells) fenced blocks, capturing the fence info string
+// as the tab name and the block body. Approximate vs marked (no nested-fence
+// awareness) but matches how agents author docs. The closing fence must be the
+// same run of fence characters (backreference) at a line start.
+function scanCellsBlocks(md) {
+  var re = /(?:^|\n)(```+|~~~+)cells[ \t]*([^\n]*)\n([\s\S]*?)\n\1[ \t]*(?=\n|$)/g;
+  var blocks = [];
+  var m;
+  while ((m = re.exec(md))) {
+    blocks.push({ name: (m[2] || '').trim().replace(/"/g, ''), body: m[3] });
+  }
+  return blocks;
+}
+
+// Parse + name every block into a workbook, mirroring the renderer: a fence
+// name wins, then an explicit `name=` directive, then auto Sheet1/Sheet2... by
+// order among the blocks that became real grids. Non-grid blocks (empty /
+// unresolved) are skipped; a parse error is recorded so the exit code reflects it.
+function buildWorkbook(md) {
+  var blocks = scanCellsBlocks(md);
+  var sheets = [];   // { name, model }
+  var parseErrors = [];
+  var autoIdx = 0;
+  for (var i = 0; i < blocks.length; i++) {
+    var model;
+    try { model = CELLS.parseCells(blocks[i].body); }
+    catch (e) { parseErrors.push((e && e.message) || 'parse error'); continue; }
+    if (model.error) { parseErrors.push(model.error); continue; }
+    if (model.unresolved || model.empty) continue;
+    var name = blocks[i].name || (model.name && String(model.name).trim()) || ('Sheet' + (++autoIdx));
+    sheets.push({ name: name, model: model });
+  }
+  return { sheets: sheets, parseErrors: parseErrors };
+}
+
+// Render one sheet's computed grid to a 2D array of display strings: a formula
+// cell shows its result (number, or the error code), every other cell shows its
+// literal text verbatim. fxGrid is this sheet's recalcWorkbook results.
+function valuesFor(model, fxGrid) {
+  var out = [];
+  for (var r = 0; r < model.cells.length; r++) {
+    var line = model.cells[r];
+    var row = [];
+    for (var c = 0; c < line.length; c++) {
+      var cell = line[c];
+      if (FX.isFormula(cell.raw)) {
+        var fx = (fxGrid[r] && fxGrid[r][c]) || { kind: 'empty' };
+        if (fx.kind === 'number') row.push(String(fx.value));
+        else if (fx.kind === 'error') row.push(fx.code);
+        else if (fx.kind === 'text') row.push(String(fx.value));
+        else row.push('');
+      } else {
+        row.push(cell.raw);
+      }
+    }
+    out.push(row);
+  }
+  return out;
+}
+
+// Collect cell errors across a sheet for the exit code + --json errors list.
+function errorsFor(name, model, fxGrid) {
+  var errs = [];
+  for (var r = 0; r < fxGrid.length; r++) {
+    var line = fxGrid[r] || [];
+    for (var c = 0; c < line.length; c++) {
+      var fx = line[c];
+      if (fx && fx.kind === 'error') {
+        errs.push({ sheet: name, cell: CELLS.colName(c) + (r + 1), code: fx.code });
+      }
+    }
+  }
+  return errs;
+}
+
+async function cellsVerifyCommand(opts) {
+  var file = opts.extra;   // `sdoc cells verify <file>` -> file lands in extra
+  if (!file) {
+    console.error('sdoc: cells verify needs a file - usage: sdoc cells verify <file.md> [--json] [--sheet <name>]');
+    process.exit(2);
+  }
+
+  var content = await io.readContent(file);   // same baking the browser receives
+  if (content == null) {
+    console.error('sdoc: nothing to read from ' + file);
+    process.exit(2);
+  }
+
+  var wb = buildWorkbook(content);
+  var fxGrids = FX.recalcWorkbook(wb.sheets.map(function (s) {
+    return { name: s.name, model: s.model };
+  }));
+
+  // Build the per-sheet view once; --sheet filters it afterwards.
+  var rendered = wb.sheets.map(function (s, i) {
+    return {
+      name: s.name,
+      values: valuesFor(s.model, fxGrids[i] || []),
+      errors: errorsFor(s.name, s.model, fxGrids[i] || []),
+    };
+  });
+
+  if (opts.sheetName) {
+    var want = String(opts.sheetName).toLowerCase();
+    var only = rendered.filter(function (r) { return r.name.toLowerCase() === want; });
+    if (!only.length) {
+      console.error('sdoc: no tab named "' + opts.sheetName + '" in ' + file);
+      process.exit(2);
+    }
+    rendered = only;
+  }
+
+  var allErrors = [];
+  rendered.forEach(function (r) { allErrors = allErrors.concat(r.errors); });
+  var ok = allErrors.length === 0 && wb.parseErrors.length === 0;
+
+  if (opts.jsonFlag) {
+    process.stdout.write(JSON.stringify({
+      ok: ok,
+      sheets: rendered.map(function (r) { return { name: r.name, values: r.values }; }),
+      errors: allErrors,
+      parseErrors: wb.parseErrors,
+    }, null, 2) + '\n');
+  } else {
+    if (!rendered.length) console.error('sdoc: no cells tabs found in ' + file);
+    var chunks = rendered.map(function (r) {
+      return '# sheet: ' + r.name + '\n' + CELLS.serializeCsv(r.values);
+    });
+    if (chunks.length) process.stdout.write(chunks.join('\n') + '\n');
+    wb.parseErrors.forEach(function (e) { console.error('sdoc: cells parse error - ' + e); });
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+module.exports = {
+  cellsVerifyCommand: cellsVerifyCommand,
+  scanCellsBlocks: scanCellsBlocks,
+  buildWorkbook: buildWorkbook,
+  valuesFor: valuesFor,
+};

package/lib/commands.js

@@ -0,0 +1,291 @@
+// Verb handlers wired into the router.
+//
+// Each handler takes parsed opts and returns a Promise (or void). They
+// share `prepareUrl` for the load-content / apply-defaults / build-URL
+// flow that `open` and `share` both need.
+
+const path = require('path');
+const { execSync } = require('child_process');
+
+const SDocYaml = require('../shared/sdocs-yaml.js');
+
+const { DEFAULT_URL } = require('./constants');
+const { readContent, openBrowser } = require('./io');
+const { loadDefaultStyles, applyDefaultStyles, showDefaults, resetDefaults } = require('./styles');
+const { buildUrl } = require('./url');
+const { buildShortUrl } = require('./short-link');
+const { refreshUpdateCache, maybeUpdateBinary } = require('./update-check');
+const { runSetup, maybeAutoRefresh } = require('./setup');
+
+// Shared "after the command ran" tail used by `open` and `share`.
+async function postCommandHooks() {
+  refreshUpdateCache();
+  await maybeUpdateBinary();
+  await runSetup();
+  await maybeAutoRefresh();
+}
+
+// Load content (file or stdin), apply ~/.sdocs/styles.yaml defaults, inject
+// `file:` into front matter, and build either a hash URL or a short URL.
+// Returns { url, contentPresent }.
+async function prepareUrl(opts) {
+  let content = await readContent(opts.file);
+  const defaults = loadDefaultStyles();
+  if (content && defaults) {
+    content = applyDefaultStyles(content);
+  }
+
+  // Inject `file:` into front matter (basename only — safe to share).
+  // Respects user-set file: if already present.
+  if (content && opts.file) {
+    const parsed = SDocYaml.parseFrontMatter(content);
+    if (!parsed.meta.file) {
+      parsed.meta.file = path.basename(opts.file);
+      content = SDocYaml.serializeFrontMatter(parsed.meta) + '\n' + parsed.body;
+    }
+  }
+
+  // Runtime-only local metadata for the opener's view.
+  // `share` omits it so shared URLs never carry paths.
+  let local = null;
+  if (opts.file && opts.subcommand !== 'share') {
+    const abs = path.resolve(opts.file);
+    const rel = path.relative(process.cwd(), abs);
+    local = { fullPath: abs };
+    if (!rel.startsWith('..') && !path.isAbsolute(rel)) {
+      local.path = './' + rel;
+    }
+  }
+
+  let url;
+  if (opts.shortFlag) {
+    if (opts.subcommand !== 'share') {
+      console.error('sdoc: --short is only valid with the `share` subcommand');
+      process.exit(1);
+    }
+    if (!content) {
+      console.error('sdoc: --short needs content (a file path or piped stdin)');
+      process.exit(1);
+    }
+    try {
+      url = await buildShortUrl(content, {
+        url: opts.url,
+        mode: opts.mode,
+        theme: opts.theme,
+        section: opts.section,
+      });
+    } catch (e) {
+      console.error('sdoc: could not create short link -', e.message);
+      process.exit(1);
+    }
+  } else {
+    url = buildUrl(content, {
+      url: opts.url,
+      mode: opts.mode,
+      theme: opts.theme,
+      defaultStyles: !content ? defaults : null,
+      section: opts.section,
+      local,
+      present: opts.present,
+    });
+  }
+
+  return { url, contentPresent: !!content };
+}
+
+// Default flow: `sdoc <file>` or `sdoc` (no args, or piped stdin).
+//
+// The document travels in the URL hash and renders read-only-by-default in the
+// browser; nothing connects back to disk. This is the everywhere-works path -
+// no local socket, no browser permission prompt. The live, autosaving session
+// (browser <-> file on disk) is opt-in via `sdoc bridge <file>`.
+//
+// The non-blocking, share-by-URL case is `sdoc share <file>`.
+async function openCommand(opts) {
+  const { url } = await prepareUrl(opts);
+  openBrowser(url);
+  console.log(`SDocs → ${url.length > 80 ? url.slice(0, 77) + '...' : url}`);
+  await postCommandHooks();
+}
+
+async function shareCommand(opts) {
+  const { url } = await prepareUrl(opts);
+  try {
+    const clip = process.platform === 'darwin' ? 'pbcopy'
+      : execSync('which xclip 2>/dev/null', { encoding: 'utf-8' }).trim() ? 'xclip -selection clipboard'
+      : 'xsel --clipboard --input';
+    execSync(clip, { input: url, stdio: ['pipe', 'ignore', 'ignore'] });
+    const name = opts.file ? path.basename(opts.file) : 'stdin';
+    const label = opts.shortFlag ? 'Short link' : 'Link';
+    console.log(`✓ ${label} for ${name} copied to clipboard`);
+    if (opts.shortFlag) console.log(`  ${url}`);
+  } catch (_) {
+    process.stdout.write(url + '\n');
+  }
+  await postCommandHooks();
+}
+
+function defaultsCommand(opts) {
+  if (opts.resetFlag) resetDefaults();
+  else showDefaults();
+}
+
+// `sdoc color-analysis <file>` — grade every text-on-background pair in the
+// document's custom palette against WCAG ratios, for both the light and dark
+// themes. Exits 1 if anything is unreadable so an agent (or CI) notices.
+async function colorAnalysisCommand(opts) {
+  const SDocContrast = require('../shared/sdocs-contrast.js');
+  const content = await readContent(opts.file);
+  if (!content) {
+    console.error('sdoc color-analysis: pass a markdown file (or pipe one in)');
+    console.error('  e.g. sdoc color-analysis report.md');
+    process.exit(1);
+  }
+  const meta = SDocYaml.parseFrontMatter(content).meta || {};
+  const styles = meta.styles || null;
+  const name = opts.file ? path.basename(opts.file) : 'stdin';
+
+  if (!styles || !SDocContrast.hasCustomColors(styles)) {
+    console.log(`sdoc color-analysis: ${name}`);
+    console.log('  No custom colours set - the built-in palette is contrast-safe in both themes.');
+    process.exit(0);
+  }
+
+  const a = SDocContrast.analyzeStyles(styles);
+  const pad = (s, n) => (s + ' '.repeat(n)).slice(0, n);
+  const minRatio = SDocContrast.MIN_CONTRAST;
+  function line(p) {
+    const tag = p.ok ? 'ok  ' : 'FAIL';
+    const ratio = p.ratio == null ? '   ?  ' : (p.ratio.toFixed(2) + ':1');
+    return `  ${tag}  ${pad(p.label, 16)} ${pad(p.fg + ' on ' + p.bg, 22)} ${pad(ratio, 9)} ${p.ok ? '' : '(needs ' + minRatio + ':1)'}`;
+  }
+
+  console.log(`sdoc color-analysis: ${name}\n`);
+  console.log('LIGHT THEME');
+  a.light.forEach(p => console.log(line(p)));
+  console.log('\nDARK THEME');
+  a.dark.forEach(p => console.log(line(p)));
+
+  console.log('');
+  if (a.fails.length === 0) {
+    console.log('All text/background pairs meet WCAG AA. ✓');
+    process.exit(0);
+  }
+  console.log(`${a.fails.length} unreadable pair${a.fails.length === 1 ? '' : 's'} (contrast below ${minRatio}:1).`);
+  console.log('Fix the flagged colours, or add a `dark:` override so the dark theme has its own readable values.');
+  console.log('Reminder: top-level colours are the LIGHT theme; dark mode is auto-derived unless you set `dark:`.');
+  process.exit(1);
+}
+
+function newCommand(opts) {
+  const baseUrl = opts.url || process.env.SDOCS_URL || DEFAULT_URL;
+  const url = baseUrl + '/new';
+  openBrowser(url);
+  console.log(`SDocs → ${url}`);
+}
+
+// `sdoc slides` family. Dispatches on the positional after `slides`:
+//   sdoc slides                     -> prints SLIDES_HELP
+//   sdoc slides list                -> built-in template registry
+//   sdoc slides custom-shapes       -> raw-shape reference
+//   sdoc slides icons [query]       -> Lucide icon name listing
+function slidesCommand(opts) {
+  const helpText = require('./help-text');
+  const sub = opts.file;
+  if (sub === 'list')          { printSlideStdlib();           return; }
+  if (sub === 'custom-shapes') { console.log(helpText.SLIDES_CUSTOM_SHAPES_HELP); return; }
+  if (sub === 'icons')         { printIconList(opts.extra);    return; }
+  console.log(helpText.SLIDES_HELP);
+}
+
+// `sdoc present <file>` opens the file straight into fullscreen slide
+// view. Delegates to openCommand with `present: true` set so the URL
+// gets `&present=0` and the browser auto-enters present mode on load.
+function presentCommand(opts) {
+  return openCommand(Object.assign({}, opts, { present: true }));
+}
+
+function printSlideStdlib() {
+  // Require lazily so the browser-side slide stdlib (which uses window
+  // globals) is only loaded when this command actually runs.
+  const SDocSlideStdlib = require('../../public/sdocs-slide-stdlib.js');
+  const names = SDocSlideStdlib.names || Object.keys(SDocSlideStdlib.templates || {});
+  const slots = SDocSlideStdlib.slots || {};
+  console.log('Built-in slide templates');
+  console.log('========================');
+  const pad = 22;
+  for (let i = 0; i < names.length; i++) {
+    const n = names[i];
+    let label = '@extends ' + n;
+    while (label.length < pad) label += ' ';
+    const slotList = (slots[n] || []).join(', ');
+    console.log(label + ' ' + slotList);
+  }
+  console.log('');
+  console.log('`!` marks a required slot (resolver errors when omitted).');
+  console.log('Use a built-in by adding `@extends <name>` to a slide block.');
+  console.log('Define a user @template with the same name to override (you\'ll get a warning).');
+}
+
+function printIconList(query) {
+  let names;
+  try {
+    // The manifest sits next to this file (via cli/bin/). Require by
+    // resolved path so it works whether we're invoked from a globally
+    // installed binary or from a checkout.
+    names = require('../bin/sdocs-icon-names.js');
+  } catch (e) {
+    console.error('sdoc: icon names manifest missing (cli/bin/sdocs-icon-names.js).');
+    console.error('Run `node scripts/build-icons.js` to generate it.');
+    process.exit(1);
+  }
+
+  const q = (query || '').toLowerCase().trim();
+  const matches = q ? names.filter(n => n.indexOf(q) !== -1) : names;
+
+  if (q && matches.length === 0) {
+    console.log('No Lucide icons match "' + query + '".');
+    console.log('Browse the full set at https://lucide.dev/icons/ or run `sdoc slides icons` to list everything.');
+    return;
+  }
+
+  if (q) {
+    console.log('Lucide icons matching "' + query + '" (' + matches.length + ' of ' + names.length + ')');
+  } else {
+    console.log('Lucide icons available to the `icon` shape kind (' + names.length + ' total)');
+  }
+  console.log('Source: https://lucide.dev/icons/  -  use `name=<icon>` in slides');
+  console.log('');
+
+  const longest = matches.reduce((m, n) => n.length > m ? n.length : m, 0);
+  const colWidth = longest + 2;
+  const cols = 4;
+  const rows = Math.ceil(matches.length / cols);
+  for (let r = 0; r < rows; r++) {
+    let line = '';
+    for (let c = 0; c < cols; c++) {
+      const idx = c * rows + r;
+      if (idx >= matches.length) break;
+      let name = matches[idx];
+      while (name.length < colWidth) name += ' ';
+      line += name;
+    }
+    console.log(line.replace(/\s+$/, ''));
+  }
+
+  if (!q) {
+    console.log('');
+    console.log('Tip: filter with `sdoc slides icons <substring>` (e.g. `sdoc slides icons cloud`).');
+  }
+}
+
+module.exports = {
+  prepareUrl,
+  openCommand,
+  shareCommand,
+  defaultsCommand,
+  colorAnalysisCommand,
+  newCommand,
+  slidesCommand,
+  presentCommand,
+};