Create standalone utility to archive invalid run directories

[williamthorsen]

Problem

The Factory app logs warnings when run directories are missing required files (run-index.json, run-log.jsonl, or status.json), have corrupt JSON, or fail schema validation. These warnings create noise in server logs. There is no standalone way to identify or clean up these invalid directories.

Solution

Extract directory discovery and validation logic into @codeassembly/run-core so both a new standalone CLI and the Factory app share the same code. Add a Factory configuration system to suppress invalid-run warnings by default.

New run-core modules

• src/scanners/run-directory-scanner.ts — discoverRunDirectories(basePath): walks the project/ticket/run hierarchy (both Pattern 1 tickets/ and Pattern 2 direct-entry layouts), returns a flat list of RunDirectoryEntry objects. Skips hidden dirs and -interactive dirs.
• src/scanners/run-directory-validator.ts — validateRunDirectory(runPath): wraps parseRunData and returns a discriminated union ({ valid: true, status } or { valid: false, reason }) instead of throwing. Reason values: missing run-index.json, missing run-log.jsonl, corrupt JSON, invalid schema.
• src/type-guards.ts — consolidated isEnoent helper, replacing duplicates in run-data-parser.ts and Factory's type-guards.ts.
• src/scanners/index.ts — barrel export for @codeassembly/run-core/scanners subpath.

CLI (src/cli.ts)

Standalone script following the packages/agents/src/cli.ts pattern. Binary name: codeassembly-runs.

• check (default) — scans and reports invalid run directories with concise reasons
• archive — scans, reports, then prompts to move invalid directories to {project}/tickets-archived/{ticketId}/{runId}/
• --path <dir> — override base projects path (default: AI_PROJECTS_PATH or ~/.ai/projects)

Factory changes

• src/config.ts — central factoryConfig object. Initial option: logInvalidRuns (env: FACTORY_LOG_INVALID_RUNS, default false).
• ProjectScanner — refactored to delegate to run-core's discoverRunDirectories + validateRunDirectory. Invalid runs are silently skipped unless logInvalidRuns is true. Unexpected I/O errors always logged.
• type-guards.ts — reduced to re-export from run-core.

Acceptance criteria

• discoverRunDirectories returns all candidate run directories for both directory layout patterns
• validateRunDirectory returns structured results for all error categories (missing files, corrupt JSON, invalid schema) and valid runs (v1, v2, v3)
• isEnoent lives in run-core/src/type-guards.ts; no duplicates remain
• codeassembly-runs check lists invalid directories with concise reasons and exits 1 if any found
• codeassembly-runs archive prompts and moves invalid directories to tickets-archived/
• Factory's ProjectScanner uses run-core scanners; no directory-walking logic remains in Factory
• Factory suppresses invalid-run warnings by default; FACTORY_LOG_INVALID_RUNS=true re-enables them
• factoryConfig in packages/factory/src/config.ts is extensible for future options
• All new code has unit tests
• pnpm run ci passes

[williamthorsen]

<details>
<summary>Implementation plan</summary>

# Archive invalid run directories — implementation plan

**Goal:** Create shared validation in run-core, a standalone CLI to report/archive invalid run directories, and a Factory config toggle to suppress warnings.

**Architecture:** Extract directory discovery and validation from Factory's `ProjectScanner` into `@codeassembly/run-core/scanners`. The CLI and Factory both import from this shared module. Factory gains a `config.ts` for env-var-driven settings.

**Tech Stack:** TypeScript, Vitest, Node.js `node:fs/promises`, `node:readline`

---

### Task 1: Add `isEnoent` type guard to run-core

**Files:**

- Create: `packages/run-core/src/type-guards.ts`
- Modify: `packages/run-core/src/parsers/run-data-parser.ts`
- Modify: `packages/run-core/src/index.ts`

**Step 1: Create the type guard module**

