sdocs-dev 1.14.1 → 1.18.0

package/lib/agent-files.js

@@ -1,40 +1,39 @@
-// Per-file refresh of the SDocs agent block.
+// SmallDocs skill install + legacy-block migration.
 //
-// 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.
+// One canonical SKILL.md lives at ~/.agents/skills/smalldocs/SKILL.md.
+// Every other supported agent gets a relative symlink from its own skills
+// directory into the canonical dir (single source of truth; one write
+// updates every agent). Universal agents already discover ~/.agents/skills,
+// so they are skipped. Windows falls back to a junction (absolute target),
+// then a copy if symlinks are unavailable.
+//
+// On setup/refresh we also strip any recognised always-on block from the
+// historical agent config files so the reference is not loaded twice.
 
 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,
+  SKILL_VERSION,
+  SKILL_NAME,
+  formatSkill,
+  readSkillVersion,
+  readSkillEdition,
+  canonicalSkillDir,
+  canonicalSkillFile,
+  resolveSkillAgents,
+  legacyBlockTargets,
   findBookendedBlock,
-  refreshContent,
+  findLegacyBlock,
+  removeBlockContent,
 } = 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));
-}
+const IS_WIN = process.platform === 'win32';
 
-function fileHasBlock(filePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    return findBookendedBlock(content) !== null
-        || content.includes(AGENT_BLOCK_LEGACY_OPEN);
-  } catch (_) { return false; }
-}
+// ── generic file helpers ───────────────────────────────────
 
 function isSymlink(filePath) {
   try { return fs.lstatSync(filePath).isSymbolicLink(); }
@@ -84,79 +83,314 @@ function acquireLock(filePath) {
   }
 }
 
-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;
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(s, d);
+    else fs.copyFileSync(s, d);
   }
-  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' };
+// Compare filesystem identity, not just path spelling. Agent skill parents
+// are sometimes symlinked to ~/.agents/skills; in that case two different
+// path strings can name the exact same skill directory.
+function pathsResolveSame(a, b) {
+  try { return fs.realpathSync(a) === fs.realpathSync(b); }
+  catch (_) {}
+
+  function withRealParent(p) {
+    const resolved = path.resolve(p);
+    try { return path.join(fs.realpathSync(path.dirname(resolved)), path.basename(resolved)); }
+    catch (_) { return resolved; }
+  }
+  return withRealParent(a) === withRealParent(b);
+}
 
-  const release = acquireLock(filePath);
-  if (!release)                                    return { path: filePath, changed: false, reason: 'locked' };
+// ── canonical skill ────────────────────────────────────────
 
+function refreshCanonicalSkill(home) {
+  home = home || os.homedir();
+  const file = canonicalSkillFile(home);
+  let existing = null;
   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);
