scripts

Maintenance and automation scripts for the template. Shell scripts are written for Bash and generally use set -euo pipefail; Python scripts are executable with python3.

Quick map

Script	Purpose
asciicheck.py	Check/fix unexpected non-ASCII characters.
block-env-commits.sh	Prevent .env* secrets from being committed.
build-web.sh	Build the Next.js web UI static export (apps/web/out/).
bump-version.sh	Update version-bearing files from the Cargo.toml version.
check-blob-size.py	Block unexpectedly large changed blobs.
check-coupled-files.sh	Warn when files that normally change together drift.
check-dependency-updates.sh	Report lockfile-compatible and latest dependency updates.
check-file-size.sh	Pre-commit source file size budget.
check-runtime-current.sh	Detect stale Docker/systemd runtimes.
check-yanked-exceptions.py	Fail on unapproved or expired yanked dependency exceptions.
check-openapi.py	Generate/check docs/generated/openapi.json for the REST API surface.
check-schema-docs.py	Generate/check docs/MCP_SCHEMA.md and action docs.
check-scaffold-intent-contract.py	Validate scaffold intent schema and examples without third-party dependencies.
check-identity-contract.py	Reject stale template identities, default ports, and duplicate action registries.
check-version-sync.sh	Check version consistency.
generate-cli.sh	Generate a standalone CLI for this server via mcporter (requires running server).
pre-release-check.sh	Full release-readiness gate, including schema/OpenAPI/scaffold contract drift checks.
refresh-docs.sh	Refresh ignored reference docs with Axon/Repomix.
repair.sh	Stop, rebuild, and restart the service via systemd or Docker Compose.
run-ascii-check.sh	Collect tracked files and run asciicheck.py; pass --fix to rewrite in place.
sync-cargo.sh	Sync Cargo.lock into plugin data directories.
test-mcp-auth.sh	Smoke-test HTTP MCP bearer auth.
test-live-jsonrpc.sh	Smoke-test a live MCP server and disposable SSH fixture.
test-template-features.sh	Fast template invariant smoke tests.
validate-plugin-layout.sh	Validate Claude/Codex/Gemini plugin package layout.
web-watch.sh	Watch apps/web for changes and rebuild on save (requires watchexec).

blob-size-allowlist.txt is data for check-blob-size.py, not an executable script.

---

Script reference

asciicheck.py

python3 scripts/asciicheck.py README.md Justfile
python3 scripts/asciicheck.py --fix README.md
just ascii-check
just ascii-fix

Checks files for unexpected non-ASCII characters. A small allowlist covers intentional documentation glyphs such as section signs, arrows, and box-drawing characters.

block-env-commits.sh

bash scripts/block-env-commits.sh

Pre-commit guard that rejects staged .env, .env.local, .env.prod, etc. .env.example is allowed.

bump-version.sh

scripts/bump-version.sh 1.3.5
scripts/bump-version.sh patch
scripts/bump-version.sh minor
scripts/bump-version.sh major

Updates Cargo.toml, Cargo.lock, and server.json when present. Plugin manifests intentionally remain versionless.

check-blob-size.py

python3 scripts/check-blob-size.py
python3 scripts/check-blob-size.py --base origin/main --head HEAD --max-bytes 512000
just blob-size-check

Checks changed git blobs against a size budget. Use scripts/blob-size-allowlist.txt for intentional large artifacts such as plugin binaries.

check-coupled-files.sh

scripts/check-coupled-files.sh origin/main HEAD
just coupled-files-check

CI-oriented guard for files that usually change together, such as script changes with scripts/README.md, schema changes with docs/MCP_SCHEMA.md, and automation changes with docs. Schema changes may omit docs/MCP_SCHEMA.md when scripts/check-schema-docs.py --check proves the generated docs are already current.

check-dependency-updates.sh

scripts/check-dependency-updates.sh
scripts/check-dependency-updates.sh --skip-search
scripts/check-dependency-updates.sh --fail-on-updates
just deps-check

Read-only dependency drift report. It runs cargo update --dry-run, then checks direct root dependencies against crates.io unless --skip-search is used.

check-file-size.sh

scripts/check-file-size.sh
MAX_RS=450 MAX_TS=350 scripts/check-file-size.sh
just file-size-check

Checks staged .rs, .ts, and .tsx files for effective production lines. Test files and Rust inline #[cfg(test)] modules are exempted.

check-openapi.py

python3 scripts/check-openapi.py --write
python3 scripts/check-openapi.py --check
just openapi
just openapi-check

Generates docs/generated/openapi.json for the Synapse REST API surface, including probes and POST /v1/synapse. Operation metadata is derived from src/actions/operations.rs; MCP-only operations remain documented separately.

check-scaffold-intent-contract.py

python3 scripts/check-scaffold-intent-contract.py
just scaffold-contract-check

Validates docs/contracts/scaffold-intent.schema.json plus checked-in examples under docs/contracts/examples/. This is a targeted validator, not a full JSON Schema implementation, so it can run in fresh checkouts without extra Python packages.

check-runtime-current.sh

scripts/check-runtime-current.sh
scripts/check-runtime-current.sh --mode systemd --expected-binary target/release/synapse
scripts/check-runtime-current.sh --mode docker --pull --compose-dir .
just runtime-current

Systemd mode compares the running process hash to the unit ExecStart binary and optional expected binary. Docker mode compares the running container image ID with the local Compose image ID.

check-yanked-exceptions.py

python3 scripts/check-yanked-exceptions.py

Runs the Cargo Deny advisories check and rejects every yanked dependency except the exact, documented, time-bounded exception in the script. It also fails once an exception reaches its expiry date, ensuring the waiver cannot become permanent by accident.

