Refactoring

.github/workflows/_e2e-cli.yml

@@ -0,0 +1,88 @@
+name: E2E Tests for CLI (reusable)
+
+# Bun:test suites under apps/e2e/cli against apps/cli/dist/cli.
+# Called by:
+#   - CI (full run, after build-cli)
+#   - E2E Tests for CLI (manual workflow_dispatch, after build-cli)
+# Expects artifact `cli-dist` from the caller.
+
+on:
+  workflow_call:
+    inputs:
+      test_filter:
+        description: 'Optional bun test path under apps/e2e/cli (e.g. ./cli/tmdb.test.ts). Empty runs all CLI e2e tests.'
+        required: false
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  e2e-cli:
+    name: E2E Tests for CLI
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      TMDB_API_KEY: ${{ secrets.TMDB_API_KEY }}
+      TVDB_API_KEY: ${{ secrets.TVDB_API_KEY }}
+      TMDB_HOST: https://api.themoviedb.org/3
+      TVDB_HOST: https://api4.thetvdb.com/v4
+      USE_EMBEDDED_HTTP_PROXY: 'true'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install all dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Download CLI build
+        uses: actions/download-artifact@v4
+        with:
+          name: cli-dist
+          path: apps/cli/dist
+
+      - name: Require API key secrets
+        run: |
+          missing=0
+          if [ -z "${TMDB_API_KEY:-}" ]; then
+            echo "::error::Secret TMDB_API_KEY is empty. Add it under Settings → Secrets and variables → Actions."
+            missing=1
+          fi
+          if [ -z "${TVDB_API_KEY:-}" ]; then
+            echo "::error::Secret TVDB_API_KEY is empty. Add it under Settings → Secrets and variables → Actions."
+            missing=1
+          fi
+          exit "$missing"
+
+      - name: Run CLI E2E tests
+        run: |
+          if [ -n "${{ inputs.test_filter }}" ]; then
+            bun ci/run-cli-e2e-test.ts "${{ inputs.test_filter }}"
+          else
+            bun ci/run-cli-e2e-test.ts
+          fi
+
+  e2e-cli-gate:
+    name: cli-e2e / gate
+    needs: [e2e-cli]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require CLI E2E job passed
+        run: |
+          set -euo pipefail
+          if [ "${{ needs.e2e-cli.result }}" != "success" ]; then
+            echo "::error::cli e2e: ${{ needs.e2e-cli.result }}"
+            exit 1
+          fi
+          echo "CLI E2E job passed."

.github/workflows/ci.yml

@@ -2,9 +2,13 @@ name: CI
 
 # Merged from build.yml + e2e-test.yml + e2e-docker.yml + e2e-http-proxy.yml.
 # E2E groups run only after the build pipeline (test / lint / typecheck / build) succeeds.
+#
+# CLI bun:test e2e: reusable _e2e-cli.yml (also callable via "E2E Tests for CLI" workflow).
+#
 # Required check names (RELEASE_REQUIRED_CHECKS) must stay stable:
 #   Run Unit Tests, Lint UI, Typecheck, Build UI, Build CLI,
 #   host-e2e / gate, docker-e2e / gate, http-proxy-e2e / gate
+#   (cli-e2e / gate is optional for release until added to RELEASE_REQUIRED_CHECKS)
 on:
   push:
     branches: [ main, develop ]
@@ -15,6 +19,8 @@ on:
       - 'pnpm-workspace.yaml'
       - 'pnpm-lock.yaml'
       - '.github/workflows/ci.yml'
+      - '.github/workflows/_e2e-cli.yml'
+      - '.github/workflows/e2e-cli.yml'
   pull_request:
     branches: [ main, develop ]
     paths:
@@ -24,6 +30,8 @@ on:
       - 'pnpm-workspace.yaml'
       - 'pnpm-lock.yaml'
       - '.github/workflows/ci.yml'
+      - '.github/workflows/_e2e-cli.yml'
+      - '.github/workflows/e2e-cli.yml'
   workflow_dispatch:
 
 permissions:
