@agjs/tsforge 0.1.0

package/src/lib/fs/process.ts

@@ -0,0 +1,146 @@
+/** Drain a spawned process's piped stdout + stderr to strings (the one place
+ *  this Bun pattern lives). Pass `proc.stdout, proc.stderr` from a process
+ *  spawned with `stdout: "pipe", stderr: "pipe"`. */
+export async function readProcessOutput(
+  stdout: ReadableStream<Uint8Array>,
+  stderr: ReadableStream<Uint8Array>
+): Promise<{ stdout: string; stderr: string }> {
+  const [out, err] = await Promise.all([
+    new Response(stdout).text(),
+    new Response(stderr).text(),
+  ]);
+
+  return { stdout: out, stderr: err };
+}
+
+/** Options for `runShellCommand` — cancellation, an optional kill-timeout, and
+ *  optional live output streaming. */
+export interface IShellRunOptions {
+  /** Abort signal — when it fires, the child process is killed. */
+  signal?: AbortSignal;
+  /** Kill the process after this many ms (0 / omitted = no timeout). */
+  timeoutMs?: number;
+  /** Forward each decoded output chunk live; omit to just capture. */
+  onChunk?: (text: string) => void;
+}
+
+/** Result of `runShellCommand` — captured streams + how it ended. */
+export interface IShellRun {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  /** True when the kill-timeout fired (vs the command exiting on its own). */
+  timedOut: boolean;
+}
+
+/**
+ * Spawn `sh -c command` in `cwd` and capture stdout/stderr — the ONE place that
+ * runs a shell command for the harness (the `run` tool and the gate both route
+ * here), so cancellation and the kill-timeout are enforced uniformly. A pending
+ * `signal` abort or an elapsed `timeoutMs` kills the child (otherwise a model-
+ * issued `vite dev`/`tail -f`/hung test would wedge the harness with no escape).
+ * `onChunk` streams output live; without it output is just captured.
+ */
+export async function runShellCommand(
+  cwd: string,
+  command: string,
+  opts: IShellRunOptions = {}
+): Promise<IShellRun> {
+  return runArgvCommand(cwd, ["sh", "-c", command], opts);
+}
+
+/**
+ * Like `runShellCommand`, but spawns an explicit argv with NO shell — so
+ * arguments are passed literally and can't be expanded/injected (`$()`, backticks,
+ * globbing). Use this for any command built from model- or content-supplied
+ * values (e.g. ripgrep patterns). A missing binary resolves to exit 127, not a
+ * throw, so callers can degrade gracefully.
+ */
+export async function runArgvCommand(
+  cwd: string,
+  argv: string[],
+  opts: IShellRunOptions = {}
+): Promise<IShellRun> {
+  const { signal, timeoutMs = 0, onChunk } = opts;
+
+  let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+
+  try {
+    proc = Bun.spawn(argv, { cwd, stdout: "pipe", stderr: "pipe" });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    return { stdout: "", stderr: message, exitCode: 127, timedOut: false };
+  }
+
+  let timedOut = false;
+  const timer =
+    timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          proc.kill();
+        }, timeoutMs)
+      : null;
+
+  const onAbort = (): void => {
+    proc.kill();
+  };
+
+  if (signal !== undefined) {
+    if (signal.aborted) {
+      proc.kill();
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+
+  const decoder = new TextDecoder();
+  const buf: { out: string; err: string } = { out: "", err: "" };
+  // Read through a closure so control-flow analysis treats these as `boolean`
+  // (the setTimeout/abort mutations are invisible to it, else it narrows to
+  // literal `false` and the kill branch reads as dead code).
+  const wasKilled = (): boolean => timedOut || (signal?.aborted ?? false);
+
+  const pump = async (
+    stream: ReadableStream<Uint8Array>,
+    key: "out" | "err"
+  ): Promise<void> => {
+    for await (const bytes of stream) {
+      const text = decoder.decode(bytes, { stream: true });
+
+      buf[key] += text;
+
+      if (onChunk !== undefined) {
+        onChunk(text);
+      }
+    }
+  };
+
+  try {
+    const pumps = Promise.all([
+      pump(proc.stdout, "out"),
+      pump(proc.stderr, "err"),
+    ]);
+    const exitCode = await proc.exited;
+
+    // A KILLED process can leave its piped streams open in Bun, so the pumps
+    // would hang forever — flush briefly, then return what we captured. On a
+    // normal exit the streams close and the pumps resolve on their own.
+    await (wasKilled()
+      ? Promise.race([
+          pumps,
+          new Promise<void>((resolve) => setTimeout(resolve, 100)),
+        ])
+      : pumps);
+
+    return { stdout: buf.out, stderr: buf.err, exitCode, timedOut };
+  } finally {
+    if (timer !== null) {
+      clearTimeout(timer);
+    }
+
+    if (signal !== undefined) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  }
+}

package/src/lib/guards/guards.ts

@@ -0,0 +1,9 @@
+/** Narrow `unknown` to a record without a type assertion. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Narrow `unknown` to an array of `unknown` (not `any[]`). */
+export function isArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}

