feat: Add round-trip validation for inkeep pull

[amikofalvy]

Summary

Implements comprehensive validation for inkeep pull that ensures generated TypeScript files can be serialized back to match the original backend data.

This addresses the duplication issue where pull validation logic was reimplementing parts of push conversion logic. Now both commands share the same serialization path.

Changes

Core Utilities

• Shared Project Loader (agents-cli/src/utils/project-loader.ts)

  • Extracted loadProject() function used by both push and pull commands
  • Eliminates code duplication between commands

• Deep JSON Comparison (agents-cli/src/utils/json-comparison.ts)

  • Compares two FullProjectDefinition objects field-by-field
  • Ignores computed/timestamp fields
  • Provides detailed error messages showing exact differences

Validation

• Round-Trip Validation (in pull.ts)
  • Loads generated TypeScript using the same logic as inkeep push
  • Serializes back to JSON via project.getFullDefinition()
  • Compares with original backend data
  • Two-stage validation:
    1. Basic file verification (file existence, structure)
    2. Round-trip validation (TS → JSON conversion accuracy)

Updated Commands

• Pull Command

  • Now performs comprehensive two-stage validation
  • Provides clear, actionable error messages
  • Catches LLM generation issues immediately

• Push Command

  • Uses shared loadProject() utility
  • Consistent with pull command implementation

Testing & Documentation

• Comprehensive Test Suite (agents-cli/src/commands/__tests__/pull-validation.test.ts)

  • 11 tests covering all validation aspects
  • All tests passing ✅

• Updated Documentation (agents-docs/content/docs/typescript-sdk/cli-reference.mdx)

  • Added "Validation Process" section
  • Explains both validation stages with examples

Benefits

✅ Eliminates Duplication - Reuses toFullProjectDefinition() logic from push
✅ Better Validation - Ensures generated TS is actually correct
✅ Catches Errors Early - LLM generation issues detected before push
✅ Maintainability - Single source of truth for TS → JSON conversion
✅ Confidence - Guarantees pull → push round-trip works correctly

Testing

• All tests pass (11/11 new tests)
• TypeScript compilation successful
• Build completes without errors
• All pre-push checks pass
• Documentation updated

Example Output

Success:

✓ Basic file verification passed
✓ Round-trip validation passed - generated TS matches backend data

Failure:

✗ Round-trip validation failed

❌ Round-trip validation errors:
   The generated TypeScript does not serialize back to match the original backend data.
  • Value mismatch at agents.my-agent.name: "Original Name" vs "Generated Name"
  • Missing tool in generated: tool-id

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7a0c95c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Ready	Preview	Comment	Oct 16, 2025 9:40am
agents-manage-api	Ready	Preview	Comment	Oct 16, 2025 9:40am
agents-manage-ui	Ready	Preview	Comment	Oct 16, 2025 9:40am
agents-run-api	Ready	Preview	Comment	Oct 16, 2025 9:40am