zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/utils/AGENTS.md

@@ -0,0 +1,22 @@
+# Scope du dossier
+
+- Helpers purs et réutilisables: records, paths, JSON, hashing, formatting.
+- Ce dossier ne doit pas contenir de logique Pi runtime, tools, commands, factories ou orchestration.
+
+# Invariants
+
+- Préserver les messages d'erreur, règles de sanitization, hashing et path matching.
+- Ne pas modifier `pathMatches`, `safeRunId`, `safeFileStem`, ou la logique de bornage d'output.
+- Garder les helpers déterministes sauf si la source ne l'était pas.
+
+# Imports
+
+- Autorisé: modules Node minimaux nécessaires (`node:fs`, `node:path`, `node:crypto`, `node:os`) selon le helper.
+- Interdit: `ExtensionAPI`, runtime Pi, tools, commands, factories, orchestration.
+- Interdit: importer depuis `index.ts`.
+- Utiliser `.js` pour les imports relatifs.
+
+# Validation locale
+
+- `npm run check -- --pretty false`.
+- Si `pathMatches` ou formatting child output bouge: `npm run smoke:harness`.

package/.pi/extensions/zob-harness/src/utils/formatting.ts

@@ -0,0 +1,34 @@
+import type { ChildResult } from "../types.js";
+
+function blockedFeedback(toolName: string, reason: string, attempted: string): string {
+  return [
+    `ZOB damage-control blocked ${toolName}: ${reason}`,
+    "",
+    `Attempted: ${attempted}`,
+    "",
+    "Continue safely:",
+    "- If this was non-destructive reconnaissance, skip it or ask the user for the specific value.",
+    "- If this was destructive, stop and ask for explicit approval with exact command, risk, and rollback plan.",
+    "- Do not retry the same blocked call.",
+  ].join("\n");
+}
+
+function capOutput(output: string, limit = 50 * 1024): string {
+  if (Buffer.byteLength(output, "utf8") <= limit) return output;
+  let truncated = output.slice(0, limit);
+  while (Buffer.byteLength(truncated, "utf8") > limit) truncated = truncated.slice(0, -1);
+  return `${truncated}\n\n[truncated: full output stored in tool details]`;
+}
+
+function formatChildResultText(result: ChildResult): string {
+  const messages: string[] = [];
+  if (result.failureKind) messages.push(`Failure kind: ${result.failureKind}`);
+  if (result.contractErrors && result.contractErrors.length > 0) messages.push(`Blocked before child launch (preflight/config):\n- ${result.contractErrors.join("\n- ")}`);
+  if (result.gateErrors && result.gateErrors.length > 0) messages.push(`Output-contract gate errors (format repair may be enough; inspect and rerun only if content is actually missing):\n- ${result.gateErrors.join("\n- ")}`);
+  if (result.errorMessage) messages.push(`Error: ${result.errorMessage}`);
+  if (result.stderr.trim()) messages.push(`stderr:\n${result.stderr.trim()}`);
+  if (result.output.trim()) messages.push(result.output.trim());
+  return messages.length > 0 ? messages.join("\n\n") : "(no output)";
+}
+
+export { blockedFeedback, capOutput, formatChildResultText };

package/.pi/extensions/zob-harness/src/utils/hashing.ts

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export { sha256, sha256Hex };

