…nkeep#3177)

* chore: post-migration productivity hardening (tooling, CI, DX)

Rebased onto main after significant churn. Dropped items that became
redundant with inkeep#143 (monorepo trap guards) and inkeep#153 (Dependabot lockfile
auto-sync), kept the rest. Addresses review comments inline.

KEPT (11 items)

Tooling:
- .npmrc: add engine-strict, auto-install-peers, strict-peer-dependencies,
  resolution-mode=highest
- .node-version: 22 -> 22.18.0 (patch pin for reproducibility)
- package.json: preinstall `only-allow pnpm` + postinstall
  `check-node-version.mjs` + `check:node-version` script
- scripts/check-node-version.mjs: hardened against IO errors + malformed
  .node-version values (addresses pullfrog/claude review comments about
  try/catch on readFileSync + lts/* handling)
- turbo.json: globalDependencies now invalidates on root pnpm-lock.yaml,
  .node-version, pnpm-workspace.yaml (was only watching public/agents/)
- tsconfig.base.json: strict baseline for opt-in package migration
  (used by PR inkeep#133)

DX:
- setup-dev.js: validateEnvironmentEarly() fails fast on missing
  ANTHROPIC_API_KEY before any Docker/install work. parseEnvFile
  readFileSync wrapped in try/catch for EACCES resilience.

CI:
- public-agents-extended-validation.yml: turbo affected filter
  `...[origin/base_ref]` on PR events; `merge_group`/`push` keep full run.
  Ported to the new single `turbo check` command structure introduced
  by inkeep#125 (the original diff targeted the pre-inkeep#125 matrix).
- public-agents-cypress.yml + composite action: 4-way deterministic
  shard matrix (no Cypress record key required); gate job fans in on
  default needs behavior.
- private-master-ci.yml: clarifying comment about turbo affected filter
  not applying (workflow_dispatch only).

DROPPED (vs original inkeep#130)

- scripts/check-lockfile-sync.mjs + `check:lockfile-sync` script:
  superseded by inkeep#143's `check-monorepo-traps.mjs lockfiles` which actually
  runs `pnpm install --frozen-lockfile` in both directories (strictly
  stronger than my mtime heuristic). inkeep#153 auto-syncs Dependabot lockfile
  PRs, killing the main scenario this script was protecting.
- biome.jsonc noExplicitAny "off" -> "warn": would break CI because main's
  Core Validation uses `biome lint --error-on-warnings` and there are
  16+ pre-existing `any` usages in agents-docs + agents-cookbook. Defer
  the flip to a separate PR that also grinds down those violations.
- coverage.yml workflow: no team demand surfaced; non-blocking but still
  shows red. Revisit when someone owns coverage tracking.

COMMENTS ADDRESSED

- claude[bot]: IO error handling on readFileSync/statSync/readdirSync in
  check-node-version.mjs + setup-dev.js parseEnvFile -> wrapped with
  graceful fallbacks
- claude[bot]: malformed .node-version (lts/*, latest) -> regex validation
  skips with a warning instead of producing confusing "Required: v" output
- pullfrog[bot]: github.base_ref is only populated on pull_request events
  -> added in-source comment explaining the trap for future maintainers
- pullfrog[bot]: check-lockfile-sync missed public/agents/agents-* layer
  -> moot, file is dropped
- pullfrog[bot]: coverage.yml missing paths filter + prepare:public-agents-build
  -> moot, file is dropped
- claude[bot]: grep -c exit code -> handled by `|| echo 0` fallback (minor,
  no change)

Not addressed (intentional)
- Biome format/explicit-any violations in agents-docs + agents-cookbook
  flagged by PR inkeep#133's run -> pre-existing on main; out of scope for this
  PR. Will surface again when biome.jsonc flip lands.

* fix: address two CI failures on the rebased inkeep#130

1. check-node-version.mjs: skip in CI/Vercel/GitHub Actions. Vercel's
   build env runs Node 24.14.1 regardless of what .node-version says,
   which caused the postinstall hook to reject and fail the install
   with:

     [check-node-version] Node version mismatch
       Required: v22.18.0 (major v22.x)
       Current:  v24.14.1

   The script's purpose is to catch DEVS on the wrong Node locally, not
   to gate deploys — the platform manages Node. Skip when CI=true,
   VERCEL=1, or GITHUB_ACTIONS=true.

2. public-agents-cypress.yml: strip the public/agents/agents-manage-ui/
   prefix from shard spec paths. cypress runs from manage-ui as cwd
   (via pnpm --dir --filter exec), so repo-root paths double up:

     public/agents/agents-manage-ui/public/agents/agents-manage-ui/cypress/e2e/...

   Now outputs cypress-relative paths like cypress/e2e/agent-prompt.cy.ts.

* fix(ci): drop stale `private/_migration-docs/IMPORT_STATUS.md` check

Reintroduced by accident when I ported the workflow over during the
rebase. Main removed this path in inkeep#157 (`chore(ci): clean up stale
monorepo-migration artifacts`). With the line reintroduced, any
workflow_dispatch run would fail at `test -f`.

Addresses claude[bot] CRITICAL review comment on inkeep#130.

* fix(ci): use App bot identity for auto-format commits

The workflow generates an INTERNAL_CI_APP token and pushes with it
specifically so downstream CI fires on the bot's commit. But the
commit is authored as github-actions[bot], which GitHub treats as
a GITHUB_TOKEN commit and suppresses synchronize for regardless of
the push credentials. Seen on inkeep#172: required checks never reported
on the auto-format HEAD and the PR was stuck BLOCKED.

Resolve the App's own bot slug and numeric user id from the newly
minted token and use <slug>[bot] as the committer. Push still uses
the same App token; synchronize fires as intended.

* ci(extended-validation): auto-update OpenAPI snapshot on PRs

Mirrors the pattern already in public/agents/.github/workflows/ci.yml:
when a PR changes agents-api routes, openapi.*, or createApp.*, regenerate
the OpenAPI snapshot and commit it back to the PR branch using the
INTERNAL_CI_APP token so downstream CI re-runs.

Avoids recurring "OpenAPI snapshot mismatch" test failures (e.g. PR inkeep#200)
where contributors add routes without running
`pnpm --filter @inkeep/agents-api openapi:update-snapshot` locally.

- Gated on non-fork PRs (GITHUB_TOKEN on forks is read-only)
- Uses GitHub App token so commits trigger downstream workflows
- Runs before service-container setup so failure modes are cheap

* chore: align .node-version with repo convention, declare engines.node range

Two fixes to the Node pinning block:

.node-version: 22.18.0 -> 22
  The patch pin was an outlier. Every CI workflow in this repo pins
  `node-version: 22` or `22.x` (24 workflows, zero patch pins), every
  vercel.json has no nodeVersion field (Vercel uses 22.x auto-patch),
  and main's .node-version was just `22`. A patch pin creates monthly
  maintenance (fnm re-install + bump PR) without catching any bug the
  major-level pin doesn't.

package.json: add engines.node = ">=22.0.0 <23"
  .npmrc sets engine-strict=true but there was no engines field for it
  to enforce, making it a no-op. This range aligns with the major-level
  convention used everywhere else and makes engine-strict bite when a
  dev is on Node 18/24.

Belt-and-suspenders: postinstall script catches major drift at install
time (already major-only via .split('.')[0]); engines+engine-strict
catches it at dependency-resolution time. Both skip in CI/Vercel.
GitOrigin-RevId: 08d61f29389bfbbb487ed3093999449ca18b9e98

Co-authored-by: Varun Varahabhotla <[email protected]>