ask-colleague 0.1.0 → 0.1.1

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for improving Agent Colleague.
+Thanks for improving Ask Colleague.
 
 ## Local checks
 
@@ -13,9 +13,9 @@ bash -n bin/colleague install.sh uninstall.sh scripts/ask-codex.sh scripts/ask-c
 For an end-to-end local `npx` check:
 
 ```bash
-npm pack --pack-destination /tmp
-npx --yes --package /tmp/agent-colleague-0.4.0.tgz agent-colleague --version
-npx --yes --package /tmp/agent-colleague-0.4.0.tgz agent-colleague install --dry-run
+tgz="/tmp/$(npm pack --pack-destination /tmp | tail -n 1)"
+npx --yes --package "$tgz" ask-colleague --version
+npx --yes --package "$tgz" ask-colleague install --dry-run
 ```
 
 ## Design constraints

package/README.md

@@ -1,5 +1,7 @@
 # Ask Colleague
 
+[![npm version](https://img.shields.io/npm/v/ask-colleague.svg)](https://www.npmjs.com/package/ask-colleague)
+
 A tiny, self-contained bridge that lets one local AI coding CLI ask another local AI coding CLI for a one-shot second opinion.
 
 The default flow:
@@ -30,8 +32,6 @@ That makes “ask a colleague” just a local shell bridge:
 
 ## Install with npx
 
-After this package is published to npm:
-
 ```bash
 npx ask-colleague@latest install
 ```
@@ -91,6 +91,10 @@ npx ask-colleague@latest uninstall
 
 Uninstall removes only files recorded in `~/.ask-colleague/install-manifest.tsv` and only if their checksums still match. If you edited an installed skill or prompt, uninstall leaves it in place and tells you to use `--force` if you really want it removed.
 
+### Windows
+
+`colleague` is a Bash CLI. On Windows, run everything — `npx`, the install, and the `claude`/`codex` CLIs — inside WSL (recommended) or Git Bash (best effort). Running `npx ask-colleague@latest install` from PowerShell or cmd.exe prints setup guidance instead of failing on a missing Bash.
+
 ## Install from source
 
 ```bash
@@ -261,7 +265,8 @@ Good question:
 
 ```text
 ask-colleague/
-  bin/colleague                         # main bridge CLI and npm bin target
+  bin/colleague                         # main bridge CLI (Bash)
+  bin/colleague.js                      # Node launcher for the npm bin (Windows-safe)
   package.json                          # npm package metadata and bin mappings
   scripts/ask-codex.sh                  # compatibility wrapper
   scripts/ask-claude.sh                 # compatibility wrapper
@@ -278,6 +283,10 @@ ask-colleague/
 
 ## Troubleshooting
 
+### `WSL ... execvpe(/bin/bash) failed: No such file or directory` on Windows
+
+Older versions (0.1.0) pointed the npm bin directly at the Bash script, so PowerShell invoked the WSL bash stub, which fails like this when no Linux distribution is installed. Upgrade with `npx ask-colleague@latest install` — current versions detect this and print setup guidance. Then run the bridge inside WSL or Git Bash as described in the Windows section above.
+
 ### `colleague: codex CLI not found in PATH`
 
 Install Codex CLI and confirm `codex --version` works in the same shell where Claude Code or Codex is running.
@@ -331,12 +340,14 @@ The smoke tests use dry-run and mocked CLI paths, so they do not require authent
 ```json
 {
   "bin": {
-    "ask-colleague": "bin/colleague",
-    "colleague": "bin/colleague"
+    "ask-colleague": "bin/colleague.js",
+    "colleague": "bin/colleague.js"
   }
 }
 ```
 
+`bin/colleague.js` is a tiny Node launcher that delegates to the Bash CLI. It exists because npm's Windows shims would otherwise hand the Bash script to the WSL bash stub, which fails cryptically when no Linux distribution is installed. The launcher runs the script with a real Bash where one exists and prints setup guidance otherwise.
+
 This means:
 
 ```bash
@@ -359,15 +370,13 @@ Before publishing, test the exact tarball that npm would distribute:
 ```bash
 npm test
 npm pack --dry-run
-npm pack --pack-destination /tmp
-npx --yes --package /tmp/ask-colleague-0.4.0.tgz ask-colleague --version
-npx --yes --package /tmp/ask-colleague-0.4.0.tgz ask-colleague install --dry-run
+tgz="/tmp/$(npm pack --pack-destination /tmp | tail -n 1)"
+npx --yes --package "$tgz" ask-colleague --version
+npx --yes --package "$tgz" ask-colleague install --dry-run
 ```
 
 ## Publish to npm
 
-Before publishing, check the package name and add repository metadata to `package.json` if you have a public repo URL ready.
-
 ```bash
 npm login
 npm publish --access public

package/bin/colleague

@@ -3,7 +3,7 @@
 # Works with Codex (`codex exec -`) and Claude Code (`cat prompt | claude -p ...`).
 set -euo pipefail
 
-VERSION="0.4.0"
+VERSION="0.1.1"
 DEFAULT_MAX_BYTES="${COLLEAGUE_MAX_CONTEXT_BYTES:-120000}"
 STATE_DIR="${COLLEAGUE_STATE_DIR:-$HOME/.ask-colleague}"
 MANIFEST="$STATE_DIR/install-manifest.tsv"

package/bin/colleague.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// npm bin launcher for the Bash CLI in bin/colleague.
+//
+// npm's Windows shims execute the shebang interpreter directly. For a Bash
+// script in PowerShell/cmd.exe that resolves to the WSL bash stub, which fails
+// with a cryptic "execvpe(/bin/bash) failed" error when no Linux distribution
+// is installed. Routing the bin through Node (always present under npx) lets
+// us delegate to a working Bash where one exists and print actionable
+// guidance where one does not.
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const script = path.join(__dirname, 'colleague');
+const args = process.argv.slice(2);
+
+function fail(message) {
+  process.stderr.write(message);
+  process.exit(1);
+}
+
+const WINDOWS_HELP = [
+  'ask-colleague: this command needs Bash, which is not available in this Windows shell.',
+  '',
+  'The Claude Code <-> Codex bridge is a Bash CLI, so on Windows it runs inside',
+  'WSL or Git Bash:',
+  '',
+  '  WSL (recommended):',
+  '    1. Install WSL: https://learn.microsoft.com/windows/wsl/install',
+  '    2. Open a WSL shell (e.g. Ubuntu) and run: npx ask-colleague@latest install',
+  '       The claude / codex CLIs must also be installed inside WSL.',
+  '',
+  '  Git Bash (best effort):',
+  '    Run the same npx command from a Git Bash terminal.',
+  '',
+  'If you saw a "WSL ... execvpe(/bin/bash) failed" error, Windows invoked the',
+  'WSL bash stub without a Linux distribution installed.',
+  '',
+].join('\n');
+
+if (process.platform === 'win32') {
+  // Only proceed with a Bash that understands Windows paths (Git Bash/MSYS,
+  // Cygwin). The WSL stub either fails outright (no distro) or cannot read
+  // the Windows path of the script we need to hand it.
+  const probe = spawnSync('bash', ['-c', 'echo $OSTYPE'], { encoding: 'utf8' });
+  const ostype = (probe.stdout || '').trim();
+  if (probe.error || probe.status !== 0 || !/^(msys|cygwin)/.test(ostype)) {
+    fail(WINDOWS_HELP);
+  }
+}
+
+const result = spawnSync('bash', [script, ...args], { stdio: 'inherit' });
+if (result.error && result.error.code === 'ENOENT') {
+  fail('ask-colleague: bash not found in PATH. Install Bash, or on Windows run inside WSL or Git Bash.\n');
+}
+process.exit(result.status === null ? 1 : result.status);

package/docs/publishing.md

@@ -8,46 +8,15 @@ npx ask-colleague@latest install
 
 `npx` runs the npm package's executable once. The executable then copies the long-lived `colleague` command and both skill files into the user's home directory, recording checksums in `~/.ask-colleague/install-manifest.tsv`.
 
-## 1. Pick the package name
+## 1. Check package metadata
 
-The starter `package.json` uses:
+`package.json` must agree with the rest of the repo before each publish:
 
-```json
-"name": "ask-colleague"
-```
-
-Before publishing, check that the package name is available. If it is taken, use a scoped package name instead:
-
-```json
-"name": "@your-scope/ask-colleague"
-```
-
-With a scoped name, the install command becomes:
-
-```bash
-npx @your-scope/ask-colleague@latest install
-```
-
-## 2. Add public repository metadata
-
-This starter package intentionally does not include fake GitHub metadata. Before publishing from your real repo, add fields like:
-
-```json
-{
-  "homepage": "https://github.com/<owner>/<repo>#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/<owner>/<repo>.git"
-  },
-  "bugs": {
-    "url": "https://github.com/<owner>/<repo>/issues"
-  }
-}
-```
-
-Also replace `<your-ask-colleague-repo-url>` in `README.md`.
+- `version` matches `VERSION` in `bin/colleague` and the version checks in `tests/smoke.sh`
+- `homepage`, `repository`, and `bugs` point at the public GitHub repo
+- `bin` maps both `ask-colleague` and `colleague` to `bin/colleague.js`
 
-## 3. Run local checks
+## 2. Run local checks
 
 ```bash
 npm test
@@ -57,14 +26,12 @@ npm pack --dry-run
 Then build a real local tarball and run it through `npx`:
 
 ```bash
-npm pack --pack-destination /tmp
-npx --yes --package /tmp/ask-colleague-0.4.0.tgz ask-colleague --version
-npx --yes --package /tmp/ask-colleague-0.4.0.tgz ask-colleague install --dry-run
+tgz="/tmp/$(npm pack --pack-destination /tmp | tail -n 1)"
+npx --yes --package "$tgz" ask-colleague --version
+npx --yes --package "$tgz" ask-colleague install --dry-run
 ```
 
-If you changed the package name or version, update the tarball path accordingly.
-
-## 4. Inspect package contents
+## 3. Inspect package contents
 
 Make sure the npm tarball includes only what users need:
 
@@ -80,6 +47,7 @@ README.md
 LICENSE
 CONTRIBUTING.md
 bin/colleague
+bin/colleague.js
 install.sh
 uninstall.sh
 scripts/ask-codex.sh
@@ -95,7 +63,7 @@ docs/security.md
 docs/publishing.md
 ```
 
-## 5. Publish
+## 4. Publish
 
 ```bash
 npm login
@@ -104,7 +72,7 @@ npm publish --access public
 
 For scoped packages, `--access public` is required unless your npm account/org has different defaults.
 
-## 6. Verify public install
+## 5. Verify public install
 
 After npm finishes publishing:
 
@@ -128,7 +96,7 @@ colleague uninstall --dry-run
 colleague uninstall
 ```
 
-## 7. Optional AGENTS.md fallback
+## 6. Optional AGENTS.md fallback
 
 Do not enable the global Codex AGENTS.md fallback by default in release notes. Users who want it can opt in:
 
@@ -136,7 +104,7 @@ Do not enable the global Codex AGENTS.md fallback by default in release notes. U
 npx ask-colleague@latest install --agents-md
 ```
 
-## 8. Release updates
+## 7. Release updates
 
 Bump the version before each publish:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ask-colleague",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Ask a colleague, a bridge that lets Claude Code and Codex ask each other for one-shot peer advice.",
   "license": "MIT",
   "homepage": "https://github.com/stevyhacker/ask-colleague#readme",
@@ -22,8 +22,8 @@
     "coding-agent"
   ],
   "bin": {
-    "ask-colleague": "bin/colleague",
-    "colleague": "bin/colleague"
+    "ask-colleague": "bin/colleague.js",
+    "colleague": "bin/colleague.js"
   },
   "files": [
     "bin/",