+    const st = fs.lstatSync(file);
+    if (!st.isFile()) {
+      return {
+        changed: false, reason: 'conflict', path: file,
+        error: 'existing canonical SKILL.md is not a regular SmallDocs-managed file; left untouched',
+      };
+    }
+    existing = fs.readFileSync(file, 'utf-8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      return { changed: false, reason: 'error', path: file, error: e.message };
+    }
+  }
+  const currentVersion = existing ? readSkillVersion(existing) : null;
+  const currentEdition = existing ? readSkillEdition(existing) : 'standard';
+  if (existing !== null && currentVersion === null) {
     return {
-      path: filePath, changed: true,
-      fromVersion: result.fromVersion, toVersion: result.toVersion,
+      changed: false, reason: 'conflict', path: file,
+      error: 'existing canonical SKILL.md is not managed by SmallDocs; left untouched',
     };
+  }
+  if (currentVersion === SKILL_VERSION) {
+    return { changed: false, reason: 'current', path: file };
+  }
+  if (currentVersion !== null && currentVersion > SKILL_VERSION) {
+    return { changed: false, reason: 'newer', path: file };
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  atomicWrite(file, formatSkill(SKILL_VERSION, { cloud: currentEdition === 'cloud' }));
+  return {
+    changed: true, path: file,
+    fromVersion: currentVersion || 0, toVersion: SKILL_VERSION,
+  };
+}
+
+// ── symlink install ────────────────────────────────────────
+
+// A real directory at an agent skills path is only safe to replace if it looks
+// like one of our own copy-fallback installs (a prior Windows run, or a system
+// where symlinks are unavailable): it must contain a SKILL.md carrying our
+// sdocs-skill marker. Anything else is user content we must not destroy.
+function looksLikeOurSkillDir(dir) {
+  try {
+    const content = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf-8');
+    return readSkillVersion(content) !== null;
+  } catch (_) { return false; }
+}
+
+// Ensure <linkDir> resolves to <canonicalDir>. Idempotent: a link already
+// pointing at canonical is a no-op; a wrong/stale symlink is replaced. A real
+// directory is replaced only if it is recognisably one of our copy-fallback
+// installs. Other directories and files are left untouched (returns an error)
+// so the user's own content is never clobbered. Returns { method } where
+// method is symlink | copy | noop | error.
+function ensureSkillLink(canonicalDir, linkDir) {
+  if (pathsResolveSame(canonicalDir, linkDir)) return { method: 'noop' };
+
+  try {
+    const st = fs.lstatSync(linkDir);
+    if (st.isSymbolicLink()) {
+      const tgt = fs.readlinkSync(linkDir);
+      const resolved = path.resolve(path.dirname(linkDir), tgt);
+      if (resolved === canonicalDir) return { method: 'noop' };
+      // Stale/wrong symlink: safe to remove (a link holds no user data).
+      fs.rmSync(linkDir, { recursive: true, force: true });
+    } else if (st.isDirectory()) {
+      if (!looksLikeOurSkillDir(linkDir)) {
+        return { method: 'error', error: 'exists and is not a SmallDocs skill directory; left untouched' };
+      }
+      fs.rmSync(linkDir, { recursive: true, force: true });
+    } else {
+      return { method: 'error', error: 'exists and is not a SmallDocs skill directory; left untouched' };
+    }
   } catch (e) {
-    return { path: filePath, changed: false, error: e.message };
-  } finally {
-    release();
+    if (e.code !== 'ENOENT') return { method: 'error', error: e.message };
+  }
+
+  try { fs.mkdirSync(path.dirname(linkDir), { recursive: true }); }
+  catch (e) { return { method: 'error', error: e.message }; }
+
+  // Relative symlink on POSIX so it survives a home-dir move; junction on
+  // Windows requires an absolute target.
+  try {
+    let target = path.resolve(canonicalDir);
+    let linkParent = path.resolve(path.dirname(linkDir));
+    try { target = fs.realpathSync(canonicalDir); } catch (_) {}
+    try { linkParent = fs.realpathSync(path.dirname(linkDir)); } catch (_) {}
+    if (IS_WIN) {
+      fs.symlinkSync(target, linkDir, 'junction');
+    } else {
+      const rel = path.relative(linkParent, target);
+      fs.symlinkSync(rel, linkDir, 'dir');
+    }
+    return { method: 'symlink' };
+  } catch (_) {
+    // Permission / non-admin Windows: fall back to a real copy.
+    try {
+      copyDirRecursive(canonicalDir, linkDir);
+      return { method: 'copy' };
+    } catch (e) {
+      return { method: 'error', error: e.message };
+    }
+  }
+}
+
+function detectSkillAgents(home, env) {
+  home = home || os.homedir();
+  return resolveSkillAgents(home, env || process.env)
+    .filter(a => a.detect.some(p => { try { return fs.existsSync(p); } catch (_) { return false; } }));
+}
+
+// Evidence that the user previously opted into SmallDocs setup: a skill file
+// already on disk (prior skill install), or a recognised always-on block in one
+// of the historical config files (pre-skill install). maybeAutoRefresh uses
+// this so a brand-new user is NOT auto-installed without consent - they get the
+// interactive first-run prompt (or run `sdoc setup --yes`) instead.
+function hasSetupEvidence(home, env) {
+  home = home || os.homedir();
+  env = env || process.env;
+  try {
+    const content = fs.readFileSync(canonicalSkillFile(home), 'utf-8');
+    if (readSkillVersion(content) !== null) return true;
+  } catch (_) {}
+  for (const t of legacyBlockTargets(home, env)) {
+    let content;
+    try { content = fs.readFileSync(t.file, 'utf-8'); } catch (_) { continue; }
+    if (findBookendedBlock(content) || findLegacyBlock(content)) return true;
+  }
+  return false;
+}
+
+// ── legacy block stripping ─────────────────────────────────
+
+function stripLegacyBlocks(home, env) {
+  home = home || os.homedir();
+  const out = [];
+
+  function skippedTarget(t, reason) {
+    try {
+      const content = fs.readFileSync(t.file, 'utf-8');
+      const hasBlock = !!(findBookendedBlock(content) || findLegacyBlock(content));
+      return {
+        name: t.name, file: t.file, changed: false, reason,
+        error: hasBlock ? `${reason}; recognised legacy SmallDocs block left untouched` : undefined,
+      };
+    } catch (e) {
+      return { name: t.name, file: t.file, changed: false, reason, error: e.message };
+    }
+  }
+
+  for (const t of legacyBlockTargets(home, env || process.env)) {
+    if (!fs.existsSync(t.file))                    { out.push({ name: t.name, file: t.file, changed: false, reason: 'absent' });   continue; }
+    if (isSymlink(t.file))                          { out.push(skippedTarget(t, 'symlink')); continue; }
+
+    const release = acquireLock(t.file);
+    if (!release)                                   { out.push(skippedTarget(t, 'locked'));  continue; }
+    try {
+      const content = fs.readFileSync(t.file, 'utf-8');
+      const r = removeBlockContent(content);
+      if (!r.changed)                              { out.push({ name: t.name, file: t.file, changed: false, reason: r.reason });   continue; }
+      backupFile(t.file);
+      atomicWrite(t.file, r.content);
+      out.push({ name: t.name, file: t.file, changed: true, fromVersion: r.version });
+    } catch (e) {
+      out.push({ name: t.name, file: t.file, changed: false, error: e.message });
+    } finally {
+      release();
+    }
   }
+  return out;
 }
 
