@agjs/tsforge 0.1.0

package/src/rule-packs/utils.ts

@@ -0,0 +1,142 @@
+import path from "node:path";
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { isRecord } from "../lib/guards";
+
+/** Keys on AST nodes that never hold child nodes (or would walk upward). */
+export const NON_AST_KEYS = new Set([
+  "parent",
+  "loc",
+  "range",
+  "tokens",
+  "comments",
+  "start",
+  "end",
+  "leadingComments",
+  "trailingComments",
+  "innerComments",
+]);
+
+/** AST nodes are plain objects with a string `type` discriminant. */
+export function isNodeLike(value: unknown): value is TSESTree.Node {
+  return isRecord(value) && typeof value.type === "string";
+}
+
+/** Push every direct child AST node of `node` onto `stack`. */
+export function pushChildNodes(
+  node: TSESTree.Node,
+  stack: TSESTree.Node[]
+): void {
+  for (const [key, value] of Object.entries(node)) {
+    if (NON_AST_KEYS.has(key)) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (isNodeLike(child)) {
+          stack.push(child);
+        }
+      }
+    } else if (isNodeLike(value)) {
+      stack.push(value);
+    }
+  }
+}
+
+/** Depth-first visit of `root` and all descendants (cycle-safe). */
+export function walkAll(
+  root: TSESTree.Node,
+  callback: (node: TSESTree.Node) => void
+): void {
+  const stack: TSESTree.Node[] = [root];
+  const visited = new WeakSet();
+
+  for (let node = stack.pop(); node !== undefined; node = stack.pop()) {
+    if (visited.has(node)) {
+      continue;
+    }
+
+    visited.add(node);
+    callback(node);
+    pushChildNodes(node, stack);
+  }
+}
+
+/** True if any node in the subtree satisfies `predicate` (cycle-safe). */
+export function walkSome(
+  root: TSESTree.Node,
+  predicate: (node: TSESTree.Node) => boolean
+): boolean {
+  const stack: TSESTree.Node[] = [root];
+  const visited = new WeakSet();
+
+  for (let node = stack.pop(); node !== undefined; node = stack.pop()) {
+    if (visited.has(node)) {
+      continue;
+    }
+
+    visited.add(node);
+
+    if (predicate(node)) {
+      return true;
+    }
+
+    pushChildNodes(node, stack);
+  }
+
+  return false;
+}
+
+/**
+ * Returns the file's repo-relative path with forward slashes for cross-platform consistency.
+ */
+export function toPosixRelative(filename: string, cwd: string): string {
+  const rel = path.relative(cwd, filename);
+
+  return rel.split(path.sep).join("/");
+}
+
+/**
+ * Simple glob-like matching for patterns. Supports:
+ * - `**` (match any directory levels)
+ * - `*` (match any characters except `/`)
+ * - `?` (match single character)
+ * - literal strings
+ */
+export function matchesGlobPattern(path: string, pattern: string): boolean {
+  // Escape regex special chars except * and ?
+  const regexPattern = pattern
+    .split("**/")
+    .join("<<<GLOBSTAR>>>")
+    .split("/")
+    .map((seg) => {
+      if (seg === "<<<GLOBSTAR>>>") {
+        return ".*";
+      }
+
+      return seg
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&") // escape regex chars
+        .replace(/\*/g, "[^/]*") // * matches anything except /
+        .replace(/\?/g, "[^/]"); // ? matches single char except /
+    })
+    .join("/");
+
+  const regex = new RegExp(`^${regexPattern}$`);
+
+  return regex.test(path);
+}
+
+/**
+ * Returns true if the path matches any of the glob patterns.
+ */
+export function matchesAnyGlobPattern(
+  filePath: string,
+  patterns: readonly string[]
+): boolean {
+  if (patterns.length === 0) {
+    return false;
+  }
+
+  return patterns.some((pattern) => matchesGlobPattern(filePath, pattern));
+}

package/src/session-store.ts