package/.pi/extensions/zob-harness/src/utils/json.ts

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isRecord, parseJsonLine } from "./records.js";
+
+function parseJsonFile(path: string): unknown {
+  return JSON.parse(readFileSync(path, "utf8")) as unknown;
+}
+
+function readJsonl(path: string): Array<Record<string, unknown>> {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n").map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line)).filter(isRecord);
+}
+
+function readJsonObjectIfPresent(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = parseJsonFile(path);
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readJsonlRecords(path: string): Array<Record<string, unknown>> {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n").map((line) => line.trim()).filter(Boolean).map((line) => parseJsonLine(line)).filter(isRecord);
+}
+
+export { parseJsonFile, readJsonl, readJsonlRecords, readJsonObjectIfPresent };

package/.pi/extensions/zob-harness/src/utils/paths.ts

@@ -0,0 +1,54 @@
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+function expandHome(input: string): string {
+  if (input === "~") return homedir();
+  if (input.startsWith("~/")) return join(homedir(), input.slice(2));
+  return input;
+}
+
+function wildcardToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`(^|/)${escaped}($|/)`);
+}
+
+export function pathMatches(targetPath: string, pattern: string, cwd: string, policyRoot = cwd): boolean {
+  const expanded = expandHome(pattern);
+  const root = resolve(policyRoot);
+  const normalizedTarget = resolve(cwd, expandHome(targetPath));
+  const relativeTarget = normalizedTarget.startsWith(root) ? normalizedTarget.slice(root.length + 1) : normalizedTarget;
+  if (expanded.endsWith("/")) {
+    const prefix = resolve(root, expanded.slice(0, -1));
+    return normalizedTarget === prefix || normalizedTarget.startsWith(`${prefix}/`) || relativeTarget.startsWith(expanded);
+  }
+  const regex = wildcardToRegex(expanded);
+  return regex.test(normalizedTarget) || regex.test(relativeTarget) || relativeTarget.includes(expanded);
+}
+
+function safeFileStem(value: string): string {
+  return value.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "agent";
+}
+
+function newRunId(prefix: string): string {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function safeRunId(value: string | undefined, prefix: string): string {
+  const raw = value ?? newRunId(prefix);
+  return safeFileStem(raw);
+}
+
+function resolveRepoPath(repoRoot: string, requestedPath: string): { path: string; errors: string[] } {
+  const root = resolve(repoRoot);
+  const resolvedPath = resolve(root, expandHome(requestedPath));
+  if (resolvedPath !== root && !resolvedPath.startsWith(`${root}/`)) {
+    return { path: resolvedPath, errors: [`Path must stay inside repo root: ${requestedPath}`] };
+  }
+  return { path: resolvedPath, errors: [] };
+}
+
+function isSafeArtifactName(value: string): boolean {
+  return value.length > 0 && value === basename(value) && !value.includes("..") && !value.includes("/") && !value.includes("\\\\") && /^[a-zA-Z0-9._-]+$/.test(value);
+}
+
+export { expandHome, isSafeArtifactName, newRunId, resolveRepoPath, safeFileStem, safeRunId };

package/.pi/extensions/zob-harness/src/utils/records.ts

@@ -0,0 +1,25 @@
+import type { AssistantLikeMessage, JsonEvent, TextBlock } from "../types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function textFromMessage(message: AssistantLikeMessage | undefined): string {
+  if (!message || !Array.isArray(message.content)) return "";
+  return message.content
+    .filter((part): part is TextBlock => isRecord(part) && part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n");
+}
+
+function parseJsonLine(line: string): JsonEvent | undefined {
+  try {
+    const value = JSON.parse(line) as unknown;
+    if (!isRecord(value)) return undefined;
+    return value as JsonEvent;
+  } catch {
+    return undefined;
+  }
+}
+
+export { isRecord, parseJsonLine, textFromMessage };

package/.pi/extensions/zob-harness/src/utils/resources.ts

@@ -0,0 +1,38 @@
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BUNDLED_ZOB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "..");
+
+export function bundledZobRoot(): string {
+  return BUNDLED_ZOB_ROOT;
+}
+
+export function projectZobResourcePath(repoRoot: string, ...segments: string[]): string {
+  return join(repoRoot, ".pi", ...segments);
+}
+
+export function bundledZobResourcePath(...segments: string[]): string {
+  return join(BUNDLED_ZOB_ROOT, ".pi", ...segments);
+}
+
+export function readableZobResourcePath(repoRoot: string, ...segments: string[]): string {
+  const projectPath = projectZobResourcePath(repoRoot, ...segments);
+  if (existsSync(projectPath)) return projectPath;
+  return bundledZobResourcePath(...segments);
+}
+
+export function readableZobResourcePaths(repoRoot: string, ...segments: string[]): string[] {
+  const paths = [bundledZobResourcePath(...segments), projectZobResourcePath(repoRoot, ...segments)];
+  return [...new Set(paths)].filter((path) => existsSync(path));
+}
+
+export function listZobResourceJsonStems(repoRoot: string, ...segments: string[]): string[] {
+  const names = new Set<string>();
+  for (const dir of readableZobResourcePaths(repoRoot, ...segments)) {
+    for (const fileName of readdirSync(dir)) {
+      if (fileName.endsWith(".json")) names.add(fileName.slice(0, -".json".length));
+    }
+  }
+  return [...names].sort();
+}