Skip to content

Conversation

@dimaMachina
Copy link
Collaborator

@dimaMachina dimaMachina commented Dec 17, 2025

I think we should keep file structure for build dist directory.

image

This PR also

  • removes unused dependencies in agents-cli
  • removes bundling of @inkeep/agents-core in agents-cli
  • removes clean-package, clean-package.config.json and package.json scripts
        "prepack": "clean-package",
        "postpack": "clean-package restore"
    

@changeset-bot
Copy link

changeset-bot bot commented Dec 17, 2025

🦋 Changeset detected

Latest commit: f08aeb1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages
Name Type
@inkeep/ai-sdk-provider Major
@inkeep/agents-core Major
@inkeep/agents-sdk Major
@inkeep/agents-manage-api Major
@inkeep/agents-run-api Major
@inkeep/agents-cli Major
@inkeep/agents-manage-ui Major
@inkeep/create-agents Major
@inkeep/agents-manage-mcp Major

Not sure what this means? Click here to learn what changesets are.

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

@vercel
Copy link

vercel bot commented Dec 17, 2025

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

Project Deployment Review Updated (UTC)
agents-docs Ready Ready Preview, Comment Dec 20, 2025 9:26am
agents-manage-api Error Error Dec 20, 2025 9:26am
agents-manage-ui Ready Ready Preview, Comment Dec 20, 2025 9:26am
agents-run-api Ready Ready Preview, Comment Dec 20, 2025 9:26am

Comment on lines -27 to -29
banner: {
js: '#!/usr/bin/env node',
},
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in which file we need this banner? I think it's better to add directly to its source code

@claude
Copy link

claude bot commented Dec 17, 2025

Claude finished @dimaMachina's task —— View job


Staff Engineer Review

I've completed my analysis of this PR. Here's my comprehensive feedback as a TypeScript Staff Engineer and System Architect.

Review Progress

  • Analyze changed files and understand the scope
  • Review tsdown configuration changes
  • Evaluate dependency removals and their impact
  • Check for system-wide architectural implications
  • Address the banner configuration comment
  • Provide comprehensive feedback

🎯 Overall Assessment: Strong Architectural Improvement

This PR represents a thoughtful refactoring that addresses several important architectural concerns:

  • Build optimization: Moves from bundling to preserving file structure
  • Dependency cleanup: Removes 16 unused dependencies (~140 deletions)
  • Bundle separation: Externalizes @inkeep/agents-core instead of bundling

🔍 Key Changes Analysis

1. Build Strategy Transformation

Old approach: Explicit entry points with bundling

entry: { index: 'src/index.ts', config: 'src/config.ts' }
noExternal: [/^@inkeep\/agents-core/]  // Bundled workspace packages

New approach: Preserve source structure

entry: ['src/**/*.ts', '!**/__tests__', '!**/*.test.ts']
external: ['@inkeep/agents-core']
unbundle: true

Impact: ✅ This change is architecturally sound and follows Node.js best practices for CLI tools.

2. Critical Issue: Missing Banner ⚠️

The removal of the shebang banner is a breaking change:

- banner: { js: '#!/usr/bin/env node' }

Problem: Without this banner, the CLI binary won't be executable directly. The agents-cli/src/index.ts doesn't contain a shebang, so the built output needs one.

Recommendation: Add the shebang directly to src/index.ts:

#!/usr/bin/env node
import './env';
// ... rest of file

This addresses @dimaMachina's review comment and is the correct architectural approach.

3. Dependency Cleanup Assessment

