Skip to content
askdareDocumentation

    ADR-0007: Tooling

    • Status: Accepted. Spike S2 (packaging) was answered by the build itself: 0.1 has no client entries, publint and attw run in pnpm check, and the tarball check builds a fresh app with Turbopack and webpack before each release candidate.
    • Date: 2026-10-29

    Decision

    AreaChoiceNotes
    Workspacepnpm 12 workspacesNo Turborepo or Nx: 2–3 workspaces don't need an orchestrator
    Library buildtsdown0.1 has no client entries: the widget is a prebuilt iframe app. The React subpath in 0.2 will start each client entry with 'use client', checked in CI. tsup is unmaintained.
    iframe app and loaderVite 8Library mode. The output is inlined into the package as string modules.
    TypeScriptTypecheck with TS 7 (tsgo); isolatedDeclarationsTS 6.0 only where a tool needs the compiler's JavaScript API
    Lint and formatBiome 2.6Import restrictions enforce module boundaries; for example, only src/openai/ may import openai.
    Unit and integration testsVitest 5 + MSW 3Recorded Responses API SSE fixtures are replayed with http.post handlers
    End-to-end testsPlaywright 1.64Two origins (app and host page), axe checks, visual regression on the state gallery
    Package qualitypublint, @arethetypeswrong/cli, size budgets in the asset build, .d.ts snapshot, no-leak testLoader under 5 KB gzipped
    ReleaseChangesets 3, npm trusted publishing (OIDC) with provenanceNo npm token stored anywhere
    CI and maintenanceGitHub Actions, Renovate (openai updates batched weekly), CodeQL, TruffleHogNightly canary and daily live smoke (ADR-0006)

    AI-assisted development

    • .mcp.json holds read-only servers only:
      • the OpenAI Docs MCP (https://developers.openai.com/mcp);
      • next-devtools-mcp, pinned to a version.
    • Skills are vetted before use and pinned, kept in .claude/skills/ with their sources, commits and reviews in .claude/skills/sources.json.
    • Project skills: typescript-conventions, openai-api, release, adr.
    • CLAUDE.md at the root. site/CLAUDE.md and examples/starter/CLAUDE.md import the AGENTS.md next to them (generated by next dev; in the starter, also written by init).
    • Servers with account write access (Vercel, Heroku, Upstash) are configured in local or user scope only, never in the repo.

    Alternatives considered

    • Turborepo or Nx. Overkill at this size.
    • ESLint 10 with flat config. Fine, but Biome covers lint and format in one fast tool.
    • API Extractor. Deferred; the .d.ts snapshot plus the no-leak test cover the risk for now.