## Deploying & Releasing

- **Publish npm packages with pnpm, never npm.** This workspace uses pnpm

  catalogs, so a dependency is written `catalog:` in the source manifest and

  must be rewritten to a concrete version before it is published. `pnpm pack`

  and `pnpm publish` do that rewrite; `npm pack` does not. A package packed

  with `npm pack` publishes a manifest npm itself cannot resolve, and the

  consumer sees `EUNSUPPORTEDPROTOCOL "catalog:"` — a message that names the

  protocol rather than the mistake. It has shipped that way before.

- **Never publish a tarball you have not verified installs.** For the CLI,

  `pnpm --filter @openagentsinc/cli run verify:package` packs the way a publish

  packs, refuses a manifest carrying `catalog:` or `workspace:` specifiers,

  installs the tarball into an empty project with `npm`, and runs the packed

  binary. It runs automatically as `prepublishOnly`. Note that

  `npm publish <file.tgz>` skips that lifecycle, so if you publish a pre-packed

  tarball you must run the verifier yourself first.

- **Confirm the published artifact from the registry, not from the build.**

  Install the exact published version into an empty directory and run a real

  command against a live surface. Registry metadata is cached locally, so

  `npm view` and `npm install` may report the previous version for a few

  minutes after a successful publish; use `--prefer-online`, or read

  `https://registry.npmjs.org/<package>` directly, before concluding a publish

  failed.

- **`docs/DEPLOYMENT.md` is the single hub for every deploy / publish / release.**

  Read it first for any of: deploying the `openagents.com` Cloud Run service,

  publishing Pylon to npm, publishing signed Pylon binaries, the

    "test": "vp test --run",

    "typecheck": "tsc -p tsconfig.json --noEmit",

    "verify": "pnpm run fmt:check && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build",

    "verify:package": "node scripts/verify-packed-install.mjs"

    "verify:package": "node scripts/verify-packed-install.mjs",

    "prepublishOnly": "pnpm run verify:package"

  },

  "dependencies": {

    "@effect/platform-node": "catalog:",

  }

  const tarball = join(tarballDirectory, tarballs[0]);

  // A workspace specifier that survives packing makes the published package

  // uninstallable: `npm install` cannot resolve `catalog:` or `workspace:` and

  // fails with EUNSUPPORTEDPROTOCOL, which names the protocol and not the

  // mistake. `pnpm pack` rewrites them and `npm pack` does not, so this is

  // exactly what a publish packed the wrong way looks like. Read from the

  // packed manifest rather than the source one, because the rewrite is the

  // thing under test.

  const packedManifest = JSON.parse(

    run("tar", ["-xOf", tarball, "package/package.json"]).stdout,

  );

  const unresolved = ["dependencies", "peerDependencies", "optionalDependencies"].flatMap(

    (field) =>

      Object.entries(packedManifest[field] ?? {})

        .filter(([, range]) => /^(catalog:|workspace:)/.test(String(range)))

        .map(([name, range]) => `${field}.${name}: ${String(range)}`),

  );

  if (unresolved.length > 0) {

    throw new Error(

      "The packed manifest carries workspace specifiers npm cannot resolve, so " +

        "the published package would not install:\n  " +

        unresolved.join("\n  ") +

        "\nPack and publish with pnpm, never npm: `pnpm publish` rewrites these " +

        "to concrete versions and `npm pack` leaves them.",

    );

  }

  run("npm", ["install", tarball, "--no-audit", "--no-fund", "--no-package-lock", "--save-exact"], {

    cwd: consumerDirectory,

  });