@dieulc/workflow 0.10.0 → 0.11.0

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@dieulc/workflow",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "private": false,
   "keywords": ["pi-package", "workflow", "plan-mode", "review-mode", "questionnaire", "rewind"],
   "description": "Plan↔Build mode with an independent Review Mode reviewer, questionnaire, subagent explore, todos and shadow-checkpoint rewind for Pi.",
   "license": "MIT",
   "scripts": {
-    "test": "node --test utils.todo.test.ts permissions.test.ts shell-text.test.ts roles.test.ts profiles.test.ts provider-retarget.test.ts thinking-levels.test.ts workflow-status.test.ts picker.test.ts questionnaire-layout.test.ts questionnaire-view.test.ts model-default.test.ts review.test.ts review-handoff.test.ts review-ui.test.ts extension.test.ts commit-policy.test.ts edit-policy.test.ts tab-policy.test.ts tab-editor.test.ts",
+    "test": "node --test utils.todo.test.ts todo-panel.test.ts permissions.test.ts shell-text.test.ts roles.test.ts profiles.test.ts provider-retarget.test.ts thinking-levels.test.ts workflow-status.test.ts picker.test.ts questionnaire-layout.test.ts questionnaire-view.test.ts model-default.test.ts review.test.ts review-handoff.test.ts review-ui.test.ts extension.test.ts commit-policy.test.ts edit-policy.test.ts tab-policy.test.ts tab-editor.test.ts folder-policy.test.ts shell-paths.test.ts read-policy.test.ts read-policy-tools.test.ts read-policy-redact.test.ts read-policy-gate.test.ts folder-floor-write.test.ts folder-floor-commit.test.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "check:policy": "node --experimental-transform-types scripts/verify-write-policy.mjs",
+    "check:read-policy": "node --experimental-transform-types scripts/verify-read-policy.mjs",
     "prepublishOnly": "node ../../../scripts/verify-packages.mjs --pack-only --packages workflow"
   },
   "repository": {
@@ -29,6 +30,11 @@
     "utils.ts",
     "checkpoint.ts",
     "commit-policy.ts",
+    "folder-policy.ts",
+    "shell-paths.ts",
+    "read-policy.ts",
+    "read-policy-tools.ts",
+    "read-policy-redact.ts",
     "edit-policy.ts",
     "roles.ts",
     "profiles.ts",
@@ -37,6 +43,7 @@
     "tab-editor.ts",
     "thinking-levels.ts",
     "workflow-status.ts",
+    "todo-panel.ts",
     "questionnaire-layout.ts",
     "questionnaire-view.ts",
     "model-default.ts",

package/read-policy-redact.ts

@@ -0,0 +1,319 @@
+/**
+ * Workflow Extension — Read-policy output redaction
+ *
+ * Defence in depth for channels the tool-call gate cannot fully see:
+ *
+ *   - `grep` searches a directory with `rg --hidden`; a `.env` that is not
+ *     gitignored would otherwise be returned in matched lines.
+ *   - `find` / `ls` list sensitive names; listings omit them.
+ *   - `bash` can print `git diff`/`git show` sections or `rg`-style lines.
+ *   - Pi's truncated bash output writes the full text to a temp file and tells
+ *     the model its path; when we redact, that escape hatch is removed.
+ *   - a successful `read` of a sensitive path is replaced as a safety net.
+ *
+ * Textual redaction is best-effort (custom renderers/structured content could
+ * bypass); callers drop `structuredContent` whenever content changes.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { FolderPolicyConfig } from "./folder-policy.ts";
+import { matchSensitivePath, toPosixPath } from "./folder-policy.ts";
+
+export interface RedactableBlock {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+export interface RedactableToolResult {
+  toolName: string;
+  input: Record<string, unknown>;
+  content: RedactableBlock[];
+  details?: unknown;
+  structuredContent?: unknown;
+}
+
+export interface RedactedToolResult {
+  content?: RedactableBlock[];
+  details?: unknown;
+  structuredContent?: undefined;
+}
+
+export interface RedactTextResult {
+  text: string;
+  redacted: boolean;
+}
+
+function searchBase(input: Record<string, unknown>, cwd: string): string {
+  const raw = input.path;
+  if (typeof raw !== "string" || !raw.trim()) return cwd;
+  const resolved = path.resolve(cwd, raw);
+  try {
+    return fs.statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function isSensitive(pathValue: string, config: FolderPolicyConfig, cwd: string): boolean {
+  return matchSensitivePath(pathValue, config, cwd).sensitive;
+}
+
+function resolveOutputPath(
+  raw: string,
+  base: string,
+  cwd: string,
+): string {
+  if (path.isAbsolute(raw)) return raw;
+  const joined = path.resolve(base, raw);
+  // `grep` relativises against the search root; if the joined path does not
+  // exist, the raw path may already be cwd-relative.
+  try {
+    if (fs.existsSync(joined)) return joined;
+  } catch {
+    /* ignore */
+  }
+  return path.resolve(cwd, raw);
+}
+
+function redactGrep(
+  text: string,
+  input: Record<string, unknown>,
+  cwd: string,
+  config: FolderPolicyConfig,
+): RedactTextResult {
+  const base = searchBase(input, cwd);
+  const out: string[] = [];
+  let redacted = false;
+  for (const line of text.split("\n")) {
+    const match = /^(.+?)(?::(\d+):|-(\d+)-)(.*)$/.exec(line);
+    if (!match) {
+      out.push(line);
+      continue;
+    }
+    const rawPath = match[1];
+    if (rawPath.includes("://")) {
+      out.push(line);
+      continue;
+    }
+    const resolved = resolveOutputPath(rawPath, base, cwd);
+    if (isSensitive(resolved, config, cwd)) {
+      redacted = true;
+      continue;
+    }
+    out.push(line);
+  }
+  if (redacted && out.every((line) => !line.trim())) {
+    return {
+      text:
+        "[matches in sensitive files were withheld by read policy]",
+      redacted: true,
+    };
+  }
+  return { text: out.join("\n"), redacted };
+}
+
+function redactFind(
+  text: string,
+  input: Record<string, unknown>,
+  cwd: string,
+  config: FolderPolicyConfig,
+): RedactTextResult {
+  const base = searchBase(input, cwd);
+  const out: string[] = [];
+  let redacted = false;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      out.push(line);
+      continue;
+    }
+    const resolved = resolveOutputPath(trimmed.replace(/\/$/, ""), base, cwd);
+    if (isSensitive(resolved, config, cwd)) {
+      redacted = true;
+      continue;
+    }
+    out.push(line);
+  }
+  if (redacted && out.every((line) => !line.trim())) {
+    return { text: "[entries withheld by read policy]", redacted: true };
+  }
+  return { text: out.join("\n"), redacted };
+}
+
+function redactLs(
+  text: string,
+  input: Record<string, unknown>,
+  cwd: string,
+  config: FolderPolicyConfig,
+): RedactTextResult {
+  const raw = input.path;
+  const base =
+    typeof raw === "string" && raw.trim()
+      ? path.resolve(cwd, raw)
+      : cwd;
+  const out: string[] = [];
+  let redacted = false;
+  for (const line of text.split("\n")) {
+    const entry = line.trim().replace(/\/$/, "");
+    if (!entry) {
+      out.push(line);
+      continue;
+    }
+    if (isSensitive(path.join(base, entry), config, cwd)) {
+      redacted = true;
+      continue;
+    }
+    out.push(line);
+  }
+  if (redacted && out.every((line) => !line.trim())) {
+    return { text: "[entries withheld by read policy]", redacted: true };
+  }
+  return { text: out.join("\n"), redacted };
+}
+
+function redactBash(
+  text: string,
+  cwd: string,
+  config: FolderPolicyConfig,
+): RedactTextResult {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let redacted = false;
+  let inSensitiveDiff = false;
+  for (const line of lines) {
+    const diffHeader = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+    if (diffHeader) {
+      const targetA = resolveOutputPath(diffHeader[1], cwd, cwd);
+      const targetB = resolveOutputPath(diffHeader[2], cwd, cwd);
+      inSensitiveDiff =
+        isSensitive(targetA, config, cwd) ||
+        isSensitive(targetB, config, cwd);
+      if (inSensitiveDiff) {
+        redacted = true;
+        out.push("[diff section withheld by read policy]");
+      } else {
+        out.push(line);
+      }
+      continue;
+    }
+    if (inSensitiveDiff) {
+      redacted = true;
+      continue;
+    }
+    if (/^Full output: /.test(line)) {
+      // Remove the temp-file escape hatch only when something was redacted;
+      // the caller also drops details.fullOutputPath.
+      if (redacted) continue;
+    }
+    const prefixed = /^(.+?)(?::(\d+):|-(\d+)-)(.*)$/.exec(line);
+    if (prefixed && !prefixed[1].includes("://")) {
+      const resolved = resolveOutputPath(prefixed[1], cwd, cwd);
+      if (isSensitive(resolved, config, cwd)) {
+        redacted = true;
+        continue;
+      }
+    }
+    out.push(line);
+  }
+  if (redacted && out.every((line) => !line.trim())) {
+    return { text: "[output withheld by read policy]", redacted: true };
+  }
+  return { text: out.join("\n"), redacted };
+}
+
+/**
+ * Redact one text payload. `kind` is the tool name (grep/find/ls/bash/read).
+ */
+export function redactSensitiveText(
+  text: string,
+  kind: string,
+  input: Record<string, unknown>,
+  cwd: string,
+  config: FolderPolicyConfig,
+): RedactTextResult {
+  if (!text) return { text, redacted: false };
+  if (kind === "grep") return redactGrep(text, input, cwd, config);
+  if (kind === "find") return redactFind(text, input, cwd, config);
+  if (kind === "ls") return redactLs(text, input, cwd, config);
+  if (kind === "bash" || kind === "powershell")
+    return redactBash(text, cwd, config);
+  return { text, redacted: false };
+}
+
+function inputPath(input: Record<string, unknown>): string {
+  const raw =
+    input.path ?? input.file ?? input.filePath ?? input.file_path ?? undefined;
+  return typeof raw === "string" ? raw.trim() : "";
+}
+
+/**
+ * Redact a tool result. Returns `undefined` when nothing changed (the caller
+ * leaves the result untouched). Any change drops `structuredContent`, per the
+ * Pi tool_result contract.
+ */
+export function redactToolResult(
+  event: RedactableToolResult,
+  config: FolderPolicyConfig,
+  cwd: string,
+): RedactedToolResult | undefined {
+  const tool = String(event.toolName ?? "");
+  const readTools = new Set([
+    "read",
+    "read_symbol",
+    "read_enclosing",
+    "module_report",
+    "effective_config",
+  ]);
+  if (readTools.has(tool)) {
+    const target = inputPath(event.input);
+    if (target && isSensitive(path.resolve(cwd, target), config, cwd)) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "[blocked by read policy: sensitive file]",
+          },
+        ],
+        structuredContent: undefined,
+      };
+    }
+    return undefined;
+  }
+
+  if (!["grep", "find", "ls", "bash", "powershell"].includes(tool))
+    return undefined;
+  let changed = false;
+  const content = (event.content ?? []).map((block) => {
+    if (block?.type !== "text" || typeof block.text !== "string") return block;
+    const result = redactSensitiveText(
+      block.text,
+      tool,
+      event.input ?? {},
+      cwd,
+      config,
+    );
+    if (!result.redacted) return block;
+    changed = true;
+    return { ...block, text: result.text };
+  });
+  if (!changed) return undefined;
+
+  const result: RedactedToolResult = { content, structuredContent: undefined };
+  if (event.details && typeof event.details === "object") {
+    const details = { ...(event.details as Record<string, unknown>) };
+    if (tool === "bash" || tool === "powershell") {
+      delete details.fullOutputPath;
+      delete details.full_output_path;
+    }
+    result.details = details;
+  }
+  return result;
+}
+
+/** A short display path for refusals/diagnostics. */
+export function displayRedactPath(value: string, cwd: string): string {
+  return toPosixPath(path.relative(cwd, value) || value);
+}

