inscope 0.1.0 → 0.2.0-canary.0

package/README.md

@@ -1,41 +1,104 @@
-# inscope
+# Inscope
 
-Per-workspace identity for [Claude Code](https://claude.com/claude-code). Scope
-MCP servers, GitHub auth, and git commit identity to the directory you are in,
-so concurrent sessions in different projects never bleed work and personal
-accounts into each other.
+**Per-workspace identity for [Claude Code](https://claude.com/claude-code): scope MCP servers, GitHub auth, and git commit identity to the directory you are in.**
 
-You describe each workspace once; `inscope` owns the moving parts and keeps them
-in sync:
+[![Twitter](https://img.shields.io/twitter/follow/nrjdalal_dev?label=%40nrjdalal_dev)](https://twitter.com/nrjdalal_dev)
+[![npm](https://img.shields.io/npm/v/inscope?color=red&logo=npm)](https://www.npmjs.com/package/inscope)
+[![downloads](https://img.shields.io/npm/dt/inscope?color=red&logo=npm)](https://www.npmjs.com/package/inscope)
+[![stars](https://img.shields.io/github/stars/nrjdalal/inscope?color=blue)](https://github.com/nrjdalal/inscope)
+
+> #### `cd` into a project and you are the right person: the right GitHub token, the right MCP servers, the right git commit email, all resolved live from `$PWD`. No toggles, no profile switching, and it holds up with several Claude Code sessions open at once.
+
+Concurrent sessions in different projects should never bleed work and personal accounts into each other. You describe each workspace once; `inscope` owns the moving parts and keeps them in sync:
 
 - a `.mcp.json` at each workspace root, with uniquely named servers
 - a single zsh `chpwd` hook that resolves the right tokens from `$PWD`
 - git `includeIf` rules so commits get the right email per path
 
-Nothing sensitive is written to disk. GitHub tokens come from the `gh` keyring
-and Slack tokens from the macOS Keychain, resolved live by the hook.
+Nothing sensitive is written to disk. GitHub tokens come from the `gh` keyring and Slack tokens from the macOS Keychain, resolved live by the hook.
+
+> Background and the why behind the design: [Race-Free Identity in Claude Code](https://zerostarter.dev/blog/mcp-per-workspace).
+
+---
+
+### Table of Contents
+
+- [Some Examples](#-some-examples)
+- [Features](#-features)
+- [Requirements](#-requirements)
+- [Quick Usage](#-quick-usage)
+- [Commands](#-commands)
+- [What It Manages](#-what-it-manages)
+- [MCP Servers](#-mcp-servers)
+- [Config File](#-config-file)
+- [Contributing](#-contributing)
+
+---
+
+## 📖 Some Examples
+
+```sh
+# set up the config + hook, and source it from ~/.zshrc
+inscope init
+
+# map a work directory: work gh account, work email, work + slack servers
+inscope add ~/acme --gh acme --email you@acme.com --servers github,linear,notion,slack
+
+# map a personal directory: just your gh account and personal email
+inscope add ~/nrjdalal --gh nrjdalal --email you@personal.dev
+
+# list what is configured
+inscope list
+
+# verify tokens, identities, and the hook all resolve
+inscope doctor
+
+# regenerate everything after editing the config by hand
+inscope apply
+
+# remove a workspace mapping
+inscope rm ~/acme
+```
+
+`cd ~/acme/api` and you are the work account, with work MCP servers and your work commit email. `cd ~/nrjdalal/blog` and you are you.
+
+---
+
+## ✨ Features
+
+- 🪪 Per-directory identity: GitHub token, git commit email, and MCP servers scoped to `$PWD`
+- 🧵 Race-free across concurrent shells and Claude Code sessions, with no global toggles
+- 🔐 No secrets on disk: GitHub tokens from the `gh` keyring, Slack tokens from the macOS Keychain
+- 🤖 Generates a `.mcp.json` per workspace with uniquely named GitHub, Linear, Notion and Slack servers
+- ✉️ Git `includeIf` rules so every commit lands with the right author email per path
+- 🪝 A single zsh `chpwd` hook does all the resolution; nothing else touches your shell
+- 🩺 `inscope doctor` verifies tokens, identities, and the hook before you trust them
+- ♻️ Idempotent and surgical: only the managed blocks in `.zshrc`, `.gitconfig` and `.mcp.json` are touched
+
+---
 
-> Background and the why behind the design:
-> [Race-Free Identity in Claude Code](https://zerostarter.dev/blog/mcp-per-workspace).
+## 🧰 Requirements
 
-## Requirements
+macOS, zsh, [`gh`](https://cli.github.com), and [Claude Code](https://claude.com/claude-code).
 
-macOS, zsh, [`gh`](https://cli.github.com), and Claude Code.
+---
 
-## Install
+## 🚀 Quick Usage
 
-```bash
+Install globally (the CLI manages your shell hook, so a global install is expected):
+
+```sh
 npm i -g inscope
 ```
 
-## Quickstart
+Then walk through the setup once:
 
-```bash
+```sh
 # 1. set up the config + hook, and source it from ~/.zshrc
 inscope init
 
-# 2. sign each GitHub account into gh (once)
-gh auth login   # repeat per account
+# 2. sign each GitHub account into gh (once per account)
+gh auth login
 
 # 3. map your workspaces
 inscope add ~/acme     --gh acme     --email you@acme.com --servers github,linear,notion,slack
@@ -46,24 +109,44 @@ source ~/.zshrc
 inscope doctor
 ```
 
-`cd ~/acme/api` and you are the work account, with work MCP servers and your
-work commit email. `cd ~/nrjdalal/blog` and you are you. No toggles, and it
-holds up with several terminals open at once.
+Launch `claude` from inside a mapped directory (or relaunch) to pick up the identity. No toggles, and it holds up with several terminals open at once.
+
+---
 
-## Commands
+## 🔧 Commands
 
-| Command        | What it does                                                         |
-| -------------- | -------------------------------------------------------------------- |
-| `inscope init`   | create the config, generate the hook, source it from `~/.zshrc`      |
-| `inscope add`    | map a directory to a gh account, git email, and MCP servers          |
-| `inscope rm`     | remove a workspace mapping                                           |
-| `inscope list`   | list configured workspaces                                           |
-| `inscope apply`  | regenerate the hook, git includes, and every `.mcp.json` from config |
-| `inscope doctor` | verify tokens, identities, and the hook resolve correctly            |
+```
+inscope init           Create the config, generate the hook, source it from ~/.zshrc
+inscope add <path>     Map a directory to a GitHub account, git email, and MCP servers
+inscope rm <path>      Remove a workspace mapping (alias: remove)
+inscope list           List configured workspaces (alias: ls)
+inscope apply          Regenerate the hook, git includes, and .mcp.json (alias: sync)
+inscope doctor         Verify tokens, identities, and the hook resolve correctly
+
+-v, --version          Display version
+-h, --help             Display help
+```
 
 Run any command with `-h` for its options.
 
-## What it manages
+### `inscope add` options
+
+```
+    --gh <account>        gh account whose token this workspace uses
+    --email <email>       git commit email for this workspace
+    --git-name <name>     git commit author name (optional)
+    --label <name>        workspace name; defaults to the directory basename
+    --servers <list>      comma-separated: github,linear,notion,slack
+                          (default: github,linear,notion)
+    --slack-keychain <s>  keychain service for the Slack token
+                          (default: slack-<label>-mcp-xoxp when slack is on)
+    --slack-message       allow the Slack MCP server to post messages
+    --seed-slack          prompt for the Slack token and store it in the keychain
+```
+
+---
+
+## 🧩 What It Manages
 
 | Surface      | Location                                                    |
 | ------------ | ----------------------------------------------------------- |
@@ -72,10 +155,65 @@ Run any command with `-h` for its options.
 | MCP servers  | `<workspace>/.mcp.json`                                     |
 | Git identity | `~/.gitconfig` includeIf + `~/.config/git/<name>.gitconfig` |
 
-Edit `workspaces.json` by hand if you like, then run `inscope apply`. It only
-touches the blocks it owns; your other `.zshrc`, `.gitconfig`, and `.mcp.json`
-content is left alone.
+`inscope` only touches the blocks it owns; your other `.zshrc`, `.gitconfig` and `.mcp.json` content is left alone. Edit `workspaces.json` by hand if you like, then run `inscope apply`.
+
+---
+
+## 🤖 MCP Servers
+
+Each enabled server is written into the workspace `.mcp.json` with a name suffixed by the workspace label (for example `github-acme`), so servers from different workspaces never collide.
+
+| Server   | Transport | Token source                                   |
+| -------- | --------- | ---------------------------------------------- |
+| `github` | http      | `GITHUB_TOKEN` from the active `gh` account    |
+| `linear` | http      | OAuth via the Linear MCP endpoint              |
+| `notion` | http      | OAuth via the Notion MCP endpoint              |
+| `slack`  | stdio     | `SLACK_MCP_XOXP_TOKEN` from the macOS Keychain |
+
+Slack is opt-in. Enable it with `--servers ...,slack`, then store the token once:
+
+```sh
+inscope add ~/acme --gh acme --servers github,linear,notion,slack --seed-slack
+```
+
+`--seed-slack` prompts for the `xoxp` token and writes it to the Keychain. Pass `--slack-message` to allow the Slack MCP server to post messages.
+
+---
+
+## 📋 Config File
+
+The source of truth is `~/.config/claude/workspaces.json`:
+
+```jsonc
+{
+  "version": 1,
+  "workspaces": [
+    {
+      "name": "acme",
+      "path": "~/acme",
+      "gh": "acme",
+      "git": { "email": "you@acme.com" },
+      "servers": {
+        "github": true,
+        "linear": true,
+        "notion": true,
+        "slack": { "keychain": "slack-acme-mcp-xoxp", "addMessageTool": false }
+      }
+    }
+  ]
+}
+```
+
+Edit it directly, then run `inscope apply` to regenerate the hook, git includes, and every `.mcp.json`. `inscope doctor` will tell you if anything no longer resolves.
+
+---
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome. Run the tests with `bun test` and the type checks with `bun run typecheck` before opening a PR.
+
+---
 
 ## License
 
-MIT
+[MIT](./LICENSE) © [Neeraj Dalal](https://nrjdalal.com)

package/dist/bin/index.mjs

@@ -55,7 +55,7 @@ __inscope_resolve_identity
 `)},le=e=>{let n=M(e);if(!t.existsSync(n))return;let r=P(n);if(r.mcpServers&&typeof r.mcpServers==`object`)for(let t of j(e.name))delete r.mcpServers[t];t.writeFileSync(n,JSON.stringify(r,null,2)+`
 `)},F=`zshrc`,ue=e=>{let t=o();return e===t?`$HOME`:e.startsWith(t+n.sep)?`$HOME/${e.slice(t.length+1)}`:e},de=()=>{let e=ue(f()),t=`# Loads each workspace's tokens (GitHub, Slack) from $PWD on every cd.\n[ -r "${e}" ] && source "${e}"`;S(h(),F,t)},I=e=>{let r=f();t.mkdirSync(n.dirname(r),{recursive:!0}),t.writeFileSync(r,k(e)),ie(e),de();let i=[];for(let t of e.workspaces)ce(t),i.push(M(t));return{hook:r,gitconfig:e.workspaces.some(e=>e.git?.email||e.git?.name),mcp:i}},L=()=>({version:1,workspaces:[]}),R=()=>t.existsSync(d()),z=()=>{let e=d(),n=t.readFileSync(e,`utf8`),r=JSON.parse(n);return V(r),r},B=e=>{let r=d();t.mkdirSync(n.dirname(r),{recursive:!0}),t.writeFileSync(r,JSON.stringify(e,null,2)+`
 `)},V=e=>{if(!e||typeof e!=`object`)throw Error(`config is not an object`);if(!Array.isArray(e.workspaces))throw Error(`config.workspaces must be an array`);let t=new Set;for(let n of e.workspaces){if(!n.name)throw Error(`a workspace is missing a name`);if(!n.path)throw Error(`workspace "${n.name}" is missing a path`);if(t.has(n.name))throw Error(`duplicate workspace name "${n.name}"`);t.add(n.name)}},H=e=>n.basename(u(e)),fe=(e,t)=>{let n=e.workspaces.find(e=>e.name===t);if(n)return n;let r=u(t);return e.workspaces.find(e=>u(e.path)===r)},pe=(e,t)=>{let n=e.workspaces.filter(e=>e.name!==t.name);return n.push({...t,path:l(t.path)}),n.sort((e,t)=>e.name.localeCompare(t.name)),{...e,workspaces:n}},me=(e,t)=>{let n=fe(e,t);return n?{cfg:{...e,workspaces:e.workspaces.filter(e=>e.name!==n.name)},removed:n}:{cfg:e}},U=(e,t,n)=>{let r=i(e,t,{encoding:`utf8`,input:n?.input});return{status:r.status??(r.error?127:1),stdout:r.stdout??``,stderr:r.stderr??``}},he=()=>process.platform===`darwin`,W=()=>process.env.USER||``,ge=(e,t=U)=>{let n=t(`gh`,[`auth`,`token`,`-u`,e]),r=n.stdout.trim();return n.status===0&&r?r:null},G=(e,t=U)=>{let n=t(`security`,[`find-generic-password`,`-a`,W(),`-s`,e,`-w`]);return n.status===0&&n.stdout.trim().length>0},_e=(e,t,n=U)=>{let r=n(`security`,[`add-generic-password`,`-U`,`-a`,W(),`-s`,e,`-w`,t]);if(r.status!==0)throw Error(`security add-generic-password failed: ${r.stderr.trim()||`unknown error`}`)},K=e=>`security add-generic-password -U -a "${W()||`$USER`}" -s ${e} -w 'xoxp-...'`,ve=(e,t=U)=>{let n=t(`git`,[`config`,`--file`,e,`user.email`]);return n.status===0?n.stdout.trim():null},ye=e=>new Promise(t=>{let n=a.createInterface({input:process.stdin,output:process.stdout}),r=n.output,i=!1;n._writeToOutput=t=>{if(!i){r.write(t),t.includes(e)&&(i=!0);return}},n.question(e,e=>{r.write(`
-`),n.close(),t(e.trim())})});var q=`inscope`,J=`0.1.0`,Y={name:`Neeraj Dalal`,email:`admin@nrjdalal.com`,url:`https://nrjdalal.com`};const X=`Map a directory to a GitHub account, git email, and MCP servers.
+`),n.close(),t(e.trim())})});var q=`inscope`,J=`0.2.0-canary.0`,Y={name:`Neeraj Dalal`,email:`admin@nrjdalal.com`,url:`https://nrjdalal.com`};const X=`Map a directory to a GitHub account, git email, and MCP servers.
 Re-running with the same path or label updates that workspace.
 
 Usage:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inscope",
-  "version": "0.1.0",
+  "version": "0.2.0-canary.0",
   "description": "Per-workspace identity for Claude Code: scope MCP servers, GitHub auth, and git commit identity to the directory you are in.",
   "keywords": [
     "claude-code",
@@ -26,49 +26,10 @@
   "type": "module",
   "exports": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
-  "bin": {
-    "inscope": "./dist/bin/index.mjs"
-  },
   "files": [
     "dist"
   ],
-  "scripts": {
-    "bin": "tsdown && node dist/bin/index.mjs",
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "prepare": "npx simple-git-hooks"
-  },
-  "simple-git-hooks": {
-    "pre-commit": "npx lint-staged",
-    "commit-msg": "npx commitlint --edit $1"
-  },
-  "commitlint": {
-    "extends": [
-      "@commitlint/config-conventional"
-    ]
-  },
-  "lint-staged": {
-    "*": "prettier --write --ignore-unknown",
-    "package.json": "sort-package-json"
-  },
-  "prettier": {
-    "plugins": [
-      "@ianvs/prettier-plugin-sort-imports"
-    ],
-    "semi": false
-  },
-  "devDependencies": {
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
-    "@ianvs/prettier-plugin-sort-imports": "^4.4.2",
-    "@types/node": "^22.15.32",
-    "lint-staged": "^15.5.2",
-    "prettier": "^3.5.3",
-    "simple-git-hooks": "^2.13.0",
-    "sort-package-json": "^3.2.1",
-    "tsdown": "^0.16.4",
-    "typescript": "^5.8.3"
+  "bin": {
+    "inscope": "dist/bin/index.mjs"
   }
 }