@agenteer/stdlib 1.0.0-rc.1

package/src/validators/compile.ts

@@ -0,0 +1,175 @@
+/**
+ * `@agenteer/node-compile` — deterministic compile validator (sub-plan 03 §6).
+ *
+ * M4 ships a TypeScript (`tsc`) adapter only; the adapter interface below
+ * is what community packages (pyright/clippy/go-build) plug into. Choosing
+ * TS-only keeps the surface small and dogfoods from day one.
+ *
+ * Deterministic given identical project state + invoking flags; results
+ * are cacheable on `(manifest, input, ctx_slice)` per sub-plan 00 §11.
+ *
+ * `shell.exec` is declared statically. The caller-supplied `cwd` decides
+ * where tsc runs; capability scope for fs.read is declared dynamically
+ * from input.cwd so workflows only hand over the directory that matters.
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+  authorizeOperation,
+} from "@agenteer/core";
+import {
+  failOutput,
+  passOutput,
+  runCommand,
+  tailOf,
+  ValidatorOutputSchema,
+  type ValidatorIssue,
+  type ValidatorOutput,
+} from "../shared/index.js";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-compile",
+  name: "compile",
+  description:
+    "Run a compile step (v1: TypeScript `tsc`). Returns structured issue list; verdict is DATA.",
+  determinism: "deterministic",
+  required_actions: ["shell.exec:"],
+  dynamic_actions: true,
+  dynamic_action_spec: "fs.read:${input.cwd}",
+  tags: ["validator"],
+});
+
+const InputSchema = z.object({
+  /** Which language toolchain. v1 ships `typescript` only; `x-*` reserved for community. */
+  language: z.enum(["typescript"]),
+  cwd: z.string().min(1),
+  /** Explicit tsconfig path relative to cwd (default: `tsconfig.json`). */
+  tsconfig: z.string().optional(),
+  /** Additional flags (e.g. `--incremental false`). */
+  flags: z.array(z.string()).default([]),
+  timeout_ms: z.number().int().min(1).max(600_000).default(300_000),
+});
+
+type Input = z.input<typeof InputSchema>;
+
+export function compileFactory(): Node<Input, ValidatorOutput> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: ValidatorOutputSchema,
+    ctx: [],
+    model: null,
+    async execute(
+      input: NodeInput<Input>,
+      handle: NodeRuntimeHandle,
+    ): Promise<NodeResult<ValidatorOutput>> {
+      const { language, cwd, tsconfig, flags } = input.original;
+      const timeout_ms = input.original.timeout_ms ?? 300_000;
+
+      try {
+        authorizeOperation(handle.granted, { kind: "shell.exec" });
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: `permission_denied: ${err instanceof Error ? err.message : String(err)}`,
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+
+      const adapter = ADAPTERS[language];
+      const command = adapter.command({ tsconfig, flags: flags ?? [] });
+
+      try {
+        const r = await runCommand(command, {
+          cwd,
+          timeout_ms,
+          signal: handle.signal,
+        });
+        const issues = adapter.parseIssues(r.stdout + "\n" + r.stderr);
+        const verdict: ValidatorOutput["verdict"] = r.exit_code === 0 && issues.length === 0 ? "pass" : "fail";
+        const out =
+          verdict === "pass"
+            ? {
+                ...passOutput(`${language} compile clean (${r.duration_ms}ms)`),
+                exit_code: r.exit_code,
+              }
+            : failOutput(
+                issues.length
+                  ? issues
+                  : [
+                      {
+                        message: `${language} exited ${r.exit_code}${r.timed_out ? " (timed out)" : ""}`,
+                        severity: "error" as const,
+                      },
+                    ],
+                `${language} compile failed: ${issues.length} issue(s)`,
+                {
+                  exit_code: r.exit_code,
+                  stdout_tail: tailOf(r.stdout),
+                  stderr_tail: tailOf(r.stderr),
+                },
+              );
+        return { kind: "output", value: out, evidence: { verdict } };
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+          retryable: true,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const compileManifest = MANIFEST;
+
+/**
+ * Compile adapter interface — community-extensible.
+ *
+ * A compile adapter maps an opaque `language` id to (a) a shell command
+ * and (b) a stdout/stderr parser that extracts structured issues. The
+ * parser must be best-effort: when tool output cannot be parsed, return
+ * an empty list and let the exit code carry the verdict.
+ */
+export interface CompileAdapter {
+  readonly language: string;
+  command(opts: { tsconfig?: string; flags: readonly string[] }): string;
+  parseIssues(combinedOutput: string): ValidatorIssue[];
+}
+
+/** tsc issue regex — `path(line,col): error TSxxxx: message`. */
+const TSC_ISSUE_RE = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+TS\d+:\s+(.*)$/gm;
+
+const TYPESCRIPT_ADAPTER: CompileAdapter = {
+  language: "typescript",
+  command(opts) {
+    const tsconfigArg = opts.tsconfig ? `--project ${JSON.stringify(opts.tsconfig)}` : "";
+    const extra = opts.flags.join(" ");
+    return `npx -y tsc --noEmit ${tsconfigArg} ${extra}`.replace(/\s+/g, " ").trim();
+  },
+  parseIssues(output) {
+    const issues: ValidatorIssue[] = [];
+    for (const m of output.matchAll(TSC_ISSUE_RE)) {
+      const [, file, line, col, sev, msg] = m;
+      issues.push({
+        path: `${file}:${line}:${col}`,
+        message: msg!.trim(),
+        code: "TS",
+        severity: sev === "warning" ? "warning" : "error",
+      });
+    }
+    return issues;
+  },
+};
+
+const ADAPTERS: Record<Input["language"], CompileAdapter> = {
+  typescript: TYPESCRIPT_ADAPTER,
+};

package/src/validators/json_schema_validate.ts

@@ -0,0 +1,103 @@
+/**
+ * `@agenteer/node-json-schema-validate` — deterministic validator (sub-plan 03 §8).
+ *
+ * Validates a value against a Zod schema in-process. The "JSON Schema"
+ * name reflects the published wire contract (sub-plan 02 §2.4); we use
+ * Zod as the runtime validator for M2 since all stdlib consumers are
+ * TypeScript. ajv-backed JSON-Schema validation lands alongside the
+ * registry in M6.
+ *
+ * R3 note: validators emit `verdict: "fail"` as DATA on output, not as
+ * `Failed`. `Failed` is reserved for "couldn't run at all."
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-json-schema-validate",
+  name: "json_schema_validate",
+  description: "Validate a value against a caller-supplied schema; return verdict + errors.",
+  determinism: "deterministic",
+  tags: ["validator"],
+});
+
+// We accept either a Zod schema reference or a raw "any" schema marker.
+// At M2 the common case is Zod; the JSON-Schema path ships later.
+const InputSchema = z.object({
+  /** Value to validate. */
+  value: z.unknown(),
+  /** Zod schema (pass a z.ZodType directly through the factory; runtime accepts unknown to satisfy I/O shape). */
+  schema: z.unknown(),
+});
+
+const ValidationIssueSchema = z.object({
+  path: z.array(z.union([z.string(), z.number()])),
+  message: z.string(),
+  code: z.string().optional(),
+});
+
+const OutputSchema = z.object({
+  verdict: z.enum(["pass", "fail"]),
+  errors: z.array(ValidationIssueSchema),
+  value: z.unknown().optional(),
+});
+
+type Input = z.infer<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function jsonSchemaValidateFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>): Promise<NodeResult<Output>> {
+      const { value, schema } = input.original;
+      if (!isZodType(schema)) {
+        return {
+          kind: "failed",
+          reason: "invalid_input:schema_not_zod",
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+      const parsed = schema.safeParse(value);
+      if (parsed.success) {
+        return {
+          kind: "output",
+          value: { verdict: "pass", errors: [], value: parsed.data },
+          evidence: { verdict: "pass" },
+        };
+      }
+      const errors = parsed.error.issues.map((i) => ({
+        path: [...i.path] as (string | number)[],
+        message: i.message,
+        code: i.code,
+      }));
+      return {
+        kind: "output",
+        value: { verdict: "fail", errors },
+        evidence: { verdict: "fail" },
+      };
+    },
+  };
+}
+
+function isZodType(x: unknown): x is z.ZodTypeAny {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    "_def" in (x as object) &&
+    typeof (x as { safeParse?: unknown }).safeParse === "function"
+  );
+}
+
+export const jsonSchemaValidateManifest = MANIFEST;