The removed dependencies appear to be genuinely unused:

  • @babel/*, ast-types, recast - AST manipulation tools
  • drizzle-orm, pg - Database dependencies (now in agents-core)
  • @opentelemetry/* - Telemetry (likely moved to core)
  • @better-auth/sso, @nangohq/node - Authentication (externalized)

Risk Assessment: Low - these were likely bundled transitively through @inkeep/agents-core.

4. System Architecture Implications 🏗️

Positive Impacts:

  1. Clearer separation of concerns: CLI becomes a thin layer over agents-core
  2. Improved maintainability: File structure matches source structure
  3. Better tree-shaking: Consumers can import specific modules
  4. Reduced bundle size: No more bundling workspace packages

Potential Risks:

  1. Runtime dependency resolution: Must ensure agents-core exports are properly resolved
  2. Version synchronization: CLI now depends on external agents-core build
  3. Distribution complexity: More files in dist/ directory

🔧 Technical Recommendations

High Priority 🚨

  1. Fix the shebang issue - Add #!/usr/bin/env node to src/index.ts (addresses review comment)
  2. Verify CLI functionality - Test that node dist/index.js and inkeep binary both work
  3. Update exports if needed - Ensure package.json exports cover all new dist files

Medium Priority ⚠️

  1. Add integration test - Verify the CLI actually works with the new structure
  2. Document breaking changes - If this affects any consumers
  3. Consider dist/ file organization - Current approach may create many files

Low Priority 💡

  1. Optimize entry patterns - Consider if all TypeScript files should be built
  2. Review external dependencies - Ensure optimal bundling strategy

🧪 Testing Considerations

The PR should include:

  1. CLI execution test: Verify binary works after build
  2. Import resolution test: Ensure agents-core modules resolve correctly
  3. Build output verification: Check dist/ structure matches expectations

🚀 Future Extensibility

This change positions the CLI well for:

  • Modular architecture: Easy to extract CLI commands into separate modules
  • Plugin system: Better support for extensible commands
  • Performance optimization: Improved startup time with unbundled approach

Final Recommendation

Approve with required fix: This is a solid architectural improvement, but the shebang issue must be addressed before merge. The approach of preserving file structure and externalizing workspace dependencies is the right long-term strategy.

Action Items:

  1. Add shebang to src/index.ts
  2. Test CLI functionality thoroughly
  3. Consider adding a test that verifies the built CLI executable

Note: The file structure preservation shown in the attached screenshot looks excellent - this is exactly how a well-structured CLI dist should look.

Comment on lines -10 to -23
".": "./src/index.ts",
"./constants/models": "./src/constants/models.ts",
"./constants/schema-validation": "./src/constants/schema-validation/index.ts",
"./schema": "./src/db/schema.ts",
"./db/schema": "./src/db/schema.ts",
"./auth": "./src/auth/auth.ts",
"./auth/schema": "./src/auth/auth-schema.ts",
"./auth/validation": "./src/auth/auth-validation-schemas.ts",
"./auth/permissions": "./src/auth/permissions.ts",
"./db/test-client": "./src/db/test-client.ts",
"./types": "./src/types/index.ts",
"./validation": "./src/validation/index.ts",
"./client-exports": "./src/client-exports.ts",
"./credential-stores": "./src/credential-stores/index.ts",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should avoid usage of clean-package.config.json to keep single part of source

"@better-auth/sso": "^1.4.0",
"@clack/prompts": "^0.11.0",
"@inkeep/agents-core": "workspace:^",
"@nangohq/node": "^0.69.14",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Were these dependencies not used?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image I searched if these dependencies are used in cli and removed which are not used

"outputs": ["dist/**", "build/**", ".next/**", "!.next/cache/**"]
},
"dev": {
"dependsOn": ["^build"],
Copy link
Collaborator Author

@dimaMachina dimaMachina Dec 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Run "build" task in workspaces I depend on first

Comment on lines -107 to -111
"@inkeep/agents-docs#typecheck": {
"dependsOn": ["build"],
"inputs": ["$TURBO_DEFAULT$"],
"outputs": [".next/**"]
},
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems no longer needed

@dimaMachina dimaMachina marked this pull request as ready for review December 20, 2025 10:13
@dimaMachina
Copy link
Collaborator Author

@claude review now

@claude
Copy link

claude bot commented Dec 20, 2025

Claude finished @dimaMachina's task in 2m 26s —— View job


✅ PR Review Complete

I've completed my review of the changes to the build configuration and dependency management. Here's my comprehensive feedback:

Review Checklist:

  • Analyze tsdown configuration changes
  • Review dependency removals
  • Check for breaking changes
  • Verify shebang banner issue resolution
  • Review architectural implications
  • Check existing review comments and their resolutions
  • Provide comprehensive feedback

📋 Summary

This PR represents a significant architectural shift from bundling to preserving file structure in the build output, along with substantial dependency cleanup. The approach is generally sound, but there's one critical issue that must be addressed before merging.

🚨 Critical Issue

Missing Shebang in CLI Entry Point

The removal of the banner: { js: '#!/usr/bin/env node' } configuration from agents-cli/tsdown.config.ts creates a breaking change. Without the shebang, the CLI binary won't be executable directly.

Current State:

  • agents-cli/src/index.ts doesn't have a shebang
  • tsdown.config.ts no longer adds the shebang via banner
  • package.json bin field points to ./dist/index.js

Required Fix: Add the shebang directly to agents-cli/src/index.ts:

#!/usr/bin/env node
import './env'; // Load environment files first (needed by instrumentation)

This aligns with @dimaMachina's review comment about adding it to the source file, which is indeed the better approach.

✅ Positive Changes

1. Build Strategy Improvements

  • Unbundled approach: Moving from explicit entry points to glob patterns (src/**/*.ts) preserves the source structure
  • External dependencies: Properly externalizing @inkeep/agents-core instead of bundling it
  • Cleaner exports: The new export structure in agents-core/package.json properly maps types and runtime exports

