diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000000..c1dfb633ff16 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,60 @@ +# Fluid Framework + +Distributed real-time collaborative web application framework using JavaScript/TypeScript. + +## Build System + +- Uses **pnpm** as package manager (required) +- Enable corepack: `corepack enable` +- Install dependencies: `pnpm install` +- Build all: `pnpm build` +- Build specific package: `pnpm build --filter @fluidframework/` + +## Commands + +- `pnpm build` - Build all packages +- `pnpm test` - Run tests across all packages +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm clean` - Clean build artifacts + +## Workspace Structure + +This is a pnpm monorepo with multiple release groups: + +- **packages/**: Core Fluid Framework packages (`@fluidframework/*`) + - `common/` - Shared interfaces and utilities + - `dds/` - Distributed Data Structures + - `drivers/` - Service drivers + - `framework/` - Framework components + - `loader/` - Container loading + - `runtime/` - Runtime components + - `service-clients/` - Service client implementations + - `test/` - Test utilities + - `tools/` - Developer tools + - `utils/` - Shared utilities +- **experimental/**: Experimental packages (`@fluid-experimental/*`) +- **examples/**: Example applications (`@fluid-example/*`, not published) +- **azure/packages/**: Azure-specific packages +- **tools/**: Build and development tools + +## Code Style + +- TypeScript with strict mode +- ESLint for linting +- Biome for formatting +- API Extractor for API documentation and release tags + +## Testing + +- Uses Mocha for most packages +- Use `pnpm test` in package directory +- Coverage via c8: `pnpm test:coverage` + +## Key Conventions + +- Package exports use release tags: `/public`, `/beta`, `/alpha`, `/legacy`, `/internal` +- Dual ESM/CJS builds (lib/ for ESM, dist/ for CJS) +- Use `workspace:~` for internal dependencies +- Follow conventional commits for commit messages diff --git a/azure/packages/azure-local-service/CLAUDE.md b/azure/packages/azure-local-service/CLAUDE.md new file mode 100644 index 000000000000..d72b5779ca28 --- /dev/null +++ b/azure/packages/azure-local-service/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluidframework/azure-local-service + +Local implementation of the Azure Fluid Relay service for testing/development use. This is a thin wrapper around `tinylicious`. + +## Build + +This package has no build step - it's a simple JavaScript entry point. + +- `pnpm clean` - Remove generated files + +## Run + +- `pnpm start` - Start the local service using pm2 +- `pnpm start:debug` - Start with Node.js inspector enabled (port 9229) +- `pnpm stop` - Stop the pm2-managed service + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:format` - Check formatting with Biome + +## Key Files + +- `index.js` - Entry point that imports and runs tinylicious + +## Notes + +- This package wraps `tinylicious` to provide a local Azure Fluid Relay-compatible service +- Uses pm2 for process management in production mode +- No tests are defined for this package +- Type validation is disabled diff --git a/azure/packages/azure-service-utils/CLAUDE.md b/azure/packages/azure-service-utils/CLAUDE.md new file mode 100644 index 000000000000..060a921aa326 --- /dev/null +++ b/azure/packages/azure-service-utils/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluidframework/azure-service-utils + +Helper service-side utilities for connecting to Azure Fluid Relay service. Provides token generation utilities for backend APIs. + +## Build + +- `pnpm build` - Full build (compile + API reports) +- `pnpm build:compile` - Compile TypeScript only +- `pnpm build:esnext` - Build ESM output to `lib/` +- `pnpm tsc` - Build CommonJS output to `dist/` +- `pnpm clean` - Remove generated files + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:format` - Check formatting with Biome + +## API Reports + +- `pnpm build:api-reports` - Generate API reports +- `pnpm api` - Run API extractor + +## Key Files + +- `src/index.ts` - Main entry point, exports `generateToken` and types +- `src/generateToken.ts` - Token generation logic using jsrsasign +- Dual CJS/ESM output with multiple export paths (public, legacy, internal) + +## Notes + +- Primary export is `generateToken` for creating Azure Fluid Relay tokens +- Uses `jsrsasign` for JWT token generation +- Exports are tiered: public (default), legacy, and internal +- No tests are currently defined +- Type validation uses the "legacy" entrypoint diff --git a/common/build/eslint-config-fluid/CLAUDE.md b/common/build/eslint-config-fluid/CLAUDE.md new file mode 100644 index 000000000000..add794939c68 --- /dev/null +++ b/common/build/eslint-config-fluid/CLAUDE.md @@ -0,0 +1,37 @@ +# @fluidframework/eslint-config-fluid + +Shareable ESLint config for the Fluid Framework. Provides multiple configuration presets for consistent linting across Fluid packages. + +## Build + +- `pnpm build` - Print configs and run prettier check +- `pnpm print-configs` - Generate printed config files to `printed-configs/` +- `pnpm clean` - Remove dist and build logs + +## Format + +- `pnpm format` - Format code with prettier +- `pnpm prettier` - Check formatting without fixing +- `pnpm prettier:fix` - Fix formatting issues + +## Test + +- No tests currently implemented + +## Key Files + +- `index.js` - Main entry point +- `base.js` - Base ESLint configuration +- `recommended.js` - Recommended rules configuration +- `strict.js` - Strict rules configuration +- `strict-biome.js` - Strict config with Biome compatibility +- `flat.mts` - Flat config format (ESLint 9+) +- `minimal-deprecated.js` - Minimal/deprecated rules configuration +- `scripts/print-configs.ts` - Script to generate printed config output + +## Notes + +- This is a private package (not published to npm) +- Uses ESLint 9 flat config format via `flat.mts` +- The `print-configs` script outputs expanded configs to `printed-configs/` for debugging +- Integrates multiple ESLint plugins: TypeScript, import-x, jsdoc, unicorn, react, and more diff --git a/examples/apps/blobs/CLAUDE.md b/examples/apps/blobs/CLAUDE.md new file mode 100644 index 000000000000..0d8f9f99d33f --- /dev/null +++ b/examples/apps/blobs/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/blobs + +Example of using blobs in Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start with Tinylicious (t9s) service +- `pnpm start:local` - Start with local service +- `pnpm start:t9s` - Start with Tinylicious service +- `pnpm start:odsp` - Start with ODSP service + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses React for UI rendering +- Demonstrates blob handling with SharedMap +- Webpack-based build with multiple service configurations diff --git a/examples/apps/collaborative-textarea/CLAUDE.md b/examples/apps/collaborative-textarea/CLAUDE.md new file mode 100644 index 000000000000..be661e7be76c --- /dev/null +++ b/examples/apps/collaborative-textarea/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-example/collaborative-textarea + +A minimal example using the React collaborative-textarea component. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses React for UI and @fluidframework/sequence for collaborative text +- Demonstrates real-time collaborative text editing +- Built with @fluidframework/aqueduct DataObject pattern diff --git a/examples/apps/contact-collection/CLAUDE.md b/examples/apps/contact-collection/CLAUDE.md new file mode 100644 index 000000000000..6c0efe958588 --- /dev/null +++ b/examples/apps/contact-collection/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-example/contact-collection + +Example of using a Fluid Object as a collection of items. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses React for UI rendering +- Demonstrates managing a collection of contact items with Fluid +- Built with @fluidframework/aqueduct DataObject pattern diff --git a/examples/apps/data-object-grid/CLAUDE.md b/examples/apps/data-object-grid/CLAUDE.md new file mode 100644 index 000000000000..2d377f61030f --- /dev/null +++ b/examples/apps/data-object-grid/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/data-object-grid + +Data object grid creates child data objects from a registry and lays them out in a grid. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration +- `pnpm dev` - Run webpack in development mode + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses Fluent UI React components and react-grid-layout +- Demonstrates composing multiple Fluid examples (clicker, codemirror, prosemirror, etc.) +- Built with @fluidframework/aqueduct DataObject pattern diff --git a/examples/apps/diceroller/CLAUDE.md b/examples/apps/diceroller/CLAUDE.md new file mode 100644 index 000000000000..3002c1353049 --- /dev/null +++ b/examples/apps/diceroller/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/diceroller + +Minimal Fluid Container and Object sample to implement a collaborative dice roller. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start with Tinylicious (t9s) service +- `pnpm start:local` - Start with local service +- `pnpm start:t9s` - Start with Tinylicious service +- `pnpm start:odsp` - Start with ODSP service + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses React for UI and @fluidframework/map for shared state +- Minimal example demonstrating basic Fluid Framework usage +- Supports multiple service backends (local, t9s, ODSP) diff --git a/examples/apps/presence-tracker/CLAUDE.md b/examples/apps/presence-tracker/CLAUDE.md new file mode 100644 index 000000000000..52ed74384a6b --- /dev/null +++ b/examples/apps/presence-tracker/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/presence-tracker + +Example application that tracks page focus and mouse position using the Fluid Framework presence features. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start both Tinylicious server and client +- `pnpm start:client` - Start only the webpack dev server +- `pnpm start:tinylicious` - Start only the Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (starts Tinylicious automatically) +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses @fluidframework/presence for real-time presence tracking +- Uses @fluidframework/tinylicious-client and fluid-framework +- Requires Tinylicious server running on port 7070 +- Uses start-server-and-test for coordinated server/client startup diff --git a/examples/apps/staging/CLAUDE.md b/examples/apps/staging/CLAUDE.md new file mode 100644 index 000000000000..946005e76302 --- /dev/null +++ b/examples/apps/staging/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-example/staging + +Using the experimental staging feature. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Demonstrates experimental staging feature +- Uses React for UI and @fluidframework/map for shared state +- Supports multiple drivers: local, Tinylicious, and Routerlicious diff --git a/examples/apps/task-selection/CLAUDE.md b/examples/apps/task-selection/CLAUDE.md new file mode 100644 index 000000000000..f43a8144a738 --- /dev/null +++ b/examples/apps/task-selection/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-example/task-selection + +Example demonstrating selecting a unique task amongst connected Fluid clients. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses @fluidframework/task-manager for task coordination +- Uses @fluid-experimental/oldest-client-observer for client tracking +- Demonstrates leader election and task assignment patterns diff --git a/examples/apps/tree-cli-app/CLAUDE.md b/examples/apps/tree-cli-app/CLAUDE.md new file mode 100644 index 000000000000..73b8d753c9bf --- /dev/null +++ b/examples/apps/tree-cli-app/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluid-example/tree-cli-app + +SharedTree CLI app demo. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:test` - Build test files +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm app` - Run the CLI application (node ./lib/index.js) + +## Test + +- `pnpm test` - Run Mocha tests +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- CLI-based example (no webpack/browser) +- Uses @fluidframework/tree for SharedTree functionality +- Uses @sinclair/typebox for schema validation +- Uses Mocha for testing (not Jest like other examples) diff --git a/examples/apps/tree-comparison/CLAUDE.md b/examples/apps/tree-comparison/CLAUDE.md new file mode 100644 index 000000000000..45a824cee675 --- /dev/null +++ b/examples/apps/tree-comparison/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluid-example/tree-comparison + +Comparing API usage in legacy SharedTree and new SharedTree. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private example application (not published to npm) +- Uses React for UI rendering +- Compares @fluid-experimental/tree (legacy) with @fluidframework/tree (new) +- Useful for understanding migration between SharedTree versions +- Supports Tinylicious and Routerlicious drivers diff --git a/examples/benchmarks/bubblebench/baseline/CLAUDE.md b/examples/benchmarks/bubblebench/baseline/CLAUDE.md new file mode 100644 index 000000000000..5255bc720a46 --- /dev/null +++ b/examples/benchmarks/bubblebench/baseline/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluid-example/bubblebench-baseline + +Bubblemark-inspired DDS benchmark using SharedMap as the baseline implementation. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the benchmark (local mode) +- `pnpm start:tinylicious` - Run against Tinylicious +- `pnpm start:docker` - Run against Docker +- `pnpm start:r11s` - Run against R11s +- `pnpm start:spo` - Run against SharePoint Online +- `pnpm start:spo-df` - Run against SharePoint Online (dogfood) + +## Test + +- `pnpm test` - Run Jest tests (uses Puppeteer) +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a benchmark example (private, not published) +- Uses SharedMap (`@fluidframework/map`) for state management +- Depends on `@fluid-example/bubblebench-common` for shared utilities +- Browser-based benchmark bundled with Webpack diff --git a/examples/benchmarks/bubblebench/common/CLAUDE.md b/examples/benchmarks/bubblebench/common/CLAUDE.md new file mode 100644 index 000000000000..7f46675476c0 --- /dev/null +++ b/examples/benchmarks/bubblebench/common/CLAUDE.md @@ -0,0 +1,27 @@ +# @fluid-example/bubblebench-common + +Shared utilities and components for the Bubblebench benchmark suite. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a library package (private, not published) +- Exports shared code at `lib/index.js` +- No standalone run or test scripts - this is consumed by other bubblebench packages +- Key dependencies: + - `@fluid-experimental/tree` - Experimental tree DDS + - `@fluidframework/map` - SharedMap DDS + - `react` / `react-dom` - UI rendering + - `best-random` - Random number generation + - `use-resize-observer` - React resize hooks diff --git a/examples/benchmarks/bubblebench/experimental-tree/CLAUDE.md b/examples/benchmarks/bubblebench/experimental-tree/CLAUDE.md new file mode 100644 index 000000000000..f4254485b02f --- /dev/null +++ b/examples/benchmarks/bubblebench/experimental-tree/CLAUDE.md @@ -0,0 +1,37 @@ +# @fluid-example/bubblebench-experimental-tree + +Bubblemark-inspired DDS benchmark using the experimental tree DDS implementation. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the benchmark (local mode) +- `pnpm start:tinylicious` - Run against Tinylicious +- `pnpm start:docker` - Run against Docker +- `pnpm start:r11s` - Run against R11s +- `pnpm start:spo` - Run against SharePoint Online +- `pnpm start:spo-df` - Run against SharePoint Online (dogfood) + +## Test + +- `pnpm test` - Run Jest tests (uses Puppeteer) +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a benchmark example (private, not published) +- Uses `@fluid-experimental/tree` for state management +- Depends on `@fluid-example/bubblebench-common` for shared utilities +- Browser-based benchmark bundled with Webpack +- Compare performance against baseline and other implementations diff --git a/examples/benchmarks/bubblebench/ot/CLAUDE.md b/examples/benchmarks/bubblebench/ot/CLAUDE.md new file mode 100644 index 000000000000..bbb9df25ab14 --- /dev/null +++ b/examples/benchmarks/bubblebench/ot/CLAUDE.md @@ -0,0 +1,37 @@ +# @fluid-example/bubblebench-ot + +Bubblemark-inspired DDS benchmark using ShareJS JSON1 OT (Operational Transformation). + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the benchmark (local mode) +- `pnpm start:tinylicious` - Run against Tinylicious +- `pnpm start:docker` - Run against Docker +- `pnpm start:r11s` - Run against R11s +- `pnpm start:spo` - Run against SharePoint Online +- `pnpm start:spo-df` - Run against SharePoint Online (dogfood) + +## Test + +- `pnpm test` - Run Jest tests (uses Puppeteer) +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a benchmark example (private, not published) +- Uses `@fluid-experimental/sharejs-json1` and `ot-json1` for OT-based state management +- Depends on `@fluid-example/bubblebench-common` for shared utilities +- Browser-based benchmark bundled with Webpack +- Compare performance against CRDT-based implementations (baseline, tree, shared-tree) diff --git a/examples/benchmarks/bubblebench/shared-tree/CLAUDE.md b/examples/benchmarks/bubblebench/shared-tree/CLAUDE.md new file mode 100644 index 000000000000..04b71121d4df --- /dev/null +++ b/examples/benchmarks/bubblebench/shared-tree/CLAUDE.md @@ -0,0 +1,37 @@ +# @fluid-example/bubblebench-shared-tree + +Bubblemark-inspired DDS benchmark using the production SharedTree DDS. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the benchmark (local mode) +- `pnpm start:tinylicious` - Run against Tinylicious +- `pnpm start:docker` - Run against Docker +- `pnpm start:r11s` - Run against R11s +- `pnpm start:spo` - Run against SharePoint Online +- `pnpm start:spo-df` - Run against SharePoint Online (dogfood) + +## Test + +- `pnpm test` - Run Jest tests (uses Puppeteer) +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a benchmark example (private, not published) +- Uses `@fluidframework/tree` (production SharedTree) for state management +- Depends on `@fluid-example/bubblebench-common` for shared utilities +- Browser-based benchmark bundled with Webpack +- This is the recommended tree implementation to compare against baseline diff --git a/examples/benchmarks/odspsnapshotfetch-perftestapp/CLAUDE.md b/examples/benchmarks/odspsnapshotfetch-perftestapp/CLAUDE.md new file mode 100644 index 000000000000..99b7f6ab3feb --- /dev/null +++ b/examples/benchmarks/odspsnapshotfetch-perftestapp/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/odspsnapshotfetch-perftestapp + +Benchmark for comparing binary vs. JSON snapshot download performance from ODSP (OneDrive/SharePoint). + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start the benchmark (defaults to SPO dogfood) +- `pnpm start:spo` - Run against SharePoint Online +- `pnpm start:spo-df` - Run against SharePoint Online (dogfood) +- `pnpm dev` - Development mode with webpack + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a benchmark example (private, not published) +- Runs as an Express.js server (`lib/expressApp.js`) +- Tests ODSP driver performance for snapshot fetching +- Key dependencies: + - `@fluidframework/odsp-driver` - ODSP driver implementation + - `@fluidframework/odsp-doclib-utils` - ODSP utilities + - `@fluidframework/tool-utils` - CLI and tool utilities + - `express` - HTTP server +- No automated tests - manual performance testing app diff --git a/examples/benchmarks/tablebench/CLAUDE.md b/examples/benchmarks/tablebench/CLAUDE.md new file mode 100644 index 000000000000..dfa22420980f --- /dev/null +++ b/examples/benchmarks/tablebench/CLAUDE.md @@ -0,0 +1,47 @@ +# @fluid-internal/tablebench + +Table-focused benchmarks for comparing SharedTree and SharedMatrix performance. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:test` - Build test files +- `pnpm clean` - Remove build artifacts + +## Run + +- `pnpm start` - Start Tinylicious and webpack dev server +- `pnpm start:t9s` - Start Tinylicious only +- `pnpm start:webpack` - Start webpack dev server (requires Tinylicious running) + +## Test + +- `pnpm test` - Run Mocha tests +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:customBenchmarks` - Run custom benchmark suite + +## Benchmarks + +- `pnpm bench` - Run execution time benchmarks +- `pnpm bench:profile` - Run benchmarks with V8 profiling (outputs `profile.txt`) +- `pnpm bench:profile:inspect-brk` - Run benchmarks with debugger attached +- `pnpm bench:size` - Run size benchmarks +- `pnpm test:benchmark:report` - Generate benchmark report + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is a benchmark example (private, not published) +- Uses `@fluid-tools/benchmark` for performance measurement +- Key dependencies: + - `@fluidframework/tree` - SharedTree DDS + - `@fluidframework/matrix` - SharedMatrix DDS + - `@fluidframework/azure-client` - Azure Fluid Relay client +- Uses Mocha test framework with custom benchmark reporter +- Requires Tinylicious for local development (`pnpm start` handles this) diff --git a/examples/client-logger/app-insights-logger/CLAUDE.md b/examples/client-logger/app-insights-logger/CLAUDE.md new file mode 100644 index 000000000000..43cbf76a40b5 --- /dev/null +++ b/examples/client-logger/app-insights-logger/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-example/app-insights-logger + +A simple Fluid application with a React UI to test the Fluid App Insights telemetry logger that routes Fluid telemetry to Azure App Insights. + +## Build + +- `pnpm build` - Build the package +- `pnpm webpack` - Build webpack bundle for production +- `pnpm webpack:dev` - Build webpack bundle for development + +## Run + +- `pnpm start` - Start the full application (Tinylicious + client) +- `pnpm start:tinylicious` - Start Tinylicious server only +- `pnpm start:test-app:client` - Start webpack dev server only + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:coverage` - Run tests with coverage + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm eslint` - Run ESLint +- `pnpm eslint:fix` - Fix ESLint issues +- `pnpm format` - Format with Biome + +## Notes + +- This is an example package (not published) +- Uses Tinylicious as the local Fluid server (port 7070) +- Demonstrates integration with `@fluidframework/app-insights-logger` +- Uses `@microsoft/applicationinsights-web` for Azure App Insights integration +- Tests use Jest with jsdom environment and React Testing Library diff --git a/examples/data-objects/canvas/CLAUDE.md b/examples/data-objects/canvas/CLAUDE.md new file mode 100644 index 000000000000..22d226d92259 --- /dev/null +++ b/examples/data-objects/canvas/CLAUDE.md @@ -0,0 +1,25 @@ +# @fluid-example/canvas + +Fluid ink canvas example demonstrating collaborative drawing. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (Puppeteer-based) + +## Notes + +- This is an example package (private, not published) +- Uses `@fluid-experimental/ink` for collaborative ink/drawing functionality +- Uses webpack for bundling with dev server support diff --git a/examples/data-objects/clicker/CLAUDE.md b/examples/data-objects/clicker/CLAUDE.md new file mode 100644 index 000000000000..8212fb70239f --- /dev/null +++ b/examples/data-objects/clicker/CLAUDE.md @@ -0,0 +1,25 @@ +# @fluid-example/clicker + +Minimal Fluid component sample implementing a collaborative counter. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (Puppeteer-based) + +## Notes + +- This is an example package (private, not published) +- Uses `@fluidframework/counter` and `@fluidframework/task-manager` DDSes +- Good starting point for understanding Fluid Framework basics diff --git a/examples/data-objects/codemirror/CLAUDE.md b/examples/data-objects/codemirror/CLAUDE.md new file mode 100644 index 000000000000..82b4c6fd660c --- /dev/null +++ b/examples/data-objects/codemirror/CLAUDE.md @@ -0,0 +1,23 @@ +# @fluid-example/codemirror + +Simple collaborative markdown editor using CodeMirror. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server +- `pnpm dev` - Run webpack in development mode + +## Notes + +- This is an example package (private, not published) +- Integrates CodeMirror 5 with Fluid's SharedString (`@fluidframework/sequence`) +- Demonstrates real-time collaborative text editing diff --git a/examples/data-objects/inventory-app/CLAUDE.md b/examples/data-objects/inventory-app/CLAUDE.md new file mode 100644 index 000000000000..c9a1dc6083d9 --- /dev/null +++ b/examples/data-objects/inventory-app/CLAUDE.md @@ -0,0 +1,26 @@ +# @fluid-example/inventory-app + +Minimal sample demonstrating SharedTree and React integration. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (Puppeteer-based) + +## Notes + +- This is an example package (private, not published) +- Uses `@fluidframework/tree` (SharedTree) for hierarchical data +- Uses `@fluidframework/react` for React bindings +- Good reference for SharedTree + React patterns diff --git a/examples/data-objects/monaco/CLAUDE.md b/examples/data-objects/monaco/CLAUDE.md new file mode 100644 index 000000000000..aae9c079e39a --- /dev/null +++ b/examples/data-objects/monaco/CLAUDE.md @@ -0,0 +1,22 @@ +# @fluid-example/monaco + +Collaborative Monaco code editor example. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Notes + +- This is an example package (private, not published) +- Integrates Monaco Editor with Fluid's SharedString (`@fluidframework/sequence`) +- Uses monaco-editor-webpack-plugin for bundling +- Demonstrates rich code editor collaboration diff --git a/examples/data-objects/multiview/constellation-model/CLAUDE.md b/examples/data-objects/multiview/constellation-model/CLAUDE.md new file mode 100644 index 000000000000..51d87a37c20b --- /dev/null +++ b/examples/data-objects/multiview/constellation-model/CLAUDE.md @@ -0,0 +1,18 @@ +# @fluid-example/multiview-constellation-model + +Constellation model for the multiview sample demonstrating model-view separation. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Part of the multiview example demonstrating separation of model and view +- Depends on `@fluid-example/multiview-coordinate-interface` and `@fluid-example/multiview-coordinate-model` +- Uses `@fluidframework/map` for data storage +- Library-only package (no runnable app) diff --git a/examples/data-objects/multiview/constellation-view/CLAUDE.md b/examples/data-objects/multiview/constellation-view/CLAUDE.md new file mode 100644 index 000000000000..0d4edea74c70 --- /dev/null +++ b/examples/data-objects/multiview/constellation-view/CLAUDE.md @@ -0,0 +1,19 @@ +# @fluid-example/multiview-constellation-view + +Constellation view component for the multiview sample. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Part of the multiview example demonstrating separation of model and view +- React-based view component +- Depends on `@fluid-example/multiview-coordinate-interface` and `@fluid-example/multiview-slider-coordinate-view` +- Library-only package (no runnable app) diff --git a/examples/data-objects/multiview/container/CLAUDE.md b/examples/data-objects/multiview/container/CLAUDE.md new file mode 100644 index 000000000000..b77d0367237b --- /dev/null +++ b/examples/data-objects/multiview/container/CLAUDE.md @@ -0,0 +1,27 @@ +# @fluid-example/multiview-container + +Container package that assembles the multiview sample application. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (Puppeteer-based) + +## Notes + +- This is an example package (private, not published) +- Main entry point for the multiview example +- Combines all multiview models and views into a runnable application +- Demonstrates how to compose multiple Fluid data objects with different views diff --git a/examples/data-objects/multiview/coordinate-model/CLAUDE.md b/examples/data-objects/multiview/coordinate-model/CLAUDE.md new file mode 100644 index 000000000000..cfbfc02bcb59 --- /dev/null +++ b/examples/data-objects/multiview/coordinate-model/CLAUDE.md @@ -0,0 +1,18 @@ +# @fluid-example/multiview-coordinate-model + +Coordinate model for the multiview sample storing x,y coordinate data. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Part of the multiview example demonstrating separation of model and view +- Implements `@fluid-example/multiview-coordinate-interface` +- Uses `@fluidframework/map` for coordinate storage +- Library-only package (no runnable app) diff --git a/examples/data-objects/multiview/interface/CLAUDE.md b/examples/data-objects/multiview/interface/CLAUDE.md new file mode 100644 index 000000000000..9fb672c526f5 --- /dev/null +++ b/examples/data-objects/multiview/interface/CLAUDE.md @@ -0,0 +1,18 @@ +# @fluid-example/multiview-coordinate-interface + +Interface definitions for the multiview sample coordinate system. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Defines shared interfaces used by models and views in the multiview example +- Depends only on `@fluid-example/example-utils` +- Library-only package (no runnable app) +- Other multiview packages depend on this for type definitions diff --git a/examples/data-objects/multiview/plot-coordinate-view/CLAUDE.md b/examples/data-objects/multiview/plot-coordinate-view/CLAUDE.md new file mode 100644 index 000000000000..1c58e0a9c258 --- /dev/null +++ b/examples/data-objects/multiview/plot-coordinate-view/CLAUDE.md @@ -0,0 +1,19 @@ +# @fluid-example/multiview-plot-coordinate-view + +Plot view component for displaying coordinates in the multiview sample. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Part of the multiview example demonstrating separation of model and view +- React-based view component that plots coordinate data +- Depends on `@fluid-example/multiview-coordinate-interface` +- Library-only package (no runnable app) diff --git a/examples/data-objects/multiview/slider-coordinate-view/CLAUDE.md b/examples/data-objects/multiview/slider-coordinate-view/CLAUDE.md new file mode 100644 index 000000000000..c2277f8e72ff --- /dev/null +++ b/examples/data-objects/multiview/slider-coordinate-view/CLAUDE.md @@ -0,0 +1,19 @@ +# @fluid-example/multiview-slider-coordinate-view + +Slider view component for editing coordinates in the multiview sample. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Part of the multiview example demonstrating separation of model and view +- React-based view component with slider controls for coordinate editing +- Depends on `@fluid-example/multiview-coordinate-interface` +- Library-only package (no runnable app) diff --git a/examples/data-objects/multiview/triangle-view/CLAUDE.md b/examples/data-objects/multiview/triangle-view/CLAUDE.md new file mode 100644 index 000000000000..78231834dd77 --- /dev/null +++ b/examples/data-objects/multiview/triangle-view/CLAUDE.md @@ -0,0 +1,19 @@ +# @fluid-example/multiview-triangle-view + +Triangle view component for the multiview sample. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Notes + +- This is an example package (private, not published) +- Part of the multiview example demonstrating separation of model and view +- React-based view component that renders coordinate data as a triangle +- Depends on `@fluid-example/multiview-coordinate-interface` +- Library-only package (no runnable app) diff --git a/examples/data-objects/prosemirror/CLAUDE.md b/examples/data-objects/prosemirror/CLAUDE.md new file mode 100644 index 000000000000..3392c912c944 --- /dev/null +++ b/examples/data-objects/prosemirror/CLAUDE.md @@ -0,0 +1,24 @@ +# @fluid-example/prosemirror + +Collaborative rich text editor using ProseMirror. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server +- `pnpm dev` - Run webpack in development mode + +## Notes + +- This is an example package (private, not published) +- Integrates ProseMirror with Fluid's SharedString and merge-tree +- Uses multiple ProseMirror plugins (history, keymap, menu, schema-list) +- Demonstrates structured rich text collaboration diff --git a/examples/data-objects/smde/CLAUDE.md b/examples/data-objects/smde/CLAUDE.md new file mode 100644 index 000000000000..31abaaaa3b51 --- /dev/null +++ b/examples/data-objects/smde/CLAUDE.md @@ -0,0 +1,22 @@ +# @fluid-example/smde + +Simple markdown editor using SimpleMDE. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server +- `pnpm dev` - Run webpack in development mode + +## Notes + +- This is an example package (private, not published) +- Integrates SimpleMDE with Fluid's SharedString (`@fluidframework/sequence`) +- Simpler alternative to CodeMirror/Monaco examples diff --git a/examples/data-objects/table-document/CLAUDE.md b/examples/data-objects/table-document/CLAUDE.md new file mode 100644 index 000000000000..c6d5d26bd09b --- /dev/null +++ b/examples/data-objects/table-document/CLAUDE.md @@ -0,0 +1,23 @@ +# @fluid-example/table-document + +Chaincode component containing table data structures. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:commonjs` - Build CommonJS output +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Test + +- `pnpm test` - Run Mocha tests +- `pnpm test:coverage` - Run tests with c8 coverage + +## Notes + +- This package is NOT private (may be published) +- Uses `@fluid-experimental/sequence-deprecated` for table data +- Provides both ESM and CommonJS exports +- Has API extractor configuration for type checking diff --git a/examples/data-objects/table-tree/CLAUDE.md b/examples/data-objects/table-tree/CLAUDE.md new file mode 100644 index 000000000000..0967f2f7d697 --- /dev/null +++ b/examples/data-objects/table-tree/CLAUDE.md @@ -0,0 +1,26 @@ +# @fluid-example/table-tree + +Simple table example app using SharedTree. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (Puppeteer-based) + +## Notes + +- This is an example package (private, not published) +- Uses `@fluidframework/tree` (SharedTree) for table data +- Uses Fluent UI React components (`@fluentui/react-components`) +- Demonstrates tabular data with SharedTree diff --git a/examples/data-objects/todo/CLAUDE.md b/examples/data-objects/todo/CLAUDE.md new file mode 100644 index 000000000000..4351cb426bb2 --- /dev/null +++ b/examples/data-objects/todo/CLAUDE.md @@ -0,0 +1,26 @@ +# @fluid-example/todo + +Simple collaborative todo canvas application. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server + +## Test + +- `pnpm test` - Run Jest tests (Puppeteer-based) + +## Notes + +- This is an example package (private, not published) +- Uses `@fluidframework/tree` (SharedTree), `@fluidframework/map`, and `@fluidframework/sequence` +- Uses `@fluidframework/react` for React bindings +- Good example of combining multiple DDSes in one application diff --git a/examples/data-objects/webflow/CLAUDE.md b/examples/data-objects/webflow/CLAUDE.md new file mode 100644 index 000000000000..036f83b5d591 --- /dev/null +++ b/examples/data-objects/webflow/CLAUDE.md @@ -0,0 +1,30 @@ +# @fluid-example/webflow + +Collaborative markdown editor with custom flow layout. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm build:copy` - Copy CSS files to lib +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix lint issues + +## Run + +- `pnpm start` - Start dev server (local mode) +- `pnpm start:tinylicious` - Start with Tinylicious server +- `pnpm start:single` - Start in single-user mode +- `pnpm dev` - Watch mode for TypeScript + +## Test + +- `pnpm test` - Run Mocha tests +- `pnpm test:coverage` - Run tests with c8 coverage + +## Notes + +- This is an example package (private, not published) +- Uses `@fluidframework/sequence` and `@fluidframework/merge-tree` +- Has jsdom-based tests for DOM manipulation +- More complex editor example with custom layout engine diff --git a/examples/external-data/CLAUDE.md b/examples/external-data/CLAUDE.md new file mode 100644 index 000000000000..7c79b5133290 --- /dev/null +++ b/examples/external-data/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-example/app-integration-external-data + +Demonstrates integrating an external data source with Fluid data. + +## Build + +- `pnpm build` - Build the package +- `pnpm webpack` - Build webpack bundle for production +- `pnpm webpack:dev` - Build webpack bundle for development + +## Run + +- `pnpm start` - Start the full application (Tinylicious + services + client) +- `pnpm start:tinylicious` - Start Tinylicious server only +- `pnpm start:services` - Start mock external services (ports 5236 and 5237) +- `pnpm start:client` - Start webpack dev server + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm eslint` - Run ESLint +- `pnpm eslint:fix` - Fix ESLint issues +- `pnpm format` - Format with Biome + +## Notes + +- This is an example package (not published) +- Uses Tinylicious as the local Fluid server (port 7070) +- Includes mock external data service (port 5236) and customer service (port 5237) +- Tests use Puppeteer for browser automation diff --git a/examples/service-clients/azure-client/external-controller/CLAUDE.md b/examples/service-clients/azure-client/external-controller/CLAUDE.md new file mode 100644 index 000000000000..54b79eceb4ec --- /dev/null +++ b/examples/service-clients/azure-client/external-controller/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluid-example/app-integration-external-controller + +Minimal Fluid Container & Data Object sample to implement a collaborative dice roller as a standalone app. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm webpack` - Production webpack build +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start with Tinylicious (local Fluid server on port 7070) +- `pnpm start:azure` - Start with Azure Fluid Relay +- `pnpm start:client` - Start webpack dev server only (requires separate Fluid server) + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm eslint` - Run ESLint only +- `pnpm check:format` - Check Biome formatting +- `pnpm format` - Auto-fix formatting with Biome + +## Notes + +- This is a private example package (not published to npm) +- Uses `@fluidframework/azure-client` for Azure Fluid Relay connectivity +- Uses `@fluidframework/presence` for collaborative presence features +- Tinylicious runs on port 7070 for local development +- Tests use Puppeteer for browser automation diff --git a/examples/service-clients/azure-client/todo-list/CLAUDE.md b/examples/service-clients/azure-client/todo-list/CLAUDE.md new file mode 100644 index 000000000000..6f8c402acbee --- /dev/null +++ b/examples/service-clients/azure-client/todo-list/CLAUDE.md @@ -0,0 +1,37 @@ +# @fluid-example/azure-client-todo-list + +Minimal Fluid Container sample demonstrating the use of SharedTree and nested DDSs via a simple to-do list application. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm webpack` - Production webpack build +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start with Tinylicious (local Fluid server on port 7070) +- `pnpm start:azure` - Start with Azure Fluid Relay +- `pnpm start:client` - Start webpack dev server only (requires separate Fluid server) + +## Test + +- `pnpm test` - Run Jest tests with Puppeteer +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm eslint` - Run ESLint only +- `pnpm check:format` - Check Biome formatting +- `pnpm format` - Auto-fix formatting with Biome + +## Notes + +- This is a private example package (not published to npm) +- Uses `@fluidframework/azure-client` for Azure Fluid Relay connectivity +- React-based UI with `@fluidframework/react` bindings +- Demonstrates SharedTree usage with nested distributed data structures +- Tinylicious runs on port 7070 for local development +- Tests use Puppeteer for browser automation diff --git a/examples/service-clients/odsp-client/shared-tree-demo/CLAUDE.md b/examples/service-clients/odsp-client/shared-tree-demo/CLAUDE.md new file mode 100644 index 000000000000..1030b1560fe7 --- /dev/null +++ b/examples/service-clients/odsp-client/shared-tree-demo/CLAUDE.md @@ -0,0 +1,30 @@ +# @fluid-example/shared-tree-demo + +A shared tree demo using React and ODSP (OneDrive/SharePoint) client. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm webpack` - Production webpack build +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start webpack dev server + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm eslint` - Run ESLint only +- `pnpm check:format` - Check Biome formatting +- `pnpm format` - Auto-fix formatting with Biome + +## Notes + +- This is a private example package (not published to npm) +- Uses `@fluidframework/odsp-client` for OneDrive/SharePoint connectivity +- Requires Azure AD authentication via `@azure/msal-browser` +- React-based UI with Tailwind CSS for styling +- No local Tinylicious option - requires ODSP backend configuration +- May require `.env` file configuration (uses dotenv-webpack) diff --git a/examples/utils/bundle-size-tests/CLAUDE.md b/examples/utils/bundle-size-tests/CLAUDE.md new file mode 100644 index 000000000000..d3d6cbdb65ec --- /dev/null +++ b/examples/utils/bundle-size-tests/CLAUDE.md @@ -0,0 +1,30 @@ +# @fluid-example/bundle-size-tests + +A package for understanding the bundle size of Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build TypeScript only +- `pnpm webpack` - Run webpack bundling + +## Test + +- `pnpm test` - Run mocha tests (requires webpack build first) + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Bundle Analysis + +- `pnpm explore:tree` - Generate bundle analysis report for SharedTree + +## Notes + +- This is an example utility package (not published) +- Tests verify bundle sizes against thresholds using puppeteer +- Webpack bundles are required before running tests +- Uses source-map-explorer for detailed bundle analysis diff --git a/examples/utils/example-driver/CLAUDE.md b/examples/utils/example-driver/CLAUDE.md new file mode 100644 index 000000000000..bc33d022bdfd --- /dev/null +++ b/examples/utils/example-driver/CLAUDE.md @@ -0,0 +1,22 @@ +# @fluid-example/example-driver + +Simplified drivers used by examples in the FluidFramework repo. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is an example utility package (not published) +- Provides simplified driver wrappers for local, ODSP, routerlicious, and tinylicious drivers +- No tests in this package +- Dual ESM/CommonJS output diff --git a/examples/utils/example-utils/CLAUDE.md b/examples/utils/example-utils/CLAUDE.md new file mode 100644 index 000000000000..3cb3b34d8986 --- /dev/null +++ b/examples/utils/example-utils/CLAUDE.md @@ -0,0 +1,25 @@ +# @fluid-example/example-utils + +Shared utilities used by examples. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:docs` - Generate API documentation with api-extractor +- `pnpm tsc` - Build CommonJS output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome +- `pnpm check:exports` - Validate API exports + +## Notes + +- This is an example utility package (not published) +- Provides shared utilities for Fluid Framework examples +- Includes React components and hooks for Fluid containers +- Dual ESM/CommonJS output +- No tests in this package diff --git a/examples/utils/example-webpack-integration/CLAUDE.md b/examples/utils/example-webpack-integration/CLAUDE.md new file mode 100644 index 000000000000..d012af16146c --- /dev/null +++ b/examples/utils/example-webpack-integration/CLAUDE.md @@ -0,0 +1,23 @@ +# @fluid-example/example-webpack-integration + +Webpack configuration used by examples in the FluidFramework repo. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is an example utility package (not published) +- Provides shared webpack configuration for Fluid examples +- Includes webpack and webpack-dev-server as dependencies +- Dual ESM/CommonJS output +- No tests in this package diff --git a/examples/utils/import-testing/CLAUDE.md b/examples/utils/import-testing/CLAUDE.md new file mode 100644 index 000000000000..0879dbef5775 --- /dev/null +++ b/examples/utils/import-testing/CLAUDE.md @@ -0,0 +1,30 @@ +# @fluid-example/import-testing + +Testing package imports across different module systems and TypeScript versions. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:test` - Build ESM and CJS tests +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run all tests (ESM and CJS) +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:mocha:cjs` - Run CJS tests only +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is an example utility package (not published) +- Tests imports of fluid-framework and related packages +- Validates compatibility across multiple TypeScript versions (5.4-5.9) +- Tests both ESM and CommonJS module systems diff --git a/examples/utils/migration-tools/CLAUDE.md b/examples/utils/migration-tools/CLAUDE.md new file mode 100644 index 000000000000..06500a1201d1 --- /dev/null +++ b/examples/utils/migration-tools/CLAUDE.md @@ -0,0 +1,25 @@ +# @fluid-example/migration-tools + +Tools for migrating data in Fluid containers. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:docs` - Generate API documentation with api-extractor +- `pnpm tsc` - Build CommonJS output + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome +- `pnpm check:exports` - Validate API exports + +## Notes + +- This is an example utility package (not published) +- Provides utilities for container migration scenarios +- Exports via `/alpha` and `/internal` subpaths (not root) +- Dual ESM/CommonJS output +- No tests in this package diff --git a/examples/utils/webpack-fluid-loader/CLAUDE.md b/examples/utils/webpack-fluid-loader/CLAUDE.md new file mode 100644 index 000000000000..6835e391df44 --- /dev/null +++ b/examples/utils/webpack-fluid-loader/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-example/webpack-fluid-loader + +Fluid object loader for webpack-dev-server. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:webpack` - Build webpack bundle +- `pnpm webpack` - Run webpack directly +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run mocha tests (ESM only by default) +- `pnpm test:mocha:esm` - Run ESM tests +- `pnpm test:mocha:cjs` - Run CJS tests +- `pnpm test:coverage` - Run tests with c8 coverage + +## Lint + +- `pnpm lint` - Run linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Notes + +- This is an example utility package (not published) +- Injects a script tag pointing at its own bundle (`/code/fluid-loader.bundle.js`) into the page +- Webpack bundle must stay up to date for users of this loader +- Supports local, ODSP, and routerlicious drivers +- Dual ESM/CommonJS output diff --git a/examples/version-migration/live-schema-upgrade/CLAUDE.md b/examples/version-migration/live-schema-upgrade/CLAUDE.md new file mode 100644 index 000000000000..351fed6c3a4a --- /dev/null +++ b/examples/version-migration/live-schema-upgrade/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-example/app-integration-live-schema-upgrade + +Example application that demonstrates how to add a data object to a live container. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private version migration example (not published to npm) +- Uses webpack for bundling and dev server +- Uses Puppeteer for integration tests +- Key dependencies: @fluidframework/aqueduct, @fluidframework/counter, @fluidframework/container-loader diff --git a/examples/version-migration/same-container/CLAUDE.md b/examples/version-migration/same-container/CLAUDE.md new file mode 100644 index 000000000000..46490801413b --- /dev/null +++ b/examples/version-migration/same-container/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluid-example/version-migration-same-container + +Migrate data between two formats by exporting and reimporting in the same container. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private version migration example (not published to npm) +- Uses React for the UI +- Uses webpack for bundling and dev server +- Uses Puppeteer for integration tests +- Key dependencies: @fluidframework/map, @fluidframework/sequence, @fluidframework/cell, @fluidframework/task-manager diff --git a/examples/version-migration/separate-container/CLAUDE.md b/examples/version-migration/separate-container/CLAUDE.md new file mode 100644 index 000000000000..e0060e3c3b33 --- /dev/null +++ b/examples/version-migration/separate-container/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/version-migration-separate-container + +Migrate data between two formats by exporting and reimporting in a new container. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private version migration example (not published to npm) +- Uses React for the UI +- Uses webpack for bundling and dev server +- Uses Puppeteer for integration tests +- Depends on @fluid-example/migration-tools for migration utilities +- Key dependencies: @fluidframework/map, @fluidframework/sequence, @fluidframework/cell, @fluidframework/container-runtime diff --git a/examples/version-migration/tree-shim/CLAUDE.md b/examples/version-migration/tree-shim/CLAUDE.md new file mode 100644 index 000000000000..c41646d23455 --- /dev/null +++ b/examples/version-migration/tree-shim/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-example/tree-shim + +Migrating from legacy SharedTree to new SharedTree using a tree shim. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - TypeScript compilation only +- `pnpm clean` - Clean build artifacts + +## Run + +- `pnpm start` - Start the webpack dev server +- `pnpm start:tinylicious` - Start Tinylicious server and then the app +- `pnpm start:test` - Start with test configuration + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format code with Biome + +## Notes + +- This is a private version migration example (not published to npm) +- Uses React for the UI +- Uses webpack for bundling and dev server +- Uses Puppeteer for integration tests +- Key dependencies: @fluid-experimental/tree (legacy), @fluidframework/tree (new) +- Demonstrates shimming between legacy and new SharedTree implementations diff --git a/examples/view-integration/container-views/CLAUDE.md b/examples/view-integration/container-views/CLAUDE.md new file mode 100644 index 000000000000..f05ecc0d8b12 --- /dev/null +++ b/examples/view-integration/container-views/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluid-example/app-integration-container-views + +Minimal Fluid Container & data store sample to implement a collaborative dice roller as a standalone app. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm webpack` - Build webpack bundle for production +- `pnpm webpack:dev` - Build webpack bundle for development + +## Run + +- `pnpm start` - Start webpack dev server + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm check:format` - Check formatting with Biome +- `pnpm format` - Fix formatting with Biome + +## Notes + +- This is a view integration example (not published) +- Uses React for the view layer +- Uses @fluidframework/aqueduct for the data layer +- Tests use Puppeteer for browser automation diff --git a/examples/view-integration/external-views/CLAUDE.md b/examples/view-integration/external-views/CLAUDE.md new file mode 100644 index 000000000000..ea7364e513fb --- /dev/null +++ b/examples/view-integration/external-views/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-example/app-integration-external-views + +Minimal Fluid Container & Data Object sample to implement a collaborative dice roller as a standalone app. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm webpack` - Build webpack bundle for production +- `pnpm webpack:dev` - Build webpack bundle for development + +## Run + +- `pnpm start` - Start with Tinylicious service (default) +- `pnpm start:local` - Start with local service +- `pnpm start:t9s` - Start with Tinylicious service +- `pnpm start:odsp` - Start with OneDrive/SharePoint service +- `pnpm start:test` - Start for testing (local service, test config) + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm check:format` - Check formatting with Biome +- `pnpm format` - Fix formatting with Biome + +## Notes + +- This is a view integration example (not published) +- Uses React for the view layer +- Demonstrates external view integration with Fluid containers +- Supports multiple service backends (local, Tinylicious, ODSP) +- Tests use Puppeteer for browser automation diff --git a/examples/view-integration/view-framework-sampler/CLAUDE.md b/examples/view-integration/view-framework-sampler/CLAUDE.md new file mode 100644 index 000000000000..5aeb5013d16c --- /dev/null +++ b/examples/view-integration/view-framework-sampler/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-example/view-framework-sampler + +Example of integrating a Fluid data object with a variety of view frameworks. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm webpack` - Build webpack bundle for production +- `pnpm webpack:dev` - Build webpack bundle for development + +## Run + +- `pnpm start` - Start webpack dev server +- `pnpm start:test` - Start for testing (test config) + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:jest:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm check:format` - Check formatting with Biome +- `pnpm format` - Fix formatting with Biome + +## Notes + +- This is a view integration example (not published) +- Demonstrates integration with multiple view frameworks: React and Vue +- Uses @fluidframework/aqueduct for the data layer +- Tests use Puppeteer for browser automation diff --git a/experimental/PropertyDDS/packages/property-changeset/CLAUDE.md b/experimental/PropertyDDS/packages/property-changeset/CLAUDE.md new file mode 100644 index 000000000000..fafd2a59e070 --- /dev/null +++ b/experimental/PropertyDDS/packages/property-changeset/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluid-experimental/property-changeset + +Property changeset definitions and related functionalities. Core component of the PropertyDDS system for representing and manipulating property changes. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests (ESM and CJS) +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, both ESM and CJS) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluid-experimental/property-common` - Common property utilities +- `ajv` / `ajv-keywords` - JSON schema validation +- `lodash` - Utility functions +- `traverse` - Object traversal + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Part of the PropertyDDS suite of packages +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/PropertyDDS/packages/property-common/CLAUDE.md b/experimental/PropertyDDS/packages/property-common/CLAUDE.md new file mode 100644 index 000000000000..b6f9e5c9e09b --- /dev/null +++ b/experimental/PropertyDDS/packages/property-common/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-experimental/property-common + +Common functions used in properties. Foundational utilities for the PropertyDDS system. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `ajv` - JSON schema validation +- `lodash` - Utility functions +- `murmurhash3js` - Hashing utilities +- `base64-js` - Base64 encoding/decoding +- `traverse` - Object traversal + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Part of the PropertyDDS suite of packages +- Base dependency for other PropertyDDS packages +- Type validation is disabled for this package +- Tests run from `dist/test` directory diff --git a/experimental/PropertyDDS/packages/property-dds/CLAUDE.md b/experimental/PropertyDDS/packages/property-dds/CLAUDE.md new file mode 100644 index 000000000000..e39ade4003f2 --- /dev/null +++ b/experimental/PropertyDDS/packages/property-dds/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-experimental/property-dds + +Definition of the property distributed data store. The main DDS implementation for the PropertyDDS system. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests (ESM and CJS) +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluid-experimental/property-changeset` - Changeset handling +- `@fluid-experimental/property-properties` - Property definitions +- `@fluidframework/shared-object-base` - Base class for shared objects +- `axios` - HTTP client +- `lz4js` / `pako` - Compression +- `msgpackr` - MessagePack serialization + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Part of the PropertyDDS suite of packages +- Main DDS implementation that depends on property-changeset and property-properties +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/PropertyDDS/packages/property-properties/CLAUDE.md b/experimental/PropertyDDS/packages/property-properties/CLAUDE.md new file mode 100644 index 000000000000..59f6cde4f1d6 --- /dev/null +++ b/experimental/PropertyDDS/packages/property-properties/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-experimental/property-properties + +Definitions of properties. Core property type definitions for the PropertyDDS system. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluid-experimental/property-changeset` - Changeset handling +- `@fluid-experimental/property-common` - Common utilities +- `ajv` - JSON schema validation +- `lodash` - Utility functions +- `traverse` - Object traversal + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Part of the PropertyDDS suite of packages +- Provides property type definitions used by property-dds +- Type validation is disabled for this package +- Tests run from `dist/test` directory diff --git a/experimental/dds/ot/ot/CLAUDE.md b/experimental/dds/ot/ot/CLAUDE.md new file mode 100644 index 000000000000..5db6ca344980 --- /dev/null +++ b/experimental/dds/ot/ot/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluid-experimental/ot + +Distributed data structure for hosting ottypes. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests (ESM and CJS) +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluidframework/shared-object-base` - Base class for shared objects +- `@fluidframework/datastore-definitions` - Datastore interfaces + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/dds/ot/sharejs/json1/CLAUDE.md b/experimental/dds/ot/sharejs/json1/CLAUDE.md new file mode 100644 index 000000000000..82a3d11ccc40 --- /dev/null +++ b/experimental/dds/ot/sharejs/json1/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-experimental/sharejs-json1 + +Distributed data structure for hosting ottypes, specifically ShareJS json1 OT type. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests (ESM and CJS) +- `pnpm dev` - Watch mode for development +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluid-experimental/ot` - Base OT hosting infrastructure +- `ot-json1` - ShareJS json1 OT type implementation + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/dds/sequence-deprecated/CLAUDE.md b/experimental/dds/sequence-deprecated/CLAUDE.md new file mode 100644 index 000000000000..4c3719a26deb --- /dev/null +++ b/experimental/dds/sequence-deprecated/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-experimental/sequence-deprecated + +Deprecated distributed sequences. Contains legacy sequence implementations that are no longer recommended for new development. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build tests (ESM and CJS) +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluidframework/merge-tree` - Core merge tree implementation +- `@fluidframework/sequence` - Main sequence package +- `@fluidframework/shared-object-base` - Base class for shared objects + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- This package contains deprecated implementations; prefer `@fluidframework/sequence` for new code +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/dds/tree/CLAUDE.md b/experimental/dds/tree/CLAUDE.md new file mode 100644 index 000000000000..42776abc9f65 --- /dev/null +++ b/experimental/dds/tree/CLAUDE.md @@ -0,0 +1,41 @@ +# @fluid-experimental/tree + +Distributed tree data structure. An experimental tree implementation with advanced features. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:stress` - Run fuzz/stress tests +- `pnpm perf` - Run performance benchmarks +- `pnpm perf:measure` - Run measurement benchmarks + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluidframework/tree` - Core tree package +- `@fluidframework/id-compressor` - ID compression utilities +- `@fluidframework/shared-object-base` - Base class for shared objects +- `@tylerbu/sorted-btree-es6` - Sorted B-tree data structure +- `denque` - Double-ended queue +- `lru-cache` - LRU caching + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- Contains fuzz tests (`*.fuzz.tests.js`) for stress testing +- Has benchmark tests for performance measurement +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/framework/data-objects/CLAUDE.md b/experimental/framework/data-objects/CLAUDE.md new file mode 100644 index 000000000000..2818799ec706 --- /dev/null +++ b/experimental/framework/data-objects/CLAUDE.md @@ -0,0 +1,28 @@ +# @fluid-experimental/data-objects + +A collection of ready-to-use Fluid Data Objects. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm clean` - Clean build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluidframework/aqueduct` - Fluid aqueduct framework +- `@fluidframework/map` - SharedMap implementation +- `@fluidframework/datastore-definitions` - Datastore interfaces + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- No test suite in this package +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/experimental/framework/last-edited/CLAUDE.md b/experimental/framework/last-edited/CLAUDE.md new file mode 100644 index 000000000000..32b672ca8cec --- /dev/null +++ b/experimental/framework/last-edited/CLAUDE.md @@ -0,0 +1,28 @@ +# @fluid-experimental/last-edited + +Tracks the last edited information in the Container. Useful for displaying when content was last modified. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm clean` - Clean build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Dependencies + +- `@fluidframework/aqueduct` - Fluid aqueduct framework +- `@fluidframework/container-runtime` - Container runtime +- `@fluidframework/shared-summary-block` - Shared summary block for persistence + +## Notes + +- This is an experimental package under the `@fluid-experimental` namespace +- No test suite in this package +- Type validation is disabled for this package +- Supports both ESM and CommonJS output diff --git a/packages/common/client-utils/CLAUDE.md b/packages/common/client-utils/CLAUDE.md new file mode 100644 index 000000000000..135c86ff4f7b --- /dev/null +++ b/packages/common/client-utils/CLAUDE.md @@ -0,0 +1,39 @@ +# @fluid-internal/client-utils + +Internal client utilities for the Fluid Framework. Not intended for use outside the Fluid Framework. + +## Build + +- `pnpm build` - Build the package (runs fluid-build) +- `pnpm build:esnext` - Build ESM with TypeScript +- `pnpm tsc` - Build CommonJS +- `pnpm clean` - Remove build artifacts + +## Test + +- `pnpm test` - Run all tests (mocha + jest) +- `pnpm test:mocha` - Run mocha tests (ESM and CJS) +- `pnpm test:jest` - Run jest tests (browser environment with puppeteer) +- `pnpm test:coverage` - Run tests with c8 coverage + +## Lint + +- `pnpm lint` - Run all linters +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with biome +- `pnpm eslint` - Run eslint only + +## Key Files + +- `src/indexBrowser.ts` - Browser entry point +- `src/indexNode.ts` - Node.js entry point +- `src/bufferBrowser.ts` / `src/bufferNode.ts` - Platform-specific buffer utilities +- `src/base64EncodingBrowser.ts` / `src/base64EncodingNode.ts` - Platform-specific base64 encoding +- `src/hashFileBrowser.ts` / `src/hashFileNode.ts` - Platform-specific hashing +- `src/typedEventEmitter.ts` - Typed event emitter implementation + +## Notes + +- Dual entry points: separate browser and Node.js builds +- Uses both mocha and jest for testing (jest for browser tests with puppeteer) +- Dependencies: `@fluidframework/core-interfaces`, `@fluidframework/core-utils` diff --git a/packages/common/container-definitions/CLAUDE.md b/packages/common/container-definitions/CLAUDE.md new file mode 100644 index 000000000000..3db114c73b65 --- /dev/null +++ b/packages/common/container-definitions/CLAUDE.md @@ -0,0 +1,42 @@ +# @fluidframework/container-definitions + +Fluid container definitions - interfaces and types for Fluid containers. + +## Build + +- `pnpm build` - Build the package (runs fluid-build) +- `pnpm build:esnext` - Build ESM with TypeScript +- `pnpm tsc` - Build CommonJS +- `pnpm clean` - Remove build artifacts + +## Test + +This package has no tests (`ci:test` echoes "No test for this package"). + +## Lint + +- `pnpm lint` - Run all linters +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with biome +- `pnpm eslint` - Run eslint only + +## Key Files + +- `src/loader.ts` - Loader interfaces and types +- `src/runtime.ts` - Runtime interfaces and types +- `src/deltas.ts` - Delta/operation types +- `src/audience.ts` - Audience interfaces +- `src/fluidPackage.ts` - Fluid package definitions +- `src/error.ts` - Error types + +## Exports + +- `.` - Public API +- `./legacy` - Legacy API (beta exports) +- `./internal` - Internal API + +## Notes + +- Type-only package defining core container interfaces +- Dependencies: `@fluidframework/core-interfaces`, `@fluidframework/driver-definitions` +- Has known broken type validation for `ContainerErrorTypes` diff --git a/packages/common/core-interfaces/CLAUDE.md b/packages/common/core-interfaces/CLAUDE.md new file mode 100644 index 000000000000..bcf1a40952a0 --- /dev/null +++ b/packages/common/core-interfaces/CLAUDE.md @@ -0,0 +1,49 @@ +# @fluidframework/core-interfaces + +Core Fluid object interfaces - foundational types for the Fluid Framework. + +## Build + +- `pnpm build` - Build the package (runs fluid-build) +- `pnpm build:esnext` - Build ESM with TypeScript +- `pnpm tsc` - Build CommonJS +- `pnpm clean` - Remove build artifacts + +## Test + +- `pnpm test` - Run mocha tests +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:mocha:cjs` - Run CJS tests only +- `pnpm test:coverage` - Run tests with c8 coverage + +## Lint + +- `pnpm lint` - Run all linters +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with biome +- `pnpm eslint` - Run eslint only + +## Key Files + +- `src/events.ts` - Event-related interfaces +- `src/handles.ts` - Handle interfaces +- `src/error.ts` - Error interfaces and types +- `src/disposable.ts` - Disposable interface +- `src/fluidLoadable.ts` - Loadable interfaces +- `src/jsonSerializable.ts` / `src/jsonDeserialized.ts` - JSON serialization types +- `src/exposedInternalUtilityTypes.ts` - Internal utility types +- `src/brandedType.ts` / `src/erasedType.ts` - Type branding utilities + +## Exports + +- `.` - Public API +- `./legacy` - Legacy API +- `./legacy/alpha` - Legacy alpha API +- `./internal` - Internal API +- `./internal/exposedUtilityTypes` - Exposed utility types + +## Notes + +- Foundation package with no runtime dependencies +- Has known broken type validation for `FluidErrorTypes` +- Contains special test for `exactOptionalPropertyTypes` TypeScript flag diff --git a/packages/common/core-utils/CLAUDE.md b/packages/common/core-utils/CLAUDE.md new file mode 100644 index 000000000000..da7ef2ee501c --- /dev/null +++ b/packages/common/core-utils/CLAUDE.md @@ -0,0 +1,53 @@ +# @fluidframework/core-utils + +Core utilities for the Fluid Framework. Not intended for use outside the Fluid client repo. + +## Build + +- `pnpm build` - Build the package (runs fluid-build) +- `pnpm build:esnext` - Build ESM with TypeScript +- `pnpm tsc` - Build CommonJS +- `pnpm clean` - Remove build artifacts + +## Test + +- `pnpm test` - Run mocha tests +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:mocha:cjs` - Run CJS tests only +- `pnpm test:coverage` - Run tests with c8 coverage + +## Benchmarks + +- `pnpm bench` - Run benchmarks +- `pnpm bench:profile` - Run benchmarks with V8 profiling + +## Lint + +- `pnpm lint` - Run all linters +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with biome +- `pnpm eslint` - Run eslint only + +## Key Files + +- `src/assert.ts` - Assertion utilities +- `src/lazy.ts` - Lazy initialization utilities +- `src/timer.ts` - Timer utilities +- `src/delay.ts` - Delay/sleep utilities +- `src/promiseCache.ts` - Promise caching +- `src/promises.ts` - Promise utilities +- `src/heap.ts` - Heap data structure +- `src/list.ts` - List data structure +- `src/compare.ts` - Comparison utilities +- `src/map.ts` - Map utilities + +## Exports + +- `.` - Public API +- `./legacy` - Legacy API +- `./internal` - Internal API + +## Notes + +- Internal utility package with no external dependencies +- Contains performance benchmarks using @fluid-tools/benchmark diff --git a/packages/common/driver-definitions/CLAUDE.md b/packages/common/driver-definitions/CLAUDE.md new file mode 100644 index 000000000000..327737d0e03f --- /dev/null +++ b/packages/common/driver-definitions/CLAUDE.md @@ -0,0 +1,42 @@ +# @fluidframework/driver-definitions + +Fluid driver definitions - interfaces and types for Fluid drivers (storage/transport layer). + +## Build + +- `pnpm build` - Build the package (runs fluid-build) +- `pnpm build:esnext` - Build ESM with TypeScript +- `pnpm tsc` - Build CommonJS +- `pnpm clean` - Remove build artifacts + +## Test + +This package has no tests (`ci:test` echoes "No test for this package"). + +## Lint + +- `pnpm lint` - Run all linters +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with biome +- `pnpm eslint` - Run eslint only + +## Key Files + +- `src/storage.ts` - Storage interfaces (document storage, blob storage) +- `src/driverError.ts` - Driver error types +- `src/urlResolver.ts` - URL resolver interfaces +- `src/cacheDefinitions.ts` - Caching interfaces +- `src/protocol/` - Protocol-related definitions +- `src/git/` - Git-related definitions + +## Exports + +- `.` - Public API +- `./legacy` - Legacy API +- `./internal` - Internal API + +## Notes + +- Type-only package defining driver/storage layer interfaces +- Dependencies: `@fluidframework/core-interfaces` +- Build depends on `typetests:gen` task diff --git a/packages/dds/cell/CLAUDE.md b/packages/dds/cell/CLAUDE.md new file mode 100644 index 000000000000..f4751021303f --- /dev/null +++ b/packages/dds/cell/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/cell + +Distributed data structure for a single value. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Dual ESM/CommonJS package +- Extends `@fluidframework/shared-object-base` +- Has public and internal entry points diff --git a/packages/dds/counter/CLAUDE.md b/packages/dds/counter/CLAUDE.md new file mode 100644 index 000000000000..9f6264f8a611 --- /dev/null +++ b/packages/dds/counter/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/counter + +Counter DDS - a distributed counter data structure. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Dual ESM/CommonJS package +- Has public, legacy, and internal entry points +- Uses stochastic testing via `@fluid-private/stochastic-test-utils` diff --git a/packages/dds/ink/CLAUDE.md b/packages/dds/ink/CLAUDE.md new file mode 100644 index 000000000000..3a2b22ea7def --- /dev/null +++ b/packages/dds/ink/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-experimental/ink + +Ink DDS - experimental distributed data structure for ink/drawing data. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Experimental package (`@fluid-experimental` scope) +- Type validation is disabled +- Uses `uuid` for unique identifiers diff --git a/packages/dds/legacy-dds/CLAUDE.md b/packages/dds/legacy-dds/CLAUDE.md new file mode 100644 index 000000000000..c0468a9907c8 --- /dev/null +++ b/packages/dds/legacy-dds/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/legacy-dds + +Legacy DDSs for the Fluid Framework. These are not intended for use in new code. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Contains legacy DDSs - not for new development +- Type validation is disabled +- Has public, legacy, and internal entry points diff --git a/packages/dds/map/CLAUDE.md b/packages/dds/map/CLAUDE.md new file mode 100644 index 000000000000..2b63d14443c5 --- /dev/null +++ b/packages/dds/map/CLAUDE.md @@ -0,0 +1,40 @@ +# @fluidframework/map + +Distributed map - a key-value data structure. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:memory` - Run memory tests +- `pnpm test:stress` - Run stress/fuzz tests +- `pnpm test:snapshots:regen` - Regenerate test snapshots + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `src/test/memory/` - Memory tests +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Dual ESM/CommonJS package +- Has public, legacy, and internal entry points +- Includes memory and stress testing capabilities +- Uses `path-browserify` for browser compatibility diff --git a/packages/dds/matrix/CLAUDE.md b/packages/dds/matrix/CLAUDE.md new file mode 100644 index 000000000000..201628991888 --- /dev/null +++ b/packages/dds/matrix/CLAUDE.md @@ -0,0 +1,46 @@ +# @fluidframework/matrix + +Distributed matrix - a 2D data structure. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:memory` - Run memory tests +- `pnpm test:stress` - Run stress/fuzz tests +- `pnpm test:benchmark:report` - Run benchmark tests + +## Benchmark + +- `pnpm bench` - Run benchmarks +- `pnpm bench:profile` - Run benchmarks with profiling + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `bench/` - Benchmark code +- `src/test/memory/` - Memory tests +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Depends on `@fluidframework/merge-tree` for underlying data structure +- Uses `@tiny-calc/nano` for calculations +- Has public, legacy, and internal entry points +- Includes memory, stress, and benchmark testing diff --git a/packages/dds/merge-tree/CLAUDE.md b/packages/dds/merge-tree/CLAUDE.md new file mode 100644 index 000000000000..86376ce87df5 --- /dev/null +++ b/packages/dds/merge-tree/CLAUDE.md @@ -0,0 +1,44 @@ +# @fluidframework/merge-tree + +Merge tree - core data structure for sequence-based DDSs. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:stress` - Run stress/fuzz tests +- `pnpm test:benchmark:report` - Run benchmark tests + +## Performance + +- `pnpm perf` - Run performance benchmarks +- `pnpm perf:measure` - Run measurement benchmarks +- `pnpm perf:profile` - Run with profiling + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Core dependency for sequence-based DDSs (sequence, matrix) +- Has public, legacy, and internal entry points +- Extensive performance testing capabilities +- Uses `@fluid-private/stochastic-test-utils` for fuzz testing diff --git a/packages/dds/ordered-collection/CLAUDE.md b/packages/dds/ordered-collection/CLAUDE.md new file mode 100644 index 000000000000..ed1de3f0b59d --- /dev/null +++ b/packages/dds/ordered-collection/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluidframework/ordered-collection + +Consensus Collection - distributed ordered collection with consensus. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Dual ESM/CommonJS package +- Has public, legacy, and internal entry points +- Uses `uuid` for unique identifiers +- Uses consensus-based operations diff --git a/packages/dds/pact-map/CLAUDE.md b/packages/dds/pact-map/CLAUDE.md new file mode 100644 index 000000000000..da91b91a12f9 --- /dev/null +++ b/packages/dds/pact-map/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-experimental/pact-map + +Distributed data structure for key-value pairs using pact consensus. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Experimental package (`@fluid-experimental` scope) +- Type validation is disabled +- Single entry point (no public/legacy split) diff --git a/packages/dds/register-collection/CLAUDE.md b/packages/dds/register-collection/CLAUDE.md new file mode 100644 index 000000000000..5a9a68a8d468 --- /dev/null +++ b/packages/dds/register-collection/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/register-collection + +Consensus Register - distributed register collection with consensus. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Dual ESM/CommonJS package +- Has public, legacy, and internal entry points +- Uses consensus-based operations diff --git a/packages/dds/sequence/CLAUDE.md b/packages/dds/sequence/CLAUDE.md new file mode 100644 index 000000000000..054a3f8cec94 --- /dev/null +++ b/packages/dds/sequence/CLAUDE.md @@ -0,0 +1,46 @@ +# @fluidframework/sequence + +Distributed sequence - ordered collection of items (e.g., SharedString). + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:memory` - Run memory tests +- `pnpm test:stress` - Run stress/fuzz tests +- `pnpm test:benchmark:report` - Run benchmark tests + +## Performance + +- `pnpm perf` - Run performance benchmarks +- `pnpm perf:measure` - Run measurement benchmarks + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `src/test/memory/` - Memory tests +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Depends on `@fluidframework/merge-tree` for underlying data structure +- Has public, legacy, and internal entry points +- Includes interval collection functionality +- Extensive testing: memory, stress, fuzz, and benchmarks +- Build depends on merge-tree test build diff --git a/packages/dds/shared-object-base/CLAUDE.md b/packages/dds/shared-object-base/CLAUDE.md new file mode 100644 index 000000000000..dbb16055c97a --- /dev/null +++ b/packages/dds/shared-object-base/CLAUDE.md @@ -0,0 +1,41 @@ +# @fluidframework/shared-object-base + +Fluid base class for shared distributed data structures. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Benchmark + +- `pnpm bench` - Run benchmarks + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `bench/` - Benchmark code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Core base class for all DDSs - most DDS packages depend on this +- Has public, legacy, and internal entry points +- Depends on `@fluidframework/datastore` and `@fluidframework/id-compressor` +- Uses `sinon` for test mocking diff --git a/packages/dds/shared-summary-block/CLAUDE.md b/packages/dds/shared-summary-block/CLAUDE.md new file mode 100644 index 000000000000..44d362ac95e9 --- /dev/null +++ b/packages/dds/shared-summary-block/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/shared-summary-block + +A DDS that does not generate ops but is part of summary. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Special DDS that participates in summaries but doesn't generate ops +- Has public, legacy, and internal entry points +- Useful for storing metadata or configuration diff --git a/packages/dds/task-manager/CLAUDE.md b/packages/dds/task-manager/CLAUDE.md new file mode 100644 index 000000000000..7ba3d9a7a90f --- /dev/null +++ b/packages/dds/task-manager/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluidframework/task-manager + +Distributed data structure for queueing exclusive tasks. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Dual ESM/CommonJS package +- Has public, legacy, and internal entry points +- Depends on `@fluidframework/container-runtime-definitions` +- Used for coordinating exclusive task execution across clients diff --git a/packages/dds/test-dds-utils/CLAUDE.md b/packages/dds/test-dds-utils/CLAUDE.md new file mode 100644 index 000000000000..153f63a4a82e --- /dev/null +++ b/packages/dds/test-dds-utils/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-private/test-dds-utils + +Fluid DDS test utilities - shared testing infrastructure for DDS packages. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests (ESM and CJS) +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:mocha:suite` - Run DDS suite cases + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports + +## Key Files + +- `src/` - Source code with test utilities +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Private package (`@fluid-private` scope) - internal use only +- Type validation is disabled +- Provides shared test infrastructure for DDS packages +- Depends on `@fluid-private/stochastic-test-utils` +- Tests run in both ESM and CJS modes diff --git a/packages/dds/tree/CLAUDE.md b/packages/dds/tree/CLAUDE.md new file mode 100644 index 000000000000..28d44b0730f6 --- /dev/null +++ b/packages/dds/tree/CLAUDE.md @@ -0,0 +1,53 @@ +# @fluidframework/tree + +Distributed tree - hierarchical data structure. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output only +- `pnpm build:test` - Build test files +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:mocha:prod` - Run tests in production mode +- `pnpm test:memory` - Run memory tests +- `pnpm test:stress` - Run stress/fuzz tests +- `pnpm test:customBenchmarks` - Run custom benchmarks +- `pnpm test:snapshots:regen` - Regenerate test snapshots + +## Benchmark + +- `pnpm bench` - Run benchmarks +- `pnpm bench:profile` - Run benchmarks with profiling +- `pnpm test:benchmark:report` - Generate benchmark report + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:exports` - Validate API exports +- `pnpm depcruise` - Check dependency graph +- `pnpm depcruise:regen-known-issues` - Regenerate known dependency issues + +## Key Files + +- `src/` - Source code +- `src/test/memory/` - Memory tests +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Most feature-rich DDS with alpha, beta, public, legacy, and internal entry points +- Uses `@sinclair/typebox` for schema validation +- Uses `@tylerbu/sorted-btree-es6` for efficient tree operations +- Depends on `@fluidframework/id-compressor` for ID management +- Has dependency cruiser configuration for architecture validation +- Extensive testing: memory, stress, fuzz, smoke, and benchmarks +- Build depends on id-compressor test build diff --git a/packages/drivers/debugger/CLAUDE.md b/packages/drivers/debugger/CLAUDE.md new file mode 100644 index 000000000000..a370ffa79757 --- /dev/null +++ b/packages/drivers/debugger/CLAUDE.md @@ -0,0 +1,27 @@ +# @fluidframework/debugger + +Fluid Debugger - a tool to play through history of a file. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/replay-driver` - For replaying document operations +- `@fluidframework/driver-definitions` - Core driver interfaces +- `jsonschema` - JSON schema validation + +## Notes + +- No test suite in this package +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/driver-base/CLAUDE.md b/packages/drivers/driver-base/CLAUDE.md new file mode 100644 index 000000000000..d742232a97c1 --- /dev/null +++ b/packages/drivers/driver-base/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluidframework/driver-base + +Shared driver code for Fluid driver implementations. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, ESM only by default) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/driver-definitions` - Core driver interfaces +- `@fluidframework/driver-utils` - Driver utilities +- `@fluidframework/telemetry-utils` - Telemetry support + +## Notes + +- Base class implementations for driver development +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/driver-web-cache/CLAUDE.md b/packages/drivers/driver-web-cache/CLAUDE.md new file mode 100644 index 000000000000..7823ea9fcadf --- /dev/null +++ b/packages/drivers/driver-web-cache/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluidframework/driver-web-cache + +Implementation of the driver caching API for a web browser. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (Jest) +- `pnpm test:jest` - Run Jest tests directly + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `idb` - IndexedDB wrapper for browser storage +- `@fluidframework/driver-definitions` - Core driver interfaces +- `@fluidframework/driver-utils` - Driver utilities + +## Notes + +- Uses IndexedDB for browser-based caching +- Tests use `fake-indexeddb` for mocking +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/file-driver/CLAUDE.md b/packages/drivers/file-driver/CLAUDE.md new file mode 100644 index 000000000000..73c5a9cabe82 --- /dev/null +++ b/packages/drivers/file-driver/CLAUDE.md @@ -0,0 +1,28 @@ +# @fluidframework/file-driver + +A driver that reads/writes from/to local file storage. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/replay-driver` - For replay functionality +- `@fluidframework/driver-definitions` - Core driver interfaces +- `@fluidframework/driver-utils` - Driver utilities + +## Notes + +- No test suite in this package +- Node.js only (file system operations) +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/local-driver/CLAUDE.md b/packages/drivers/local-driver/CLAUDE.md new file mode 100644 index 000000000000..9d021e6287f0 --- /dev/null +++ b/packages/drivers/local-driver/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/local-driver + +Fluid local driver for in-process testing and development. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, ESM only by default) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/server-local-server` - Local Fluid server +- `@fluidframework/routerlicious-driver` - Base routerlicious driver +- `@fluidframework/driver-base` - Shared driver code +- `jsrsasign` - JWT token generation + +## Notes + +- Uses in-memory local server for testing +- Depends on `@fluidframework/server-*` packages +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/odsp-driver-definitions/CLAUDE.md b/packages/drivers/odsp-driver-definitions/CLAUDE.md new file mode 100644 index 000000000000..75de2c5a4c7e --- /dev/null +++ b/packages/drivers/odsp-driver-definitions/CLAUDE.md @@ -0,0 +1,27 @@ +# @fluidframework/odsp-driver-definitions + +Type definitions and interfaces for SharePoint Online (SPO) and OneDrive Consumer (ODC) driver. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/driver-definitions` - Core driver interfaces + +## Notes + +- Definition-only package (no runtime code) +- No test suite in this package +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting +- Has known breaking type changes (see typeValidation in package.json) diff --git a/packages/drivers/odsp-driver/CLAUDE.md b/packages/drivers/odsp-driver/CLAUDE.md new file mode 100644 index 000000000000..04146f6243e3 --- /dev/null +++ b/packages/drivers/odsp-driver/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/odsp-driver + +Socket storage implementation for SharePoint Online (SPO) and OneDrive Consumer (ODC). + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, both CJS and ESM) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/odsp-driver-definitions` - ODSP-specific types +- `@fluidframework/odsp-doclib-utils` - ODSP document library utilities +- `@fluidframework/driver-base` - Shared driver code +- `socket.io-client` - WebSocket communication + +## Notes + +- Primary driver for Microsoft 365 integration +- Tests use Sinon for mocking +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/odsp-urlResolver/CLAUDE.md b/packages/drivers/odsp-urlResolver/CLAUDE.md new file mode 100644 index 000000000000..8801c0db7a3f --- /dev/null +++ b/packages/drivers/odsp-urlResolver/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluidframework/odsp-urlresolver + +URL Resolver for ODSP (OneDrive/SharePoint) URLs. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, ESM only by default) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/odsp-driver` - ODSP driver implementation +- `@fluidframework/odsp-driver-definitions` - ODSP-specific types +- `@fluidframework/driver-definitions` - Core driver interfaces + +## Notes + +- Resolves ODSP URLs to Fluid resolved URLs +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/replay-driver/CLAUDE.md b/packages/drivers/replay-driver/CLAUDE.md new file mode 100644 index 000000000000..0a05422199de --- /dev/null +++ b/packages/drivers/replay-driver/CLAUDE.md @@ -0,0 +1,29 @@ +# @fluidframework/replay-driver + +Document replay version of Socket.IO implementation for playing back Fluid document history. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/driver-definitions` - Core driver interfaces +- `@fluidframework/driver-utils` - Driver utilities +- `@fluidframework/telemetry-utils` - Telemetry support + +## Notes + +- No test suite in this package +- Used by debugger and file-driver packages +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting +- Dev dependency on `nock` for HTTP mocking diff --git a/packages/drivers/routerlicious-driver/CLAUDE.md b/packages/drivers/routerlicious-driver/CLAUDE.md new file mode 100644 index 000000000000..c21d1998b11c --- /dev/null +++ b/packages/drivers/routerlicious-driver/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluidframework/routerlicious-driver + +Socket.IO + Git implementation of Fluid service API for Routerlicious servers. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, CJS only due to ESM stubbing issues) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/driver-base` - Shared driver code +- `@fluidframework/server-services-client` - Routerlicious client utilities +- `socket.io-client` - WebSocket communication +- `cross-fetch` - HTTP requests + +## Notes + +- Primary driver for Routerlicious-based Fluid services +- ESM tests skipped due to stubbing issues (ADO #7404) +- Tests use Sinon and Nock for mocking +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/routerlicious-urlResolver/CLAUDE.md b/packages/drivers/routerlicious-urlResolver/CLAUDE.md new file mode 100644 index 000000000000..1dac3aa940b0 --- /dev/null +++ b/packages/drivers/routerlicious-urlResolver/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluidframework/routerlicious-urlresolver + +URL Resolver for Routerlicious URLs. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, both ESM and CJS) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/driver-definitions` - Core driver interfaces +- `nconf` - Configuration management + +## Notes + +- Resolves Routerlicious URLs to Fluid resolved URLs +- Uses nconf for environment-based configuration +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/drivers/tinylicious-driver/CLAUDE.md b/packages/drivers/tinylicious-driver/CLAUDE.md new file mode 100644 index 000000000000..98ac69e07515 --- /dev/null +++ b/packages/drivers/tinylicious-driver/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluidframework/tinylicious-driver + +Driver for Tinylicious, the lightweight local Fluid server for development. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, ESM only by default) +- `pnpm test:mocha:verbose` - Verbose test output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome + +## Key Dependencies + +- `@fluidframework/routerlicious-driver` - Base routerlicious driver +- `@fluidframework/driver-utils` - Driver utilities +- `jsrsasign` - JWT token generation + +## Exports + +- `.` - Main driver exports +- `./test-utils` - Test utility exports + +## Notes + +- Wraps routerlicious-driver for Tinylicious compatibility +- Ideal for local development and testing +- Dual ESM/CJS build output (lib/ and dist/) +- Uses Biome for formatting diff --git a/packages/framework/agent-scheduler/CLAUDE.md b/packages/framework/agent-scheduler/CLAUDE.md new file mode 100644 index 000000000000..f3cd0a2f4bca --- /dev/null +++ b/packages/framework/agent-scheduler/CLAUDE.md @@ -0,0 +1,31 @@ +# @fluidframework/agent-scheduler + +Built-in runtime object for distributing agents across instances of a container. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +This package has no test script configured. + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Supports both ESM and CommonJS exports +- Has multiple export entrypoints: `.` (public), `./legacy`, `./internal` +- Uses `@fluidframework/map` and `@fluidframework/register-collection` internally diff --git a/packages/framework/aqueduct/CLAUDE.md b/packages/framework/aqueduct/CLAUDE.md new file mode 100644 index 000000000000..2edde377677a --- /dev/null +++ b/packages/framework/aqueduct/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluidframework/aqueduct + +A set of implementations for Fluid Framework interfaces. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Supports both ESM and CommonJS exports +- Has multiple export entrypoints: `.` (public), `./legacy`, `./internal` +- Core framework package with many internal dependencies including container-runtime, datastore, and tree diff --git a/packages/framework/attributor/CLAUDE.md b/packages/framework/attributor/CLAUDE.md new file mode 100644 index 000000000000..eeb86b3886ba --- /dev/null +++ b/packages/framework/attributor/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-experimental/attributor + +Operation attributor - tracks attribution of operations to users/sessions. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Experimental package (note `@fluid-experimental` scope) +- Single export entrypoint (no public/legacy separation) +- Uses lz4js for compression +- Type validation is disabled diff --git a/packages/framework/client-logger/app-insights-logger/CLAUDE.md b/packages/framework/client-logger/app-insights-logger/CLAUDE.md new file mode 100644 index 000000000000..a967f190ebb7 --- /dev/null +++ b/packages/framework/client-logger/app-insights-logger/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluidframework/app-insights-logger + +Fluid logging client that sends telemetry events to Azure App Insights. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Integrates with `@microsoft/applicationinsights-web` +- Has multiple export entrypoints: `.` (public), `./beta`, `./internal` +- Browser-focused package with UMD bundle support diff --git a/packages/framework/client-logger/fluid-telemetry/CLAUDE.md b/packages/framework/client-logger/fluid-telemetry/CLAUDE.md new file mode 100644 index 000000000000..d3fbbc8f1d5e --- /dev/null +++ b/packages/framework/client-logger/fluid-telemetry/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/fluid-telemetry + +Customer-facing Fluid telemetry types and classes for producing and consuming telemetry. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run all tests (requires Tinylicious server) +- `pnpm test:mocha` - Run unit tests only +- `pnpm test:realsvc:tinylicious` - Run end-to-end tests with Tinylicious + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files (unit: `*.spec.js`, e2e: `*.spec.realsvc.js`) +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Tests require Tinylicious server running on port 7070 +- Has multiple export entrypoints: `.` (public), `./beta`, `./internal` +- Depends on `@fluidframework/fluid-static` and container loader +- Type validation is disabled diff --git a/packages/framework/data-object-base/CLAUDE.md b/packages/framework/data-object-base/CLAUDE.md new file mode 100644 index 000000000000..435fce8b43ad --- /dev/null +++ b/packages/framework/data-object-base/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-experimental/data-object-base + +Data object base for synchronously and lazily loaded object scenarios. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +This package has no test script configured. + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Experimental package (note `@fluid-experimental` scope) +- Single export entrypoint (no public/legacy separation) +- Builds base classes for data objects with container-runtime integration +- Type validation is disabled diff --git a/packages/framework/dds-interceptions/CLAUDE.md b/packages/framework/dds-interceptions/CLAUDE.md new file mode 100644 index 000000000000..1483d3c79d27 --- /dev/null +++ b/packages/framework/dds-interceptions/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-experimental/dds-interceptions + +Distributed Data Structures that support an interception callback. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Experimental package (note `@fluid-experimental` scope) +- Single export entrypoint (no public/legacy separation) +- Wraps `@fluidframework/map`, `@fluidframework/sequence`, and `@fluidframework/merge-tree` +- Type validation is disabled diff --git a/packages/framework/fluid-framework/CLAUDE.md b/packages/framework/fluid-framework/CLAUDE.md new file mode 100644 index 000000000000..88605bf583c7 --- /dev/null +++ b/packages/framework/fluid-framework/CLAUDE.md @@ -0,0 +1,33 @@ +# fluid-framework + +The main entry point into Fluid Framework public packages. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +This package has no test script configured. + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files (re-exports from other packages) +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- This is the primary public API package for Fluid Framework +- Has multiple export entrypoints: `.` (public), `./alpha`, `./beta`, `./legacy` +- Re-exports from: container-definitions, container-loader, core-interfaces, fluid-static, map, sequence, tree, and more +- No direct implementation - primarily aggregates and re-exports +- Type validation is disabled diff --git a/packages/framework/fluid-static/CLAUDE.md b/packages/framework/fluid-static/CLAUDE.md new file mode 100644 index 000000000000..2b800b16ebbc --- /dev/null +++ b/packages/framework/fluid-static/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/fluid-static + +A tool to enable consumption of Fluid Data Objects without requiring custom container code. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Simplifies Fluid container setup for common use cases +- Has multiple export entrypoints: `.` (public), `./legacy`, `./internal` +- Depends on aqueduct, container-loader, container-runtime, and tree +- Used by `fluid-framework` as a dependency diff --git a/packages/framework/oldest-client-observer/CLAUDE.md b/packages/framework/oldest-client-observer/CLAUDE.md new file mode 100644 index 000000000000..2b56f909b054 --- /dev/null +++ b/packages/framework/oldest-client-observer/CLAUDE.md @@ -0,0 +1,32 @@ +# @fluid-experimental/oldest-client-observer + +Data object to determine if the local client is the oldest amongst connected clients. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +This package has no test script configured. + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Experimental package (note `@fluid-experimental` scope) +- Has multiple export entrypoints: `.` (public), `./legacy`, `./internal` +- Useful for leader election scenarios in distributed systems +- Type validation is disabled diff --git a/packages/framework/presence/CLAUDE.md b/packages/framework/presence/CLAUDE.md new file mode 100644 index 000000000000..d24a165748b6 --- /dev/null +++ b/packages/framework/presence/CLAUDE.md @@ -0,0 +1,39 @@ +# @fluidframework/presence + +A component for lightweight data sharing within a single session. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm build:esnext` - Build ESM (runs main + experimental builds) +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha, both ESM and CJS) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output +- `tsconfig.main.json` - Main build config +- `tsconfig.json` - Experimental build config (extends main) + +## Notes + +- Has specialized build: `build:esnext:main` then `build:esnext:experimental` +- Export entrypoints: `./beta`, `./alpha`, `./legacy/alpha` (no default `.` export) +- Uses `@fluidframework/id-compressor` for client identification +- Integrates with fluid-static for session awareness +- Type validation is disabled diff --git a/packages/framework/react/CLAUDE.md b/packages/framework/react/CLAUDE.md new file mode 100644 index 000000000000..6a97961e1963 --- /dev/null +++ b/packages/framework/react/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluidframework/react + +Utilities for integrating content powered by the Fluid Framework into React applications. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has multiple export entrypoints: `.` (public), `./alpha`, `./beta`, `./internal` +- Peer dependency on React 18.x +- Uses `@testing-library/react` and `global-jsdom` for testing +- Integrates with `@fluidframework/tree` for reactive tree bindings +- Type validation is disabled diff --git a/packages/framework/request-handler/CLAUDE.md b/packages/framework/request-handler/CLAUDE.md new file mode 100644 index 000000000000..666db92956fe --- /dev/null +++ b/packages/framework/request-handler/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluidframework/request-handler + +A simple request handling library for Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has multiple export entrypoints: `.` (public), `./legacy`, `./internal` +- Core infrastructure package for request routing in containers +- Depends on container-runtime-definitions and runtime-utils diff --git a/packages/framework/synthesize/CLAUDE.md b/packages/framework/synthesize/CLAUDE.md new file mode 100644 index 000000000000..3bdedc33e6d0 --- /dev/null +++ b/packages/framework/synthesize/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluidframework/synthesize + +A library for synthesizing scope objects. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has multiple export entrypoints: `.` (public), `./legacy`, `./internal` +- Minimal dependencies (only `@fluidframework/core-utils`) +- Used for dependency injection patterns in Fluid diff --git a/packages/framework/tree-agent-langchain/CLAUDE.md b/packages/framework/tree-agent-langchain/CLAUDE.md new file mode 100644 index 000000000000..2f71fee961a4 --- /dev/null +++ b/packages/framework/tree-agent-langchain/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluidframework/tree-agent-langchain + +LangChain integration helpers for @fluidframework/tree-agent. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has multiple export entrypoints: `.` (public), `./alpha`, `./internal` +- Extends `@fluidframework/tree-agent` with LangChain support +- Dependencies: `@langchain/core`, `zod` +- Dev dependencies include LangChain providers (Anthropic, OpenAI, Google) +- Type validation is disabled diff --git a/packages/framework/tree-agent-ses/CLAUDE.md b/packages/framework/tree-agent-ses/CLAUDE.md new file mode 100644 index 000000000000..ebae0c354654 --- /dev/null +++ b/packages/framework/tree-agent-ses/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/tree-agent-ses + +SES (Secure ECMAScript) integration helpers for @fluidframework/tree-agent. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has multiple export entrypoints: `.` (public), `./alpha`, `./internal` +- Provides sandboxed execution for AI-generated code via SES +- Dependencies: `@fluidframework/tree-agent`, `ses` (Secure ECMAScript) +- Type validation is disabled diff --git a/packages/framework/tree-agent/CLAUDE.md b/packages/framework/tree-agent/CLAUDE.md new file mode 100644 index 000000000000..1896edd635d4 --- /dev/null +++ b/packages/framework/tree-agent/CLAUDE.md @@ -0,0 +1,37 @@ +# @fluidframework/tree-agent + +Experimental package to simplify integrating AI into Fluid-based applications. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has multiple export entrypoints: `.` (public), `./alpha`, `./internal` +- Core AI integration package for Fluid Framework +- Dependencies: `@anthropic-ai/sdk`, `zod` for schema validation +- Dev dependencies include LangChain providers (Anthropic, OpenAI, Google) and SES for sandboxing +- Integrates with `@fluidframework/tree` for collaborative AI-powered data structures +- Type validation is disabled diff --git a/packages/framework/undo-redo/CLAUDE.md b/packages/framework/undo-redo/CLAUDE.md new file mode 100644 index 000000000000..30a7818fe4f3 --- /dev/null +++ b/packages/framework/undo-redo/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluidframework/undo-redo + +Undo/Redo functionality for Fluid Framework data structures. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:compile` - Compile only +- `pnpm clean` - Clean build artifacts + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source TypeScript files +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## Notes + +- Has export entrypoints: `.` (public), `./internal` +- Supports undo/redo for: `@fluidframework/map`, `@fluidframework/matrix`, `@fluidframework/sequence` +- Uses `@fluidframework/merge-tree` for sequence operations diff --git a/packages/loader/container-loader/CLAUDE.md b/packages/loader/container-loader/CLAUDE.md new file mode 100644 index 000000000000..67be7460b7e6 --- /dev/null +++ b/packages/loader/container-loader/CLAUDE.md @@ -0,0 +1,39 @@ +# @fluidframework/container-loader + +Fluid container loader - Core package for loading and managing Fluid containers. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:compile` - Compile without API reports +- `pnpm build:test` - Build test files + +## Test + +- `pnpm test` - Run all tests (mocha) +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/loader.ts` - Main Loader class for creating/loading containers +- `src/container.ts` - Container implementation +- `src/deltaManager.ts` - Manages delta/op synchronization +- `src/connectionManager.ts` - Handles WebSocket connections to Fluid services +- `src/protocol.ts` - Protocol handling for Fluid operations +- `src/quorum.ts` - Quorum management for consensus + +## Notes + +- Dual-build package (ESM in `lib/`, CommonJS in `dist/`) +- Has internal test exports under `./internal/test/*` paths +- Uses mocha for testing with sinon for mocks +- Key dependencies: driver-definitions, driver-utils, telemetry-utils diff --git a/packages/loader/driver-utils/CLAUDE.md b/packages/loader/driver-utils/CLAUDE.md new file mode 100644 index 000000000000..3278ee49d2bd --- /dev/null +++ b/packages/loader/driver-utils/CLAUDE.md @@ -0,0 +1,40 @@ +# @fluidframework/driver-utils + +Collection of utility functions for Fluid drivers. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:compile` - Compile without API reports +- `pnpm build:test` - Build test files + +## Test + +- `pnpm test` - Run all tests (mocha) +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:coverage` - Run tests with coverage (c8) + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/adapters/` - Service adapters including compression support +- `src/documentServiceProxy.ts` - Proxy for document service +- `src/documentStorageServiceProxy.ts` - Proxy for storage service +- `src/runWithRetry.ts` - Retry logic for operations +- `src/networkUtils.ts` - Network utilities +- `src/treeConversions.ts` - Tree structure conversions +- `src/buildSnapshotTree.ts` - Snapshot tree building +- `src/insecureUrlResolver.ts` - URL resolver for testing + +## Notes + +- Dual-build package (ESM in `lib/`, CommonJS in `dist/`) +- Provides compression adapters via `src/adapters/compression/` +- Uses axios for HTTP requests and lz4js for compression +- Key dependencies: driver-definitions, telemetry-utils diff --git a/packages/loader/test-loader-utils/CLAUDE.md b/packages/loader/test-loader-utils/CLAUDE.md new file mode 100644 index 000000000000..32a37ac5d144 --- /dev/null +++ b/packages/loader/test-loader-utils/CLAUDE.md @@ -0,0 +1,28 @@ +# @fluid-private/test-loader-utils + +Mocks and other test utilities for the Fluid Framework Loader. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:compile` - Compile without API reports + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/mockDocumentService.ts` - Mock document service for testing +- `src/mockDocumentDeltaConnection.ts` - Mock delta connection +- `src/mockDeltaStorage.ts` - Mock delta storage + +## Notes + +- Private package (`@fluid-private/`) - not published to npm +- No test suite in this package (it provides test utilities for other packages) +- Type validation is disabled for this package +- Used by `container-loader` and other packages for testing diff --git a/packages/runtime/container-runtime-definitions/CLAUDE.md b/packages/runtime/container-runtime-definitions/CLAUDE.md new file mode 100644 index 000000000000..60248986519b --- /dev/null +++ b/packages/runtime/container-runtime-definitions/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluidframework/container-runtime-definitions + +Fluid Runtime definitions - TypeScript interfaces and types for container runtime. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm clean` - Clean build outputs + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code (interfaces and types only) +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./internal` - Internal API (full exports) + +## Notes + +- Types-only package (no runtime JavaScript) +- Defines interfaces consumed by container-runtime and other packages +- Dependencies: container-definitions, core-interfaces, driver-definitions, runtime-definitions diff --git a/packages/runtime/container-runtime/CLAUDE.md b/packages/runtime/container-runtime/CLAUDE.md new file mode 100644 index 000000000000..fa387074b2fb --- /dev/null +++ b/packages/runtime/container-runtime/CLAUDE.md @@ -0,0 +1,44 @@ +# @fluidframework/container-runtime + +Fluid container runtime - the core runtime implementation for Fluid containers. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests (Mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:benchmark:report` - Run performance benchmarks + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./internal` - Internal API (full exports) +- `./internal/test/*` - Test-only exports for containerRuntime, deltaScheduler, blobManager, summary, gc + +## Notes + +- Dual ESM/CJS package with separate build outputs +- Uses `fluid-build` for build orchestration +- Has benchmark tests for performance monitoring +- Key dependencies: datastore, id-compressor, runtime-utils, driver-utils diff --git a/packages/runtime/datastore-definitions/CLAUDE.md b/packages/runtime/datastore-definitions/CLAUDE.md new file mode 100644 index 000000000000..440b01adaf74 --- /dev/null +++ b/packages/runtime/datastore-definitions/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluidframework/datastore-definitions + +Fluid data store definitions - TypeScript interfaces and types for data stores. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm clean` - Clean build outputs + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code (interfaces and types only) +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./legacy/alpha` - Legacy alpha API +- `./internal` - Internal API (full exports) + +## Notes + +- Types-only package (no runtime JavaScript) +- Defines interfaces consumed by datastore and other packages +- Has alpha API exports via `./legacy/alpha` entrypoint +- Dependencies: container-definitions, core-interfaces, driver-definitions, id-compressor, runtime-definitions diff --git a/packages/runtime/datastore/CLAUDE.md b/packages/runtime/datastore/CLAUDE.md new file mode 100644 index 000000000000..f5bc321a696f --- /dev/null +++ b/packages/runtime/datastore/CLAUDE.md @@ -0,0 +1,41 @@ +# @fluidframework/datastore + +Fluid data store implementation - runtime implementation for data stores within containers. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests (Mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./internal` - Internal API (full exports) + +## Notes + +- Dual ESM/CJS package with separate build outputs +- Uses `fluid-build` for build orchestration +- Key dependencies: datastore-definitions, id-compressor, runtime-utils, driver-utils diff --git a/packages/runtime/id-compressor/CLAUDE.md b/packages/runtime/id-compressor/CLAUDE.md new file mode 100644 index 000000000000..0ab9f738a8fb --- /dev/null +++ b/packages/runtime/id-compressor/CLAUDE.md @@ -0,0 +1,45 @@ +# @fluidframework/id-compressor + +ID compressor - efficient ID generation and compression for Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests (Mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:benchmark:report` - Run performance benchmarks +- `pnpm test:snapshots:regen` - Regenerate test snapshots + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./internal` - Internal API (full exports) +- `./internal/test-utils` - Test utilities (restricted export) + +## Notes + +- Dual ESM/CJS package with separate build outputs +- Has benchmark tests for performance monitoring +- Uses snapshot testing - regenerate with `test:snapshots:regen` +- Key dependencies: core-utils, telemetry-utils, sorted-btree-es6, uuid diff --git a/packages/runtime/runtime-definitions/CLAUDE.md b/packages/runtime/runtime-definitions/CLAUDE.md new file mode 100644 index 000000000000..90d47690f9b7 --- /dev/null +++ b/packages/runtime/runtime-definitions/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluidframework/runtime-definitions + +Fluid Runtime definitions - core TypeScript interfaces and types for the runtime layer. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm clean` - Clean build outputs + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code (interfaces and types) +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./legacy/alpha` - Legacy alpha API +- `./internal` - Internal API (full exports) + +## Notes + +- Foundational definitions package used by most runtime packages +- Has alpha API exports via `./legacy/alpha` entrypoint +- Dependencies: container-definitions, core-interfaces, driver-definitions, id-compressor, telemetry-utils diff --git a/packages/runtime/runtime-utils/CLAUDE.md b/packages/runtime/runtime-utils/CLAUDE.md new file mode 100644 index 000000000000..75df51b15074 --- /dev/null +++ b/packages/runtime/runtime-utils/CLAUDE.md @@ -0,0 +1,43 @@ +# @fluidframework/runtime-utils + +Collection of utility functions for Fluid Runtime. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests (Mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./legacy/alpha` - Legacy alpha API +- `./internal` - Internal API (full exports) + +## Notes + +- Dual ESM/CJS package with separate build outputs +- Has alpha API exports via `./legacy/alpha` entrypoint +- Shared utilities used by container-runtime, datastore, and other runtime packages +- Dependencies: container-definitions, container-runtime-definitions, datastore-definitions, runtime-definitions diff --git a/packages/runtime/test-runtime-utils/CLAUDE.md b/packages/runtime/test-runtime-utils/CLAUDE.md new file mode 100644 index 000000000000..08a34bc1e95d --- /dev/null +++ b/packages/runtime/test-runtime-utils/CLAUDE.md @@ -0,0 +1,41 @@ +# @fluidframework/test-runtime-utils + +Fluid runtime test utilities - mock implementations and helpers for testing Fluid applications. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM only +- `pnpm clean` - Clean build outputs + +## Test + +- `pnpm test` - Run all tests (Mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/` - Source code (mock implementations, test helpers) +- `src/test/` - Test files +- `lib/` - ESM build output +- `dist/` - CommonJS build output + +## API Exports + +- `.` - Public API (`lib/public.d.ts`) +- `./legacy` - Legacy API with beta exports +- `./internal` - Internal API (full exports) + +## Notes + +- Test-only package - provides mocks for runtime interfaces +- Used as devDependency by other packages for unit testing +- Includes mock implementations for data stores, delta connections, and runtime components +- Dependencies include routerlicious-driver and jsrsasign for token generation diff --git a/packages/service-clients/azure-client/CLAUDE.md b/packages/service-clients/azure-client/CLAUDE.md new file mode 100644 index 000000000000..f5b3d7a47448 --- /dev/null +++ b/packages/service-clients/azure-client/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluidframework/azure-client + +A tool to enable creation and loading of Fluid containers using the Azure Fluid Relay service. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:test` - Build tests + +## Test + +- `pnpm test` - Run tests against Tinylicious (starts server automatically on port 7070) +- `pnpm test:realsvc:local:run` - Run tests directly (requires Tinylicious already running) + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/` - Source code +- `lib/` - ESM output +- `dist/` - CommonJS output +- Exports: `.` (public), `./legacy`, `./internal` + +## Notes + +- Tests require Tinylicious running on port 7070 +- Uses `@fluidframework/azure-local-service` for local testing +- Dual ESM/CommonJS package with multiple export paths diff --git a/packages/service-clients/end-to-end-tests/azure-client/CLAUDE.md b/packages/service-clients/end-to-end-tests/azure-client/CLAUDE.md new file mode 100644 index 000000000000..7fdc66ef31dd --- /dev/null +++ b/packages/service-clients/end-to-end-tests/azure-client/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluidframework/azure-end-to-end-tests + +End-to-end tests for Azure client. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:test` - Build tests only + +## Test + +- `pnpm test` - Run tests against Tinylicious (starts server automatically on port 7071) +- `pnpm test:realsvc:azure` - Run tests against Azure Fluid Relay service +- `pnpm test:realsvc:tinylicious:run` - Run tests directly (requires Tinylicious already running) +- `pnpm test:coverage` - Run tests with coverage (c8) + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/test/` - Test source files +- `.mocharc.cjs` - Mocha configuration + +## Notes + +- Tests run on port 7071 (different from main azure-client tests on 7070) +- Set `FLUID_CLIENT=azure` to test against real Azure service +- Supports verbose logging with `FLUID_TEST_VERBOSE=msgs` or `FLUID_TEST_VERBOSE=msgs+telem` +- Tests cross-version compatibility with `@fluidframework/azure-client-legacy` (v1.2.0) diff --git a/packages/service-clients/end-to-end-tests/odsp-client/CLAUDE.md b/packages/service-clients/end-to-end-tests/odsp-client/CLAUDE.md new file mode 100644 index 000000000000..a9f5ab26630e --- /dev/null +++ b/packages/service-clients/end-to-end-tests/odsp-client/CLAUDE.md @@ -0,0 +1,31 @@ +# @fluid-experimental/odsp-end-to-end-tests + +End-to-end tests for ODSP (OneDrive/SharePoint) client. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:test` - Build tests only + +## Test + +- `pnpm test` - Run tests against ODSP service +- `pnpm test:realsvc:odsp` - Run tests against ODSP (same as `test`) +- `pnpm test:coverage` - Run tests with coverage (c8) + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/test/` - Test source files +- `.mocharc.cjs` - Mocha configuration + +## Notes + +- Requires ODSP credentials/configuration to run tests +- Set `FLUID_TEST_VERBOSE=1` for verbose logging +- Tests use `@fluidframework/odsp-doclib-utils` for ODSP authentication utilities diff --git a/packages/service-clients/odsp-client/CLAUDE.md b/packages/service-clients/odsp-client/CLAUDE.md new file mode 100644 index 000000000000..8c65b32d2f1c --- /dev/null +++ b/packages/service-clients/odsp-client/CLAUDE.md @@ -0,0 +1,33 @@ +# @fluidframework/odsp-client + +A tool to enable creation and loading of Fluid containers using the ODSP (OneDrive/SharePoint) service. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:test` - Build tests + +## Test + +- `pnpm test` - Run unit tests with Mocha (ESM) +- `pnpm test:mocha:cjs` - Run tests in CommonJS mode + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/` - Source code +- `lib/` - ESM output +- `dist/` - CommonJS output +- Exports: `.` (public), `./beta`, `./internal` + +## Notes + +- Dual ESM/CommonJS package with multiple export paths +- Uses `@fluidframework/odsp-driver` and `@fluidframework/odsp-doclib-utils` for ODSP connectivity +- Type validation is disabled for this package diff --git a/packages/service-clients/tinylicious-client/CLAUDE.md b/packages/service-clients/tinylicious-client/CLAUDE.md new file mode 100644 index 000000000000..91facfac0262 --- /dev/null +++ b/packages/service-clients/tinylicious-client/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluidframework/tinylicious-client + +A tool to enable creation and loading of Fluid containers using the Tinylicious service. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:test` - Build tests + +## Test + +- `pnpm test` - Run tests against Tinylicious (starts server automatically on port 7070) +- `pnpm test:realsvc:tinylicious:run` - Run tests directly (requires Tinylicious already running) + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm format` - Format with Biome + +## Key Files + +- `src/` - Source code +- `lib/` - ESM output +- `dist/` - CommonJS output +- Exports: `.` (public), `./beta`, `./internal` + +## Notes + +- Tinylicious is a lightweight local Fluid service for development/testing +- Tests require Tinylicious running on port 7070 +- Dual ESM/CommonJS package with multiple export paths +- Uses `@fluidframework/tinylicious-driver` for service connectivity diff --git a/packages/test/functional-tests/CLAUDE.md b/packages/test/functional-tests/CLAUDE.md new file mode 100644 index 000000000000..eced4c3ba539 --- /dev/null +++ b/packages/test/functional-tests/CLAUDE.md @@ -0,0 +1,30 @@ +# @fluid-internal/functional-tests + +Functional tests for Fluid Framework DDS and container components. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output with TypeScript +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run all tests (ESM) +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:mocha:cjs` - Run CJS tests only +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:coverage` - Run tests with coverage + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Notes + +- Private package (not published) +- Tests Fluid DDS types including SharedTree, SharedMap, SharedMatrix, SharedSequence +- Uses Mocha test framework with c8 for coverage +- Module type: ESM diff --git a/packages/test/local-server-stress-tests/CLAUDE.md b/packages/test/local-server-stress-tests/CLAUDE.md new file mode 100644 index 000000000000..e0e6824f85c2 --- /dev/null +++ b/packages/test/local-server-stress-tests/CLAUDE.md @@ -0,0 +1,29 @@ +# @fluid-internal/local-server-stress-tests + +Stress tests that can only run against the local server. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:test` - Build test files only + +## Test + +- `pnpm test` - Run stress tests +- `pnpm test:mocha` - Run mocha tests from `lib/test/**/*.spec.*js` +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:coverage` - Run tests with coverage + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Notes + +- Private package (not published) +- Module type: CommonJS +- Uses `@fluidframework/server-local-server` for local testing +- Tests DDS stress scenarios including SharedTree, SharedMap, SharedMatrix, SharedSequence +- Uses stochastic test utilities from `@fluid-private/stochastic-test-utils` diff --git a/packages/test/local-server-tests/CLAUDE.md b/packages/test/local-server-tests/CLAUDE.md new file mode 100644 index 000000000000..7a8c305dbde0 --- /dev/null +++ b/packages/test/local-server-tests/CLAUDE.md @@ -0,0 +1,29 @@ +# @fluid-internal/local-server-tests + +Tests that can only run against the local server. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:test` - Build test files from `src/test/tsconfig.json` + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:mocha` - Run mocha tests from `lib/test/**/*.spec.*js` +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:coverage` - Run tests with coverage + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Notes + +- Private package (not published) +- Module type: CommonJS +- Uses `@fluidframework/server-local-server` for local testing +- Uses `@fluid-private/test-pairwise-generator` for test case generation +- Uses sinon for mocking diff --git a/packages/test/mocha-test-setup/CLAUDE.md b/packages/test/mocha-test-setup/CLAUDE.md new file mode 100644 index 000000000000..5b76f1db0580 --- /dev/null +++ b/packages/test/mocha-test-setup/CLAUDE.md @@ -0,0 +1,29 @@ +# @fluid-internal/mocha-test-setup + +Utilities for Fluid tests - provides common Mocha test configuration and setup. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output +- `pnpm build:docs` - Generate API documentation + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Exports + +- `.` - Main entry point (ESM and CJS) +- `./mocharc-common` - Common Mocha configuration (CJS only) + +## Notes + +- Published package with dual ESM/CJS support +- Provides source-map-support integration +- Depends on `@fluid-internal/test-driver-definitions` +- Used as a dev dependency by other test packages diff --git a/packages/test/snapshots/CLAUDE.md b/packages/test/snapshots/CLAUDE.md new file mode 100644 index 000000000000..635a058ac8cb --- /dev/null +++ b/packages/test/snapshots/CLAUDE.md @@ -0,0 +1,34 @@ +# @fluid-internal/test-snapshots + +Comprehensive test of snapshot logic for Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:test` - Build test files (ESM and CJS) +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run all tests (ESM by default) +- `pnpm test:mocha:esm` - Run ESM tests +- `pnpm test:mocha:cjs` - Run CJS tests +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:coverage` - Run tests with coverage +- `pnpm test:new` - Generate new snapshots +- `pnpm test:update` - Update existing snapshots + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Notes + +- Private package (not published) +- Module type: ESM +- Uses `@fluid-internal/replay-tool` for snapshot replay +- Tests snapshot logic for various DDS types (Cell, Counter, Map, Matrix, Sequence, etc.) +- Uses file-driver and replay-driver for snapshot testing diff --git a/packages/test/stochastic-test-utils/CLAUDE.md b/packages/test/stochastic-test-utils/CLAUDE.md new file mode 100644 index 000000000000..f0bb7d8e7a8a --- /dev/null +++ b/packages/test/stochastic-test-utils/CLAUDE.md @@ -0,0 +1,39 @@ +# @fluid-private/stochastic-test-utils + +Utilities for stochastic (randomized) tests in Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:test` - Build test files (ESM and CJS) +- `pnpm tsc` - Build CommonJS output +- `pnpm build:docs` - Generate API documentation + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:mocha:esm` - Run ESM tests +- `pnpm test:mocha:cjs` - Run CJS tests +- `pnpm test:mocha:verbose` - Run tests with verbose output +- `pnpm test:coverage` - Run tests with coverage +- `pnpm bench` - Run benchmarks + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Exports + +- `.` - Main entry point (ESM and CJS) +- `./internal/test/utils` - Internal test utilities + +## Notes + +- Published package with dual ESM/CJS support +- Uses `best-random` for random number generation +- Provides utilities for creating reproducible randomized tests +- Key dependency: `@fluidframework/core-utils` diff --git a/packages/test/test-driver-definitions/CLAUDE.md b/packages/test/test-driver-definitions/CLAUDE.md new file mode 100644 index 000000000000..7d10af34295d --- /dev/null +++ b/packages/test/test-driver-definitions/CLAUDE.md @@ -0,0 +1,27 @@ +# @fluid-internal/test-driver-definitions + +A driver abstraction and interface definitions for testing against Fluid servers. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output +- `pnpm build:docs` - Generate API documentation + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Notes + +- Published package with dual ESM/CJS support +- Types-only package (no runtime code, main is empty) +- Defines interfaces for test drivers +- Key dependencies: + - `@fluidframework/core-interfaces` + - `@fluidframework/driver-definitions` +- Used by `@fluid-private/test-drivers` for implementations diff --git a/packages/test/test-drivers/CLAUDE.md b/packages/test/test-drivers/CLAUDE.md new file mode 100644 index 000000000000..0832363300b9 --- /dev/null +++ b/packages/test/test-drivers/CLAUDE.md @@ -0,0 +1,28 @@ +# @fluid-private/test-drivers + +A driver abstraction and implementations for testing against various Fluid servers. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output +- `pnpm build:docs` - Generate API documentation + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Notes + +- Published package with dual ESM/CJS support +- Implements test drivers for multiple backends: + - Local server (`@fluidframework/local-driver`) + - Tinylicious (`@fluidframework/tinylicious-driver`) + - Routerlicious (`@fluidframework/routerlicious-driver`) + - ODSP (`@fluidframework/odsp-driver`) +- Depends on `@fluid-internal/test-driver-definitions` for interfaces +- Uses `@fluid-private/test-pairwise-generator` for test configuration diff --git a/packages/test/test-end-to-end-tests/CLAUDE.md b/packages/test/test-end-to-end-tests/CLAUDE.md new file mode 100644 index 000000000000..0278db02eed4 --- /dev/null +++ b/packages/test/test-end-to-end-tests/CLAUDE.md @@ -0,0 +1,40 @@ +# @fluid-private/test-end-to-end-tests + +End-to-end tests for Fluid Framework against real services. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:test` - Build test files (ESM) + +## Test + +- `pnpm test` - Run all tests (local + tinylicious) +- `pnpm test:realsvc:local` - Run tests against local server +- `pnpm test:realsvc:tinylicious` - Run tests against Tinylicious +- `pnpm test:realsvc:frs` - Run tests against FRS (Fluid Relay Service) +- `pnpm test:realsvc:odsp` - Run tests against OneDrive/SharePoint +- `pnpm test:realsvc:r11s` - Run tests against Routerlicious +- `pnpm test:realsvc:verbose` - Run tests with verbose output + +## Benchmarks + +- `pnpm test:benchmark:report` - Run time benchmarks (local) +- `pnpm test:benchmark:report:frs` - Run time benchmarks (FRS) +- `pnpm test:benchmark:report:odsp` - Run time benchmarks (ODSP) +- `pnpm test:memory-profiling:report` - Run memory benchmarks (local) + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Notes + +- Private package (not published) +- Module type: ESM +- Tests run against multiple service backends via test drivers +- Uses `start-server-and-test` to manage Tinylicious lifecycle +- Supports backward compatibility testing via `fluid__test__backCompat` env var +- Benchmark configs in `src/test/benchmark/` diff --git a/packages/test/test-pairwise-generator/CLAUDE.md b/packages/test/test-pairwise-generator/CLAUDE.md new file mode 100644 index 000000000000..2543856afa8b --- /dev/null +++ b/packages/test/test-pairwise-generator/CLAUDE.md @@ -0,0 +1,31 @@ +# @fluid-private/test-pairwise-generator + +Pairwise test case generator for Fluid Framework tests. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output +- `pnpm build:docs` - Generate API documentation + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:mocha:esm` - Run ESM tests +- `pnpm test:mocha:cjs` - Run CJS tests +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Notes + +- Published package with dual ESM/CJS support +- Uses `random-js` for randomization +- Generates pairwise combinations to reduce test matrix size while maintaining coverage +- Used by test packages to generate configuration combinations diff --git a/packages/test/test-service-load/CLAUDE.md b/packages/test/test-service-load/CLAUDE.md new file mode 100644 index 000000000000..9c9c1844bd98 --- /dev/null +++ b/packages/test/test-service-load/CLAUDE.md @@ -0,0 +1,42 @@ +# @fluid-internal/test-service-load + +Service load tests for Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:test` - Build test files (ESM and CJS) +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run stress tests (Tinylicious) +- `pnpm test:stress` - Run stress tests with Tinylicious +- `pnpm test:stress:run` - Run stress tests directly via Mocha + +## Run Load Tests + +- `pnpm start` - Start load test runner +- `pnpm start:mini` - Start with mini profile +- `pnpm start:t9s` - Start against Tinylicious +- `pnpm start:frs` - Start against FRS +- `pnpm start:odsp` - Start against ODSP +- `pnpm full` - Run full load test profile +- `pnpm debug` - Run with Node.js debugger attached +- `pnpm debug:runner` - Run debug profile + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome + +## Notes + +- Private package (not published) +- Module type: ESM +- Uses Commander for CLI argument parsing +- Profiles configured for different load scenarios (mini, full, ci_frs, debug) +- Uses `@fluid-private/stochastic-test-utils` for randomized operations +- Supports browser authentication via `--browserAuth` flag diff --git a/packages/test/test-utils/CLAUDE.md b/packages/test/test-utils/CLAUDE.md new file mode 100644 index 000000000000..a1a5d88354d4 --- /dev/null +++ b/packages/test/test-utils/CLAUDE.md @@ -0,0 +1,41 @@ +# @fluidframework/test-utils + +Utilities for Fluid Framework tests - core test infrastructure. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:test` - Build test files (ESM and CJS) +- `pnpm tsc` - Build CommonJS output +- `pnpm build:docs` - Generate API documentation +- `pnpm api` - Run API tasks + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:mocha:esm` - Run ESM tests +- `pnpm test:mocha:cjs` - Run CJS tests +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Exports + +- `.` - Public API (default) +- `./legacy` - Legacy API (beta exports) +- `./internal` - Internal API (full exports) + +## Notes + +- Published package with dual ESM/CJS support +- Core test infrastructure used by most Fluid test packages +- Provides test container creation, driver utilities, and test helpers +- Uses `best-random` for deterministic test randomization +- Supports multiple driver backends (local, ODSP, Routerlicious) +- Type validation enabled with `legacy` entrypoint diff --git a/packages/test/test-version-utils/CLAUDE.md b/packages/test/test-version-utils/CLAUDE.md new file mode 100644 index 000000000000..e284e308a061 --- /dev/null +++ b/packages/test/test-version-utils/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-private/test-version-utils + +Utilities for version compatibility testing in Fluid Framework. + +## Build + +- `pnpm build` - Build the package +- `pnpm build:esnext` - Build ESM output +- `pnpm build:test` - Build test files (ESM) +- `pnpm build:docs` - Generate API documentation + +## Test + +- `pnpm test` - Run all tests +- `pnpm test:mocha` - Run tests with 10s timeout +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Fix linting issues +- `pnpm format` - Format code with Biome +- `pnpm check:are-the-types-wrong` - Verify type exports + +## Exports + +- `.` - Main entry point (ESM only) +- `./mocharc-common` - Common Mocha configuration (CJS) + +## Notes + +- Published package (ESM only, no CJS) +- Provides utilities for testing version compatibility across Fluid releases +- Uses `semver` for version parsing and comparison +- Uses `proper-lockfile` for file locking during package installation +- Uses `nconf` for configuration management +- Key dependency: `@fluid-tools/version-tools` +- Caches legacy package versions in `node_modules/.legacy` diff --git a/packages/test/types_jest-environment-puppeteer/CLAUDE.md b/packages/test/types_jest-environment-puppeteer/CLAUDE.md new file mode 100644 index 000000000000..d6a0bcafce9e --- /dev/null +++ b/packages/test/types_jest-environment-puppeteer/CLAUDE.md @@ -0,0 +1,23 @@ +# @types/jest-environment-puppeteer + +TypeScript `globals` definitions fix-up for jest-environment-puppeteer. + +## Build + +- `pnpm build` - Build the package (no-op, types only) + +## Lint + +- `pnpm format` - Format code with Biome +- `pnpm check:format` - Check formatting with Biome + +## Key Files + +- `index.d.ts` - Type definitions + +## Notes + +- Private package (not published) +- Types-only package providing TypeScript definitions +- Fixes global type definitions for jest-environment-puppeteer +- No runtime code, no tests diff --git a/packages/tools/changelog-generator-wrapper/CLAUDE.md b/packages/tools/changelog-generator-wrapper/CLAUDE.md new file mode 100644 index 000000000000..0e017249ce97 --- /dev/null +++ b/packages/tools/changelog-generator-wrapper/CLAUDE.md @@ -0,0 +1,24 @@ +# @fluid-private/changelog-generator-wrapper + +Wrapper for changelog generation using changesets. + +## Build + +- `pnpm build` - Build and lint (no TypeScript compilation required) +- `pnpm lint` - Run ESLint + +## Lint/Format + +- `pnpm format` - Format code with Biome +- `pnpm eslint:fix` - Fix ESLint issues + +## Key Dependencies + +- `@changesets/cli` - Changelog generation +- `changesets-format-with-issue-links` - Formatting with issue links + +## Notes + +- Private package (not published) +- No TypeScript compilation needed (`tsc` script is a no-op) +- CommonJS module type diff --git a/packages/tools/devtools/devtools-browser-extension/CLAUDE.md b/packages/tools/devtools/devtools-browser-extension/CLAUDE.md new file mode 100644 index 000000000000..d1a82dbef439 --- /dev/null +++ b/packages/tools/devtools/devtools-browser-extension/CLAUDE.md @@ -0,0 +1,41 @@ +# @fluid-internal/devtools-browser-extension + +Browser extension for visualizing Fluid Framework stats and operations. + +## Build + +- `pnpm build` - Full build including webpack bundle +- `pnpm build:compile` - Compile TypeScript only +- `pnpm webpack` - Build production webpack bundle +- `pnpm webpack:dev` - Build development webpack bundle + +## Test + +- `pnpm test` - Run all tests (Mocha + Jest) +- `pnpm test:mocha` - Run Mocha unit tests (ESM and CJS) +- `pnpm test:jest` - Run Jest end-to-end tests +- `pnpm test:coverage` - Run tests with coverage + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome +- `pnpm good-fences` - Run good-fences boundary checks + +## Development + +- `pnpm start:client:test` - Start webpack dev server for testing + +## Key Dependencies + +- `@fluid-internal/devtools-view` - UI components +- `@fluidframework/devtools-core` - Core functionality +- `@microsoft/1ds-core-js` / `@microsoft/1ds-post-js` - Telemetry +- React 18 + +## Notes + +- Private package (not published) +- Uses Puppeteer for e2e tests +- Requires Chrome types for extension APIs +- Uses sinon-chrome for mocking Chrome APIs in tests diff --git a/packages/tools/devtools/devtools-core/CLAUDE.md b/packages/tools/devtools/devtools-core/CLAUDE.md new file mode 100644 index 000000000000..b3e2dc44b685 --- /dev/null +++ b/packages/tools/devtools/devtools-core/CLAUDE.md @@ -0,0 +1,48 @@ +# @fluidframework/devtools-core + +Core functionality for Fluid Framework developer tools. + +## Build + +- `pnpm build` - Full build including lint and API +- `pnpm build:compile` - Compile only +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output +- `pnpm build:genver` - Generate version info + +## Test + +- `pnpm test` - Run Mocha tests (ESM only by default) +- `pnpm test:mocha:cjs` - Run CommonJS tests +- `pnpm test:coverage` - Run tests with coverage + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome +- `pnpm eslint:fix` - Fix ESLint issues + +## API + +- `pnpm api` - Generate API reports +- `pnpm build:docs` - Build API documentation +- `pnpm typetests:gen` - Generate type tests + +## Exports + +- `.` - Public API +- `./alpha` - Alpha API +- `./beta` - Beta API +- `./internal` - Internal API + +## Key Dependencies + +- Fluid container and runtime packages +- DDS packages (map, sequence, matrix, cell, counter, tree) +- `@fluidframework/telemetry-utils` + +## Notes + +- Dual ESM/CJS module output (lib/ for ESM, dist/ for CJS) +- Type validation enabled with alpha entrypoint +- Core package that other devtools packages depend on diff --git a/packages/tools/devtools/devtools-test-app/CLAUDE.md b/packages/tools/devtools/devtools-test-app/CLAUDE.md new file mode 100644 index 000000000000..9ad6fdb3eb5d --- /dev/null +++ b/packages/tools/devtools/devtools-test-app/CLAUDE.md @@ -0,0 +1,44 @@ +# @fluid-private/devtools-test-app + +Example application demonstrating Fluid devtools integration. + +## Build + +- `pnpm build` - Full build +- `pnpm build:compile` - Compile TypeScript +- `pnpm webpack` - Build production bundle +- `pnpm webpack:dev` - Build development bundle + +## Test + +- `pnpm test` - Run Jest tests +- `pnpm test:coverage` - Run tests with coverage + +## Development + +- `pnpm start` - Start dev server with watch mode for all devtools packages +- `pnpm start:client` - Start webpack dev server only + +## Watch Commands + +- `pnpm watch:esnext` - Watch this package +- `pnpm watch:devtools-core` - Watch devtools-core changes +- `pnpm watch:devtools-view` - Watch devtools-view changes + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome + +## Key Dependencies + +- `@fluid-internal/devtools-view` - Devtools UI +- `@fluidframework/devtools-core` - Core devtools +- `@fluentui/react-components` - Fluent UI +- React 18 with re-resizable for UI layout + +## Notes + +- Private package (not published) +- Use `pnpm start` for development with hot reloading +- Demonstrates integration patterns for devtools diff --git a/packages/tools/devtools/devtools-view/CLAUDE.md b/packages/tools/devtools/devtools-view/CLAUDE.md new file mode 100644 index 000000000000..73bb970e196d --- /dev/null +++ b/packages/tools/devtools/devtools-view/CLAUDE.md @@ -0,0 +1,42 @@ +# @fluid-internal/devtools-view + +Visualization suite for Fluid Devtools UI components. + +## Build + +- `pnpm build` - Full build +- `pnpm build:compile` - Compile TypeScript +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run Jest tests (CJS only due to fluentui issue 30778) +- `pnpm test:jest:cjs` - Run CJS Jest tests +- `pnpm test:jest:esm` - Run ESM Jest tests (currently skipped) +- `pnpm test:coverage` - Run tests with coverage + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome + +## API + +- `pnpm build:docs` - Build API documentation +- `pnpm check:exports` - Check API exports + +## Key Dependencies + +- `@fluentui/react` and `@fluentui/react-components` - UI framework +- `@fluidframework/devtools-core` - Core devtools data +- `recharts` - Charting library +- `react-split-pane` - Resizable panes +- React 18 + +## Notes + +- Private package (not published) +- Dual ESM/CJS output (lib/ for ESM, dist/ for CJS) +- ESM tests skipped due to FluentUI compatibility issue +- Uses axe-core for accessibility testing diff --git a/packages/tools/devtools/devtools/CLAUDE.md b/packages/tools/devtools/devtools/CLAUDE.md new file mode 100644 index 000000000000..6320141defc7 --- /dev/null +++ b/packages/tools/devtools/devtools/CLAUDE.md @@ -0,0 +1,44 @@ +# @fluidframework/devtools + +Fluid Framework developer tools for integrating devtools into Fluid applications. + +## Build + +- `pnpm build` - Full build including lint and API +- `pnpm build:compile` - Compile only +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Tests not yet implemented (TODO) + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome +- `pnpm eslint:fix` - Fix ESLint issues + +## API + +- `pnpm api` - Generate API reports +- `pnpm build:docs` - Build API documentation +- `pnpm typetests:gen` - Generate type tests + +## Exports + +- `.` - Public API +- `./alpha` - Alpha API +- `./beta` - Beta API +- `./internal` - Internal API + +## Key Dependencies + +- `@fluidframework/devtools-core` - Core devtools functionality +- `@fluidframework/fluid-static` - Fluid static integration + +## Notes + +- Dual ESM/CJS module output (lib/ for ESM, dist/ for CJS) +- Uses api-extractor for API surface management +- Type validation enabled with alpha entrypoint diff --git a/packages/tools/fetch-tool/CLAUDE.md b/packages/tools/fetch-tool/CLAUDE.md new file mode 100644 index 000000000000..fbb5b8c006f0 --- /dev/null +++ b/packages/tools/fetch-tool/CLAUDE.md @@ -0,0 +1,35 @@ +# @fluid-tools/fetch-tool + +Console tool to fetch Fluid data from relay services. + +## Build + +- `pnpm build` - Full build +- `pnpm build:compile` - Compile TypeScript +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## CLI + +- Binary: `fluid-fetch` (bin/fluid-fetch) +- Run locally: `node bin/fluid-fetch` + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome +- `pnpm eslint:fix` - Fix ESLint issues + +## Key Dependencies + +- `@azure/identity` - Azure authentication +- `@fluidframework/odsp-driver` - SharePoint/OneDrive driver +- `@fluidframework/routerlicious-driver` - Routerlicious driver +- `@fluidframework/tool-utils` - Shared tool utilities + +## Notes + +- ESM module type +- Supports ODSP and Routerlicious services +- Uses Azure identity with cache persistence +- Type validation with internal entrypoint diff --git a/packages/tools/fluid-runner/CLAUDE.md b/packages/tools/fluid-runner/CLAUDE.md new file mode 100644 index 000000000000..377452631b66 --- /dev/null +++ b/packages/tools/fluid-runner/CLAUDE.md @@ -0,0 +1,52 @@ +# @fluidframework/fluid-runner + +Utility for running functionality inside a Fluid Framework environment. + +## Build + +- `pnpm build` - Full build including lint and API +- `pnpm build:compile` - Compile only +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## Test + +- `pnpm test` - Run Mocha tests (ESM and CJS) +- `pnpm test:mocha:esm` - Run ESM tests only +- `pnpm test:mocha:cjs` - Run CJS tests only +- `pnpm test:coverage` - Run tests with coverage + +## CLI + +- Binary: `fluid-runner` (bin/fluid-runner.mjs) +- Run locally: `node bin/fluid-runner.mjs` + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome + +## API + +- `pnpm api` - Generate API reports +- `pnpm build:docs` - Build API documentation +- `pnpm typetests:gen` - Generate type tests + +## Exports + +- `.` - Public API +- `./legacy` - Legacy API +- `./internal` - Internal API + +## Key Dependencies + +- `@fluidframework/container-loader` - Container loading +- `@fluidframework/odsp-driver` - ODSP support +- `yargs` - CLI argument parsing +- `@json2csv/plainjs` - CSV output + +## Notes + +- Dual ESM/CJS output (lib/ for ESM, dist/ for CJS) +- Type validation with legacy entrypoint +- Uses yargs for CLI interface diff --git a/packages/tools/replay-tool/CLAUDE.md b/packages/tools/replay-tool/CLAUDE.md new file mode 100644 index 000000000000..1d2c597684d3 --- /dev/null +++ b/packages/tools/replay-tool/CLAUDE.md @@ -0,0 +1,36 @@ +# @fluid-internal/replay-tool + +Tool for replaying Fluid ops for debugging and analysis. + +## Build + +- `pnpm build` - Full build +- `pnpm build:compile` - Compile TypeScript +- `pnpm build:esnext` - Build ESM output +- `pnpm tsc` - Build CommonJS output + +## CLI + +- Binary: `replayTool` (bin/replayTool) +- Run locally: `node bin/replayTool` + +## Lint/Format + +- `pnpm lint` - Run all linting +- `pnpm format` - Format with Biome +- `pnpm eslint:fix` - Fix ESLint issues + +## Key Dependencies + +- Fluid runtime packages (container-runtime, datastore, runtime-utils) +- DDS packages (map, sequence, matrix, cell, ordered-collection) +- `@fluidframework/replay-driver` - Replay driver +- `@fluidframework/file-driver` - File-based driver +- `json-stable-stringify` - Deterministic JSON output + +## Notes + +- Private package (not published) +- Dual ESM/CJS output (lib/ for ESM, dist/ for CJS) +- Includes experimental/deprecated packages (ink, sequence-deprecated) +- Useful for debugging op sequences and container state diff --git a/packages/utils/odsp-doclib-utils/CLAUDE.md b/packages/utils/odsp-doclib-utils/CLAUDE.md new file mode 100644 index 000000000000..f7847f6a5804 --- /dev/null +++ b/packages/utils/odsp-doclib-utils/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluidframework/odsp-doclib-utils + +ODSP (OneDrive/SharePoint) utilities for authentication, error handling, and drive operations. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm build:compile` - Compile without API reports + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/odspAuth.ts` - ODSP authentication utilities +- `src/odspErrorUtils.ts` - Error handling for ODSP operations +- `src/odspDrives.ts` - Drive operations (list drives, etc.) +- `src/odspRequest.ts` - HTTP request helpers for ODSP +- `src/parseAuthErrorClaims.ts` - Parse authentication error claims + +## Notes + +- Dual ESM/CommonJS package with `lib/` (ESM) and `dist/` (CommonJS) outputs +- Exports three entry points: default (public), `/legacy`, and `/internal` +- Uses `isomorphic-fetch` for cross-environment HTTP requests +- Depends on `@fluidframework/odsp-driver-definitions` for ODSP types diff --git a/packages/utils/telemetry-utils/CLAUDE.md b/packages/utils/telemetry-utils/CLAUDE.md new file mode 100644 index 000000000000..a3186bc59472 --- /dev/null +++ b/packages/utils/telemetry-utils/CLAUDE.md @@ -0,0 +1,44 @@ +# @fluidframework/telemetry-utils + +Collection of telemetry-related utilities for Fluid Framework including logging, error handling, and event batching. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm build:compile` - Compile without API reports + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/logger.ts` - Core logging infrastructure and logger implementations +- `src/error.ts` - Error utilities and error normalization +- `src/errorLogging.ts` - Error logging helpers +- `src/fluidErrorBase.ts` - Base class for Fluid errors +- `src/layerCompatError.ts` - Layer compatibility error handling +- `src/config.ts` - Configuration utilities for telemetry +- `src/mockLogger.ts` - Mock logger for testing +- `src/sampledTelemetryHelper.ts` - Sampled telemetry for high-frequency events +- `src/telemetryEventBatcher.ts` - Batch telemetry events +- `src/events.ts` - Event utilities + +## Notes + +- Dual ESM/CommonJS package with `lib/` (ESM) and `dist/` (CommonJS) outputs +- Exports three entry points: default (public), `/legacy`, and `/internal` +- Core dependency for most Fluid packages - changes here affect many consumers +- Uses `debug` for debug logging and `uuid` for generating correlation IDs +- Uses `sinon` for test mocking diff --git a/packages/utils/tool-utils/CLAUDE.md b/packages/utils/tool-utils/CLAUDE.md new file mode 100644 index 000000000000..12f8eaf43d30 --- /dev/null +++ b/packages/utils/tool-utils/CLAUDE.md @@ -0,0 +1,39 @@ +# @fluidframework/tool-utils + +Common utilities for Fluid tools including token management, snapshot normalization, and HTTP helpers. + +## Build + +- `pnpm build` - Build the package (ESM + CommonJS) +- `pnpm build:esnext` - Build ESM only +- `pnpm build:commonjs` - Build CommonJS only +- `pnpm build:compile` - Compile without API reports + +## Test + +- `pnpm test` - Run tests (mocha) +- `pnpm test:coverage` - Run tests with coverage (c8) +- `pnpm test:mocha:verbose` - Run tests with verbose output + +## Lint + +- `pnpm lint` - Run all linting +- `pnpm lint:fix` - Auto-fix lint issues +- `pnpm check:biome` - Check formatting with Biome +- `pnpm format` - Format code with Biome + +## Key Files + +- `src/odspTokenManager.ts` - ODSP token caching and management +- `src/snapshotNormalizer.ts` - Normalize Fluid snapshots for comparison +- `src/httpHelpers.ts` - HTTP request utilities +- `src/fluidToolRc.ts` - Configuration file (`.fluidtoolrc`) handling +- `src/debug.ts` - Debug utilities + +## Notes + +- Dual ESM/CommonJS package with `lib/` (ESM) and `dist/` (CommonJS) outputs +- Exports two entry points: default (public) and `/internal` +- Uses `proper-lockfile` for file locking and `async-mutex` for async synchronization +- Primarily used by internal tooling, not typical application code +- Token manager handles caching ODSP tokens with file-based persistence diff --git a/tools/markdown-magic/CLAUDE.md b/tools/markdown-magic/CLAUDE.md new file mode 100644 index 000000000000..12367151b5d0 --- /dev/null +++ b/tools/markdown-magic/CLAUDE.md @@ -0,0 +1,38 @@ +# @fluid-tools/markdown-magic + +Shared utilities for Markdown content generation and embedding using markdown-magic. Provides transform pragmas that can be included in Markdown documentation to automatically generate/embed contents. + +## Build + +- `pnpm build` - Runs markdown-magic on the package's own README.md +- `pnpm build:docs` - Same as build + +## Test + +- `pnpm test` - Runs markdown-magic transforms against test files in `test/**/*.md` + +## Lint/Format + +- `pnpm check:format` - Check formatting with Biome +- `pnpm format` - Auto-fix formatting with Biome + +## Key Files + +- `src/index.cjs` - Main entry point and CLI +- `src/md-magic.config.cjs` - Configuration for markdown-magic +- `src/transforms/` - Transform implementations (INCLUDE, PACKAGE_SCOPE_NOTICE, etc.) +- `src/templates/` - Markdown templates for various package notice types +- `bin/markdown-magic` - CLI binary + +## CLI Usage + +```shell +markdown-magic --files [--workingDirectory ] +``` + +## Notes + +- This is a CommonJS package (`.cjs` files) +- Private package - not published to npm +- Transforms use `` pragma syntax +- Key transforms: `INCLUDE`, `LIBRARY_README_HEADER`, `README_FOOTER`, `PACKAGE_SCOPE_NOTICE`, `INSTALLATION_INSTRUCTIONS`, `API_DOCS`