diff --git a/AGENTS.md b/AGENTS.md index 3cc50d4..a9e23b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,16 +53,10 @@ CHANGELOG.md # Keep-a-Changelog format, backfilled through v0.1.2 ## Distribution -**Current blessed install (git-install, pre-npm):** -```json -{ "plugin": ["opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.2"] } -``` - -**Future canonical install (npm, once published):** +**Canonical install (npm):** ```json { "plugin": ["@stablekernel/opencode-bgrun@0.1.2"] } ``` -Once npm is live, git-install references should be removed from docs. **Human CLI on PATH (optional, notify-only):** ```bash diff --git a/README.md b/README.md index 913af6b..0042590 100644 --- a/README.md +++ b/README.md @@ -91,22 +91,22 @@ scripts called from the agent via a bash tool. ## Install details -### Recommended: git-install via `opencode.json` (coworkers / CI) +### Recommended: npm install via `opencode.json` (coworkers / CI) Add the following entry to the `plugins` array in your `opencode.json`: ```json { "plugins": [ - "opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1" + "@stablekernel/opencode-bgrun@0.1.2" ] } ``` OpenCode installs the package into -`~/.cache/opencode/packages//node_modules/opencode-bgrun/` and loads the plugin -automatically on startup. No PATH setup is needed for the **agent (tool) path** — the plugin -resolves `bin/bgrun` by absolute path at runtime. +`~/.cache/opencode/packages/@stablekernel/opencode-bgrun@/node_modules/@stablekernel/opencode-bgrun/` +and loads the plugin automatically on startup. No PATH setup is needed for the **agent (tool) +path** — the plugin resolves `bin/bgrun` by absolute path at runtime. ### Local / dev install (repo clone) @@ -131,18 +131,28 @@ is required for the tool registration and completion poller to become active. ### Optional: human shell CLI The **`bgrun` tool** (plugin-registered) is what AI agents call and it works automatically -from the git-install — no PATH setup required. It also delivers the session-wake feature. +from the npm install — no PATH setup required. It also delivers the session-wake feature. The human shell commands (`bgrun`, `bgstatus`, `bgtail`, `bgclean`) are **optional and notify-only** — they fire a desktop notification on completion but do **not** wake an agent -session. (Agent-wake is exclusively the plugin `bgrun` tool.) After a git-install via +session. (Agent-wake is exclusively the plugin `bgrun` tool.) After an npm install via `opencode.json` those scripts are **not on your PATH**; typing `bgrun` in a terminal will produce `command not found`. #### Recommended: `install.sh --cli-only` -Run `./install.sh --cli-only` to symlink just the four CLI scripts into `~/.local/bin` without -touching the plugin or skill (which the git-install already provides): +**Recommended:** install via npm global: + +```bash +npm i -g @stablekernel/opencode-bgrun +``` + +This puts `bgrun`, `bgstatus`, `bgtail`, and `bgclean` on your PATH automatically via npm's +bin map. + +Alternatively, if you have the repo cloned, run `./install.sh --cli-only` to symlink just +the four CLI scripts into `~/.local/bin` without touching the plugin or skill (which the npm +install already provides): ```bash # If you have the repo cloned: @@ -153,13 +163,13 @@ touching the plugin or skill (which the git-install already provides): ``` `--cli-only` also works **without a clone** when the plugin is already installed via the -`opencode.json` git-spec. It auto-discovers the scripts inside OpenCode's package cache at: +`opencode.json` npm spec. It auto-discovers the scripts inside OpenCode's package cache at: ``` -~/.cache/opencode/packages/opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1/node_modules/opencode-bgrun/bin +~/.cache/opencode/packages/@stablekernel/opencode-bgrun@/node_modules/@stablekernel/opencode-bgrun/bin/ ``` -The version tag in the path is discovered dynamically, so it keeps working across version +The version segment in the path is discovered dynamically, so it keeps working across version bumps. To use this mode you need the `install.sh` script itself — grab it from the repo or copy it from the cache dir above. @@ -167,11 +177,10 @@ To remove: `./uninstall.sh --cli-only`. #### Manual alternative -If you prefer, symlink directly from the cache. The path contains `#`, `:`, and `@` so it -**must be quoted**: +If you prefer, symlink directly from the npm global cache: ```bash -PKG="$HOME/.cache/opencode/packages/opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1/node_modules/opencode-bgrun" +PKG="$HOME/.cache/opencode/packages/@stablekernel/opencode-bgrun@0.1.2/node_modules/@stablekernel/opencode-bgrun" mkdir -p "$HOME/.local/bin" for cmd in bgrun bgstatus bgtail bgclean; do ln -sf "$PKG/bin/$cmd" "$HOME/.local/bin/$cmd" diff --git a/install.sh b/install.sh index 590a8d5..3af7c58 100755 --- a/install.sh +++ b/install.sh @@ -6,12 +6,12 @@ # • Symlinks bin/, plugin/, and skill/ into the user's config dirs. # # --cli-only: PATH-only install for users who already have the plugin installed -# via the git-install spec in opencode.json. +# via the npm plugin spec in opencode.json. # • Skips npm, plugin symlink, and skill symlink. # • Discovers CLI scripts from (a) this repo clone or (b) the OpenCode cache. # # Safe to re-run; replaces existing symlinks, never clobbers real files. -# Coworkers: use the git-install plugin spec in the README instead. +# Coworkers: use the npm plugin spec in the README instead. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" @@ -34,7 +34,7 @@ Usage: install.sh [OPTIONS] Options: --cli-only Install only the 4 CLI scripts (bgrun bgstatus bgtail bgclean) onto PATH (~/.local/bin/). Skips npm install, plugin symlink, - and skill symlink. Useful for git-install users who already + and skill symlink. Useful for npm-install users who already have the plugin loaded via opencode.json and just want shell access to the bg* helpers. @@ -46,8 +46,9 @@ Modes: --cli-only PATH-only install. Source priority: 1. /bin/ (if running from a clone) - 2. ~/.cache/opencode/packages/opencode-bgrun@.../bin/ - (auto-discovered from OpenCode's plugin cache) + 2. ~/.cache/opencode/packages/@stablekernel/opencode-bgrun@.../ + node_modules/@stablekernel/opencode-bgrun/bin/ + (auto-discovered from OpenCode's plugin cache) If neither source is found, installation fails with guidance. EOF } @@ -118,17 +119,15 @@ if [ "$CLI_ONLY" -eq 1 ]; then ok "Linking CLI from: $CLI_SRC (repo clone)" else # (b) Discover from OpenCode plugin cache - # The cache path contains @ : # and an embedded / in the package spec, - # so the package spec spans two path segments: - # opencode-bgrun@github:stablekernel / opencode-bgrun#v0.1.1 - # We glob over both segments to handle any version. + # The npm cache path is well-formed: @stablekernel/opencode-bgrun@/ + # We glob over the version segment to handle any installed version. CACHE_MATCH="" CACHE_COUNT=0 # Expand the glob manually; iterate over potential matches. # Using a for loop with a glob is safe — bash expands it before the loop. # We use a sub-glob for the two-segment package spec, then check each hit. - for candidate in "$HOME"/.cache/opencode/packages/opencode-bgrun@*/opencode-bgrun*/node_modules/opencode-bgrun/bin; do + for candidate in "$HOME"/.cache/opencode/packages/@stablekernel/opencode-bgrun@*/node_modules/@stablekernel/opencode-bgrun/bin; do # If the glob found no matches, bash leaves the literal pattern — # check that the candidate actually exists as a directory. if [ -d "$candidate" ]; then @@ -144,7 +143,7 @@ if [ "$CLI_ONLY" -eq 1 ]; then printf " To fix, do one of:\n" printf " 1. Run this script from a repo clone (git clone stablekernel/opencode-bgrun).\n" printf " 2. Add the plugin to opencode.json first:\n" - printf " \"plugins\": [\"opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1\"]\n" + printf " \"plugins\": [\"@stablekernel/opencode-bgrun@0.1.2\"]\n" printf " then let OpenCode fetch it, and re-run: install.sh --cli-only\n" exit 1 fi @@ -152,7 +151,7 @@ if [ "$CLI_ONLY" -eq 1 ]; then if [ "$CACHE_COUNT" -gt 1 ]; then warn "Multiple cached plugin versions found — using the last (lexically highest) match." warn "Matches found:" - for candidate in "$HOME"/.cache/opencode/packages/opencode-bgrun@*/opencode-bgrun*/node_modules/opencode-bgrun/bin; do + for candidate in "$HOME"/.cache/opencode/packages/@stablekernel/opencode-bgrun@*/node_modules/@stablekernel/opencode-bgrun/bin; do if [ -d "$candidate" ]; then warn " $candidate" fi diff --git a/skill/run-bg/SKILL.md b/skill/run-bg/SKILL.md index 43e621c..eae65af 100644 --- a/skill/run-bg/SKILL.md +++ b/skill/run-bg/SKILL.md @@ -82,7 +82,7 @@ as a fallback when no `.session` sidecar is present. **The plugin is required on OpenCode.** Without it, the human desktop notification still fires, but there is no live agent wake. Install the plugin by adding -`opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1` to the `plugin` array in your +`@stablekernel/opencode-bgrun@0.1.2` to the `plugin` array in your `opencode.json` (recommended), or run `./install.sh` from a repo clone for local dev. Restart OpenCode either way. See Setup below. @@ -108,18 +108,19 @@ deliverables. Today `bgrun` handles them at the notification rung only. ## Setup (one-time) -**1. Recommended — plugin via git-install:** +**1. Recommended — plugin via npm:** Add the spec to the `plugin` array in your `opencode.json`: ```json -{ "plugin": ["opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1"] } +{ "plugin": ["@stablekernel/opencode-bgrun@0.1.2"] } ``` OpenCode fetches the package automatically on next start. Restart OpenCode to load the plugin. This gives you the agent-facing `bgrun` tool and the session-wake feature. It does **not** put the human shell CLIs (`bgrun`, `bgstatus`, `bgtail`, `bgclean`) on your PATH. **2. Human shell CLI (optional, notify-only):** -To also get the shell CLIs on your PATH, run `./install.sh --cli-only`. It works from a -clone, or auto-discovers the git-installed package in OpenCode's cache without a clone. +Recommended: `npm i -g @stablekernel/opencode-bgrun` — puts all four CLI scripts on your +PATH via npm's bin map. Alternatively, run `./install.sh --cli-only` from a clone, or +auto-discovers the npm-installed package in OpenCode's cache without a clone. `./install.sh --help` shows all modes. Remove with `./uninstall.sh --cli-only`. **3. Local dev (from a clone):** diff --git a/uninstall.sh b/uninstall.sh index 90a479b..8ed0a56 100755 --- a/uninstall.sh +++ b/uninstall.sh @@ -62,7 +62,7 @@ done # Usage: remove_link # Accepted roots: # 1. $SCRIPT_DIR (dev/clone install) -# 2. $HOME/.cache/opencode/packages/ containing "opencode-bgrun" (git-install) +# 2. $HOME/.cache/opencode/packages/ containing "@stablekernel/opencode-bgrun" (npm install) remove_link() { local dest="$1"