sdocs-dev 1.4.2 → 1.6.1

package/bin/sdocs-postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// One-line hint after `npm i -g sdocs-dev`. Non-interactive by design.
+//
+// Skipped on:
+//   - CI=true (automated builds)
+//   - NO_UPDATE_NOTIFIER=1 (user opt-out)
+//   - npm installing as a dependency (not a global install)
+//
+// NOT gated on isTTY: when an agent installs sdoc on a user's behalf, the
+// agent reads stdout, so the hint reaches the user via the agent's summary.
+
+if (process.env.CI) process.exit(0);
+if (process.env.NO_UPDATE_NOTIFIER) process.exit(0);
+
+// `npm_config_global` is set when this is a global install (`npm i -g`).
+// For local installs (as a dependency), stay silent.
+if (process.env.npm_config_global !== 'true') process.exit(0);
+
+console.log(`
+sdocs-dev installed. Run \`sdoc\` to wire SDocs into your CLI coding agents.
+
+This allows you to use SDocs in conversation with a CLI coding agent.
+Try asking:
+  "write up the plan and sdoc it to me"
+  "explain async/await to me in a sdoc"
+  "draft the release notes as a sdoc I can share"
+`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs-dev",
-  "version": "1.4.2",
+  "version": "1.6.1",
   "description": "Open, share, and style markdown files from the terminal",
   "main": "bin/sdocs-dev.js",
   "bin": {
@@ -15,7 +15,8 @@
   ],
   "scripts": {
     "start": "node server.js",
-    "test": "node test/run.js"
+    "test": "node test/run.js",
+    "postinstall": "node bin/sdocs-postinstall.js"
   },
   "keywords": [
     "markdown",
@@ -31,12 +32,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/JoshInLisbon/SDocs.git"
+    "url": "git+https://github.com/espressoplease/SDocs.git"
   },
   "homepage": "https://sdocs.dev",
+  "dependencies": {
+    "better-sqlite3": "^12.8.0"
+  },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
-    "better-sqlite3": "^12.8.0",
     "brotli": "^1.3.3",
     "brotli-dec-wasm": "^2.3.2",
     "brotli-wasm": "^3.0.1",

package/public/sdocs-yaml.js

@@ -1,10 +1,30 @@
 // sdocs-yaml.js — YAML front matter parse/serialize (UMD)
-// Shared by browser (app) and Node (CLI + tests)
+// Shared by browser (app) and Node (CLI + tests).
+// Supports a subset of YAML: nested maps, inline `{...}` leaf maps, and
+// arrays of scalars or objects serialized as `- item` blocks.
 (function (exports) {
 'use strict';
 
+// Skip keys that would replace the object's prototype chain or shadow
+// built-ins via the cascade. A shared YAML doc cannot smuggle ghost
+// properties into `meta.comments` etc. by setting `__proto__:` to a
+// nested map.
+function isUnsafeKey(k) {
+  return k === '__proto__' || k === 'prototype' || k === 'constructor';
+}
+
 function parseScalar(v) {
-  v = v.trim().replace(/^["']|["']$/g, '');
+  v = v.trim();
+  if (v === '') return v;
+  // Quoted string: strip quotes and handle minimal escapes.
+  if ((v[0] === '"' && v[v.length - 1] === '"') ||
+      (v[0] === "'" && v[v.length - 1] === "'")) {
+    var quoted = v.slice(1, -1);
+    if (v[0] === '"') {
+      quoted = quoted.replace(/\\"/g, '"').replace(/\\\\/g, '\\').replace(/\\n/g, '\n');
+    }
+    return quoted;
+  }
   const n = Number(v);
   return (!isNaN(n) && v !== '') ? n : v;
 }
@@ -14,30 +34,73 @@ function parseInlineObject(str) {
   const obj = {};
   inner.split(',').forEach(pair => {
     const m = pair.trim().match(/^(\w[\w-]*):\s*(.*)/);
-    if (m) obj[m[1]] = parseScalar(m[2].trim());
+    if (m && !isUnsafeKey(m[1])) obj[m[1]] = parseScalar(m[2].trim());
   });
   return obj;
 }
 
+// Parses an array block starting at lines[startIdx] whose items are
+// introduced by `- ` at exactly `indent` columns. An item is either a
+// scalar (`- foo`) or an object whose first key appears on the same line
+// as the dash (`- key: value`) and whose following keys are indented two
+// beyond the dash.
+function parseArray(lines, startIdx, indent) {
+  var out = [];
+  var i = startIdx;
+  var dashPrefix = ' '.repeat(indent) + '- ';
+  while (i < lines.length && lines[i].startsWith(dashPrefix)) {
+    var rest = lines[i].substring(dashPrefix.length);
+    var km = rest.match(/^(\w[\w-]*):\s*(.*)/);
+    if (km) {
+      // Object item. Collect this line's key + any keys indented further.
+      var obj = {};
+      var key = km[1], val = km[2].trim();
+      if (!isUnsafeKey(key)) obj[key] = parseScalar(val);
+      i++;
+      var itemPrefix = ' '.repeat(indent + 2);
+      while (i < lines.length && lines[i].startsWith(itemPrefix) && !lines[i].startsWith(dashPrefix)) {
+        var line = lines[i].substring(indent + 2);
+        var im = line.match(/^(\w[\w-]*):\s*(.*)/);
+        if (im && !isUnsafeKey(im[1])) obj[im[1]] = parseScalar(im[2]);
+        i++;
+      }
+      out.push(obj);
+    } else {
+      out.push(parseScalar(rest));
+      i++;
+    }
+  }
+  return { arr: out, nextIdx: i };
+}
+
 function parseBlock(lines, startIdx, indent) {
   const result = {};
   let i = startIdx;
   const prefix = new RegExp('^' + ' '.repeat(indent));
   const deeper = new RegExp('^' + ' '.repeat(indent + 2));
+  const dashDeeper = new RegExp('^' + ' '.repeat(indent + 2) + '- ');
+  const dashSame = new RegExp('^' + ' '.repeat(indent) + '- ');
   while (i < lines.length && prefix.test(lines[i])) {
     const nl = lines[i].substring(indent);
     const nm = nl.match(/^(\w[\w-]*):\s*(.*)/);
     if (!nm) { i++; continue; }
     const key = nm[1], rest = nm[2].trim();
+    const safe = !isUnsafeKey(key);
     if (rest.startsWith('{')) {
-      result[key] = parseInlineObject(rest); i++;
-    } else if (rest === '' && i + 1 < lines.length && deeper.test(lines[i + 1])) {
+      const v = parseInlineObject(rest); if (safe) result[key] = v; i++;
+    } else if (rest === '' && i + 1 < lines.length && dashDeeper.test(lines[i + 1])) {
+      // Array child: `key:` followed by `  - ...` lines.
+      i++;
+      var arr = parseArray(lines, i, indent + 2);
+      if (safe) result[key] = arr.arr;
+      i = arr.nextIdx;
+    } else if (rest === '' && i + 1 < lines.length && deeper.test(lines[i + 1]) && !dashSame.test(lines[i + 1])) {
       i++;
       var sub = parseBlock(lines, i, indent + 2);
-      result[key] = sub.obj;
+      if (safe) result[key] = sub.obj;
       i = sub.nextIdx;
     } else {
-      result[key] = parseScalar(rest); i++;
+      if (safe) result[key] = parseScalar(rest); i++;
     }
   }
   return { obj: result, nextIdx: i };
@@ -62,13 +125,50 @@ function hasNestedObjects(obj) {
   return false;
 }
 
+function serializeArrayItems(arr, indent) {
+  const lines = [];
+  const pad = ' '.repeat(indent);
+  for (const item of arr) {
+    if (item === null || typeof item !== 'object') {
+      lines.push(`${pad}- ${JSON.stringify(item)}`);
+    } else {
+      const entries = Object.entries(item);
+      if (entries.length === 0) {
+        lines.push(`${pad}- {}`);
+        continue;
+      }
+      const [firstK, firstV] = entries[0];
+      lines.push(`${pad}- ${firstK}: ${JSON.stringify(firstV)}`);
+      for (let j = 1; j < entries.length; j++) {
+        const [k, v] = entries[j];
+        lines.push(`${pad}  ${k}: ${JSON.stringify(v)}`);
+      }
+    }
+  }
+  return lines;
+}
+
 function serializeFrontMatter(meta) {
   const lines = ['---'];
   for (const [k, v] of Object.entries(meta)) {
-    if (typeof v === 'object' && v !== null) {
+    if (Array.isArray(v)) {
+      // For the comments list, prepend a one-line schema doc so a reader
+      // (human or agent) opening this file cold can interpret block ids
+      // and the resolved flag without grepping the source.
+      if (k === 'comments' && v.length) {
+        lines.push('# Comments: block "tag:n" = nth (0-indexed) <tag> in render order.');
+        lines.push('# block kind may carry block_text (first ~60 chars) as a survival hint when the index drifts.');
+        lines.push('# inline kind anchors via quote (+ optional prefix/suffix). resolved: true marks addressed.');
+      }
+      lines.push(`${k}:`);
+      for (const line of serializeArrayItems(v, 2)) lines.push(line);
+    } else if (typeof v === 'object' && v !== null) {
       lines.push(`${k}:`);
       for (const [sk, sv] of Object.entries(v)) {
-        if (typeof sv === 'object' && sv !== null) {
+        if (Array.isArray(sv)) {
+          lines.push(`  ${sk}:`);
+          for (const line of serializeArrayItems(sv, 4)) lines.push(line);
+        } else if (typeof sv === 'object' && sv !== null) {
           // If sub-object contains nested objects (3 levels), serialize as block
           if (hasNestedObjects(sv)) {
             lines.push(`  ${sk}:`);