@@ -169,7 +177,9 @@ jobs:
             spec: "./test/specs/ai/*.e2e.ts"
             artifact_prefix: ai
           - name: Run Config and HTTP Proxy Tests
-            spec: "./common/config/*.e2e.ts ./common/httpproxy/*.e2e.ts"
+            # Proxy-through-custom-host specs live under common/config (*WithHttpProxy).
+            # common/httpproxy/* was removed in 78ad8f00.
+            spec: "./common/config/*.e2e.ts"
             artifact_prefix: config-httpproxy
           - name: Run MCP Tests
             spec: "./common/mcp/*.e2e.ts"
@@ -319,7 +329,7 @@ jobs:
 
   e2e-docker:
     name: ${{ matrix.name }}
-    needs: build-image
+    needs: [build-image]
     runs-on: ubuntu-latest
     timeout-minutes: 90
     env:
@@ -341,11 +351,9 @@ jobs:
       matrix:
         include:
           - name: Docker E2E (config)
+            # Includes *WithHttpProxy specs (former common/httpproxy suite).
             spec: "./common/config/*.e2e.ts"
             artifact_prefix: docker-config
-          - name: Docker E2E (httpproxy)
-            spec: "./common/httpproxy/*.e2e.ts"
-            artifact_prefix: docker-httpproxy
           - name: Docker E2E (mcp)
             spec: "./common/mcp/*.e2e.ts"
             artifact_prefix: docker-mcp
@@ -411,7 +419,7 @@ jobs:
         run: gunzip -c smm-latest.tar.gz | docker load
 
       - name: Require API key secrets for suites that need them
-        if: matrix.artifact_prefix == 'docker-httpproxy' || matrix.artifact_prefix == 'docker-media-init'
+        if: matrix.artifact_prefix == 'docker-config' || matrix.artifact_prefix == 'docker-media-init'
         run: |
           missing=0
           if [ -z "${TMDB_API_KEY:-}" ]; then
@@ -556,3 +564,11 @@ jobs:
             exit 1
           fi
           echo "All HTTP Proxy E2E jobs passed."
+
+  # ------------------------------------------------------------------
+  # CLI E2E (bun:test under apps/e2e/cli) — reusable _e2e-cli.yml
+  # ------------------------------------------------------------------
+  e2e-cli:
+    needs: [build-cli]
+    uses: ./.github/workflows/_e2e-cli.yml
+    secrets: inherit

.github/workflows/e2e-cli.yml

@@ -0,0 +1,55 @@
+name: E2E Tests for CLI
+
+# Manual-only entry for CLI bun:test e2e (apps/e2e/cli).
+# Builds CLI, then calls reusable _e2e-cli.yml (same job used by CI).
+#
+# For full CI (unit + host/docker/http-proxy + CLI e2e), use the CI workflow.
+
+on:
+  workflow_dispatch:
+    inputs:
+      test_filter:
+        description: 'Optional bun test path under apps/e2e/cli (e.g. ./cli/tmdb.test.ts). Empty runs all CLI e2e tests.'
+        required: false
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  build-cli:
+    name: Build CLI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install all dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build CLI
+        run: cd apps/cli && pnpm run build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-dist
+          path: apps/cli/dist
+          retention-days: 7
+
+  e2e-cli:
+    needs: [build-cli]
+    uses: ./.github/workflows/_e2e-cli.yml
+    with:
+      test_filter: ${{ inputs.test_filter }}
+    secrets: inherit

.superpowers/sdd/task-3-fix-report.md

@@ -0,0 +1,25 @@
+# Task 3 Important Findings Fix Report
+
+## Status
+
+Fixed metadata-root propagation and made Core metadata create/update operations atomic within the existing `MediaMetadataHelper` path mutex.
+
+## Changes
+
+- Added `Core.getMetadataRoot()` and used it for metadata helpers, scrape/recognition/rename/import pipelines, and plan persistence operations.
+- Added `MediaMetadataHelper.createIfAbsent()` so existence check and write share one path lock.
+- Added `MediaMetadataHelper.updateIfPresent()` so read-modify-write patches share one path lock.
+- Added focused regressions for distinct metadata roots, concurrent creates, and concurrent non-overlapping patches.
+
+## Verification
+
+- Red phase: all three new regressions failed for the expected reasons.
+- `pnpm exec vitest run src/Core.metadataCrud.test.ts`: 11 tests passed.
+- `pnpm test` in `apps/core`: 45 files and 313 tests passed.
+- `pnpm typecheck` in `apps/core`: passed.
+- IDE lint diagnostics for changed TypeScript files: none.
+
+## Residual
+
+- Locking remains process-local, matching the existing helper design; no distributed or cross-process lock was added.
+- A corrupt existing cache is not overwritten: create reports already-exists based on the physical file, while update reports not-found because the helper cannot read valid metadata.

.superpowers/sdd/task-3-report.md

