failproofai 0.0.14-beta.1 → 0.0.14

package/scripts/validate-mdx.ts

@@ -2,12 +2,12 @@
  * Validate that every docs page (`.mdx` and `.md` — Mintlify parses both as
  * MDX) parses with the same MDX engine Mintlify runs at deploy time.
  *
- * Why this exists: `mintlify validate` (the existing `docs` CI job) only checks
- * `docs.json` structure and nav-link resolution — it does NOT parse page
- * content. A page that is structurally referenced but contains an MDX syntax
- * error (e.g. a `<slug>` that escaped its surrounding backticks because a
- * translation dropped a closing `` ` ``) passes `mintlify validate` but fails
- * the Mintlify deploy with:
+ * Why this exists: `mintlify validate` (the existing `docs` CI job) checks
+ * `docs.json` structure, nav-link resolution, and frontmatter YAML — but it
+ * does NOT report MDX *body* syntax errors. A page whose frontmatter is valid
+ * but whose body contains an MDX syntax error (e.g. a `<slug>` that escaped its
+ * surrounding backticks because a translation dropped a closing `` ` ``) passes
+ * `mintlify validate` but fails the Mintlify deploy with:
  *
  *   Failed to parse page content at path tr/cli/audit.mdx:
  *   Expected a closing tag for `<slug>` (61:127-61:133) before the end of `paragraph`
@@ -21,12 +21,16 @@
  *
  * The error string above is emitted by `@mdx-js/mdx`'s micromark MDX layer,
  * which is the same engine Mintlify uses, so compiling here reproduces the
- * deploy-time parse faithfully.
+ * deploy-time parse faithfully. `main()` validates the frontmatter too (via
+ * `findPageError`), so this net is a strict superset of `mintlify validate`:
+ * it catches both the frontmatter YAML class that fails `mintlify validate`
+ * and the body-MDX class that `mintlify validate` lets through to deploy.
  */
 import { readdirSync, statSync, readFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compile } from "@mdx-js/mdx";
+import YAML from "yaml";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DOCS_DIR = join(__dirname, "..", "docs");
@@ -37,21 +41,86 @@ export interface MdxParseError {
   column?: number;
 }
 
+/**
+ * Shared frontmatter matcher. The capture group is the YAML block *body* (the
+ * text between the fences); `match[0]` is still the whole block including the
+ * fences and trailing newline, which is what `stripFrontmatter` blanks.
+ */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+
 /**
  * Replace a leading YAML frontmatter block (`--- … ---`) with blank lines.
  *
  * Mintlify parses frontmatter as YAML, not MDX, so it never causes an MDX parse
- * error. We blank it rather than delete it so the remaining content keeps its
- * original line numbers — error positions then match the real file.
+ * error — but it CAN contain a YAML syntax error, which blanking here hides
+ * from `findMdxParseError`. That gap is covered separately by
+ * `findFrontmatterError`; `findPageError` runs both. We blank rather than delete
+ * so the remaining body keeps its original line numbers — body error positions
+ * then match the real file.
  */
 export function stripFrontmatter(source: string): string {
-  const match = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/.exec(source);
+  const match = FRONTMATTER_RE.exec(source);
   if (!match) return source;
   // Keep newlines, drop every other character, so line numbers stay aligned.
   const blanked = match[0].replace(/[^\n]/g, "");
   return blanked + source.slice(match[0].length);
 }
 
