@actions-json/bridge 0.1.120 → 0.1.121

package/README.md

@@ -1,34 +1,37 @@
 # @actions-json/bridge
 
 Run the [actions.json](https://yaniv256.github.io/actions.json/) MCP bridge with
-`npx` — no Rust toolchain required. On first run this downloads the prebuilt
-`actions-json-mcp` binary for your platform from the GitHub release, caches it,
-and runs it. The primitive dictionary (browser-control tool catalog) is bundled,
-so you don't pass `--actions`.
+`npx` — no Rust toolchain, no setup. On first run it downloads the prebuilt
+`actions-json-mcp` binary for your platform, bundles the primitive dictionary
+(so you don't pass `--actions`), and scaffolds a storage workspace at
+`~/.actions-json/storage` (so you don't pass `--storage-root`).
 
 ## Usage
 
 ```bash
-npx @actions-json/bridge mcp --storage-root /path/to/.storage
+npx @actions-json/bridge mcp
 ```
 
-Register it with a coding agent — for Claude Code:
+Register it with a coding agent — Claude Code:
 
 ```bash
-claude mcp add actions-json -- \
-  npx -y @actions-json/bridge mcp --storage-root /path/to/.storage
+claude mcp add actions-json -- npx -y @actions-json/bridge mcp
 ```
 
-For Codex:
+Codex:
 
 ```bash
-codex mcp add actions-json -- \
-  npx -y @actions-json/bridge mcp --storage-root /path/to/.storage
+codex mcp add actions-json -- npx -y @actions-json/bridge mcp
 ```
 
-All arguments after the binary pass straight through to `actions-json-mcp`. To
-use a custom primitive dictionary, pass your own `--actions <file>` and the
-bundled default is skipped. See
+Overrides (the defaults are skipped when you pass your own):
+
+- `--storage-root <dir>` — use a different storage workspace. Or set
+  `ACTIONS_JSON_STORAGE`.
+- `--actions <file>` — use a custom primitive dictionary instead of the bundled
+  one.
+
+All arguments after the binary pass straight through to `actions-json-mcp`. See
 [Getting Started](https://yaniv256.github.io/actions.json/getting-started.html).
 
 ## Platforms

package/bin/cli.js

@@ -9,6 +9,7 @@
 const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { ensureBinary } = require('../lib/install');
+const { ensureStorageRoot } = require('../lib/storage');
 
 // 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
@@ -17,13 +18,25 @@ const { ensureBinary } = require('../lib/install');
 const BUNDLED_ACTIONS = path.join(__dirname, '..', 'dictionary', 'overlay.actions.json');
 const SUBCOMMANDS_NEEDING_ACTIONS = new Set(['mcp', 'serve']);
 
-function withDefaultActions(args) {
-  const sub = args[0];
-  if (!SUBCOMMANDS_NEEDING_ACTIONS.has(sub)) return args;
-  if (args.includes('--actions')) return args;
-  if (args.includes('--help') || args.includes('-h')) return args;
-  // Insert right after the subcommand.
-  return [args[0], '--actions', BUNDLED_ACTIONS, ...args.slice(1)];
+function isRunSubcommand(args) {
+  return SUBCOMMANDS_NEEDING_ACTIONS.has(args[0]) &&
+    !args.includes('--help') && !args.includes('-h');
+}
+
+// Inject defaults the user shouldn't have to specify: the bundled primitive
+// dictionary (--actions) and a scaffolded storage root (--storage-root). Both
+// are skipped if the user passed their own.
+function withDefaults(args) {
+  if (!isRunSubcommand(args)) return args;
+  const out = [args[0]];
+  if (!args.includes('--actions')) {
+    out.push('--actions', BUNDLED_ACTIONS);
+  }
+  if (!args.includes('--storage-root')) {
+    out.push('--storage-root', ensureStorageRoot());
+  }
+  out.push(...args.slice(1));
+  return out;
 }
 
 async function main() {
@@ -36,7 +49,7 @@ async function main() {
     return;
   }
 
-  const args = withDefaultActions(process.argv.slice(2));
+  const args = withDefaults(process.argv.slice(2));
   const child = spawn(bin, args, { stdio: 'inherit' });
 
   // Forward termination signals so the bridge shuts down cleanly.

package/lib/storage.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// 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
+// coding agent launches the bridge.
+function defaultStorageRoot() {
+  return (
+    process.env.ACTIONS_JSON_STORAGE ||
+    path.join(os.homedir(), '.actions-json', 'storage')
+  );
+}
+
+const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
+
+// Recursively copy the scaffold, skipping the .gitkeep placeholders (they only
+// exist to ship empty dirs inside the package/repo).
+function copyScaffold(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()) {
+      copyScaffold(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+// Ensure the storage root exists; scaffold it from the bundled template on
+// first run. 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 });
+    copyScaffold(SCAFFOLD_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 });
+    }
+    process.stderr.write(`Created actions.json storage at ${target}\n`);
+  }
+  return path.resolve(target);
+}
+
+module.exports = { ensureStorageRoot, defaultStorageRoot };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@actions-json/bridge",
-  "version": "0.1.120",
+  "version": "0.1.121",
   "bridgeBinaryVersion": "0.1.119",
-  "description": "Run the actions.json MCP bridge with npx — no Rust toolchain required. Downloads the prebuilt actions-json-mcp binary for your platform, bundles the primitive dictionary, and runs it.",
+  "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 scaffolds a storage workspace on first run.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
     "bin/",
     "lib/",
     "dictionary/",
+    "scaffold/",
     "README.md"
   ],
   "engines": {

package/scaffold/README.md

@@ -0,0 +1,76 @@
+# actions.json storage scaffold
+
+This is a starter `actions.json.storage` workspace. The `init` step copies it to
+`.storage/` in your `actions.json` checkout, where it lives **inside the folder
+but is not part of the code repo** (`.storage/` is gitignored).
+
+Point the bridge at it with `--storage-root .storage`.
+
+## Scopes
+
+Storage is organized by visibility. Each scope is just 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: point it at 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` exist in the scaffold. Add `shared/<name>/` when you need
+it.
+
+## Opening a scope for sharing or syncing
+
+The scaffold is local-only until you choose to version a scope. Each scope is an
+ordinary folder, so you turn one into a git repo when you want to.
+
+**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 .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 .storage/scopes/private instead of 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 .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 already discovers maps under `scopes/shared/<name>/`):
+
+```bash
+cd .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/scaffold/scopes/private/scope.json

@@ -0,0 +1,17 @@
+{
+  "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/scaffold/scopes/public/scope.json

@@ -0,0 +1,17 @@
+{
+  "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"
+  }
+}

package/scaffold/storage.json

@@ -0,0 +1,33 @@
+{
+  "protocol": "actions.json.storage",
+  "version": "0.1.0",
+  "owner": {
+    "type": "person",
+    "id": "you"
+  },
+  "visibility": "root-private",
+  "default_mount": "private",
+  "mounts": {
+    "private": {
+      "path": "scopes/private",
+      "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."
+    },
+    "public": {
+      "path": "scopes/public",
+      "mount_type": "local",
+      "visibility": "public",
+      "description": "Reviewed, redacted maps you publish openly. Point this at your own public repo when you want to share."
+    }
+  },
+  "default_policy": {
+    "observations": "write_to_private_scope",
+    "item_indexes": "write_to_private_scope",
+    "runs": "write_to_private_scope",
+    "overlays": "write_to_private_scope",
+    "action_maps": "reviewed_change_in_scope",
+    "promotion": "review_required"
+  }
+}