@vibecodr/cli 0.1.8

package/docs/contributors.md

@@ -0,0 +1,68 @@
+# Contributors
+
+## Runtime
+
+- Node `>=22 <26`
+- local development is currently exercised on Node 24
+
+## Core commands
+
+```bash
+npm install
+npm run check
+npm test
+npm run test:live-smoke
+npm run build
+npm run verify
+node dist/bin/vibecodr-mcp.js help
+```
+
+## Useful smoke checks
+
+```bash
+node dist/bin/vibecodr-mcp.js status --json
+node dist/bin/vibecodr-mcp.js doctor --json --non-interactive
+node dist/bin/vibecodr-mcp.js tools --json --non-interactive
+node dist/bin/vibecodr-mcp.js call get_vibecodr_platform_overview --json --non-interactive
+```
+
+`tools` does not force auth for public catalogs. Protected `call` flows will refresh or trigger login on challenge.
+
+## Profiles
+
+Create a staging profile:
+
+```bash
+node dist/bin/vibecodr-mcp.js config profile create staging --server-url https://staging-openai.vibecodr.space/mcp
+node dist/bin/vibecodr-mcp.js config profile use staging
+```
+
+## Registration mode forcing
+
+Examples:
+
+```bash
+node dist/bin/vibecodr-mcp.js login --registration dcr
+node dist/bin/vibecodr-mcp.js login --registration manual
+```
+
+Current repo reality:
+
+- the official production path uses the committed client metadata document URL `https://openai.vibecodr.space/.well-known/oauth-client/vibecodr-mcp.json`
+- CIMD mode requires `VIBECDR_MCP_CIMD_CLIENT_ID`
+- manual mode can use `VIBECDR_MCP_MANUAL_CLIENT_ID` or an interactive prompt
+
+## Mock fixtures and deeper integration
+
+Automated coverage now includes:
+
+- parser and renderer behavior
+- interactive schema prompting for nested objects and arrays
+- command-level install smoke for Codex, Cursor, VS Code workspace scope, and Windsurf
+- a mock OAuth/MCP fixture that exercises DCR login, loopback callback handling, protected tools/list, protected tools/call, refresh, invalid_grant clearing, and logout revocation behavior
+- a live smoke suite that validates the official first-party auth bootstrap and public tool discovery/call against `https://openai.vibecodr.space/mcp`
+
+Still not covered in automation:
+
+- real live browser login against the hosted service with account credentials
+- real client-application installs across Codex/Cursor/VS Code/Windsurf on CI hosts

package/docs/install.md

@@ -0,0 +1,90 @@
+# Install
+
+This repo now includes `install` and `uninstall` adapters, but the direct runtime core remains the primary product surface.
+
+## Current recommended use
+
+One-shot install without publishing:
+
+```bash
+npm install
+npm run build
+node dist/bin/vibecodr-mcp.js install codex --json
+```
+
+After the package is published:
+
+```bash
+npx -y -p @vibecodr/cli vibecodr install codex
+```
+
+Direct CLI-only usage:
+
+```bash
+npx -y -p @vibecodr/cli vibecodr login
+npx -y -p @vibecodr/cli vibecodr tools --json
+```
+
+## Client commands
+
+### Codex
+
+```bash
+vibecodr install codex
+```
+
+Behavior now:
+
+- prefers `codex mcp add <name> --url <server-url>`
+- falls back to TOML merge in `~/.codex/config.toml`
+- user scope only
+
+### Cursor
+
+```bash
+vibecodr install cursor --scope user
+vibecodr install cursor --scope project --path .
+```
+
+Behavior now:
+
+- writes `~/.cursor/mcp.json` for user scope
+- writes `.cursor/mcp.json` for project scope
+- `--open-client` also opens the current Cursor deeplink install URI
+
+### VS Code
+
+```bash
+vibecodr install vscode --scope user
+vibecodr install vscode --scope project --path .
+```
+
+Behavior now:
+
+- user scope prefers `code --add-mcp`
+- if `code` is unavailable and `--open-client` is set, opens the documented `vscode:mcp/install?...` URI
+- project scope writes `.vscode/mcp.json`
+
+### Windsurf
+
+```bash
+vibecodr install windsurf
+```
+
+Behavior now:
+
+- writes `~/.codeium/windsurf/mcp_config.json`
+- warns in docs about the legacy plugin path
+
+## Important split
+
+Install config is not runtime auth.
+
+- `install` configures the client
+- `login` authenticates the CLI itself
+- each editor still owns its own MCP OAuth state
+
+## Current limitations
+
+- VS Code user-scope uninstall is not automated with a documented removal surface yet
+- install adapters are implemented, but they are intentionally thin and never used for runtime `tools` or `call`

