borgmcp-shared 0.2.2

package/dist/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"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"}

package/docs/compatibility.md

@@ -0,0 +1,38 @@
+# Protocol Compatibility
+
+`borgmcp-shared` versions the contracts shared by Borg MCP clients and server
+implementations. Package versions and protocol generations are related but are
+not interchangeable: a package release can add helpers without changing the
+wire protocol.
+
+| Package range | Protocol generation | Status |
+| --- | --- | --- |
+| `>=0.2.0 <0.3.0` | `1` | Versioned envelope, runtime codecs, and adapter conformance |
+
+## Change Policy
+
+Consumers must pin `^0.2.0`, which npm interprets as `>=0.2.0 <0.3.0`. During
+the pre-1.0 series, a breaking envelope or wire-contract change requires a
+minor release (`0.3.0`); additive compatible contracts and corrections use a
+patch release (`0.2.x`). Consumers widen the minor range only after deliberate
+compatibility review. A broad `<1.0.0` range is unsafe because pre-1.0 minor
+versions may break the wire contract.
+
+A wire-shape change must include all of the following:
+
+1. A new or updated implementation-neutral conformance vector.
+2. A documented client and server rollout order.
+3. A compatibility entry that identifies the affected package and protocol
+   versions.
+4. A migration window when older deployed clients or servers can still be in
+   use.
+
+Removing or reinterpreting an existing field is a protocol-breaking change even
+when TypeScript permits it. Implementations must not infer compatibility from a
+successful build alone; they should check the declared protocol generation and
+run the shared conformance suite.
+
+Model/provider selection is intentionally absent from the `0.2.x` coordination
+contract. Agent CLIs own model configuration; Borg servers may expose the
+separate advisory `reported_model` field for session observability, but clients
+must not use it for routing, launch configuration, or authorization.

package/docs/releasing.md

