From aa4017f025aa94bfd4bbdac7729cec42d88bb089 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 16:46:15 +0000 Subject: [PATCH] docs(exec): remove the sh driver The sh driver was removed in hephbuild/heph#397 (heph@44ccc91): its `sh -u -e` run has no portable pipefail, so a pipeline reported only its last stage's status and a failing producer could look like a success. The exec plugin now registers two drivers, exec and bash, and bash is a pipefail-safe superset of what sh offered. Updates the Exec plugin page, the buildfile example that used `driver = "sh"`, and the sh mentions across the heph-expert and heph-go skill/agent/command references (per the reference-drift rule in CLAUDE.md), bumping both plugins' and the marketplace's patch version. --- .claude-plugin/marketplace.json | 2 +- .../heph-expert/.claude-plugin/plugin.json | 2 +- plugins/heph-expert/agents/heph-expert.md | 2 +- plugins/heph-expert/commands/heph-debug.md | 2 +- plugins/heph-expert/commands/heph-target.md | 2 +- plugins/heph-expert/skills/heph/SKILL.md | 6 ++--- .../skills/heph/references/authoring.md | 8 +++--- .../heph-expert/skills/heph/references/cli.md | 2 +- .../skills/heph/references/concepts.md | 2 +- .../skills/heph/references/configuration.md | 2 +- .../skills/heph/references/plugins.md | 4 +-- plugins/heph-go/.claude-plugin/plugin.json | 2 +- plugins/heph-go/agents/heph-go-expert.md | 2 +- plugins/heph-go/commands/heph-go-codegen.md | 2 +- plugins/heph-go/skills/heph-go/SKILL.md | 4 +-- .../skills/heph-go/references/go-plugin.md | 2 +- website/docs/plugins/buildfile.md | 4 +-- website/docs/plugins/exec.md | 27 +++++++------------ 18 files changed, 35 insertions(+), 42 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 263e329..e45c2bd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-marketplace.json", "name": "heph-marketplace", - "version": "0.1.1", + "version": "0.1.2", "description": "Claude Code plugins for the heph build system, co-located with the docs.", "owner": { "name": "hephbuild", diff --git a/plugins/heph-expert/.claude-plugin/plugin.json b/plugins/heph-expert/.claude-plugin/plugin.json index 0d539d5..6461d4a 100644 --- a/plugins/heph-expert/.claude-plugin/plugin.json +++ b/plugins/heph-expert/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin.json", "name": "heph-expert", - "version": "0.1.1", + "version": "0.1.2", "description": "Expert assistance for the heph build system: author BUILD files, debug caching and sandbox issues, wire up CI, and explain the target graph.", "author": { "name": "hephbuild" diff --git a/plugins/heph-expert/agents/heph-expert.md b/plugins/heph-expert/agents/heph-expert.md index 4092e12..6db63b0 100644 --- a/plugins/heph-expert/agents/heph-expert.md +++ b/plugins/heph-expert/agents/heph-expert.md @@ -64,7 +64,7 @@ exactly right and might have changed, fetch the live doc page (the docs expose a rebuild on unrelated changes. 7. **Debug in the sandbox.** For failures, reach for `heph run --shell` - (bash/sh) to reproduce with the exact inputs/tools/env, rather than adding + (bash driver) to reproduce with the exact inputs/tools/env, rather than adding prints or loosening isolation. ## Output style diff --git a/plugins/heph-expert/commands/heph-debug.md b/plugins/heph-expert/commands/heph-debug.md index 3caa798..98226af 100644 --- a/plugins/heph-expert/commands/heph-debug.md +++ b/plugins/heph-expert/commands/heph-debug.md @@ -15,7 +15,7 @@ Work through this, narrating findings concisely: outputs, tools and sandbox config are what you expect. `heph inspect spec ` shows the raw provider spec if the resolved def looks wrong. -2. **Reproduce in the sandbox.** `heph run --shell` (bash/sh drivers) +2. **Reproduce in the sandbox.** `heph run --shell` (bash driver) drops you into the exact inputs/tools/env. Inside, inspect `$SRC_*`, `$TOOL_*`, `$OUT*`, `$LIST_SRC_*`, and re-run the `run` command by hand to see the real error. diff --git a/plugins/heph-expert/commands/heph-target.md b/plugins/heph-expert/commands/heph-target.md index 64923a4..0f1290c 100644 --- a/plugins/heph-expert/commands/heph-target.md +++ b/plugins/heph-expert/commands/heph-target.md @@ -15,7 +15,7 @@ Steps: `.hephconfig` `buildfile.patterns`). The package is the workspace-relative directory; the target address will be `//:`. -2. **Pick the driver.** `bash`/`sh`/`exec` for shell actions, `nix` for a pinned +2. **Pick the driver.** `bash`/`exec` for shell actions, `nix` for a pinned toolchain, `textfile` for a generated text file, `group` to bundle. For Go code, do NOT write `target()` — the `go` provider generates `:build`/`:test` automatically; hand the user off to the dedicated **`heph-go`** plugin diff --git a/plugins/heph-expert/skills/heph/SKILL.md b/plugins/heph-expert/skills/heph/SKILL.md index 0730012..02d920b 100644 --- a/plugins/heph-expert/skills/heph/SKILL.md +++ b/plugins/heph-expert/skills/heph/SKILL.md @@ -6,13 +6,13 @@ description: >- .hephconfig, BUILD files with target()/glob()/file(), heph addresses like //pkg:name or //@heph/..., the heph CLI (heph run, heph inspect, heph query, heph validate, heph tool gc/gen-gitignore), heph caching/cache hits, target - sandboxes, codegen (copy / in_place), output groups, drivers (bash, sh, exec, + sandboxes, codegen (copy / in_place), output groups, drivers (bash, exec, nix, go_*) or providers (buildfile, go, query). Also use it for ANY task that involves writing, reading, debugging, or reviewing heph BUILD files, tuning .hephconfig, diagnosing why a target rebuilt or a cache missed, or setting up heph in CI — even when the user does not say the word "heph" explicitly but the files or commands make it clear. -version: 0.1.1 +version: 0.1.2 --- # heph build system @@ -85,7 +85,7 @@ is self-contained and mirrors the official docs. show the resolved/raw definition. Nothing executes unless a provider must run to answer. 4. **Debug failures in the sandbox.** `heph run --shell` drops into the - exact inputs/tools/env the target runs with (bash/sh drivers). Recommend this + exact inputs/tools/env the target runs with (bash driver). Recommend this over adding debug prints. 5. **Distinguish the three dependency kinds** (`deps` / `hash_deps` / `runtime_deps`) and the three codegen-vs-cache choices — they are the most diff --git a/plugins/heph-expert/skills/heph/references/authoring.md b/plugins/heph-expert/skills/heph/references/authoring.md index b1dfadd..3f918b8 100644 --- a/plugins/heph-expert/skills/heph/references/authoring.md +++ b/plugins/heph-expert/skills/heph/references/authoring.md @@ -43,13 +43,13 @@ Only these fields are interpreted by the engine/buildfile: | Field | Required | Meaning | |---|---|---| | `name` | yes | Target name within its package. | -| `driver` | no* | Driver that executes it (`bash`, `sh`, `exec`, `nix`, `group`, …). Required when `defaultDriver` is not set in the buildfile provider options. | +| `driver` | no* | Driver that executes it (`bash`, `exec`, `nix`, `group`, …). Required when `defaultDriver` is not set in the buildfile provider options. | | `labels` | no | Label or list of labels, used by `query` and matchers. | | `transitive` | no | Sandbox settings propagated to dependents. | **Everything else** (`run`, `deps`, `out`, `env`, `cache`, `codegen`, …) is **driver-defined**: buildfile forwards it verbatim to the named driver. For the -exec drivers (`bash`/`sh`/`exec`) those fields are documented below. +exec drivers (`bash`/`exec`) those fields are documented below. ```python title="BUILD" lib = target(name = "lib", driver = "bash", run = "go build -o $OUT .", out = "lib") @@ -147,8 +147,8 @@ go_service(name = "api") ## Exec driver fields -The `exec` plugin registers three drivers: `exec` (direct execution), `bash` -(bash with job control), `sh` (POSIX shell). `bash`/`sh` support interactive +The `exec` plugin registers two drivers: `exec` (direct execution), `bash` +(bash with job control, `-o pipefail`). `bash` supports interactive `--shell` mode with PTY allocation. Target config keys: | Key | Meaning | diff --git a/plugins/heph-expert/skills/heph/references/cli.md b/plugins/heph-expert/skills/heph/references/cli.md index 924df3b..6a2aea7 100644 --- a/plugins/heph-expert/skills/heph/references/cli.md +++ b/plugins/heph-expert/skills/heph/references/cli.md @@ -23,7 +23,7 @@ heph run