@@ -0,0 +1,359 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readdir, mkdir, chmod, stat, unlink } from "node:fs/promises";
+import type { IChatMessage, IToolCall } from "./inference";
+import { isRecord } from "./lib/guards";
+
+/** Days to keep a session before `pruneSessions` deletes it (env-overridable). */
+const DEFAULT_TTL_DAYS = 30;
+const MS_PER_DAY = 86_400_000;
+
+/** Persistence is off when TSFORGE_NO_PERSIST is set — sessions stay in memory only. */
+export function persistenceEnabled(): boolean {
+  return (process.env.TSFORGE_NO_PERSIST ?? "") === "";
+}
+
+/**
+ * On-disk persistence for interactive CLI sessions, so `tsforge --continue` can
+ * resume the most recent conversation for a working directory. One JSON file per
+ * session under `~/.tsforge/sessions/`, rewritten after each turn. Deliberately
+ * simple (flat files, no index) — a session is small and there are never many.
+ */
+export interface ISessionRecord {
+  /** Stable id (also the filename stem). */
+  id: string;
+  /** The working directory this session ran against — `--continue` matches on it. */
+  cwd: string;
+  /** Gate command, if one was set. */
+  accept: string;
+  /** Editable scope globs. */
+  files: string[];
+  /** Last-write time (ms) — newest wins for `--continue`. */
+  updatedAt: number;
+  /** Plan mode was on when last saved — restored on `--continue` so a resumed
+   *  session doesn't silently drop its read-only guarantee. */
+  planMode?: boolean;
+  /** The full conversation, including the system message. */
+  messages: IChatMessage[];
+}
+
+/** The sessions directory — under `$TSFORGE_HOME` if set (tests/sandboxing),
+ *  else the user's home. Read at call time so it can be redirected per process. */
+function storeDir(): string {
+  return join(process.env.TSFORGE_HOME ?? homedir(), ".tsforge", "sessions");
+}
+
+/** The run-logs directory (`--log`): `$TSFORGE_HOME`/.tsforge/logs, else under the
+ *  user's home. A fixed, predictable location so logs are always findable. */
+export function logsDir(): string {
+  return join(process.env.TSFORGE_HOME ?? homedir(), ".tsforge", "logs");
+}
+
+/**
+ * Persist (create or overwrite) a session record — unless persistence is off.
+ * Secrets in message text are redacted FIRST (so they never hit disk), the dir
+ * is created 0700 and the file written 0600 (owner-only). We deliberately do NOT
+ * encrypt: a key stored beside the data only deters backup/sync exfil, not local
+ * compromise — data minimization (redaction) + perms is the higher-value floor.
+ */
+export async function saveSession(record: ISessionRecord): Promise<void> {
+  if (!persistenceEnabled()) {
+    return;
+  }
+
+  const dir = storeDir();
+  const path = join(dir, `${record.id}.json`);
+  const safe: ISessionRecord = {
+    ...record,
+    messages: redactMessages(record.messages),
+  };
+
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await Bun.write(path, JSON.stringify(safe, null, 2));
+  await chmod(path, 0o600);
+}
+
+/** Delete sessions older than `ttlDays` (by file mtime). Best-effort; never throws. */
+export async function pruneSessions(ttlDays?: number): Promise<void> {
+  const envTtl = Number(process.env.TSFORGE_SESSION_TTL_DAYS);
+  const ttl = ttlDays ?? (Number.isFinite(envTtl) ? envTtl : DEFAULT_TTL_DAYS);
+  const dir = storeDir();
+  let names: string[];
+
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+
+  const cutoff = Date.now() - ttl * MS_PER_DAY;
+
+  for (const name of names) {
+    if (!name.endsWith(".json")) {
+      continue;
+    }
+
+    const path = join(dir, name);
+
+    try {
+      const info = await stat(path);
+
+      if (info.mtimeMs < cutoff) {
+        await unlink(path);
+      }
+    } catch {
+      // racing deletion / unreadable — skip
+    }
+  }
+}
+
+/** All saved sessions for `cwd`, newest first. */
+export async function listSessions(cwd: string): Promise<ISessionRecord[]> {
+  const dir = storeDir();
+  let names: string[];
+
+  try {
+    names = await readdir(dir);
+  } catch {
+    return []; // no store yet
+  }
+
+  const records: ISessionRecord[] = [];
+
+  for (const name of names) {
+    if (!name.endsWith(".json")) {
+      continue;
+    }
+
+    const record = await readRecord(join(dir, name));
+
+    if (record !== null && record.cwd === cwd) {
+      records.push(record);
+    }
+  }
+
+  return records.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+/** The most recently-updated session for `cwd`, or null if there is none. */
+export async function latestSession(
+  cwd: string
+): Promise<ISessionRecord | null> {
+  return (await listSessions(cwd))[0] ?? null;
+}
+
+/** Load a specific session by id (for `--resume <id>`), or null if absent. */
+export async function loadSession(id: string): Promise<ISessionRecord | null> {
+  return readRecord(join(storeDir(), `${id}.json`));
+}
+
+async function readRecord(path: string): Promise<ISessionRecord | null> {
+  try {
+    const data: unknown = JSON.parse(await Bun.file(path).text());
+
+    if (
+      isRecord(data) &&
+      typeof data.id === "string" &&
+      typeof data.cwd === "string" &&
+      typeof data.updatedAt === "number" &&
+      Array.isArray(data.messages)
+    ) {
+      return {
+        id: data.id,
+        cwd: data.cwd,
+        accept: typeof data.accept === "string" ? data.accept : "",
+        files: Array.isArray(data.files)
+          ? data.files.filter((f): f is string => typeof f === "string")
+          : [],
+        updatedAt: data.updatedAt,
+        messages: toMessages(data.messages),
+      };
+    }
+  } catch {
+    // unreadable / malformed → skip it
+  }
+
+  return null;
+}
+
+/** Validate a persisted message array back into IChatMessage[] (no `as` casts). */
+function toMessages(raw: readonly unknown[]): IChatMessage[] {
+  const messages: IChatMessage[] = [];
+
+  for (const item of raw) {
+    const message = toMessage(item);
+
+    if (message !== null) {
+      messages.push(message);
+    }
+  }
+
+  return messages;
+}
+
+function toMessage(raw: unknown): IChatMessage | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+
+  const role = toRole(raw.role);
+
+  if (role === null) {
+    return null;
+  }
+
+  const message: IChatMessage = {
+    role,
+    content: typeof raw.content === "string" ? raw.content : "",
+  };
+
+  if (typeof raw.toolCallId === "string") {
+    message.toolCallId = raw.toolCallId;
+  }
+
+  const toolCalls = toToolCalls(raw.toolCalls);
+
+  if (toolCalls.length > 0) {
+    message.toolCalls = toolCalls;
+  }
+
+  return message;
+}
+
+/** Narrow an unknown to the message role union via case-narrowing (no `as`). */
+function toRole(value: unknown): IChatMessage["role"] | null {
+  switch (value) {
+    case "system":
+    case "user":
+    case "assistant":
+    case "tool":
+      return value;
+    default:
+      return null;
+  }
+}
+
+const REDACTED = "[redacted]";
+
+// A PEM private-key block — redact the whole thing.
+const PRIVATE_KEY_BLOCK =
+  /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----/g;
+
+// A password embedded in a connection-string's userinfo (`scheme://user:PASS@host`).
+const CONNECTION_PASSWORD = /(:\/\/[^\s:/@]*:)[^\s:/@]+(@)/g;
+
+// `<key>: <value>` / `<key> = <value>` where the key NAME contains a secret word.
+// The value is only redacted when it actually looks like a secret (see
+// valueLooksSecret) — so `password: string` (a type annotation) survives.
+const SECRET_KEYWORD =
+  /\b([\w.]*(?:password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|client[_-]?secret|credentials?|auth[_-]?token|private[_-]?key)[\w.]*)(\s*["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;{}()]+)/gi;
+
+// Standalone secret SHAPES — the whole match is the secret, replaced wholesale.
+const SECRET_SHAPES: readonly RegExp[] = [
+  /\bsk-[A-Za-z0-9_-]{16,}\b/g, // OpenAI-style keys (incl. sk-proj-)
+  /\b[sprk]k_(?:live|test)_[A-Za-z0-9]{8,}\b/g, // Stripe sk_live_/pk_test_/rk_…
+  /\bgh[posru]_[A-Za-z0-9]{20,}\b/g, // GitHub tokens (ghp_, gho_, …)
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, // GitHub fine-grained PAT
+  /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+  /\bAIza[0-9A-Za-z_-]{20,}\b/g, // Google API key
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, // Slack tokens
+  /\bnpm_[A-Za-z0-9]{36}\b/g, // npm token
+  /\bey[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, // JWTs
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, // Authorization: Bearer …
+];
+
+/** Does a `key=` value look like a real secret (vs a type/identifier)? */
+function valueLooksSecret(value: string): boolean {
+  const quoted =
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"));
+
+  if (quoted) {
+    return value.length - 2 >= 3; // a non-trivial quoted literal
+  }
+
+  // A bare token: secret-looking if it has non-letters (digits/symbols) or is
+  // long. A short pure-letter word (`string`, `number`, `getInput`) is kept.
+  return /[^A-Za-z]/.test(value) || value.length >= 16;
+}
+
+/**
+ * Scrub secrets from text before it is persisted (data minimization). Covers
+ * private-key blocks, connection-string passwords, `<secret-key>: <value>`
+ * assignments (only when the value looks like a real secret), and a battery of
+ * known token shapes (OpenAI/Stripe/GitHub/AWS/Google/Slack/npm/JWT/Bearer).
+ */
+export function redactText(text: string): string {
+  let out = text.replace(PRIVATE_KEY_BLOCK, REDACTED);
+
+  out = out.replace(CONNECTION_PASSWORD, `$1${REDACTED}$2`);
+
+  out = out.replace(
+    SECRET_KEYWORD,
+    (match: string, key: string, sep: string, value: string) =>
+      valueLooksSecret(value) ? `${key}${sep}${REDACTED}` : match
+  );
+
+  for (const shape of SECRET_SHAPES) {
+    out = out.replace(shape, REDACTED);
+  }
+
+  return out;
+}
+
+/**
+ * Redact every message before persisting: its text (user prompts, assistant
+ * answers, AND tool output — a `cat .env` dump is a real leak vector) AND the
+ * string values inside tool-call arguments (a token pasted into a `run` command
+ * or `create` content). Structure is preserved; only string values are scrubbed.
+ */
+function redactMessages(messages: readonly IChatMessage[]): IChatMessage[] {
+  return messages.map((message) => ({
+    ...message,
+    content: redactText(message.content),
+    ...(message.toolCalls === undefined
+      ? {}
+      : { toolCalls: redactToolCalls(message.toolCalls) }),
+  }));
+}
+
+function redactToolCalls(calls: readonly IToolCall[]): IToolCall[] {
+  return calls.map((call) => ({
+    ...call,
+    arguments: redactArgs(call.arguments),
+  }));
+}
+
+function redactArgs(args: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(args)) {
+    out[key] = typeof value === "string" ? redactText(value) : value;
+  }
+
+  return out;
+}
+
+function toToolCalls(raw: unknown): IToolCall[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const calls: IToolCall[] = [];
+
+  for (const call of raw) {
+    if (
+      isRecord(call) &&
+      typeof call.name === "string" &&
+      isRecord(call.arguments)
+    ) {
+      calls.push({
+        id: typeof call.id === "string" ? call.id : undefined,
+        name: call.name,
+        arguments: call.arguments,
+      });
+    }
+  }
+
+  return calls;
+}

package/src/spec/generate-tests.ts

@@ -0,0 +1,213 @@
+import { join } from "node:path";
+import { rm } from "node:fs/promises";
+import type { IChatMessage, IProvider } from "../inference";
+import type { Reporter } from "../loop";
+import { CREATE_TOOL, TOOL_NAME, toCreate } from "../agent";
+import { applyCreate } from "../files/create";
+import { isInScope } from "../lib/scope";
+import { runTests, isRealRed, type IRunTestsResult } from "../validate";
+
+export interface IGenerateTestsOptions {
+  /** Where to write the suite. */
+  testFile: string;
+  /** Where to write the throwing stub the suite runs against (the future impl). */
+  implFile: string;
+  /** One-line statement of what's under test (e.g. the spec title). */
+  goal: string;
+  /** The acceptance criteria prose the tests must encode. */
+  criteria: string;
+  /** Max model turns (default 6). The suite + stub usually land over 1-2 turns. */
+  maxAttempts?: number;
+  onEvent?: Reporter;
+}
+
+export interface IGenerateTestsResult {
+  testFile: string;
+  /** True once the suite loads, collects tests, and is RED against the stub. */
+  ok: boolean;
+  testCount: number;
+  attempts: number;
+}
+
+/**
+ * Turn a spec's acceptance criteria into an executable `bun:test` suite — the
+ * step that lets an *untested* spec enter the deterministic gate.
+ *
+ * The model writes the suite plus a throwing stub of the impl (over one or more
+ * turns), so the suite is runnable (imports resolve) yet starts RED. `runTests`
+ * is the oracle, and a suite is accepted only when it: (1) loads cleanly (no errors),
+ * (2) collects >= 1 test, and (3) is fully RED — every test fails against the
+ * do-nothing stub. (3) is the load-bearing check: a vacuous test that never
+ * calls the implementation would PASS against the stub, and we reject exactly
+ * those. The result is the precise RED seed the implement loop then drives green.
+ */
+export async function generateTests(
+  provider: IProvider,
+  cwd: string,
+  opts: IGenerateTestsOptions
+): Promise<IGenerateTestsResult> {
+  const maxAttempts = opts.maxAttempts ?? 6;
+  const report: Reporter = opts.onEvent ?? (() => undefined);
+  const scope = [opts.testFile, opts.implFile];
+
+  let attempts = 0;
+  let feedback = "";
+
+  while (attempts < maxAttempts) {
+    attempts += 1;
+
+    // Re-prompt with the CURRENT file state each turn rather than wiping
+    // progress: tool-calling models emit roughly one `create` per turn, so the
+    // suite lands one turn and the stub the next. The prompt names which files
+    // are still missing; `create` upserts so a bad file can be overwritten.
+    const present = await whichExist(cwd, [opts.testFile, opts.implFile]);
+    const res = await provider.complete(buildPrompt(opts, present, feedback), {
+      tools: [CREATE_TOOL],
+      temperature: 0,
+      onToken: (text) => {
+        report({ kind: "token", task: opts.testFile, message: text });
+      },
+    });
+
+    for (const call of res.toolCalls) {
+      await applyCreateCall(scope, cwd, call.name, call.arguments, report);
+    }
+
+    const run = await runTests(opts.testFile, cwd);
+    const verdict = assess(run);
+
+    report({
+      kind: "fix",
+      task: opts.testFile,
+      message: `turn ${attempts}: ${run.total} tests, ${run.pass} pass, ${run.fail} fail, ${run.errors} err — ${verdict.ok ? "accepted (RED)" : verdict.reason}`,
+    });
+
+    if (verdict.ok) {
+      return {
+        testFile: opts.testFile,
+        ok: true,
+        testCount: run.total,
+        attempts,
+      };
+    }
+
+    feedback = `${verdict.reason}\nRunner output:\n${run.output}`;
+  }
+
+  return { testFile: opts.testFile, ok: false, testCount: 0, attempts };
+}
+
+/** Which of `files` currently exist in `cwd` (for telling the model what's left). */
+async function whichExist(cwd: string, files: string[]): Promise<Set<string>> {
+  const present = new Set<string>();
+
+  for (const file of files) {
+    if (await Bun.file(join(cwd, file)).exists()) {
+      present.add(file);
+    }
+  }
+
+  return present;
+}
+
+interface IVerdict {
+  ok: boolean;
+  reason: string;
+}
+
+/** The deterministic "are these real tests?" oracle. */
+function assess(run: IRunTestsResult): IVerdict {
+  if (run.errors > 0) {
+    return { ok: false, reason: "the suite failed to load/parse" };
+  }
+
+  if (run.total === 0) {
+    return { ok: false, reason: "no tests were collected" };
+  }
+
+  if (run.pass > 0) {
+    return {
+      ok: false,
+      reason: `${run.pass} test(s) passed against a stub that throws on every call — those tests don't exercise the implementation`,
+    };
+  }
+
+  return { ok: isRealRed(run), reason: "" };
+}
+
+async function applyCreateCall(
+  scope: string[],
+  cwd: string,
+  name: string,
+  args: Record<string, unknown>,
+  report: Reporter
+): Promise<void> {
+  if (name !== TOOL_NAME.create) {
+    return;
+  }
+
+  const create = toCreate(args);
+
+  if (create === null || !isInScope(create.file, scope)) {
+    return;
+  }
+
+  // Upsert: generateTests is the authority for these two scoped files, so a
+  // `create` re-writes (drop any prior, then create) rather than no-clobbering —
+  // the model regenerates a whole file to fix it.
+  await rm(join(cwd, create.file), { force: true });
+
+  const result = await applyCreate(cwd, create);
+
+  if (result.ok) {
+    report({
+      kind: "create",
+      task: create.file,
+      file: create.file,
+      message: `create ${create.file}`,
+      content: create.content,
+    });
+  }
+}
+
+function buildPrompt(
+  opts: IGenerateTestsOptions,
+  present: Set<string>,
+  feedback: string
+): IChatMessage[] {
+  const moduleSpecifier = `./${opts.implFile.replace(/\.ts$/, "")}`;
+
+  const system = [
+    "You are a TypeScript test author. From acceptance criteria you write a rigorous, executable `bun:test` suite that pins behaviour with concrete, literal expected values.",
+    "Cover the happy path AND the edge cases the criteria imply (zero, negative, empty, boundary, rounding, large values). Every acceptance item maps to at least one assertion, and EVERY test must call the implementation under test.",
+    `You must produce TWO files via \`create\` calls (emit as many per turn as you can):\n  1. The test file — \`import { test, expect } from "bun:test";\` and import the implementation from "${moduleSpecifier}".\n  2. The implementation stub — export every function the tests import, with the correct signature but a body that does \`throw new Error("not implemented")\`.`,
+    "The stub makes the suite runnable and guarantees it starts RED: if any test passes against a stub that throws on every call, that test isn't really testing the implementation — don't write tests like that.",
+    "A `create` overwrites the file if it already exists, so to fix a file just create it again with the corrected full contents.",
+    "House rules: no `any`, no `as`, no non-null `!`; prefer `const`.",
+  ].join("\n");
+
+  const missing = [opts.testFile, opts.implFile].filter((f) => !present.has(f));
+  const state =
+    missing.length > 0
+      ? `Files still MISSING — create them now: ${missing.join(", ")}.`
+      : "Both files exist; fix whichever the runner rejected by re-creating it.";
+
+  const retry =
+    feedback.length > 0 ? `The current state was rejected: ${feedback}` : "";
+
+  const user = [
+    `Write the test suite at: ${opts.testFile}`,
+    `Write the implementation stub at: ${opts.implFile}`,
+    `Goal: ${opts.goal}`,
+    `Acceptance criteria:\n${opts.criteria}`,
+    state,
+    retry,
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+
+  return [
+    { role: "system", content: system },
+    { role: "user", content: user },
+  ];
+}