@@ -0,0 +1,220 @@
+# Publishing `borgmcp-shared`
+
+This repository publishes immutable public releases from a protected GitHub
+Actions environment. A release is built once, audited as a tarball, and then
+published from that exact tarball. Local publication and publication from an
+unreviewed branch are not supported.
+
+The active release policy is governed by the ratified
+`shared-package-consumption` and `npm-publish-sole-operator-approval` decisions.
+This document describes the operator procedure; it does not authorize a release.
+
+## Permanent Repository Configuration
+
+Configure these controls before creating a release tag:
+
+1. Keep `.github/workflows/publish.yml` as the only npm trusted-publisher
+   workflow. The workflow uses a GitHub-hosted runner, exact Node and npm
+   versions, no dependency cache, and only `contents: read` plus
+   `id-token: write` in the protected publish job. npm is installed with
+   lifecycle scripts disabled under an isolated `${RUNNER_TEMP}` prefix; only
+   that prefix's bin directory enters `GITHUB_PATH`. Never update the active
+   global npm installation from within npm itself.
+2. Create a GitHub environment named `npm-publish`. Require an authorized
+   approval from the sole operator `TheodorStorm`, allow self-review so that the
+   sole-operator path remains executable, and prevent administrators from
+   bypassing its protection rules. Store npm bootstrap credentials only in this
+   environment. This exact shape is ratified by
+   `npm-publish-sole-operator-approval`; adding any other reviewer or bypass
+   actor requires a new decision.
+3. Add an active tag ruleset whose only included ref is
+   `refs/tags/v*.*.*`. Enable creation, update (without fetch-and-merge),
+   deletion, and non-fast-forward restrictions. The sole bypass actor is the
+   release-operator user `TheodorStorm` (GitHub user ID `12745431`), with no
+   role, administrator, team, application, or deploy-key bypass. Require an
+   annotated tag; the workflow rejects lightweight tags and tags whose commit is
+   not on `main`.
+4. Set the environment variable `NPM_EXPECTED_OWNER` to `byteventures`, the npm
+   maintainer returned by `npm view borgmcp maintainers`. Do not infer this value
+   from package metadata.
+5. Keep the GitHub repository public when provenance is generated. npm cannot
+   issue provenance for a public package built from a private GitHub repository,
+   and the workflow stops if the repository is private.
+6. Protect `refs/heads/main` with an active ruleset and no bypass actors. Require
+   resolved review threads and the `package (20)` and `package (22)` checks from
+   GitHub Actions application ID `15368`, with strict status checking. Set the
+   GitHub approval count to zero and disable stale-review dismissal, code-owner
+   review, and last-push approval: the separately recorded cube CR, Security,
+   and Release Quality gates are the human evidence, while a GitHub approval
+   requirement would be inoperable for the sole repository operator. Allow
+   merge commits only and protect deletion and non-fast-forward operations. Do
+   not add a restrictive update rule, which would block normal pull-request
+   merges without a bypass.
+7. Restrict Actions to selected GitHub-owned actions and require full commit-SHA
+   pins. Do not allow all verified Marketplace publishers or any custom pattern.
+   The CI and publish workflows need only `actions/checkout`,
+   `actions/setup-node`, `actions/upload-artifact`, and
+   `actions/download-artifact`, each pinned in source. Keep workflow tokens
+   read-only and prohibit them from approving pull requests.
+8. Enable GitHub private vulnerability reporting, secret scanning, push
+   protection, and Dependabot security updates unconditionally. Enable secret
+   validity checks and non-provider pattern detection whenever the organization
+   plan licenses them. GitHub requires a paid plan with GitHub Secret Protection
+   for [validity checks](https://docs.github.com/en/code-security/how-tos/secure-your-secrets/customize-leak-detection/enable-validity-checks)
+   and [non-provider patterns](https://docs.github.com/en/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns).
+   The configuration guard accepts those two controls as disabled only while the
+   live organization plan is exactly `free`; a plan change makes them mandatory.
+   `SECURITY.md` directs reporters to the private reporting path, so disabled
+   reporting is always a release-blocking documentation failure.
+
+The environment approval is the final technical control. Approval must remain
+pending while Security reviews the artifact produced by the `verify` job.
+GitHub's ephemeral workflow token cannot read every repository-administration
+setting checked by `scripts/verify-release-configuration.mjs`. An authorized
+operator must run the guard with an administration-capable token before creating
+the tag and again immediately before approving the environment:
+
+```sh
+GITHUB_TOKEN="$(gh auth token)" node scripts/verify-release-configuration.mjs
+```
+
+The token is read from the operator's credential store and must not be written
+to the repository, an artifact, or workflow output. Any guard failure blocks the
+tag or environment approval.
+
+Every release and verification-only run must be a first attempt. The workflow
+logs `GITHUB_RUN_ID` and `GITHUB_RUN_ATTEMPT`, rejects any attempt other than `1`
+before dependency installation, and includes the same values in the uploaded
+`RUN_EVIDENCE` file. Never use the Actions rerun controls to advance a failed
+immutable tag or proof run.
+
+Both jobs reject a repository-root `.npmrc` before their first npm command. The
+exact npm bootstrap uses isolated runner-temp prefix, user config, and cache
+paths, forces `https://registry.npmjs.org`, disables scripts, and verifies both
+the installed npm version and registry before adding its bin directory to
+`GITHUB_PATH`.
+
+## First-Publish Bootstrap
+
+npm trusted publishing cannot be configured until the unscoped package exists.
+The initial `v0.2.0` bootstrap run, `29353763609`, failed during verification
+before producing an artifact or reaching publication. The failed `v0.2.0` tag is
+immutable and MUST NOT be moved, reused, or rerun. The separately authorized
+`v0.2.1` tag run, `29355823822`, also failed verification before dependency
+installation or artifact creation because the checkout action replaced its local
+annotated-tag ref with the peeled commit. The remote `v0.2.1` tag remains valid
+and immutable and MUST NOT be moved, reused, or rerun.
+
+The first protected-main verification-only proof run, `29356980492`, confirmed
+the repaired tag/source trust checks, then failed before artifact upload because
+npm 11 interpreted the bare `release/<tarball>` argument as a package/GitHub spec
+instead of a local file. It produced no auditable artifact and MUST NOT be rerun.
+The workflow now passes generated tarballs to both npm dry-run and publication as
+explicit `./release/<tarball>` filesystem paths.
+
+The next protected-main proof run, `29357632667`, passed every verification gate
+against immutable `v0.2.1`, structurally skipped the publish job, and produced an
+exact artifact that passed Security audit. This proved the corrected tag,
+protected-main, input, artifact, and npm local-file handling without reusing the
+tag for publication.
+
+Under the ratified `borgmcp-shared-recovery-version` decision, `0.2.2` is the
+selected recovery version. The source bump does not itself authorize a tag,
+environment approval, or publication.
+
+The eventual first publication will use one temporary credential while still
+generating provenance from GitHub Actions.
+
+Before creating the tag, the release operator must verify all of the following:
+
+- The npm account is the account that owns `borgmcp`, uses authentication-and-
+  writes 2FA, and has tested, protected recovery methods.
+- `borgmcp-shared` is still unclaimed. An `E404` is expected. Any package or
+  ownership result that differs from the reviewed state is a stop condition.
+- Code Review, load-bearing Security Review, and Release Quality approved the
+  exact commit on `main`.
+- The Queen explicitly authorized generating the final release artifact. This
+  authorization does not by itself approve the later environment deployment.
+
+Create a short-lived, least-privilege npm publish token under the verified owner
+account. Store it as the `NPM_TOKEN` secret in the `npm-publish` environment;
+never place it in repository variables, workflow files, shell history,
+`package.json`, a committed `.npmrc`, or an issue. Set the protected environment
+variable `ALLOW_UNCLAIMED_FIRST_PUBLISH` to `true` only for this bootstrap.
+
+The `0.2.2` package, lockfile, runbook, and version assertions must pass fresh CR,
+Security, and Release Quality gates and merge to protected `main` before the
+Coordinator creates its matching annotated tag under
+`borgmcp-shared-first-publish-autonomy`. The tag starts the workflow but does not
+immediately publish. The unprivileged `verify` job performs the following gates
+first:
+
+- verifies the public repository, annotated tag, exact package version, and
+  ancestry on `main`;
+- installs the lockfile without lifecycle scripts and runs audit, type checks,
+  all tests, a clean build, and the tracked-`dist` drift check;
+- creates one tarball with lifecycle scripts disabled;
+- enforces the explicit public file allowlist, legal files, dependency and
+  lifecycle policy, size limits, and resolvable source maps;
+- exercises npm's publish metadata in dry-run mode; and
+- installs the exact tarball with scripts disabled in a clean consumer, verifies
+  its production tree, and imports every reviewed public export; and
+- uploads the tarball, verifier report, and SHA-512 checksum for seven days.
+
+Security must download and audit that exact workflow artifact. After Security
+approves the tarball, Release Quality confirms the operator procedure, and the
+Queen explicitly authorizes the public flip, an authorized reviewer may approve
+the waiting `npm-publish` environment deployment. The publish job downloads and
+checksum-verifies the same artifact, repeats the artifact verifier, checks that
+`0.2.2` is absent and the name is unclaimed as expected, and publishes only the
+downloaded tarball with `--access public --provenance`.
+
+Immediately after a successful first publish:
+
+1. Confirm the workflow's registry-integrity, owner, and SLSA provenance checks
+   passed before changing any consumer dependency.
+2. Configure npm's trusted publisher for organization `Byte-Ventures`, repository
+   `borg-mcp-shared`, workflow filename `publish.yml`, environment
+   `npm-publish`, and the `npm publish` action.
+3. Remove the `NPM_TOKEN` environment secret, revoke the bootstrap token at npm,
+   and set `ALLOW_UNCLAIMED_FIRST_PUBLISH` to `false`.
+4. Configure npm publishing access to require 2FA and disallow traditional
+   tokens. Future releases authenticate through short-lived OIDC credentials.
+5. Only then replace consumers' exact Git SHA dependencies with
+   `borgmcp-shared@^0.2.0` and commit their registry lockfiles.
+
+## Later Releases
+
+Later releases follow the same source gates, annotated protected tag, exact
+tarball audit, Queen authorization, and environment approval. The registry
+preflight requires the package to be owned by `NPM_EXPECTED_OWNER` and rejects
+an existing target version. It also fails if
+`ALLOW_UNCLAIMED_FIRST_PUBLISH` is not `false` or any `NPM_TOKEN` remains;
+npm must exchange the workflow's OIDC identity through the configured trusted
+publisher.
+
+## Stop and Recovery Conditions
+
+Stop without approving the environment when any of these conditions occurs:
+
+- the repository is private, the tag is lightweight or unprotected, the tag
+  does not exactly match `v<package version>`, or its commit is not on `main`;
+- the approved commit, tag target, tarball checksum, or audit artifact differs;
+- `GITHUB_RUN_ATTEMPT` is not `1`, or run/attempt evidence is missing;
+- tests, audit, build, tracked output, artifact policy, legal metadata, or dry
+  run fails;
+- the npm name, expected owner, account 2FA, recovery methods, credential scope,
+  trusted-publisher configuration, or environment protection cannot be verified;
+- the target version already exists, npm returns anything other than the
+  expected ownership/availability response, or npm/GitHub is degraded; or
+- final CR, Security, Release Quality, exact-tarball Security approval, or Queen
+  authorization is missing.
+
+npm versions are immutable. Never retry by overwriting `0.2.0`, moving the tag,
+force-pushing a branch, or publishing from a local rebuild. A failed verification
+before publication requires fixing the source and beginning again with a new
+reviewed version/tag plan. If npm accepted the version but integrity or
+provenance verification failed, block every consumer migration, preserve the
+workflow logs and artifact, and escalate as a release incident. Do not unpublish,
+deprecate, or publish a replacement version without a separately reviewed and
+authorized recovery decision.

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "borgmcp-shared",
+  "version": "0.2.2",
+  "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./templates": {
+      "types": "./dist/templates.d.ts",
+      "import": "./dist/templates.js"
+    },
+    "./role-section": {
+      "types": "./dist/role-section.d.ts",
+      "import": "./dist/role-section.js"
+    },
+    "./log-stream-hwm": {
+      "types": "./dist/log-stream-hwm.d.ts",
+      "import": "./dist/log-stream-hwm.js"
+    },
+    "./drone-address": {
+      "types": "./dist/drone-address.d.ts",
+      "import": "./dist/drone-address.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "import": "./dist/protocol/index.js"
+    },
+    "./domain": {
+      "types": "./dist/domain/index.d.ts",
+      "import": "./dist/domain/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "import": "./dist/conformance/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "docs"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "verify:artifact": "node scripts/verify-packed-artifact.mjs",
+    "prepack": "npm run check && npm test && npm run build"
+  },
+  "keywords": [
+    "borgmcp",
+    "mcp",
+    "multi-agent",
+    "protocol",
+    "conformance"
+  ],
+  "author": "Byte Ventures IO AB",
+  "license": "Apache-2.0",
+  "homepage": "https://borgmcp.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byte-Ventures/borg-mcp-shared.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Byte-Ventures/borg-mcp-shared/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}