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

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

@@ -1,46 +0,0 @@
-## Why
-
-The TDK CLI codebase has accumulated significant technical debt through code duplication, scattered type definitions, unused code, circular dependencies, weak typing, defensive programming patterns, legacy fallbacks, and AI-generated artifacts. These issues compound daily, slowing development, increasing bug risk, and making the codebase harder to maintain and navigate. Now is the critical time to execute a comprehensive cleanup before the technical debt becomes unmanageable.
-
-## What Changes
-
-This change executes a **comprehensive 8-dimensional codebase cleanup**:
-
-1. **DRY & Deduplication**: Consolidate duplicate code patterns and implement DRY principles where they reduce complexity
-2. **Type Consolidation**: Find all type definitions and consolidate shared types into centralized locations
-3. **Dead Code Elimination**: Use knip to identify and remove all unused code with verification
-4. **Circular Dependency Resolution**: Untangle circular dependencies using madge analysis
-5. **Strong Typing**: Remove all weak types (any, unknown) with proper research-based replacements
-6. **Defensive Programming Cleanup**: Remove unnecessary try/catch blocks that hide errors without purpose
-7. **Legacy Code Removal**: Eliminate deprecated, fallback, and legacy code paths
-8. **AI Slop Cleanup**: Remove stubs, LARP artifacts, unnecessary comments, and non-helpful documentation
-
-## Capabilities
-
-### New Capabilities
-- `code-quality-guardian`: Automated enforcement of code quality standards post-cleanup
-- `type-registry`: Centralized type definition management system
-- `dependency-graph-monitor`: Continuous monitoring for circular dependencies
-
-### Modified Capabilities
-- All CLI commands benefit from cleaner, deduplicated code
-- Type safety improved across all modules
-- Error handling becomes explicit and purposeful
-- Code navigation and comprehension improved
-
-## Impact
-
-- **CLI**: TypeScript source files in `cli/src/` - comprehensive cleanup of all 8 dimensions
-- **Discovery**: Python modules in `discovery/` - cleanup where applicable
-- **Engine**: Starlark files in `engine/` - cleanup of dead code and comments
-- **Tests**: All test files - improved type safety and removed dead test code
-- **Breaking changes**: Minimal - only removal of truly unused code
-
-## Success Metrics
-
-- Zero `any` or `unknown` types remaining (except truly unavoidable cases)
-- All circular dependencies resolved
-- 20%+ reduction in code volume through deduplication and dead code removal
-- All knip-reported unused code verified and removed
-- No unnecessary try/catch blocks remaining
-- No AI-generated stubs or placeholder comments

package/openspec/changes/archive/2026-05-04-comprehensive-cleanup-final/specs/ai-slop-cleanup/CLEANUP_REPORT_8.md

