@tdk-landscape/tdk-cli-core 1.3.45 → 1.3.48

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

@@ -0,0 +1,46 @@
+## 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

@@ -0,0 +1,174 @@
+# 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

@@ -0,0 +1,160 @@
+# 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**