diff --git a/.github/skills/ai-context/SKILL.md b/.github/skills/ai-context/SKILL.md new file mode 100644 index 0000000000..c51a968344 --- /dev/null +++ b/.github/skills/ai-context/SKILL.md @@ -0,0 +1,111 @@ +--- +name: ai-context +description: Use when creating, updating, or maintaining AI documentation files (AGENTS.md, CLAUDE.md, skills). Covers file structure, conventions, and guidelines for evolving AI context. +--- + +# AI Context Documentation + +How to write and maintain the structured documentation that AI coding assistants consume. + +## File Hierarchy + +``` +AGENTS.md # Root context — always loaded by agents +CLAUDE.md # Required for Claude Code (loads AGENTS.md) +.github/skills//SKILL.md # On-demand detailed context +packages//AGENTS.md # Package-specific context +/AGENTS.md # Folder-specific context +``` + +## Root Files + +### AGENTS.md + +Always loaded on every interaction. Keep it **minimal** to save tokens. + +Must contain: +- One-line project description +- Essential commands (run, test, build) +- Repository structure overview (top-level dirs only) +- Skills index table linking to each `SKILL.md` +- Key entry points for common tasks + +Must **not** contain: +- Detailed explanations (put those in skills) +- Code examples longer than one line +- Duplicated content from skills + +### CLAUDE.md + +Required because Claude Code doesn't load `AGENTS.md` natively. It bridges Claude Code into the same context system. Contents: + +```markdown +Read [AGENTS.md](AGENTS.md) before starting any task. + +## Skills + +Load these for detailed context on specific topics: + +| Skill | When to use | +|-------|-------------| +| [](.github/skills//SKILL.md) | | +``` + +Keep in sync with the skills table in `AGENTS.md`. + +## Skills + +### Creating a Skill + +1. Create `.github/skills//SKILL.md` +2. Add YAML frontmatter with `name` and `description` +3. Add an entry to the skills table in both `AGENTS.md` and `CLAUDE.md` + +### SKILL.md Format + +```markdown +--- +name: +description: +--- + +# + +<One-line summary.> + +## <Sections organized by task> +``` + +### Writing Guidelines + +- **Frontmatter `description`**: Write it as a trigger — what task or question should cause an agent to load this skill +- **Be concise**: Use tables over prose, code snippets over explanations +- **Be specific**: File paths, command names, function signatures — not vague descriptions +- **No duplication**: If info exists in another skill, reference it instead of repeating +- **Actionable structure**: Organize by what the agent needs to *do*, not by architecture + +## Package & Folder Context + +Add `AGENTS.md` inside a package or folder when: +- The directory has non-obvious conventions agents keep getting wrong +- There are local commands, patterns, or gotchas not covered by root docs + +Keep these files very short — a few lines of context is often enough. + +## When to Update + +| Trigger | Action | +|---------|--------| +| Agent repeatedly asks about a topic | Create a new skill | +| Agent gets something wrong despite docs | Refine the relevant skill | +| New package/directory with unique patterns | Add a local `AGENTS.md` | +| Architecture or tooling changes | Update affected skills | +| Skill grows too large | Split into multiple skills | +| Skills table changes | Update both `AGENTS.md` and `CLAUDE.md` | + +## Principles + +1. **Token budget**: Root files stay small; details go in skills +2. **Load on demand**: Skills are only read when relevant to the task +3. **Living docs**: Update when patterns change — stale docs are worse than none +4. **Cross-platform**: `AGENTS.md` + `.github/skills/` is the shared convention; `CLAUDE.md` bridges Claude Code which doesn't load `AGENTS.md` natively diff --git a/.github/skills/codebase/SKILL.md b/.github/skills/codebase/SKILL.md new file mode 100644 index 0000000000..32ba7872fe --- /dev/null +++ b/.github/skills/codebase/SKILL.md @@ -0,0 +1,110 @@ +--- +name: codebase +description: Use when understanding the build system, modifying CLI commands, working with isobuild, or navigating the tools/ directory. Covers build pipeline flow and file locations. +--- + +# Codebase + +Meteor's build system (Isobuild) and CLI structure. + +## Overview + +Meteor is a full-stack JavaScript platform with: +- **Core packages** in `/packages` +- **Build system (Isobuild)** in `/tools/isobuild` +- **CLI tool** in `/tools/cli` +- **Real-time data layer** via DDP +- **Mobile support** via Cordova + +## Build Pipeline + +1. **CLI** (`tools/cli/main.js`) → parses commands +2. **Project Context** (`project-context.js`) → resolves packages, dependencies +3. **Isobuild** (`tools/isobuild/`) + - Bundler (`bundler.js`) → orchestrates build + - Compiler (`compiler.js`) → compiles packages + - Linker (`linker.js`) → wraps modules + - Build plugins (Babel, TypeScript, CSS) +4. **Output** → `star.json`, programs +5. **Runners** (`tools/runners/`) → run-app.js, run-mongo.js, run-hmr.js +6. **Live App** → DDP Server ↔ Minimongo ↔ UI + +## Directory Structure + +``` +tools/ +├── cli/ # Command-line interface +├── isobuild/ # Build system core +├── packaging/ # Package management +├── runners/ # App execution engines +├── fs/ # File system utilities +├── cordova/ # Mobile/Cordova support +├── static-assets/ # Project templates +└── project-context.js # Dependency resolution +``` + +## CLI (`tools/cli/`) + +| File | Description | +|------|-------------| +| `main.js` | Entry point, command dispatcher | +| `commands.js` | Main command implementations | +| `commands-packages.js` | Package management commands | +| `commands-cordova.js` | Cordova/mobile commands | + +**Commands:** `meteor create`, `run`, `build`, `deploy`, `add/remove`, `mongo`, `shell` + +## Isobuild (`tools/isobuild/`) + +| File | Description | +|------|-------------| +| `bundler.js` | High-level bundling orchestration | +| `compiler.js` | Package compilation | +| `linker.js` | Module wrapping and linking | +| `import-scanner.ts` | Import statement parsing | +| `compiler-plugin.js` | Compiler plugin API | +| `isopack.js` | Package format handling | + +## Runners (`tools/runners/`) + +| File | Description | +|------|-------------| +| `run-app.js` | Web application runner | +| `run-mongo.js` | MongoDB server runner | +| `run-hmr.js` | Hot module reload runner | +| `run-all.js` | Multi-runner orchestration | + +## Build Targets + +| Target | Description | +|--------|-------------| +| `web.browser` | Modern browsers | +| `web.browser.legacy` | Legacy browsers (IE11) | +| `web.cordova` | Cordova mobile apps | +| `server` | Node.js server | + +## Package Relationships + +- `tools-core` → rspack, future integrations +- `accounts-base` → all accounts-* packages +- `ddp-server` + `ddp-client` → realtime communication +- `mongo` → minimongo (client-side) +- `webapp` → all HTTP handling + +## Project Templates + +Via `meteor create --<template>`: `react`, `vue`, `svelte`, `angular`, `blaze`, `typescript`, `tailwind`, `solid`, `apollo`, `minimal`, `bare`, `full` + +## Environment Variables + +| Variable | Purpose | +|----------|---------| +| `METEOR_PROFILE` | Build profiling | +| `METEOR_PACKAGE_DIRS` | Additional package paths | +| `METEOR_DEBUG_BUILD` | Verbose build output | + +## Troubleshooting + +- **Package not found:** Check `package.js` name, run `meteor reset` +- **Build plugin not running:** Check `archMatching`, file extensions +- **npm issues:** Clear `.meteor/local/`, run `meteor npm install` diff --git a/.github/skills/conventions/SKILL.md b/.github/skills/conventions/SKILL.md new file mode 100644 index 0000000000..1767100ca5 --- /dev/null +++ b/.github/skills/conventions/SKILL.md @@ -0,0 +1,188 @@ +--- +name: conventions +description: Use when writing new packages, adding CLI commands, creating build plugins, or following Meteor code patterns. Covers package.js structure, file naming, and common code patterns. +--- + +# Code Conventions + +Package structure, file naming, and code patterns for the Meteor codebase. + +## Package Structure + +Every Meteor package follows this structure: + +``` +packages/my-package/ +├── package.js # Package manifest (name, version, dependencies, exports) +├── my-package.js # Main implementation (or split by concern) +├── my-package-server.js # Server-only code (optional) +├── my-package-client.js # Client-only code (optional) +├── my-package-tests.js # Tests (loaded via api.addFiles in test mode) +└── README.md # Documentation (optional) +``` + +## Package.js Anatomy + +```javascript +Package.describe({ + name: 'my-package', + version: '1.0.0', + summary: 'Brief description', + git: 'https://github.com/meteor/meteor.git', + documentation: 'README.md' +}); + +Package.onUse(function(api) { + api.versionsFrom(['3.0']); // Minimum Meteor version + + api.use([ + 'ecmascript', // ES2015+ support + 'mongo', // MongoDB integration + 'tracker' // Reactivity (client) + ]); + + api.use('accounts-base', { weak: true }); // Optional dependency + + api.mainModule('my-package-server.js', 'server'); + api.mainModule('my-package-client.js', 'client'); + + api.export('MyPackage'); // Global export +}); + +Package.onTest(function(api) { + api.use(['tinytest', 'my-package']); + api.addFiles('my-package-tests.js'); +}); + +Npm.depends({ + 'lodash': '4.17.21' // npm dependencies +}); +``` + +## File Naming Conventions + +| Pattern | Purpose | +|---------|---------| +| `*-server.js` | Server-only code | +| `*-client.js` | Client-only code | +| `*-common.js` | Shared code | +| `*-tests.js` | Test files | +| `*.d.ts` | TypeScript declarations | + +## Common Patterns + +### Adding a New Core Package + +1. Create directory in `/packages/my-package/` +2. Add `package.js` with proper dependencies +3. Implement functionality with proper exports +4. Add tests in `*-tests.js` +5. Update version numbers if needed + +### Modifying Build System + +Key files to understand: +- `/tools/isobuild/bundler.js` - High-level bundling +- `/tools/isobuild/compiler.js` - Package compilation +- `/tools/project-context.js` - Dependency resolution +- `/tools/cli/commands.js` - CLI command handlers + +### Adding CLI Commands + +Edit `/tools/cli/commands.js` or create new command file: + +```javascript +main.registerCommand({ + name: 'my-command', + options: { + 'option-name': { type: String, short: 'o' } + }, + catalogRefresh: new catalog.Refresh.Never() +}, function(options) { + // Implementation +}); +``` + +### WebApp Middleware Pattern + +```javascript +import { WebApp } from 'meteor/webapp'; + +// Add middleware before Meteor's default handlers +WebApp.rawConnectHandlers.use('/api', (req, res, next) => { + // Runs before authentication + next(); +}); + +// Add middleware after authentication +WebApp.connectHandlers.use('/api', (req, res, next) => { + // req.userId available if authenticated + next(); +}); +``` + +### Build Plugin Pattern + +```javascript +// In package.js +Package.registerBuildPlugin({ + name: 'compile-my-files', + use: ['ecmascript', 'caching-compiler'], + sources: ['plugin.js'], + npmDependencies: { 'my-compiler': '1.0.0' } +}); + +// In plugin.js +Plugin.registerCompiler({ + extensions: ['myext'], + archMatching: 'web' +}, () => new MyCompiler()); + +class MyCompiler extends CachingCompiler { + getCacheKey(inputFile) { + return inputFile.getSourceHash(); + } + + compileOneFile(inputFile) { + const source = inputFile.getContentsAsString(); + const compiled = transform(source); + inputFile.addJavaScript({ + data: compiled, + path: inputFile.getPathInPackage() + '.js' + }); + } +} +``` + +### Using tools-core in Packages + +```javascript +// In package.js +api.use('tools-core'); + +// In implementation +import { + logProgress, + checkNpmDependencyExists, + getMeteorAppConfig, + spawnProcess +} from 'meteor/tools-core'; + +// Check and install dependencies +if (!checkNpmDependencyExists('@rspack/core')) { + installNpmDependency(['@rspack/core@^1.7.1']); +} + +// Spawn external process +const proc = spawnProcess('npx', ['rspack', 'build'], { + cwd: getMeteorAppDir(), + onStdout: (data) => logProgress(data) +}); +``` + +## Version Patterns + +Meteor uses `X.Y.Z-rcN.M` versioning where: +- `X.Y.Z` - Semantic version +- `rcN` - Release candidate number +- `M` - Package-specific revision diff --git a/.github/skills/modern-tools/SKILL.md b/.github/skills/modern-tools/SKILL.md new file mode 100644 index 0000000000..cfcacdb09a --- /dev/null +++ b/.github/skills/modern-tools/SKILL.md @@ -0,0 +1,246 @@ +--- +name: modern-tools +description: Use when working with tools-core utilities, rspack integration, or modern tooling. Covers logging, npm management, process spawning, git helpers, and Meteor app configuration APIs. +--- + +# Modern Tools + +Utility packages for modern tooling, bundler integrations, and native solutions. + +## tools-core (`/packages/tools-core`) + +Central utility package providing helpers for npm, logging, process management, and Meteor configuration. This is the foundation for modern tool integrations. + +### Logging Module (`lib/log.js`) + +```javascript +import { logProgress, logError, logInfo, logSuccess } from 'meteor/tools-core'; + +logProgress('Building application...'); // Blue +logSuccess('Build complete'); // Green +logError('Build failed'); // Red +logInfo('Using Rspack bundler'); // Purple +``` + +Respects `METEOR_DISABLE_COLORS` environment variable. + +### NPM Management Module (`lib/npm.js`) + +| Function | Description | +|----------|-------------| +| `getNodeBinaryPath(binaryName)` | Gets path to Node binaries (npm, npx, node) | +| `checkNpmDependencyExists(dep, opts)` | Checks if npm package is installed | +| `checkNpmBinaryExists(binary, opts)` | Checks if binary exists in node_modules/.bin | +| `checkNpmDependencyVersion(dep, opts)` | Validates semver with conditions (gte, lt, eq) | +| `installNpmDependency(deps, opts)` | Installs dependencies (npm/yarn, dev/exact flags) | +| `getNpmCommand(args)` | Returns npm command with `meteor npm` fallback | +| `getNpxCommand(args)` | Returns npx command with `meteor npx` fallback | +| `getYarnCommand(args)` | Gets yarn command path | +| `isYarnProject(opts)` | Detects yarn projects (yarn.lock, packageManager) | +| `getMonorepoPath(opts)` | Detects monorepo root (workspaces, lerna, pnpm) | +| `isMonorepo(opts)` | Boolean monorepo detection | + +### Process Management Module (`lib/process.js`) + +| Function | Description | +|----------|-------------| +| `spawnProcess(cmd, args, opts)` | Spawns process with streaming output, color preservation | +| `stopProcess(proc, opts)` | Graceful termination with SIGTERM/SIGKILL fallback | +| `isProcessRunning(proc)` | Checks if process is still running | +| `isPortAvailable(port, host)` | Checks if port is free | +| `waitForPort(port, opts)` | Waits for port availability with timeout | + +Options for `spawnProcess`: `env`, `cwd`, `detached`, `onStdout`, `onStderr`, `onExit`, `onError` + +### Meteor Configuration Module (`lib/meteor.js`) + +**Application Configuration:** + +| Function | Description | +|----------|-------------| +| `getMeteorAppDir()` | Gets application root directory | +| `getMeteorAppPackageJson()` | Parses app's package.json | +| `getMeteorAppConfig()` | Retrieves Meteor config from package.json or Plugin | +| `getMeteorAppPort()` | Gets app port from environment | +| `getMeteorAppConfigModern()` | Gets modern bundler configuration | +| `isMeteorAppConfigModernVerbose()` | Checks verbose flag | +| `hasMeteorAppConfigAutoInstallDeps()` | Auto-install deps flag | + +**Entry Points:** + +| Function | Description | +|----------|-------------| +| `getMeteorAppEntrypoints()` | Gets main/test modules for client/server | +| `getMeteorInitialAppEntrypoints()` | Gets initial entry points with HTML detection | +| `isMeteorAppTestModule()` | Checks if project is test module | +| `setMeteorAppEntrypoints(opts)` | Sets entry points via environment variables | +| `setMeteorAppIgnore(pattern)` | Sets file ignore patterns | +| `setMeteorAppCustomScriptUrl(url)` | Sets custom script URLs | + +**Command Detection:** + +| Function | Description | +|----------|-------------| +| `isMeteorAppRun()` | Running in 'run' mode | +| `isMeteorAppBuild()` | Running in 'build' or 'deploy' | +| `isMeteorAppUpdate()` | Running in 'update' | +| `isMeteorAppTest()` | In test mode | +| `isMeteorAppTestFullApp()` | Test mode with full-app flag | +| `isMeteorAppTestWatch()` | Test mode in watch mode | +| `isMeteorAppNativeAndroid()` | Native Android mode | +| `isMeteorAppNativeIos()` | Native iOS mode | +| `isMeteorAppNative()` | Any native mode | +| `isMeteorAppDevelopment()` | Development mode | +| `isMeteorAppProduction()` | Production mode | +| `isMeteorAppDebug()` | Debug mode | + +**Package Detection:** + +| Function | Description | +|----------|-------------| +| `isMeteorBlazeProject()` | Has blaze/blaze-html-templates | +| `isMeteorBlazeHotProject()` | Blaze with hot reload | +| `isMeteorCoffeescriptProject()` | Has CoffeeScript | +| `isMeteorLessProject()` | Has Less CSS | +| `isMeteorScssProject()` | Has SCSS/Sass | +| `isMeteorTypescriptProject()` | Has TypeScript | +| `isMeteorBundleVisualizerProject()` | Has bundle visualizer | +| `isMeteorPackagesTest()` | test-packages command | + +**File Operations:** + +| Function | Description | +|----------|-------------| +| `getMeteorAppFilesAndFolders(opts)` | Scans app directory (recursive, with ignore) | +| `getMeteorAppPackages()` | Lists all loaded packages | +| `getMeteorEnvPackageDirs()` | Gets package directories from env vars | +| `getMeteorToolsRequire(filePath)` | Requires module relative to Meteor tools | + +### Global State Module (`lib/global-state.js`) + +Maintains persistent state across file changes during development: + +```javascript +import { getGlobalState, setGlobalState, removeGlobalState, clearGlobalState } from 'meteor/tools-core'; + +setGlobalState('buildStartTime', Date.now()); +const startTime = getGlobalState('buildStartTime'); +``` + +### Git Management Module (`lib/git.js`) + +| Function | Description | +|----------|-------------| +| `isGitRepository(dir)` | Checks if directory is git repo | +| `gitignoreExists(dir)` | Checks .gitignore existence | +| `ensureGitignoreExists(dir, entries)` | Creates .gitignore with initial entries | +| `getMissingGitignoreEntries(dir, entries)` | Finds missing entries | +| `addGitignoreEntries(dir, entries, ctx)` | Adds entries with context logging | + +### String Utilities (`lib/string.js`) + +| Function | Description | +|----------|-------------| +| `capitalizeFirstLetter(str)` | Capitalizes first character | +| `shuffleString(str)` | Shuffles string characters | +| `joinWithAnd(items, opts)` | Human-readable list ("a, b, and c") | + +--- + +## Rspack Integration (`/packages/rspack`) + +Modern bundler integration using Rspack (Rust-based Webpack alternative). + +### Package Structure + +| File | Description | +|------|-------------| +| `lib/constants.js` | Default versions, global state keys, build contexts | +| `lib/dependencies.js` | Dependency checking and auto-installation | +| `lib/build-context.js` | Build directory management | +| `lib/config.js` | Meteor configuration for Rspack | +| `lib/processes.js` | Rspack process spawning | +| `lib/compilation.js` | Compilation tracking | + +### Build Contexts + +| Context | Directory | Purpose | +|---------|-----------|---------| +| `RSPACK_BUILD_CONTEXT` | `_build` | Build output | +| `RSPACK_ASSETS_CONTEXT` | `build-assets` | Static assets | +| `RSPACK_CHUNKS_CONTEXT` | `build-chunks` | Chunk bundles | +| `RSPACK_DOCTOR_CONTEXT` | `.rsdoctor` | Analysis/diagnostics | + +### Key Dependencies + +- `@rspack/core` ^1.7.1 +- `@meteorjs/rspack` ^0.3.56 (configuration logic) +- `@rspack/plugin-react-refresh` ^1.4.3 +- `swc-loader` ^0.2.6 + +### Integration with tools-core + +- Uses `getMeteorInitialAppEntrypoints()` for entry points +- Uses command detection functions for build mode awareness +- Uses process spawning and npm utilities + +--- + +## TypeScript Compiler (`/packages/typescript`) + +Compiler plugin for TypeScript/TSX file compilation. + +**Registered Plugin:** `compile-typescript` + +**Supported Extensions:** `.ts`, `.tsx` + +**Implied Packages:** `modules`, `ecmascript-runtime`, `babel-runtime`, `promise`, `dynamic-import` + +**Features:** +- Transpiles TypeScript before Babel processing +- Supports client/server/legacy browser targets +- Integrates with React Fast Refresh for HMR + +**Limitations:** +- Per-file transpilation (no cross-file type analysis) +- No tsconfig.json support (Meteor manages settings) +- No type checking during compilation +- No .d.ts generation + +--- + +## WebApp & Express (`/packages/webapp`) + +HTTP server integration using Express.js 5.x framework. + +### Key APIs + +```javascript +import { WebApp } from 'meteor/webapp'; + +// Middleware registration +WebApp.connectHandlers.use('/api', myMiddleware); +WebApp.handlers.use(compression()); + +// Direct Express access +WebApp.expressApp.get('/health', (req, res) => res.send('OK')); + +// Server instance +WebApp.httpServer; + +// Hooks +WebApp.onListening(() => console.log('Server ready')); +``` + +### Express Exports + +| Property | Description | +|----------|-------------| +| `WebApp.connectHandlers` | Express middleware registry (legacy name) | +| `WebApp.handlers` | Current middleware registry | +| `WebApp.rawConnectHandlers` | Raw Express handlers | +| `WebApp.expressApp` | Direct Express app instance | +| `WebApp.httpServer` | HTTP server instance | +| `WebApp.express` | Express module export | + +**Dependencies:** express@5.1.0, cookie-parser@1.4.6, compression@1.7.4, errorhandler@1.5.1 diff --git a/.github/skills/packages/SKILL.md b/.github/skills/packages/SKILL.md new file mode 100644 index 0000000000..4c0b1b467e --- /dev/null +++ b/.github/skills/packages/SKILL.md @@ -0,0 +1,152 @@ +--- +name: packages +description: Use when exploring the package ecosystem, finding which package handles a feature, understanding package relationships, or adding dependencies. Lists all core packages by domain. +--- + +# Core Packages + +Overview of Meteor's package ecosystem organized by domain. + +## Authentication & Accounts + +| Package | Description | +|---------|-------------| +| `accounts-base` | Foundation for the user account system | +| `accounts-password` | Password-based authentication | +| `accounts-passwordless` | Magic-link/token-based authentication | +| `accounts-2fa` | Two-factor authentication support | +| `accounts-ui` / `accounts-ui-unstyled` | Pre-built UI components for auth | +| `accounts-oauth` | OAuth protocol support | +| `oauth` / `oauth1` / `oauth2` | OAuth implementation | +| `oauth-encryption` | Encrypted OAuth token storage | +| `service-configuration` | OAuth provider configuration | + +**Social Login Providers:** +- `accounts-facebook`, `accounts-github`, `accounts-google` +- `accounts-twitter`, `accounts-meetup`, `accounts-weibo` +- `accounts-meteor-developer` + +## Data & Database + +| Package | Description | +|---------|-------------| +| `mongo` | MongoDB integration and collection API | +| `minimongo` | Client-side MongoDB emulation | +| `mongo-id` | MongoDB ObjectID generation | +| `mongo-livedata` | Reactive MongoDB queries | +| `npm-mongo` | MongoDB Node.js driver wrapper | +| `mongo-dev-server` | Development MongoDB server | +| `ddp` | Distributed Data Protocol meta-package | +| `ddp-common` | Shared DDP utilities | +| `ddp-client` | DDP client implementation | +| `ddp-server` | DDP server implementation | +| `ddp-rate-limiter` | Rate limiting for DDP methods/subscriptions | +| `ejson` | Extended JSON serialization | + +## Build System & Compilation + +| Package | Description | +|---------|-------------| +| `babel-compiler` | JavaScript transpilation via Babel | +| `babel-runtime` | Babel runtime helpers | +| `ecmascript` | ECMAScript 2015+ support | +| `ecmascript-runtime` | ES6+ runtime polyfills | +| `typescript` | TypeScript compilation support | +| `modules` | ES modules system | +| `modules-runtime` | Module runtime implementation | +| `modules-runtime-hot` | Hot module reloading runtime | +| `hot-code-push` | Live code updates | +| `hot-module-replacement` | HMR support | +| `rspack` | Rspack bundler integration | +| `boilerplate-generator` | HTML boilerplate generation | +| `dynamic-import` | Dynamic `import()` support | +| `caching-compiler` | Build cache management | + +## Minification & Assets + +| Package | Description | +|---------|-------------| +| `minifier-js` | JavaScript minification (terser) | +| `minifier-css` | CSS minification | +| `standard-minifier-js` | Default JS minifier package | +| `standard-minifier-css` | Default CSS minifier package | +| `standard-minifiers` | Meta-package for minifiers | +| `static-html` | Static HTML file processing | + +## Web & Server + +| Package | Description | +|---------|-------------| +| `webapp` | HTTP server and request handling | +| `webapp-hashing` | Asset fingerprinting | +| `reload` | Client-side app reload mechanism | +| `reload-safetybelt` | Reload failure recovery | +| `autoupdate` | Automatic client updates | +| `browser-policy` | Content Security Policy | +| `force-ssl` | HTTPS enforcement | +| `allow-deny` | Collection permission rules | +| `fetch` | HTTP Fetch API polyfill | +| `routepolicy` | Route-based policies | + +## Client-Side Utilities + +| Package | Description | +|---------|-------------| +| `tracker` | Reactive dependency tracking | +| `reactive-var` | Single reactive value | +| `reactive-dict` | Reactive key-value store | +| `session` | Client-side session storage | +| `localstorage` | LocalStorage wrapper | +| `socket-stream-client` | WebSocket client | +| `random` | Cryptographic random generation | +| `check` | Runtime type checking | +| `underscore` | Utility library | +| `base64` | Base64 encoding/decoding | +| `diff-sequence` | Array diffing algorithm | +| `id-map` | ID-based mapping | +| `ordered-dict` | Ordered dictionary | + +## Testing (6 packages) + +| Package | Description | +|---------|-------------| +| `tinytest` | Meteor's built-in test framework | +| `tinytest-harness` | Test harness utilities | +| `test-helpers` | Testing utility functions | +| `test-in-browser` | Browser-based test runner | +| `test-in-console` | Console-based test runner | + +## Context & Roles + +| Package | Description | +|---------|-------------| +| `context` | Request context management (AsyncLocalStorage) | +| `roles` | User roles and permissions system | + +## Deprecated Packages (`packages/deprecated/`) + +40+ legacy packages maintained for backward compatibility: +- UI libraries: `amplify`, `backbone`, `d3`, `handlebars` +- Legacy OAuth: `facebook`, `github`, `google` (use `accounts-*` instead) +- Config UIs: `*-config-ui` packages +- Others: `jquery-history`, `jshint`, `jsparse`, `deps` (use `tracker`) + +## Development-Only Packages + +| Package | Description | +|---------|-------------| +| `autopublish` | Auto-publish all collections (remove in production) | +| `insecure` | Allow all database writes (remove in production) | + +## NPM Packages (`/npm-packages`) + +Packages published to npm for external use: + +| Package | npm Name | Description | +|---------|----------|-------------| +| `meteor-babel` | `@meteorjs/babel` | Babel wrapper for ES2015+ transpilation | +| `babel-preset-meteor` | `@meteorjs/babel-preset-meteor` | Babel preset with Meteor-specific transforms | +| `meteor-rspack` | `@meteorjs/rspack` | Rspack configuration builder | +| `meteor-promise` | `meteor-promise` | ES6 Promise with Fiber support | +| `meteor-node-stubs` | `meteor-node-stubs` | Node.js core module polyfills for browser | +| `eslint-plugin-meteor` | `eslint-plugin-meteor` | Meteor-specific ESLint rules | diff --git a/.github/skills/testing/SKILL.md b/.github/skills/testing/SKILL.md new file mode 100644 index 0000000000..160ba85c97 --- /dev/null +++ b/.github/skills/testing/SKILL.md @@ -0,0 +1,144 @@ +--- +name: testing +description: Use when writing tests, debugging test failures, running the test suite, or setting up test infrastructure. Covers self-test, package tests, and modern E2E tests. +--- + +# Testing + +Test patterns, commands, and utilities for the Meteor codebase. + +## Test Commands + +```bash +# CLI self-tests +./meteor self-test # Run all CLI tests +./meteor self-test "test name" # Run specific test +./meteor self-test --list # List available tests +./meteor self-test --exclude "^[a-b]" # Exclude tests by regex +./meteor self-test --retries 0 # Skip retries in development + +# Package tests (TinyTest — view results at http://localhost:3000) +./meteor test-packages # Test all core packages +./meteor test-packages mongo # Test specific package +TINYTEST_FILTER="collection" ./meteor test-packages # Filter specific tests + +# Package tests in console (headless via Puppeteer) +PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium ./packages/test-in-console/run.sh + +# Modern E2E tests (Jest + Playwright) +npm run install:modern # Install dependencies +npm run test:modern # Run all E2E tests +npm run test:modern -- -t="React" # Run specific test +``` + +## Modern E2E Tests (`tools/modern-tests/`) + +Jest + Playwright suite for verifying modern bundler integrations (rspack). Tests cover framework skeletons and build scenarios. + +**Test apps:** `apps/{react,vue,svelte,solid,blaze,typescript,babel,coffeescript,monorepo}` + +## Test Helpers Package (`packages/test-helpers`) + +Comprehensive testing utilities for Meteor applications. + +### Async Testing + +```javascript +import { testAsyncMulti, simplePoll, waitUntil } from 'meteor/test-helpers'; + +// Wait for condition +await waitUntil(() => someCondition, { timeout: 5000, interval: 100 }); + +// Poll until ready +simplePoll(() => isReady(), successCallback, failCallback); +``` + +### DOM/UI Testing + +```javascript +import { clickElement, simulateEvent, canonicalizeHtml, renderToDiv } from 'meteor/test-helpers'; + +clickElement(button); +simulateEvent(input, 'keydown', { keyCode: 13 }); +const normalized = canonicalizeHtml(html); +``` + +### Connection Testing + +```javascript +import { makeTestConnection, captureConnectionMessages } from 'meteor/test-helpers'; + +const conn = makeTestConnection(clientId); +const messages = captureConnectionMessages(server); +``` + +### Utilities + +| Function | Description | +|----------|-------------| +| `SeededRandom` | Predictable random for deterministic tests | +| `try_all_permutations()` | Test all permutations of inputs | +| `withCallbackLogger()` | Track callback invocations | +| `mockBehaviours()` | Behavior mocking | + +## Tinytest (`packages/tinytest`) + +Meteor's built-in test framework. + +```javascript +Tinytest.add('my test', function (test) { + test.equal(1 + 1, 2); + test.isTrue(true); + test.throws(function () { throw new Error(); }); +}); + +Tinytest.addAsync('async test', async function (test) { + const result = await asyncOperation(); + test.equal(result, expected); +}); +``` + +## Environment Variables + +| Variable | Description | +|----------|-------------| +| `TEST_METADATA` | Test configuration JSON | +| `METEOR_TEST_PACKAGES` | Packages to test | + +## Debug Commands + +```bash +# Verbose build output +METEOR_DEBUG_BUILD=1 ./meteor run + +# Profile build performance +METEOR_PROFILE=1 ./meteor build + +# Force rebuild +./meteor reset && ./meteor run + +# Debug Meteor tool with Chrome inspector +TOOL_NODE_FLAGS="--inspect-brk" ./meteor +``` + +## Writing Package Tests + +In `package.js`: + +```javascript +Package.onTest(function(api) { + api.use(['tinytest', 'test-helpers', 'my-package']); + api.addFiles('my-package-tests.js'); +}); +``` + +In `my-package-tests.js`: + +```javascript +import { MyPackage } from 'meteor/my-package'; + +Tinytest.add('MyPackage - basic functionality', function (test) { + const result = MyPackage.doSomething(); + test.equal(result, expected); +}); +``` diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..9cac088bee --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,60 @@ +# Meteor + +Full-stack JavaScript platform for modern web and mobile applications. + +## Commands + +```bash +./meteor run # Run from source +./meteor create my-app # Create app +./meteor self-test # CLI tests +./meteor test-packages ./packages/<name> # Package tests +npm run test:modern # E2E tests (Jest + Playwright) +``` + +## Structure + +``` +packages/ # Core Meteor packages (~100+) +tools/ # CLI & build system (Isobuild) +npm-packages/ # Published @meteorjs/* packages +scripts/ # Build & release automation +``` + +## Key Entry Points + +| Task | Location | +|------|----------| +| CLI commands | `tools/cli/commands.js` | +| Build system | `tools/isobuild/bundler.js` | +| Package lookup | `packages/<name>/package.js` | +| Modern bundler | `packages/rspack/`, `packages/tools-core/` | + +## Skills + +Load these for detailed context on specific topics: + +| Skill | When to use | +|-------|-------------| +| [codebase](.github/skills/codebase/SKILL.md) | Build system, CLI, isobuild, tools/ directory | +| [conventions](.github/skills/conventions/SKILL.md) | Writing packages, CLI commands, code patterns | +| [testing](.github/skills/testing/SKILL.md) | Writing tests, debugging failures, test infrastructure | +| [packages](.github/skills/packages/SKILL.md) | Finding packages by feature, understanding dependencies | +| [modern-tools](.github/skills/modern-tools/SKILL.md) | tools-core utilities, rspack, modern integrations | +| [ai-context](.github/skills/ai-context/SKILL.md) | Creating, updating, or maintaining AI documentation files | + +## Package Domains + +| Category | Packages | +|----------|----------| +| Auth | `accounts-base`, `accounts-password`, `accounts-oauth` | +| Database | `mongo`, `minimongo`, `ddp-server`, `ddp-client` | +| Build | `babel-compiler`, `ecmascript`, `typescript`, `rspack` | +| Web | `webapp`, `autoupdate`, `reload` | +| Reactivity | `tracker`, `reactive-var`, `reactive-dict` | + +## Notes + +- `docs/` and `guide/` are the public documentation website, not agent context +- `v3-docs/` contains Meteor 3.x documentation +- See [DEVELOPMENT.md](DEVELOPMENT.md) for contributor setup diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..cfdb92933f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,14 @@ +Read [AGENTS.md](AGENTS.md) before starting any task. + +## Skills + +Load these for detailed context on specific topics: + +| Skill | When to use | +|-------|-------------| +| [codebase](.github/skills/codebase/SKILL.md) | Build system, CLI, isobuild, tools/ directory | +| [conventions](.github/skills/conventions/SKILL.md) | Writing packages, CLI commands, code patterns | +| [testing](.github/skills/testing/SKILL.md) | Writing tests, debugging failures, test infrastructure | +| [packages](.github/skills/packages/SKILL.md) | Finding packages by feature, understanding dependencies | +| [modern-tools](.github/skills/modern-tools/SKILL.md) | tools-core utilities, rspack, modern integrations | +| [ai-context](.github/skills/ai-context/SKILL.md) | Creating, updating, or maintaining AI documentation files |