release-drill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Membase Release Drill

Package → install → authenticate → verify skills → verify hooks, per client,
using the artifacts a real user would receive — never the working tree
directly. Run all five clients unless the user names one.

Ground rules:

- `$REPO` = this repo's absolute root. `$DRILL` = a scratch dir you create
  (e.g. `/tmp/membase-release-drill`). All built artifacts go in `$DRILL`.
- Evidence over green text: every VERIFY step names the exact observable
  (file mtime, backend search hit, skill list output). Report a table at the
  end: client × {install, auth, skills, hooks} with evidence.
- Auth is browser OAuth — you cannot complete it headless. CHECK auth state;
  when missing, give the user the exact login command and wait.
- Restore anything you disturb. The user's live setup (especially the
  OpenClaw gateway and the codex trust state) must survive the drill.
- If `pnpm check` or `pnpm test` is red at HEAD, stop and report — drilling a
  broken tree wastes everyone's time.

## Phase 0 — package everything

```bash
mkdir -p $DRILL
cd $REPO && pnpm check && pnpm test          # gates first
# openclaw (npm lineage): capture-core must be resolvable BEFORE the runtime
cd $REPO/packages/capture-core && pnpm pack --pack-destination $DRILL
cd $REPO/clients/openclaw/runtime && pnpm pack --pack-destination $DRILL
# hermes (PyPI lineage)
cd $REPO/clients/hermes/python && python3 -m build --outdir $DRILL
# membase-cli (npm)
cd ~/Desktop/membase/membase-cli && bun run build && npm pack --pack-destination $DRILL
```

Sanity on the tarballs (catches "files" allowlist regressions):
- runtime tarball contains `openclaw.plugin.json`, `index.ts`, `src/` WITHOUT
  `*.test.ts`; its package.json dependency on `@membase/capture-core` is an
  exact version (workspace:* rewritten), and that version equals the
  capture-core tarball's.
- wheel contains `wiki_project.py`, `current_date.py`, `plugin/plugin.yaml`
  (`unzip -l $DRILL/*.whl`).

## Phase 1+2 — install + auth, per client

Install matrix (local artifacts, no network registries):

| client   | command |
|----------|---------|
| claude   | `claude plugin marketplace add $REPO && claude plugin install membase@membase-plugins` |
| codex    | `npx -y plugins add $REPO -t codex -y && codex plugin add membase@personal` |
| cursor   | `npx -y plugins add $REPO -t cursor -y` (macOS: lands in Claude's plugin cache — that is expected, not a bug) |
| openclaw | local registry (see verdaccio setup below) → publish capture-core tgz, then the runtime tgz → `npm_config_registry=http://localhost:4873 openclaw plugins install @membase/openclaw-membase --force` |
| hermes   | `uv tool install $DRILL/hermes_membase-*-py3-none-any.whl --force && hermes-membase install --skip-login` (use `HERMES_HOME=$DRILL/hermes-home` to keep the drill isolated) |

Verdaccio setup (publish REQUIRES an authenticated user even with
`publish: $all` — learned the hard way):

```bash
cat > $DRILL/verdaccio.yaml <<'EOF'
storage: /tmp/membase-release-drill/verdaccio-storage
uplinks: { npmjs: { url: https://registry.npmjs.org/ } }
packages:
  '@membase/*': { access: $all, publish: $all }
  '**': { access: $all, publish: $all, proxy: npmjs }
auth: { htpasswd: { file: /tmp/membase-release-drill/htpasswd, max_users: 1000 } }
EOF
npx -y verdaccio --config $DRILL/verdaccio.yaml --listen 4873 &
# register a user via the legacy PUT API and capture the token:
curl -s -X PUT http://localhost:4873/-/user/org.couchdb.user:drilluser \
  -H "Content-Type: application/json" \
  -d '{"name":"drilluser","password":"drillpass123","type":"user"}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])"
echo "//localhost:4873/:_authToken=<TOKEN>" > $DRILL/.npmrc-drill
npm publish --registry http://localhost:4873 --userconfig $DRILL/.npmrc-drill <tgz>
```

After the openclaw install, ALWAYS check which source is ACTIVE — a
pre-existing config-selected dev link silently wins over the npm install
(`openclaw plugins list` prints a "not the active source" warning). An
install that succeeded but is not active verifies packaging, not loading.

Or route everything through the CLI under test:
`node ~/Desktop/membase/membase-cli/bin/run --client <name>` — this
additionally exercises the routing, the codex identity registration, and the
codex hook-command repair. Prefer it for claude/codex/cursor; openclaw/hermes
need the local-artifact commands above until the packages are published.

Auth state checks (per-client hook credentials are separate from the
client's own MCP OAuth):

Claude auth MUST be checked with the plugin's own `get_status` tool (via the
`plugin:membase:membase` MCP server), not by assuming: a machine can have BOTH
the plugin's local stdio server AND a remote `mcp.membase.so` entry (from an
old membase-cli install). The remote one answering does NOT mean the plugin is
logged in — `get_status` reporting `logged_in: false` while recall "works"
means every request is riding the remote path and hook capture is dead. It
also self-reports `duplicate_remote_mcp_configs` — surface that to the user.

| client   | hook credentials at | login command when missing |
|----------|--------------------|----------------------------|
| claude   | `~/.claude/plugins/membase/credentials.json` | `/membase:login` inside Claude Code |
| codex    | `~/.membase/codex/credentials.json` | drive the bundled server's `login` tool (see `scripts` note below) or any prior scripted login |
| cursor   | `~/.claude/plugins/membase/…` (shared cache) | via Claude Code login |
| openclaw | `~/.openclaw/credentials/openclaw-membase.json` | `openclaw membase login` |
| hermes   | `$HERMES_HOME/credentials/membase.json` | `hermes-membase login` |

## Phase 3 — verify skills

- **claude**: `claude plugin list` shows membase enabled; ask a throwaway
  `claude -p` session to list skills and expect the membase skill names.
- **codex**: `codex exec --skip-git-repo-check "List every skill identifier
  starting with 'membase'"` → expect all 7 `membase:*` entries. If none:
  check `codex plugin list` shows `membase@personal` **installed, enabled**
  (the plugins-cli config key alone is NOT enough — known identity mismatch).
- **cursor**: skills ride the shared Claude cache; verify the cache path in
  `~/.claude/plugins/` contains `skills/`. Interactive check is manual.
- **openclaw**: `openclaw plugins list` shows the plugin enabled with 10
  tools; `openclaw membase --help` lists the CLI surface (search/add/wiki
  with `--project`).

From aristoapp/membase, MIT.

More from aristoapp/membase