-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) };
-  });
+// ── orchestration ──────────────────────────────────────────
+
+// One call that does the full sync: refresh canonical skill, symlink every
+// detected non-universal agent, strip legacy blocks. Returns a result the
+// setup flow reports and derives setup-state from.
+function syncAgentSkill(opts = {}) {
+  const home = opts.home || os.homedir();
+  const env = opts.env || process.env;
+  const canonicalDir = canonicalSkillDir(home);
+
+  const result = {
+    canonical: refreshCanonicalSkill(home),
+    links: [],
+    stripped: [],
+    errors: [],
+  };
+
+  if (result.canonical.error) {
+    result.errors.push(`${result.canonical.path}: ${result.canonical.error}`);
+    return result;
+  }
+
+  for (const agent of detectSkillAgents(home, env)) {
+    if (agent.universal) continue; // canonical copy already covers them
+    const linkDir = path.join(agent.dir, SKILL_NAME);
+    const r = ensureSkillLink(canonicalDir, linkDir);
+    result.links.push({ name: agent.displayName, path: linkDir, ...r });
+    if (r.error) result.errors.push(`${agent.name}: ${r.error}`);
+  }
+
+  // Keep the legacy instructions in place unless every required skill link
+  // succeeded. They are the safe fallback if an agent-specific path collides
+  // with user content or cannot be written.
+  if (result.errors.length) return result;
+
+  result.stripped = stripLegacyBlocks(home, env);
+  for (const s of result.stripped) {
+    if (s.error) result.errors.push(`${s.file}: ${s.error}`);
+  }
+
+  return result;
+}
+
+// True if a sync changed anything (skill written/upgraded, a link created,
+// or a block stripped). Drives the "nothing to do" message and setup state.
+function syncChanged(result) {
+  if (result.canonical && result.canonical.changed) return true;
+  if (result.links.some(l => l.method === 'symlink' || l.method === 'copy')) return true;
+  if (result.stripped.some(s => s.changed)) return true;
+  return false;
+}
+
+// Flatten a sync result into the {path, changed, error?} shape that
+// implicitConsentState expects.
+function toImplicitResults(result) {
+  const arr = [];
+  if (result.canonical) {
+    arr.push({ path: result.canonical.path, changed: !!result.canonical.changed, error: result.canonical.error });
+  }
+  for (const l of result.links) {
+    arr.push({ path: l.path, changed: l.method === 'symlink' || l.method === 'copy', error: l.error });
+  }
+  for (const s of result.stripped) {
+    arr.push({ path: s.file, changed: s.changed, error: s.error });
+  }
+  return arr;
 }
 
-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}`);
+function printSyncSummary(result) {
+  if (result.canonical && result.canonical.changed) {
+    console.log(`\u2713 SmallDocs skill updated to v${SKILL_VERSION} at ${result.canonical.path}`);
+    console.log(`  Changes: ${AGENT_CHANGES_URL}#v${SKILL_VERSION}`);
   }