+/**
+ * Parse the leading YAML frontmatter block and return its parse error, or
+ * `null` when the block is absent (legal — some pages and every i18n README
+ * have none) or valid.
+ *
+ * This is the half of page validation that `findMdxParseError` structurally
+ * cannot do: it compiles only the *body* (frontmatter blanked), so a YAML
+ * syntax error in `title:`/`description:` — the exact class that failed the
+ * `consolidate` job's `mintlify validate` step, and that this repo's own
+ * `validate:mdx` net could not see — sailed straight through. `mintlify`
+ * parses the frontmatter as YAML, so parsing it here reproduces that check.
+ *
+ * The reported `line` is FILE-relative (the opening `---` is file line 1), so
+ * it matches the convention `findMdxParseError` already uses for body errors.
+ * That is deliberately one greater than the block-relative number `mintlify`
+ * prints — do NOT "fix" it to match mintlify; file-relative is what points a
+ * reader (or a model asked to repair the page) at the right line.
+ */
+export function findFrontmatterError(source: string): MdxParseError | null {
+  const match = FRONTMATTER_RE.exec(source);
+  if (!match) return null;
+  try {
+    YAML.parse(match[1]);
+    return null;
+  } catch (err) {
+    const e = err as {
+      message?: string;
+      linePos?: Array<{ line: number; col: number }>;
+    };
+    const raw = e.message ?? String(err);
+    return {
+      // Drop yaml's block-relative "at line N, column N:" phrase (it would
+      // contradict the file-relative line we report) but keep the caret-
+      // underlined excerpt after it — the single most useful signal for a
+      // model asked to repair the offending line.
+      message: raw.replace(/ at line \d+, column \d+:/, ":"),
+      line: e.linePos?.[0] ? e.linePos[0].line + 1 : undefined,
+      column: e.linePos?.[0]?.col,
+    };
+  }
+}
+
+/**
+ * Validate a full page the way the Mintlify deploy does: frontmatter YAML
+ * first, then the MDX body. Returns the first error found, or `null`. This is
+ * the single entry point shared by `validate:mdx` (`main()` below) and the
+ * translation pipeline's generation-time gate, so the two can never disagree
+ * about what is publishable.
+ */
+export async function findPageError(
+  source: string,
+): Promise<MdxParseError | null> {
+  return findFrontmatterError(source) ?? (await findMdxParseError(source));
+}
+
 /**
  * Compile one MDX source string with the deploy-time parser. Returns `null`
  * when it parses cleanly, or the parse error (with position) otherwise.
@@ -114,7 +183,7 @@ async function main(): Promise<void> {
   const failures: Array<{ file: string; error: MdxParseError }> = [];
 
   for (const file of files) {
-    const error = await findMdxParseError(readFileSync(file, "utf-8"));
+    const error = await findPageError(readFileSync(file, "utf-8"));
     if (error) failures.push({ file: relative(process.cwd(), file), error });
   }
 

package/src/audit/cli.ts

@@ -22,6 +22,7 @@ import { trackHookEvent } from "../hooks/hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 import { sanitizeErrorMessage } from "../../lib/telemetry-sanitize";
 import { openWhenReady } from "./open-browser";
+import { brandAnsi, ANSI_RESET, ANSI_BOLD, ANSI_DIM } from "../hooks/tui";
 
 /** Port the bundled dashboard binds to. Matches `scripts/launch.ts`'s default
  *  for `start` mode, which `failproofai` (bare) already uses. */
