edsger 0.73.0 → 0.74.0

package/dist/commands/features/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI command: edsger features <productId> --scan-id <id>
+ *
+ * Clones every repository linked to the product, asks Claude to catalogue
+ * the user-facing features it delivers, and persists them via the
+ * product_features table. The desktop UI creates a pending feature_scans
+ * row first then invokes the CLI with --scan-id; the CLI flips status
+ * running → success/failed and writes features via the MCP toolkit.
+ */
+export interface FeaturesCliOptions {
+    scanId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runFeatures(productId: string, options: FeaturesCliOptions): Promise<void>;

package/dist/commands/features/index.js

@@ -0,0 +1,34 @@
+/**
+ * CLI command: edsger features <productId> --scan-id <id>
+ *
+ * Clones every repository linked to the product, asks Claude to catalogue
+ * the user-facing features it delivers, and persists them via the
+ * product_features table. The desktop UI creates a pending feature_scans
+ * row first then invokes the CLI with --scan-id; the CLI flips status
+ * running → success/failed and writes features via the MCP toolkit.
+ */
+import { runFeaturesPhase } from '../../phases/features/index.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+export async function runFeatures(productId, options) {
+    const { scanId, guidance, verbose } = options;
+    if (!productId) {
+        throw new Error('A product ID is required for features');
+    }
+    if (!scanId) {
+        throw new Error('--scan-id is required (the pending feature_scans row id)');
+    }
+    logInfo(`Starting features scan for product ${productId}`);
+    const result = await runFeaturesPhase({
+        productId,
+        scanId,
+        guidance,
+        verbose,
+    });
+    if (result.status === 'success') {
+        logSuccess(result.message);
+    }
+    else {
+        logError(result.message);
+        process.exit(1);
+    }
+}

package/dist/commands/pr-resolve/index.d.ts

@@ -5,7 +5,9 @@
 export interface PRResolveCliOptions {
     prUrl: string;
     prId?: string;
+    /** Repo-only mode: resolve GitHub config from a repositories row. */
+    repoId?: string;
     verbose?: boolean;
     learn?: boolean;
 }
-export declare function runPRResolve(productId: string, options: PRResolveCliOptions): Promise<void>;
+export declare function runPRResolve(productId: string | undefined, options: PRResolveCliOptions): Promise<void>;

package/dist/commands/pr-resolve/index.js

@@ -2,31 +2,36 @@
  * CLI command: edsger pr-resolve <productId> --pr-url <url>
  * Resolves PR change requests: fixes what's genuinely better, explains what it won't change.
  */