-  for (const r of results.filter(r => r.error)) {
-    console.log(`! ${r.path}: ${r.error}`);
+  if (result.canonical && result.canonical.error) {
+    console.log(`! ${result.canonical.path}: ${result.canonical.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 l of result.links) {
+    if (l.method === 'symlink' || l.method === 'copy') {
+      console.log(`\u2713 ${l.name}: ${l.path} (${l.method})`);
+    }
+    if (l.error) console.log(`! ${l.name}: ${l.error}`);
   }
-  for (const r of results.filter(r => r.reason === 'hand_edited')) {
-    console.log(`! ${r.path}: local edits detected, run \`sdoc setup\` to refresh manually`);
+  for (const s of result.stripped) {
+    if (s.changed)    console.log(`\u2713 removed old SmallDocs block from ${s.file}`);
+    if (s.error)      console.log(`! ${s.file}: ${s.error}`);
+    if (s.reason === 'hand_edited') console.log(`! ${s.file}: local edits detected, left untouched`);
   }
 }
 
 module.exports = {
-  detectAgents,
-  fileHasBlock,
+  IS_WIN,
   isSymlink,
   atomicWrite,
   backupFile,
   acquireLock,
-  writeBookendedBlock,
-  refreshAgentFile,
-  refreshAllAgentFiles,
-  printRefreshSummary,
+  copyDirRecursive,
+  refreshCanonicalSkill,
+  ensureSkillLink,
+  looksLikeOurSkillDir,
+  detectSkillAgents,
+  hasSetupEvidence,
+  stripLegacyBlocks,
+  syncAgentSkill,
+  syncChanged,
+  toImplicitResults,
+  printSyncSummary,
 };

package/lib/cells-verify.js

@@ -86,6 +86,7 @@ function valuesFor(model, fxGrid) {
         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 if (fx.kind === 'boolean') row.push(fx.value ? 'TRUE' : 'FALSE');
         else row.push('');
       } else {
         row.push(cell.raw);

package/lib/cloud-bindings.js

@@ -0,0 +1,85 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const credentials = require('./cloud-credentials');
+
+function bindingsFile() { return path.join(credentials.cloudDir(), 'bindings.json'); }
+function pendingFile() { return path.join(credentials.cloudDir(), 'pending.json'); }
+function basesDir() { return path.join(credentials.cloudDir(), 'bases'); }
+
+function read(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return {}; }
+}
+
+function canonical(file) {
+  const absolute = path.resolve(file);
+  try { return fs.realpathSync(absolute); } catch (_) { return absolute; }
+}
+
+function key(accountId, file) { return accountId + '\0' + canonical(file); }
+function get(accountId, file) { return read(bindingsFile())[key(accountId, file)] || null; }
+
+function set(accountId, file, binding) {
+  const values = read(bindingsFile());
+  values[key(accountId, file)] = { ...binding, account_id: accountId, path: canonical(file) };
+  credentials.atomicWrite(bindingsFile(), values);
+  return values[key(accountId, file)];
+}
+
+function getPending(accountId, file) { return read(pendingFile())[key(accountId, file)] || null; }
+function setPending(accountId, file, value) {
+  const values = read(pendingFile());
+  values[key(accountId, file)] = value;
+  credentials.atomicWrite(pendingFile(), values);
+}
+function clearPending(accountId, file) {
+  const values = read(pendingFile());
+  delete values[key(accountId, file)];
+  credentials.atomicWrite(pendingFile(), values);
+}
+
+function operationKey(accountId, operation, resourceId) {
+  return accountId + '\0operation:' + operation + '\0' + resourceId;
+}
+function getOperationPending(accountId, operation, resourceId) {
+  return read(pendingFile())[operationKey(accountId, operation, resourceId)] || null;
+}
+function setOperationPending(accountId, operation, resourceId, value) {
+  const values = read(pendingFile());
+  values[operationKey(accountId, operation, resourceId)] = value;
+  credentials.atomicWrite(pendingFile(), values);
+}
+function clearOperationPending(accountId, operation, resourceId) {
+  const values = read(pendingFile());
+  delete values[operationKey(accountId, operation, resourceId)];
+  credentials.atomicWrite(pendingFile(), values);
+}
+
+function hash(content) { return crypto.createHash('sha256').update(content).digest('hex'); }
+
+function baseFile(accountId, documentId, revisionId) {
+  const root = path.resolve(basesDir());
+  const file = path.resolve(root, String(accountId), String(documentId), String(revisionId) + '.md');
+  if (file !== root && !file.startsWith(root + path.sep)) return null;
+  return file;
+}
+
+function cacheBase(accountId, documentId, revisionId, content) {
+  const file = baseFile(accountId, documentId, revisionId);
+  if (!file) throw new Error('Cloud base path is invalid');
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, content, { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+  return file;
+}
+
+function readBase(accountId, documentId, revisionId) {
+  const file = baseFile(accountId, documentId, revisionId);
+  if (!file) return null;
+  try { return fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
+}
+
+module.exports = { bindingsFile, pendingFile, canonical, get, set, getPending, setPending,
+  clearPending, getOperationPending, setOperationPending, clearOperationPending, hash, cacheBase,
+  readBase };