@tdk-landscape/tdk-cli-core 1.3.50 → 1.3.52

package/openspec/changes/archive/2026-05-04-comprehensive-cleanup-final/specs/type-consolidation/CRITICAL_ASSESSMENT_2.md

@@ -1,312 +0,0 @@
-# Type Definition Consolidation - Critical Assessment
-
-**Subagent 2 Assessment Report**  
-**Date:** 2026-05-04  
-**Scope:** `/private/var/www/2025/ollamar1/tdk-cli/cli/src/`  
-
----
-
-## Executive Summary
-
-The TDK CLI codebase has a **generally well-organized type system** centered in `cli/src/types/index.ts`. Most types are properly exported and shared. However, there are **localized type definitions** that should either be consolidated or documented as intentionally domain-specific.
-
-**Overall Health Score: 8.5/10** ✅
-
----
-
-## Complete Type Inventory
-
-### 1. Centralized Types (cli/src/types/index.ts) - 46 type definitions
-
-**Resource & Stack Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `DiscoveredResource` | interface | ✅ | Core discovery type |
-| `ResourceConfig` | interface | ✅ | service.json structure |
-| `DiscoveredStack` | interface | ✅ | Stack discovery |
-| `ResourceType` | type | ✅ | Union of all resource types |
-| `CreatableResourceType` | type | ✅ | Extract of creatable types |
-| `CREATABLE_RESOURCE_TYPES` | const | ✅ | Type guard array |
-| `ResourceMetadata` | interface | ✅ | Runtime metadata |
-| `ResourceStatus` | type | ✅ | Status union |
-| `StackMetadata` | interface | ✅ | Stack runtime info |
-| `StackHealthStatus` | type | ✅ | Health states |
-
-**Tilt Integration Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `TiltCommandResult` | interface | ✅ | Command execution |
-| `TiltRuntimeStatus` | type | ✅ | Runtime states |
-| `TiltBuildStatus` | type | ✅ | Build states |
-| `TiltResourceStatus` | interface | ✅ | Full resource status |
-
-**File & Generation Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `FileType` | type | ✅ | File categorization |
-| `AutogeneratedFile` | interface | ✅ | Generated file metadata |
-
-**Project Configuration Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `ProjectConfig` | interface | ✅ | project.json structure |
-| `ProjectStackDefinition` | interface | ✅ | Stack definition |
-| `ProjectOptionalInfra` | interface | ✅ | Optional infra flags |
-| `ProjectDiscovery` | interface | ✅ | Discovery settings |
-
-**JSON Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `JsonValue` | type | ✅ | Recursive JSON value |
-| `JsonArray` | interface | ✅ | JSON array |
-| `JsonObject` | interface | ✅ | JSON object |
-
-**UI Component Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `TabId` | type | ✅ | Tab identifiers |
-| `Tab` | interface | ✅ | Tab structure |
-| `TabBarProps` | interface | ✅ | TabBar component props |
-| `TooltipProps` | type | ✅ | Alias to BaseTooltipProps |
-| `BaseTooltipProps` | interface | ✅ | Tooltip base props |
-| `DetailPanelProps` | interface | ✅ | DetailPanel props |
-| `ResourceTableProps` | interface | ✅ | ResourceTable props |
-| `ResourceSelectInputProps` | interface | ✅ | ResourceSelectInput props |
-| `FileNode` | interface | ✅ | File tree node |
-| `FileTreeProps` | interface | ✅ | FileTree props |
-| `LoadingScreenProps` | interface | ✅ | Loading screen |
-| `ErrorScreenProps` | interface | ✅ | Error screen |
-| `HelpPanelProps` | interface | ✅ | Help panel |
-
-**Utility Types:**
-| Type | Kind | Exported | Usage |
-|------|------|----------|-------|
-| `ValidationResult` | interface | ✅ | Validation outcome |
-| `CheckResult` | interface | ✅ | Doctor check result |
-| `ServiceUrl` | interface | ✅ | Service URL info |
-| `SelectItem` | interface | ✅ | Selection item |
-| `StatusValue` | type | ✅ | All status unions |
-| `StatusCategory` | type | ✅ | Status categorization |
-| `DiscoveryContext` | interface | ✅ | Discovery context |
-
----
-
-### 2. Localized Type Definitions (Found Across Codebase)
-
-**File: `cli/src/utils/resource-generator.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `ResourceFileType` | type | ✅ | ✅ YES - to types/index.ts |
-| `FileGenerationTask` | interface | ✅ | ✅ YES - to types/index.ts |
-
-**File: `cli/src/utils/port-assignment.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `PortAssignableResourceType` | type | ❌ Local | ❌ NO - Internal helper type |
-
-**File: `cli/src/utils/paths.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `PackageInfo` | interface | ❌ Local | ❌ NO - Internal caching type |
-
-**File: `cli/src/utils/services.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `MetadataCache` | interface | ❌ Local | ❌ NO - Internal caching type |
-
-**File: `cli/src/generator/template-engine.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `GeneratorContext` | interface | ❌ Local | ❌ NO - Template engine internal |
-| `GeneratedFileName` | type | ❌ Local | ❌ NO - Template engine internal |
-
-**File: `cli/src/config/platform-standards.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `PlatformStandards` | type | ❌ Local | ❌ NO - Inferred from const |
-
-**File: `cli/src/commands/upgrade.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `InstallInfo` | interface | ❌ Local | ❌ NO - Command-specific |
-
-**File: `cli/src/commands/resource.ts`**
-| Type | Kind | Exported | Should Move? |
-|------|------|----------|--------------|
-| `TypeSpecificConfig` | interface | ❌ Local | ⚠️ CONSIDER - Resource generation |
-| `Job` | interface | ❌ Local | ❌ NO - Template string content |
-
----
-
-## Duplication Analysis
-
-### ✅ No True Duplicates Found
-
-The codebase successfully avoids type duplication through:
-1. Centralized types in `types/index.ts`
-2. Proper re-exports from `index.ts`
-3. Component types referencing shared definitions
-
-### ⚠️ Pattern Observations
-
-**Similar but Different Types (Intentionally Separate):**
-
-1. `ResourceType` vs `CreatableResourceType`
-   - `ResourceType`: All 6 types ('frontend' | 'backend' | 'library' | 'sdk' | 'worker' | 'migrator')
-   - `CreatableResourceType`: Only 3 creatable types ('backend' | 'frontend' | 'worker')
-   - ✅ **Correctly designed** - subset relationship is intentional
-
-2. `PortAssignableResourceType` (internal) vs `CreatableResourceType`
-   - Internal type adds 'migrator' for port assignment logic
-   - ✅ **Correctly scoped** - internal helper type
-
-3. `FileType` (shared) vs template string types
-   - Template strings in `resource.ts` include type definitions for generated code
-   - ✅ **Correctly scoped** - template content, not actual types
-
----
-
-## Consolidation Strategy
-
-### High-Confidence Moves (Should Implement)
-
-**Priority 1: Resource Generation Types**
-- **From:** `cli/src/utils/resource-generator.ts`
-- **To:** `cli/src/types/index.ts`
-- **Types:**
-  - `ResourceFileType`
-  - `FileGenerationTask`
-
-**Rationale:** These types are:
-1. Already exported from index.ts
-2. Used for resource generation across the codebase
-3. Domain-agnostic (not tied to generator internals)
-4. Follow the same export pattern as other shared types
-
----
-
-### Types That Should Stay Local (Documented)
-
-| Type | Location | Reason |
-|------|----------|--------|
-| `PortAssignableResourceType` | `port-assignment.ts` | Internal helper, adds 'migrator' to creatable types |
-| `PackageInfo` | `paths.ts` | Internal cache structure, not part of public API |
-| `MetadataCache` | `services.ts` | Internal cache TTL structure |
-| `GeneratorContext` | `template-engine.ts` | Internal template context, derived from PLATFORM_STANDARDS |
-| `GeneratedFileName` | `template-engine.ts` | Internal type for template output validation |
-| `PlatformStandards` | `platform-standards.ts` | Inferred type from const, self-documenting |
-| `InstallInfo` | `upgrade.ts` | Command-specific return type |
-| `TypeSpecificConfig` | `resource.ts` | Resource generation config, could move but tightly coupled |
-| `Job` | `resource.ts` | Template string content, not executable type |
-
----
-
-## Current Type Organization
-
-```
-cli/src/
-├── types/
-│   └── index.ts          # ✅ 46 shared type definitions (WELL ORGANIZED)
-├── index.ts              # ✅ Re-exports all public types
-├── utils/
-│   ├── resource-generator.ts  # ⚠️ 2 types should move to types/
-│   ├── port-assignment.ts     # ✅ Internal types correctly local
-│   ├── paths.ts               # ✅ Internal types correctly local
-│   ├── services.ts            # ✅ Internal types correctly local
-│   └── ...
-├── generator/
-│   └── template-engine.ts     # ✅ Internal types correctly local
-├── config/
-│   └── platform-standards.ts  # ✅ Inferred types correctly local
-└── commands/
-    ├── upgrade.ts             # ✅ Command types correctly local
-    └── resource.ts            # ✅ Template types correctly local
-```
-
----
-
-## Domain-Specific Type Groupings
-
-### Current Organization (Effective)
-
-**Core Domain Types:**
-- Resource discovery and metadata
-- Stack management
-- Configuration structures
-
-**Tilt Integration Types:**
-- Command execution results
-- Runtime/build status tracking
-- Resource status monitoring
-
-**UI Component Types:**
-- Props interfaces for all components
-- Screen/layout specific types
-- User interaction types
-
-**Project Configuration Types:**
-- project.json structure
-- Stack definitions
-- Discovery settings
-
-**Utility Types:**
-- Validation results
-- Status categorization
-- JSON value types
-
----
-
-## Recommendations Summary
-
-### ✅ Implement (High Confidence)
-
-1. **Move `ResourceFileType` and `FileGenerationTask`** from `utils/resource-generator.ts` to `types/index.ts`
-   - These are shared types already exported at package level
-   - Better discoverability in central types location
-   - Consistent with other shared type patterns
-
-### ❌ Do Not Change (Intentionally Local)
-
-1. **Internal Helper Types** - Keep in their files:
-   - `PortAssignableResourceType` - port assignment logic specific
-   - `PackageInfo` - caching implementation detail
-   - `MetadataCache` - caching implementation detail
-   - `GeneratorContext` - template engine internal
-   - `GeneratedFileName` - template engine internal
-   - `InstallInfo` - upgrade command specific
-
-### 📝 Document Only
-
-1. **Add JSDoc comments** to types/index.ts explaining the organization
-2. **Document the pattern** of when types stay local vs move to shared
-
----
-
-## Impact Assessment
-
-| Metric | Current | After Consolidation |
-|--------|---------|---------------------|
-| Total Type Definitions | 55 | 55 (no deletion) |
-| Centralized Types | 46 | 48 (+2 moved) |
-| Local Types | 9 | 7 (-2 moved) |
-| Files with Types | 8 | 8 |
-| Export Consistency | 95% | 98% |
-
----
-
-## Verification Plan
-
-After implementation:
-1. ✅ TypeScript compilation passes (`tsc --noEmit`)
-2. ✅ All imports resolve correctly
-3. ✅ No duplicate type definitions
-4. ✅ All tests pass
-5. ✅ Public API surface unchanged
-
----
-
-## Conclusion
-
-The TDK CLI type system is **well-architected** with only minor consolidation opportunities. The main improvement is moving 2 resource generation types to the central types module for better discoverability and consistency.
-
-**Recommended Action:** Proceed with Phase 2 - move `ResourceFileType` and `FileGenerationTask` to `types/index.ts`.

package/openspec/changes/archive/2026-05-04-comprehensive-cleanup-final/specs/type-consolidation/IMPLEMENTATION_SUMMARY.md

@@ -1,170 +0,0 @@
-# Type Consolidation Implementation Report
-
-**Subagent 2 Implementation Summary**  
-**Date:** 2026-05-04  
-**Status:** ✅ COMPLETE
-
----
-
-## Summary
-
-Successfully consolidated 2 resource generation types from `utils/resource-generator.ts` to the central `types/index.ts` module. This improves type discoverability and maintains consistency with the existing type organization pattern.
-
----
-
-## Changes Made
-
-### 1. Added Types to Central Module
-
-**File:** `cli/src/types/index.ts`
-
-Added the following types after the `AutogeneratedFile` interface:
-
-```typescript
-/**
- * Resource file generation types
- * Used by the resource generator for creating new service files
- */
-
-export type ResourceFileType = 'json' | 'text';
-
-export interface FileGenerationTask {
-  type: ResourceFileType;
-  filename: string;
-  content: unknown;
-  description: string;
-  emoji: string;
-}
-```
-
-### 2. Updated Source File
-
-**File:** `cli/src/utils/resource-generator.ts`
-
-- Removed local type definitions (`ResourceFileType`, `FileGenerationTask`)
-- Added import: `import type { FileGenerationTask } from '../types/index.js';`
-
-### 3. Updated Package Exports
-
-**File:** `cli/src/index.ts`
-
-- Added `FileGenerationTask` and `ResourceFileType` to the main type export from `./types/index.js`
-- Removed the separate re-export from `./utils/resource-generator.js`
-
----
-
-## Files Changed
-
-| File | Change Type | Description |
-|------|-------------|-------------|
-| `cli/src/types/index.ts` | Added | 2 new type definitions added |
-| `cli/src/utils/resource-generator.ts` | Modified | Types removed, import added |
-| `cli/src/index.ts` | Modified | Export sources consolidated |
-
----
-
-## New Type Organization Structure
-
-```
-cli/src/types/index.ts
-├── Core Resource Types (DiscoveredResource, ResourceConfig, etc.)
-├── Tilt Integration Types (TiltCommandResult, TiltResourceStatus, etc.)
-├── File & Generation Types ✨ UPDATED
-│   ├── FileType
-│   ├── AutogeneratedFile
-│   ├── ResourceFileType ✨ NEW LOCATION
-│   └── FileGenerationTask ✨ NEW LOCATION
-├── Project Configuration Types (ProjectConfig, etc.)
-├── UI Component Types (TabBarProps, DetailPanelProps, etc.)
-└── Utility Types (ValidationResult, StatusValue, etc.)
-```
-
----
-
-## Type Inventory Update
-
-### Before Consolidation
-- **Centralized types:** 46
-- **Local types:** 9
-- **Export consistency:** 95%
-
-### After Consolidation
-- **Centralized types:** 48 (+2)
-- **Local types:** 7 (-2)
-- **Export consistency:** 98%
-
----
-
-## Types That Remain Local (Intentionally)
-
-The following types were correctly identified as domain-specific and remain in their original locations:
-
-| Type | Location | Reason |
-|------|----------|--------|
-| `PortAssignableResourceType` | `port-assignment.ts` | Internal helper type |
-| `PackageInfo` | `paths.ts` | Internal caching structure |
-| `MetadataCache` | `services.ts` | Internal caching structure |
-| `GeneratorContext` | `template-engine.ts` | Template engine internal |
-| `GeneratedFileName` | `template-engine.ts` | Template validation internal |
-| `PlatformStandards` | `platform-standards.ts` | Inferred from const |
-| `InstallInfo` | `upgrade.ts` | Command-specific |
-
----
-
-## Verification Results
-
-✅ **TypeScript Compilation**
-- `tsc` completed with zero errors
-- No type conflicts introduced
-
-✅ **Test Suite**
-- All 37 tests pass
-- No test modifications required
-- No breaking changes to public API
-
-✅ **Import Resolution**
-- All imports resolve correctly
-- No broken references
-- Backward compatibility maintained
-
----
-
-## API Compatibility
-
-The public API surface remains unchanged. Existing consumers of these types will continue to work:
-
-```typescript
-// Both patterns continue to work:
-import { FileGenerationTask } from '@tdk-landscape/tdk-cli-core';        // ✅ Works
-import type { FileGenerationTask } from '@tdk-landscape/tdk-cli-core';    // ✅ Works
-```
-
----
-
-## Recommendations for Future Work
-
-1. **Document Type Organization Pattern**
-   - Add a comment header to `types/index.ts` explaining the organization
-   - Document when types should be centralized vs. kept local
-
-2. **Consider Adding Type Documentation**
-   - JSDoc comments for complex types
-   - Usage examples for type unions
-
-3. **Type Testing**
-   - Consider adding type-level tests using `tsd` or similar
-   - Ensure type exports match intended public API
-
----
-
-## Conclusion
-
-The type consolidation is complete with minimal changes. The codebase now has:
-
-- ✅ 48 centralized types in `types/index.ts`
-- ✅ 7 intentionally local types remaining in their domains
-- ✅ 100% TypeScript compilation success
-- ✅ 100% test pass rate
-- ✅ Zero breaking changes
-
-**The TDK CLI type system is well-consolidated and maintainable.**

package/openspec/changes/archive/2026-05-04-comprehensive-cleanup-final/tasks.md

@@ -1,137 +0,0 @@
-## 1. Deduplication & DRY Implementation
-
-Research Phase:
-- [ ] 1.1 Use jscpd or similar to find code duplication patterns
-- [ ] 1.2 Identify duplicate logic across CLI commands
-- [ ] 1.3 Find duplicate utility functions
-- [ ] 1.4 Document patterns appearing 3+ times
-- [ ] 1.5 Write CRITICAL_ASSESSMENT_1.md with findings and recommendations
-
-Implementation Phase:
-- [ ] 1.6 Create shared utility modules for common patterns
-- [ ] 1.7 Consolidate duplicate validation logic
-- [ ] 1.8 Extract shared template generation code
-- [ ] 1.9 Merge duplicate error handling patterns
-- [ ] 1.10 Verify all deduplication with tests
-
-## 2. Type Definition Consolidation
-
-Research Phase:
-- [ ] 2.1 Inventory all type definitions in cli/src
-- [ ] 2.2 Find types that should be shared but are duplicated
-- [ ] 2.3 Identify domain-specific type groupings
-- [ ] 2.4 Map current type file organization
-- [ ] 2.5 Write CRITICAL_ASSESSMENT_2.md with consolidation plan
-
-Implementation Phase:
-- [ ] 2.6 Create centralized types directory structure
-- [ ] 2.7 Move shared types to appropriate modules
-- [ ] 2.8 Update all imports to use consolidated types
-- [ ] 2.9 Remove duplicate type definitions
-- [ ] 2.10 Verify type checking passes
-
-## 3. Dead Code Elimination (knip)
-
-Research Phase:
-- [ ] 3.1 Run knip to identify unused exports
-- [ ] 3.2 Run knip to identify unused dependencies
-- [ ] 3.3 Cross-reference with actual usage in codebase
-- [ ] 3.4 Identify false positives (dynamically loaded code)
-- [ ] 3.5 Write CRITICAL_ASSESSMENT_3.md with removal candidates
-
-Implementation Phase:
-- [ ] 3.6 Remove verified unused exports
-- [ ] 3.7 Remove verified unused dependencies from package.json
-- [ ] 3.8 Remove unused imports in all files
-- [ ] 3.9 Remove unused functions and variables
-- [ ] 3.10 Verify no runtime regressions
-
-## 4. Circular Dependency Resolution (madge)
-
-Research Phase:
-- [ ] 4.1 Run madge --circular on cli/src
-- [ ] 4.2 Map full dependency graph
-- [ ] 4.3 Identify root causes of each cycle
-- [ ] 4.4 Design minimal fixes for each cycle
-- [ ] 4.5 Write CRITICAL_ASSESSMENT_4.md with resolution plan
-
-Implementation Phase:
-- [ ] 4.6 Extract shared code to break cycles
-- [ ] 4.7 Reorder imports where possible
-- [ ] 4.8 Create interface/implementation splits if needed
-- [ ] 4.9 Verify madge shows no circular dependencies
-- [ ] 4.10 Run full test suite
-
-## 5. Weak Type Replacement (any/unknown)
-
-Research Phase:
-- [ ] 5.1 Find all `any` types in codebase
-- [ ] 5.2 Find all `unknown` types in codebase
-- [ ] 5.3 Research actual runtime values for each
-- [ ] 5.4 Check package type definitions for external APIs
-- [ ] 5.5 Write CRITICAL_ASSESSMENT_5.md with replacement types
-
-Implementation Phase:
-- [ ] 5.6 Replace `any` with specific types
-- [ ] 5.7 Replace `unknown` with union types or branded types
-- [ ] 5.8 Add runtime type guards where needed
-- [ ] 5.9 Update function signatures
-- [ ] 5.10 Verify no type errors and tests pass
-
-## 6. Defensive Programming Cleanup
-
-Research Phase:
-- [ ] 6.1 Find all try/catch blocks in codebase
-- [ ] 6.2 Identify error-swallowing patterns (empty catch)
-- [ ] 6.3 Identify unnecessary fallback values
-- [ ] 6.4 Determine which catches serve legitimate purposes
-- [ ] 6.5 Write CRITICAL_ASSESSMENT_6.md with cleanup plan
-
-Implementation Phase:
-- [ ] 6.6 Remove empty catch blocks
-- [ ] 6.7 Remove error-hiding patterns
-- [ ] 6.8 Replace vague fallbacks with explicit error handling
-- [ ] 6.9 Keep only necessary defensive code with clear comments
-- [ ] 6.10 Verify error handling tests pass
-
-## 7. Legacy & Deprecated Code Removal
-
-Research Phase:
-- [ ] 7.1 Find all TODO/FIXME comments related to legacy code
-- [ ] 7.2 Identify deprecated functions and methods
-- [ ] 7.3 Find fallback code for removed features
-- [ ] 7.4 Identify migration compatibility code
-- [ ] 7.5 Write CRITICAL_ASSESSMENT_7.md with removal candidates
-
-Implementation Phase:
-- [ ] 7.6 Remove deprecated functions
-- [ ] 7.7 Remove legacy fallback code paths
-- [ ] 7.8 Clean up migration compatibility shims
-- [ ] 7.9 Update any remaining callers
-- [ ] 7.10 Verify clean code paths remain
-
-## 8. AI Slop & Comment Cleanup
-
-Research Phase:
-- [ ] 8.1 Scan for AI-generated comment patterns
-- [ ] 8.2 Find TODO comments describing future work that's done
-- [ ] 8.3 Identify stub functions and placeholder code
-- [ ] 8.4 Find "LARP" comments (describing aspirational state)
-- [ ] 8.5 Write CRITICAL_ASSESSMENT_8.md with cleanup targets
-
-Implementation Phase:
-- [ ] 8.6 Remove AI-generated boilerplate comments
-- [ ] 8.7 Remove completed TODO comments
-- [ ] 8.8 Remove or implement stub functions
-- [ ] 8.9 Replace LARP comments with accurate descriptions
-- [ ] 8.10 Add helpful comments where genuinely needed
-
-## Final Verification
-
-- [ ] 9.1 Run full test suite (all tests must pass)
-- [ ] 9.2 Run type checker (zero errors)
-- [ ] 9.3 Run linter (zero warnings)
-- [ ] 9.4 Run knip (verify clean)
-- [ ] 9.5 Run madge (no circular dependencies)
-- [ ] 9.6 Generate final report with metrics
-- [ ] 9.7 Archive all critical assessment documents