@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/helper/toml.js

@@ -0,0 +1,244 @@
+'use strict';
+
+// A deliberately generic, restricted TOML parser. It has no knowledge of Codex, or of any other
+// harness — it only understands the TOML subset needed to safely locate scalar keys and table
+// headers for a surgical, comment-preserving rewrite. It was extracted out of codex-config.js
+// (which is Codex-specific and is moving under src/adapters/codex/) so that non-Codex code, such
+// as the lifecycle layer, can parse TOML without depending on a harness-specific module.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/toml.js')` keeps working while the rest of the tree is still `.js`.
+
+                                            
+
+                     
+                    
+               
+                
+ 
+
+                      
+               
+                
+ 
+
+                      
+                  
+                                  
+                        
+ 
+
+                                                                
+
+                          
+                           
+                
+               
+ 
+
+function stripComment(line        )         {
+  let quote                = null;
+  let escape = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quote) {
+      if (escape) escape = false;
+      else if (char === '\\') escape = true;
+      else if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '#') return line.slice(0, i);
+  }
+  return line;
+}
+
+function splitAssignment(line        )                          {
+  let quote                = null;
+  let escape = false;
+  let depth = 0;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quote) {
+      if (escape) escape = false;
+      else if (char === '\\') escape = true;
+      else if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") quote = char;
+    else if (char === '[' || char === '{') depth++;
+    else if (char === ']' || char === '}') depth--;
+    else if (char === '=' && depth === 0) return [line.slice(0, i), line.slice(i + 1)];
+  }
+  return null;
+}
+
+function balanced(value        )          {
+  let quote                = null;
+  let escape = false;
+  let depth = 0;
+  for (const char of value) {
+    if (quote) {
+      if (escape) escape = false;
+      else if (char === '\\') escape = true;
+      else if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '[' || char === '{') depth++;
+    else if (char === ']' || char === '}') {
+      depth--;
+      if (depth < 0) return false;
+    }
+  }
+  return !quote && depth === 0;
+}
+
+function parseValue(raw        )             {
+  const value = raw.trim();
+  if (!value || !balanced(value)) throw new Error('invalid TOML value');
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^[+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(value)) return Number(value);
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    if (value[0] === '"') return JSON.parse(value);
+    return value.slice(1, -1);
+  }
+  // Valid TOML arrays/inline tables/datetime values do not need interpretation when unmanaged.
+  if (value.startsWith('[') || value.startsWith('{') || /^\d{4}-\d\d-\d\d(?:[Tt ].*)?$/.test(value)) return value;
+  throw new Error('unsupported or invalid TOML value');
+}
+
+const BARE_KEY = /^[A-Za-z0-9_-]+$/;
+
+/** Splits a TOML key path (`a.b`, `mcp_servers."my-server"`, `'lit'.x`) into its segments.
+ * Quoted segments are ordinary TOML — a table header like `[mcp_servers."timo-document-hub"]` is
+ * spec-valid — but this scanner previously matched bare keys only and rejected the whole file,
+ * making any config that used one unreadable. Returns null for anything it cannot represent
+ * faithfully, so every caller keeps failing closed rather than guessing at a rewrite.
+ *
+ * A dot *inside* a quoted segment is legal TOML (`"gpt-5.5" = 4`) and is preserved — see
+ * flattenKeyPath for how it is kept from colliding with a genuine path separator. */
+function parseKeyPath(raw        )                  {
+  const segments           = [];
+  let i = 0;
+  const skipSpace = () => { while (i < raw.length && (raw[i] === ' ' || raw[i] === '\t')) i += 1; };
+  skipSpace();
+  if (i >= raw.length) return null;
+  while (i < raw.length) {
+    let segment        ;
+    const quote = raw[i];
+    if (quote === '"' || quote === "'") {
+      i += 1;
+      let body = '';
+      while (i < raw.length && raw[i] !== quote) {
+        if (quote === '"' && raw[i] === '\\') { body += raw.slice(i, i + 2); i += 2; continue; }
+        body += raw[i]; i += 1;
+      }
+      if (raw[i] !== quote) return null;                       // unterminated
+      i += 1;
+      try { segment = quote === '"' ? JSON.parse(`"${body}"`) : body; } catch { return null; }
+    } else {
+      const start = i;
+      while (i < raw.length && raw[i] !== '.' && raw[i] !== ' ' && raw[i] !== '\t') i += 1;
+      segment = raw.slice(start, i);
+      if (!BARE_KEY.test(segment)) return null;
+    }
+    if (!segment) return null;
+    segments.push(segment);
+    skipSpace();
+    if (i >= raw.length) break;
+    if (raw[i] !== '.') return null;
+    i += 1;
+    skipSpace();
+    if (i >= raw.length) return null;                          // trailing dot
+  }
+  return segments.length ? segments : null;
+}
+
+/** Flattens key-path segments into the dotted string `entries` is keyed by, escaping any dot that
+ * lives *inside* a segment so it cannot be mistaken for a path separator — without this,
+ * `["a.b"]` and `[a.b]` collide and a surgical edit could rewrite the wrong line. Managed
+ * identities (normaliseDesired) are bare-key-only, so their flattened form is unchanged and
+ * lookups against them still match. */
+function flattenKeyPath(segments          )         {
+  return segments.map((segment) => segment.replace(/\\/g, '\\\\').replace(/\./g, '\\.')).join('.');
+}
+
+/** A conservative TOML scanner. It validates the subset needed to safely locate scalar keys;
+ * unsupported multi-line syntax fails closed rather than risking a destructive rewrite. `headers`
+ * lists each table header line in file order, so a caller never re-detects headers itself. */
+function parseToml(text        )             {
+  const lines = text.split(/\r?\n/);
+  let table           = [];
+  const entries = new Map                   ();
+  const headers               = [];
+  for (let index = 0; index < lines.length; index++) {
+    const clean = stripComment(lines[index]).trim();
+    if (!clean) continue;
+    // `[[array.of.tables]]` still fails closed: the inner capture starts with '[', which
+    // parseKeyPath rejects, so array-of-tables remains unsupported exactly as before.
+    const tableMatch = clean.match(/^\[(.+)\]$/);
+    if (tableMatch) {
+      const tablePath = parseKeyPath(tableMatch[1].trim());
+      if (!tablePath) throw new Error(`Malformed or unsupported TOML table on line ${index + 1}`);
+      table = tablePath;
+      headers.push({ line: index, table: flattenKeyPath(table) });
+      continue;
+    }
+    if (clean.startsWith('[')) throw new Error(`Malformed or unsupported TOML table on line ${index + 1}`);
+    const assignment = splitAssignment(clean);
+    if (!assignment) throw new Error(`Malformed TOML assignment on line ${index + 1}`);
+    const keyPath = parseKeyPath(assignment[0].trim());
+    if (!keyPath) throw new Error(`Unsupported TOML key on line ${index + 1}`);
+    let value            ;
+    try { value = parseValue(assignment[1]); } catch { throw new Error(`Malformed TOML value on line ${index + 1}`); }
+    const fullKey = flattenKeyPath([...table, ...keyPath]);
+    if (entries.has(fullKey)) throw new Error(`Duplicate TOML key '${fullKey}'`);
+    entries.set(fullKey, { value, line: index, table: flattenKeyPath(table) });
+  }
+  return { lines, entries, headers };
+}
+
+/** The table rules of TOML 1.0 that parseToml does not enforce, as found in `text`:
+ * `duplicate-table` when a table is opened by a second `[header]`, or by a `[header]` after dotted
+ * keys already defined it; `table-and-value` when one path is both a key's value and a table (by a
+ * header, or implied by a longer dotted key). `line` is the 1-based line of the second definition.
+ * Throws what parseToml throws. */
+function tableViolations(text        )                   {
+  parseToml(text);
+  const lines = text.split(/\r?\n/);
+  const violations                   = [];
+  const opened = new Set        ();
+  const dotted = new Set        ();
+  const tables = new Set        ();
+  const values = new Set        ();
+  const asTable = (segments          , line        ) => {
+    const flat = flattenKeyPath(segments);
+    if (values.has(flat)) violations.push({ kind: 'table-and-value', table: flat, line });
+    tables.add(flat);
+  };
+  let table           = [];
+  for (let index = 0; index < lines.length; index++) {
+    const clean = stripComment(lines[index]).trim();
+    if (!clean) continue;
+    const tableMatch = clean.match(/^\[(.+)\]$/);
+    if (tableMatch) {
+      table = parseKeyPath(tableMatch[1].trim()) ;
+      const flat = flattenKeyPath(table);
+      if (opened.has(flat) || dotted.has(flat)) violations.push({ kind: 'duplicate-table', table: flat, line: index + 1 });
+      opened.add(flat);
+      for (let length = 1; length <= table.length; length++) asTable(table.slice(0, length), index + 1);
+      continue;
+    }
+    const keyPath = parseKeyPath(splitAssignment(clean) [0].trim()) ;
+    for (let length = 1; length < keyPath.length; length++) {
+      const segments = [...table, ...keyPath.slice(0, length)];
+      dotted.add(flattenKeyPath(segments));
+      asTable(segments, index + 1);
+    }
+    const full = flattenKeyPath([...table, ...keyPath]);
+    if (tables.has(full)) violations.push({ kind: 'table-and-value', table: full, line: index + 1 });
+    values.add(full);
+  }
+  return violations;
+}
+
+module.exports = { parseToml, stripComment, tableViolations };

