@actions-json/bridge 0.1.119 → 0.1.121

package/lib/install.js

@@ -7,10 +7,13 @@ const https = require('node:https');
 const { execFileSync } = require('node:child_process');
 const { assetSlug, downloadUrl, binaryName } = require('./platform');
 
-// Resolve the package version (used to pick the matching release).
+// The bridge binary version to download. This is pinned separately from the
+// package version so the wrapper can ship changes (e.g. the bundled dictionary)
+// without rebuilding identical bridge binaries. Falls back to the package
+// version if the pin isn't set.
 function packageVersion() {
   const pkg = require('../package.json');
-  return pkg.version;
+  return pkg.bridgeBinaryVersion || pkg.version;
 }
 
 // Where we cache the downloaded binary: alongside the package, keyed by version

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,7 +1,8 @@
 {
   "name": "@actions-json/bridge",
-  "version": "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 and runs it.",
+  "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, bundles the primitive dictionary, and scaffolds a storage workspace on first run.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,6 +16,8 @@
   "files": [
     "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"
+  }
+}