Upgrade exemplar to multi-resource stencil with full test coverage

[codeyogi911]

Summary

Replaces the single-endpoint JSONPlaceholder exemplar with a comprehensive, production-ready stencil (exemplar-cli) that demonstrates all patterns clify-generated CLIs must support. The new exemplar is structurally inspired by google/agents-cli and includes three resources (items, item-variants, orders) exercising pagination, idempotency, multipart uploads, and auth.

Key Changes

• New exemplar structure (examples/exemplar-cli/):

  • Hierarchical subcommands (<resource> <action>)
  • One file per resource under commands/
  • Shared HTTP, auth, output, and config layers under lib/
  • First-class login command with --status
  • Modular skills under skills/<cli>-<role>/

• Comprehensive test suite:

  • Smoke tests: CLI shape, --version, --help, error semantics
  • Integration tests: cursor pagination, idempotency-key headers, multipart uploads, structured error mapping
  • Auth tests: bearer token wiring, login status reflection, 401 handling
  • In-repo mock server (zero-dep) — no network required for npm test

• Three-resource API surface:

  • items: list (cursor pagination), get, create (idempotency), update, delete
  • item-variants: sub-resource flattened to two-level nesting
  • orders: list, get, create (idempotency), upload (multipart)

• Knowledge base (knowledge/):

  • Cursor pagination pattern
  • Idempotency-key header usage
  • Composite order validation rules
  • Rate-limit behavior

• Eval harness (evals/):

  • Deterministic graders for file presence, .clify.json fields, auth scheme
  • Case-based testing against real APIs (Zoho Inventory example)
  • Structural similarity scoring placeholder

• Updated documentation:

  • New references/scaffold-pipeline.md: in-depth per-phase reference
  • Renamed skills/clify-scaffold/ → skills/clify/ with lean summary
  • Removed obsolete clify-validate and clify-sync skills (functionality preserved in core)
  • Updated references/conventions.md to reference exemplar-cli

• Backward compatibility:

  • Old JSONPlaceholder exemplar moved to examples/legacy/jsonplaceholder-cli/
  • Validation gate updated to scan both old and new CLI layouts (lib/ + commands/)

Notable Implementation Details

• Mock server uses Node's built-in http module (zero dependencies)
• Auth scheme is pluggable via lib/auth.mjs — scaffolder swaps scheme and matching branch for target API
• Help text is generated from runtime resource registry, ensuring it never drifts
• Path interpolation handles :id and :itemId placeholders with proper URL encoding
• Pagination iterator (paginate()) handles cursor, page, offset, and Link header strategies
• Idempotency-key and If-Match headers are optional flags, not forced
• Multipart uploads wire --file flag and read file from disk
• Error output uses structured JSON format with code + message
• .clify.json captures auth scheme, API name, docs URL, content hash, and node version requirement

https://claude.ai/code/session_016WbCqoWpJ77he4VQbLSySe