@cloudpeers-jkl/cli

CLI for cloudpeers services. Two flows:

• scaffold --from-manifest — turn a Builder Discovery Lab manifest into a deployable cloudpeers service skeleton (workspace + sovereignty tagger + A2A registration + x402 endpoints + cloudpeers Capability Profile) in <30 seconds.
• cloudpeers-init — archetype-templated init (legacy flow; narrator + strategist templates).

Install + use

# Scaffold from a Lab manifest
npx @cloudpeers-jkl/cli scaffold \
  --from-manifest ./manifest.json \
  --out ./my-service \
  --archetype narrator

The manifest matches the shape emitted by the Builder Discovery Lab at cloudpeers.com/labs/builder-discovery (serviceId, name, declared_outcome, capabilities, sovereignty, a2a). mcpEndpoints is deprecated as of 0.4.0 — the integration surface is A2A; legacy manifests that still carry it parse with a warning and the values are ignored (rejection planned for 0.5.0).

What the scaffold gives you

my-service/
├── README.md                            # fork → deploy → register → settle
├── package.json + tsconfig.json         # minimal TypeScript toolchain
├── src/
│   ├── index.ts                         # http boot — A2A envelope (POST /a2a) + well-known + x402 routes
│   ├── a2a/register.ts                  # authenticated registration → services.cloudpeers.com/api/registry/register
│   ├── a2a/auth.ts                      # OAuth 2.0 client_credentials token minting (RFC 6749 §4.4)
│   ├── a2a/client.ts                    # outbound A2A: discover / send / task-completion read
│   ├── capabilities/<cap>.ts            # one file per declared capability
│   ├── capabilities/index.ts            # dispatch map: A2A envelope → handler
│   ├── x402/{initiate,settle}.ts        # x402 endpoints + Guardian validator hook
│   └── sovereignty/tagger.ts            # data classifier wired to manifest.sovereignty
├── .well-known/ucp/<service-id>.json    # static cloudpeers Capability Profile
├── .well-known/agent-card.json          # A2A Agent Card (url patched from PUBLIC_BASE_URL at serve time)
├── policies/<service-id>.nemoclaw.yaml  # NemoClaw policy, v0 schema (three tiers, fail-closed, consent-at-share)
├── research/autoresearch-experiment.yaml# one experiment per capability, tagged with declared_outcome
├── SOUL.md / STATUS.md / KNOWLEDGE.md   # workspace shape
└── tests/                               # smoke + capability conformance + x402 flow (tsx harness)

Implement validateOutcome() in src/x402/settle.ts per your service's declared outcome contract — that's the Guardian hook that gates settlement. Everything else is wired.

Scope

Phase 2 (0.4.0, this release) — the A2A wiring + registration contract + NemoClaw release:

• Inbound A2A envelope route (POST /a2a, JSON-RPC 2.0 message/send) dispatching to declared capabilities; direct invocation at POST /api/capabilities/<name>
• Outbound A2A client: discover() / send() / getTask() / sendAndWait() against /api/a2a/*
• Authenticated registration (OAuth client_credentials) against services.cloudpeers.com — the unauthenticated agents.cloudpeers.com path is gone
• Agent Card emission + serving with CORS (/.well-known/agent-card.json)
• mcpEndpoints deprecated (accept-and-warn)
• NemoClaw policy YAML (v0 schema), AutoResearch experiment scaffold, capability + x402 test files

Still out of scope:

• Connector + Sponsor archetype variants (Phase 3 — narrator + strategist today)
• --from-session <id> Supabase fetch (Phase 3 — use --from-manifest <path>)
• E2E CI test (Phase 4)

See SCAFFOLD_TEST.md for the structural-diff contract vs the Peer Context reference impl at github.com/jenklin/cloudpeers-peer-context.

Develop

git clone https://github.com/jenklin/cloudpeers.git
cd cloudpeers/packages/cli
npm install
npm test

npm test runs tests/scaffold.test.js end-to-end: scaffolds the examples/memory-keeper-manifest.json into a temp directory, asserts file presence + content (A2A wiring, agent card, NemoClaw invariants, no stale agents.cloudpeers.com / mcpEndpoints strings), runs the generated repo's own smoke + capability + x402 tests, and verifies the manifest schema rejects malformed input while accepting-and-warning on legacy mcpEndpoints.

License

MIT