package/src/lib/guards/index.ts

@@ -0,0 +1 @@
+export * from "./guards";

package/src/lib/json/index.ts

@@ -0,0 +1 @@
+export * from "./json";

package/src/lib/json/json.ts

@@ -0,0 +1,12 @@
+/** Pull a JSON object out of a fenced ```json block or raw text. */
+export function extractJson(text: string): string {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+
+  if (fenced?.[1] !== undefined) {
+    return fenced[1];
+  }
+
+  const braced = /\{[\s\S]*\}/.exec(text);
+
+  return braced?.[0] ?? text;
+}

package/src/lib/scope/index.ts

@@ -0,0 +1,2 @@
+export * from "./scope";
+export * from "./scope.constants";

package/src/lib/scope/scope.constants.ts

@@ -0,0 +1,3 @@
+/** A throwaway prefix the model may always write to — `scratch/` experiments are
+ *  ignored by the gate, so it can test hypotheses by running code. */
+export const SCRATCH_PREFIX = "scratch/";

package/src/lib/scope/scope.ts

@@ -0,0 +1,40 @@
+import { resolve, relative } from "node:path";
+import { SCRATCH_PREFIX } from "./scope.constants";
+
+/**
+ * Normalize a model-supplied path against the workspace root, fixing the common
+ * small-model footguns that otherwise nest files wrongly: an ABSOLUTE path inside
+ * the workspace, or a RELATIVE path that redundantly repeats the workspace
+ * location (`agjs/code/app/x.ts` while cwd is `/agjs/code/app` → without this it
+ * lands at `…/app/agjs/code/app/x.ts`). Returns a path relative to `cwd`; a path
+ * that escapes the workspace comes back with `../` and is then rejected by scope.
+ */
+export function normalizeWorkspacePath(cwd: string, file: string): string {
+  const cwdNoSlash = cwd.replace(/^\/+/, "");
+  let candidate = file;
+
+  if (candidate.startsWith(`${cwd}/`)) {
+    candidate = candidate.slice(cwd.length + 1);
+  } else if (candidate.startsWith(`${cwdNoSlash}/`)) {
+    candidate = candidate.slice(cwdNoSlash.length + 1);
+  }
+
+  return relative(cwd, resolve(cwd, candidate));
+}
+
+/** True when `file` matches any of the glob `patterns` (the editable scope). */
+export function isInScope(file: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => new Bun.Glob(pattern).match(file));
+}
+
+/** A file the model may write: its editable scope, OR a throwaway scratch file.
+ *  A path that escapes the workspace (`../…`) or is absolute is NEVER writable —
+ *  a recursive glob would otherwise match a traversal path. Normalize with
+ *  `normalizeWorkspacePath` first so this sees the workspace-relative form. */
+export function writable(file: string, patterns: string[]): boolean {
+  if (file.startsWith("..") || file.startsWith("/")) {
+    return false;
+  }
+
+  return isInScope(file, patterns) || file.startsWith(SCRATCH_PREFIX);
+}

package/src/loop/astgrep-fix.ts