package/src/validators/regex_check.ts

@@ -0,0 +1,107 @@
+/**
+ * `@agenteer/node-regex-check` — deterministic regex assertion validator.
+ *
+ * Runs N `must_match` / `must_not_match` patterns against an input string.
+ * Returns `verdict: "fail"` as data per ratified resolution — `Failed`
+ * is reserved for "couldn't run at all" (invalid regex, missing input).
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+} from "@agenteer/core";
+import {
+  failOutput,
+  passOutput,
+  type ValidatorIssue,
+  type ValidatorOutput,
+  ValidatorOutputSchema,
+} from "../shared/index.js";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-regex-check",
+  name: "regex_check",
+  description: "Assert an input satisfies a set of must-match / must-not-match regex rules.",
+  determinism: "deterministic",
+  tags: ["validator"],
+});
+
+const RuleSchema = z.object({
+  id: z.string().min(1),
+  pattern: z.string().min(1),
+  kind: z.enum(["must_match", "must_not_match"]),
+  /** Regex flags (e.g. `i`, `m`). Invalid flags → Failed. */
+  flags: z.string().optional(),
+  /** Human-readable message used when this rule fails. */
+  message: z.string().optional(),
+});
+type Rule = z.infer<typeof RuleSchema>;
+
+const InputSchema = z.object({
+  input: z.string(),
+  rules: z.array(RuleSchema).min(1),
+});
+
+type Input = z.input<typeof InputSchema>;
+
+export function regexCheckFactory(): Node<Input, ValidatorOutput> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: ValidatorOutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>): Promise<NodeResult<ValidatorOutput>> {
+      const { input: text, rules } = input.original;
+
+      const issues: ValidatorIssue[] = [];
+      for (const rule of rules as Rule[]) {
+        let re: RegExp;
+        try {
+          re = new RegExp(rule.pattern, rule.flags);
+        } catch (err) {
+          return {
+            kind: "failed",
+            reason: `invalid_regex:${rule.id}`,
+            retryable: false,
+            details: { error: err instanceof Error ? err.message : String(err) },
+            evidence: { verdict: "fail" },
+          };
+        }
+        const matched = re.test(text);
+        if (rule.kind === "must_match" && !matched) {
+          issues.push({
+            path: rule.id,
+            message: rule.message ?? `expected /${rule.pattern}/ to match`,
+            code: "must_match",
+            severity: "error",
+          });
+        } else if (rule.kind === "must_not_match" && matched) {
+          issues.push({
+            path: rule.id,
+            message: rule.message ?? `expected /${rule.pattern}/ NOT to match`,
+            code: "must_not_match",
+            severity: "error",
+          });
+        }
+      }
+
+      const out: ValidatorOutput =
+        issues.length === 0
+          ? passOutput(`all ${rules.length} regex rule(s) passed`)
+          : failOutput(issues, `${issues.length} of ${rules.length} regex rule(s) failed`);
+
+      return {
+        kind: "output",
+        value: out,
+        evidence: { verdict: out.verdict },
+      };
+    },
+  };
+}
+
+export const regexCheckManifest = MANIFEST;

