diff --git a/.claude/skills/development-workflow/SKILL.md b/.claude/skills/development-workflow/SKILL.md index 85deb9dd..30c4eaf7 100644 --- a/.claude/skills/development-workflow/SKILL.md +++ b/.claude/skills/development-workflow/SKILL.md @@ -9,30 +9,30 @@ This skill provides all commands and best practices for building, developing, an ## Building and Development -- `bun run build` - Build the project using tsdown -- `bun run rebuild` - Fetch latest OpenAPI specs and rebuild everything -- `bun run dev` - Watch mode for development (builds on file changes) -- `bun run fetch:specs` - Update OpenAPI specifications from remote +- `pnpm build` - Build the project using tsdown +- `pnpm rebuild` - Fetch latest OpenAPI specs and rebuild everything +- `pnpm dev` - Watch mode for development (builds on file changes) +- `pnpm fetch:specs` - Update OpenAPI specifications from remote ## Testing -- `bun run test` - Run all tests (unit, examples, scripts) -- `bun run test:unit` - Run only unit tests -- `bun test src/path/to/file.spec.ts` - Run a specific test file -- `bun test -t "test name"` - Run tests matching a pattern +- `pnpm test` - Run all tests (unit, examples, scripts) +- `pnpm test:unit` - Run only unit tests +- `pnpm vitest src/path/to/file.spec.ts` - Run a specific test file +- `pnpm vitest -t "test name"` - Run tests matching a pattern ## Code Quality -- `bun run lint` - Run Biome linter -- `bun run format` - Format code with Biome -- `bun run typecheck` - Type check with tsgo -- `bun run lint:fix` - Auto-fix linting issues +- `pnpm lint` - Run Biome linter +- `pnpm format` - Format code with Biome +- `pnpm typecheck` - Type check with tsgo +- `pnpm lint:fix` - Auto-fix linting issues ## Documentation -- `bun run docs:build` - Build MkDocs documentation -- `bun run docs:serve` - Serve docs locally -- `bun run docs:deploy` - Deploy docs to GitHub Pages +- `pnpm docs:build` - Build MkDocs documentation +- `pnpm docs:serve` - Serve docs locally +- `pnpm docs:deploy` - Deploy docs to GitHub Pages ## Development Guidelines @@ -51,7 +51,7 @@ Keep commits tiny but meaningful: ### When to Rebuild -Always run `bun run rebuild` when: +Always run `pnpm rebuild` when: - Updating OpenAPI specifications - After pulling spec changes - Before committing generated files @@ -60,18 +60,18 @@ Always run `bun run rebuild` when: 1. Create feature branch: `git checkout -b feature-name` 2. Make changes to source files -3. Run type checking: `bun run typecheck` -4. Run linter: `bun run lint:fix` -5. Run tests: `bun run test` -6. Format code: `bun run format` -7. Rebuild if specs changed: `bun run rebuild` +3. Run type checking: `pnpm typecheck` +4. Run linter: `pnpm lint:fix` +5. Run tests: `pnpm test` +6. Format code: `pnpm format` +7. Rebuild if specs changed: `pnpm rebuild` 8. Commit with detailed messages 9. Push and create PR: `gh pr create` ## Troubleshooting ### Command Failures -If `bunx ` fails, try `bun x ` instead. +If `pnpm exec ` fails, try `pnpm dlx ` instead. If bash commands fail, try running with fish shell: ```bash @@ -133,10 +133,10 @@ Use the TypeScript exhaustiveness pattern (`satisfies never`) when branching on ## Publishing & Deployment When ready to release: -1. Ensure all tests pass: `bun run test` -2. Verify type checking: `bun run typecheck` -3. Build documentation: `bun run docs:build` +1. Ensure all tests pass: `pnpm test` +2. Verify type checking: `pnpm typecheck` +3. Build documentation: `pnpm docs:build` 4. Bump version in package.json 5. Create release commit 6. Push to main or create release PR -7. Deploy docs: `bun run docs:deploy` +7. Deploy docs: `pnpm docs:deploy` diff --git a/.claude/skills/openapi-architecture/SKILL.md b/.claude/skills/openapi-architecture/SKILL.md deleted file mode 100644 index 55230c8b..00000000 --- a/.claude/skills/openapi-architecture/SKILL.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: openapi-architecture -description: OpenAPI specification processing and StackOne SDK architecture ---- - -# OpenAPI Architecture & StackOne SDK - -This skill explains the core architecture and design patterns used in the StackOne AI Node SDK for transforming OpenAPI specifications into AI-friendly tools. - -## Project Overview - -The **StackOne AI Node SDK** is a TypeScript library that transforms OpenAPI specifications into AI-friendly tools for use with LLM frameworks like OpenAI and Vercel AI SDK. - -## Core Components - -### 1. Tool Class (`src/tool.ts`) -The fundamental building block that wraps API operations into AI agent-consumable format. Each tool represents a single API endpoint with: -- Schema validation -- Execution logic -- Input/output handling - -### 2. ToolSets (`src/toolsets/`) -Collections of tools working together: -- **OpenAPIToolSet**: Generic toolset for any OpenAPI spec -- **StackOneToolSet**: Pre-configured for StackOne unified APIs (ATS, CRM, HRIS, etc.) - -### 3. OpenAPI Processing (`src/openapi/`) -- **loader.ts**: Fetches and loads OpenAPI specifications -- **parser.ts**: Transforms OpenAPI operations into Tool instances -- **generated/**: Auto-generated TypeScript definitions from specs - -### 4. Request Builder (`src/modules/requestBuilder.ts`) -Transforms tool inputs into properly formatted HTTP requests: -- Handles file uploads -- Manages authentication -- Supports multiple body types (JSON, form, multipart-form) - -## Key Design Patterns - -### Schema-First -Everything is driven by JSON Schema definitions from OpenAPI specs. This ensures consistency and type safety. - -### Type Safety -Comprehensive TypeScript types are generated from OpenAPI specs, providing compile-time safety. - -### Framework Agnostic -Core logic is independent of AI frameworks. Use adapters for OpenAI and Vercel AI. - -### Lazy Loading -Tools are created on-demand to minimize memory usage. - -### Extensibility -Hooks for parameter transformation and pre-execution logic allow customization. - -## TypeScript Exhaustiveness Checks - -Use the `satisfies never` pattern for compile-time exhaustiveness checking: - -```typescript -switch (bodyType) { - case 'json': - // ... - break; - case 'form': - // ... - break; - case 'multipart-form': - // ... - break; - default: { - bodyType satisfies never; // Error if new variant added - throw new Error(`Unsupported HTTP body type: ${String(bodyType)}`); - } -} -``` - -This keeps union definitions and switch statements in sync. Adding a new union member will trigger a compile-time error. - -## HTTP Body Types - -The request builder supports three body types via `HttpBodyType`: -- **json**: Serialized JSON body with appropriate headers -- **form**: URL-encoded form data -- **multipart-form**: Multipart form data (for file uploads) - -Each type is handled with proper header configuration and serialization. - -## Development Workflow - -1. OpenAPI specs are fetched from remote sources and stored in `specs/` -2. TypeScript types are auto-generated from specs into `src/openapi/generated/` -3. The parser transforms OpenAPI operations into Tool instances at runtime -4. Tools are used directly or via framework-specific adapters - -## Important Notes - -- All generated files should be committed (not gitignored) -- Follow existing patterns for error handling and logging -- Run `bun run rebuild` after updating OpenAPI specs -- The parser handles complex OpenAPI features like authentication, parameters, and responses - -## Guidelines - -- Maintain backward compatibility when updating OpenAPI specs -- Document any custom parameter transformations -- Use generated types throughout the codebase -- Test all changes thoroughly with MSW mocks diff --git a/.claude/skills/typescript-testing/SKILL.md b/.claude/skills/typescript-testing/SKILL.md index c13e1dd1..d2cec3d3 100644 --- a/.claude/skills/typescript-testing/SKILL.md +++ b/.claude/skills/typescript-testing/SKILL.md @@ -1,23 +1,23 @@ --- name: typescript-testing -description: Bun test runner and MSW-based testing patterns for StackOne SDK +description: Vitest test runner and MSW-based testing patterns for StackOne SDK --- -# TypeScript Testing with Bun and MSW +# TypeScript Testing with Vitest and MSW -This skill guides testing practices for the StackOne SDK using Bun's test runner and Mock Service Worker (MSW) for HTTP mocking. +This skill guides testing practices for the StackOne SDK using Vitest test runner and Mock Service Worker (MSW) for HTTP mocking. ## Testing Framework -The project uses **Bun's built-in test runner** with Jest-compatible API. Run tests with: -- `bun run test` - Run all tests (unit, examples, scripts) -- `bun run test:unit` - Run only unit tests -- `bun test src/path/to/file.spec.ts` - Run a specific test file -- `bun test -t "test name"` - Run tests matching a pattern +The project uses **Vitest** as the test runner. Run tests with: +- `pnpm test` - Run all tests (unit, examples, scripts) +- `pnpm test:unit` - Run only unit tests +- `pnpm vitest src/path/to/file.spec.ts` - Run a specific test file +- `pnpm vitest -t "test name"` - Run tests matching a pattern ## MSW (Mock Service Worker) -**MSW is the preferred HTTP mocking solution.** MSW is configured globally in `bun.test.setup.ts`, so no per-file setup is required. +**MSW is the preferred HTTP mocking solution.** MSW is configured globally in `vitest.setup.ts`, so no per-file setup is required. ### Adding Mock Handlers @@ -89,23 +89,12 @@ import { createFixture } from 'fs-fixture'; it('should save file to disk', async () => { await using fixture = await createFixture(); - await fixture.writeFile('data.json', JSON.stringify({ test: 'data' })); expect(await fixture.exists('data.json')).toBe(true); - - const content = await fixture.readFile('data.json', 'utf8'); - expect(JSON.parse(content)).toEqual({ test: 'data' }); }); ``` -Available methods: -- `fixture.path` - Absolute fixture directory path -- `fixture.exists(path)` - Check existence -- `fixture.readFile(path, encoding?)` - Read as string or Buffer -- `fixture.writeFile(path, content)` - Write file -- `fixture.readJson(path)` - Parse JSON with type safety -- `fixture.writeJson(path, data, space?)` - Write formatted JSON -- `fixture.mkdir(path)` - Create nested directories +**Reference:** See `node_modules/fs-fixture/README.md` for full API and advanced usage ## Test Organization diff --git a/.cursor/rules/biome-standards.mdc b/.cursor/rules/biome-standards.mdc deleted file mode 100644 index e9665853..00000000 --- a/.cursor/rules/biome-standards.mdc +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: Standards for using Biome for linting and formatting in the repository -globs: *.{ts,js,tsx,jsx}" -alwaysApply: false ---- ---- -description: Standards for using Biome for linting and formatting in the repository -globs: "*.{ts,js,tsx,jsx}" ---- -# Biome Standards - -Standards for using Biome for linting and formatting in the StackOne repository. - - -name: biome_standards -description: Standards for using Biome for linting and formatting -filters: - # Match TypeScript and JavaScript files - - type: file_extension - pattern: "\\.(ts|js|tsx|jsx)$" - -actions: - - type: suggest - message: | - ## Biome Linting and Formatting Standards - - ### Running Biome Commands - - 1. **Linting**: Check code for issues without applying fixes - ```bash - bun run lint - # or - biome check . - ``` - - 2. **Formatting**: Format code without checking for issues - ```bash - bun run format - # or - biome format --write . - ``` - - 3. **Check and Fix**: Check code and apply automatic fixes - ```bash - bun run check - # or - biome check --apply . - ``` - - ### Pre-commit Hooks - - - Biome is configured with Husky to run automatically on staged files before commits - - To bypass in exceptional cases: `git commit --no-verify` - - ### Configuration - - - Configuration is in `biome.json` at the project root - - Do not modify this file without team discussion - - Key settings: - - Indent: 2 spaces - - Line width: 100 characters - - Quote style: Single quotes - - Trailing commas: ES5 style - - Semicolons: Always required - - ### Best Practices - - 1. Run Biome before submitting PRs - 2. Fix all errors (warnings can be addressed later) - 3. Don't disable rules without team discussion - 4. Use TypeScript with proper types to avoid many linting issues - 5. For arrow functions, always include return types - 6. Use Bun for all package management and script running - -examples: - - input: | - // Bad: Missing semicolon, double quotes, no return type - const add = (a: number, b: number) => a + b - console.log("Result:", add(1, 2)) - - // Good: With semicolon, single quotes, return type - const add = (a: number, b: number): number => a + b; - console.log('Result:', add(1, 2)); - output: "Code formatted according to Biome standards" - -metadata: - priority: high - version: 1.0 - \ No newline at end of file diff --git a/.cursor/rules/bun-standards.mdc b/.cursor/rules/bun-standards.mdc deleted file mode 100644 index 582ae8f4..00000000 --- a/.cursor/rules/bun-standards.mdc +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: Standards for using Bun in this repository -globs: -alwaysApply: false ---- - -# Bun Standards - -## Overview - -This repository uses [Bun](mdc:https:/bun.sh) as the JavaScript runtime and package manager. Bun is a fast all-in-one JavaScript runtime that can replace Node.js, npm, yarn, and webpack. - -## Package Management - -- Use `bun install` instead of `npm install` to add dependencies -- Use `bun.lockb` for lockfiles (automatically generated) -- When adding new dependencies, specify exact versions: `bun add package@x.y.z` - -## TypeScript Configuration - -- Bun has built-in TypeScript support, no need for separate transpilation -- When working with TypeScript files, be aware that Bun's type definitions may conflict with Node.js types -- Use `/// ` at the top of files that use Bun-specific APIs - -## Running Scripts - -- Use `bun run` to execute scripts defined in package.json -- For direct execution of TypeScript files, use `bun file.ts` instead of `ts-node file.ts` - -## Testing - -- Use Bun's built-in test runner with `bun test` -- Test files should follow the pattern `*.test.ts` or `*.spec.ts` - -## Environment Variables - -- Bun automatically loads `.env` files -- Access environment variables via `Bun.env` or `process.env` - -## Type Compatibility - -- When encountering type conflicts between Bun and other libraries: - - Use type assertions carefully - - Consider using `as any` only when necessary - - Prefer creating proper type interfaces when possible - -## Deployment - -- For production deployments, use `bun build` to create optimized bundles diff --git a/.cursor/rules/pnpm-standards.mdc b/.cursor/rules/pnpm-standards.mdc new file mode 100644 index 00000000..62592e51 --- /dev/null +++ b/.cursor/rules/pnpm-standards.mdc @@ -0,0 +1,48 @@ +--- +description: Standards for using pnpm in this repository +globs: +alwaysApply: false +--- + +# pnpm Standards + +## Overview + +This repository uses [pnpm](https://pnpm.io) as the package manager. pnpm is a fast, disk space efficient package manager. + +## Package Management + +- Use `pnpm install` instead of `npm install` to add dependencies +- Use `pnpm-lock.yaml` for lockfiles (automatically generated) +- When adding new dependencies, use: `pnpm add package@x.y.z` + +## TypeScript Configuration + +- TypeScript is configured via `tsconfig.json` +- Use `pnpm typecheck` to run type checking with tsgo + +## Running Scripts + +- Use `pnpm