// Architecture deep-dive for poku covering project structure, execution flow, config discovery, runtime detection, and competitive context. Use when navigating the codebase or understanding how components fit together.
| name | architecture |
| description | Architecture deep-dive for poku covering project structure, execution flow, config discovery, runtime detection, and competitive context. Use when navigating the codebase or understanding how components fit together. |
How the project is organized and where to look. Read the actual directories and source to confirm details, since file lists change over time.
Read the src/ tree to understand module organization. Each directory has a clear responsibility:
src/modules/: public surface. The barrel files exposed to consumers are the ones listed under exports in package.json (read it for the current entrypoints). Subfolders hold the essentials (core poku/assert/strict) and the helper APIs (describe, it, test, skip, kill, env, etc.)src/services/: runtime services. The runner, per-file execution, watch mode, and reporters live heresrc/parsers/: CLI and config parsing. Argument reading, config discovery, runtime detection, and runner resolutionsrc/configs/: global state, including the GLOBAL singletonsrc/builders/: chainable builders (assert, reporter)src/polyfills/: cross-runtime compatibility shimssrc/bin/: CLI entry. src/bin/index.ts is the published binarysrc/@types/: TypeScript type definitionsTo find a specific file, read the relevant directory rather than relying on a fixed list here.
Trace the path from CLI invocation to test results:
src/bin/index.ts) parses args, loads config, and calls poku()poku() orchestrator in the essentials module starts the runshell: falsePOKU_* environment variables set by the parentpoku.config.js, .pokurc.json, .pokurc.jsonc. The discovery logic lives in the options parser under src/parsers/. poku.config.cjs and poku.config.ts are supported only via an explicit --config= flag, not auto-discoverysrc/@types/ and the CLI help in src/bin/. They are the source of truth and stay current as options evolveRead the runtime detection and runner resolution in src/parsers/:
POKU_RUNTIME env var, then typeof Deno, then typeof Bun, otherwise default 'node'['bun']), Deno (['deno', 'run', ...perms]), Node (['node'], or ['node', '--import=tsx'] for TypeScript files)Poku differentiates from Jest/Vitest/Mocha/etc. by:
CLAUDE.md)benchmark/ for current numbers and the caveats stated there)--isolation=none runs all files in the same process, useful for debugging)startService, waitForPort, kill, and related helpers)Documentation deep-dive for the poku website covering Docusaurus setup, language policy, feature-to-docs mapping, conventions, JSDoc, and the changelog. Use when editing or adding docs or mapping a feature to its page.
Run the mandatory pre-commit checks for the poku repository before staging a commit. Use this whenever the user asks to commit, prepare a commit, push, open a PR, or verify a change is ready. Runs typecheck, lint:fix, build, and the local test suite in order, plus runtime-sensitive suites when the change touches runtime detection, isolation, child-process spawning, environment-variable plumbing, or any Bun or Deno specific code path.
Testing deep-dive for poku covering test structure, commands, patterns, fixtures, utils, Docker compatibility, and coverage. Use when writing, organizing, or running tests, adding fixtures, or working on coverage.
Engineering deep-dive for poku covering performance, code, and security patterns, TypeScript config, build pipeline, developer experience, and CI/CD. Use when implementing or optimizing code, writing performance-sensitive logic, touching the build, or applying code-style and security rules.