@@ -1,174 +0,0 @@
-# AI Slop, Stub, and Comment Cleanup Report
-
-**Date:** 2026-05-04  
-**Agent:** Subagent 8  
-**Scope:** TDK CLI Source Code (`cli/src/`)
-
----
-
-## Summary
-
-Successfully removed AI-generated boilerplate comments, unnecessary JSDoc blocks, and obvious inline comments from the TDK CLI codebase. All changes were high-confidence removals - no functional code was changed, no helpful comments were removed, and all tests pass.
-
----
-
-## Files Changed
-
-| File | Changes Made | Lines Removed |
-|------|--------------|---------------|
-| `cli/src/utils/file-helpers.ts` | Removed 5 JSDoc blocks | ~25 lines |
-| `cli/src/utils/formatting.ts` | Removed 3 JSDoc blocks, 4 inline comments | ~18 lines |
-| `cli/src/utils/errors.ts` | Simplified 1 JSDoc, removed 1 inline comment | ~4 lines |
-| `cli/src/utils/services.ts` | Removed 2 inline comments | 2 lines |
-| `cli/src/utils/discovery-context.ts` | Removed 1 JSDoc, 2 inline comments | ~7 lines |
-| `cli/src/commands/config.ts` | Removed 1 JSDoc block, 1 inline comment | ~9 lines |
-| `cli/src/commands/resource.ts` | Removed 1 JSDoc comment | 1 line |
-| `cli/src/commands/up.ts` | Removed 3 inline comments | 3 lines |
-| `cli/src/commands/stacks.ts` | Removed 1 inline comment | 1 line |
-| `cli/src/config/platform-standards.ts` | Removed 2 header comments | 2 lines |
-
-**Total:** 10 files changed, ~72 lines removed
-
----
-
-## Categories of Cleanup
-
-### 1. Removed JSDoc Comments Restating the Obvious
-
-**Example from `file-helpers.ts` (BEFORE):**
-```typescript
-/**
- * Write a JSON object to a file with consistent formatting.
- * Automatically adds trailing newline for POSIX compliance.
- */
-export function writeJsonFile(filePath: string, data: unknown, space: number = 2): void {
-```
-
-**AFTER:**
-```typescript
-export function writeJsonFile(filePath: string, data: unknown, space: number = 2): void {
-```
-
-**Rationale:** Function name `writeJsonFile` already tells us what it does. The JSDoc adds no value.
-
-### 2. Removed Inline Comments Stating the Obvious
-
-**Example from `services.ts` (BEFORE):**
-```typescript
-const configType = resource.config?.appType;
-// Default to 'backend' when type not explicitly configured
-let type: ResourceType = configType || 'backend';
-```
-
-**AFTER:**
-```typescript
-const configType = resource.config?.appType;
-let type: ResourceType = configType || 'backend';
-```
-
-**Rationale:** The code `|| 'backend'` makes it obvious we're defaulting to 'backend'.
-
-### 3. Simplified Verbose JSDoc
-
-**Example from `errors.ts` (BEFORE):**
-```typescript
-/**
- * Display a formatted error message. Does NOT exit.
- * Use showErrorAndExit() for fatal errors.
- */
-export function showError(...)
-```
-
-**AFTER:**
-```typescript
-/** Display a formatted error message. Does NOT exit. */
-export function showError(...)
-```
-
-**Rationale:** The second sentence was redundant - the function name already implies it's not exiting (that would be `showErrorAndExit`).
-
----
-
-## Preserved Comments (Kept Intentionally)
-
-The following comments were kept because they add real value:
-
-| File | Line | Comment | Why It Stays |
-|------|------|---------|--------------|
-| `commands/up.ts:65` | `// Give it a moment to fully shut down` | Explains WHY the 2000ms delay exists |
-| `commands/stack.ts:99` | `// Clear cache since we're about to modify resources` | Explains WHY we clear cache |
-| `utils/tilt.ts:73` | Error handling comment | Explains non-obvious design decision |
-| `commands/resource.ts:153,166-167,252,259,286,421` | Template guidance comments | Helpful for users who get generated code |
-| `commands/networks.ts` | Multiple regex pattern comments | Explain complex parsing logic |
-| `commands/upgrade.ts` | Fallback logic comments | Explain WHY different paths taken |
-
----
-
-## Verification Results
-
-### Tests
-```
-✓ src/commands/__tests__/project.test.ts (4 tests) 8ms
-✓ src/commands/__tests__/error-handling.test.ts (4 tests) 7ms
-✓ src/commands/__tests__/config.test.ts (11 tests) 5ms
-✓ src/commands/__tests__/resource.test.ts (18 tests) 5ms
-
-Test Files  4 passed (4)
-Tests       37 passed (37)
-```
-
-### Type Checking
-```
-$ npx tsc --noEmit
-(no errors)
-```
-
----
-
-## Impact Assessment
-
-### Before
-- 20+ redundant comments
-- Visual noise that obscures actual code
-- Maintenance burden (keeping comments in sync)
-- AI-generated style patterns
-
-### After
-- Clean, self-documenting code
-- Only meaningful comments remain
-- Easier to scan and understand
-- Consistent with modern TypeScript practices
-
----
-
-## Guidelines for Future Development
-
-Based on this cleanup, established the following patterns:
-
-1. **Remove comments that restate the obvious**
-   - ❌ `// Update cache` before `cache = value`
-   - ❌ JSDoc describing simple functions like `writeFile`
-
-2. **Keep comments that explain WHY**
-   - ✅ `// Give it a moment to fully shut down`
-   - ✅ Security context: `// Prevent path traversal attacks`
-
-3. **Keep comments for complex logic**
-   - ✅ Regex pattern explanations
-   - ✅ Algorithm explanations
-
-4. **Prefer self-documenting code**
-   - Clear function names over comments
-   - Descriptive variable names
-
----
-
-## Conclusion
-
-The TDK CLI codebase is now cleaner and easier to read. The removed comments were creating visual noise without adding value. The remaining comments all serve a purpose: explaining WHY something is done, not WHAT is being done (the code shows that).
-
-**Status:** ✅ COMPLETE - All tests pass, TypeScript compiles, code is cleaner.
-
----
-
-**End of Report**