-import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, } from '../../api/github.js';
 import { resolveStandalonePR } from '../../phases/pr-resolve/index.js';
 import { logError, logInfo, logSuccess } from '../../utils/logger.js';
 export async function runPRResolve(productId, options) {
-    const { prUrl, prId, verbose } = options;
-    logInfo(`Starting PR resolve for product ${productId}`);
+    const { prUrl, prId, repoId, verbose } = options;
+    const scopeLabel = repoId ? `repository ${repoId}` : `product ${productId}`;
+    logInfo(`Starting PR resolve for ${scopeLabel}`);
     logInfo(`PR URL: ${prUrl}`);
-    // Get GitHub config via product developer settings
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    // Resolve GitHub config from the repository (repo-only mode) or the product.
+    const githubConfig = repoId
+        ? await getGitHubConfigByRepository(repoId, verbose)
+        : await getGitHubConfigByProduct(productId ?? '', verbose);
     if (!githubConfig.configured ||
         !githubConfig.token ||
         !githubConfig.owner ||
         !githubConfig.repo) {
-        logError(`GitHub not configured for product ${productId}: ${githubConfig.message || 'No installation found'}`);
+        logError(`GitHub not configured for ${scopeLabel}: ${githubConfig.message || 'No installation found'}`);
         process.exit(1);
     }
     const result = await resolveStandalonePR({
         productId,
+        repositoryId: repoId,
         pullRequestUrl: prUrl,
         githubToken: githubConfig.token,
         owner: githubConfig.owner,
         repo: githubConfig.repo,
         prId,
         verbose,
-        learn: options.learn,
+        // Checklist learning is product-scoped; skip it in repo-only mode.
+        learn: repoId ? false : options.learn,
     });
     if (result.status === 'success') {
         logSuccess(`PR resolve completed: ${result.message}`);

package/dist/commands/pr-review/index.d.ts

@@ -5,6 +5,8 @@
 export interface PRReviewCliOptions {
     prUrl: string;
     prId?: string;
+    /** Repo-only mode: resolve GitHub config from a repositories row. */
+    repoId?: string;
     verbose?: boolean;
 }
-export declare function runPRReview(productId: string, options: PRReviewCliOptions): Promise<void>;
+export declare function runPRReview(productId: string | undefined, options: PRReviewCliOptions): Promise<void>;

package/dist/commands/pr-review/index.js

@@ -2,24 +2,28 @@
  * CLI command: edsger pr-review <productId> --pr-url <url>
  * Reviews a standalone GitHub PR and posts comments.
  */
-import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, } from '../../api/github.js';
 import { reviewStandalonePR } from '../../phases/pr-review/index.js';
 import { logError, logInfo, logSuccess } from '../../utils/logger.js';
 export async function runPRReview(productId, options) {
-    const { prUrl, prId, verbose } = options;
-    logInfo(`Starting PR review for product ${productId}`);
+    const { prUrl, prId, repoId, verbose } = options;
+    const scopeLabel = repoId ? `repository ${repoId}` : `product ${productId}`;
+    logInfo(`Starting PR review for ${scopeLabel}`);
     logInfo(`PR URL: ${prUrl}`);
-    // Get GitHub config via product developer settings
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    // Resolve GitHub config from the repository (repo-only mode) or the product.
+    const githubConfig = repoId
+        ? await getGitHubConfigByRepository(repoId, verbose)
+        : await getGitHubConfigByProduct(productId ?? '', verbose);
     if (!githubConfig.configured ||
         !githubConfig.token ||
         !githubConfig.owner ||
         !githubConfig.repo) {
-        logError(`GitHub not configured for product ${productId}: ${githubConfig.message || 'No installation found'}`);
+        logError(`GitHub not configured for ${scopeLabel}: ${githubConfig.message || 'No installation found'}`);
         process.exit(1);
     }
     const result = await reviewStandalonePR({
         productId,
+        repositoryId: repoId,
         pullRequestUrl: prUrl,
         githubToken: githubConfig.token,
         owner: githubConfig.owner,

package/dist/commands/sync-github-pull-requests/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI command: `edsger sync-github-pull-requests <repoId>`
+ *
+ * Mirrors a connected GitHub repo's pull requests into the local
+ * `pull_requests` table (scoped by repository_id) for the repo detail page.
+ * Idempotent — already-synced PRs are refreshed, never duplicated.
+ */
+export interface SyncGithubPullRequestsCliOptions {
+    verbose?: boolean;
+}
+export declare function runSyncGithubPullRequests(repositoryId: string, options?: SyncGithubPullRequestsCliOptions): Promise<void>;

package/dist/commands/sync-github-pull-requests/index.js

@@ -0,0 +1,42 @@
+/**
+ * CLI command: `edsger sync-github-pull-requests <repoId>`
+ *
+ * Mirrors a connected GitHub repo's pull requests into the local
+ * `pull_requests` table (scoped by repository_id) for the repo detail page.
+ * Idempotent — already-synced PRs are refreshed, never duplicated.
+ */
+import { getGitHubConfigByRepository } from '../../api/github.js';
+import { syncGithubPullRequests } from '../../phases/sync-github-pull-requests/index.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+export async function runSyncGithubPullRequests(repositoryId, options = {}) {
+    const { verbose } = options;
+    logInfo(`Starting GitHub pull request sync for repository ${repositoryId}`);
+    const githubConfig = await getGitHubConfigByRepository(repositoryId, verbose);
+    if (!githubConfig.configured ||
+        !githubConfig.token ||
+        !githubConfig.owner ||
+        !githubConfig.repo) {
+        logError(`GitHub not configured for repository ${repositoryId}: ${githubConfig.message || 'No installation found'}`);
+        process.exit(1);
+    }
+    const result = await syncGithubPullRequests({
+        repositoryId,
+        githubToken: githubConfig.token,
+        owner: githubConfig.owner,
+        repo: githubConfig.repo,
+        verbose,
+    });
+    if (result.status === 'success') {
+        logSuccess(`GitHub PR sync completed: ${result.message}`);
+        if (result.repository) {
+            logInfo(`Repository: ${result.repository}`);
+        }
+        if (result.fetchedCount !== undefined) {
+            logInfo(`Fetched ${result.fetchedCount} · created ${result.createdCount ?? 0} · updated ${result.updatedCount ?? 0}`);
+        }
+    }
+    else {
+        logError(`GitHub PR sync failed: ${result.message}`);
+        process.exit(1);
+    }
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { runConfigGet, runConfigList, runConfigSet, runConfigUnset, } from './co
 import { runDataFlow } from './commands/data-flow/index.js';
 import { runDiscover } from './commands/discover/index.js';
 import { runErDiagram } from './commands/er-diagram/index.js';
+import { runFeatures } from './commands/features/index.js';
 import { runFinancingDeck } from './commands/financing-deck/index.js';
 import { runFindArchitecture } from './commands/find-architecture/index.js';
 import { runFindBugs } from './commands/find-bugs/index.js';
@@ -46,6 +47,7 @@ import { runStateDiagram } from './commands/state-diagram/index.js';
 import { runSyncAws } from './commands/sync-aws/index.js';
 import { runSyncDatadog } from './commands/sync-datadog/index.js';
 import { runSyncGithubIssues } from './commands/sync-github-issues/index.js';
+import { runSyncGithubPullRequests } from './commands/sync-github-pull-requests/index.js';
 import { runSyncOrgRepos } from './commands/sync-org-repos/index.js';
 import { runSyncSentryIssues } from './commands/sync-sentry-issues/index.js';
 import { runSyncTerraform } from './commands/sync-terraform/index.js';
@@ -763,13 +765,17 @@ program
 // Subcommand: edsger pr-review <productId>
 // ============================================================
 program
-    .command('pr-review <productId>')
-    .description('AI-review a GitHub PR for a product')
+    .command('pr-review [productId]')
+    .description('AI-review a GitHub PR for a product (or standalone repository)')
     .requiredOption('--pr-url <url>', 'GitHub PR URL')
     .option('--pr-id <id>', 'Pull request record ID in database')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('-v, --verbose', 'Verbose output')
     .action(async (productId, opts) => {
     try {
+        if (!productId && !opts.repoId) {
+            throw new Error('Provide a productId or --repo-id (repo-only mode) for pr-review');
+        }
         await runPRReview(productId, opts);
     }
     catch (error) {
@@ -842,6 +848,21 @@ program
     }
 });
 // ============================================================
+// Subcommand: edsger sync-github-pull-requests <repoId>
+// ============================================================
+program
+    .command('sync-github-pull-requests <repoId>')
+    .description("Mirror a connected GitHub repo's pull requests into the local pull_requests list for the repo detail page (idempotent — refreshes, never duplicates)")
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (repoId, opts) => {
+    try {
+        await runSyncGithubPullRequests(repoId, opts);
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+// ============================================================
 // Subcommand: edsger sync-org-repos <teamId>
 // ============================================================
 program
@@ -1081,17 +1102,42 @@ program
     }
 });
 // ============================================================
+// Subcommand: edsger features <productId>
+// ============================================================
+program
+    .command('features <productId>')
+    .description('Scan every repository linked to a product for the user-facing features it delivers and persist them via the product_features table. Manually defined features are enriched, never rewritten. Writes against the pending feature_scans row identified by --scan-id.')
+    .requiredOption('--scan-id <id>', 'Pending feature_scans row id to drive (created by the desktop UI before invocation)')
+    .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (productId, opts) => {
+    try {
+        await runFeatures(productId, {
+            scanId: opts.scanId,
+            guidance: opts.guidance,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        exitWithError(error);
+    }
+});
+// ============================================================
 // Subcommand: edsger pr-resolve <productId>
 // ============================================================
 program
-    .command('pr-resolve <productId>')
-    .description('AI-resolve change requests on a GitHub PR')
+    .command('pr-resolve [productId]')
+    .description('AI-resolve change requests on a GitHub PR for a product (or standalone repository)')
     .requiredOption('--pr-url <url>', 'GitHub PR URL')
     .option('--pr-id <id>', 'Pull request record ID in database')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('--no-learn', 'Skip checklist learning after resolve')
     .option('-v, --verbose', 'Verbose output')
     .action(async (productId, opts) => {
     try {
+        if (!productId && !opts.repoId) {
+            throw new Error('Provide a productId or --repo-id (repo-only mode) for pr-resolve');
+        }
         await runPRResolve(productId, opts);
     }
     catch (error) {

package/dist/phases/features/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Features phase: clone EVERY repository linked to the product
+ * (product_repositories), ask Claude to catalogue the user-facing features
+ * the product delivers, and persist them via the product_features table.
+ *
+ * Multi-repo: unlike recipes (single primary repo), features are discovered
+ * across the whole product. Repo resolution + cloning is shared with the
+ * diagram phases (cloneDiagramRepos): each repo is cloned into its own
+ * subdirectory of a per-product parent dir, and the agent runs in the
+ * parent so it can explore all of them in one pass.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop
+ * (mirrors the recipes phase):
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the feature_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/feature-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / remove as
+ *     it goes. There is no "submit at the end" buffer — partial progress
+ *     survives even if the agent later errors out.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { type ClonedRepo } from '../diagram-shared/clone-repos.js';
+import type { FeatureSummary } from './types.js';
+export interface FeaturesPhaseOptions {
+    productId: string;
+    scanId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface FeaturesPhaseResult {
+    status: 'success' | 'error' | 'cancelled';
+    message: string;
+    counts?: {
+        created: number;
+        updated: number;
+        removed: number;
+    };
+}
+/**
+ * Repo-scope note for the agent's user prompt. Unlike the diagram phases'
+ * describeRepoScope (which asks for one unified flow), this tells the agent
+ * the exact full names it may use in the `repos` field of each feature.
+ */
+export declare function describeFeatureRepoScope(repos: ClonedRepo[]): string;
+export declare function runFeaturesPhase(options: FeaturesPhaseOptions): Promise<FeaturesPhaseResult>;
+export declare function listProductRepositoryIds(supabase: SupabaseClient, productId: string): Promise<string[]>;
+export declare function getScanCreator(supabase: SupabaseClient, scanId: string): Promise<{
+    created_by: string;
+} | null>;
+export declare function listProductFeatures(supabase: SupabaseClient, productId: string): Promise<FeatureSummary[]>;
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export declare function markRunning(supabase: SupabaseClient, scanId: string): Promise<boolean>;
+export declare function heartbeat(supabase: SupabaseClient, scanId: string): Promise<void>;
+export declare function markFailed(supabase: SupabaseClient, scanId: string, errorMessage: string): Promise<boolean>;
+export declare function markSuccess(supabase: SupabaseClient, scanId: string): Promise<boolean>;

package/dist/phases/features/index.js

@@ -0,0 +1,292 @@
+/**
+ * Features phase: clone EVERY repository linked to the product
+ * (product_repositories), ask Claude to catalogue the user-facing features
+ * the product delivers, and persist them via the product_features table.
+ *
+ * Multi-repo: unlike recipes (single primary repo), features are discovered
+ * across the whole product. Repo resolution + cloning is shared with the
+ * diagram phases (cloneDiagramRepos): each repo is cloned into its own
+ * subdirectory of a per-product parent dir, and the agent runs in the
+ * parent so it can explore all of them in one pass.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop
+ * (mirrors the recipes phase):
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the feature_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/feature-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / remove as
+ *     it goes. There is no "submit at the end" buffer — partial progress
+ *     survives even if the agent later errors out.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
+import { cloneDiagramRepos, safeDirName, } from '../diagram-shared/clone-repos.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, } from '../pr-shared/agent-utils.js';
+import { createFeaturesMcpServer, createFeaturesMutationCounts, } from './mcp-server.js';
+import { createFeaturesSystemPrompt, createFeaturesUserPrompt, } from './prompts.js';
+const WORKSPACE_KEY = 'features';
+const MAX_TURNS = 200;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+// Triggered on every assistant message so a stalled agent (no messages
+// flowing) lets the row go stale and the reader can mark it failed.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+/**
+ * Repo-scope note for the agent's user prompt. Unlike the diagram phases'
+ * describeRepoScope (which asks for one unified flow), this tells the agent
+ * the exact full names it may use in the `repos` field of each feature.
+ */
+export function describeFeatureRepoScope(repos) {
+    if (repos.length === 1) {
+        return `The working directory is a clone of \`${repos[0].fullName}\`. Use that full name in the \`repos\` field.`;
+    }
+    const list = repos.map((r) => `- ${r.fullName} (subdirectory: ${safeDirName(r.fullName)})`);
+    return [
+        `This product spans ${repos.length} repositories, each cloned into its own subdirectory of the working directory:`,
+        ...list,
+        'Explore all of them. A feature implemented across several repositories is ONE feature listing every repo it touches in `repos` — do not duplicate it per repo.',
+    ].join('\n');
+}
+export async function runFeaturesPhase(options) {
+    const { productId, scanId, guidance, verbose } = options;
+    logInfo(`Starting features scan for product ${productId}`);
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, scanId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'Feature scan row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    let cleanupDir;
+    let succeeded = false;
+    try {
+        // Every repo linked to the product, in stored order. cloneDiagramRepos
+        // falls back to the product's primary repo when the list is empty
+        // (older single-repo products with no product_repositories rows).
+        const repositoryIds = await listProductRepositoryIds(supabase, productId);
+        const cloned = await cloneDiagramRepos({
+            productId,
+            repositoryIds,
+            workspaceKey: WORKSPACE_KEY,
+            verbose,
+        });
+        if (!cloned.ok) {
+            await markFailed(supabase, scanId, cloned.message);
+            return { status: 'error', message: cloned.message };
+        }
+        ;
+        ({ cleanupDir } = cloned);
+        const [basics, scanMeta, existingFeatures] = await Promise.all([
+            fetchProductBasics(productId),
+            getScanCreator(supabase, scanId),
+            listProductFeatures(supabase, productId),
+        ]);
+        if (!scanMeta) {
+            const msg = 'feature_scans row vanished mid-run; aborting';
+            await markFailed(supabase, scanId, msg);
+            return { status: 'error', message: msg };
+        }
+        const systemPrompt = createFeaturesSystemPrompt();
+        const userPrompt = createFeaturesUserPrompt({
+            productName: basics.name,
+            productDescription: basics.description,
+            guidance,
+            existingFeatures,
+            repoScopeNote: describeFeatureRepoScope(cloned.repos),
+        });
+        const counts = createFeaturesMutationCounts();
+        const mcpServer = createFeaturesMcpServer({
+            supabase,
+            productId,
+            createdBy: scanMeta.created_by,
+        }, counts, existingFeatures);
+        logInfo(`Running Claude agent to identify features across ${cloned.repos.length} repo(s)...`);
+        let lastHeartbeatAt = 0;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: cloned.projectDir,
+                mcpServers: {
+                    features: mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                extractTextFromContent(message.message?.content ?? [], verbose);
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, scanId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            if (message.subtype !== 'success') {
+                const msg = `Features scan failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, scanId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Scan was cancelled while the agent was running',
+                    counts,
+                };
+            }
+            const written = await markSuccess(supabase, scanId);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Scan was cancelled before the result could be written',
+                    counts,
+                };
+            }
+            succeeded = true;
+            const summary = `created ${counts.created}, updated ${counts.updated}, removed ${counts.removed}`;
+            logSuccess(`Features scan complete — ${summary}`);
+            return {
+                status: 'success',
+                message: `Features scan complete (${summary})`,
+                counts,
+            };
+        }
+        const msg = 'Features scan ended without a result message';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg, counts };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Features scan failed: ${errorMessage}`);
+        await markFailed(supabase, scanId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(cleanupDir);
+        }
+    }
+}
+// ============================================================================
+// DB helpers — exported for unit tests
+// ============================================================================
+export async function listProductRepositoryIds(supabase, productId) {
+    const { data, error } = await supabase
+        .from('product_repositories')
+        .select('repository_id, position')
+        .eq('product_id', productId)
+        .order('position', { ascending: true });
+    if (error || !data) {
+        return [];
+    }
+    return data.map((r) => r.repository_id);
+}
+export async function getScanCreator(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .select('created_by')
+        .eq('id', scanId)
+        .maybeSingle();
+    if (error || !data) {
+        return null;
+    }
+    return data;
+}
+export async function listProductFeatures(supabase, productId) {
+    const { data, error } = await supabase
+        .from('product_features')
+        .select('id, name, description, status, source')
+        .eq('product_id', productId)
+        .order('created_at', { ascending: true });
+    if (error || !data) {
+        return [];
+    }
+    return data;
+}
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export async function markRunning(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function heartbeat(supabase, scanId) {
+    const { error } = await supabase
+        .from('feature_scans')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', scanId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+export async function markFailed(supabase, scanId, errorMessage) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function markSuccess(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .update({
+        status: 'success',
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as success: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}