Skip to content

development.md

Latest commit

 

History

History
77 lines (53 loc) · 2.99 KB

development.md

File metadata and controls

77 lines (53 loc) · 2.99 KB
Raw

Development

Workspace layout

packages/core      Shared, host-independent code (@cortexkit/openai-auth-core, not published)
packages/opencode  OpenCode plugin (@cortexkit/opencode-openai-auth)
packages/pi        Pi extension (@cortexkit/pi-openai-auth)
scripts            Release and development tooling

STRUCTURE.md maps the files in more detail, and ARCHITECTURE.md describes how the pieces fit together.

Checks

Install dependencies:

bun install

Run the checks (the build refuses dependencies that resolve outside the repository):

bun run typecheck
bun run test
bun run build
bun run lint
bun run format:check

Inspect package contents before publishing:

The Node bundles keep jsonc-parser as a declared runtime dependency: its UMD entry uses relative require calls that Bun's bundler leaves unresolved when inlined. The packed-package tests check the external dependency allowlist and load the installed package with plain Node.

bun run pack:opencode:dry
bun run pack:pi:dry

Testing a local build with OpenCode

bun run dev

This builds the OpenCode plugin, symlinks the output into .opencode/plugins/, and starts tsc --watch. Restart OpenCode after starting the dev script and after rebuilds. Remove the local dev symlink with:

bun run dev:clean

Analyzing cache cliffs

To inspect a cache cliff, a sudden drop in prompt-cache reuse between turns, enable request dumps and run:

bun run analyze:cache -- --session ses_... --no-timeline

To print previous and current request-body text around the first differing byte, add --wire-context with the number of surrounding bytes:

bun run analyze:cache -- --session ses_... --no-timeline --wire-context 180

Mutation catalogue

mutations.toml lists deliberate breaks of production code, each with the named test that must fail when it is applied, so a guard cannot quietly stop guarding. A per-row list_command discovers the Bun test names without running the test bodies and verifies that each expected name still exists. ckdev-mutate replays them: it runs each named test on the clean tree, applies the break, requires the test to fail for the recorded reason, and restores the file. A row is for a silent, costly failure (a credential lost or leaked, a reset credit spent twice, output replayed, an account lost in a crash, a wire contract), not for style. Run it from a clean tree; CI replays the rows a pull request touches, the full catalogue on main, and the full catalogue with --broad nightly.

cargo install --locked --git https://github.com/cortexkit/commons --rev 9d6b663dac487bb982c7bfd18a96eee2292164ad cortexkit-mutate
ckdev-mutate check --strict
ckdev-mutate run --all

The --rev value above is CI's pinned ckdev-mutate source revision, stored as CKDEV_MUTATE_REV in .github/workflows/ci.yml, so local and CI checks use the same runner.