package/openspec/changes/archive/2026-05-04-comprehensive-cleanup-final/specs/ai-slop-cleanup/CRITICAL_ASSESSMENT_8.md

@@ -1,160 +0,0 @@
-# Critical Assessment: AI Slop, Stub, and Comment Cleanup
-
-**Date:** 2026-05-04  
-**Scope:** TDK CLI Source Code (`cli/src/`)  
-**Assessor:** Subagent 8 (AI Slop Cleanup)
-
----
-
-## Executive Summary
-
-The TDK CLI codebase has undergone significant prior cleanup, resulting in a relatively clean state. Most obvious AI-generated boilerplate has already been removed. This assessment identifies **remaining subtle patterns** that still warrant cleanup.
-
-**Inventory Summary:**
-- **JSDoc comments restating the obvious:** 11 instances
-- **Inline comments stating obvious operations:** 14 instances
-- **File headers stating the obvious:** 2 instances
-- **Template comments (user-facing):** 7 instances
-- **TODO/FIXME comments:** 0 (clean!)
-- **Stub functions:** 0 (clean!)
-
----
-
-## Phase 1: Complete Inventory
-
-### Category 1: JSDoc Comments Restating the Obvious (11 instances)
-
-These JSDoc comments describe simple operations that are already clear from function names:
-
-| File | Line | Current Comment | Classification |
-|------|------|-----------------|----------------|
-| `utils/file-helpers.ts:4-7` | `/** Write a JSON object to a file with consistent formatting... */` | **REMOVE** - Function name says it |
-| `utils/file-helpers.ts:13-16` | `/** Write a JSON object to a file within a directory... */` | **REMOVE** - Simple wrapper, obvious |
-| `utils/file-helpers.ts:27-29` | `/** Write text content to a file with consistent encoding. */` | **REMOVE** - Obvious from name |
-| `utils/file-helpers.ts:34-37` | `/** Write text content to a file within a directory... */` | **REMOVE** - Obvious wrapper |
-| `utils/file-helpers.ts:47-52` | `/** Ensure a directory exists, creating it if necessary... */` | **REMOVE** - Obvious from name |
-| `utils/formatting.ts:214-217` | `/** Display a success message with checkmark icon... */` | **REMOVE** - Function is self-explanatory |
-| `utils/formatting.ts:222-225` | `/** Display a step/action message with blue color... */` | **REMOVE** - Obvious |
-| `utils/formatting.ts:230-234` | `/** Display detailed information with indentation... */` | **REMOVE** - Obvious |
-| `utils/errors.ts:113-116` | `/** Display a formatted error message... */` | **SIMPLIFY** - Keep one line explaining it doesn't exit |
-| `utils/discovery-context.ts:18-21` | `/** Create a discovery context with all resource and stack info... */` | **REMOVE** - Obvious from name |
-| `commands/config.ts:178-184` | `/** Toggle an optional infrastructure service on or off... */` | **REMOVE** - Obvious from function name |
-
-### Category 2: Inline Comments Stating the Obvious (14 instances)
-
-| File | Line | Comment | Classification |
-|------|------|---------|----------------|
-| `utils/errors.ts:36` | `// Common error factories` | **REMOVE** - Obvious from variable name |
-| `utils/services.ts:215` | `// Default to 'backend' when type not explicitly configured` | **REMOVE** - Code says this |
-| `utils/services.ts:302` | `// Calculate overall status based on resource statuses` | **REMOVE** - Obvious |
-| `utils/formatting.ts:72` | `// Use category for type-safe chalk color mapping` | **REMOVE** - Implementation detail |
-| `utils/formatting.ts:171` | `// Top border with title` | **REMOVE** - Obvious |
-| `utils/formatting.ts:177` | `// Content lines` | **REMOVE** - Obvious |
-| `utils/formatting.ts:183` | `// Bottom border` | **REMOVE** - Obvious |
-| `utils/discovery-context.ts:4` | `// Cache for memoizing discovery context within a session` | **REMOVE** - Obvious |
-| `utils/discovery-context.ts:50` | `// Update cache` | **REMOVE** - Obvious |
-| `commands/up.ts:37` | `// No stack specified - get all resources` | **REMOVE** - Code says this |
-| `commands/up.ts:65` | `// Give it a moment to fully shut down` | **KEEP** - Explains WHY the delay |
-| `commands/up.ts:72` | `// If TILT_PORT is already set in env, use that` | **REMOVE** - Obvious |
-| `commands/up.ts:94` | `// Run tilt up` | **REMOVE** - Obvious |
-| `commands/stack.ts:99` | `// Clear cache since we're about to modify resources` | **KEEP** - Explains WHY |
-| `commands/stacks.ts:14` | `// Single discovery call for all resources and stacks` | **REMOVE** - Obvious |
-| `config/platform-standards.ts:1-2` | `// Platform-wide standards...` | **REMOVE** - File is self-explanatory |
-| `commands/resource.ts:29` | `/** Type-specific configuration extensions... */` | **REMOVE** - Obvious |
-
-### Category 3: Template Comments (User-Facing Code)
-
-These comments appear in generated code templates. Some are helpful, some are noise:
-
-| File | Line | Comment | Classification |
-|------|------|---------|----------------|
-| `commands/resource.ts:153` | `// Health check endpoint (required by TILT_RESOURCE_DEFAULTS.star)` | **KEEP** - Explains WHY |
-| `commands/resource.ts:166-167` | `// Add dependency checks here...` | **KEEP** - Helpful guidance |
-| `commands/resource.ts:252` | `// Add job processing logic here using job.payload` | **KEEP** - Helpful placeholder |
-| `commands/resource.ts:259` | `// Connect to your queue...` | **KEEP** - Helpful guidance |
-| `commands/resource.ts:286` | `// Wait before retrying to avoid tight error loops` | **KEEP** - Explains WHY |
-| `commands/resource.ts:421` | `// Prevent path traversal attacks` | **KEEP** - Security context |
-
-### Category 4: High-Value Comments to Preserve
-
-These comments explain WHY or provide important context:
-
-| File | Line | Comment | Why It Stays |
-|------|------|---------|--------------|
-| `utils/tilt.ts:73` | Explains error handling strategy | Explains non-obvious design decision |
-| `commands/upgrade.ts:23,66,87,115` | Comments explaining fallback logic | Explain WHY different paths |
-| `commands/networks.ts:64,75-76,79-80,90,92,97-98,104,143` | Complex parsing logic comments | Explain complex regex patterns |
-| `commands/resource.ts:421` | Security comment | Explains security intent |
-
-### Category 5: TODO/FIXME/Stubs
-
-**STATUS: CLEAN**
-
-No TODO, FIXME, HACK, or XXX comments found in production code.
-No stub functions with `throw new Error("Not implemented")` found.
-
----
-
-## Phase 2: Implementation Plan
-
-### High-Confidence Removals (Safe to Remove)
-
-1. **Remove JSDoc comments** from:
-   - `utils/file-helpers.ts` - All 5 JSDoc blocks (lines 4-52)
-   - `utils/formatting.ts` - 3 JSDoc blocks (lines 214-236)
-   - `utils/discovery-context.ts` - 1 JSDoc block (lines 18-21)
-   - `commands/config.ts` - 1 JSDoc block (lines 178-184)
-   - `commands/resource.ts` - 1 JSDoc block (line 29)
-
-2. **Remove obvious inline comments** from:
-   - `utils/errors.ts:36`
-   - `utils/services.ts:215,302`
-   - `utils/formatting.ts:72,171,177,183`
-   - `utils/discovery-context.ts:4,50`
-   - `commands/up.ts:37,72,94`
-   - `commands/stacks.ts:14`
-   - `config/platform-standards.ts:1-2`
-
-### Medium-Confidence Changes (Simplify)
-
-1. **Simplify JSDoc in `utils/errors.ts:113-116`**:
-   - Keep: `/** Display a formatted error message. Does NOT exit. */`
-   - Remove verbose description and suggestions note
-
----
-
-## Expected Results
-
-- **Comments removed:** ~20
-- **Lines removed:** ~50
-- **Code readability:** Improved - less visual noise
-- **No functional changes:** Pure comment cleanup
-
----
-
-## Files to Modify
-
-1. `cli/src/utils/file-helpers.ts`
-2. `cli/src/utils/formatting.ts`
-3. `cli/src/utils/errors.ts`
-4. `cli/src/utils/services.ts`
-5. `cli/src/utils/discovery-context.ts`
-6. `cli/src/commands/config.ts`
-7. `cli/src/commands/resource.ts`
-8. `cli/src/commands/up.ts`
-9. `cli/src/commands/stacks.ts`
-10. `cli/src/config/platform-standards.ts`
-
----
-
-## Verification Checklist
-
-- [ ] All tests pass after changes
-- [ ] No TODO/FIXME comments removed
-- [ ] No security-related comments removed
-- [ ] No template/helpful comments removed
-- [ ] Code is easier to read after cleanup
-
----
-
-**End of Assessment**