diff --git a/AGENTS.md b/AGENTS.md index 1ac2bdc..d06b66c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -95,14 +95,6 @@ This is non-optional and part of the boundary definition. --- -## Security guarantees - -> **Note**: For security scope definitions, see **README.md Security scope section**. - -For implementation-level security constraints, see the **Security rules (mandatory) section** above. - ---- - ## Key validation criteria To maintain a predictable boundary, keys must meet the following criteria. Failure to do so results in an `invalid_key` issue. @@ -214,23 +206,6 @@ If a feature conflicts with these, it must be rejected. --- -## v0.1.0 scope - -v0.1.0 establishes the FormData boundary with: - -- Flat FormData parsing into a plain JavaScript object -- Detection of forbidden, duplicate, and invalid keys -- Non-throwing issue reporting -- A minimal, stable public API - ---- - -## Versioning - -For versioning policy details, see **README.md Versioning section**. - ---- - ## Review rule of thumb If a change makes the parser: @@ -242,76 +217,3 @@ If a change makes the parser: it likely violates the boundary. When in doubt, reject the change. - ---- - -## Agent Skills - -This project provides the content of AGENTS.md in Agent Skills format through the `skills/` directory. - -### Purpose - -Agent Skills are structured knowledge packages optimized for Claude Code and similar AI-powered development tools. They enable: - -- **Automatic triggering**: Skills activate during PR creation, code review, etc. -- **Progressive disclosure**: Load only necessary information on demand -- **Standardized format**: Follows [agentskills.dev](https://agentskills.dev) specification - -### Available Skills - -#### boundary-validator (`skills/boundary-validator/`) - -Validates code changes against the Design rules and Security rules defined in this document. - -- **Purpose**: Automated detection of boundary principle violations -- **Triggers**: PR creation, code review, post-implementation checks -- **Coverage**: - - Keys are opaque strings (no bracket/dot notation parsing) - - No silent behavior (detect duplicate keys) - - No inference, no convenience (no type coercion, validation) - - Explicit issue reporting (no exceptions for input errors) - - Security rules (forbidden keys, prototype safety) - -**Supported tools**: Claude Code - -For details, see [`skills/boundary-validator/SKILL.md`](skills/boundary-validator/SKILL.md). - -### Using Skills in Other Tools - -Agent Skills are currently supported primarily by Claude Code. For other development tools: - -| Tool | Support | Usage | -| ----------------- | --------- | -------------------------------------------- | -| **Claude Code** | ✅ Full | Automatic detection of `skills/` directory | -| **Windsurf** | ⚠️ Manual | Reference this AGENTS.md directly in prompts | -| **Cursor** | ⚠️ Manual | Use `.cursorrules` or reference AGENTS.md | -| **claude.ai Web** | ⚠️ Manual | Upload SKILL.md as project knowledge | - -**For non-supported tools**: Use this AGENTS.md document directly, or configure your tool to reference the project's design principles explicitly in CLAUDE.md. - -### Relationship to AGENTS.md - -- **AGENTS.md is the source of truth**: All design principle changes are made here first -- **Skills are optimized versions**: The `skills/` directory provides the same rules in a format optimized for agent consumption -- **Synchronization**: When AGENTS.md is updated, corresponding files in `skills/boundary-validator/references/` should be updated - -This is a **strategic duplication**: - -- **AGENTS.md**: Human-readable, comprehensive, works with all tools -- **skills/**: Agent-optimized, progressive disclosure, auto-triggering (Claude Code) - -Both serve different audiences and purposes, making the duplication necessary for maximum compatibility. - -### Maintenance - -When updating design rules: - -1. **Edit AGENTS.md first** (this file is the master) -2. **Update corresponding references** in `skills/boundary-validator/references/` - - `design-rules.md` - Lines 36-75 of this file - - `security-rules.md` - Lines 76-95 of this file - - `api-contract.md` - Lines 119-199 of this file -3. **Increment skill version** in `skills/boundary-validator/SKILL.md` frontmatter -4. **Commit both** AGENTS.md and skills/ changes together - -For more information about the skills system, see [`skills/README.md`](skills/README.md). diff --git a/CLAUDE.md b/CLAUDE.md index 8bf2a2b..6650560 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,8 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -**safe-formdata** is a boundary-focused FormData parser that establishes a strict, security-oriented boundary between untrusted FormData input and application logic. - ## Critical: Follow AGENTS.md -**All implementation and review decisions must strictly adhere to AGENTS.md**, which defines the non-negotiable technical rules: - -- Implementation-level interpretation of README.md design principles -- Security implementation rules (prototype safety, forbidden keys) -- API contract and type definitions -- Non-goals (hard exclusions for any feature requests) -- Code review criteria ("Review rule of thumb") +**All implementation and review decisions must strictly adhere to AGENTS.md.** When implementing features or reviewing code: @@ -22,67 +10,19 @@ When implementing features or reviewing code: 2. Then, apply AGENTS.md technical constraints 3. If a change makes the parser smarter/more convenient, it likely violates the boundary → reject it -## Project Skills - -This project includes **Agent Skills** in the `skills/` directory, providing automated code review capabilities for Claude Code. - -### boundary-validator +## Agent Skills -The `boundary-validator` skill automatically validates code changes against AGENTS.md design rules: +The `boundary-validator` skill (`skills/boundary-validator/`) validates code changes against AGENTS.md design rules. -- **Location**: `skills/boundary-validator/` -- **Purpose**: Detect boundary principle violations during PR creation and code review - **Triggers**: Automatically activates when creating PRs or requesting code reviews -- **Coverage**: - - Keys are opaque strings (no bracket/dot notation parsing) - - No silent behavior (detect duplicate keys) - - No inference, no convenience (no type coercion, validation) - - Explicit issue reporting (no exceptions for input errors) - - Security rules (forbidden keys, prototype safety) +- **Coverage**: See AGENTS.md "Design rules" and "Security rules" sections **Usage in Claude Code**: -``` +```text Review this code against boundary-validator rules ``` -The skill will automatically check your implementation for violations and provide specific feedback with line references. - -### For Non-Claude Code Tools - -If you're using other development tools (Windsurf, Cursor, etc.): - -- **Reference AGENTS.md directly** in your prompts or tool configuration -- Agent Skills are primarily designed for Claude Code -- See `skills/README.md` for more details on cross-tool compatibility - -For complete information about the skills system, see [`skills/README.md`](skills/README.md) and [`AGENTS.md`](AGENTS.md#agent-skills). - -## API Documentation - -For complete API documentation, TypeScript interfaces, and usage examples, see **README.md**. - -**README.md follows a "philosophy-first" structure:** - -1. **Overview** - What this library is and is not -2. **Design principles** - Core philosophy (keys are opaque, no silent fixes, etc.) -3. **Security scope** - What's in scope vs out of scope -4. **Design decisions (Why not?)** - Why common features are intentionally omitted -5. **Installation** - Package manager setup -6. **Quick Start** - Minimal working example -7. **API** - Detailed API reference - -This structure ensures users understand the "boundary-focused" philosophy before writing code, reducing misuse. - -Key resources: - -- API interfaces (ParseResult discriminated union, ParseIssue) -- Issue codes (invalid_key, forbidden_key, duplicate_key) -- Security scope (in scope vs out of scope) -- Design decisions (Why no structural inference?, etc.) -- Type narrowing pattern (`data !== null`) -- Versioning policy - ## Usage Examples The `examples/` directory contains comprehensive usage examples: @@ -99,6 +39,20 @@ Run type checking for examples: bun run check:type:example ``` +## Toolchain + +| Tool | Role | +| ---------------------- | ------------------------------- | +| **bun** | Package manager / script runner | +| **TypeScript** (`tsc`) | Type checking | +| **tsup** | Build (bundler) | +| **vitest** | Test runner | +| **oxlint** | Linter | +| **Biome** | Formatter (TS/JS/JSON) | +| **Prettier** | Formatter (Markdown/YAML) | +| **publint** / **attw** | Package export validation | +| **npm-run-all2** | Script orchestration | + ## Development Commands ### Setup @@ -114,78 +68,64 @@ bun run dev # Watch mode for building bun run test:watch # Watch mode for testing ``` -### Testing +### Linting & Formatting ```bash -bun run test # Run all tests -bun run test:coverage # Run tests with coverage report +bun run lint # oxlint (deny-warnings) +bun run lint:fix # oxlint --fix-suggestions +bun run format # Biome + Prettier (write) +bun run fix # lint:fix + format (all-in-one auto-fix) ``` -### Build +### Quality Checks ```bash -bun run build # Build for production -bun run check:type:source # TypeScript type checking +bun run check # lint + format check (read-only) +bun run check:type # TypeScript check (source + examples) +bun run check:type:source # TypeScript check (source only) +bun run check:type:example # TypeScript check (examples only) +bun run check:package # publint + attw export validation ``` -## Type Safety and IDE Integration - -All type definitions include comprehensive JSDoc comments for enhanced IDE experience: - -### Type Narrowing Pattern +### Testing -The `ParseResult` type is a discriminated union. Use `data !== null` to narrow the type: +```bash +bun run test # Run all tests +bun run test:coverage # Run tests with coverage report +``` -```typescript -const result = parse(formData); +### Build -if (result.data !== null) { - // TypeScript knows: data is Record - // TypeScript knows: issues is [] - console.log(result.data.username); -} else { - // TypeScript knows: data is null - // TypeScript knows: issues is ParseIssue[] - console.error(result.issues); -} +```bash +bun run build # Build for production (tsup) ``` -### JSDoc Benefits - -When you hover over types in your IDE, you'll see: +### Publishing -- **ParseResult** - Discriminated union explanation and usage examples -- **ParseIssue** - Each property's purpose and security implications -- **IssueCode** - Security rationale for each issue code +```bash +bun run prepare:publish # Full pre-publish pipeline: type check → test:coverage → build → check:package +``` -Example JSDoc locations: +## CI/CD -- `src/types/ParseResult.ts` - Full discriminated union documentation -- `src/types/ParseIssue.ts` - Property-level explanations -- `src/types/IssueCode.ts` - Security-focused code definitions +- **Workflows**: `.github/workflows/` + - `ci.yml` - Main CI pipeline + - `publish.yml` - npm publish + - `prepare-release-pr.yml` - Release PR automation + - `wc-*.yml` - Reusable workflow components (type-check, lint-format, test, etc.) +- **PR template**: `.github/PULL_REQUEST_TEMPLATE.md` +- **Renovate**: `.github/renovate.json` -### Important: No `.ok` Property +## Important: No `.ok` Property -Unlike some libraries, `ParseResult` does not have a `.ok` property. Use `data !== null` instead: +`ParseResult` does not have a `.ok` property. Use `data !== null` to narrow the type: ```typescript -// ✅ Correct +// Correct if (result.data !== null) { } -// ❌ Wrong - .ok does not exist +// Wrong - .ok does not exist if (result.ok) { } ``` - ---- - -## Architecture Notes - -This project follows a minimal, security-focused architecture: - -- **TypeScript-based**: Strict type checking enabled -- **Minimal dependencies**: Zero runtime dependencies, minimal dev dependencies -- **Framework-agnostic**: Works with any JavaScript framework or runtime -- **Security-first**: Uses `Object.create(null)` to prevent prototype pollution -- **Discriminated unions**: Type-safe result handling without boolean flags diff --git a/skills/README.md b/skills/README.md index 902e138..13d35cd 100644 --- a/skills/README.md +++ b/skills/README.md @@ -26,30 +26,17 @@ Performs code review based on boundary principles. For details, see [`boundary-validator/SKILL.md`](./boundary-validator/SKILL.md). -## Supported Tools - -### ✅ Automatic Support - -- **Claude Code** - Automatically detects `skills/` in the project - -### ⚠️ Manual Reference Required - -- **Windsurf** - Instruct to reference AGENTS.md directly -- **Cursor** - Specify rules in AGENTS.md or `.cursorrules` -- **claude.ai Web** - Manually upload as project knowledge - -## Relationship to AGENTS.md - -- **AGENTS.md**: Master document for both humans and agents -- **skills/**: Optimized version for Agent Skills-compatible tools - -If you're using tools that don't support Agent Skills, please reference [AGENTS.md](../AGENTS.md) directly. - ## Maintenance Policy -1. **AGENTS.md is the source of truth**: Make design principle changes in AGENTS.md first -2. **Skills follow**: Reflect AGENTS.md changes in `skills/` -3. **Strategic duplication**: Document duplication is acceptable due to different purposes +When updating design rules: + +1. **Edit AGENTS.md first** (source of truth) +2. **Update corresponding references** in `boundary-validator/references/` + - `design-rules.md` — Design rules section + - `security-rules.md` — Security rules section + - `api-contract.md` — API contract section +3. **Increment skill version** in `boundary-validator/SKILL.md` frontmatter +4. **Commit both** AGENTS.md and `skills/` changes together ## Official Specification