@rjfan/dsh-presence 0.18.0 → 0.20.1

package/src/destructive.js

@@ -8,6 +8,16 @@
 //      `git clean` -> dry run) so nothing is removed,
 //   3. refuses unset variables, workspace roots/ancestors, home, `/` and `.git`,
 //   4. otherwise returns a report of the resolved targets and requires confirm.
+//
+// 0.19.0 adds two things the P0 feedback asked for:
+//   5. a top-level split of the command line (`;`, `&&`, `||`, newlines outside
+//      quotes), so a rejected mixed command can list the segments that are safe
+//      to run on their own (`confirm:"partial"`), and
+//   6. a single-file exemption: exactly `rm -f <literal path>` for a path that
+//      resolves inside the session workspace runs directly — it cannot remove a
+//      tree, which is what the guard exists to stop.
+
+import { posix } from 'node:path';
 
 export function shq(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
@@ -66,6 +76,176 @@ export function shellWords(text) {
   return words;
 }
 
+/**
+ * Split one command line on top-level `;`, `&&`, `||` and newlines.
+ *
+ * Quotes (`'`, `"`, backtick), backslash escapes and `(...)` / `$(...)` nesting
+ * are honoured, so `echo "a; b"` and `echo "$(a; b)"` stay one segment. A lone
+ * `&` or `|` is a background/pipeline operator rather than a sequence boundary,
+ * so it stays inside its segment; that keeps the unit conservative (the whole
+ * pipeline is one destructive or one safe segment).
+ *
+ * @returns {string[]} trimmed, non-empty segments in command order.
+ */
+export function splitShellSegments(command) {
+  const text = String(command ?? '');
+  const segments = [];
+  let current = '';
+  let quote = null;
+  let depth = 0;
+  const flush = () => {
+    const segment = current.trim();
+    if (segment) segments.push(segment);
+    current = '';
+  };
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote === "'") {
+      current += character;
+      if (character === "'") quote = null;
+      continue;
+    }
+    if (quote === '"' || quote === '`') {
+      current += character;
+      if (character === '\\' && index + 1 < text.length) {
+        current += text[index + 1];
+        index += 1;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === '\\' && index + 1 < text.length) {
+      // An escaped operator is a literal character, not a boundary.
+      current += character + text[index + 1];
+      index += 1;
+      continue;
+    }
+    if (character === "'" || character === '"' || character === '`') {
+      quote = character;
+      current += character;
+      continue;
+    }
+    if (character === '(') {
+      depth += 1;
+      current += character;
+      continue;
+    }
+    if (character === ')') {
+      if (depth > 0) depth -= 1;
+      current += character;
+      continue;
+    }
+    if (depth === 0) {
+      if (character === ';' || character === '\n' || character === '\r') {
+        flush();
+        continue;
+      }
+      if (character === '&' && text[index + 1] === '&') {
+        flush();
+        index += 1;
+        continue;
+      }
+      if (character === '|' && text[index + 1] === '|') {
+        flush();
+        index += 1;
+        continue;
+      }
+    }
+    current += character;
+  }
+  flush();
+  return segments;
+}
+
+/** Characters that make a path non-literal (glob, expansion, redirect, chaining). */
+const NOT_LITERAL_PATH = /[*?[\]$;&|<>`(){}\\~\n\r]/;
+
+/**
+ * The path of an exact `rm -f <one literal path>` command, or null.
+ *
+ * The exemption is intentionally narrow: a different verb/mount, `-r`, an
+ * extra operand, a glob, a variable, a redirect, a pipeline or a second
+ * command all keep the normal guard path.
+ */
+export function singleRmTarget(command) {
+  const text = String(command ?? '');
+  if (NOT_LITERAL_PATH.test(text)) return null;
+  const words = shellWords(text);
+  if (words.length !== 3) return null;
+  if (words[0] !== 'rm' || words[1] !== '-f') return null;
+  const target = words[2];
+  if (!target || target.startsWith('-')) return null;
+  return target;
+}
+
+function withoutTrailingSlashes(value) {
+  const text = String(value);
+  if (text === '/') return '/';
+  return text.replace(/\/+$/, '');
+}
+
+/** Absolute, lexically normalised form of `target` relative to `cwd`. */
+function absoluteRemotePath(cwd, target) {
+  if (!cwd || !target) return null;
+  try {
+    return posix.normalize(posix.join(String(cwd), String(target)));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when `target` is deletable under the exemption: inside the workspace,
+ * but neither the workspace root itself nor an ancestor of it.
+ */
+export function isDeletableWorkspaceFile(target, workspaceRoot) {
+  const path = withoutTrailingSlashes(target);
+  const base = withoutTrailingSlashes(workspaceRoot);
+  if (!path.startsWith('/') || !base.startsWith('/')) return false;
+  if (path === base) return false;
+  // `path` is an ancestor of the workspace root (e.g. `/tmp` for `/tmp/ws`).
+  if (base.startsWith(`${path}/`)) return false;
+  return path.startsWith(`${base}/`);
+}
+
+/** Resolve a remote path through symlinks; falls back to the parent directory. */
+async function resolveRemotePath(connection, target, cwd) {
+  const script =
+    `cd ${shq(cwd)} || exit 0; p=${shq(target)}; ` +
+    `r=$(realpath -m -- "$p" 2>/dev/null || readlink -f -- "$p" 2>/dev/null); ` +
+    `[ -n "$r" ] || r=$(cd "$(dirname -- "$p")" 2>/dev/null && printf '%s/%s' "$PWD" "$(basename -- "$p")"); ` +
+    `printf '%s\\n' "$r"`;
+  try {
+    const result = await connection.exec(`bash -c ${shq(script)}`, { timeoutMs: 15_000 });
+    const line = String(result.stdout ?? '')
+      .split('\n')
+      .map((value) => value.trim())
+      .filter(Boolean)[0];
+    return line ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The 0.19.0 single-file exemption: `rm -f <one literal path>` for a path that
+ * resolves inside the workspace, is not the workspace root and cannot be an
+ * ancestor of it. Symlinks are resolved first, so a link inside the workspace
+ * that points outside is not exempt.
+ */
+async function exemptSingleFileRm({ connection, command, cwd, workspace }) {
+  const workspaceRoot = workspace?.path ?? null;
+  if (!cwd || !workspaceRoot) return false;
+  const target = singleRmTarget(command);
+  if (!target) return false;
+  const lexical = absoluteRemotePath(cwd, target);
+  if (!lexical) return false;
+  const resolved = await resolveRemotePath(connection, target, cwd);
+  const candidate = resolved && resolved.startsWith('/') ? posix.normalize(resolved) : lexical;
+  return isDeletableWorkspaceFile(candidate, workspaceRoot);
+}
+
 function isWithin(parent, child) {
   if (!parent) return false;
   const base = parent.replace(/\/+$/, '');
@@ -74,6 +254,13 @@ function isWithin(parent, child) {
 
 /** Run the command in a shell where the destructive verb only reports. */
 async function dryRunDestructive(connection, command, kind, cwd) {
+  if (kind === 'truncate') {
+    // There is no safe replay for these verbs: `shred`/`truncate`/`mkfs`/`dd of=`
+    // write for real and a `:>` redirect cannot be shadowed. Never execute them
+    // in the dry run; report that targets cannot be resolved instead of doing
+    // the damage while claiming "nothing was executed".
+    return { targets: [], stderr: '', code: 0, skipped: true };
+  }
   let probe;
   if (kind === 'rm') {
     probe =
@@ -136,27 +323,71 @@ async function describeTargets(connection, targets, cwd) {
     });
 }
 
+/**
+ * Classify every top-level segment so a rejected command can say which parts
+ * were safe. `targets` is best effort: a segment that depends on an earlier
+ * assignment (`J=""; rm -rf $J`) cannot be dry-run on its own, so it stays empty
+ * instead of guessing.
+ */
+async function describeSplit({ connection, command, cwd, kind, resolved }) {
+  const safeSegments = [];
+  const destructiveSegments = [];
+  for (const segment of splitShellSegments(command)) {
+    const segmentKind = destructiveKind(segment);
+    if (segmentKind) destructiveSegments.push({ segment, kind: segmentKind, targets: [] });
+    else safeSegments.push(segment);
+  }
+  if (destructiveSegments.length === 0) {
+    // The classifier matched across a line break the splitter treats as a
+    // boundary; keep the whole command as the single destructive unit.
+    destructiveSegments.push({ segment: String(command).trim(), kind, targets: [] });
+  }
+  if (destructiveSegments.length === 1 && safeSegments.length === 0) {
+    // The whole command is the destructive segment: reuse the targets the
+    // guard already resolved instead of dry-running it a second time.
+    destructiveSegments[0].targets = resolved;
+    return { safeSegments, destructiveSegments };
+  }
+  for (const entry of destructiveSegments) {
+    try {
+      const segmentDry = await dryRunDestructive(connection, entry.segment, entry.kind, cwd);
+      entry.targets = await describeTargets(connection, segmentDry.targets, cwd);
+    } catch {
+      entry.targets = [];
+    }
+  }
+  return { safeSegments, destructiveSegments };
+}
+
 /**
  * Gate one destructive command.
  *
- * Returns null for a benign command (= run it), a report object for a destructive
- * command without confirmation (= do not run, show the report), and throws for
- * the unrecoverable cases (unset variable, workspace root/ancestor, home, `/`,
- * `.git`) regardless of confirmation.
+ * Returns null for a benign command (= run it) or for the single-file `rm -f`
+ * exemption, a report object for a destructive command without confirmation
+ * (= do not run, show the report), and throws for the unrecoverable cases
+ * (unset variable, workspace root/ancestor, home, `/`, `.git`) regardless of
+ * confirmation.
  *
  * @param connection - live PresenceConnection.
  * @param command - the raw command line.
  * @param cwd - remote working directory, or null.
  * @param workspace - `{ path }` of the session workspace, or null.
  * @param host - alias used in messages.
- * @param confirm - the caller already saw a report and asked to proceed.
+ * @param confirm - the caller already saw a report and asked to proceed
+ *   (`true` = whole command, `'partial'` = the caller runs split.safeSegments).
  */
 export async function guardDestructive({ connection, command, cwd = null, workspace = null, host = 'remote', confirm = false }) {
   const kind = destructiveKind(command);
   if (!kind) return null;
 
+  // 0.19.0: removing one generated file with `rm -f` is the everyday case; the
+  // guard exists to stop tree deletions. Everything that is not exactly
+  // `rm -f <literal path>` inside the workspace keeps the full guard below.
+  if (await exemptSingleFileRm({ connection, command, cwd, workspace })) return null;
+
   const dry = await dryRunDestructive(connection, command, kind, cwd);
   const resolved = await describeTargets(connection, dry.targets, cwd);
+  const split = await describeSplit({ connection, command, cwd, kind, resolved });
   const home = await connection.homePath().catch(() => null);
   const workspaceRoot = workspace?.path ?? null;
 
@@ -174,20 +405,42 @@ export async function guardDestructive({ connection, command, cwd = null, worksp
     );
   }
 
-  const report = [
+  const targetsLine =
+    resolved.length > 0
+      ? 'resolved targets:'
+      : dry.skipped
+        ? `resolved targets: (not resolvable without doing it - ${kind} commands are never replayed)`
+        : 'resolved targets: (none - the command would touch nothing)';
+  const safeLines = split.safeSegments.length > 0 ? split.safeSegments.map((segment) => `  ${segment}`) : ['  (none)'];
+  const confirmHint =
+    split.safeSegments.length > 0
+      ? 'Pass confirm:true to run the whole command, confirm:"partial" to run only the safe segments, ' +
+        'or use presence_trash for a recoverable delete.'
+      : 'Pass confirm:true to run the whole command, or use presence_trash for a recoverable delete.';
+
+  const lines = [
+    'Nothing was executed — the whole command was skipped, including non-destructive parts.',
     `destructive command needs confirmation (${kind}): nothing was executed yet`,
     `host: ${host}`,
     `command: ${String(command).replace(/\s+/g, ' ').slice(0, 400)}`,
     cwd ? `cwd: ${cwd}` : null,
-    resolved.length > 0 ? 'resolved targets:' : 'resolved targets: (none - the command would touch nothing)',
+    targetsLine,
     ...resolved.map((entry) => `  ${entry.type}  ${entry.path}  ${entry.entries}  ${entry.size}`),
-    confirm
-      ? null
-      : 'Pass confirm:true to execute it. Prefer presence_trash when the files are in a workspace (recoverable).',
-  ].filter(Boolean);
+    '',
+    'Safe segments you can run separately:',
+    ...safeLines,
+  ];
+  if (!confirm) lines.push('', confirmHint);
 
   // `targets` is the machine-readable twin of the report's target block:
   // callers that answer in JSON (presence_exec format:'json') do not need to
   // parse the text, and existing callers keep reading `report`/`resolved`.
-  return { kind, report: report.join('\n'), resolved, targets: resolved };
+  // `split` lets the caller run only the safe segments (confirm:"partial").
+  return {
+    kind,
+    report: lines.filter((line) => line !== null && line !== undefined).join('\n'),
+    resolved,
+    targets: resolved,
+    split,
+  };
 }

package/src/intercept.js

@@ -8,6 +8,7 @@
 
 import { parseMountPath, parsePresenceUrl, resolveRemoteInput } from './mounts.js';
 import { remoteGlobDetailed, remoteGrep, splitGlobPattern } from './remote-search.js';
+import { canonicalObservation, lookupObservation, recordObservation } from './observed-store.js';
 
 const LIMIT = 200;
 
@@ -131,3 +132,152 @@ export function installToolInterceptor(ctx, { pool, cwdOf }) {
     }
   });
 }
+
+/**
+ * Bridge between the Presence file tools and the harness read-before-edit
+ * policy (plugin `fs-observation-policy`).
+ *
+ * The policy records an authoritative observation only when a tool emits
+ * `fs/observed` with a resolved target and the returned version. Its state is a
+ * WeakMap keyed by the live Session object inside that plugin — it is not a
+ * service, so it cannot be read or written directly from here. What IS possible
+ * (and what this bridge does) is to publish the same event the built-in tools
+ * publish:
+ *  - after `presence_read`/`presence_write`/`presence_edit` succeed (through the
+ *    `observe` callback the tools call), so a later built-in `edit` on the same
+ *    remote file passes;
+ *  - after a built-in `read`/`read_image`, so the persisted record survives
+ *    compaction (the guard's own WeakMap does not);
+ *  - just before a built-in `edit`/`write`, re-publishing the recorded version
+ *    when the file is still at exactly that version. A changed file is never
+ *    auto-approved.
+ *
+ * `exec cat` (or any command that happens to read a file) is deliberately NOT
+ * turned into an observation: a shell command carries neither a target identity
+ * nor a version, and fabricating one would defeat the guard.
+ *
+ * @param ctx - plugin context (event owner).
+ * @param options.cwdOf - async (exec) => session cwd or null.
+ * @param options.late - late-bound services (`fs`).
+ * @returns `{ observe, resolveObservation }`; `observe` is the callback
+ *   `definePresenceTools` expects, `resolveObservation` is useful for probes.
+ */
+export function installObservationBridge(ctx, { cwdOf, late }) {
+  const sessionIdOf = (exec) => exec?.agent?.session?.id ?? exec?.agent?.session?.header?.id ?? null;
+
+  const explicitHostOf = (exec) => {
+    const host = exec?.arguments?.host;
+    return typeof host === 'string' && host.trim() ? host.trim() : null;
+  };
+
+  /**
+   * Resolve a tool path spelling to `{ target, canonical }`. A remote spelling
+   * becomes the canonical `presence://host/path` target directly (so a local
+   * session that passed `host` explicitly still records the right identity);
+   * a genuinely local path falls back to the provider's own target, keeping the
+   * pre-0.20 local repair behavior.
+   */
+  const resolveObservation = async (exec, path) => {
+    if (typeof path !== 'string' || path === '') return null;
+    let cwd = null;
+    try {
+      cwd = (await cwdOf(exec)) ?? null;
+    } catch {
+      cwd = null;
+    }
+    const explicitHost = explicitHostOf(exec);
+    const canonical = canonicalObservation(path, { cwd, host: explicitHost });
+    if (canonical) {
+      // The presence provider's identity IS the presence URL; the policy only
+      // reads `targetKey`, and every other `fs/observed` listener can stat this
+      // target through the same provider.
+      return { target: { targetKey: canonical.key, displayPath: canonical.key }, canonical };
+    }
+    // A relative spelling cannot be mapped when the call named a different host
+    // than the mounted workspace: resolving it through the provider would record
+    // the mounted machine's file, which is NOT the file the tool touched. Never
+    // fabricate a target that belongs to another machine.
+    if (explicitHost && cwd && parseMountPath(cwd)) return null;
+    const fs = late?.fs;
+    if (!fs || typeof fs.resolve !== 'function') return null;
+    try {
+      const target = await fs.resolve(path, cwd ? { cwd } : undefined);
+      if (!target) return null;
+      return { target, canonical: canonicalObservation(target, { cwd }) };
+    } catch {
+      return null;
+    }
+  };
+
+  /** Record that this session saw the file at its current version. */
+  const observe = async (exec, path, options = {}) => {
+    try {
+      const resolved = await resolveObservation(exec, path);
+      if (!resolved) return;
+      const fs = late?.fs;
+      const stat = fs && typeof fs.stat === 'function' ? await fs.stat(resolved.target) : null;
+      const observation = stat ? { kind: 'present', version: stat.version } : { kind: 'absent' };
+      // The built-in read/write tools already publish their own event; a second
+      // one would only churn `changes` listeners. Presence tools have no other
+      // publisher, so they always publish here.
+      if (options.publish !== false) ctx.emit('fs/observed', resolved.target, observation, { agent: exec?.agent });
+      if (stat && options.remember !== false) {
+        recordObservation(
+          sessionIdOf(exec),
+          resolved.canonical ?? String(resolved.target.targetKey ?? ''),
+          stat.version,
+          { cwd: null },
+        );
+      }
+    } catch {
+      /* the observation is an optimization, never a failure */
+    }
+  };
+
+  /** Re-publish a recorded observation if the file is still at that version. */
+  const repair = async (exec, path) => {
+    const sessionId = sessionIdOf(exec);
+    if (!sessionId) return null;
+    const resolved = await resolveObservation(exec, path);
+    if (!resolved) return null;
+    const targetKey = resolved.canonical?.key ?? String(resolved.target.targetKey ?? '');
+    const recorded = lookupObservation(sessionId, resolved.canonical ?? targetKey);
+    if (!recorded) return null;
+    const fs = late?.fs;
+    const stat = fs && typeof fs.stat === 'function' ? await fs.stat(resolved.target) : null;
+    if (!stat || stat.version !== recorded) return null;
+    ctx.emit('fs/observed', resolved.target, { kind: 'present', version: stat.version }, { agent: exec.agent });
+    return stat.version;
+  };
+
+  // Built-in read/read_image: remember what the session has seen, so the record
+  // survives compaction even though the guard's WeakMap does not.
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    try {
+      if (!result?.isError && (exec?.name === 'read' || exec?.name === 'read_image')) {
+        await observe(exec, exec.arguments?.file_path, { publish: false });
+      }
+    } catch {
+      /* best effort */
+    }
+    return next();
+  });
+
+  // Built-in edit/write on a remote target: if this session read the file at
+  // the same version we recorded, re-publish the observation so the guard
+  // passes. A changed file is left alone: the guard's refusal is the point.
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    try {
+      if (exec?.name === 'edit' || exec?.name === 'write') {
+        const path = exec.arguments?.file_path;
+        if (typeof path === 'string' && path !== '') await repair(exec, path);
+      }
+    } catch {
+      /* best effort: a failed repair leaves the original guard behavior */
+    }
+    return next();
+  });
+
+  return { observe, resolveObservation };
+}
+