sdocs-dev 1.14.1 → 1.18.0

package/lib/io.js

@@ -5,14 +5,16 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { transcludeCells } = require('./cells-transclude');
 const { isWrappedFile, wrapForDisplay } = require('./file-wrap');
+const codeLangs = require('./code-langs');
 
 const SUBCOMMANDS = new Set([
   'new', 'share', 'schema', 'defaults', 'help', 'version',
-  'charts', 'diagrams', 'videos', 'video', 'cells', 'code', 'comments',
+  'charts', 'diagrams', 'videos', 'video', 'apps', 'app', 'cells', 'code', 'comments',
   'setup', 'safe', 'auto-update', 'refresh', 'upgrade',
   'bridge', 'feedback',
   'slides', 'present',
   'library',
+  'cloud',
   'color-analysis',
 ]);
 
@@ -54,8 +56,32 @@ function parseArgs(argv) {
   let yesFlag = false;
   let dryRunFlag = false;
   let sheetName = null;
+  let projectFlag = null;
+  let accountFlag = null;
+  let outputPath = null;
+  let revisionFlag = null;
+  let documentFlag = null;
+  let baseRevisionFlag = null;
+  let limitFlag = null;
+  let noOpenFlag = false;
+  let noBindFlag = false;
+  let forceFlag = false;
+  let everyoneFlag = false;
+  let onlyYouFlag = false;
+  let sharedWithMeFlag = false;
+  let noteText = null;
+  const memberFlags = [];
+  const documentFlags = [];
+  const tagFilters = [];
   const addTags = [];
   const annotations = [];
+  // Multi-file code walkthrough: every source-code positional is collected
+  // into `files`, in command order. `currentFile` is the cursor an annotation
+  // binds to, so `file1.py 4:"x" file2.py 13:"y"` ties line 4 to file1 and
+  // line 13 to file2. The first code file also fills the single-file `file`
+  // slot, so a one-file `sdoc app.py` is unchanged.
+  const files = [];
+  let currentFile = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -107,6 +133,26 @@ function parseArgs(argv) {
     if (arg === '--yes' || arg === '-y')             { yesFlag          = true; continue; }
     if (arg === '--dry-run')                         { dryRunFlag       = true; continue; }
     if (arg === '--sheet')                           { sheetName        = args[++i]; continue; }
+    if (arg === '--project')                         { projectFlag      = args[++i]; continue; }
+    if (arg === '--account')                         { accountFlag      = args[++i]; continue; }
+    if (arg === '--member')                          { memberFlags.push(args[++i]); continue; }
+    if (arg === '--everyone')                        { everyoneFlag     = true; continue; }
+    if (arg === '--only-you')                        { onlyYouFlag      = true; continue; }
+    if (arg === '--shared-with-me')                  { sharedWithMeFlag = true; continue; }
+    if (arg === '--note')                            { noteText = args[++i]; continue; }
+    if (arg === '--output' || arg === '-o')          { outputPath       = args[++i]; continue; }
+    if (arg === '--revision')                        { revisionFlag     = args[++i]; continue; }
+    if (arg === '--document') {
+      documentFlag = args[++i];
+      documentFlags.push(documentFlag);
+      continue;
+    }
+    if (arg === '--base-revision')                   { baseRevisionFlag = args[++i]; continue; }
+    if (arg === '--limit')                           { limitFlag        = Number(args[++i]); continue; }
+    if (arg === '--tag')                             { tagFilters.push(args[++i]); continue; }
+    if (arg === '--no-open')                         { noOpenFlag       = true; continue; }
+    if (arg === '--no-bind')                         { noBindFlag       = true; continue; }
+    if (arg === '--force')                           { forceFlag        = true; continue; }
 
     if (!subcommand && SUBCOMMANDS.has(arg)) {
       subcommand = arg;
@@ -127,11 +173,24 @@ function parseArgs(argv) {
       // Strip one layer of surrounding quotes if a shell preserved them.
       const text = ann[3].replace(/^"([\s\S]*)"$/, '$1').replace(/^'([\s\S]*)'$/, '$1');
       if (start >= 1 && end >= start && text.trim()) {
-        annotations.push({ line: start, endLine: end, text });
+        // `file` binds the annotation to the most-recently-named code file
+        // (null if none yet — resolved to the only/first file downstream).
+        annotations.push({ line: start, endLine: end, text, file: currentFile });
       }
       continue;
     }
 
+    // A source-code positional (in the default flow, not under a subcommand):
+    // collect it as a walkthrough file and move the annotation cursor onto it.
+    // Subcommand sub-args (e.g. `slides icons`) are never code files, so they
+    // fall through to the file/extra slots below as before.
+    if (!subcommand && codeLangs.isCodeFile(arg)) {
+      files.push(arg);
+      currentFile = arg;
+      if (!file) file = arg;
+      continue;
+    }
+
     if (!file) { file = arg; continue; }
     // Second positional is captured as `extra` so `sdoc slides icons heart`
     // gets {subcommand: 'slides', file: 'icons', extra: 'heart'}.
@@ -144,7 +203,10 @@ function parseArgs(argv) {
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
     tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
-    addTags, annotations,
+    projectFlag, accountFlag, outputPath, revisionFlag, documentFlag, baseRevisionFlag,
+    limitFlag, noOpenFlag, noBindFlag, forceFlag, tagFilters,
+    everyoneFlag, onlyYouFlag, sharedWithMeFlag, noteText, memberFlags, documentFlags,
+    addTags, annotations, files,
   };
 }
 
@@ -183,13 +245,45 @@ async function readContent(file) {
   return null; // no content — just open studio
 }
 
-function openBrowser(url) {
+// Read N source files into one code-walkthrough body: each unique file wrapped
+// in a ```<lang> <basename> fence, joined in command order. Returns the body
+// plus the de-duplicated basename list (the tab order). Tabs are keyed by
+// basename — a file named twice on the command line is one tab; two DIFFERENT
+// files sharing a basename is an error rather than a silent merge (and keeps
+// the shared front matter to safe basenames, matching the single-file `file:`).
+function readCodewalkContent(files) {
+  const parts = [];
+  const tabs = [];
+  const byBase = Object.create(null);
+  for (const f of files) {
+    const resolved = path.resolve(f);
+    const base = path.basename(f);
+    if (byBase[base]) {
+      if (byBase[base] !== resolved) {
+        console.error(`sdoc: a code walkthrough needs distinct file names — two files named "${base}"`);
+        process.exit(1);
+      }
+      continue; // same file referenced again → one tab
+    }
+    if (!fs.existsSync(resolved)) {
+      console.error(`sdoc: file not found: ${f}`);
+      process.exit(1);
+    }
+    byBase[base] = resolved;
+    tabs.push(base);
+    const raw = fs.readFileSync(resolved, 'utf-8');
+    parts.push(codeLangs.wrapCodeFile(raw, f, base));
+  }
+  return { body: parts.join('\n'), files: tabs };
+}
+
+function openBrowser(url, fallback) {
   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}`);
+    (fallback || console.log)(`Open in browser: ${url}`);
   }
 }
 
@@ -197,5 +291,6 @@ module.exports = {
   SUBCOMMANDS,
   parseArgs,
   readContent,
+  readCodewalkContent,
   openBrowser,
 };

package/lib/library-commands.js

@@ -30,16 +30,8 @@ function libraryDisable() {
 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
@@ -114,7 +106,7 @@ function libraryLs(opts) {
     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)`);
+      console.log(`(tip: open a file with \`sdoc <file> +tag\` to add and tag it)`);
       return;
     }
     console.log(`most frequent tags for tagged markdown files under ${scope} (tag - count):`);
@@ -132,7 +124,7 @@ function libraryLs(opts) {
   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)`);
+    console.log(`(tip: open a file with \`sdoc <file>\` to add it)`);
     return;
   }
 
