@blogic-cz/agent-tools 1.11.1 → 1.13.0

package/src/credential-guard/shell-oracle.ts

@@ -0,0 +1,187 @@
+import { formatLiteralPrintf } from "./literal-output";
+import { parseBash } from "./bash";
+import { judge } from "./policy";
+import { splitXargsInput, type XargsInput } from "./xargs";
+
+const quote = (text: string): string => "'" + text.replaceAll("'", "'\\''") + "'";
+const receipt: Record<string, { checked: number; refused: number; mismatches: unknown[] }> = {};
+async function compare(
+  family: string,
+  shell: string,
+  source: string,
+  modeled: readonly string[] | null,
+) {
+  const count = (receipt[family] ??= { checked: 0, refused: 0, mismatches: [] });
+  const child = Bun.spawn([shell, "-c", source], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/bin:/bin", HOME: "/tmp" },
+  });
+  const actual = await new Response(child.stdout).text();
+  await new Response(child.stderr).text();
+  await child.exited;
+  count.checked++;
+  if (modeled === null) count.refused++;
+  else if (family === "termination") {
+    const reached = actual.split("\n").includes("[reached]");
+    if (reached && !modeled.some((output) => output.includes("[reached]")))
+      count.mismatches.push({ shell, source, actual, modeled });
+  } else if (!modeled.includes(actual)) count.mismatches.push({ shell, source, actual, modeled });
+}
+function modeledOutput(source: string): readonly string[] | null {
+  const outputs: string[] = [];
+  let unresolved = false;
+  const decision = judge(parseBash(source), {
+    home: "/home/dev",
+    cwd: "/tmp",
+    onInvocation(executable, argv) {
+      if (executable === "/usr/bin/printf" && argv[1] === "[%s]\\n") {
+        if (argv.some((word) => word === undefined)) unresolved = true;
+        outputs.push(
+          (argv.length > 2 ? argv.slice(2) : [""]).map((word) => `[${word}]\n`).join(""),
+        );
+      }
+    },
+  });
+  return decision.kind === "pass" && !unresolved
+    ? outputs.length
+      ? [...outputs, outputs.join("")]
+      : [""]
+    : null;
+}
+const jobs: Array<() => Promise<void>> = [];
+const shells = ["/bin/bash", "/bin/sh", "/bin/zsh", "/bin/dash"];
+const available = await Promise.all(
+  shells.map(async (shell) => ({ shell, exists: await Bun.file(shell).exists() })),
+);
+for (const { shell, exists } of available) {
+  if (!exists) {
+    console.log(`SKIP missing shell ${shell}`);
+    continue;
+  }
+  const braces = [
+    "{a,}",
+    "{,}",
+    "{,b}",
+    "x{,b}",
+    "{a,b}{,c}",
+    "'{a,b}'",
+    '"{a,b}"',
+    "{a,{b,c}}",
+    "{a,}''",
+    "''{,b}",
+  ];
+  for (const left of ["a", "", "b"])
+    for (const right of ["", "c", "d"]) braces.push(`{${left},${right}}`, `p{${left},${right}}q`);
+  for (const words of braces) {
+    const source = `/usr/bin/printf '[%s]\\n' seed ${words}`;
+    const model =
+      shell.endsWith("/sh") || shell.endsWith("/dash")
+        ? `sh -c ${quote(source)}`
+        : shell.endsWith("/bash")
+          ? `bash -c ${quote(source)}`
+          : source;
+    jobs.push(() => compare("brace", shell, source, modeledOutput(model)));
+  }
+  for (const format of ["%s\\n", "%s ", "%s", "%s:%s\\n"])
+    for (const words of [[], ["alpha"], ["alpha", "beta"], ["", "beta"], ["a b", "c"]]) {
+      const source = `printf ${quote(format)} ${words.map(quote).join(" ")}`;
+      const modeled = formatLiteralPrintf([format, ...words]);
+      jobs.push(() => compare("printf", shell, source, modeled === null ? null : [modeled]));
+    }
+  for (const compound of [
+    "{ exit 0; }",
+    "(exit 0)",
+    "if true; then exit 0; fi",
+    "case x in x) exit 0;; esac",
+    "for x in a; do exit 0; done",
+    "while true; do exit 0; done",
+    "exit 0 && true",
+    "exit 0 || true",
+    "exit 0 && false || true",
+    "exit 0 || false && true",
+    "{ exit 0; } && true",
+    "! { exit 0; } || true",
+  ])
+    for (const redirect of ["&>/dev/null", "&>>/dev/null"]) {
+      const source = `${compound} ${redirect}; /usr/bin/printf '[%s]\\n' reached`;
+      jobs.push(() =>
+        compare(
+          "termination",
+          shell,
+          source,
+          modeledOutput(
+            `${shell.endsWith("/bash") || shell.endsWith("/zsh") ? "bash" : "sh"} -c ${quote(source)}`,
+          ),
+        ),
+      );
+    }
+  for (const command of ["exit", "return"])
+    for (const redirect of [
+      "",
+      " 2>/dev/null",
+      " &>/dev/null",
+      " &>>/dev/null",
+      " </tmp/guard-oracle-missing/input",
+      " >/dev/null/x",
+      " 2>&1",
+      " 2>&99",
+      " 1>&- 2>&1",
+    ])
+      for (const op of [";", "||"]) {
+        const source = `${command} 0${redirect} ${op} /usr/bin/printf '[%s]\\n' reached`;
+        jobs.push(() =>
+          compare(
+            "termination",
+            shell,
+            source,
+            modeledOutput(
+              `${shell.endsWith("/bash") || shell.endsWith("/zsh") ? "bash" : "sh"} -c ${quote(source)}`,
+            ),
+          ),
+        );
+      }
+}
+const modes: XargsInput[] = [
+  { replacement: null, maxArgs: null, maxLines: null },
+  { replacement: "{}", maxArgs: null, maxLines: null },
+  { replacement: null, maxArgs: 1, maxLines: null },
+  { replacement: null, maxArgs: null, maxLines: 1 },
+];
+const inputs = [
+  "a\nb\n",
+  "a b\n",
+  "'' word\n",
+  '"" word\n',
+  "a  b\n",
+  "a\tb\n",
+  "  a\n",
+  "a\n\nb\n",
+  "'a b'\n",
+  "a\\ b\n",
+];
+for (const a of ["a", "''", '""', " "])
+  for (const b of [" ", "  ", "\t", "\n"]) inputs.push(a + b + "b\n");
+for (const mode of modes)
+  for (const input of inputs) {
+    const groups = splitXargsInput(input, mode);
+    const output =
+      groups === null
+        ? null
+        : groups
+            .flatMap((words) => (words.length ? words : [""]).map((word) => `[${word}]\n`))
+            .join("");
+    const flags = mode.replacement ? "-I{}" : mode.maxArgs ? "-n1" : mode.maxLines ? "-L1" : "";
+    const source = `printf '%s' ${quote(input)} | /usr/bin/xargs ${flags} /usr/bin/printf '[%s]\\n' ${mode.replacement ? "'{}'" : ""}`;
+    jobs.push(() =>
+      compare(
+        `xargs-${flags || "default"}`,
+        "/bin/bash",
+        source,
+        output === null ? null : [output],
+      ),
+    );
+  }
+await jobs.reduce((previous, run) => previous.then(run), Promise.resolve());
+console.log(JSON.stringify(receipt, null, 2));
+if (Object.values(receipt).some((family) => family.mismatches.length)) process.exitCode = 1;

