@actions-json/bridge 0.1.124 → 0.1.187

package/bin/cli.js

@@ -10,6 +10,7 @@ const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { ensureBinary } = require('../lib/install');
 const { ensureStorageRoot } = require('../lib/storage');
+const { install } = require('../lib/register');
 
 // The primitive dictionary (browser-control tool catalog) ships with this
 // package — it's a fixed runtime file, not user config. When the caller runs a
@@ -40,6 +41,13 @@ function withDefaults(args) {
 }
 
 async function main() {
+  // `install` is a wrapper-side subcommand (register the MCP server with the
+  // local coding agents); it does not touch the bridge binary or launch it.
+  if (process.argv[2] === 'install') {
+    process.exit(install());
+    return;
+  }
+
   let bin;
   try {
     bin = await ensureBinary();

package/lib/register.js

@@ -0,0 +1,139 @@
+'use strict';
+
+// `npx @actions-json/bridge install` — register the actions-json MCP server with
+// whatever coding agents are present, by calling each agent's own `mcp add`
+// command. This removes the manual "copy the right claude/codex command" step
+// from the install: we detect the agent, run its registrar, and report.
+//
+// Design: we shell out to each agent's OWN CLI (`claude mcp add …`,
+// `codex mcp add …`) rather than hand-editing their config files, so the agent
+// stays the source of truth for its own config format. Idempotent-ish: agents
+// treat re-adding an existing server as an error, which we catch and report as
+// "already registered" rather than failing the whole run.
+
+const { execFileSync, execSync } = require('node:child_process');
+
+// The canonical launch command every agent should register.
+const SERVER_NAME = 'actions-json';
+const LAUNCH = ['npx', '-y', '@actions-json/bridge', 'mcp'];
+
+// Each supported agent: how to detect its CLI, and how to register a stdio MCP
+// server with it. `addArgs` produces the argv for a spawn of `bin`.
+const AGENTS = [
+  {
+    key: 'claude',
+    label: 'Claude Code',
+    bin: 'claude',
+    listArgs: () => ['mcp', 'list'],
+    addArgs: () => ['mcp', 'add', SERVER_NAME, '--', ...LAUNCH],
+    manual: `claude mcp add ${SERVER_NAME} -- ${LAUNCH.join(' ')}`,
+  },
+  {
+    key: 'codex',
+    label: 'Codex',
+    bin: 'codex',
+    listArgs: () => ['mcp', 'list'],
+    addArgs: () => ['mcp', 'add', SERVER_NAME, '--', ...LAUNCH],
+    manual: `codex mcp add ${SERVER_NAME} -- ${LAUNCH.join(' ')}`,
+  },
+];
+
+// Is a CLI on PATH? Cross-platform: `command -v` on posix, `where` on win32.
+function onPath(bin) {
+  try {
+    if (process.platform === 'win32') {
+      execSync(`where ${bin}`, { stdio: 'ignore' });
+    } else {
+      execSync(`command -v ${bin}`, { stdio: 'ignore', shell: '/bin/sh' });
+    }
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+// Is the actions-json server ALREADY registered with this agent? We check first
+// and never overwrite an existing config — a re-run must be a no-op, not a
+// clobber (an install should only touch config when there's a reason to).
+function alreadyRegistered(agent) {
+  if (!agent.listArgs) return false;
+  try {
+    const out = execFileSync(agent.bin, agent.listArgs(), { stdio: 'pipe' }).toString();
+    return out.includes(SERVER_NAME);
+  } catch (_e) {
+    // If listing fails we can't confirm; fall through to the add path, which
+    // still catches an "already exists" error rather than overwriting.
+    return false;
+  }
+}
+
+// Register with one agent. Returns { agent, status, detail }.
+function registerOne(agent) {
+  if (!onPath(agent.bin)) {
+    return { agent: agent.label, status: 'absent' };
+  }
+  // Never replace an existing registration — skip if it's already there.
+  if (alreadyRegistered(agent)) {
+    return { agent: agent.label, status: 'already' };
+  }
+  try {
+    execFileSync(agent.bin, agent.addArgs(), { stdio: 'pipe' });
+    return { agent: agent.label, status: 'registered' };
+  } catch (e) {
+    // Belt-and-suspenders: if the add still reports the name exists (race, or an
+    // agent we couldn't list), treat as already — do NOT clobber. Anything else
+    // is a real failure we surface with the manual command.
+    const out = `${e.stdout || ''}${e.stderr || ''}`.toLowerCase();
+    if (out.includes('already') || out.includes('exist')) {
+      return { agent: agent.label, status: 'already' };
+    }
+    return { agent: agent.label, status: 'failed', detail: agent.manual };
+  }
+}
+
+// Detect + register across all known agents; print a human summary. Returns an
+// exit code (0 if at least one agent got the server, 1 if none did).
+function install() {
+  const results = AGENTS.map(registerOne);
+  const present = results.filter((r) => r.status !== 'absent');
+
+  process.stdout.write('\nactions.json — MCP registration\n');
+  for (const r of results) {
+    if (r.status === 'absent') continue;
+    const mark =
+      r.status === 'registered' ? '✓ registered' :
+      r.status === 'already' ? '✓ already registered' :
+      '✗ failed';
+    process.stdout.write(`  ${mark}: ${r.agent}\n`);
+    if (r.status === 'failed') {
+      process.stdout.write(`      run manually: ${r.detail}\n`);
+    }
+  }
+
+  if (present.length === 0) {
+    process.stdout.write(
+      '  No supported coding agent (Claude Code or Codex) found on PATH.\n' +
+        '  Install one, then re-run `npx @actions-json/bridge install`, or add it manually:\n'
+    );
+    for (const a of AGENTS) {
+      process.stdout.write(`      ${a.manual}\n`);
+    }
+  } else {
+    const ok = present.some((r) => r.status === 'registered' || r.status === 'already');
+    if (ok) {
+      process.stdout.write(
+        '\nDone. Restart (or reconnect) your agent so it launches the server, then\n' +
+          'install the browser extension and connect it. See:\n' +
+          '  https://yaniv256.github.io/actions.json/getting-started.html\n'
+      );
+    }
+  }
+  process.stdout.write('\n');
+
+  return present.length > 0 &&
+    present.some((r) => r.status === 'registered' || r.status === 'already')
+    ? 0
+    : 1;
+}
+
+module.exports = { install, AGENTS, SERVER_NAME, onPath, registerOne };

package/lib/storage.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 
 // Default storage location when the caller doesn't pass --storage-root.
 // Lives in the user's home dir (not cwd) so it resolves no matter where the
@@ -14,39 +15,58 @@ function defaultStorageRoot() {
   );
 }
 
-const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
+// The bundled seed skeleton (storage.json + scope READMEs + private placeholder),
+// mirroring examples/actions.json.storage. The PUBLIC site maps are NOT bundled;
+// they are cloned from the public maps repo on first run (see clonePublicMaps)
+// so a fresh install arrives stocked with real, working maps to try.
+const SEED_DIR = path.join(__dirname, '..', 'seed');
+const PUBLIC_MAPS_REPO = 'https://github.com/yaniv256/actions.json.storage.public.git';
 
-// Recursively copy the template, skipping the .gitkeep placeholders (they only
-// exist to ship empty dirs inside the package/repo).
-function copyTemplate(src, dst) {
+// Recursively copy the seed skeleton into the target.
+function copySeed(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === '.gitkeep') continue;
     const s = path.join(src, entry.name);
     const d = path.join(dst, entry.name);
     if (entry.isDirectory()) {
-      copyTemplate(s, d);
+      copySeed(s, d);
     } else {
       fs.copyFileSync(s, d);
     }
   }
 }
 
-// Ensure the storage root exists; create it from the bundled template on
-// first run. Returns the absolute path. Never overwrites existing storage.
+// Clone the public site maps into scopes/public so the workspace ships with
+// something to try. Best-effort: if git is missing or the clone fails (offline,
+// etc.), seed an empty scopes/public and tell the user how to get the maps —
+// never fail the whole seed over the optional maps.
+function clonePublicMaps(target) {
+  const publicDir = path.join(target, 'scopes', 'public');
+  if (fs.existsSync(publicDir) && fs.readdirSync(publicDir).length > 0) return;
+  try {
+    execFileSync('git', ['clone', '--depth', '1', PUBLIC_MAPS_REPO, publicDir], {
+      stdio: 'ignore',
+    });
+    process.stderr.write(`Cloned public site maps into ${publicDir}\n`);
+  } catch (_e) {
+    fs.mkdirSync(publicDir, { recursive: true });
+    process.stderr.write(
+      `Could not clone public site maps (need git + network). ` +
+        `Get them later with:\n  git clone ${PUBLIC_MAPS_REPO} "${publicDir}"\n`
+    );
+  }
+}
+
+// Ensure the storage root exists; create it from the bundled seed on first run,
+// then clone the public maps. Returns the absolute path. Never overwrites
+// existing storage.
 function ensureStorageRoot(root) {
   const target = root || defaultStorageRoot();
   if (!fs.existsSync(target)) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
-    copyTemplate(TEMPLATE_DIR, target);
-    // Recreate the empty scope dirs that .gitkeep stood in for.
-    for (const p of [
-      ['scopes', 'private', 'sites'],
-      ['scopes', 'public', 'sites'],
-      ['scopes', 'shared'],
-    ]) {
-      fs.mkdirSync(path.join(target, ...p), { recursive: true });
-    }
+    copySeed(SEED_DIR, target);
+    fs.mkdirSync(path.join(target, 'scopes', 'private'), { recursive: true });
+    clonePublicMaps(target);
     process.stderr.write(`Created actions.json storage at ${target}\n`);
   }
   return path.resolve(target);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions-json/bridge",
-  "version": "0.1.124",
+  "version": "0.1.187",
   "bridgeBinaryVersion": "0.1.186",
   "description": "Run the actions.json MCP bridge with npx — no Rust toolchain required. Downloads the prebuilt actions-json-mcp binary, bundles the primitive dictionary, and creates your storage workspace on first run.",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "bin/",
     "lib/",
     "dictionary/",
-    "template/",
+    "seed/",
     "README.md"
   ],
   "engines": {

package/seed/README.md

@@ -0,0 +1,27 @@
+# actions.json.storage
+
+Your `actions.json.storage` workspace — the root/index that records storage configuration, mounted
+scopes, and layout. It was created here on first run of `@actions-json/bridge`.
+
+## Layout
+
+```text
+storage.json     Root manifest (mounts, visibility, sync policy)
+scopes/
+  public/        Reviewed, reusable public site maps (cloned from the public maps repo)
+  private/       Your OWN owner-only storage — local by default (see its README)
+```
+
+## ⚠️ Privacy
+
+`scopes/private` is where your browsing memory, observations, and unreviewed maps live. It is **local
+and private by default** here in your home directory. If you later put this workspace under version
+control, putting files in `scopes/private` does NOT make them private on its own — keep the repo
+private, or mount `scopes/private` from your own **private** repo. See `scopes/private/README.md`.
+
+## The public maps
+
+`scopes/public` is cloned from
+[actions.json.storage.public](https://github.com/yaniv256/actions.json.storage.public) so you have
+working site maps to try immediately. Update them with `git -C scopes/public pull`, or repoint the
+`public` mount in `storage.json` at your own public repo.

package/seed/scopes/README.md

@@ -0,0 +1,10 @@
+# scopes/
+
+Each subfolder is a **mounted scope** — a separate storage area with its own visibility. Scopes are
+usually git submodules pointing at their own repositories, so they can have different access than this
+root repo.
+
+- **public/** — reviewed, reusable public site-action maps (a git submodule to a public repo).
+- **private/** — your OWN owner-only storage (see its README). Not included in this public example.
+
+Add further scopes (e.g. `shared/<audience>/`) as separate repositories when you need them.

package/seed/scopes/private/README.md

@@ -0,0 +1,23 @@
+# scopes/private/ — placeholder
+
+This is a **placeholder folder**, intentionally empty in the public example. Your private scope holds
+owner-only browsing memory, observations, run logs, item indexes, and unreviewed action maps — content
+that should never be public.
+
+## ⚠️ Enforce privacy — two options
+
+Putting files in this folder does NOT make them private on its own. Choose one:
+
+1. **Keep the whole `actions.json.storage` repo private** (set the forked repo to Private). Then this
+   folder and its contents stay private along with everything else.
+2. **Mount this folder from your OWN private repo** as a submodule, so private content lives in a
+   separate private repository even if the root repo is public:
+
+   ```bash
+   git submodule add https://github.com/YOUR-ORG/your-actions.json.storage.private.git scopes/private
+   ```
+
+   and add a matching `private` mount to `storage.json`.
+
+If you do neither and commit private files into a public repo, they will be exposed. The public example
+links to no private repo, so nothing here is exposed by default.

package/{template → seed}/storage.json

@@ -13,13 +13,14 @@
       "mount_type": "local",
       "visibility": "private",
       "default": true,
-      "description": "Your owner-only browsing memory, observations, overlays, run logs, item indexes, and unreviewed action maps. Local by default; point it at your own private repo to sync the same memory across your machines and agents."
+      "description": "Your owner-only browsing memory, observations, overlays, run logs, item indexes, and unreviewed action maps. Local by default; point it at your OWN private repo to sync the same memory across your machines and agents (see scopes/private/README.md)."
     },
     "public": {
       "path": "scopes/public",
-      "mount_type": "local",
+      "mount_type": "git_clone",
+      "repo": "https://github.com/yaniv256/actions.json.storage.public.git",
       "visibility": "public",
-      "description": "Reviewed, redacted maps you publish openly. Point this at your own public repo when you want to share."
+      "description": "Reviewed, reusable public site-action maps (Trello, Gmail, Docs, GitHub, LinkedIn, Calendar, …). Cloned from the public maps repo on first run; pull to update, or point this at your own public repo."
     }
   },
   "default_policy": {

package/template/README.md

@@ -1,74 +0,0 @@
-# actions.json storage
-
-This **is** your `actions.json.storage` workspace — operational, not an example.
-The bridge created it on first run (default: `~/.actions-json/storage`) and reads
-and writes here as your agent browses. Your browsing memory, observations, and
-action maps live in these folders.
-
-## Scopes
-
-Storage is organized by visibility. Each scope is a folder under `scopes/`; the
-runtime discovers site maps under `scopes/<scope>/sites/<host>/`.
-
-| Scope | What goes here | Git |
-|---|---|---|
-| `private/` | Your owner-only browsing memory, observations, run logs, and unreviewed maps. | Local by default. Opt in: back it with your own **private** repo to sync across your machines and agents. |
-| `public/` | Reviewed, redacted maps **you publish** openly. | Opt in: point it at your own public repo. |
-| `shared/<name>/` | Maps shared with a specific collaborator, **and** maps you pull **from** a source. | Opt in: one git remote per source. |
-
-`private` and `public` are set up. Add `shared/<name>/` when you need it.
-
-## Versioning a scope
-
-Each scope is an ordinary folder, local until you choose to version it. Turn one
-into a git repo when you want to sync or share it.
-
-**Sync your private memory across machines** — back `scopes/private/` with your
-own **private** repo so the same browsing memory follows your agent everywhere:
-
-```bash
-cd ~/.actions-json/storage/scopes/private
-git init && git add . && git commit -m "my private actions.json memory"
-git remote add origin https://github.com/<you>/<your-private-storage>.git  # private!
-git push -u origin main
-# on another machine: clone it into scopes/private instead of git init
-```
-
-This stays private — it is your repo, set to private. It only ever leaves your
-machine if you point it at a remote, and `public`/`shared` promotion still
-requires explicit review.
-
-**Publish your public maps** — make `scopes/public/` your own public repo:
-
-```bash
-cd ~/.actions-json/storage/scopes/public
-git init && git add . && git commit -m "my public actions.json maps"
-git remote add origin https://github.com/<you>/<your-public-storage>.git
-git push -u origin main
-```
-
-**Pull the official map library** — vendor maps *from* a source into a shared
-scope (the runtime discovers maps under `scopes/shared/<name>/`):
-
-```bash
-cd ~/.actions-json/storage/scopes/shared
-git clone https://github.com/yaniv256/actions.json.storage.public.git actions-json
-# maps now resolve from scopes/shared/actions-json/sites/<host>/
-```
-
-Pulling from someone else's library uses the **shared** scope (inbound), not
-`public` (which is for what *you* publish). Keep that boundary clear.
-
-## Layout
-
-```text
-storage.json              Root manifest — which scopes are mounted
-scopes/
-  private/
-    scope.json            Private scope manifest
-    sites/<host>/         Per-site maps, observations, overlays (local; sync via a private repo)
-  public/
-    scope.json            Public scope manifest
-    sites/<host>/         Reviewed, redacted maps you publish
-  shared/<name>/          Add per-collaborator or per-source as needed
-```

package/template/scopes/private/scope.json

@@ -1,17 +0,0 @@
-{
-  "protocol": "actions.json.storage.scope",
-  "version": "0.1.0",
-  "scope": "private",
-  "parent": "actions.json.storage",
-  "owner": {
-    "type": "person",
-    "id": "you"
-  },
-  "visibility": "private",
-  "default_policy": {
-    "observations": "store_freely",
-    "runs": "store_freely",
-    "overlays": "store_freely",
-    "action_maps": "draft_until_reviewed"
-  }
-}

package/template/scopes/public/scope.json

@@ -1,17 +0,0 @@
-{
-  "protocol": "actions.json.storage.scope",
-  "version": "0.1.0",
-  "scope": "public",
-  "parent": "actions.json.storage",
-  "owner": {
-    "type": "person",
-    "id": "you"
-  },
-  "visibility": "public",
-  "default_policy": {
-    "observations": "do_not_store_raw_private_observations",
-    "reports": "reviewed_public_artifact",
-    "action_maps": "reviewed_and_redacted",
-    "promotion": "review_required"
-  }
-}