Skip to content

Align SDK to Protocol‑Commons v1.1.0 — unify APIs, docs, CLI, and tests#11

Merged
GsCommand merged 1 commit intomainfrom
codex/conduct-protocol-grade-audit-and-upgrade
Mar 19, 2026
Merged

Align SDK to Protocol‑Commons v1.1.0 — unify APIs, docs, CLI, and tests#11
GsCommand merged 1 commit intomainfrom
codex/conduct-protocol-grade-audit-and-upgrade

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • Remove long-standing drift between docs, fixtures, and code by making a single canonical SDK story (Protocol‑Commons v1.1.0) and a clear receipt vs runtime_metadata boundary.
  • Make the TypeScript and Python packages feel like a consistent, production-grade SDK surface with an obvious install/test/publish flow.
  • Give the CLI first-class verification and reproducible developer workflows and ensure CI validates the full matrix (build, tests, verification).

Description

  • Docs and guides: Rewrote root landing and onboarding files to present a single developer path and the canonical envelope model (receipt + optional runtime_metadata) by updating README.md, QUICKSTART.md, EXAMPLES.md, DEVELOPER_EXPERIENCE.md, and DEPLOYMENT_GUIDE.md.
  • TypeScript SDK: bumped typescript-sdk/package.json to 1.1.0, lowered engine to node >=20, added CommandResponse envelope and normalizeCommandResponse() to normalize legacy blended responses, made verifyReceipt() accept either receipt or full envelope and always verify the canonical receipt, and surfaced protocol constants (commonsVersion, packageVersion). Updated CLI (src/cli.ts) to print the envelope and added a verify command. Updated tests and smoke scripts.
  • Python SDK: bumped python-sdk/pyproject.toml and package __version__ to 1.1.0, introduced CanonicalReceipt/CommandResponse/RuntimeMetadata types, added normalize_command_response() in the client, ensured CommandLayerClient returns the { "receipt", "runtime_metadata" } envelope, and updated verify_receipt() to accept envelope or receipt while always verifying the canonical receipt. Updated Python docs and tests accordingly.
  • Fixtures & tests: regenerated and aligned test_vectors/* to v1.1.0 canonical receipts and updated cross-SDK runtime tests in runtime/tests/ and SDK unit tests to validate the new envelope and verification semantics.
  • CI/workflows: updated GitHub Actions to run TypeScript typecheck, build, unit tests, runtime protocol tests, CLI smoke tests, and an npm pack --dry-run, and to run Python lint/typecheck/tests + package build/twine checks.

Testing

  • TypeScript: ran cd typescript-sdk && npm ci && npm run typecheck && npm test which built artifacts and executed unit + template + CLI smoke tests; all tests passed (38 passed, 0 failed in JS unit template runs) and npm pack --dry-run produced a clean package tarball.
  • Python: ran cd python-sdk && python -m pip install --no-build-isolation -e . then python -m ruff check . && python -m mypy commandlayer && python -m pytest tests/ -v; lint, mypy, and all tests passed (18 passed, 0 failed).
  • Cross-checks: ran the runtime verification tests (node --test runtime/tests/*.mjs) using the built TypeScript package; tests passed.
  • Packaging note: python -m build could not be run in this environment initially because the build module was not installed here; CI workflow was updated to perform python -m build + twine check so packaging checks run in CI (local editable install + test suite succeeded).

Files changed (high level): root docs (README.md, QUICKSTART.md, EXAMPLES.md, DEVELOPER_EXPERIENCE.md, DEPLOYMENT_GUIDE.md), TypeScript SDK (package.json, src/index.ts, src/cli.ts, tests, scripts), Python SDK (pyproject.toml, commandlayer/*, tests, docs), workflows (.github/workflows/*), and test_vectors/* (regenerated v1.1.0 fixtures).


Codex Task

@GsCommand GsCommand merged commit 36b41aa into main Mar 19, 2026
6 of 8 checks passed
@GsCommand GsCommand deleted the codex/conduct-protocol-grade-audit-and-upgrade branch April 24, 2026 03:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant