Chapter 0

How to Use This Guide

What this book covers, what it assumes you already know, and where that other stuff lives.

xops is the operating layer for Node.js repositories — one command surface for the work around npm, git, tests, and release. This book is the deep dive into the half of xops that matters when you're actually shipping something: the release lifecycle, the optional package graph, the safety net around publishing, and the operational playbooks that turn ad-hoc release scripts into repeatable, risk-classified commands.

This book assumes you already know the basics of the xops command surface, xops ask, and everyday flags like --build/--test/--filter — that's the companion book, xops for Dummies: the Daily CLI. This book does not re-explain those; it goes straight into what happens when you run xops release or xops --full-flow for real.

The stamps in the margins

Who this is for

You're the developer who runs the release, the person who set up a monorepo's publish scripts, or the code agent operator who needs xops release to fail loudly and safely instead of silently shipping a half-built package. You don't need to memorize every JSON key in xops.json; you do need to know the order things happen in, what the pack-check actually blocks, and which exit code means "your problem" versus "the environment's problem."

Chapter 1

The Release Lifecycle

Fix, install, build, test, publish, push — in that order, and why the order is not negotiable.

Operation order

For each package, xops runs: [fix] → install → build → test → publish → push. Only the requested operations run. fix runs by default only for --publish-flow and --full-flow, or when --fix is passed explicitly; --no-fix skips it.

xops --publish-flow   # fix, install, publish, and push, with a final report
xops --full-flow      # fix, install, build, test, publish, and push, with a final report

Dependency-aware execution order

Local package relationships are mapped automatically. If @x12i/api depends on @x12i/core, then @x12i/core is installed, built, tested, and published first. Dependency cycles are detected and reported before any command runs.

Releasing from a subfolder gets an extra safety check: when you run lifecycle commands from a package's own folder, xops walks to the git root, finds sibling packages, and compares their local version to what you declared. If a sibling is ahead of your declared range or not yet published:

Git behavior: monorepo vs. multi-repo

In a monorepo, all npm lifecycle steps run across every package first, then git add/commit/push runs once at the repository root. In multi-repo mode, each package/repo completes its full lifecycle — including its own push — before xops moves to the next repo. If there are no git changes to commit, xops reports that and continues rather than failing.

Chapter 2

The Optional Package Graph

xops.json documents publish order and release profiles — and nothing changes until you opt in.

Discovery doesn't need it

xops finds packages from package.json files without any extra configuration. By default, discovery is scoped: inside a git repo, to that repo's root; inside an npm workspace, to the workspace root; anywhere else, to the current folder only. Pass --all to scan every package.json recursively, including nested git repos.

What xops.json is for

Nothing changes unless you opt in. xops.json is a machine-readable package graph — not a replacement for package.json, but a complement documenting discovery layout, publish sequences, local dependency edges, known cycles, and release profiles. Add it only when a repo benefits from explicit publish order, documented dev/test cycles, or tiered releases.

xops map                        # writes xops.json (backs up existing to xops.json.bak)
xops map-to ./custom-graph.json # writes to a custom file
xops map-out                    # prints JSON to stdout

Once xops.json exists at the repo root, xops picks it up for list, validate, and lifecycle commands: publish order comes from its sequences, relationships still come from each package.json by default (operations.graphSource defaults to package-json), private roots are excluded via operations.privatePackages, and documented dev cycles are respected when operations.allowDocumentedDevDependencyCycles is set.

Fix configuration lives here too

Once you have xops.json, you can pin toolchain versions or disable automatic fix for lifecycle flows:

{
  "operations": {
    "autoFix": false,
    "fix": {
      "dependencies": true,
      "devDependencies": false,
      "peerDependencies": false,
      "exclude": ["typescript", "@types/node"]
    }
  }
}

Chapter 3

Publish Safety

The pack-check that runs no matter what your ignore files say, and the exit codes that tell you whose problem it is.

What happens before every publish

