playground-cli: Instructions file for Claude Code

CLAUDE.md

Refer to the Contributing and Architecture Highlights sections of README.md for development workflows, the release process, and repo conventions.

Verification before committing

Before claiming a task complete, opening a PR, or merging, run all four. The first three are enforced by CI; pnpm test also catches regressions:

pnpm format:check
pnpm lint:license
pnpm typecheck
pnpm test

🔴 pnpm <script> can exit BEFORE running the tool, and it looks like a pass. pnpm 11 runs a deps-status check first; when that fails — most often ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION after bumping onto a freshly published release train — it prints a stack and exits non-zero without invoking tsc/vitest at all. Grepping the output for error TS then finds nothing and reads as a clean typecheck. This cost real bugs in Sept 2026: four type errors (a missed await in identityGate.ts that broke every gated command, the same in DripScreen.tsx, and two malformed allowance literals) all "passed" a typecheck that never ran, and shipped to a live phone test. Check the exit code, or run the tool directly — ./node_modules/.bin/tsc --noEmit, npx vitest run. CI is unaffected (a non-zero exit fails the job either way); this is a local-verification trap only.

pnpm build compiles with bun, which STRIPS types without checking them — it is NOT a type signal. The tsc baseline was burned to zero in June 2026 and pnpm typecheck (tsc --noEmit) now runs as a CI job, so any new type error fails the build — keep it at zero.

.cdm/cdm.d.ts and .cdm/contracts.d.ts are COMMITTED, and must stay so. They are generated by cdm install and are the module augmentation that gives contract handles their real per-method signatures. Without them the registry handle is a bare Contract<ContractDef>, and every .query()/.tx() call site goes silently unchecked — that gap let the 7-arg publish regression and a getMetadataUri shape bug through, and it also produces the inverse trap (code that compiles locally and fails only in CI, because a structural interface can't match the un-augmented type). .cdm/ was gitignored wholesale until Sept 2026; CI never ran cdm install (the cdm CLI is a global tool needing chain access, not a repo dep), so the Typecheck job was checking everything EXCEPT the contract calls. The rest of .cdm/ stays ignored on purpose: contracts/**/info.json snapshots per-version contract addresses that we never read (addresses resolve live from the CDM meta-registry), so committing them would add a second, stale source of truth. After any cdm i, commit the regenerated .d.ts files — a stale one type-checks against the previous ABI, which is exactly the failure this prevents. (Oct 2026: with cdm-builder 6.0.0 on the same papi-3 product-sdk line as us, the contract.ts seams below no longer exist in the code — only asCloudStorageApi remains. The history is kept for the next skew.) The cdm-builder version skew is bridged through THREE cast seams: asCloudStorageApi in src/utils/allowances/bulletin.ts (the TypedApi<Paseo_bulletin> vs BulletinTypedApi codegen skew — two codegens of the same chain), plus asCdmAssetHubApi/asCdmAssetHubDescriptor and asCdmRegistryContract in src/commands/contract.ts. The asset-hub seams bridge the paseo-asset-hub DotnsGateway/descriptor shape drift between cdm-builder's pinned @parity/product-sdk-descriptors and our root's (the contract pipeline never touches DotnsGateway, so the cast is runtime-safe). asCdmRegistryContract was added when our root @parity/product-sdk-contracts reached 0.9.x: Contract.tx() now resolves a Result<TxResult, …>, nominally unassignable to cdm-builder's older RegistryContract param — but the install-time registry is query-only (no signer wired in), so .tx() is never invoked through it and the cast is runtime-safe. At [email protected] the pinned product-sdk moved up to [email protected] / [email protected] while our root is contracts@^0.9.2 / descriptors@^0.8.0 — so the .tx() Result shape realigns (making asCdmRegistryContract likely redundant) while a descriptors minor gap (0.7 vs 0.8) remains. Before deleting any seam, remove it and run pnpm typecheck. If lint:license flags a file you authored, run ./scripts/check-license-headers.sh --fix to prepend the standard Parity Apache-2.0 header (SPDX-License-Identifier: Apache-2.0 + Copyright (C) Parity Technologies (UK) Ltd., both lines required). The check script keeps shebangs on line 1 and places the header below them.