The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Add BUGBOT.md files
Chirag Jainf7a0a181a87e
diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.mdnew file mode 100644index 000000000..aaca56cc1--- /dev/null+++ b/.cursor/BUGBOT.md@@ -0,0 +1,59 @@+# TrueForge review rules++Repo-wide checks. Package-specific rules live in `packages/trueforge-core/.cursor/BUGBOT.md` and `packages/trueforge/.cursor/BUGBOT.md`.++## Changeset (non-blocking)++If the diff changes code that ships in a published package and does not add a new `.changeset/*.md` file, add a **non-blocking** finding. Tell the author to run `pnpm changeset` and name only the packages that should bump:++- `packages/trueforge-core` → `@truefoundry/trueforge-core`+- `packages/trueforge` → `@truefoundry/trueforge`+- `packages/trueforge-ui` → `@truefoundry/trueforge-ui`+- `packages/trueforge-sdk` → `@truefoundry/trueforge-sdk` (SDK regen already adds this via `pnpm changeset:sdk-regen`)+- `packages/frontend` → `@truefoundry/trueforge` (UI is bundled into the server tarball)++Skip when:++- The PR already adds `.changeset/*.md`+- Changes are docs, `AGENTS.md`, CI/workflows, charts, docker-compose, or `packages/local-sandbox` only+- The PR is a Version Packages / `changeset-release/*` release PR++## CI and release wiring++If a workspace package is added, renamed, or moved, flag unless CI package path filters, matrix package ids, and root `test:*` scripts in `.github/workflows/ci.yml` and root `package.json` stay synchronized.++If the change touches release, pack, or publish wiring, flag if it would break dist-free host development, `pnpm smoke`, or packed CJS/ESM consumers of `@truefoundry/trueforge-core`.++If `docker-compose.yml` or `docker-compose.dev.yml` changes, flag when shared Postgres/Redis settings (image versions, health checks, `env_file`) drift. Intentional differences (app services, data paths, project `name`, host ports, in-network `POSTGRES_HOST` / `REDIS_URL`) must stay explicit. `docker-compose.yml` may read `packages/trueforge/.env` but must override container connectivity so host-dev localhost values are not used inside the smoke-test stack.++## Types, schemas, and ownership++If types or schemas change, flag when `packages/trueforge-core`, `packages/frontend`, `packages/trueforge`, or `patches` is updated without the other affected layers.++Flag TypeScript that uses `as T`, `as unknown as T`, non-null `!`, or `as never` to silence type errors. Implementations must use sound contracts, guards, or corrected types.++If a `catch` throws a new error, flag unless the new error sets `{ cause: caught }`.++Flag duplicate type, schema, helper, or contract definitions and forwarding shims that hide ownership. Each must have one canonical owner.++`AgentChatServer`, `AgentBuilderServer`, catalog ports, session/turn DTOs, and stream events must be defined only in `@truefoundry/assistant-ui-runtime` (`src/server/types.ts` / `events.ts`). Flag hand-written parallel definitions in `@truefoundry/trueforge-ui`. That package may only re-export them from `src/server/types.ts`. React wiring (`ServerContext`, `ShellModeContext`, `TrueForgeServerConfig`) may import those types; it must not redefine ports.++Flag runtime types backed by Zod schemas that are duplicated as hand-written interfaces or indirect utility-type chains. They must be named `z.infer<typeof Schema>` aliases.++## Modules, dead code, generated files++Flag `require()`, `require.resolve()`, or lint suppressions used to bypass import checks. Modules must use static `import` and `import type`.++If a change makes code unused, flag leftover exports, files, documentation, duplicates, or “just in case” shims. Dead code must be removed in the same change.++Flag manual edits to `.github/fern/openapi/openapi.json`, `docs/openapi.json`, or `packages/trueforge-sdk`. Those are autogenerated in CI. Both OpenAPI copies must stay identical.++## Tests and APIs++Flag tests inlined under `src`. Tests must live under a package-top-level `test` or `tests` directory that mirrors `src`.++Flag functions with more than one parameter of the same type passed positionally (e.g. `f(a: string, b: string)`). They must take a single options object.++Flag `z.union` when every member carries a shared literal discriminator field. Use `z.discriminatedUnion` in that case.++Flag HTTP/OpenAPI wire shapes (path params, query params, request/response JSON fields) and database identifiers (table/column names, persisted jsonb document keys) that are not `snake_case`.diff --git a/AGENTS.md b/AGENTS.mdindex 6e3be15a6..bda083a68 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,7 @@- Workspace tasks MUST use `package.json` scripts; add a script when a missing workflow is repeatable like the existing commands, not ad hoc commands.- CI package path filters, matrix package ids, and root scripts `test:*` in `.github/workflows/ci.yml` and root `package.json` MUST stay synchronized when a workspace package is added, renamed, or moved; the `store` filter sync rule lives in `packages/trueforge-core/src/agent-session/store/AGENTS.md`.- Release wiring MUST keep dist-free host development, `pnpm smoke`, and packed CJS/ESM consumers of `@truefoundry/trueforge-core` working without changes.+- PRs that change published-package code (`packages/trueforge-core`, `packages/trueforge`, `packages/trueforge-ui`, `packages/trueforge-sdk`) or `packages/frontend` (ships inside `@truefoundry/trueforge`) MUST include a new `.changeset/*.md` file (`pnpm changeset`). Docs, CI/workflows, charts, docker-compose, and `packages/local-sandbox`-only changes do not. SDK regeneration already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.- Shared Postgres/Redis settings in `docker-compose.yml` and `docker-compose.dev.yml` (image versions, health checks, `env_file`) MUST stay synchronized; intentional differences (app services, data paths, project `name`, host ports, in-network `POSTGRES_HOST` / `REDIS_URL`) MUST stay explicit. `packages/trueforge/.env` is the host-dev + secrets source; `docker-compose.yml` may read it but MUST override container connectivity so host-dev localhost values are not used inside the smoke-test stack.- Changes to types or schemas MUST keep `packages/trueforge-core`, `packages/frontend`, `packages/trueforge`, and `patches` synchronized; they MUST NOT update only one affected layer.- TypeScript code MUST NOT use assertion escapes such as `as T`, `as unknown as T`, non-null `!`, or `as never` to silence type errors; implementations MUST use sound contracts, guards, or corrected types.@@ -14,7 +15,7 @@- Every nested `AGENTS.md` MUST have a sibling `CLAUDE.md` containing only `@AGENTS.md`, so Cursor and Claude Code load the same scoped rules.- OpenAPI specs under `.github/fern/openapi/openapi.json` and `docs/openapi.json` are autogenerated in CI and MUST NOT be edited manually (both copies MUST stay identical)- Code under `packages/trueforge-sdk` is autogenerated in CI and MUST NOT be edited manually-- Tests MUST live under a top-level `test` directory that mirrors the `src` layout; they MUST NOT be inlined under `src`.+- Tests MUST live under a package-top-level `test` or `tests` directory that mirrors the `src` layout; they MUST NOT be inlined under `src`.- Functions with more than one parameter of the same type MUST take a single options object (e.g. `f({ a, b }: { a: string; b: string })`); they MUST NOT use multiple positional parameters of that repeated type (e.g. `f(a: string, b: string)`).- Zod unions MUST use `z.discriminatedUnion` whenever every member carries a shared literal discriminator field; `z.union` is only permitted when no such common discriminator exists.- HTTP/OpenAPI wire shapes (path params, query params, request/response JSON fields) and database identifiers (table/column names, persisted jsonb document keys) MUST use `snake_case`.diff --git a/README.md b/README.mdindex 6e3c2ad84..8f955b9a0 100644--- a/README.md+++ b/README.md@@ -39,6 +39,9 @@<a href="https://www.npmjs.com/package/@truefoundry/trueforge-core"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core" alt="npm @truefoundry/trueforge-core"></a>+ <a href="https://deepwiki.com/truefoundry/trueforge">+ <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">+ </a></p># TrueForgediff --git a/packages/trueforge-core/.cursor/BUGBOT.md b/packages/trueforge-core/.cursor/BUGBOT.mdnew file mode 100644index 000000000..c836a8c9d--- /dev/null+++ b/packages/trueforge-core/.cursor/BUGBOT.md@@ -0,0 +1,32 @@+# @truefoundry/trueforge-core review rules++Included when reviewing files under `packages/trueforge-core`. Repo-wide rules are in the root `.cursor/BUGBOT.md`.++## Package exports and dist++Flag a `"trueforge-dev"` export condition renamed to `"development"` or `"production"`. Workspace source must stay ESM so that condition can load `src/` without a build. The package publishes from its own root with `files: ["dist", "README.md"]`, so `src/` is never in the tarball; Vite/webpack auto-activate a literal `"development"` condition in dev mode with no consumer opt-in.++Flag `dist/` output that does not expose CJS `.js` and ESM `.mjs` alongside `.d.ts`.++## Optional properties++Top-level public package surfaces (`core`, `agent-session`, and other exported entrypoints) MAY use optional (`?`) properties.++Flag `?` on internal records, snapshots, store INPUT types, and other internal contracts. Absence must be an explicit required `| null` or `| undefined` field. Prefer `null` for domain absence; use `undefined` only when update/patch semantics must distinguish “not provided” from “clear.” Public surfaces must supply those explicit absences when calling inward.++## Session store++`ISessionStore` is the session/turn persistence contract (no streaming/SSE). Postgres, SQLite, and `InMemorySessionStore` must implement it. Shared behavior must live in `storeContractSuite.ts`; backend wrappers only bind a store.++If an `ISessionStore` method, input, error, or semantic changes, flag unless the interface, every implementation, and the contract suite are updated in the same change.++If store or contract-test paths are added, moved, or renamed, flag unless the `store` path filter in `.github/workflows/ci.yml` stays synchronized.++## Durable runtime state++Flag in-memory mutation that runs before the corresponding event is yielded. Durable state must follow:++```ts+yield event; // consumer persists and may throw+mutateMemory(); // runs only after persistence succeeds+```diff --git a/packages/trueforge/.cursor/BUGBOT.md b/packages/trueforge/.cursor/BUGBOT.mdnew file mode 100644index 000000000..9baea9a94--- /dev/null+++ b/packages/trueforge/.cursor/BUGBOT.md@@ -0,0 +1,85 @@+# @truefoundry/trueforge review rules++Included when reviewing files under `packages/trueforge`. Repo-wide rules are in the root `.cursor/BUGBOT.md`. Do not re-flag generated OpenAPI/SDK edits; that check lives in the root file.++## Environment variables++Flag `process.env` reads in `packages/trueforge/src/**` other than `config.ts` and documented bootstrap in `cli.ts` (flags applied before `./main` import because config reads env at module load).++Do not flag tests. Do not flag `logger.ts` `NO_COLOR` / `FORCE_COLOR` reads unless that file grows unrelated env reads.++## Transactions++Flag `withTransaction` callbacks that `await` `fetch`, an SDK client, Redis, or other remote I/O (including through helpers). Finish remote work before opening the txn. Callbacks must only do local DB work.++`withTransaction` is `db.transaction().execute(callback)`: commits on resolve, rolls back on throw. Return domain data from the callback; build success `c.json(...)` after it. Flag `return c.json({ error: ... }, status)` inside the callback — a returned Response commits while the client still sees an error. Failures that must undo writes must `throw` (e.g. `HTTPException`).++## OpenAPI naming++Wire fields stay `snake_case` (also covered at repo root). New endpoints must follow this convention; renaming shipped schemas breaks `packages/trueforge-sdk`.++**Paths:** plural kebab under `/api/v1/{collection}`, nested `/…/{id}/{subcollection}`, settings `/api/v1/settings/{collection}`, catalog `/api/v1/catalog/{collection}`. Ids as `{resource}_id`; name-keyed ops use `{name}` — do not mix id and name across verbs for one resource.++If a settings resource is one-per-tenant (e.g. sandbox provider), keep the plural path `/api/v1/settings/sandbox-providers` for URL consistency, but Fern methods are `get`/`upsert` returning a single object — not `list` returning an array.++**Verbs:** `GET` list/get → 200; `POST` create → **201**; `PUT` replace/upsert → 200; `DELETE` → **200** with `DeleteFooResponse` (`{}`), optional `DeleteFoosRequestQuery`; actions `POST /{id}/{action}`.++**Schemas** (resource `Foo`, collection `foos`; item OpenAPI name is PascalCase singular):++| Operation | Request | Response |+| ----------------------- | ----------------------------------- | ----------------------------------------- |+| `GET /foos` | `ListFoosRequestQuery` (if any) | `ListFoosResponse` |+| `POST /foos` | `CreateFooRequest` | `GetFooResponse` (or `CreateFooResponse`) |+| `GET /foos/{foo_id}` | — | `GetFooResponse` |+| `PUT` upsert/replace | `PutFooRequest` | `GetFooResponse` (or `PutFooResponse`) |+| `DELETE /foos/{foo_id}` | `DeleteFoosRequestQuery` (optional) | `DeleteFooResponse` (`{}`) |++Prefer reusing `GetFooResponse` when create/update return the same item.++**Request body vs manifest:** `FooManifest` is only the persisted jsonb document. Flag create/put bodies that flatten manifest fields onto the request root or alias the request schema to `FooManifest`. They must be `CreateFooRequest` / `PutFooRequest` with an explicit wrapper:++```ts+{+ manifest: FooManifest; // stored document only+ dry_run?: boolean; // operation-level fields live beside manifest+}+```++Session/turn-style creates that are not a stored manifest keep a flat `Create*Request` without a `manifest` key.++Settings list → `ListFoosResponse`; chat → `ListAvailableFoosResponse`; catalog → `ListCatalogFoosResponse` / item `CatalogFoo`.++Nested child `Bar`: `ListBarsResponse`, `CreateBarRequest`, `GetBarResponse`; Fern `list_bars`, `create_bar`, …++**Envelopes:** success `{ data: Item | Item[] }` (+ `pagination` via `fernExtensions.ts` token contract); errors `RequestErrorResponse`.++**Fern:** set `x-fern-sdk-group-name` / `x-fern-sdk-method-name` (`list`/`get`/`create`/`update`/`upsert`/`delete` + snake_case actions). Schemas live in `src/schemas/` with matching `.openapi('…')` names; types via `z.infer`.++**No inline object schemas:** flag anonymous `z.object({ … })` nested inside another object. Extract each nested object as a top-level named schema with a meaningful `.openapi('…')` name (e.g. `FooAuth`, `FooManifest`). Primitives, arrays of primitives, and `$ref`s to existing named schemas are fine inline.++**Avoid `allOf`:** new wire schemas must emit flat OpenAPI objects.++- Flag `z.merge` — prefer `z.object({ ...A.shape, ...B.shape })` or leave bases unnamed and `.extend` only then.+- Flag `.extend()` on a schema that already has `.openapi('Name')` — use `z.object({ ...Base.shape, … })` or leave the base unnamed.+- Flag `.describe()` on a named `$ref` field (`NameSchema.describe(…)`) — describe the shared schema once, or inline constraints.+- Discriminated `oneOf` for real polymorphism is fine; flag a one-member `oneOf`. Single-variant unions must be a plain object alias.++## Postgres++Flag temporal columns that are `timestamp` without time zone. Use `timestamptz`.++Flag application timestamps that are not treated as UTC instants. Serialize with `Date.prototype.toISOString()` (always `...Z` with milliseconds).++Flag DB queries inside loops (N+1). Prefer a single batched query, a join, or an `IN`/`ANY` lookup.++Flag Postgres migrations whose `up`/`down` do not start with `SET LOCAL lock_timeout = '5s'`.++## SQLite++Flag JSON projection aliases missing from `client.ts` `JSON_RESULT_COLUMNS`.++Kysely's SqliteAdapter keeps `supportsTransactionalDdl: false`, so Migrator does not wrap migrations. Flag every schema-touching `up`/`down` that does not open `db.transaction()` itself. `PRAGMA foreign_keys` is a no-op inside a transaction — toggle it outside the txn when rebuilding a referenced parent.++## Persisted JSON schemas++If a Zod schema that backs persisted JSON (e.g. `model_provider.manifest`) changes in a breaking way, flag unless the change includes a data migration or rewrite for existing rows.