check-schema-docs.py

python3 scripts/check-schema-docs.py --write
python3 scripts/check-schema-docs.py --check
just schema-docs
just schema-docs-check

Treats src/actions/operations.rs::OPERATION_SPECS as canonical and verifies schema docs, help text, README, and plugin skill mentions. Generated output lives in docs/MCP_SCHEMA.md, including the required title and created/updated frontmatter used by the fleet documentation contract.

build-web.sh

bash scripts/build-web.sh
just build-web

Builds the Next.js web UI static export from apps/web/. Installs node_modules if absent, then runs pnpm build. Output lands in apps/web/out/ and is embedded into the binary via the web feature. No-ops silently when apps/web/ does not exist.

check-version-sync.sh

scripts/check-version-sync.sh
scripts/check-version-sync.sh /path/to/project

Validates that version-bearing files agree. Missing CHANGELOG.md entries are warnings; mismatched versions are failures.

generate-cli.sh

SYNAPSE_MCP_TOKEN=... bash scripts/generate-cli.sh
just generate-cli

Generates a standalone CLI binary for this server via mcporter generate-cli. Requires a running server on port 40080 and mcporter in PATH. Caches a schema hash under dist/.cache/ and skips regeneration when the tool schema is unchanged. The generated binary embeds the token — do not commit or share it.

TEMPLATE: Update the port and token env var name in this script when adapting.

pre-release-check.sh

scripts/pre-release-check.sh
scripts/pre-release-check.sh --skip-verify --skip-build-plugin
scripts/pre-release-check.sh --mcporter
just pre-release

Runs the release gate: pattern checks, plugin validation, schema docs, template feature smoke tests, version sync, blob size, ASCII hygiene, just verify, and just build-plugin. --mcporter also runs just test-mcporter and requires a running server.

refresh-docs.sh

scripts/refresh-docs.sh
scripts/refresh-docs.sh --dry-run
scripts/refresh-docs.sh --skip-crawl
scripts/refresh-docs.sh --skip-repomix

Refreshes ignored reference docs under docs/references/:

docs/references/
├── mcp/docs/          # crawled modelcontextprotocol.io
├── mcp/repos/         # Repomix packs: rust-sdk, spec, registry
├── claude-code/       # crawled code.claude.com
├── mcporter/docs/     # sparse-cloned mcporter docs
├── mcporter/repos/    # Repomix pack of mcporter source
├── INDEX.md
└── CHANGES.md

Environment:

Variable	Default	Description
AXON_OUTPUT_DIR	~/.axon/output	Axon host output directory.
REPOMIX_BIN	auto-detected	Repomix executable, otherwise npx --yes repomix.

The MCP spec and registry packs ignore huge SVG/Excalidraw diagrams to keep text reference packs usable.

repair.sh

bash scripts/repair.sh
just repair

Stops, rebuilds, and restarts the synapse service. Detects the active service manager automatically: prefers the synapse.service systemd user unit, then falls back to Docker Compose. Useful after an in-place binary update without a full docker compose build.

run-ascii-check.sh

bash scripts/run-ascii-check.sh          # check mode
bash scripts/run-ascii-check.sh --fix    # rewrite smart punctuation to ASCII
just ascii-check
just ascii-fix

Collects all tracked *.md, *.rs, *.toml, *.json, *.yml, *.yaml, *.sh, and *.py files (excluding docs/references/ and docs/sessions/) and passes them to scripts/asciicheck.py. Used in CI via bash scripts/run-ascii-check.sh and locally via the Justfile aliases.

sync-cargo.sh

bash scripts/sync-cargo.sh

Copies Cargo.lock from CLAUDE_PLUGIN_ROOT to CLAUDE_PLUGIN_DATA when needed. Falls back to cargo fetch if the copy cannot be completed.

test-mcp-auth.sh

SYNAPSE_MCP_TOKEN=... scripts/test-mcp-auth.sh
scripts/test-mcp-auth.sh --url http://localhost:40080/mcp --token ...
scripts/test-mcp-auth.sh --check-x-api-key

Checks that /health is public, /mcp rejects missing/bad bearer tokens with 401, and /mcp accepts a valid bearer token. x-api-key is optional because the template auth layer uses bearer tokens.

test-template-features.sh

bash scripts/test-template-features.sh
just template-features

Fast shell smoke tests for invariants that are awkward as Rust tests: .env blocking, agent docs symlinks, plugin layout, schema docs, and ASCII hygiene.

web-watch.sh

bash scripts/web-watch.sh
just web-watch

Watches apps/web/ for changes and rebuilds on save using watchexec. Ignores .next/, out/, and node_modules/. Requires watchexec: cargo install watchexec-cli.

validate-plugin-layout.sh

scripts/validate-plugin-layout.sh
PLUGIN_ROOT=plugins/synapse scripts/validate-plugin-layout.sh
just validate-plugin

Validates Claude, Codex, and Gemini plugin manifests, shared MCP config, skills, sensitive fields, and the rule that plugin manifests do not contain version.

Also enforces that the plugin ships no lifecycle hooks: no manifest declares a hooks key, no hooks/ directory is packaged, and monitors/monitors.json invokes the synapse binary from PATH rather than a hooks/ wrapper script. The old wrapper exited 0 when the binary was missing, which hid the failure; a direct invocation surfaces it as a monitor error.

---

Hook integration

block-env-commits.sh, check-version-sync.sh, and check-file-size.sh are designed for lefthook pre-commit integration. Install hooks with:

just install-hooks

Maintenance rule

When adding, renaming, or changing a script, update this README and any Justfile recipe that calls it.