package/src/install/backup-set.js

@@ -0,0 +1,149 @@
+'use strict';
+// backup-set.js — the files a run backs up: every file its lifecycle plan is about to write or
+// delete, the scripts an adapter copies beside a change's target, the old copy a moved resource
+// leaves behind, and files a pending tombstone will sweep. Files holding only MCP entries stay out:
+// their ledger row, not a file copy, is how an entry is recovered, and the same file can hold the
+// harness's own state, which a rollback must never restore over. DoFlow's own records stay out too,
+// except the ones named in `records`: the ownership ledger rides along with the files, because a
+// rollback that restores files without the rows describing them leaves every later update and
+// remove refusing those files as modified outside DoFlow.
+// Reads only: it stats files and creates nothing.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../install/backup-set.js')` keeps working while the tree is still `.js`. The
+// `./backup` require carries `.ts` because backup migrated in the same slice.
+const fs = require('node:fs');
+const path = require('node:path');
+const { BackupError, scopeRelative } = require('./backup.js');
+
+const REASON_ORDER = ['change', 'companion', 'relocated-from', 'tombstone', 'snapshot', 'record'];
+
+function byCodePoint(a        , b        )         {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+/** What a set entry is on disk now, following links. */
+function statEntry(file        , fsImpl     )                                                             {
+  let stat;
+  try {
+    stat = fsImpl.statSync(file);
+  } catch (err     ) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return { kind: 'absent', size: null, mode: null };
+    throw new BackupError(`could not read ${file}: ${err.code || err.message}`);
+  }
+  if (stat.isFile()) return { kind: 'file', size: stat.size, mode: stat.mode & 0o7777 };
+  return { kind: 'other', size: null, mode: null };
+}
+
+function isAtOrUnder(file        , root        )          {
+  const resolved = path.resolve(root);
+  return file === resolved || file.startsWith(resolved.endsWith(path.sep) ? resolved : resolved + path.sep);
+}
+
+/** Candidates (absolute path -> harnesses and reasons) into a BackupSet, after the exclusions.
+ * A path in `records` is kept even under an excluded root. */
+function toBackupSet(candidates                  , { scope, scopeRoot, exclude, excluded, records = [], fsImpl }     )      {
+  const root = path.resolve(scopeRoot);
+  const kept = new Set(records.map((file        ) => path.resolve(file)));
+  const entries = [];
+  for (const file of [...candidates.keys()].sort(byCodePoint)) {
+    if (!kept.has(file) && exclude.some((x        ) => isAtOrUnder(file, x))) {
+      excluded.push({ path: file, reason: 'doflow-state' });
+      continue;
+    }
+    const { harnesses, reasons } = candidates.get(file);
+    entries.push({
+      path: file,
+      rel: scopeRelative(root, file),
+      harnesses: [...harnesses].sort(byCodePoint),
+      reasons: REASON_ORDER.filter((reason) => reasons.has(reason)),
+      ...statEntry(file, fsImpl),
+    });
+  }
+  const files = entries.filter((e) => e.kind === 'file');
+  return {
+    scope,
+    scopeRoot: root,
+    entries,
+    excluded: excluded.sort((a     , b     ) => byCodePoint(a.path, b.path)),
+    count: entries.length,
+    existing: files.length,
+    absent: entries.filter((e) => e.kind === 'absent').length,
+    bytes: files.reduce((sum, e) => sum + (e.size          ), 0),
+  };
+}
+
+function addCandidate(candidates                  , file        , harness               , reason        )       {
+  const key = path.resolve(file);
+  if (!candidates.has(key)) candidates.set(key, { harnesses: new Set(), reasons: new Set() });
+  const item = candidates.get(key);
+  if (harness) item.harnesses.add(harness);
+  item.reasons.add(reason);
+}
+
+/**
+ * The files a lifecycle plan's apply can overwrite or delete, as a BackupSet.
+ * `exclude` lists DoFlow's own paths (the backup root, the state root, the install manifest, the
+ * lock); an entry at or under one of them is reported in `excluded`, not backed up.
+ * `records` lists DoFlow record files backed up beside those files although an `exclude` root holds
+ * them (the ownership ledger), with no harness; a rollback restores only the ledger rows of the files
+ * it writes back (backup.ts mergeRestoredLedger). They join only a set that holds some file already,
+ * so a run that backs up nothing still backs up nothing.
+ */
+function backupSetFromPlan({ plan, scope, scopeRoot, exclude = [], records = [], fsImpl = fs }     )      {
+  const candidates = new Map();
+  const mcpOnly = new Map();
+  const resources = plan.ledger?.resources ?? [];
+  const tombstones = plan.ledger?.tombstones ?? [];
+  // A retained or released change gives up a ledger row and touches no file.
+  const changes = plan.changes.filter((change     ) => change.retained !== true && change.release !== true);
+
+  for (const change of changes) {
+    const target = path.resolve(change.target);
+    if (change.kind === 'mcp-server') {
+      if (!mcpOnly.has(target)) mcpOnly.set(target, true);
+      continue;
+    }
+    mcpOnly.set(target, false);
+    addCandidate(candidates, target, change.harness, 'change');
+    for (const companion of change.companionTargets ?? []) {
+      if (typeof companion === 'string') addCandidate(candidates, companion, change.harness, 'companion');
+    }
+    if ((change.operation === 'create' || change.operation === 'update') && typeof change.identity === 'string') {
+      for (const resource of resources) {
+        if (resource.harness !== change.harness || resource.assetId !== change.assetId || resource.identity !== change.identity) continue;
+        if (resource.kind === 'mcp-server' || typeof resource.target !== 'string') continue;
+        if (path.resolve(resource.target) === target || !fsImpl.existsSync(resource.target)) continue;
+        addCandidate(candidates, resource.target, resource.harness, 'relocated-from');
+      }
+    }
+  }
+
+  const owned = new Set(resources.filter((r     ) => typeof r.target === 'string').map((r     ) => path.resolve(r.target)));
+  for (const tombstone of tombstones) {
+    if (tombstone.sweptAt || typeof tombstone.fromTarget !== 'string') continue;
+    if (owned.has(path.resolve(tombstone.fromTarget)) || !fsImpl.existsSync(tombstone.fromTarget)) continue;
+    addCandidate(candidates, tombstone.fromTarget, tombstone.harness, 'tombstone');
+  }
+
+  const excluded = [...mcpOnly]
+    .filter(([target, onlyMcp]) => onlyMcp && !candidates.has(target))
+    .map(([target]) => ({ path: target, reason: 'mcp-entries-only' }));
+  if (candidates.size) for (const file of records) addCandidate(candidates, file, null, 'record');
+  return toBackupSet(candidates, { scope, scopeRoot, exclude, excluded, records, fsImpl });
+}
+
+/** A BackupSet of the given absolute paths, for the pre-rollback snapshot. `records` as for
+ * backupSetFromPlan: a restored ledger is snapshotted too, so the snapshot rolls back as a whole. */
+function backupSetFromPaths({ items, scope, scopeRoot, exclude = [], records = [], fsImpl = fs }     )      {
+  const candidates = new Map();
+  for (const item of items) {
+    if (item.harnesses.length === 0) addCandidate(candidates, item.path, null, 'snapshot');
+    for (const harness of item.harnesses) addCandidate(candidates, item.path, harness, 'snapshot');
+  }
+  return toBackupSet(candidates, { scope, scopeRoot, exclude, excluded: [], records, fsImpl });
+}
+
+module.exports = { backupSetFromPlan, backupSetFromPaths };