Skip to content

v3.0.2

Choose a tag to compare

@github-actions github-actions released this 22 May 16:55
· 42 commits to main since this release
e3893fa
Helix chef + sdks (#919)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR introduces `helix chef`, a new CLI command that bootstraps a
full HelixDB app by orchestrating skill/MCP installation, project init,
DB startup, and launching a coding agent (Claude Code, Codex, or
OpenCode) with a structured prompt. It also adds new Rust and TypeScript
SDKs with type-safe DSL query builders and a cross-SDK parity test
suite.

- **`helix chef`** (`helix-cli/src/commands/chef.rs`, 2182 lines):
interactive/automatic setup flow, streaming Claude Code output via
`stream-json`, and a `run_quietly` helper that temporarily sets
verbosity to `Silent` while orchestrating sub-commands.
- **Rust SDK** (`sdks/rust/`): full DSL builder API plus an async HTTP
client; the `#[register]` macro generates typed query functions.
- **TypeScript SDK** (`sdks/typescript/src/index.ts`): parallel DSL
builder with a custom bigint-safe JSON serializer/parser and query
bundle generation.
- **Parity test suite** (`.github/workflows/parity_tests.yml`,
`sdks/tests/`, `sdks/typescript/scripts/parity/`): generates fixtures
from both SDKs, runs them against a live Helix instance, and diffs the
results.

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| helix-cli/src/commands/chef.rs | New `helix chef` onboarding command:
installs skills/MCP, initializes a project, starts DB, seeds data, and
launches a coding agent. Contains the process-global
`env::set_current_dir` concern and the unimplemented `--auto`/`--agent`
flags referenced in install.sh. |
| helix-cli/install.sh | Updated post-install instructions document
`helix chef --agent` and `helix chef --auto` flags that are not
implemented in the CLI, causing clap errors when users follow these
instructions. |
| .github/workflows/parity_tests.yml | New CI workflow for SDK DSL
parity tests. Installs the helix CLI from `main` branch rather than
building from the PR's source, which may produce false results when CLI
behavior is also changing. |
| sdks/typescript/src/index.ts | New TypeScript SDK: full query-builder
DSL mirroring the Rust SDK, with custom bigint-safe JSON
serializer/parser, property value types, and query bundle generation.
Implementation looks correct and well-structured. |
| sdks/rust/src/lib.rs | New Rust SDK HTTP client with builder pattern
for stored and dynamic queries. The known URL-joining behavior for
path-prefixed base URLs is already noted in a prior review thread. |
| helix-cli/src/output.rs | Adds a new `Silent` verbosity level
(shifting existing numeric values by 1) and a `show_quiet()` helper. The
default VERBOSITY value is updated correctly from 1 to 2 to maintain
Normal as default. |
| helix-cli/src/commands/query.rs | Query output is now gated on
`show_normal()` so chef's internal seed query doesn't print to stdout.
Correct behavior; default verbosity (Normal) preserves the existing
user-facing output. |
| sdks/typescript/scripts/parity/run-helix.ts | Parity test runner that
spins up Helix instances for both Rust and TypeScript SDK fixtures and
compares their outputs. The previously-flagged `spawnSync` OS-error
surfacing issue is tracked in an existing thread. |
| sdks/rust/src/dsl.rs | Large new Rust DSL module (5370 lines)
providing type-safe query-builder API for HelixDB. Comprehensive
coverage of all query constructs; no significant issues found. |

</details>

</details>

<details><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant User
    participant Chef as helix chef
    participant NPX as npx (skills/MCP)
    participant Init as helix init
    participant DB as helix run dev
    participant Query as helix query
    participant Agent as Coding Agent (Claude/Codex)
    participant Browser

    User->>Chef: helix chef
    Chef->>User: Prompts (intent, mode, dir)
    Chef->>NPX: npx skills add HelixDB/skills
    Chef->>NPX: npx add-mcp helixdb-docs
    Chef->>Init: init local (run_quietly)
    Chef->>Chef: write HELIX_CHEF_PROMPT.md + examples/
    Chef->>DB: helix run dev (run_quietly)
    Chef->>Query: helix query dev --file seed.json (run_quietly)
    Chef->>User: Prompt: Give agent full autonomy?
    Chef->>Agent: launch with --append-system-prompt-file
    loop stream-json events
        Agent-->>Chef: tool use events (Edit/Bash/Read...)
        Chef->>User: spinner update
    end
    Agent-->>Chef: ResultEvent (cost, duration, summary)
    Chef->>Browser: try_open_frontend (http://localhost:3000)
    Chef->>User: Final summary
```
</details>

<sub>Reviews (2): Last reviewed commit: ["updating
cli"](https://github.com/helixdb/helix-db/commit/49d3e42466a31f52679e760d19e94182b489c375)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=33039363)</sub>

> Greptile also left **1 inline comment** on this PR.

<!-- /greptile_comment -->