Muhammad Zakir Ramadhan
463491136a
Bump src/version.ts and package.json together; release.ts refuses to build if they disagree, or if the git tag disagrees with either. Also updates the version shown in the README and MCP sample headers, and the example in development.md so it points at the next release rather than this one.
173 lines
7.0 KiB
Markdown
173 lines
7.0 KiB
Markdown
# Development
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
git clone https://github.com/zakirkun/shiro-neko
|
|
cd shiro-neko
|
|
bun install
|
|
```
|
|
|
|
Bun 1.3.14 or newer. Nothing else is required, though `rg` on PATH makes `grep` about 15x
|
|
faster and the fallback path is exercised without it.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
bun run shiro # run from source
|
|
bun run typecheck # tsc --noEmit
|
|
bun test # 482 tests
|
|
bun run build # single binary for this platform -> dist/shiro
|
|
bun run release # all five platforms -> dist/release + SHA256SUMS
|
|
bun run install:local # build, then copy onto PATH
|
|
```
|
|
|
|
`bun run install:local` copies the compiled binary. Do not use `bun link`: it writes a shim
|
|
that re-execs `bun`, which fails on any machine where bun was installed without `bun.exe` on
|
|
PATH — an npm install of bun, for instance. The compiled binary embeds its own runtime.
|
|
|
|
`SHIRO_INSTALL_DIR` overrides the target directory.
|
|
|
|
## Testing
|
|
|
|
No mocking framework. Everything is driven through a real boundary.
|
|
|
|
```ts
|
|
// The loop: a mock provider, asserting what crossed the wire.
|
|
const seen: LanguageModelV4CallOptions[] = [];
|
|
const model = new MockLanguageModelV4({
|
|
doStream: async (o) => { seen.push(o); return stream(text('ok')); },
|
|
});
|
|
const session = new Session({ model, askApproval: async () => 'deny', agent: variantByName('plan') });
|
|
for await (const _ of session.send('investigate')) void _;
|
|
|
|
const offered = (seen[0]?.tools ?? []).map((t) => t.name);
|
|
expect(offered).not.toContain('write_file');
|
|
```
|
|
|
|
```ts
|
|
// The UI: real keystrokes, asserting what is on screen.
|
|
const app = render(<App session={session} bridge={bridge} hooks={testHooks()} header="hdr" />);
|
|
app.stdin.write('/');
|
|
await wait(120);
|
|
expect(app.lastFrame()).toContain('/compact');
|
|
```
|
|
|
|
Provider wire formats are tested against a local `Bun.serve`. MCP is tested against a real
|
|
stdio subprocess. Tools are tested in a temp directory with `process.chdir`.
|
|
|
|
`SHIRO_HOME` points config, sessions, memory, and history at a temp directory, so a test run
|
|
never touches your real state.
|
|
|
|
### What to assert
|
|
|
|
Assert on what crossed a boundary: the request body, the rendered frame, the file on disk.
|
|
Not on internal calls.
|
|
|
|
That is not style. Several real bugs were caught this way and would have passed a
|
|
mock-verification test:
|
|
|
|
- `pruneMessages` leaving a message item without its reasoning item — visible only in the
|
|
request body
|
|
- `pruneMessages` leaving a tool result without its tool call — same, and it took a stub
|
|
endpoint that rejected the pairing to prove the fix
|
|
- `--json` serialising `Error` as `{}` — visible only in the printed output
|
|
- Automatic approval requests prompting the user — visible only in the event sequence
|
|
- `ctrl-c` killing `cmd /c` but not the command under it — visible only as elapsed time, since
|
|
the interrupt reported success while the command ran for another 19 seconds
|
|
|
|
## Adding a tool
|
|
|
|
1. Define it in `src/tools.ts` with a `zod` schema. Descriptions are read by the model, so
|
|
write them as guidance, not as documentation.
|
|
2. Add it to the `tools` object.
|
|
3. Add it to a set in `TOOL_SETS`. A tool in no set can never be gated off.
|
|
4. If it mutates anything, add it to `MUTATING_TOOLS` so it requires approval.
|
|
5. Add a line to `TOOL_DOCS` in `src/prompt.ts` saying *when* to reach for it.
|
|
6. If it is read-only, add it to `READ_ONLY` in `src/agents.ts` so `plan` and `review` can use
|
|
it.
|
|
7. Test the behaviour in a temp directory, including the failure path.
|
|
|
|
Steps 3 and 4 are two hand-maintained lists of tool names, which is a known weakness: a tool
|
|
added to one and forgotten in the other is a silently ungated write. Deriving both from the
|
|
tool definitions is on [TODO.md](../TODO.md).
|
|
|
|
Every tool costs roughly 550 characters of schema on every request. Fourteen built-in tools is
|
|
well past where selection accuracy starts to matter, which is why sets exist and why a new tool
|
|
needs to earn its place — see [ROADMAP.md](../ROADMAP.md) for what has been declined and why.
|
|
|
|
## Adding a slash command
|
|
|
|
`src/commands.ts` is the single source of truth. Add a `CommandSpec` to `COMMANDS`, a case to
|
|
`parseCommand`, and a case in `App.tsx`. The menu, `/help`, and the parser all read from that
|
|
one array, and a test asserts every entry parses and appears in help — they cannot drift.
|
|
|
|
## Code conventions
|
|
|
|
Sample a neighbouring file before inventing a pattern. Broadly:
|
|
|
|
- No comment that restates the code. Comments explain *why*, and usually only where something
|
|
non-obvious was forced by an external constraint.
|
|
- No `as any`, no `@ts-ignore`. `tsconfig.json` runs strict with
|
|
`noUncheckedIndexedAccess`.
|
|
- Validate at trust boundaries — model output, file contents, network responses. Not between
|
|
internal functions.
|
|
- Duplication over premature abstraction. No interface with one implementation.
|
|
- Errors carry what the reader needs to act. `oldString appears 3 times in src/x.ts` beats
|
|
`edit failed`.
|
|
|
|
## Releasing
|
|
|
|
The version lives in `src/version.ts`, compiled into the binary. `package.json` carries it too
|
|
for tooling, and `bun run release` refuses to build if the two disagree, or if a git tag
|
|
disagrees with either:
|
|
|
|
```
|
|
$ GITHUB_REF_NAME=v9.9.9 bun run release
|
|
tag v9.9.9 does not match src/version.ts (0.1.0-beta.2). Bump the version or retag.
|
|
```
|
|
|
|
A binary reporting the wrong version is worse than a failed release.
|
|
|
|
To cut one:
|
|
|
|
```bash
|
|
# bump src/version.ts and package.json to the same value
|
|
git commit -am "release 0.1.0-beta.3"
|
|
git tag v0.1.0-beta.3
|
|
git push --follow-tags
|
|
```
|
|
|
|
`.github/workflows/release.yml` then runs typecheck and tests, cross-compiles all five
|
|
targets on one Ubuntu runner, asserts the built binary reports the expected version, and
|
|
publishes a GitHub release with the binaries and `SHA256SUMS`. A tag containing `-` is
|
|
published as a prerelease.
|
|
|
|
Bun cross-compiles from any host, which is why there is no build matrix. Verified: a working
|
|
`darwin-arm64` binary builds on Windows.
|
|
|
|
Publishing is gated on a `v*` tag, so a manual `workflow_dispatch` run produces artifacts
|
|
without releasing.
|
|
|
|
## CI
|
|
|
|
`.github/workflows/ci.yml` runs typecheck, tests, and a build on Ubuntu, macOS, and Windows
|
|
for every push and PR.
|
|
|
|
All three are necessary. The tools shell out to `rg`, `git`, and a platform shell, and path
|
|
handling differs — a Windows-only break is invisible on Linux until someone hits it.
|
|
|
|
## Debugging the agent itself
|
|
|
|
`--no-plugins --no-skills --no-memory --no-instructions --no-subagent --no-mcp` strips it to
|
|
the built-in tools alone, which isolates whether a problem is the loop or something layered on
|
|
it. `{ "toolSets": [] }` narrows it further, to the six core tools.
|
|
|
|
`--json` in headless mode shows the exact event sequence.
|
|
|
|
For provider issues, a local `Bun.serve` that logs the request body and returns a canned SSE
|
|
stream answers "what did we actually send" faster than any amount of reading. Several bugs in
|
|
this codebase were found that way. Making that stub *reject* the thing you think you fixed is
|
|
better still: the tool-pairing repair was confirmed by a stub that returned the real 400 for an
|
|
orphaned result, then stopped doing so.
|