package/docs/licensing.md

@@ -0,0 +1,20 @@
+# Licensing
+
+This repository is the public Vibecodr CLI surface.
+
+- Package name: `@vibecodr/cli`
+- Primary executable name: `vibecodr`
+- Compatibility executable name: `vibecodr-mcp`
+- Legacy package compatibility: `@vibecodr/mcp`
+- Repo scope: direct CLI runtime, auth, diagnostics, and later thin installer adapters
+- License: Apache-2.0
+
+The hosted MCP gateway/server remains separate from this repo. That separation keeps hosted-service use distinct from any source-code reuse terms applied to the server implementation repo.
+
+Practical split:
+
+- this CLI repo governs distribution, modification, and reuse of the public client code
+- the hosted Vibecodr MCP service remains governed by Vibecodr service terms for account holders
+- the server implementation repo can carry different source-available terms without changing whether a commercial team may use the hosted service
+
+See [`architecture.md`](./architecture.md) for the client/server boundary.

package/docs/troubleshooting.md

@@ -0,0 +1,97 @@
+# Troubleshooting
+
+## Browser did not open
+
+`login` now prints the authorization URL by default.
+
+If you want the CLI to try opening the browser for you, use:
+
+```bash
+vibecodr login --browser open
+```
+
+If auto-open fails, rerun plain `login` and open the printed URL manually.
+
+## Callback timed out
+
+The loopback listener waits on `127.0.0.1` and expires after the configured timeout.
+
+Try:
+
+- rerun `login`
+- complete the browser flow before the timeout
+- ensure local security software is not blocking loopback callbacks
+
+## Secure secret store unavailable
+
+Run:
+
+```bash
+vibecodr doctor --json
+```
+
+If the `secret-store` check fails, the CLI cannot safely store tokens yet.
+
+The plaintext file secret store is intentionally test-only. If `VIBECDR_MCP_INSECURE_SECRET_STORE_PATH` is set without `VIBECDR_MCP_ENABLE_INSECURE_SECRET_STORE=true`, the CLI refuses to start rather than silently storing tokens outside the OS credential store.
+
+Platform notes:
+
+- macOS uses Keychain. Unlock the login keychain and approve Terminal or Node access if prompted.
+- Windows uses Credential Manager. Run from a normal signed-in desktop session with Credential Manager available.
+- Linux uses Secret Service. Install libsecret support and run from a session with an unlocked GNOME Keyring or KWallet. Headless Linux needs an explicit Secret Service setup for persistent CLI login.
+
+## Proxy or TLS issues
+
+The CLI uses normal outbound HTTPS fetches for discovery and token operations.
+
+Use:
+
+```bash
+vibecodr doctor --json
+```
+
+If `server-reachability` fails, verify:
+
+- proxy environment variables
+- local TLS interception policy
+- outbound access to `https://openai.vibecodr.space/mcp`
+
+## Client config conflict
+
+If install fails with a conflict, the target config already contains an entry with the same name but a different URL.
+
+Use either:
+
+- a different `--name`
+- `--overwrite` if the existing entry is meant to be replaced
+
+## Windsurf legacy path confusion
+
+Current native path:
+
+- `~/.codeium/windsurf/mcp_config.json`
+
+Older plugin references may still mention:
+
+- `~/.codeium/mcp_config.json`
+
+The CLI writes the native path.
+
+## Codex auth-on-first-use caveat
+
+Codex config install and CLI login are separate.
+
+- `install codex` configures Codex
+- `login` authenticates the Vibecodr CLI only
+- Codex will still own its own OAuth behavior when you use the server inside Codex
+
+## VS Code CLI not found
+
+If `code --add-mcp` is unavailable:
+
+- use project scope with `.vscode/mcp.json`
+- or retry user scope with `--open-client`
+
+## Step-up scope prompts
+
+The repo does not yet have a dedicated step-up scope UX beyond the normal re-auth path. If a server requests a broader scope, rerun `login` with the needed `--scope`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vibecodr/cli",
+  "version": "0.1.8",
+  "description": "Vibecodr CLI for login, live MCP tool discovery, and live tool invocation.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "vibecodr-mcp": "dist/bin/vibecodr-mcp.js",
+    "vibecodr": "dist/bin/vibecodr-mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22 <26"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "test:live-smoke": "node --import tsx --test test/live-smoke.smoke.ts",
+    "test:integration:worker": "node --import tsx --test test/worker-gateway.integration.test.ts",
+    "verify:artifact": "node scripts/check-pack-artifact.mjs",
+    "verify": "npm run check && npm test && npm run build && npm run verify:artifact"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@napi-rs/keyring": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}