From 88fdb19dc844bb3a6abc17cc5a7d2893929a0b07 Mon Sep 17 00:00:00 2001 From: Zhihao Zhang Date: Sat, 23 May 2026 09:29:27 +0000 Subject: [PATCH] fix(install): bundle quickstart skill and clarify PATH activation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two issues blocked users following the README's curl-piped install path: 1. agentvfs-quickstart (start.sh, renamed) reads docs/skills/agentvfs-workspace.md relative to its own directory to write ~/.claude/skills/agentvfs-workspace/SKILL.md and ~/.codex/AGENTS.md. The release tarball didn't include this file, so every quickstart invocation outside a source checkout failed with "skill source not found". Fix: release.yml stages docs/skills/agentvfs-workspace.md into each tarball (linux/darwin-arm64/darwin-x86_64) and install.sh installs it alongside the binaries with 0644 perms. start.sh now probes $SCRIPT_DIR/docs/skills/agentvfs-workspace.md (repo mode) then $SCRIPT_DIR/agentvfs-workspace.md (installed mode) and emits a clearer multi-line error if neither is present. 2. The "Note: $PREFIX is not in your PATH" message listed two commands without indicating which was for the current shell vs which persisted for future shells. Users persisted to ~/.bashrc and then ran agentvfs-quickstart in the same session, which still had the old PATH. Fix: install.sh now prints labeled "1) Activate in the current shell (run this NOW)" and "2) Persist for future shells (run this ONCE)" steps, and suggests the rc file matching the host OS's typical login shell (zsh on macOS, bash on Linux) with the other as a one-line fallback hint. Tested: - bash -n start.sh / sh -n install.sh / yaml.safe_load on release.yml — all clean - end-to-end test of start.sh against three layouts (repo-checkout, packaged-flat, missing-skill) using a stubbed `agentvfs` binary — all three behave as expected - visual diff of the new PATH note across linux/macos with PREFIX both in and out of PATH Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/release.yml | 9 ++++++--- install.sh | 23 ++++++++++++++++++++--- start.sh | 23 ++++++++++++++++++++--- 3 files changed, 46 insertions(+), 9 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4eaee42..b8dab21 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -27,8 +27,9 @@ jobs: cp build/agentvfs build/agentvfs-ctl LICENSE "$stage/" cp start.sh "$stage/agentvfs-quickstart" chmod +x "$stage/agentvfs-quickstart" + cp docs/skills/agentvfs-workspace.md "$stage/agentvfs-workspace.md" tar -C "$stage" -czf "agentvfs-${version}-linux-x86_64.tar.gz" \ - agentvfs agentvfs-ctl agentvfs-quickstart LICENSE + agentvfs agentvfs-ctl agentvfs-quickstart agentvfs-workspace.md LICENSE - uses: actions/upload-artifact@v4 with: name: linux-x86_64 @@ -52,8 +53,9 @@ jobs: cp build/agentvfs build/agentvfs-ctl LICENSE "$stage/" cp start.sh "$stage/agentvfs-quickstart" chmod +x "$stage/agentvfs-quickstart" + cp docs/skills/agentvfs-workspace.md "$stage/agentvfs-workspace.md" tar -C "$stage" -czf "agentvfs-${version}-darwin-arm64.tar.gz" \ - agentvfs agentvfs-ctl agentvfs-quickstart LICENSE + agentvfs agentvfs-ctl agentvfs-quickstart agentvfs-workspace.md LICENSE - uses: actions/upload-artifact@v4 with: name: darwin-arm64 @@ -77,8 +79,9 @@ jobs: cp build/agentvfs build/agentvfs-ctl LICENSE "$stage/" cp start.sh "$stage/agentvfs-quickstart" chmod +x "$stage/agentvfs-quickstart" + cp docs/skills/agentvfs-workspace.md "$stage/agentvfs-workspace.md" tar -C "$stage" -czf "agentvfs-${version}-darwin-x86_64.tar.gz" \ - agentvfs agentvfs-ctl agentvfs-quickstart LICENSE + agentvfs agentvfs-ctl agentvfs-quickstart agentvfs-workspace.md LICENSE - uses: actions/upload-artifact@v4 with: name: darwin-x86_64 diff --git a/install.sh b/install.sh index 58319fb..637ea18 100755 --- a/install.sh +++ b/install.sh @@ -107,8 +107,20 @@ mkdir -p "$PREFIX" for f in agentvfs agentvfs-ctl agentvfs-quickstart; do [ -f "$WORK/$f" ] && install -m 0755 "$WORK/$f" "$PREFIX/$f" done +# agentvfs-quickstart reads this file at runtime to write +# ~/.claude/skills/agentvfs-workspace/SKILL.md and ~/.codex/AGENTS.md. +[ -f "$WORK/agentvfs-workspace.md" ] && \ + install -m 0644 "$WORK/agentvfs-workspace.md" "$PREFIX/agentvfs-workspace.md" # Final message. +# Suggest the rc file for the most common login shell on this OS so the +# user knows where to persist the PATH addition. +if [ "$os" = darwin ]; then + default_rc="~/.zshrc"; alt_rc="~/.bashrc" +else + default_rc="~/.bashrc"; alt_rc="~/.zshrc" +fi + echo echo "Installed agentvfs $VERSION to $PREFIX" echo @@ -117,10 +129,15 @@ case ":$PATH:" in echo "next: agentvfs-quickstart /path/to/project" ;; *) - echo "Note: $PREFIX is not in your PATH. Add it:" + echo "Note: $PREFIX is not in your PATH." + echo + echo " # 1) Activate in the current shell (run this NOW):" echo " export PATH=\"$PREFIX:\$PATH\"" - echo " echo 'export PATH=\"$PREFIX:\$PATH\"' >> ~/.bashrc # or ~/.zshrc" echo - echo "Then: agentvfs-quickstart /path/to/project" + echo " # 2) Persist for future shells (run this ONCE):" + echo " echo 'export PATH=\"$PREFIX:\$PATH\"' >> $default_rc" + echo " # (use $alt_rc if that's your login shell)" + echo + echo "Then run: agentvfs-quickstart /path/to/project" ;; esac diff --git a/start.sh b/start.sh index 8d53592..d438648 100755 --- a/start.sh +++ b/start.sh @@ -85,10 +85,27 @@ if ! command -v agentvfs >/dev/null 2>&1; then fi SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" -SKILL_SRC="$SCRIPT_DIR/docs/skills/agentvfs-workspace.md" +# In a repo checkout the skill source lives under docs/skills/. In a +# packaged install (release.yml + install.sh) it's bundled flat next to +# the renamed agentvfs-quickstart script. +SKILL_SRC="" +for candidate in \ + "$SCRIPT_DIR/docs/skills/agentvfs-workspace.md" \ + "$SCRIPT_DIR/agentvfs-workspace.md"; do + if [[ -f "$candidate" ]]; then + SKILL_SRC="$candidate" + break + fi +done -if [[ ! -f "$SKILL_SRC" ]]; then - echo "start.sh: skill source not found at $SKILL_SRC — run start.sh from the agentvfs repo checkout" >&2 +if [[ -z "$SKILL_SRC" ]]; then + echo "start.sh: skill source not found." >&2 + echo " searched: $SCRIPT_DIR/docs/skills/agentvfs-workspace.md" >&2 + echo " $SCRIPT_DIR/agentvfs-workspace.md" >&2 + echo " If you installed via install.sh, this is a packaging bug — please" >&2 + echo " report at https://github.com/thustorage/ContextFS/issues." >&2 + echo " If you're running from a repo checkout, make sure" >&2 + echo " docs/skills/agentvfs-workspace.md exists." >&2 exit 1 fi