2. Dependency Cleanup

The removal of 16 dependencies from agents-cli appears safe:

  • AST manipulation tools (@babel/*, ast-types, recast) - Not used in CLI code
  • Database/ORM (drizzle-orm, pg) - Properly moved to agents-core
  • Auth/Telemetry (@better-auth/sso, @opentelemetry/*, @nangohq/node) - Externalized via agents-core
  • Logging/Utils (pino, pino-pretty, picocolors, traverse, destr) - Not directly used

3. Clean Package Removal

Removing clean-package and its configuration files reduces complexity and build overhead.

⚠️ Points to Address

1. Dynamic Import in agents-core

The change from static to dynamic import in packages/agents-core/src/data-access/functions.ts:19:

const { autoDetectDependencies } = await import('../utils/detectDependencies');

While the comment explains this is for Next.js compatibility (avoiding node:module in static analysis), this could have runtime implications. Consider:

  • Document this requirement in a code comment
  • Ensure error handling for the dynamic import
  • Test the performance impact

2. Missing Direct Dependencies

Per review comments, these packages should be direct dependencies:

  • agents-run-api/package.json: Missing drizzle-orm (used in dbClient.ts)
  • agents-manage-api/package.json: Missing drizzle-orm (used in dbClient.ts)
  • ai-sdk-provider/package.json: Missing zod (used in error and language model files)

3. Turbo.json Comments

  • Line 35: The comment about dependencies is redundant with the dependsOn field
  • Line 111: The @inkeep/create-agents#test:e2e task references agents-cookbook-templates#build which might no longer be needed

🎯 Recommendations

  1. Immediate Actions:

    • Add shebang to agents-cli/src/index.ts
    • Add missing direct dependencies to respective package.json files
    • Test the CLI binary execution after build
  2. Follow-up Tasks:

    • Verify all workspace packages build correctly with the new structure
    • Test that consumers can properly import from the new export paths
    • Consider adding an integration test for CLI execution
  3. Documentation:

    • Update any build/deployment documentation to reflect the new dist structure
    • Document the rationale for the dynamic import workaround

✨ Overall Assessment

This is a well-thought-out refactoring that improves the build architecture. The move to preserve file structure and externalize workspace dependencies is the right approach for maintainability and developer experience. Once the shebang issue and missing dependencies are addressed, this PR will be ready to merge.

The architectural direction is sound and aligns with modern JavaScript/TypeScript best practices for monorepo package management.


View job

@github-actions github-actions bot removed the stale label Dec 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants