feat(cli): auto-add thread entry when running in Amp

[aridyckovsky]

Motivation

When running effect-migrate commands inside Amp, we should automatically track which threads are being used for migration work without requiring manual thread add commands. This reduces friction and ensures complete thread tracking.

Proposed Solution

Auto-detect Amp environment and update threads.json at command start with thread context.

Detection Strategy (ordered)

1. Environment variables:

   • AMP_THREAD_URL - Direct thread URL
   • AMP_THREAD_ID - Thread ID
   • AMP_CONTEXT_THREADS - JSON array of URLs or {id, url} objects
   • AMP_CONTEXT_FILE - Path to JSON context file

2. Context file:

   • .amp/context.json in CWD or nearest ancestor

Extraction Logic

// Extract thread ID from URL if only URL provided
const ID_PATTERN = /\/threads\/(T-[0-9a-f-]{8}-[0-9a-f-]{4}-[0-9a-f-]{4}-[0-9a-f-]{4}-[0-9a-f-]{12})/i

// Normalize to { id, url }
function extractThreads(context: unknown): Array<{ id: string; url: string }> {
  // Scan for thread URLs in strings/objects
  // Extract IDs with regex
  // Return normalized entries
}

When to Add

• On command start (audit, metrics, etc.) before doing work
• Creates threads.json if it doesn't exist
• Runs before main command logic

Deduplication & Merge Logic

// Read existing threads.json
const existing = await readThreads(ampOut)

for (const newThread of ampThreads) {
  const found = existing.threads.find(t => t.id === newThread.id)
  
  if (found) {
    // Update existing: bump seenCount, update lastSeenAt, update URL if changed
    found.lastSeenAt = new Date().toISOString()
    found.seenCount = (found.seenCount || 1) + 1
    if (found.url !== newThread.url) found.url = newThread.url
  } else {
    // Add new entry
    existing.threads.push({
      id: newThread.id,
      url: newThread.url,
      createdAt: new Date().toISOString(),
      source: "amp-auto"
    })
  }
}

// Atomic write: tmp file → rename
await writeFileAtomic(threadsPath, JSON.stringify(existing, null, 2))

Opt-Out Mechanism

Automatic by default when Amp detected, with opt-out:

• Environment: AMP_AUTO_TRACK_THREADS=0
• CLI flag: --no-amp-auto-track

Error Handling

• If no Amp signals detected: silent no-op (no warnings)
• If extraction fails: debug log only, don't block audit
• If threads.json write fails: log error, continue with audit
• Never fail the audit due to thread tracking issues

Schema Extensions (Optional)

Consider adding metadata to thread entries:

{
  "id": "t-abc123...",
  "url": "https://ampcode.com/threads/T-abc123...",
  "createdAt": "2025-11-05T16:00:00.000Z",
  "source": "amp-auto" | "manual",
  "lastSeenAt": "2025-11-05T16:05:00.000Z",
  "seenCount": 3,
  "tags": ["migration"],
  "scope": ["packages/core/"]
}

Implementation Steps

1. Create detectAmpThreads() Effect:

   • Check env vars in order
   • Try reading context file
   • Extract and normalize thread info
   • Return Array<{id, url}> or empty array

2. Create mergeAmpThreads(ampOut, threads) Effect:

   • Read existing threads.json
   • Merge with deduplication by ID
   • Update seenCount/lastSeenAt for existing
   • Atomic write with tmp → rename

3. Integrate in audit command:

   Effect.gen(function*() {
     // Auto-track Amp threads
     const ampThreads = yield* detectAmpThreads()
     if (ampThreads.length > 0 && !opts.noAmpAutoTrack) {
       yield* mergeAmpThreads(ampOut, ampThreads).pipe(
         Effect.catchAll(e => Console.debug(`Thread auto-track failed: ${e}`))
       )
     }
     
     // Continue with audit...
   })

4. Add tests:

   • Detection from each env var source
   • Deduplication logic
   • Atomic write behavior
   • Opt-out mechanism
   • Silent failure on missing context

Race Condition Mitigation

• Use atomic write pattern (tmp file → rename)
• Short retry on EBUSY/EPERM errors
• Consider file locking for high-concurrency scenarios (future)

Future Enhancements

• Richer metadata: Capture actor, repo, commit, command, duration
• Per-run audit log: Separate append-only runs.log to avoid contention
• Map-based schema: O(1) dedupe with threads: { [id]: {...} }

Estimated Effort

Medium (1-3 hours for basic implementation + tests)

Related

• fix(cli): index.json should reference threads.json when threads exist #18 (threads.json in index.json)
• Thread management commands already exist