@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/runtime/markdown-scan.ts

@@ -0,0 +1,266 @@
+/**
+ * A line scan of CommonMark, deep enough to find `##` sections, fenced code
+ * and block-level HTML comments as Claude Code's memory loading reads them.
+ */
+
+/** A block quote, or a list item whose content starts `width` columns into its parent's. */
+type Container = { kind: "quote" } | { kind: "item"; width: number };
+
+interface Fence {
+  char: string;
+  length: number;
+  /** The containers the fence opened in, outermost first; a line that leaves one ends the fence. */
+  containers: readonly Container[];
+}
+
+const FENCE_OPEN = /^(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^(`{3,}|~{3,})[ \t]*$/;
+const LIST_MARKER = /^(?:[-+*]|\d{1,9}[.)])/;
+const BLANK = /^[ \t]*$/;
+
+function indentation(text: string, from: number): { column: number; rest: string } {
+  let column = from;
+  let index = 0;
+  for (; index < text.length; index++) {
+    if (text[index] === " ") column++;
+    else if (text[index] === "\t") column += 4 - (column % 4);
+    else break;
+  }
+  return { column, rest: text.slice(index) };
+}
+
+/** Where a line's text stands: `rest` starts at `column`; the innermost container's content starts at `base`. */
+interface Position {
+  column: number;
+  rest: string;
+  base: number;
+}
+
+/** CommonMark: `>` after up to three spaces of indentation, and one optional space that belongs to the marker. */
+function afterQuoteMarker({ column, rest, base }: Position): Position | null {
+  if (column - base > 3 || !rest.startsWith(">")) return null;
+  const marker = column + 1;
+  const after = indentation(rest.slice(1), marker);
+  return { ...after, base: after.column > marker ? marker + 1 : marker };
+}
+
+/** The open containers a line continues, outermost first. A blank line continues list items, never a quote. */
+function continueContainers(
+  line: string,
+  containers: readonly Container[],
+): { matched: Container[]; at: Position } {
+  let at: Position = { ...indentation(line, 0), base: 0 };
+  const matched: Container[] = [];
+  for (const container of containers) {
+    if (container.kind === "quote") {
+      const next = afterQuoteMarker(at);
+      if (!next) break;
+      at = next;
+    } else {
+      if (at.rest !== "" && at.column < at.base + container.width) break;
+      at = { ...at, base: at.base + container.width };
+    }
+    matched.push(container);
+  }
+  return { matched, at };
+}
+
+/** The open containers carried from line to line. */
+interface ContainerContext {
+  containers: readonly Container[];
+  /** A paragraph is open, so a line that leaves its containers may continue it lazily. */
+  paragraph: boolean;
+  /** The innermost item opened on a blank line, so a blank line next ends it. */
+  emptyItem: boolean;
+}
+
+const TOP_LEVEL: ContainerContext = { containers: [], paragraph: false, emptyItem: false };
+
+/** CommonMark: a line that starts a block, so it ends a paragraph rather than continuing it. */
+const INTERRUPTS = /^(?:`{3,}|~{3,}|#{1,6}(?:[ \t]|$)|>|<!--|(?:[-+*]|\d{1,9}[.)])(?:[ \t]|$))/;
+const THEMATIC_BREAK = /^(?:(?:\*[ \t]*){3,}|(?:-[ \t]*){3,}|(?:_[ \t]*){3,})$/;
+
+/**
+ * Tracks only as much of CommonMark's block quotes and list items as placing a
+ * fence needs. A backtick fence's info string may hold no backtick, so
+ * ```` ```a``` ```` is inline code.
+ */
+function lineBlock(
+  line: string,
+  context: ContainerContext,
+): { fence: Fence | null; context: ContainerContext } {
+  const { matched, at } = continueContainers(line, context.containers);
+  const continues = matched.length === context.containers.length;
+  let { column, rest, base } = at;
+  if (rest === "") {
+    const containers = continues && context.emptyItem ? matched.slice(0, -1) : matched;
+    return { fence: null, context: { containers, paragraph: false, emptyItem: false } };
+  }
+  if (!continues) {
+    const starts = INTERRUPTS.test(rest) || THEMATIC_BREAK.test(rest);
+    const lazy = context.paragraph && !(column - base <= 3 && starts);
+    if (lazy) return { fence: null, context };
+  }
+  let containers = matched;
+  let paragraph = context.paragraph && continues;
+
+  while (column - base <= 3 && !THEMATIC_BREAK.test(rest)) {
+    const quoted = afterQuoteMarker({ column, rest, base });
+    if (quoted) {
+      containers = [...containers, { kind: "quote" }];
+      ({ column, rest, base } = quoted);
+      paragraph = false;
+      if (rest === "") return { fence: null, context: { containers, paragraph, emptyItem: false } };
+      continue;
+    }
+    const marker = LIST_MARKER.exec(rest);
+    if (!marker) break;
+    const markerEnd = column + marker[0].length;
+    const after = indentation(rest.slice(marker[0].length), markerEnd);
+    const gap = after.column - markerEnd;
+    if (gap < 1 && after.rest !== "") break;
+    const ordered = marker[0].length > 1;
+    if (paragraph && (after.rest === "" || (ordered && Number.parseInt(marker[0], 10) !== 1))) {
+      break;
+    }
+    const content = gap > 4 || after.rest === "" ? markerEnd + 1 : after.column;
+    containers = [...containers, { kind: "item", width: content - base }];
+    base = content;
+    paragraph = false;
+    if (after.rest === "") {
+      return { fence: null, context: { containers, paragraph, emptyItem: true } };
+    }
+    column = after.column;
+    rest = after.rest;
+  }
+
+  if (column - base > 3) {
+    return { fence: null, context: { containers, paragraph, emptyItem: false } };
+  }
+  const match = FENCE_OPEN.exec(rest);
+  const run = match?.[1];
+  if (run && !(run.startsWith("`") && match[2]!.includes("`"))) {
+    const fence = { char: run[0]!, length: run.length, containers };
+    return { fence, context: { containers, paragraph: false, emptyItem: false } };
+  }
+  paragraph = !THEMATIC_BREAK.test(rest) && !/^#{1,6}(?:[ \t]|$)/.test(rest);
+  return { fence: null, context: { containers, paragraph, emptyItem: false } };
+}
+
+/** `ends`: a line that leaves one of the fence's containers ends it; fenced code never continues lazily. */
+function fenceLine(line: string, fence: Fence): "content" | "close" | "ends" {
+  const { matched, at } = continueContainers(line, fence.containers);
+  if (matched.length < fence.containers.length) return "ends";
+  if (at.rest === "") return "content";
+  const match = at.column - at.base <= 3 ? FENCE_CLOSE.exec(at.rest) : null;
+  return match !== null && match[1]!.startsWith(fence.char) && match[1]!.length >= fence.length
+    ? "close"
+    : "content";
+}
+
+/** CommonMark: an ATX heading may be indented by up to three spaces, and be empty. */
+const HEADING = /^ {0,3}##(?:[ \t]+(.*))?$/;
+/** CommonMark: a closing run of `#`s, after a space or tab, is no part of the heading. */
+const CLOSING_SEQUENCE = /(?:^|[ \t]+)#+[ \t]*$/;
+
+function headingText(line: string): string | null {
+  const match = HEADING.exec(line);
+  if (!match) return null;
+  return (match[1] ?? "").replace(CLOSING_SEQUENCE, "").trim();
+}
+
+export interface ScannedLine {
+  text: string;
+  /** The heading text, `""` when empty, when the line opens a top-level (`##`) section: outside fenced code, list items and block quotes, whose scope it would otherwise leave. */
+  heading: string | null;
+  /** Inside fenced code, where blank lines are content. */
+  fenced: boolean;
+  /** Where the source line starts in the scanned text. */
+  offset: number;
+}
+
+/** CommonMark: an HTML block opens on a line that begins, after up to three spaces, with `<!--`. */
+const BLOCK_COMMENT_OPEN = /^ {0,3}<!--/;
+/** Claude Code's own pattern for the comments it removes from such a block. */
+const CLOSED_COMMENT = /<!--[\s\S]*?-->/g;
+
+type ScanState = { in: "prose" } | { in: "fence"; fence: Fence } | { in: "comment" };
+
+const PROSE: ScanState = { in: "prose" };
+const COMMENT: ScanState = { in: "comment" };
+
+/**
+ * Strips block-level HTML comments as Claude Code's memory loading does: only
+ * an HTML block that opens with `<!--` and holds a `-->`, so a `<!--` inside
+ * prose, inside fenced code, or never closed stays. The rest of a closing line
+ * is still part of the HTML block, so it opens no heading and no fence.
+ */
+export function scanLinesWithoutComments(text: string): ScannedLine[] {
+  const lines: ScannedLine[] = [];
+  let state = PROSE;
+  let list = TOP_LEVEL;
+  let offset = 0;
+
+  const emit = (line: string): void => {
+    const next = lineBlock(line, list);
+    const heading = next.context.containers.length === 0 ? headingText(line) : null;
+    lines.push({ text: line, heading, fenced: false, offset });
+    list = next.context;
+    state = next.fence ? { in: "fence", fence: next.fence } : PROSE;
+  };
+  /** A comment's lines are one HTML block: it ends the containers it leaves. */
+  const enterComment = (line: string): void => {
+    list = { ...lineBlock(line, list).context, paragraph: false };
+  };
+  const emitAfterClose = (line: string, close: number): void => {
+    const rest = line.slice(close + 3).replace(CLOSED_COMMENT, "");
+    lines.push({ text: rest, heading: null, fenced: false, offset });
+    state = PROSE;
+  };
+
+  for (const raw of text.split("\n")) {
+    const inFence = state.in === "fence" ? fenceLine(raw, state.fence) : "ends";
+    if (inFence !== "ends") {
+      lines.push({ text: raw, heading: null, fenced: true, offset });
+      if (inFence === "close") state = PROSE;
+    } else if (state.in === "comment") {
+      const close = raw.indexOf("-->");
+      if (close !== -1) emitAfterClose(raw, close);
+    } else if (BLOCK_COMMENT_OPEN.test(raw)) {
+      const close = text.indexOf("-->", offset + raw.indexOf("<!--") + 4);
+      if (close === -1) emit(raw);
+      else {
+        enterComment(raw);
+        if (close < offset + raw.length) emitAfterClose(raw, close - offset);
+        else state = COMMENT;
+      }
+    } else {
+      emit(raw);
+    }
+    offset += raw.length + 1;
+  }
+  return lines;
+}
+
+/** Offsets `[start, end)` of the lines inside fenced code. */
+export function fencedRanges(text: string): [number, number][] {
+  return scanLinesWithoutComments(text)
+    .filter((line) => line.fenced)
+    .map((line) => [line.offset, line.offset + line.text.length]);
+}
+
+export function joinLines(lines: readonly ScannedLine[]): string {
+  const kept: string[] = [];
+  let afterBlank = false;
+  for (const line of lines) {
+    const blank = !line.fenced && BLANK.test(line.text);
+    if (!(blank && afterBlank)) kept.push(blank ? "" : line.text);
+    afterBlank = blank;
+  }
+  return trimBlankLines(kept.join("\n"));
+}
+
+/** Drops the blank lines around a text but no indentation: an indented fence opener keeps its meaning. */
+export function trimBlankLines(text: string): string {
+  return text.replace(/^(?:[ \t]*\n)+/, "").trimEnd();
+}

package/src/runtime/policy.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { parse } from "yaml";
 
 import { FRAMEWORK_NAME } from "./framework";
+import { defaultSecretPolicy, parseSecretsConfig, type SecretPolicy } from "./secret-patterns";
 
 /**
  * Predicates that are never projected: they are read live from the companion
@@ -14,12 +15,18 @@ export interface CompanionPolicy {
   /** Names of the Capabilities the companion has enabled. */
   enabledCapabilities: string[];
   gitAutoMode: boolean;
+  /**
+   * Secret guardrails. Unlike the other fields, a missing or broken config
+   * yields guardrails on: protection never fails open.
+   */
+  secrets: SecretPolicy;
 }
 
 export const emptyCompanionPolicy = (): CompanionPolicy => ({
   allowedAgents: [],
   enabledCapabilities: [],
   gitAutoMode: false,
+  secrets: defaultSecretPolicy(),
 });
 
 export function companionFrameworkConfigPath(companionPath: string): string {
@@ -42,7 +49,8 @@ function capabilityNames(value: unknown): string[] {
 
 /**
  * Synchronous so it composes into `readCompanionRuntimeContext`. A missing or
- * unparseable companion config yields an inert policy rather than throwing.
+ * unparseable companion config yields an inert policy rather than throwing,
+ * with secret guardrails active.
  */
 export function readCompanionPolicy(companionPath: string): CompanionPolicy {
   let parsed: unknown;
@@ -58,9 +66,15 @@ export function readCompanionPolicy(companionPath: string): CompanionPolicy {
     allowedAgents: stringList(config.allowedAgents),
     enabledCapabilities: capabilityNames(config.capabilities),
     gitAutoMode: config.git === "auto",
+    secrets: parseSecretsConfig(config.secrets),
   };
 }
 
+/** The companion's live secret policy, read on every call. */
+export function resolveSecretPolicy(companionPath: string): SecretPolicy {
+  return readCompanionPolicy(companionPath).secrets;
+}
+
 export function isCapabilityEnabled(policy: CompanionPolicy, name: string): boolean {
   return policy.enabledCapabilities.includes(name);
 }

package/src/runtime/projected-flag.ts

@@ -0,0 +1,7 @@
+/**
+ * Marks the hook copies a Claude wrap inlines into a Working Repository's
+ * settings. A managed launch loads the bundled plugin's copy of the same hooks
+ * against the same environment, so nothing inside the process tells the two
+ * apart but this flag.
+ */
+export const PROJECTED_FLAG = "--projected";

package/src/runtime/projected-guidance.ts

@@ -38,6 +38,7 @@ export function buildProjectedGuidance(
       companionPath: projection.companionPath,
       repository: { id: projection.repositoryId, path: projection.repositoryPath },
       capabilities: policy.enabledCapabilities.map((name) => ({ name })),
+      secretGuardrails: policy.secrets.guardrails,
     },
     /** The projected path, not the running install's: a wrap may be another mate's. */
     { wrapperBinPath: projection.wrapperBinPath },

package/src/runtime/runtime-document-manifest.ts

@@ -62,6 +62,30 @@ export interface RenderedRuntimeDocument {
   readonly regions: readonly ManagedRegion[];
 }
 
+/** What a working-target render returns: its warnings are data for the caller, never printed. */
+export interface RenderedRuntimeDocuments {
+  documents: RenderedRuntimeDocument[];
+  warnings: string[];
+}
+
+function nonEmpty(region: ManagedRegion): boolean {
+  if (region.kind === "list") return region.values.length > 0;
+  /** A stripping map still heals what an older Mate left, with no entry of its own. */
+  if (region.kind === "map") {
+    return Object.keys(region.entries).length > 0 || region.stripPrefix !== undefined;
+  }
+  return true;
+}
+
+/** One rendered document of its non-empty regions, or none when every region is empty. */
+export function renderedDocument(
+  documentPath: string,
+  regions: ManagedRegion[],
+): RenderedRuntimeDocument[] {
+  const kept = regions.filter(nonEmpty);
+  return kept.length > 0 ? [{ path: documentPath, regions: kept }] : [];
+}
+
 /** An owned companion copy: the hash of what Mate last wrote there. */
 export interface CopyRecord {
   runtime: WrapRuntime;
@@ -185,14 +209,24 @@ export function copies(manifest: Manifest, runtime?: WrapRuntime): Record<string
   );
 }
 
+/** Narrows link records to one link root, e.g. `.claude/skills/`. */
+export interface LinkScope {
+  prefix?: string;
+}
+
 /** Links Mate created, keyed by repo-relative POSIX path. */
-export function links(manifest: Manifest, runtime?: WrapRuntime): Record<string, LinkRecord> {
+export function links(
+  manifest: Manifest,
+  runtime?: WrapRuntime,
+  scope: LinkScope = {},
+): Record<string, LinkRecord> {
   return Object.fromEntries(
     Object.entries(manifest.links).filter(
-      ([, record]) =>
+      ([key, record]) =>
         isRecord(record) &&
         typeof record.target === "string" &&
-        (!runtime || record.runtime === runtime),
+        (!runtime || record.runtime === runtime) &&
+        key.startsWith(scope.prefix ?? ""),
     ),
   );
 }
@@ -215,11 +249,23 @@ export function recordedMapKeys(
   documentPath: string,
   at: readonly string[],
 ): string[] {
-  return (documentRegions(manifest, documentPath) ?? []).flatMap((region: unknown) =>
-    isRecord(region) && region.kind === "map" && isAt(region.at, at) && isRecord(region.entries)
-      ? Object.keys(region.entries)
-      : [],
-  );
+  return Object.keys(recordedMapEntries(manifest, documentPath, at));
+}
+
+/** The entries of the `map` regions recorded at `at` in one document, checked like {@link recordedMapKeys}. */
+export function recordedMapEntries(
+  manifest: Manifest,
+  documentPath: string,
+  at: readonly string[],
+): Record<string, unknown> {
+  return Object.assign(
+    {},
+    ...(documentRegions(manifest, documentPath) ?? []).flatMap((region: unknown) =>
+      isRecord(region) && region.kind === "map" && isAt(region.at, at) && isRecord(region.entries)
+        ? [region.entries]
+        : [],
+    ),
+  ) as Record<string, unknown>;
 }
 
 /** Every value of the `list` regions recorded under `prefix` in one document. */
@@ -262,14 +308,15 @@ export function withoutDocuments(manifest: Manifest, documentPaths: readonly str
   };
 }
 
-/** Replaces one runtime's records, leaving every other record as it is. */
+/** Replaces one runtime's records under `prefix`, leaving every other record as it is. */
 function replaceRuntimeRecords<T>(
   existing: Readonly<Record<string, T>>,
   runtime: WrapRuntime,
   records: Readonly<Record<string, T>>,
+  prefix = "",
 ): Record<string, T> {
   const kept = Object.entries(existing).filter(
-    ([, record]) => !(isRecord(record) && record.runtime === runtime),
+    ([key, record]) => !(isRecord(record) && record.runtime === runtime && key.startsWith(prefix)),
   );
   return { ...Object.fromEntries(kept), ...records };
 }
@@ -286,8 +333,12 @@ export function withLinks(
   manifest: Manifest,
   runtime: WrapRuntime,
   records: Readonly<Record<string, LinkRecord>>,
+  scope: LinkScope = {},
 ): Manifest {
-  return { ...manifest, links: replaceRuntimeRecords(manifest.links, runtime, records) };
+  return {
+    ...manifest,
+    links: replaceRuntimeRecords(manifest.links, runtime, records, scope.prefix),
+  };
 }
 
 export function manifestPath(repoPath: string): string {

package/src/runtime/secret-guard.ts

@@ -0,0 +1,148 @@
+import { resolveSecretPolicy } from "./policy";
+import { globTargetsSecretFiles, isSecretFile } from "./secret-patterns";
+import { describeSecretFindings, scanContent, type SecretFinding } from "./secret-scan";
+import { HEREDOC_MARKER, stripHeredocBodies } from "./shell-heredoc";
+
+/**
+ * The secret check both runtimes run before a tool call: the Claude PreToolUse
+ * hook and the OpenCode middleware translate their own tool payloads into one
+ * of these shapes, so the two refuse the same calls for the same reasons.
+ */
+export type SecretToolCall =
+  | { kind: "read"; paths: string[] }
+  /** `content` is what the call would put into the file: a whole body or an edit's new text. */
+  | { kind: "write"; writes: { path: string; content: string }[] }
+  | { kind: "shell"; command: string }
+  /** A content search: refused when it names a secret file or a glob aimed at secret files. */
+  | { kind: "search"; paths: string[]; globs: string[] };
+
+export interface SecretGuardScope {
+  companionPath: string;
+  /** Whether a target lands in the Companion Repository, whose writes are content-scanned. */
+  isCompanionPath: (filePath: string) => boolean;
+}
+
+export interface SecretGuardDeps {
+  scan?: (filePath: string, content: string) => Promise<SecretFinding[]>;
+}
+
+const SWITCH_HINT =
+  "Secret guardrails are on. The user can add an allow pattern or opt out under `secrets` in the companion's framework.yaml; do not work around this block.";
+
+function secretFileRefusal(filePath: string): string {
+  return [
+    "Mate guardrail: secret files are off-limits to agents.",
+    ` target: ${filePath}`,
+    "Refer to the variable by name, read an example file such as .env.example, or ask the user to set the value.",
+    SWITCH_HINT,
+  ].join("\n");
+}
+
+const SHELL_SEPARATOR = /[\s;|&<>()`]/;
+
+/**
+ * Shell words with quotes removed, redirect operators as separators and
+ * heredoc bodies dropped. A heuristic, not a parser: it exists to find file
+ * names a command spells out, and a quoted string stays one word, so a
+ * commit message that mentions `.env` is not a reference to the file.
+ */
+export function shellWords(command: string): string[] {
+  const words: string[] = [];
+  for (const line of stripHeredocBodies(command).split("\n")) {
+    let word = "";
+    let quote: string | undefined;
+    let quoted = false;
+    const flush = () => {
+      if (word || quoted) words.push(word);
+      word = "";
+      quoted = false;
+    };
+    for (let i = 0; i < line.length; i++) {
+      const char = line[i];
+      if (quote) {
+        if (char === quote) quote = undefined;
+        else if (char === "\\" && quote === '"' && i + 1 < line.length) word += line[++i];
+        else word += char;
+      } else if (char === "'" || char === '"') {
+        quote = char;
+        quoted = true;
+      } else if (char === "\\" && i + 1 < line.length) {
+        word += line[++i];
+      } else if (char === "<" && line[i + 1] === "<") {
+        flush();
+        const marker = HEREDOC_MARKER.exec(line.slice(i));
+        i += marker ? marker[0].length - 1 : 1;
+      } else if (SHELL_SEPARATOR.test(char)) {
+        flush();
+      } else {
+        word += char;
+      }
+    }
+    flush();
+  }
+  return words.filter(Boolean);
+}
+
+/** A word, plus the value of a `--flag=path` or `NAME=path` word. */
+function candidatePaths(word: string): string[] {
+  const equals = word.indexOf("=");
+  return equals > 0 ? [word, word.slice(equals + 1)] : [word];
+}
+
+/**
+ * Returns the refusal message for a call that touches a secret, or null. Reads
+ * the companion's `secrets` block live, so a toggle applies to the next call.
+ */
+export async function checkSecretAccess(
+  call: SecretToolCall,
+  scope: SecretGuardScope,
+  deps: SecretGuardDeps = {},
+): Promise<string | null> {
+  const policy = resolveSecretPolicy(scope.companionPath);
+  if (!policy.guardrails) return null;
+
+  if (call.kind === "shell") {
+    const named = shellWords(call.command)
+      .flatMap(candidatePaths)
+      .find((word) => isSecretFile(word, policy));
+    return named ? secretFileRefusal(named) : null;
+  }
+
+  if (call.kind === "search") {
+    const named =
+      call.paths.find((filePath) => filePath && isSecretFile(filePath, policy)) ??
+      call.globs.find((glob) => globTargetsSecretFiles(glob, policy));
+    return named ? secretFileRefusal(named) : null;
+  }
+
+  const paths = call.kind === "read" ? call.paths : call.writes.map((write) => write.path);
+  const secretPath = paths.find((filePath) => filePath && isSecretFile(filePath, policy));
+  if (secretPath) return secretFileRefusal(secretPath);
+  if (call.kind === "read") return null;
+
+  const scan = deps.scan ?? scanContent;
+  for (const write of call.writes) {
+    if (!write.path || !write.content || !scope.isCompanionPath(write.path)) continue;
+    let findings: SecretFinding[];
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- the first refusal wins
+      findings = await scan(write.path, write.content);
+    } catch {
+      return [
+        "Mate guardrail: content for the Companion Repository could not be scanned for secrets, so the write is blocked.",
+        ` target: ${write.path}`,
+        SWITCH_HINT,
+      ].join("\n");
+    }
+    if (findings.length > 0) {
+      return [
+        "Mate guardrail: this write would put a secret into the Companion Repository.",
+        ` target: ${write.path}`,
+        ...describeSecretFindings(findings).map((line) => ` finding: ${line}`),
+        "Replace the value with a placeholder or the variable name. For a deliberate fake, wrap it in secretlint-disable/secretlint-enable comments.",
+        SWITCH_HINT,
+      ].join("\n");
+    }
+  }
+  return null;
+}