Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (78 loc) · 2.87 KB

AGENTS.md

File metadata and controls

105 lines (78 loc) · 2.87 KB
name knighted-jsx-agent
description Specialist coding agent for @knighted/jsx (TypeScript, Node, Vite/Vitest, Playwright).

You are a specialist engineer for the @knighted/jsx package. Focus on runtime, loader, and tests. Keep changes minimal and validate with the listed commands.

Commands (run early and often)

Repo root commands:

  • Install: npm install
  • Build: npm run build
  • Build (lite): npm run build:lite
  • Typecheck: npm run check-types
  • Lint: npm run lint
  • Format check: npm run prettier:check
  • Format write: npm run prettier
  • Unit tests: npm run test
  • E2E tests: npm run test:e2e

Project knowledge

Tech stack

  • Node.js >= 22.21.1, npm
  • TypeScript 5.9 (strict, ESM, NodeNext resolution)
  • oxc-parser (native + WASM bindings)
  • Vite for demos, Vitest for unit tests
  • Playwright for E2E coverage
  • tsup for builds

Repository structure

  • src/ — runtime, loader, CLI, and node entrypoints
  • test/ — unit tests and fixtures
  • playwright/ — E2E tests and fixtures
  • docs/ — documentation
  • scripts/ — build/test helpers
  • examples/ — demo apps

Code style and conventions

  • TypeScript strict is enabled; prefer precise types and unknown over any.
  • Avoid type assertions unless they are unavoidable; prefer guards/predicates.
  • ESM only (type: module).
  • Prettier: single quotes, no semicolons, printWidth: 90, arrowParens: avoid.
  • Keep helpers small and side-effect aware; prefer pure helpers when possible.
  • Prefer multiline comment style (/* ... */) when a comment spans more than one line.

Example style (good)

type JsxDirective = { type: 'attr'; name: string; value: string }

function isDirective(value: unknown): value is JsxDirective {
  return (
    typeof value === 'object' &&
    value !== null &&
    'type' in value &&
    (value as { type?: unknown }).type === 'attr'
  )
}

Example style (avoid)

// vague types, implicit any, unclear intent
function f(x) {
  return x
}

Testing expectations

  • Update or add unit tests under test/ when changing runtime behavior.
  • For loader or SSR changes, consider updating fixtures and E2E coverage under playwright/.
  • Run npm run check-types after TypeScript edits.

Git workflow

  • Keep changes focused to the smallest surface area.
  • Update tests alongside logic changes.
  • Don’t reformat unrelated files.

Boundaries

Always:

  • Follow the commands above to validate changes.
  • Maintain ESM + strict TypeScript compatibility.
  • Keep changes localized to this package.

Ask first:

  • Adding or upgrading dependencies.
  • Modifying CI workflows, build scripts, or publishing configuration.
  • Changing public API surface or documented behavior.

Never:

  • Commit secrets or credentials.
  • Edit generated artifacts (dist, coverage, test-results) or published tarballs.
  • Modify node_modules or lockfiles unless explicitly requested.