package/src/credential-guard/xargs.ts

@@ -0,0 +1,65 @@
+export type XargsInput = {
+  readonly replacement: string | null;
+  readonly maxArgs: number | null;
+  readonly maxLines: number | null;
+};
+
+export function splitXargsInput(text: string, mode: XargsInput): readonly string[][] | null {
+  if (/[^\t\n\x20-\x7e]/.test(text)) return null;
+  if (mode.replacement !== null && /['"\t]| {2}|^ |\n |\\/.test(text)) return null;
+  const lines: string[][] = [];
+  let words: string[] = [];
+  let word = "";
+  let started = false;
+  let quote = "";
+  const finishWord = () => {
+    if (started) words.push(word);
+    word = "";
+    started = false;
+  };
+  for (let index = 0; index < text.length; index++) {
+    const ch = text[index] ?? "";
+    if (ch === "\n") {
+      if (
+        quote ||
+        ((mode.maxLines !== null || mode.replacement !== null) &&
+          /[ \t]/.test(text[index - 1] ?? ""))
+      )
+        return null;
+      finishWord();
+      if (words.length) lines.push(words);
+      words = [];
+    } else if (ch === "\\" && !quote) {
+      const next = text[++index];
+      if (next === undefined || next === "\n") return null;
+      word += next;
+      started = true;
+    } else if ((ch === "'" || ch === '"') && (!quote || ch === quote)) {
+      quote = quote ? "" : ch;
+      started = true;
+    } else if (!quote && /[ \t]/.test(ch) && mode.replacement === null) {
+      finishWord();
+    } else if (mode.replacement !== null && !started && /[ \t]/.test(ch)) {
+      continue;
+    } else {
+      word += ch;
+      started = true;
+    }
+  }
+  if (quote) return null;
+  finishWord();
+  if (words.length) lines.push(words);
+  const result: string[][] = [];
+  if (mode.replacement !== null) result.push(...lines);
+  else if (mode.maxLines !== null) {
+    for (let index = 0; index < lines.length; index += mode.maxLines)
+      result.push(lines.slice(index, index + mode.maxLines).flat());
+  } else {
+    const all = lines.flat();
+    const size = mode.maxArgs ?? Math.max(all.length, 1);
+    for (let index = 0; index < all.length; index += size)
+      result.push(all.slice(index, index + size));
+  }
+  if (result.length > 64 || result.some((args) => args.length > 64)) return null;
+  return result.length ? result : null;
+}

package/src/gh-tool/main.ts

@@ -4,7 +4,8 @@ import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Layer } from "effect";
 
 import { makeSchemaCommand, renderCauseToStderr, VERSION } from "#shared";
-import { AuditServiceLayer, withAudit } from "#shared/audit";
+import { AuditService, AuditServiceLayer, withAudit } from "#shared/audit";
+import { openRequestTelemetry } from "#gh/read/telemetry-store";
 import { withRedactedOutput } from "#shared/output-boundary";
 import { ConfigServiceLayer } from "#config";
 import {
@@ -26,6 +27,7 @@ import {
   prCreateCommand,
   prCloseCommand,
   prEditCommand,
+  prCheckboxCommand,
   prMergeCommand,
   prReadyCommand,
   prDraftCommand,
@@ -80,7 +82,9 @@ import {
 import { labelCreateCommand } from "./label";
 import { GitHubService } from "./read/transport";
 import { withReadCache } from "./read";
-import { cacheCommand } from "./read/commands";
+import { Telemetry } from "./read/telemetry";
+import { telemetryCommand } from "./read/telemetry-command";
+import { cacheCommand, rateLimitCommand } from "./read/commands";
 import {
   workflowAnnotationsCommand,
   workflowCancelCommand,
@@ -103,6 +107,7 @@ const prCommand = Command.make("pr", {}).pipe(
     prCreateCommand,
     prCloseCommand,
     prEditCommand,
+    prCheckboxCommand,
     prMergeCommand,
     prReadyCommand,
     prDraftCommand,
@@ -221,6 +226,7 @@ const mainCommand = Command.make("gh-tool", {}).pipe(
 
 Wraps the GitHub CLI (gh) with structured output for AI agents.
 Supports PR management, issue management, reviews, CI checks, and repo info.
+Use 'rate-limit' to inspect GitHub API quota without consuming it.
 
 WORKFLOW FOR AI AGENTS:
   1. Use 'pr view' to inspect current PR
@@ -250,6 +256,8 @@ WORKFLOW FOR AI AGENTS:
   24. Use 'gist list/view' to read gists and 'gist create --files a.ts --desc "..."' to share snippets`,
   ),
   Command.withSubcommands([
+    rateLimitCommand,
+    telemetryCommand,
     prCommand,
     issueCommand,
     repoCommand,
@@ -274,10 +282,28 @@ const MainLayer = GitHubService.layer.pipe(
   Layer.provideMerge(ConfigServiceLayer),
 );
 
-const program = withReadCache(withRedactedOutput(withAudit("gh", cli))).pipe(
-  Effect.provide(MainLayer),
-  Effect.tapCause(renderCauseToStderr),
-);
+const observed = Effect.gen(function* () {
+  const audit = yield* AuditService;
+  let store = null;
+  try {
+    store = openRequestTelemetry(audit.dbPath);
+  } catch {
+    /* Telemetry is optional. */
+  }
+  return yield* withReadCache(withRedactedOutput(withAudit("gh", cli))).pipe(
+    Effect.provideService(Telemetry, store),
+    Effect.ensuring(
+      Effect.sync(() => {
+        try {
+          store?.close();
+        } catch {
+          /* Best effort. */
+        }
+      }),
+    ),
+  );
+});
+const program = observed.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/gh-tool/pr/checkbox-markdown.ts

@@ -0,0 +1,317 @@
+export type CheckboxOutlineEntry =
+  | { readonly type: "task"; readonly text: string; readonly checked: boolean }
+  | { readonly type: "heading"; readonly text: string; readonly level: number };
+
+export type CheckboxOutlineParser = (body: string) => readonly CheckboxOutlineEntry[] | null;
+
+type CheckboxLine = {
+  readonly before: string;
+  readonly offset: number;
+  readonly boxIndex: number;
+  readonly checked: boolean;
+};
+
+type ScannedEntry = CheckboxOutlineEntry & {
+  readonly offset?: number;
+  readonly boxIndex?: number;
+  readonly before?: string;
+};
+
+type Fence = {
+  readonly marker: "`" | "~";
+  readonly length: number;
+  readonly listIndent: number | null;
+};
+type ListItemIndent = { readonly indent: number; readonly contentIndent: number };
+
+const taskSuffix = /^[ \t]*\[([ xX])\][ \t]*(.*)$/;
+const listMarker = /^( {0,3})(?:[-*+]|[0-9]+[.)])([ \t]+)/;
+const quoteMarker = /^ {0,3}>[ \t]?/;
+const plainSourceText = (text: string) =>
+  text
+    .replace(/(\*\*|__|~~|\*|_)(\S(?:.*?\S)?)\1/g, "$2")
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .trim();
+
+const removeContainers = (line: string) => {
+  let cursor = 0;
+  for (;;) {
+    const rest = line.slice(cursor);
+    const quote = quoteMarker.exec(rest);
+    if (quote !== null) {
+      cursor += quote[0].length;
+      continue;
+    }
+    const list = listMarker.exec(rest);
+    if (list !== null) {
+      cursor += list[0].length;
+      continue;
+    }
+    return { text: line.slice(cursor), cursor };
+  }
+};
+
+const openingFence = (line: string, listIndent: number | null): Fence | null => {
+  const content = removeContainers(line).text;
+  const match = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)\r?$/.exec(content);
+  if (match === null) return null;
+  const marker = match[1]?.[0];
+  const info = match[2] ?? "";
+  if ((marker !== "`" && marker !== "~") || (marker === "`" && info.includes("`"))) return null;
+  return { marker, length: match[1]?.length ?? 0, listIndent };
+};
+
+const closesFence = (line: string, fence: Fence) => {
+  const content = removeContainers(line).text;
+  const match = /^ {0,3}(`+|~+)[ \t]*\r?$/.exec(content);
+  const markers = match?.[1] ?? "";
+  return markers.length >= fence.length && markers[0] === fence.marker;
+};
+
+const headingFromLine = (line: string) => {
+  const { text } = removeContainers(line);
+  const match = /^ {0,3}(#{1,6})[ \t]+(.*?)\r?$/.exec(text);
+  if (match === null) return null;
+  return {
+    level: match[1]?.length ?? 0,
+    text: plainSourceText((match[2] ?? "").replace(/[ \t]+#+[ \t]*$/, "")),
+  };
+};
+
+const scanOutline = (body: string): ScannedEntry[] => {
+  const entries: ScannedEntry[] = [];
+  const lines = body.match(/[^\n]*(?:\n|$)/g) ?? [];
+  let offset = 0;
+  let fence: Fence | null = null;
+  const listItems: ListItemIndent[] = [];
+
+  for (const raw of lines) {
+    if (raw.length === 0) continue;
+    const line = (raw.endsWith("\n") ? raw.slice(0, -1) : raw).replace(/\r$/, "");
+    const lineStart = offset;
+    offset += raw.length;
+
+    const marker = listMarker.exec(line);
+    if (marker !== null) {
+      const indent = marker[1]?.length ?? 0;
+      while ((listItems.at(-1)?.indent ?? -1) >= indent) {
+        listItems.pop();
+      }
+      listItems.push({ indent, contentIndent: indent + marker[0].length });
+    } else if (line.trim() !== "") {
+      const leading = /^ */.exec(line)?.[0].length ?? 0;
+      while (listItems.length > 0 && leading < (listItems.at(-1)?.contentIndent ?? 0)) {
+        listItems.pop();
+      }
+    }
+
+    if (fence !== null) {
+      if (fence.listIndent !== null && line.trim() !== "") {
+        const leading = /^ */.exec(line)?.[0].length ?? 0;
+        if (leading < fence.listIndent) fence = null;
+      }
+      if (fence !== null) {
+        if (closesFence(line, fence)) fence = null;
+        continue;
+      }
+    }
+
+    const context = listItems.at(-1);
+    const opening = openingFence(line, context?.contentIndent ?? null);
+    if (opening !== null) {
+      fence = opening;
+      continue;
+    }
+
+    const heading = headingFromLine(line);
+    if (heading !== null) {
+      entries.push({ type: "heading", ...heading });
+      continue;
+    }
+
+    const { text, cursor } = removeContainers(line);
+    const task = taskSuffix.exec(text);
+    if (task === null) continue;
+    const checked = task[1] !== " ";
+    const boxIndex = cursor + (text.indexOf("[") + 1);
+    const content = plainSourceText(task[2] ?? "");
+    entries.push({
+      type: "task",
+      text: content,
+      checked,
+      offset: lineStart + boxIndex,
+      boxIndex,
+      before: line.replace(/\r$/, ""),
+    });
+  }
+  return entries;
+};
+
+const tokenPrefix = "\uE000checkbox:";
+const tokenSuffix = ":\uE001";
+const makeToken = (id: number) => `${tokenPrefix}${id}${tokenSuffix}`;
+const tokenPattern = /\uE000checkbox:(\d+):\uE001/g;
+
+export const bunMarkdownOutline: CheckboxOutlineParser = (body) => {
+  const markdown = (globalThis as typeof globalThis & { Bun?: typeof Bun }).Bun?.markdown;
+  if (markdown?.render === undefined) return null;
+
+  const nodes: Array<{ readonly entry: CheckboxOutlineEntry | null; readonly children: string }> =
+    [];
+  const token = (entry: CheckboxOutlineEntry | null, children: string) => {
+    const id = nodes.push({ entry, children }) - 1;
+    return makeToken(id);
+  };
+  const plain = (value: string) => value.replace(tokenPattern, "").trim();
+
+  const rendered = markdown.render(body, {
+    text: (children) => children,
+    strong: (children) => children,
+    emphasis: (children) => children,
+    strikethrough: (children) => children,
+    link: (children) => children,
+    image: (children) => children,
+    codespan: (children) => children,
+    heading: (children, meta) =>
+      token({ type: "heading", level: meta.level, text: plain(children) }, children),
+    listItem: (children, meta) =>
+      token(
+        typeof meta.checked === "boolean"
+          ? { type: "task", checked: meta.checked, text: plain(children) }
+          : null,
+        children,
+      ),
+  });
+
+  const outline: CheckboxOutlineEntry[] = [];
+  const expand = (value: string) => {
+    for (const match of value.matchAll(tokenPattern)) {
+      const idText = match[1];
+      const id = idText === undefined ? -1 : Number(idText);
+      const node = nodes[id];
+      if (node === undefined || match.index === undefined)
+        throw new Error("Invalid Bun Markdown callback outline");
+      if (node.entry !== null) outline.push(node.entry);
+      expand(node.children);
+    }
+  };
+  expand(rendered);
+  return outline;
+};
+
+const sameOutline = (scanned: readonly ScannedEntry[], parsed: readonly CheckboxOutlineEntry[]) => {
+  return (
+    scanned.length === parsed.length &&
+    scanned.every((entry, index) => {
+      const actual = parsed[index];
+      return (
+        actual !== undefined &&
+        entry.type === actual.type &&
+        entry.text === actual.text &&
+        (entry.type !== "heading" || (actual.type === "heading" && entry.level === actual.level)) &&
+        (entry.type !== "task" || (actual.type === "task" && entry.checked === actual.checked))
+      );
+    })
+  );
+};
+
+const sameEntry = (left: CheckboxOutlineEntry, right: CheckboxOutlineEntry) =>
+  left.type === right.type &&
+  left.text === right.text &&
+  (left.type !== "heading" || (right.type === "heading" && left.level === right.level)) &&
+  (left.type !== "task" || (right.type === "task" && left.checked === right.checked));
+
+export const validateCheckboxEdit = (
+  body: string,
+  offset: number,
+  replacement: " " | "x",
+  parseOutline: CheckboxOutlineParser = bunMarkdownOutline,
+) => {
+  const scanned = scanOutline(body);
+  const original = parseOutline(body);
+  const selectedIndex = scanned.findIndex(
+    (entry) => entry.type === "task" && entry.offset === offset,
+  );
+  if (
+    original === null ||
+    !sameOutline(scanned, original) ||
+    selectedIndex < 0 ||
+    original[selectedIndex]?.type !== "task" ||
+    body[offset] === undefined ||
+    (replacement !== " " && replacement !== "x")
+  ) {
+    throw new Error("PR body structure is ambiguous; tick this item in the GitHub UI");
+  }
+
+  const editedBody = `${body.slice(0, offset)}${replacement}${body.slice(offset + 1)}`;
+  const edited = parseOutline(editedBody);
+  if (edited === null || edited.length !== original.length) {
+    throw new Error("PR body structure is ambiguous; tick this item in the GitHub UI");
+  }
+
+  const expected = [...original];
+  const selected = expected[selectedIndex];
+  if (selected?.type === "task") {
+    expected[selectedIndex] = { ...selected, checked: replacement !== " " };
+  }
+  if (
+    !edited.every((entry, index) => {
+      const expectedEntry = expected[index];
+      return expectedEntry !== undefined && sameEntry(expectedEntry, entry);
+    })
+  ) {
+    throw new Error("PR body structure is ambiguous; tick this item in the GitHub UI");
+  }
+};
+
+export const findCheckboxLines = (
+  body: string,
+  match: string,
+  section: string | null,
+  parseOutline: CheckboxOutlineParser = bunMarkdownOutline,
+) => {
+  const scanned = scanOutline(body);
+  const parsed = parseOutline(body);
+  if (parsed === null || !sameOutline(scanned, parsed)) {
+    throw new Error("PR body structure is ambiguous; tick this item in the GitHub UI");
+  }
+
+  const matches: CheckboxLine[] = [];
+  let sectionLevel: number | null = null;
+  let inSection = section === null;
+
+  for (const entry of scanned) {
+    if (entry.type === "heading") {
+      if (sectionLevel !== null && entry.level <= sectionLevel) {
+        inSection = false;
+        sectionLevel = null;
+      }
+      if (section !== null && entry.text === section) {
+        inSection = true;
+        sectionLevel = entry.level;
+      }
+      continue;
+    }
+    if (!inSection || !entry.text.includes(match)) continue;
+    if (entry.offset === undefined || entry.boxIndex === undefined || entry.before === undefined)
+      continue;
+    matches.push({
+      before: entry.before,
+      offset: entry.offset,
+      boxIndex: entry.boxIndex,
+      checked: entry.checked,
+    });
+  }
+  return matches;
+};
+
+export const scanCheckboxOutline = (body: string): readonly CheckboxOutlineEntry[] =>
+  scanOutline(body).map((entry) =>
+    entry.type === "task"
+      ? { type: entry.type, text: entry.text, checked: entry.checked }
+      : { type: entry.type, text: entry.text, level: entry.level },
+  );