@@ -59,12 +60,17 @@ WHAT IT DOES
 `.trimStart();
 
 // ── ANSI helpers ────────────────────────────────────────────────────────────
-const RESET = "\x1b[0m";
-const DIM = "\x1b[2m";
-const BOLD = "\x1b[1m";
-const PINK = "\x1b[38;5;204m";
-const GREEN = "\x1b[38;5;120m";
-const CYAN = "\x1b[38;5;81m";
+// Colours come from the shared brand palette in hooks/tui.ts, so `audit` reads
+// as the same product as `config`. This file used to define its own 256-colour
+// set (a green and a blue that appear nowhere in the brand). The palette has
+// two accents rather than three, so success and command/URL text share the
+// teal — the glyph (✓) and the surrounding copy already distinguish them.
+const RESET = ANSI_RESET;
+const DIM = ANSI_DIM;
+const BOLD = ANSI_BOLD;
+const PINK = brandAnsi("pink");
+const GREEN = brandAnsi("guide"); // success — brand teal
+const CYAN = brandAnsi("guide"); // commands & URLs — brand teal
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 function colorOn(): boolean {

package/src/auth/cli.ts

@@ -28,6 +28,7 @@ import {
   writeAuth,
 } from "../../lib/auth/auth-store";
 import { CliError } from "../cli-error";
+import { brandAnsi, colorsEnabled, ANSI_RESET, ANSI_DIM } from "../hooks/tui";
 import { trackHookEvent } from "../hooks/hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 
@@ -123,11 +124,19 @@ function prompt(question: string, opts: { hidden?: boolean } = {}): Promise<stri
   });
 }
 
-const DIM = "\x1b[2m";
-const RESET = "\x1b[0m";
-const PINK = "\x1b[38;5;204m";
-const GREEN = "\x1b[38;5;120m";
-const RED = "\x1b[38;5;197m";
+// Brand palette (see hooks/tui.ts) rather than this file's former private
+// 256-colour set, so `auth` matches `config` and `audit`. Resolved once here
+// and blanked when colour is off — these are interpolated directly into
+// template literals at ~15 call sites, which previously meant `auth` emitted
+// escape codes even under NO_COLOR. Blanking the constants fixes every call
+// site at once. The palette has no red, and both uses are recoverable input
+// errors ("try again") rather than failures, so they take the amber warn hue.
+const COLOR = colorsEnabled(process.stdout);
+const DIM = COLOR ? ANSI_DIM : "";
+const RESET = COLOR ? ANSI_RESET : "";
+const PINK = COLOR ? brandAnsi("pink") : "";
+const GREEN = COLOR ? brandAnsi("guide") : "";
+const RED = COLOR ? brandAnsi("warn") : "";
 
 function emailLooksValid(email: string): boolean {
   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);

package/src/hooks/builtin-policies.ts

@@ -172,7 +172,8 @@ const CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh|dash|ksh|csh|tcsh|
 const PS_WEB_PIPE_RE = /(?:Invoke-WebRequest|iwr|Invoke-RestMethod|irm)\s+.*\|\s*(?:Invoke-Expression|iex)/i;
 
 // blockForcePush
-const FORCE_PUSH_RE = /(?:--force|-f\b)/;
+const SHORT_FLAG_BUNDLE_RE = /^-[a-zA-Z]*f[a-zA-Z]*$/;
+const SAFE_FORCE_PREFIXES = ["--force-with-lease", "--force-if-includes"] as const;
 
 // blockSecretsWrite
 const SECRET_FILE_RE = /\.(?:pem|key)$/;
@@ -587,36 +588,154 @@ function blockPushMaster(ctx: PolicyContext): PolicyResult {
   return allow();
 }
 
+// -- block-rm-rf: deletion-target resolution --
+
+/**
+ * Leading shell forms that resolve to a home directory: `~`, `~user`, `$HOME`,
+ * `${HOME}`. The lookahead keeps `$HOMEBREW_PREFIX` (a variable this policy
+ * cannot resolve) from being mistaken for `$HOME`.
+ */
+const HOME_PREFIX_RE = /^(?:~[A-Za-z0-9_.-]*|\$HOME|\$\{HOME\})(?=$|\/)/;
+
+/** `rm`, `/bin/rm`, `/usr/bin/rm`, … — the command word of a delete. */
+const RM_CMD_RE = /^(?:\/\S*\/)?rm$/;
+
+/** `find` expression that deletes: `-delete`, `-exec rm`, `-execdir rm`, `-ok rm`. */
+// Same shape as RM_CMD_RE: `find` is just as dangerous when invoked by
+// absolute path (`/usr/bin/find / -delete`), so match both forms.
+const FIND_CMD_RE = /^(?:\/\S*\/)?find$/;
+const FIND_EXEC_RE = /^-(?:exec|execdir|ok|okdir)$/;
+
+/** find's global options, which precede its path operands (`find -L / -delete`). */
+const FIND_GLOBAL_OPT_RE = /^-(?:[HLP]|D|O\d*)$/;
+
+/** First token of find's expression — everything before it is a path operand. */
+const FIND_EXPR_START_RE = /^(?:-|\\?[(!])/;
+
+/**
+ * Roots that exist to hold throwaway data. A delete of the root itself is still
+ * catastrophic (`rm -rf /tmp` wipes every process's scratch space); a delete of
+ * something *inside* one is ordinary work.
+ */
+const SCRATCH_ROOTS = ["/tmp", "/var/tmp"];
+
+/**
+ * How many path segments below a root (`/` or a home directory) a delete has to
+ * reach before it stops being catastrophic. `/etc` (1) and `/home/chetan` (2)
+ * are system- and user-level directories; `/home/chetan/project` (3) is a
+ * specific thing the caller meant to delete.
+ */
+const CATASTROPHIC_DEPTH = 2;
+
+/** Expand the leading `~` / `$HOME` / `${HOME}` of a path to the real home directory. */
+function expandHomePrefix(path: string): string {
+  const m = path.match(/^(?:~|\$HOME|\$\{HOME\})(?=$|\/)/);
+  return m ? homedir() + path.slice(m[0].length) : path;
+}
+
+/** Drop a trailing `/*` glob and any trailing slashes: `/tmp/foo/*` → `/tmp/foo`. */
+function stripTrailingGlob(path: string): string {
+  return path.replace(/\/\*$/, "").replace(/\/+$/, "");
+}
+
+/**
+ * Would deleting this target be catastrophic?
+ *
+ * Rather than pattern-matching the raw command text, this resolves the token as
+ * far as the shell would: quotes are stripped, `~` / `$HOME` are recognised as a
+ * root in their own right, and the remaining path segments are counted. A target
+ * within {@link CATASTROPHIC_DEPTH} segments of either root (`/` or home) takes
+ * out the machine or the user's data.
+ *
+ * Fails safe: a token whose head is an expansion this policy cannot evaluate —
+ * command substitution (`$(…)`, backticks) or any variable other than `$HOME` —
+ * could expand to `/`, so it counts as catastrophic. Relative targets are not
+ * flagged: they resolve under the working directory, not under a root.
+ */
+function isCatastrophicTarget(token: string): boolean {
+  const raw = token.replace(/^['"]|['"]$/g, "");
+  if (raw === "") return false;
+
+  const homePrefix = raw.match(HOME_PREFIX_RE);
+  // Unresolvable head: `$(echo /)`, `` `pwd` ``, `$TARGET_DIR`, …
+  if (!homePrefix && /^[$`]/.test(raw)) return true;
+
+  const belowRoot = homePrefix ? raw.slice(homePrefix[0].length) : raw.startsWith("/") ? raw : null;
+  if (belowRoot === null) return false;
+
+  const segments = stripTrailingGlob(belowRoot).split("/").filter(Boolean);
+  if (!homePrefix && SCRATCH_ROOTS.some((r) => `/${segments.join("/")}`.startsWith(`${r}/`))) return false;
+  return segments.length <= CATASTROPHIC_DEPTH;
+}
+
 /**
- * Check whether all *recursive* rm path targets in a command are under an allowlisted path.
+ * The paths a single command segment would recursively delete, or `null` when the
+ * segment is not a recursive delete at all.
+ *
+ * Understands the two shapes that reach every file under a target: `rm` with both
+ * `-r` and `-f` (in any spelling or order), and `find`, which recurses by design,
+ * paired with `-delete` or an `-exec rm`.
+ */
+function recursiveDeletionTargets(seg: string): string[] | null {
+  const tokens = parseArgvTokens(seg);
+
+  const findIdx = tokens.findIndex((t) => FIND_CMD_RE.test(t));
+  if (findIdx >= 0) {
+    const expr = tokens.slice(findIdx + 1);
+    const execIdx = expr.findIndex((t) => FIND_EXEC_RE.test(t));
+    const deletes = expr.includes("-delete") || (execIdx >= 0 && RM_CMD_RE.test(expr[execIdx + 1] ?? ""));
+    if (deletes) {
+      // find's path operands sit between the leading global options and the
+      // first expression token: `find -L /home/chetan -name '*.log' -delete`
+      let start = 0;
+      while (start < expr.length && FIND_GLOBAL_OPT_RE.test(expr[start])) {
+        start += expr[start] === "-D" ? 2 : 1;
+      }
+      const rest = expr.slice(start);
+      const end = rest.findIndex((t) => FIND_EXPR_START_RE.test(t));
+      return end < 0 ? rest : rest.slice(0, end);
+    }
+  }
+
+  const rmIdx = tokens.findIndex((t) => RM_CMD_RE.test(t));
+  if (rmIdx >= 0) {
+    const args = tokens.slice(rmIdx + 1);
+    const shortFlags = args.filter((t) => /^-[^-]/.test(t)).join("");
+    const longFlags = args.filter((t) => /^--/.test(t));
+    const recursive = /r/i.test(shortFlags) || longFlags.some((f) => /^--recursive$/i.test(f));
+    const force = /f/.test(shortFlags) || longFlags.some((f) => /^--force$/i.test(f));
+    if (recursive && force) return args.filter((t) => !t.startsWith("-"));
+  }
+
+  return null;
+}
+
+/** Split a command into the segments the shell would run as separate commands. */
+function shellSegments(cmd: string): string[] {
+  return cmd.split(/&&|\|\||[|;\n]/).map((s) => s.trim()).filter((s) => s !== "");
+}
+
+/**
+ * Check whether all recursive-delete targets in a command are under an allowlisted path.
  * Splits on shell operators first so that `/tmp` appearing in an unrelated
  * sub-command (e.g. `echo /tmp && rm -rf /`) does not trigger a false allow.
  * Uses path-boundary comparison so `/tmp` does not cover `/tmp2`.
  * Non-recursive rm segments (no -r/-R flag) are skipped — they pose no catastrophic risk.
  * Quoted paths with spaces are handled via a segment-level regex fallback.
+ * Home-relative targets and allowPaths entries are expanded, so `~/scratch` is
+ * covered by an allowPaths entry of either `~/scratch` or the absolute home path.
  */
-function rmTargetIsAllowed(cmd: string, allowPaths: string[]): boolean {
+function deletionTargetIsAllowed(cmd: string, allowPaths: string[]): boolean {
   if (allowPaths.length === 0) return false;
-  const segments = cmd
-    .split(/&&|\|\||[|;\n]/)
-    .map((s) => s.trim())
-    .filter((s) => /\brm\b/.test(s));
-  if (segments.length === 0) return false;
-  for (const seg of segments) {
-    const tokens = parseArgvTokens(seg);
-    const rmIdx = tokens.findIndex((t) => t === "rm");
-    if (rmIdx < 0) continue;
-    // Only validate recursive rm segments — non-recursive rm has no catastrophic-deletion risk
-    const flagTokens = tokens.slice(rmIdx + 1).filter((t) => /^-[^-]/.test(t));
-    const longFlagsInSeg = tokens.slice(rmIdx + 1).filter((t) => /^--/.test(t));
-    if (!/r/i.test(flagTokens.join("")) && !longFlagsInSeg.some(f => /^--recursive$/i.test(f))) continue;
-    const pathArgs = tokens.slice(rmIdx + 1).filter((t) => !t.startsWith("-"));
-    for (const target of pathArgs) {
-      const normalized = target.replace(/\/\*$/, "").replace(/\/+$/, "") || "/";
-      const covered = allowPaths.some((p) => {
-        const np = p.replace(/\/+$/, "") || "/";
-        return normalized === np || normalized.startsWith(np + "/");
-      });
+  const normalizedAllowPaths = allowPaths.map((p) => stripTrailingGlob(expandHomePrefix(p)) || "/");
+  let sawRecursiveDelete = false;
+  for (const seg of shellSegments(cmd)) {
+    const targets = recursiveDeletionTargets(seg);
+    if (targets === null) continue;
+    sawRecursiveDelete = true;
+    for (const target of targets) {
+      const normalized = stripTrailingGlob(expandHomePrefix(target)) || "/";
+      const covered = normalizedAllowPaths.some((np) => normalized === np || normalized.startsWith(np + "/"));
       if (!covered) {
         // Fallback: check the raw segment for quoted paths that contain spaces
         // (parseArgvTokens splits on whitespace, so "/tmp/my dir" becomes two tokens)
@@ -628,40 +747,23 @@ function rmTargetIsAllowed(cmd: string, allowPaths: string[]): boolean {
       }
     }
   }
-  return true;
+  return sawRecursiveDelete;
 }
 
 function blockRmRf(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Bash") return allow();
   const cmd = getCommand(ctx);
-  const hasDestructivePath = parseArgvTokens(cmd).some((token) => {
-    const normalized = token.replace(/\/\*$/, "").replace(/\/+$/, "") || (token.startsWith("/") ? "/" : "");
-    return normalized === "/" || normalized === "~" || /^\/[A-Za-z_][\w.-]*$/.test(normalized);
-  });
 
-  // Combined flags in one token: rm -rf /, rm -fr /
-  if (hasDestructivePath && (
-    /rm\s+-[^\s]*r[^\s]*f[^\s]*/.test(cmd) ||
-    /rm\s+-[^\s]*f[^\s]*r[^\s]*/.test(cmd)
-  )) {
+  const hasCatastrophicTarget = shellSegments(cmd).some((seg) => {
+    const targets = recursiveDeletionTargets(seg);
+    return targets !== null && targets.some(isCatastrophicTarget);
+  });
+  if (hasCatastrophicTarget) {
     const allowPaths = ((ctx.params?.allowPaths ?? []) as string[]);
-    if (rmTargetIsAllowed(cmd, allowPaths)) return allow();
+    if (deletionTargetIsAllowed(cmd, allowPaths)) return allow();
     return deny("Catastrophic deletion blocked");
   }
 
-  // Separated flags: rm -r -f /, rm -f -r /, rm -r -v -f /, etc.
-  if (hasDestructivePath && /\brm\b/.test(cmd)) {
-    const tokens = parseArgvTokens(cmd);
-    const shortFlags = tokens.filter((t) => /^-[^-]/.test(t)).join("");
-    const longFlags = tokens.filter((t) => /^--/.test(t));
-    const hasRecursive = /r/i.test(shortFlags) || longFlags.some(f => /^--recursive$/i.test(f));
-    const hasForce = /f/.test(shortFlags) || longFlags.some(f => /^--force$/i.test(f));
-    if (hasRecursive && hasForce) {
-      const allowPaths = ((ctx.params?.allowPaths ?? []) as string[]);
-      if (rmTargetIsAllowed(cmd, allowPaths)) return allow();
-      return deny("Catastrophic deletion blocked");
-    }
-  }
   // PowerShell: Remove-Item -Recurse -Force on root/drive
   if (/Remove-Item\s+.*-Recurse.*-Force.*(?:[A-Z]:\\(?:\s|$)|\\\*)/i.test(cmd)) {
     return deny("Catastrophic deletion blocked");
@@ -675,13 +777,29 @@ function blockRmRf(ctx: PolicyContext): PolicyResult {
 
 function blockForcePush(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Bash") return allow();
-  const args = extractGitPushArgs(getCommand(ctx));
-  if (args.some((a) => FORCE_PUSH_RE.test(a))) {
-    return deny("Force-pushing is blocked");
+  for (const segment of extractGitPushArgs(getCommand(ctx))) {
+    let sawEndOfOptions = false;
+    for (const token of segment.split(/\s+/)) {
+      if (token === "--") {
+        sawEndOfOptions = true;
+        continue;
+      }
+      if (sawEndOfOptions) continue;
+      if (isForcePushFlag(token)) {
+        return deny("Force-pushing is blocked");
+      }
+    }
   }
   return allow();
 }
 
+function isForcePushFlag(token: string): boolean {
+  if (token === "--force") return true;
+  if (SAFE_FORCE_PREFIXES.some((prefix) => token.startsWith(prefix))) return false;
+  if (token.startsWith("--force")) return true;
+  return SHORT_FLAG_BUNDLE_RE.test(token);
+}
+
 function blockSecretsWrite(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Write") return allow();
   const filePath = getFilePath(ctx);