@@ -209,8 +201,8 @@ async function libraryOpen() {
   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.');
+  console.log(`library: ${idx.entries.length} entries indexed` + (state.enabled === false ? ' (indexing disabled)' : ''));
+  if (!idx.entries.length) console.log('library: open a file with `sdoc <file>` to add it.');
   ensureAutostart();
   console.log(`library: agent at ${agentUrl} (ctrl-c to stop)`);
   openBrowser(pageUrl);
@@ -263,7 +255,6 @@ async function libraryCommand(opts) {
     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();
@@ -278,7 +269,7 @@ async function libraryCommand(opts) {
     }
     default:
       console.error(`sdoc library: unknown subcommand "${sub}"`);
-      console.error('usage: sdoc library [ls|enable|disable|status|rebuild|autostart|help]');
+      console.error('usage: sdoc library [ls|enable|disable|status|autostart|help]');
       process.exit(1);
   }
 }
@@ -300,7 +291,7 @@ function tapOpen(opts) {
 
 module.exports = {
   libraryCommand,
-  libraryEnable, libraryDisable, libraryStatus, libraryRebuild, libraryOpen,
+  libraryEnable, libraryDisable, libraryStatus, libraryOpen,
   libraryLs, libraryHelp,
   resolveProjectRoot, resolveLsScope, entriesUnderScope,
   tapOpen,

package/lib/library-scan.js

@@ -15,18 +15,13 @@ const paths     = require('./library-paths');
 const DEFAULT_MAX_SIZE = 1 * 1024 * 1024;
 
 const DIRNAME_BLOCKLIST = new Set([
-  'node_modules',
   '.git',
   '.svn',
   '.hg',
-  'dist',
-  'build',
-  'vendor',
   '.venv',
   '.next',
   '.cache',
   '__pycache__',
-  'target',
   '.gradle',
   '.idea',
   '.vscode',
@@ -46,6 +41,19 @@ const DIRNAME_BLOCKLIST = new Set([
   '.password-store',
 ]);
 
+// Directories skipped during scanning traversal for speed, but NOT blocked
+// from path-gating when opening an explicitly indexed file.
+const SCAN_SKIP_DIRNAMES = new Set([
+  'assets',
+  'graphify',
+  'node_modules',
+  'vendor',
+  'target',
+  'dist',
+  'build',
+  'venv',
+]);
+
 // File basenames that should never make it into the library, regardless
 // of which directory they live in or what extension they carry. Most of
 // these don't have a markdown extension and so the existing extension
@@ -129,8 +137,10 @@ function deniedByPattern(absPath) {
 }
 
 function shouldSkipDir(absDir, base, skipSet, exemptRoots) {
-  if (base.startsWith('.') && base !== '.' && base !== '..') return true;
+  // Exempt .sdocs so AI coding agent markdown artifacts are indexed
+  if (base.startsWith('.') && base !== '.' && base !== '..' && base !== '.sdocs') return true;
   if (DIRNAME_BLOCKLIST.has(base)) return true;
+  if (SCAN_SKIP_DIRNAMES.has(base)) return true;
   if (skipSet.has(absDir)) return true;
   // Skip ephemeral paths during descent unless we're inside a root that
   // the caller explicitly named (in which case they want it scanned).

package/lib/library-server.js

@@ -35,9 +35,8 @@ try {
 //   2. The deny-pattern list (SSH keys, .env, credentials.{json,...}
 //      and anything under .ssh/.aws/.gnupg/...).
 //   3. Library-membership: the real path must appear in the index.
-//      The index is what the user has explicitly opened with sdoc or
-//      placed under a scanned root; arbitrary paths outside that set
-//      are refused.
+//      The index contains files the user explicitly opened with sdoc;
+//      arbitrary paths outside that set are refused.
 //
 // Returns { ok: true, realPath } on pass, { ok: false, reason, status }
 // on refusal. Caller picks the HTTP status from `status`.
@@ -295,12 +294,6 @@ function createServer({ port } = {}) {
         return;
       }
 
-      if (req.method === 'POST' && route === '/api/library/rescan') {
-        const result = libIndex.scanAndIndex();
-        sendJson(res, 200, result);
-        return;
-      }
-
       // Serve the current contents of a local file. The editor page
       // uses this to refresh content after the URL-hash snapshot goes
       // stale (e.g. after the user edited tags then reloaded). Gated
@@ -319,9 +312,8 @@ function createServer({ port } = {}) {
       }
 
       // Re-index a single file. Called by the editor page after a Bridge
-      // save so the library catches up immediately (instead of waiting
-      // for the next manual scan). Pure read-then-index; never writes
-      // the file the path points at.
+      // save so the library catches up immediately. Pure read-then-index;
+      // never writes the file the path points at.
       if (req.method === 'POST' && route === '/api/library/reindex') {
         const body = await readBody(req);
         const filePath = body && body.path;