```typescript
// packages/run-core/src/type-guards.ts

/** Check whether an error is an ENOENT filesystem error. */
export function isEnoent(error: unknown): boolean {
  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
}

Step 2: Update run-data-parser.ts to import from the new module

Remove the local isEnoent function (lines 13-15) and replace with:

import { isEnoent } from '../type-guards.js';

Step 3: Export from root index.ts

Add to packages/run-core/src/index.ts:

// Type guards
export { isEnoent } from './type-guards.js';

Step 4: Run tests to verify nothing broke

Run: cd packages/run-core && pnpm run ws test

Step 5: Commit

#213 run-core|refactor: Extract isEnoent into shared type-guards module

---

Task 2: Create validateRunDirectory in run-core

Files:

• Create: packages/run-core/src/scanners/run-directory-validator.ts
• Create: packages/run-core/src/scanners/__tests__/run-directory-validator.test.ts
• Create: packages/run-core/src/scanners/index.ts
• Modify: packages/run-core/package.json

Step 1: Write the failing tests

Create packages/run-core/src/scanners/__tests__/run-directory-validator.test.ts with tests for:

• Valid v1, v2, v3 run directories → { valid: true, status }
• Missing both files → { valid: false, reason: 'missing run-index.json' }
• V3 missing companion → { valid: false, reason: 'missing run-log.jsonl' }
• Corrupt JSON → { valid: false, reason: 'corrupt JSON' }
• Invalid schema → { valid: false, reason: 'invalid schema' }
• Unexpected errors (EACCES) → rethrown

Step 2: Write the implementation

import type { CanonicalRunStatus } from '../types/canonical.js';
import { RunDataParseError } from '../run-data-parse-error.js';
import { isEnoent } from '../type-guards.js';
import { parseRunData } from '../parsers/run-data-parser.js';

export type InvalidRunReason = 'missing run-index.json' | 'missing run-log.jsonl' | 'corrupt JSON' | 'invalid schema';

export interface ValidRunResult { valid: true; status: CanonicalRunStatus }
export interface InvalidRunResult { valid: false; reason: InvalidRunReason }
export type RunValidationResult = ValidRunResult | InvalidRunResult;

const CATEGORY_TO_REASON: Record<string, InvalidRunReason> = {
  corrupt_json: 'corrupt JSON',
  invalid_schema: 'invalid schema',
  missing_companion: 'missing run-log.jsonl',
};

/** Validates a run directory by attempting to parse its run data files. */
export async function validateRunDirectory(runPath: string): Promise<RunValidationResult> {
  try {
    const status = await parseRunData(runPath);
    return { valid: true, status };
  } catch (error) {
    if (isEnoent(error)) return { valid: false, reason: 'missing run-index.json' };
    if (error instanceof RunDataParseError) {
      const reason = CATEGORY_TO_REASON[error.category];
      if (reason) return { valid: false, reason };
    }
    throw error;
  }
}

Step 3: Create barrel export and add ./scanners subpath to package.json

Step 4: Commit

#213 run-core|feat: Add run directory validator

---

Task 3: Create discoverRunDirectories in run-core

Files:

• Create: packages/run-core/src/scanners/run-directory-scanner.ts
• Create: packages/run-core/src/scanners/__tests__/run-directory-scanner.test.ts
• Modify: packages/run-core/src/scanners/index.ts

Step 1: Write the failing tests

Tests for: Pattern 1 (tickets/ subdir), Pattern 2 (direct entries), Pattern 1 precedence, hidden dir skipping, -interactive skipping, non-directory entries, empty base, missing base, multiple projects/tickets.

Step 2: Write the implementation

export interface RunDirectoryEntry {
  projectSlug: string;
  ticketId: string;
  runId: string;
  runPath: string;
}

/** Walks the project hierarchy and returns all candidate run directory entries. */
export async function discoverRunDirectories(basePath: string): Promise<RunDirectoryEntry[]>

Internal helpers: scanTicketsDir, scanDirectEntries, scanRunsInTicket, isDirectory.

Step 3: Update barrel export

Step 4: Commit

#213 run-core|feat: Add run directory scanner

---

Task 4: Create Factory config module

Files:

• Create: packages/factory/src/config.ts

export interface FactoryConfig {
  logInvalidRuns: boolean;
}

/** Central configuration for the Factory app, loaded from environment variables. */
export const factoryConfig: FactoryConfig = {
  logInvalidRuns: process.env.FACTORY_LOG_INVALID_RUNS === 'true',
};

Commit:

#213 factory|feat: Add central configuration module

---

Task 5: Refactor ProjectScanner to use run-core scanners

Files:

• Modify: packages/factory/src/server/services/project-scanner.ts
• Modify: packages/factory/src/server/services/__tests__/project-scanner.test.ts
• Modify: packages/factory/src/server/type-guards.ts

Step 1: Update tests to mock @codeassembly/run-core/scanners and ../../config.js instead of node:fs/promises. Test: valid run indexing, sorting, warning suppression by default, warning logging when enabled, unexpected error logging, grouping, caching.

Step 2: Rewrite ProjectScanner — delegates to discoverRunDirectories + validateRunDirectory, groups results into ProjectIndex, respects factoryConfig.logInvalidRuns.

Step 3: Reduce type-guards.ts to re-export from run-core.

Step 4: Run pnpm run check

Step 5: Commit

#213 factory|refactor: Use run-core scanners in ProjectScanner

---

Task 6: Create the CLI script

Files:

• Create: packages/run-core/src/cli.ts
• Modify: packages/run-core/package.json

Commands: check (default, exits 1 if invalid found), archive (prompts to move to tickets-archived/). Flag: --path <dir>.

Follows the packages/agents/src/cli.ts pattern. Binary: codeassembly-runs.

Commit:

#213 run-core|feat: Add CLI for checking and archiving invalid run directories

---

Task 7: Final integration verification

Run pnpm run ci. Optional smoke test with npx tsx src/cli.ts check.

```