Sidecat
← Blog

June 2026

Package authoring starts in Starlark

This was the active Sidecat line when this note was written: package authoring. Not package names hiding Go code. Not a port of the old bespoke DSL. Packages should be things a package author can actually write, inspect, test, install, and run through the workbench.

What landed

The first proof is deliberately small:

  • The Starlark core package family provides generic result, input, tool, data, phase, and debug helpers.
  • packages/go-toolchain is a user-space Starlark package that depends on sidecat.core.
  • The package runtime can validate, install, list, test, and run packages through an explicit local registry.
  • The go-toolchain package reaches go version only through manifest-bound tool.exec.
  • packages/git-workbench now runs status, diff, summary, stage, unstage, local commit, and push flows through manifest-bound tool.exec, with plan/apply/verify commands where useful.
  • Contract level is selected by the operator/context; the package does not infer C3 or C4 from names like commit or push.
  • Path-based git calls use Starlark-side argv checks to deny unsafe paths before tool execution.
  • Status-oriented commands now return structured status entries and counts alongside raw git status text.
  • Package fixtures can now seed bounded temporary git workspaces, prepare staged/unstaged/committed/ahead states, create temporary bare remotes for push, and assert useful output plus ordered capability-call traces.

That is enough to prove the shape: a user package loads a core package, calls a declared host capability through shared Starlark helpers, returns typed output, and carries fixtures that exercise real repository state instead of only toy values. Those fixtures now also check the calls a package made, so unsafe paths can prove zero host calls before host execution. The git-workbench package also proves a package can compose more than one allowed tool call and return structured repository state without hiding the behavior in Go. The package now has plan/apply/verify loops for staging, unstaging, local commits, and push. plan_stage_paths previews the diff, structured status, and paths before stage_paths stages declared paths with git add --. The unstage path mirrors that with git restore --staged -- <paths>. Commit uses a manifest-bound text tail for git commit -m, and push uses exactly git push --porcelain. The push proof creates a temporary bare remote; it does not claim real-project remote push support. This is not arbitrary git.

What this is not

This is not a stable public package ecosystem. It is experimental early catfood for the authoring path, and Sidecat itself is still early and not recommended for use. The important claim is narrower: package behavior can now live in Starlark package files, while Go stays responsible for the substrate around loading, validation, fixtures, registry operations, and authority boundaries.

Why this matters

Sidecat is workbench-led. Agents should be able to do a messy thing once, save the useful move, and promote it toward a package when repetition makes that worthwhile. Strict custody remains available, but it should be selected by contract level, not forced onto every action.

Git is now doing that job. The first pressure point it exposed was argv: package code needs a reusable way to build path-tail commands, reject unsafe paths, and keep the final tool call inside the manifest boundary. The next pressure point was package-local domain behavior: Git-specific helpers belong in packages/git-workbench, while sidecat.core and friends stay generic. The next pressure point was mutation discipline: git-workbench now exposes separate plan, apply, and verify commands for staging, unstaging, local commit, and push. The remaining pressure is idempotency, persisted plans, contract levels, remote authority routing, and broader package ergonomics. Those questions should be exposed by Starlark packages first, not papered over by Go-only helpers.

- The Sidecat Dev project