package/src/validators/test_run.ts

@@ -0,0 +1,199 @@
+/**
+ * `@agenteer/node-test-run` — deterministic test-suite validator
+ * (sub-plan 03 §7).
+ *
+ * M4 ships a vitest adapter. Runs `vitest run --reporter=json` in the
+ * declared cwd, parses per-test results, surfaces failures as structured
+ * issues. Verdict is DATA; `Failed` is reserved for "couldn't run at all"
+ * (binary missing, denylist, capability denied).
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+  authorizeOperation,
+} from "@agenteer/core";
+import {
+  failOutput,
+  passOutput,
+  runCommand,
+  tailOf,
+  ValidatorOutputSchema,
+  type ValidatorIssue,
+  type ValidatorOutput,
+} from "../shared/index.js";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-test-run",
+  name: "test_run",
+  description: "Run a test suite (v1: vitest). Returns structured per-test failures.",
+  determinism: "deterministic",
+  required_actions: ["shell.exec:"],
+  dynamic_actions: true,
+  dynamic_action_spec: "fs.read:${input.cwd}",
+  tags: ["validator"],
+});
+
+const InputSchema = z.object({
+  framework: z.enum(["vitest"]),
+  cwd: z.string().min(1),
+  /** Optional test name or path filter. */
+  filter: z.string().optional(),
+  flags: z.array(z.string()).default([]),
+  timeout_ms: z.number().int().min(1).max(1_800_000).default(600_000),
+});
+
+type Input = z.input<typeof InputSchema>;
+
+export function testRunFactory(): Node<Input, ValidatorOutput> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: ValidatorOutputSchema,
+    ctx: [],
+    model: null,
+    async execute(
+      input: NodeInput<Input>,
+      handle: NodeRuntimeHandle,
+    ): Promise<NodeResult<ValidatorOutput>> {
+      const { framework, cwd, filter, flags } = input.original;
+      const timeout_ms = input.original.timeout_ms ?? 600_000;
+
+      try {
+        authorizeOperation(handle.granted, { kind: "shell.exec" });
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: `permission_denied: ${err instanceof Error ? err.message : String(err)}`,
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+
+      const adapter = ADAPTERS[framework];
+      const command = adapter.command({ ...(filter !== undefined ? { filter } : {}), flags: flags ?? [] });
+
+      try {
+        const r = await runCommand(command, { cwd, timeout_ms, signal: handle.signal });
+        const parsed = adapter.parseReport(r.stdout, r.stderr);
+        const failed = parsed.issues.filter((i) => i.severity === "error");
+        const verdict: ValidatorOutput["verdict"] =
+          r.exit_code === 0 && failed.length === 0 ? "pass" : "fail";
+
+        const out: ValidatorOutput =
+          verdict === "pass"
+            ? {
+                ...passOutput(`${framework} passed (${parsed.testCount} tests, ${r.duration_ms}ms)`),
+                exit_code: r.exit_code,
+              }
+            : failOutput(
+                parsed.issues.length
+                  ? parsed.issues
+                  : [
+                      {
+                        message: `${framework} exited ${r.exit_code}${r.timed_out ? " (timed out)" : ""}`,
+                        severity: "error",
+                      },
+                    ],
+                `${framework}: ${failed.length} test(s) failed`,
+                {
+                  exit_code: r.exit_code,
+                  stdout_tail: tailOf(r.stdout),
+                  stderr_tail: tailOf(r.stderr),
+                },
+              );
+
+        return { kind: "output", value: out, evidence: { verdict } };
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+          retryable: true,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const testRunManifest = MANIFEST;
+
+export interface TestReport {
+  testCount: number;
+  issues: ValidatorIssue[];
+}
+
+export interface TestAdapter {
+  readonly framework: string;
+  command(opts: { filter?: string; flags: readonly string[] }): string;
+  parseReport(stdout: string, stderr: string): TestReport;
+}
+
+/** Parse Vitest's `--reporter=json` output when it's present; fall back to stdout. */
+const VITEST_ADAPTER: TestAdapter = {
+  framework: "vitest",
+  command(opts) {
+    const filter = opts.filter ? ` ${JSON.stringify(opts.filter)}` : "";
+    const extra = opts.flags.join(" ");
+    return `npx -y vitest run --reporter=json${filter} ${extra}`.replace(/\s+/g, " ").trim();
+  },
+  parseReport(stdout, _stderr) {
+    const json = extractLastJson(stdout);
+    if (!json) return { testCount: 0, issues: [] };
+    const issues: ValidatorIssue[] = [];
+    let testCount = 0;
+    type TestResult = {
+      name?: string;
+      fullName?: string;
+      status?: string;
+      failureMessages?: string[];
+    };
+    const testResults: Array<{ testResults?: TestResult[]; name?: string }> =
+      (json as { testResults?: Array<{ testResults?: TestResult[]; name?: string }> }).testResults ??
+      [];
+    for (const file of testResults) {
+      for (const t of file.testResults ?? []) {
+        testCount += 1;
+        if (t.status === "failed") {
+          issues.push({
+            path: `${file.name ?? "<file>"}::${t.fullName ?? t.name ?? "<test>"}`,
+            message: (t.failureMessages ?? ["failed"]).join("\n"),
+            code: "test_failed",
+            severity: "error",
+          });
+        }
+      }
+    }
+    return { testCount, issues };
+  },
+};
+
+const ADAPTERS: Record<Input["framework"], TestAdapter> = {
+  vitest: VITEST_ADAPTER,
+};
+
+function extractLastJson(text: string): unknown | null {
+  // Vitest prints the JSON report on its own line; a few noisy warnings
+  // can precede it. Walk backwards and take the last balanced `{...}`.
+  const idx = text.lastIndexOf("}");
+  if (idx < 0) return null;
+  let depth = 0;
+  for (let i = idx; i >= 0; i -= 1) {
+    const ch = text[i];
+    if (ch === "}") depth += 1;
+    else if (ch === "{") depth -= 1;
+    if (depth === 0) {
+      try {
+        return JSON.parse(text.slice(i, idx + 1));
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}

package/src/validators/typecheck.ts

@@ -0,0 +1,121 @@
+/**
+ * `@agenteer/node-typecheck` — thin wrapper over `compile` with
+ * types-only flags (sub-plan 03 §10).
+ *
+ * v1 supports TypeScript (`tsc --noEmit --strict`). The wrapper exists
+ * separately from `compile` so planners can distinguish "types only"
+ * from "full build"; the underlying adapter is shared.
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+  authorizeOperation,
+} from "@agenteer/core";
+import {
+  failOutput,
+  passOutput,
+  runCommand,
+  tailOf,
+  ValidatorOutputSchema,
+  type ValidatorIssue,
+  type ValidatorOutput,
+} from "../shared/index.js";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-typecheck",
+  name: "typecheck",
+  description: "Types-only check (v1: TypeScript tsc --noEmit --strict).",
+  determinism: "deterministic",
+  required_actions: ["shell.exec:"],
+  dynamic_actions: true,
+  dynamic_action_spec: "fs.read:${input.cwd}",
+  tags: ["validator"],
+});
+
+const InputSchema = z.object({
+  language: z.enum(["typescript"]),
+  cwd: z.string().min(1),
+  tsconfig: z.string().optional(),
+  strict: z.boolean().default(true),
+  timeout_ms: z.number().int().min(1).max(600_000).default(300_000),
+});
+
+type Input = z.input<typeof InputSchema>;
+
+const TSC_ISSUE_RE = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+TS\d+:\s+(.*)$/gm;
+
+export function typecheckFactory(): Node<Input, ValidatorOutput> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: ValidatorOutputSchema,
+    ctx: [],
+    model: null,
+    async execute(
+      input: NodeInput<Input>,
+      handle: NodeRuntimeHandle,
+    ): Promise<NodeResult<ValidatorOutput>> {
+      const { cwd, tsconfig } = input.original;
+      const strict = input.original.strict ?? true;
+      const timeout_ms = input.original.timeout_ms ?? 300_000;
+
+      try {
+        authorizeOperation(handle.granted, { kind: "shell.exec" });
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: `permission_denied: ${err instanceof Error ? err.message : String(err)}`,
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+
+      const tsconfigArg = tsconfig ? `--project ${JSON.stringify(tsconfig)}` : "";
+      const strictFlag = strict ? "--strict" : "";
+      const command = `npx -y tsc --noEmit ${tsconfigArg} ${strictFlag}`.replace(/\s+/g, " ").trim();
+
+      try {
+        const r = await runCommand(command, { cwd, timeout_ms, signal: handle.signal });
+        const combined = `${r.stdout}\n${r.stderr}`;
+        const issues: ValidatorIssue[] = [];
+        for (const m of combined.matchAll(TSC_ISSUE_RE)) {
+          issues.push({
+            path: `${m[1]}:${m[2]}:${m[3]}`,
+            message: m[5]!.trim(),
+            code: "TS",
+            severity: m[4] === "warning" ? "warning" : "error",
+          });
+        }
+        const verdict: ValidatorOutput["verdict"] = r.exit_code === 0 && issues.length === 0 ? "pass" : "fail";
+        const out: ValidatorOutput =
+          verdict === "pass"
+            ? { ...passOutput(`typecheck clean (${r.duration_ms}ms)`), exit_code: r.exit_code }
+            : failOutput(
+                issues.length ? issues : [{ message: `tsc exited ${r.exit_code}`, severity: "error" }],
+                `typecheck: ${issues.length} issue(s)`,
+                {
+                  exit_code: r.exit_code,
+                  stdout_tail: tailOf(r.stdout),
+                  stderr_tail: tailOf(r.stderr),
+                },
+              );
+        return { kind: "output", value: out, evidence: { verdict } };
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+          retryable: true,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const typecheckManifest = MANIFEST;