CLAUDE.md · diff

git:20260913.340e66f to git:20260917.41125a9

1 added, 1 removed. Audit A to A.

# Context

This is the standalone Context repository. It contains the local knowledge SDK,

CLI, extraction packages, Agent plugin sources, and development tooling. Hosted

server, storage, and web application stacks are outside its boundary.

## Package Topology

```mermaid

graph TD

core["@c4a/core"]

context["@c4a/context"]

extract["@c4a/extract"]

extractTs["@c4a/extract-ts"]

tui["@c4a/tui"]

contextCli["@c4a/context-cli"]

devCli["@c4a/dev-cli"]

extract --> core

extractTs --> extract

contextCli --> context

contextCli -. build-time bundle .-> core

contextCli -. build-time bundle .-> extract

contextCli -. build-time bundle .-> extractTs

devCli --> core

devCli --> tui

```

## Development Rules

- Use Bun for scripts: `bun run`, `bunx`, and `bun test`.

- Keep runtime code Node.js compatible; do not use Bun runtime APIs in package

code unless the file is explicitly a build/test tool.

- Use ESM modules and `camelCase.ts` filenames.

- Build package entrypoints through `packages/build.ts` when bundling CLI or

extractor-dependent code.

- Do not add hosted server, web, storage, model-download, or server-install

flows to this workspace.

- `@c4a/context` is the SDK surface for `src/index.ts` project entries; `@c4a/context-cli`

is the executable `context` command.

## Common Commands

```bash

bun run build

bun run typecheck

bun run test

bun run lint

bun run verify

bun run --filter @c4a/context-cli build

bun run --filter @c4a/dev-cli start

```

## Verification scope

- Local edits: run the affected package's typecheck/lint and relevant test files.

Shared test fixtures require all their consumers; SDK/schema changes include

affected downstream checks. Do not rerun the whole workspace for every edit.

- `bun run verify` runs workspace static checks and the default test collection.

CLI integration files with an observed individual test above 20 seconds belong

in `packages/context-cli/scripts/full-only-tests.json`, not the default gate.

This is a maintained classification, not a runtime timeout or automatic skip.

- `bun run verify:full` runs the default collection, then full-only CLI tests once,

followed by Node dist smoke checks; build required artifacts first.

The CLI package's `test:full` runs both collections; `test:full-only` runs only

the heavy collection. Append `--list` to inspect selection without execution.

Release CI uses `verify`; registry installation smoke is manual-only via

`bun run release:install-smoke`, not a publishing or post-release CI gate.

Successful publication triggers independent post-release `verify:full` on the

published commit. Full CLI runs default to a 20-minute per-test timeout (explicit

test budgets still apply); the streaming stress case also allows 20 minutes.

The full CI job has a separate 180-minute budget and preserves its test log.

Default and post-release full CI each use four independent runner shards;

`CONTEXT_TEST_SHARD=1/4` selects one CLI shard, with serial batches within it.

- Sorted discovery distributes new files automatically. All shards must pass;

+ Historical per-file timings drive deterministic longest-first balancing within each selected scope; unmeasured files use the measured median. Refresh `packages/context-cli/scripts/test-durations.json` from successful CI logs when timing drifts. All shards must pass;

failures do not cancel sibling shards. Each runner builds its own artifacts,

avoiding shared filesystem, environment and port state. Other package checks

remain unchanged on each runner. Local commands stay serial unless explicitly

launched in separate worktrees with distinct shard values; do not run shards

concurrently against one shared workspace or dist directory.

These commands are alternative scopes, not a ladder to execute in sequence.

- Reuse applicable passing results until inputs change. Collect failures once,

fix them together and rerun the selected scope. Keep the current result summary

separate from historical logs under `.tmp/`.

- Build and tests reading the same dist must not overlap. Prefer existing

`build:workflow`, `build:plugin` or `build:indexers` scripts for resource-only

changes; a full CLI build is still required when its bundled runtime changes.

- Test behavior, schemas, resolvable resources and safe recovery, not exact prose,

document lengths or source-code spelling. Keep mutation fixtures isolated.

## Repository boundary

- This repository is developed and released independently from any parent

monorepo or downstream distribution.

- `README.md` and `README.zh-CN.md` are the product entrypoints. Long-form

integration case studies live under `docs/`, while static replay assets live

under `case-studies/` and are published as documentation through GitHub

Pages. They are not part of the hosted product or npm runtime.

- Keep generated files out of source control: `dist/`, `node_modules/`, `.tmp/`,

coverage, and local caches.