@withnative/standby

This is the release-pinned acquisition front door for the local Native standby MCP runtime. It is intentionally small and dependency-free. The wrapper selects the exact platform artifact package installed by npm, verifies the artifact SHA-256 and compatibility identity, and copies it into an immutable versioned generation under ~/.local/share/native-local (or NATIVE_STANDBY_HOME).

The MCP client must launch the installed absolute path, never npx or this package. native-standby configure writes the native-local entry with --standby while preserving an existing hosted native entry:

npx --package @withnative/[email protected] native-standby install
npx --package @withnative/[email protected] native-standby configure \
  --replica-root "$HOME/.local/share/native-local" \
  --hosted-route ROUTE_DATABASE_ID \
  --origin-database-id ndb_DATABASE_ID \
  --mcp-config "$HOME/.config/mcp/config.json"
npx --package @withnative/[email protected] native-standby verify --json

install and update are idempotent. verify reports the installed source revision, engine schema, DDL fingerprint and executable checksum. rollback atomically changes only the stable launcher to the prior checksum-verified generation. It never removes or rewrites accepted/, device/, or refresh/.

Installation uses an exclusive install.lock directory and never reclaims a pre-existing lock automatically, including locks left by a crashed process or an interrupted owner publication. If an operation reports a lock, first confirm that no installer is still active (for example, inspect the exact install.lock/owner.json PID), then remove only that exact lock path and retry:

test -d "$HOME/.local/share/native-local/install.lock"
cat "$HOME/.local/share/native-local/install.lock/owner.json" 2>/dev/null || true
# after confirming no native-standby installer is active:
rmdir "$HOME/.local/share/native-local/install.lock" 2>/dev/null || \
  rm -rf -- "$HOME/.local/share/native-local/install.lock"

Use the configured NATIVE_STANDBY_HOME path instead when one is set. Never remove a broad parent directory or a lock path belonging to another install.

The artifact package is produced by the release pipeline and must contain package.json metadata shaped like this (the binary is not built on the laptop):

{
  "version": "0.1.0",
  "nativeStandbyArtifact": {
    "contract": "native.standby-artifact.v1",
    "version": 1,
    "platform": "linux-x86_64",
    "sourceSha": "40 lowercase hex characters",
    "artifactSha256": "64 lowercase hex characters",
    "engineSchemaVersion": 57,
    "ddlSha256": "64 lowercase hex characters",
    "standbyRequired": true,
    "binary": "bin/mcp-stdio"
  }
}

The release artifact is built with NATIVE_CE_GIT_SHA set to the full source commit. A checkout build stamped dev is deliberately not a supported standby artifact. External npm/GitHub publication is a separate approval-gated release operation and is not performed by this package's tests or local commands.

Installation executes the packaged binary with --standby-identity and checks that its self-reported source SHA, engine schema, frozen DDL fingerprint, standby contract, and executable SHA-256 agree with the package metadata. A caller-supplied manifest cannot turn an unstamped, mismatched, or non-mcp-stdio file into an installable generation.

Maintainers stage the platform package from a previously built release binary; the staging command does not compile or download anything:

mkdir -p release/npm
node packages/native-standby/scripts/stage-artifact.mjs \
  --binary target/release/mcp-stdio \
  --version 0.1.0 \
  --source-sha "$NATIVE_CE_GIT_SHA" \
  --engine-schema-version 57 \
  --ddl-sha256 FROZEN_DDL_SHA256 \
  --out release/npm/standby-linux-x64-gnu

The staged package is the only input to the later, approval-gated npm publish; the wrapper's exact-version optional dependency must point to the same version.