@@ -0,0 +1,109 @@
+# Task 3 Report: Core metadata CRUD and separate roots
+
+## Status
+
+Implemented the requested Core metadata CRUD API and separated user configuration storage from application metadata storage.
+
+## Changes
+
+- Added `Core.getMetadata(folderPath)`, which returns persisted metadata or throws `MetadataNotFoundError`.
+- Added `Core.createMetadata(mm)`, which writes new metadata or throws `MetadataAlreadyExistsError`.
+- Replaced the old full-document `setMetadata(mm)` API with `setMetadata(folderPath, patch)`, using Task 2's `applyMetadataPatch`.
+- Added idempotent `Core.deleteMetadata(folderPath)`.
+- Kept null-if-missing reads and full-document writes private to Core through `MediaMetadataHelper`.
+- Wired `UserConfigHelper` to `userDataDir` and `MediaMetadataHelper` to `reportedAppDataDir ?? appDataDir`.
+- Wired CLI `getCore()` with `getAppDataDir()` for application data and `getUserDataDir()` for configuration.
+- Passed the split roots through the import pipeline so imports continue to read/write configuration and metadata in their respective locations.
+- Migrated Core and CLI consumers away from the removed public `getMediaMetadata` and full-document `setMetadata` methods.
+
+## TDD evidence
+
+### RED
+
+Command:
+
+```bash
+cd apps/core && pnpm exec vitest run src/Core.metadataCrud.test.ts
+```
+
+Result: failed as expected — 8 tests failed. The new methods were absent (`core.getMetadata is not a function`, `core.createMetadata is not a function`), and the old `setMetadata` signature rejected the new call shape.
+
+The failing tests covered:
+
+- get missing metadata
+- create then get
+- duplicate create
+- patch merge
+- patch missing metadata
+- illegal patch key
+- idempotent delete
+- separate metadata/config roots
+
+### GREEN
+
+Command:
+
+```bash
+cd apps/core && pnpm exec vitest run src/Core.metadataCrud.test.ts
+```
+
+Result: passed — 8/8 tests.
+
+The separate-root CLI integration test initially exposed that `ImportFolderPipeline` still used one root for both stores. After passing `userDataDir` separately, the previously failing `FolderMetadata.test.ts` passed.
+
+## Verification
+
+- `cd apps/core && pnpm test && pnpm typecheck`: passed, 45 files / 310 tests, followed by a clean Core TypeScript check.
+- `cd apps/core && pnpm exec vitest run src/Core.metadataCrud.test.ts src/Core.test.ts`: passed, 80 tests in the required Task 3 suites.
+- `cd apps/cli && pnpm exec vitest run src/cli/folderDisplay.test.ts src/route/FolderMetadata.test.ts src/route/Scrape.test.ts`: passed, 3 files / 14 tests.
+- IDE lint diagnostics for edited files: no errors.
+
+## Known concern
+
+`apps/cli` typecheck remains blocked by existing Task 1 migration debt: several unrelated files still reference the removed `MediaMetadata.files` property. The Task 3 Core typecheck passes; Task 3 did not reimplement the prior migration.
+
+## Commit
+
+Planned commit message: `feat(core): metadata CRUD API and separate config/data dirs`
+# Task 3 Report: Align plan HTTP appDataDir with Core
+
+## Status
+
+Completed and committed as `fa063cc4` (`fix(cli): use Core userDataDir for plan HTTP routes on Linux`).
+
+## Changes
+
+- `apps/cli/src/route/Plans.ts`: plan HTTP routes now use `getUserDataDir()`.
+- `apps/cli/src/mcp/mcp.ts`: MCP plan-writing tools now use `getUserDataDir()`.
+- `apps/cli/server.ts`: chat plan-writing tools now use `getUserDataDir()`.
+- `apps/cli/src/route/Plans.test.ts`: added a split-directory regression test proving `/api/createPlan` writes only under `USER_DATA_DIR/plans`.
+
+## Audit
+
+- `apps/cli/src/route/coreRoutesConfig.ts` retains `getAppDataDir()` because its callers perform list-files, get-episodes, rename-folder, and rename-files HTTP operations rather than plan persistence. Changing it would relocate metadata-cache reads outside this task.
+- Plan persistence hosts in `Plans.ts`, `mcp.ts`, and `server.ts` now match `getCore().appDataDir`.
+- No second plan store was introduced.
+
+## TDD and Verification
+
+- RED: the focused test failed because no plan existed under `USER_DATA_DIR/plans`.
+- GREEN: focused regression passed (1 test).
+- Full CLI suite passed: 73 files and 474 tests; 2 files and 13 tests skipped.
+- CLI `tsc --noEmit` passed.
+- Changed-file lint diagnostics and `git show --check` passed.
+
+## Self-review
+
+- Commit contains only the three plan-host wiring changes and regression test.
+- Unrelated dirty E2E and documentation files were not staged or committed.
+- No correctness issues found. The core-routes `appDataDir` field is overloaded for plan and metadata dependencies in chat/MCP, but Core's directory is the required compatibility behavior for these plan-producing hosts.
+
+## Important review follow-up
+
+- `apps/cli/src/coreRoutesServer.ts` now supplies `getUserDataDir()` to the shared core-routes handler.
+- Startup and shutdown stale-plan cleanup in `apps/cli/index.ts` now scan `userDataDir`.
+- The legacy rename and recognition plan writers now store plans under `getUserDataDir()/plans`.
+- Added `apps/cli/src/coreRoutesServer.test.ts`; its RED run received `/metadata/app-data`, and its GREEN run received `/core/user-data`.
+- Focused plan-route tests passed: 2 files and 2 tests.
+- Full CLI tests passed: 74 files and 475 tests; 2 files and 13 tests skipped.
+- CLI `tsc --noEmit` and changed-file lint diagnostics passed.

.superpowers/sdd/task-4-fix-report.md

@@ -0,0 +1,23 @@
+# Task 4 Important Findings Fix Report
+
+## Status
+
+Fixed metadata RPC request validation so malformed JSON, invalid Zod input, and invalid Core metadata patches return 400 validation ProblemDetails.
+
+## Changes
+
+- Mapped `ZodError` and malformed-JSON `SyntaxError` to `urn:smm:problem:metadata-validation`.
+- Exported and matched Core metadata errors with `instanceof` instead of error-name strings.
+- Required create requests to contain a plain-object `data` with `mediaFolderPath: string`.
+- Restricted set patches to a strict plain object containing only `type`, `mediaFiles`, `tvShow`, and `movie`.
+- Added regressions for malformed JSON, missing `mediaFolderPath`, array patches, and complete 404 ProblemDetails fields.
+
+## Verification
+
+- Red phase: three regressions failed as expected (malformed JSON returned 500, missing `mediaFolderPath` returned 500, and `patch: []` returned 200).
+- `pnpm exec vitest run src/route/metadata`: 4 files and 8 tests passed.
+- IDE lint diagnostics for changed TypeScript files: none.
+
+## Scope
+
+No Task 5+ code or unrelated E2E/log artifacts were changed.