@@ -0,0 +1,228 @@
+import { join } from "node:path";
+import { readProcessOutput } from "../lib/fs";
+
+/**
+ * Deterministic, SAFE strict-TS idiom rewrites via ast-grep (structural, not
+ * regex — it won't match inside strings/comments, and it understands the AST).
+ * This is the "tsFixAll, but for idioms": mechanical quality fixes the model
+ * shouldn't burn turns on. The `tsc -p` gate stays the authority — a rewrite
+ * that broke anything would fail it.
+ *
+ * ONLY semantics-preserving rewrites belong here. `new Array(n).fill(x)` →
+ * `Array.from({length:n},()=>x)` is safe (same array, but typed `T[]` instead of
+ * `any[]`, which is the whole point). Loop restructures (bind-and-guard →
+ * `.entries()`) are NOT safe blind codemods — those stay as guidance.
+ */
+interface IRewrite {
+  pattern: string;
+  rewrite: string;
+  note: string;
+}
+
+const SAFE_REWRITES: readonly IRewrite[] = [
+  {
+    pattern: "new Array($N).fill($X)",
+    rewrite: "Array.from({ length: $N }, () => $X)",
+    note: "new Array().fill() is any[] under strict; Array.from is typed",
+  },
+];
+
+/**
+ * Drop a redundant type annotation on a `const` whose initializer already makes
+ * the type obvious to inference — the over-annotation a reviewer flags but no
+ * stock eslint rule catches (`no-inferrable-types` fires only on LITERAL
+ * initializers, never on calls/expressions). Structural, so it can't misfire on
+ * strings/comments. The `constraints` exclude the cases where dropping the
+ * annotation would CHANGE the inferred type: an empty/array/object literal
+ * (`number[] = []` infers `never[]`), `null`, or a function/arrow (loses its
+ * contextual parameter types under strict). Even so this is only HALF the
+ * safety — the caller re-runs the full gate and reverts the file if anything
+ * regressed, so an unsafe drop we didn't foresee can never ship.
+ */
+const DROP_ANNOTATION_RULE = `
+id: drop-redundant-annotation
+language: typescript
+rule:
+  pattern: 'const $A: $T = $B'
+constraints:
+  B:
+    not:
+      any:
+        - { kind: array }
+        - { kind: object }
+        - { kind: 'null' }
+        - { kind: arrow_function }
+        - { kind: function_expression }
+fix: 'const $A = $B'
+`;
+
+/**
+ * Strip the model's #1 needless `as` cast: a LITERAL annotated with its own union
+ * type in data — e.g. `"open" as Status` or `200 as HttpCode`. A
+ * string/number/boolean literal that's a member of the target union is ALREADY
+ * assignable, so the cast is pure ceremony the gate rejects anyway. The model writes
+ * these reflexively (a deep TS prior) on the very first file and then burns turns
+ * removing them; stripping deterministically means it never has to. SAFE by
+ * construction: only string/number/true/false operands (not identifiers, so a real
+ * value-cast like `x as Foo` is left for the model to narrow), and `as const` is
+ * excluded. tsc re-validates — if a literal genuinely wasn't assignable, the real
+ * error surfaces (better than a cast hiding it).
+ */
+const STRIP_LITERAL_CAST_RULE = `
+id: strip-literal-cast
+language: typescript
+rule:
+  pattern: $LIT as $TYPE
+constraints:
+  LIT:
+    any:
+      - { kind: string }
+      - { kind: number }
+      - { kind: 'true' }
+      - { kind: 'false' }
+  TYPE:
+    not: { regex: '^const$' }
+fix: $LIT
+`;
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..", "..");
+const AST_GREP = join(REPO_ROOT, "node_modules", ".bin", "ast-grep");
+
+async function astGrep(
+  args: string[]
+): Promise<{ stdout: string; ok: boolean }> {
+  const proc = Bun.spawn([AST_GREP, ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const { stdout } = await readProcessOutput(proc.stdout, proc.stderr);
+  const code = await proc.exited;
+
+  return { stdout, ok: code === 0 };
+}
+
+/**
+ * Apply the safe idiom rewrites to `absFile` in place. Returns how many matches
+ * were rewritten. No-ops (returns 0) if ast-grep isn't available, so it can
+ * never break the loop — the gate re-validates regardless.
+ */
+export async function astGrepFix(absFile: string): Promise<number> {
+  if (!(await Bun.file(AST_GREP).exists())) {
+    return 0;
+  }
+
+  let applied = 0;
+
+  for (const r of SAFE_REWRITES) {
+    // Count matches first (JSON), then apply — so we can report an exact count.
+    const found = await astGrep([
+      "run",
+      "-p",
+      r.pattern,
+      "-l",
+      "ts",
+      "--json",
+      absFile,
+    ]);
+
+    if (!found.ok) {
+      continue;
+    }
+
+    let matches = 0;
+
+    try {
+      const parsed: unknown = JSON.parse(found.stdout);
+
+      matches = Array.isArray(parsed) ? parsed.length : 0;
+    } catch {
+      // non-JSON output → leave matches at 0
+    }
+
+    if (matches === 0) {
+      continue;
+    }
+
+    const done = await astGrep([
+      "run",
+      "-p",
+      r.pattern,
+      "--rewrite",
+      r.rewrite,
+      "-l",
+      "ts",
+      "--update-all",
+      absFile,
+    ]);
+
+    if (done.ok) {
+      applied += matches;
+    }
+  }
+
+  return applied;
+}
+
+/**
+ * Apply an inline ast-grep RULE (with constraints) to `absFile` in place: count the
+ * constraint-filtered matches, then rewrite them, returning the count. No-ops to 0
+ * if ast-grep is absent. NOT verified here — a caller that does an unsafe rewrite
+ * MUST re-gate (the full `tsc`/eslint gate is the authority and reverts can't ship).
+ */
+async function applyInlineRule(rule: string, absFile: string): Promise<number> {
+  if (!(await Bun.file(AST_GREP).exists())) {
+    return 0;
+  }
+
+  const found = await astGrep([
+    "scan",
+    "--inline-rules",
+    rule,
+    "--json=compact",
+    absFile,
+  ]);
+
+  if (!found.ok) {
+    return 0;
+  }
+
+  let matches: number;
+
+  try {
+    const parsed: unknown = JSON.parse(found.stdout);
+
+    matches = Array.isArray(parsed) ? parsed.length : 0;
+  } catch {
+    return 0;
+  }
+
+  if (matches === 0) {
+    return 0;
+  }
+
+  const done = await astGrep([
+    "scan",
+    "--inline-rules",
+    rule,
+    "--update-all",
+    absFile,
+  ]);
+
+  return done.ok ? matches : 0;
+}
+
+/**
+ * Strip redundant `const` type annotations in `absFile` (see DROP_ANNOTATION_RULE).
+ * Caller MUST re-gate and revert on regression; this only performs the rewrite.
+ */
+export async function dropRedundantAnnotations(
+  absFile: string
+): Promise<number> {
+  return applyInlineRule(DROP_ANNOTATION_RULE, absFile);
+}
+
+/** Strip needless literal-to-union `as` casts in `absFile` (see the rule's note).
+ *  Safe by construction; the gate re-validates regardless. */
+export async function stripLiteralCasts(absFile: string): Promise<number> {
+  return applyInlineRule(STRIP_LITERAL_CAST_RULE, absFile);
+}

package/src/loop/feedback/feedback.ts

@@ -0,0 +1,138 @@
+import { join, basename, isAbsolute } from "node:path";
+import type { ITask } from "../../spec";
+import type { ErrorSet } from "../../validate";
+import type { IMetaRuleViolation } from "../../meta-rules";
+import { isInScope } from "../../lib/scope";
+import { readFiles } from "../../lib/fs";
+import { ruleHelp, idiomHints } from "../feedback/rule-docs";
+import {
+  metaRuleHelp,
+  renderMetaViolations,
+} from "../feedback/meta-rule-feedback";
+
+/** Cap rendered source lines so a large error set can't wall the model. */
+const FEEDBACK_MAX_LINES = 20;
+
+/**
+ * Gate failures the model can act on (its editable files), each rendered WITH
+ * its location and the offending source line — so the model fixes the exact
+ * spot instead of reading the file and hand-counting to find it (which it did
+ * for 3 turns on `money` when feedback was message-only). Plus the rules' fix
+ * examples. Async because it reads the source lines from disk.
+ */
+export async function gateFeedback(
+  errors: ErrorSet,
+  task: ITask,
+  cwd: string,
+  metaViolations: readonly IMetaRuleViolation[] = []
+): Promise<string> {
+  const own = errors.filter(
+    (e) =>
+      e.file === undefined ||
+      isInScope(e.file, task.files) ||
+      isInScope(basename(e.file), task.files)
+  );
+  const readOnly = errors.length - own.length;
+
+  const list =
+    own.length > 0
+      ? await renderErrors(own.slice(0, FEEDBACK_MAX_LINES), cwd)
+      : "(no failures in your editable files)";
+  const capped =
+    own.length > FEEDBACK_MAX_LINES
+      ? `\n… and ${own.length - FEEDBACK_MAX_LINES} more — fix the above first.`
+      : "";
+
+  const note =
+    readOnly > 0
+      ? `\n(${readOnly} other error(s) are in read-only files — not yours to fix; they resolve once your files are correct.)`
+      : "";
+
+  const help = ruleHelp(own);
+  const helpBlock =
+    help.length > 0 ? `\n\nHow to satisfy the gate:\n${help}` : "";
+
+  const sources = await readFiles(cwd, task.files);
+  const idioms = idiomHints(
+    sources.map((s) => s.content),
+    own
+  );
+  const idiomBlock =
+    idioms.length > 0 ? `\n\nWatch for these strict-TS idioms:\n${idioms}` : "";
+
+  // Render meta-rule violations (project structure violations)
+  const metaViolationsList =
+    metaViolations.length > 0 ? renderMetaViolations(metaViolations) : "";
+  const metaBlock =
+    metaViolationsList.length > 0
+      ? `\n\n## Project structure\n${metaViolationsList}`
+      : "";
+
+  const metaHelp = metaRuleHelp(metaViolations);
+  const metaHelpBlock = metaHelp.length > 0 ? `\n${metaHelp}` : "";
+
+  // Tool-use lapse guard: if an editable file doesn't exist, the model likely
+  // wrote the code as message TEXT instead of calling `create`. Code in your
+  // reply is NEVER applied — only tool calls touch disk. Say so explicitly.
+  const present = new Set(sources.map((s) => s.path));
+  const missing = task.files.filter((f) => !present.has(f));
+  const missingBlock =
+    missing.length > 0
+      ? `\n\n⚠ These editable files do NOT exist yet: ${missing.join(", ")}. ` +
+        "Code written in your message text is NOT applied — you MUST call the " +
+        "`create` tool with the file path and full content."
+      : "";
+
+  return `The acceptance command still fails:\n${list}${capped}${note}${helpBlock}${idiomBlock}${metaBlock}${metaHelpBlock}${missingBlock}\n\nFix your editable files and run it again.`;
+}
+
+/**
+ * Render each error as `- file:line [rule] message` followed by the offending
+ * source line, so the model sees the exact code to change. Reads each file once
+ * (cached); falls back to the bare message when there's no location.
+ */
+async function renderErrors(errors: ErrorSet, cwd: string): Promise<string> {
+  const sources = new Map<string, string[]>();
+
+  const linesOf = async (file: string): Promise<string[]> => {
+    const cached = sources.get(file);
+
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const abs = isAbsolute(file) ? file : join(cwd, file);
+    const handle = Bun.file(abs);
+    const lines = (await handle.exists())
+      ? (await handle.text()).split("\n")
+      : [];
+
+    sources.set(file, lines);
+
+    return lines;
+  };
+
+  const rendered: string[] = [];
+
+  for (const e of errors) {
+    const loc =
+      e.file !== undefined && e.line !== undefined
+        ? `${basename(e.file)}:${e.line} `
+        : "";
+    const rule = e.rule !== undefined ? `[${e.rule}] ` : "";
+    const head = `- ${loc}${rule}${e.message}`;
+
+    if (e.file !== undefined && e.line !== undefined) {
+      const src = (await linesOf(e.file))[e.line - 1];
+
+      if (src !== undefined && src.trim().length > 0) {
+        rendered.push(`${head}\n      ${e.line} │ ${src.trim()}`);
+        continue;
+      }
+    }
+
+    rendered.push(head);
+  }
+
+  return rendered.join("\n");
+}

package/src/loop/feedback/index.ts

@@ -0,0 +1,8 @@
+export { gateFeedback } from "./feedback";
+export {
+  ruleHelp,
+  idiomHints,
+  ruleHelpFromOutput,
+  parseRuleMdx,
+  qualityHints,
+} from "./rule-docs";

package/src/loop/feedback/meta-rule-docs.ts

@@ -0,0 +1,41 @@
+/**
+ * Documentation for meta-rules: project structure and config guardrails.
+ * Each rule is keyed by its ID and includes a one-sentence explanation of the fix.
+ */
+
+export const META_RULE_DOCS: Record<string, string> = {
+  // Supply chain
+  "package-exact-deps":
+    "Use exact versions in dependencies and devDependencies (no ^, ~, or ranges); only peerDependencies should use ranges.",
+
+  "no-overlapping-libs":
+    "Remove duplicate or conflicting library versions from the dependency tree; only one canonical version per library is allowed.",
+
+  // Source text
+  "no-eslint-disable-comments":
+    "Remove `// eslint-disable` comments — they hide warnings. Fix the underlying violation or refactor the code.",
+
+  "no-ts-suppressions":
+    "Remove `// @ts-ignore` and `// @ts-expect-error` comments. Use proper type guards or narrowing instead of suppressing type errors.",
+
+  // Config
+  "tsconfig-paths-exist":
+    "Verify that all paths defined in tsconfig.json point to existing files or directories; remove non-existent paths.",
+
+  "tsconfig-strict":
+    "Enable all strict mode flags in tsconfig.json (strict: true or all strict flags individually).",
+
+  // Testing
+  "test-sibling-required":
+    "Add a test file for each source file; follow naming conventions (foo.ts → foo.test.ts or foo.spec.ts).",
+
+  // CI
+  "workflow-actions-pinned":
+    "Pin GitHub Actions to specific versions in .github/workflows/*.yml (e.g., `actions/checkout@v4`, not `@main`).",
+
+  "workflow-runner-pinned":
+    "Specify an exact runner version in GitHub Actions workflows (e.g., `ubuntu-22.04`, not `ubuntu-latest`).",
+
+  "workflow-timeout-required":
+    "Add a timeout-minutes setting to each GitHub Actions job to prevent hanging workflows.",
+};