Before publishing any package, xops runs a fixed sequence: validate that .gitignore covers .env* and .npmrc when --push is also requested; validate that .npmignore covers the same (creating one if it's missing); run npm pack --dry-run --json and fail if any .env or .npmrc file would be included; bump the minor version unless --no-version-bump is set; run a second pack-check on the final package state; publish with npm publish --access public; then refresh dependent packages to @latest for anything published earlier in the same run.

What the CLI enforces regardless of configuration

• .gitignore must exclude .env* and .npmrc
• .npmignore must exclude the same (auto-created if missing)
• npm pack --dry-run --json always runs before publish — publishing is blocked if a .env or .npmrc would ship
• Tokens and token-like values are redacted from all output and reports

Exit codes: whose problem is it

Failure behavior

xops stops on the first critical failure. A package is never published if install, build, or test failed for it, and in a dependency chain, if one package fails, its dependents are never processed. On multi-package --all install runs, failures include an install summary — which packages succeeded, failed, were skipped, or were never attempted — so a partial run is obvious rather than silently incomplete.

Chapter 4

Publish Scripts and the Monorepo Workflow

Generate tiered scripts once, then run them by name instead of re-typing the flags every release.

Tiered scripts

xops scripts init writes scripts/publish-*.sh, wires them into root package.json, and merges into xops.json if it's present:

xops map                     # optional: write xops.json graph
xops scripts init            # create publish scripts
xops --all install           # bootstrap all packages
xops scripts run preflight   # validate
xops scripts run all         # release when ready

The ordered runbook, for agents or manual publishing

xops scripts init runbook discovers packages, computes dependency order, and writes both a step-by-step markdown runbook and an executable version of the same flow:

xops scripts init runbook --filter "@x12i/memorix-*"   # publish subset; verify all packages
xops scripts init runbook --dry-run                    # preview markdown only

Chapter 5

Operational Playbooks

Parameterized, risk-classified templates for repository actions you do more than once.

The built-in catalog

xops has first-class operational playbooks for repeated repository actions that need parameters, planning, risk metadata, approval behavior, and run reports. The built-in catalog currently includes kill-port, dev-stack, publish-chain, and publish-all.

xops playbooks list
xops playbooks status --json
xops playbooks init kill-port
xops playbooks plan kill-port --port 3000 --json
xops playbooks run kill-port --port 3000 --dry-run
xops playbooks run dev-stack --stack jobs --port 3000
xops playbooks run publish-chain --package @scope/app
xops playbooks run publish-all --group core --bump minor
xops playbooks explain dev-stack
xops playbooks validate
xops playbooks doctor

Shorter aliases exist for the common case: xops play kill-port --port 3000 and xops run-playbook kill-port --port 3000 both work the same way.

Where playbooks live

Local playbooks live in .xops/playbooks/. xops playbooks init <name> writes a .mjs definition using defineXopsPlaybook(...) and updates .xops/playbooks/playbooks.json; xops playbooks adopt scripts/foo.mjs --name foo --yes copies an existing ad-hoc script into the playbook catalog instead of making you rewrite it from scratch. Run artifacts land in .xops/playbooks/runs/<run-id>.json and .xops/playbooks/runs/<run-id>.md.

Plans are explicit about risk

A playbook plan includes resolved inputs, packages, env files, ports, commands, files, required tools, risks, approval requirements, expected artifacts, and steps. Risk classes are explicit, not implied: read-only, local-write, local-process, network-local, network-external, package-install, package-publish, git-mutation, system-mutation, and risk-sensitive.

Reaching playbooks from the SDK and MCP

Playbook SDK functions are exported from @x12i/xops: listPlaybooks, detectPlaybooks, loadPlaybook, planPlaybook, runPlaybook, validatePlaybook, generatePlaybook, explainPlaybook, and adoptPlaybook. Authoring helpers ship separately from @x12i/xops/playbooks. MCP exposes the same surface as xops.playbooks.list, .load, .plan, .run, .validate, .generate, .explain, and .adopt.

Appendix

Quick Reference

Operation order, exit codes, the publish safety checklist, and the built-in playbooks, on one page.

Operation order

[fix] → install → build → test → publish → push

Exit codes

Publish safety checklist (runs every time, no opt-out)

Built-in playbooks

The one-sentence summary

Every xops release runs the same fixed order, every publish gets pack-checked for secrets whether or not you asked for it, and repeated repo actions belong in a risk-classified playbook instead of a script nobody remembers the flags for.