package/read-policy-tools.ts

@@ -0,0 +1,310 @@
+/**
+ * Workflow Extension — Read tool-call classifier
+ *
+ * Turns a tool name + input into the filesystem targets the read gate must
+ * classify. Covers Pi's built-in read tools, the pi-lens read tools, `explore`
+ * (the child's working root), local `fetch_content` / `browser_*` file URLs,
+ * and a conservative generic path-key scan for extension/MCP tools.
+ *
+ * Known writers are skipped (the write policy owns them). An unknown tool with
+ * a path-like input is guarded; an unknown tool without one is allowed. This
+ * is deliberately fail-safe without pretending every MCP tool is a file read.
+ */
+
+import { fileURLToPath } from "node:url";
+
+import type { ReadPolicyConfig } from "./read-policy.ts";
+import type { FolderTarget } from "./folder-policy.ts";
+import { normalizePolicyPath, toPosixPath } from "./folder-policy.ts";
+import { analyzeShellPaths } from "./shell-paths.ts";
+
+export interface ReadCallClassification {
+  tool: string;
+  targets: FolderTarget[];
+  uncertain: string[];
+  exempt?: string;
+}
+
+const KNOWN_WRITE_TOOLS = new Set([
+  "edit",
+  "write",
+  "ast_grep_replace",
+  "review_submit_plan",
+  "review_plan_begin",
+  "review_plan_chunk",
+  "review_plan_finalize",
+]);
+
+const EXEMPT_TOOLS = new Set([
+  "memory_search",
+  "memory_read",
+  "memory_write",
+  "memory_forget",
+  "memory_restore",
+  "memory_status",
+  "scratchpad",
+  "workflow_todo",
+  "web_search",
+  "source_check",
+  "get_search_content",
+  "pi_lens_activate_tools",
+  "lens_diagnostic_mark",
+  "questionnaire",
+  "browser_screenshot",
+  "browser_console_logs",
+  "browser_console_errors",
+  "browser_network_requests",
+  "browser_close",
+  "browser_attach",
+  "browser_detach",
+]);
+
+const FILE_PATH_TOOLS = new Set([
+  "read",
+  "read_symbol",
+  "read_enclosing",
+  "module_report",
+  "effective_config",
+]);
+
+const DIR_OR_FILE_PATH_TOOLS = new Set(["ls", "grep", "find", "lsp_navigation"]);
+
+const PATHS_TOOLS = new Set([
+  "symbol_search",
+  "ast_grep_search",
+  "ast_grep_outline",
+]);
+
+const GENERIC_PATH_KEYS = new Set([
+  "path",
+  "file",
+  "filePath",
+  "file_path",
+  "dir",
+  "dirs",
+  "directory",
+  "directories",
+  "cwd",
+  "root",
+  "roots",
+  "analysisRoot",
+  "paths",
+  "files",
+]);
+
+function addTarget(
+  out: FolderTarget[],
+  value: unknown,
+  kind: FolderTarget["kind"],
+  cwd: string,
+): void {
+  if (typeof value !== "string" || !value.trim()) return;
+  const path = normalizePolicyPath(value, cwd);
+  if (!path) return;
+  const target =
+    value.includes("*") || value.includes("?")
+      ? { path: staticGlobPrefix(value, cwd), kind: "glob" as const }
+      : { path, kind };
+  if (!out.some((item) => item.path === target.path)) out.push(target);
+}
+
+/**
+ * Static, non-wildcard prefix of a glob, resolved to the narrowest directory
+ * that must be permitted. `../other/src/**\/*.ts` -> `../other/src`;
+ * `**\/*.ts` -> cwd.
+ */
+export function staticGlobPrefix(value: string, cwd: string): string {
+  const raw = value.trim();
+  const cut = raw.search(/[?*[]/);
+  const prefix = cut >= 0 ? raw.slice(0, cut) : raw;
+  const withoutTrailing = prefix.replace(/[\\/]+$/, "");
+  if (!withoutTrailing) return normalizePolicyPath(cwd, cwd);
+  const wildcardInLastSegment =
+    cut >= 0 && !/^[\\/]/.test(raw.slice(cut)) && !/[\\/]$/.test(prefix);
+  const base = wildcardInLastSegment
+    ? withoutTrailing.replace(/[\\/][^\\/]*$/, "")
+    : withoutTrailing;
+  return normalizePolicyPath(base || cwd, cwd);
+}
+
+function collection(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [value];
+}
+
+function classifyFileUrls(
+  tool: string,
+  input: Record<string, unknown>,
+  cwd: string,
+): ReadCallClassification {
+  const result: ReadCallClassification = { tool, targets: [], uncertain: [] };
+  const raw = input.url ?? input.urls;
+  for (const entry of collection(raw)) {
+    if (typeof entry !== "string" || !entry.trim()) continue;
+    const value = entry.trim();
+    if (/^https?:\/\//i.test(value) || /^(data|ftp|mailto):/i.test(value))
+      continue;
+    if (value.startsWith("file:")) {
+      try {
+        addTarget(result.targets, fileURLToPath(value), "file", cwd);
+      } catch {
+        result.uncertain.push(`${tool}: invalid file URL`);
+      }
+      continue;
+    }
+    // A bare local path is a local read (video/image/PDF fetchers). Windows
+    // drive paths are not URL schemes (`C:\...`).
+    if (
+      /^[A-Za-z]:[\\/]/.test(value) ||
+      value.startsWith("\\\\") ||
+      !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value)
+    ) {
+      addTarget(result.targets, value, "file", cwd);
+    }
+  }
+  return result;
+}
+
+/**
+ * Classify a tool call. Total: malformed inputs never throw.
+ */
+export function classifyReadCall(
+  toolName: string,
+  input: unknown,
+  cwd: string,
+  config: ReadPolicyConfig,
+): ReadCallClassification {
+  const tool = String(toolName ?? "");
+  const obj =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? (input as Record<string, unknown>)
+      : {};
+  const result: ReadCallClassification = { tool, targets: [], uncertain: [] };
+
+  if (tool === "bash" || tool === "powershell") {
+    const analysis = analyzeShellPaths(obj.command, cwd);
+    result.targets = analysis.reads;
+    result.uncertain = analysis.uncertain;
+    return result;
+  }
+
+  if (config.guardedTools.includes(tool)) {
+    collectGeneric(obj, cwd, result);
+    return result;
+  }
+
+  if (EXEMPT_TOOLS.has(tool)) {
+    result.exempt = "not a filesystem read tool";
+    return result;
+  }
+  if (KNOWN_WRITE_TOOLS.has(tool)) {
+    result.exempt = "write tool (write policy owns it)";
+    return result;
+  }
+
+  if (tool === "explore") {
+    if (obj.cwd !== undefined) addTarget(result.targets, obj.cwd, "dir", cwd);
+    const tasks = Array.isArray(obj.tasks) ? obj.tasks : [];
+    for (const task of tasks) {
+      if (!task || typeof task !== "object") continue;
+      const taskCwd = (task as Record<string, unknown>).cwd;
+      if (taskCwd !== undefined) addTarget(result.targets, taskCwd, "dir", cwd);
+    }
+    return result;
+  }
+
+  if (tool === "fetch_content" || tool === "browser_launch" || tool === "browser_navigate") {
+    return classifyFileUrls(tool, obj, cwd);
+  }
+
+  if (tool === "lens_diagnostics") {
+    for (const key of ["path", "file", "filePath", "analysisRoot"]) {
+      if (obj[key] !== undefined) addTarget(result.targets, obj[key], "dir", cwd);
+    }
+    for (const entry of collection(obj.paths)) {
+      addTarget(result.targets, entry, "file", cwd);
+    }
+    return result;
+  }
+
+  if (PATHS_TOOLS.has(tool)) {
+    for (const entry of collection(obj.paths)) {
+      addTarget(result.targets, entry, "file", cwd);
+    }
+    if (obj.path !== undefined) addTarget(result.targets, obj.path, "dir", cwd);
+    return result;
+  }
+
+  if (FILE_PATH_TOOLS.has(tool)) {
+    const value =
+      obj.path ?? obj.file ?? obj.filePath ?? obj.file_path ?? undefined;
+    if (typeof value !== "string" || !value.trim()) {
+      result.uncertain.push(`${tool}: missing path`);
+      return result;
+    }
+    addTarget(result.targets, value, "file", cwd);
+    return result;
+  }
+
+  if (DIR_OR_FILE_PATH_TOOLS.has(tool)) {
+    const value = obj.path ?? obj.file ?? obj.filePath ?? obj.file_path;
+    addTarget(result.targets, value ?? ".", "dir", cwd);
+    return result;
+  }
+
+  // Unknown/MCP tool: guard path-like inputs, otherwise allow.
+  collectGeneric(obj, cwd, result);
+  return result;
+}
+
+function collectGeneric(
+  input: unknown,
+  cwd: string,
+  result: ReadCallClassification,
+  depth = 0,
+): void {
+  if (!input || typeof input !== "object" || depth > 3) return;
+  if (Array.isArray(input)) {
+    for (const entry of input) {
+      if (typeof entry === "string") {
+        // Only reached for a direct array under a path key; handled below.
+        continue;
+      }
+      collectGeneric(entry, cwd, result, depth + 1);
+    }
+    return;
+  }
+  for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+    if (GENERIC_PATH_KEYS.has(key)) {
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          if (typeof entry === "string") {
+            const kind = key === "paths" || key === "files" ? "file" : "dir";
+            addTarget(result.targets, entry, kind, cwd);
+          } else {
+            collectGeneric(entry, cwd, result, depth + 1);
+          }
+        }
+      } else if (typeof value === "string") {
+        const kind =
+          key === "path" || key === "file" || key === "filePath" || key === "file_path"
+            ? "file"
+            : "dir";
+        addTarget(result.targets, value, kind, cwd);
+      }
+      continue;
+    }
+    // Nested containers may hold `cwd`/`path` fields (explore tasks, MCP args).
+    if (value && typeof value === "object") {
+      collectGeneric(value, cwd, result, depth + 1);
+    }
+  }
+}
+
+/** A short display path for diagnostics. */
+export function describeReadTargets(
+  targets: readonly FolderTarget[],
+): string {
+  return targets
+    .map((target) => toPosixPath(target.path))
+    .join(", ");
+}