edsger 0.56.3 → 0.57.0

package/dist/phases/screen-flow/types.js

@@ -0,0 +1,66 @@
+/**
+ * Screen Flow domain types.
+ *
+ * A ScreenSchema is a structured, framework-agnostic description of one
+ * screen in a product. The CLI extracts these from source code and the
+ * desktop renders them with a unified <ScreenPreview> component — that's
+ * what gives every flow a consistent visual style regardless of the
+ * underlying app's design system.
+ *
+ * The schema deliberately stays high-level (sections, not pixels). When the
+ * agent encounters something it can't model cleanly, it falls back to
+ * `{ type: 'custom', label }` rather than guessing.
+ */
+// ============================================================================
+// Runtime validation for AI-produced extraction
+// ============================================================================
+const SCREEN_KINDS = new Set(['page', 'modal', 'drawer', 'tab', 'state']);
+const EDGE_KINDS = new Set(['navigate', 'modal', 'redirect', 'back']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isScreenSchema(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.slug !== 'string' || value.slug.length === 0)
+        return false;
+    if (typeof value.name !== 'string' || value.name.length === 0)
+        return false;
+    if (typeof value.kind !== 'string' || !SCREEN_KINDS.has(value.kind)) {
+        return false;
+    }
+    if (typeof value.layout !== 'string')
+        return false;
+    if (!Array.isArray(value.body))
+        return false;
+    return true;
+}
+function isScreenEdge(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.fromSlug !== 'string')
+        return false;
+    if (typeof value.toSlug !== 'string')
+        return false;
+    if (typeof value.triggerLabel !== 'string')
+        return false;
+    if (typeof value.kind !== 'string' || !EDGE_KINDS.has(value.kind)) {
+        return false;
+    }
+    return true;
+}
+export function isScreenFlowExtraction(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.summary !== 'string')
+        return false;
+    if (!Array.isArray(value.nodes))
+        return false;
+    if (!Array.isArray(value.edges))
+        return false;
+    if (!value.nodes.every(isScreenSchema))
+        return false;
+    if (!value.edges.every(isScreenEdge))
+        return false;
+    return true;
+}

package/dist/phases/user-psychology/agent.d.ts

@@ -0,0 +1,16 @@
+import { type EdsgerConfig } from '../../types/index.js';
+interface ParsedResult {
+    analysis?: any;
+    error?: string;
+}
+/**
+ * Parse the AI's response. Uses the shared multi-strategy extractor so
+ * we tolerate the common AI quirks:
+ *   1. ```json fenced block
+ *   2. A bare JSON object containing `"analysis"`
+ *   3. The entire response is JSON
+ * Exported for testability.
+ */
+export declare function parsePsychologyResult(responseText: string): ParsedResult;
+export declare function executeUserPsychologyQuery(currentPrompt: string, systemPrompt: string, config: EdsgerConfig, verbose?: boolean, cwd?: string): Promise<Record<string, unknown> | null>;
+export {};

package/dist/phases/user-psychology/agent.js

@@ -0,0 +1,105 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { extractJsonFromResponse } from '../../utils/json-extractor.js';
+import { logDebug, logError, logInfo } from '../../utils/logger.js';
+/**
+ * Parse the AI's response. Uses the shared multi-strategy extractor so
+ * we tolerate the common AI quirks:
+ *   1. ```json fenced block
+ *   2. A bare JSON object containing `"analysis"`
+ *   3. The entire response is JSON
+ * Exported for testability.
+ */
+export function parsePsychologyResult(responseText) {
+    const json = extractJsonFromResponse(responseText, '"analysis"');
+    if (!json) {
+        return {
+            error: 'JSON parsing failed: no JSON object containing "analysis" found in response',
+        };
+    }
+    if (json.analysis) {
+        return { analysis: json.analysis };
+    }
+    return { error: 'Invalid JSON structure (missing `analysis` key)' };
+}
+function userMessage(content) {
+    return {
+        type: 'user',
+        message: { role: 'user', content },
+    };
+}
+// eslint-disable-next-line @typescript-eslint/require-await -- async generator required by SDK interface
+async function* prompt(analysisPrompt) {
+    yield userMessage(analysisPrompt);
+}
+export async function executeUserPsychologyQuery(currentPrompt, systemPrompt, config, verbose, cwd) {
+    let lastAssistantResponse = '';
+    let structuredResult = null;
+    let turnCount = 0;
+    logInfo('Connecting to AI agent...');
+    for await (const message of query({
+        prompt: prompt(currentPrompt),
+        options: {
+            systemPrompt: {
+                type: 'preset',
+                preset: 'claude_code',
+                append: systemPrompt,
+            },
+            model: DEFAULT_MODEL,
+            maxTurns: 1000,
+            permissionMode: 'bypassPermissions',
+            ...(cwd ? { cwd } : {}),
+        },
+    })) {
+        if (verbose) {
+            logInfo(`Received message type: ${message.type}`);
+        }
+        if (message.type === 'assistant' && message.message?.content) {
+            turnCount++;
+            for (const content of message.message.content) {
+                if (content.type === 'text') {
+                    lastAssistantResponse += `${content.text}\n`;
+                    logDebug(`${content.text}`, verbose);
+                }
+                else if (content.type === 'tool_use') {
+                    const input = (content.input ?? {});
+                    const desc = input.description ?? input.command ?? 'Running...';
+                    logInfo(`[Turn ${turnCount}] ${content.name}: ${typeof desc === 'string' ? desc.slice(0, 120) : 'Running...'}`);
+                }
+            }
+        }
+        if (message.type === 'result') {
+            if (message.subtype === 'success') {
+                logInfo(`\nUser psychology analysis completed after ${turnCount} turns, parsing results...`);
+                const responseText = message.result || lastAssistantResponse;
+                const parsed = parsePsychologyResult(responseText);
+                if (parsed.error) {
+                    logError(`Failed to parse psychology result: ${parsed.error}`);
+                    structuredResult = {
+                        status: 'error',
+                        analysis_content: 'Failed to parse analysis results',
+                        target_personas: [],
+                        jobs_to_be_done: [],
+                        pain_points: [],
+                        motivations: null,
+                        behavior_triggers: [],
+                        messaging_angles: [],
+                    };
+                }
+                else {
+                    structuredResult = parsed.analysis;
+                }
+            }
+            else {
+                logError(`\nAnalysis incomplete: ${message.subtype}`);
+                if (lastAssistantResponse) {
+                    const parsed = parsePsychologyResult(lastAssistantResponse);
+                    if (!parsed.error) {
+                        structuredResult = parsed.analysis;
+                    }
+                }
+            }
+        }
+    }
+    return structuredResult;
+}

package/dist/phases/user-psychology/context.d.ts

@@ -0,0 +1,10 @@
+import { type ProductInfo } from '../../api/products.js';
+export interface UserPsychologyContext {
+    product: ProductInfo;
+}
+export declare function fetchUserPsychologyContext(productId: string, verbose?: boolean): Promise<UserPsychologyContext>;
+export declare function formatContextForPrompt(context: UserPsychologyContext, guidance?: string): string;
+export declare function prepareUserPsychologyContext(productId: string, verbose?: boolean, hasCodebase?: boolean, guidance?: string): Promise<{
+    context: UserPsychologyContext;
+    analysisPrompt: string;
+}>;

package/dist/phases/user-psychology/context.js

@@ -0,0 +1,65 @@
+import { getProduct } from '../../api/products.js';
+import { logError, logInfo } from '../../utils/logger.js';
+import { createUserPsychologyPromptWithContext } from './prompts.js';
+export async function fetchUserPsychologyContext(productId, verbose) {
+    try {
+        if (verbose) {
+            logInfo(`Fetching psychology context for product: ${productId}`);
+        }
+        const product = await getProduct(productId, verbose);
+        if (verbose) {
+            logInfo(`  Product: ${product.name}`);
+            logInfo(`  Issues: ${product.issues?.length || 0}`);
+        }
+        return { product };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Failed to fetch psychology context: ${errorMessage}`);
+        throw new Error(`Context fetch failed: ${errorMessage}`);
+    }
+}
+export function formatContextForPrompt(context, guidance) {
+    const { product } = context;
+    const issuesList = product.issues && product.issues.length > 0
+        ? product.issues
+            .map((f) => `- **${f.name}**: ${f.description || 'No description'} (Status: ${f.status || 'unknown'})`)
+            .join('\n')
+        : 'No issues listed.';
+    const guidanceSection = guidance
+        ? `
+
+## Human Research Guidance
+The product owner has provided the following direction. **You MUST honour this guidance** — it overrides your defaults for which audience segment, market, or use case to focus on.
+
+${guidance}
+
+---`
+        : '';
+    return `# User Psychology Research Context
+
+## Product Information
+- **Name**: ${product.name}
+- **Product ID**: ${product.id}
+- **Description**: ${product.description || 'No description provided'}
+
+## Product Issues / Capabilities (${product.issues?.length || 0})
+${issuesList}
+${guidanceSection}
+
+---
+
+**Important**: Build the user psychology profile for the people who would actually use the product described above. Personas, jobs-to-be-done, and pain points must be traceable to the capabilities listed — do not invent users the product cannot serve.${guidance ? ' Honour the human research guidance above.' : ''}`;
+}
+export async function prepareUserPsychologyContext(productId, verbose, hasCodebase = false, guidance) {
+    if (verbose) {
+        logInfo('Fetching user psychology context...');
+        if (guidance) {
+            logInfo(`Human guidance: "${guidance.substring(0, 80)}${guidance.length > 80 ? '...' : ''}"`);
+        }
+    }
+    const context = await fetchUserPsychologyContext(productId, verbose);
+    const contextInfo = formatContextForPrompt(context, guidance);
+    const analysisPrompt = createUserPsychologyPromptWithContext(productId, contextInfo, hasCodebase);
+    return { context, analysisPrompt };
+}

package/dist/phases/user-psychology/index.d.ts

@@ -0,0 +1,18 @@
+import { type EdsgerConfig } from '../../types/index.js';
+export interface UserPsychologyOptions {
+    productId: string;
+    /** Required. Desktop UI always reserves a pending row first. */
+    analysisId: string;
+    verbose?: boolean;
+    guidance?: string;
+}
+export interface UserPsychologyResult {
+    productId: string;
+    status: 'success' | 'error';
+    summary: string;
+    analysisId?: string;
+    personaCount: number;
+    jobCount: number;
+    painPointCount: number;
+}
+export declare const analyseUserPsychology: (options: UserPsychologyOptions, config: EdsgerConfig) => Promise<UserPsychologyResult>;

package/dist/phases/user-psychology/index.js

@@ -0,0 +1,96 @@
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { markUserPsychologyAnalysisFailed, updateUserPsychologyAnalysis, } from '../../api/user-psychology.js';
+import { logError, logInfo } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { executeUserPsychologyQuery } from './agent.js';
+import { prepareUserPsychologyContext } from './context.js';
+import { createUserPsychologySystemPrompt } from './prompts.js';
+export const analyseUserPsychology = async (options, config) => {
+    const { productId, analysisId, verbose, guidance } = options;
+    if (verbose) {
+        logInfo(`Starting user psychology analysis for product ID: ${productId}`);
+    }
+    let repoCwd;
+    let analysisSucceeded = false;
+    try {
+        // Clone product repo if GitHub is configured. The whole point of this
+        // analysis is to ground claims in the actual codebase, so we try hard
+        // but degrade gracefully if no repo is connected.
+        try {
+            const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+            if (githubConfig.configured &&
+                githubConfig.token &&
+                githubConfig.owner &&
+                githubConfig.repo) {
+                const workspaceRoot = ensureWorkspaceDir();
+                const { repoPath } = cloneIssueRepo(workspaceRoot, `psychology-${productId}`, githubConfig.owner, githubConfig.repo, githubConfig.token);
+                repoCwd = repoPath;
+                logInfo(`Repository cloned to: ${repoCwd}`);
+            }
+            else {
+                logInfo(`No GitHub repo configured for product, running without codebase access. ${githubConfig.message || ''}`);
+            }
+        }
+        catch (error) {
+            logInfo(`Could not clone repo (continuing without codebase): ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const hasCodebase = !!repoCwd;
+        const { analysisPrompt } = await prepareUserPsychologyContext(productId, verbose, hasCodebase, guidance);
+        const systemPrompt = await createUserPsychologySystemPrompt(hasCodebase, repoCwd);
+        if (verbose) {
+            logInfo('Starting AI query for user psychology analysis...');
+        }
+        const analysisResult = await executeUserPsychologyQuery(analysisPrompt, systemPrompt, config, verbose, repoCwd);
+        if (!analysisResult) {
+            throw new Error('No analysis results received');
+        }
+        const analysisContent = analysisResult.analysis_content || 'Analysis completed';
+        const targetPersonas = (analysisResult.target_personas || []);
+        const jobsToBeDone = (analysisResult.jobs_to_be_done || []);
+        const painPoints = (analysisResult.pain_points || []);
+        const motivations = (analysisResult.motivations || null);
+        const behaviorTriggers = (analysisResult.behavior_triggers ||
+            []);
+        const messagingAngles = (analysisResult.messaging_angles || []);
+        const saved = await updateUserPsychologyAnalysis(analysisId, {
+            analysis_content: analysisContent,
+            target_personas: targetPersonas,
+            jobs_to_be_done: jobsToBeDone,
+            pain_points: painPoints,
+            motivations,
+            behavior_triggers: behaviorTriggers,
+            messaging_angles: messagingAngles,
+            status: 'completed',
+        }, verbose);
+        logInfo(`Psychology analysis completed: ${targetPersonas.length} personas, ${jobsToBeDone.length} jobs, ${painPoints.length} pain points`);
+        analysisSucceeded = true;
+        return {
+            productId,
+            status: 'success',
+            summary: analysisContent,
+            analysisId: saved?.id ?? analysisId,
+            personaCount: targetPersonas.length,
+            jobCount: jobsToBeDone.length,
+            painPointCount: painPoints.length,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError(`User psychology analysis failed: ${message}`);
+        await markUserPsychologyAnalysisFailed(analysisId, message, verbose);
+        return {
+            productId,
+            status: 'error',
+            summary: `Analysis failed: ${message}`,
+            analysisId,
+            personaCount: 0,
+            jobCount: 0,
+            painPointCount: 0,
+        };
+    }
+    finally {
+        if (analysisSucceeded) {
+            cleanupIssueRepo(repoCwd);
+        }
+    }
+};

package/dist/phases/user-psychology/prompts.d.ts

@@ -0,0 +1,2 @@
+export declare const createUserPsychologySystemPrompt: (hasCodebase?: boolean, projectDir?: string) => Promise<string>;
+export declare const createUserPsychologyPromptWithContext: (productId: string, contextInfo: string, hasCodebase?: boolean) => string;

package/dist/phases/user-psychology/prompts.js

@@ -0,0 +1,41 @@
+import { processConditionals, resolveSkill, } from '../../services/skill-resolver.js';
+import { OUTPUT_CONTRACTS } from '../output-contracts.js';
+export const createUserPsychologySystemPrompt = async (hasCodebase = false, projectDir) => {
+    const skill = await resolveSkill('phase/user-psychology', { projectDir });
+    if (!skill) {
+        throw new Error('Failed to load skill: phase/user-psychology');
+    }
+    let { prompt } = skill;
+    prompt = processConditionals(prompt, { hasCodebase });
+    return `${prompt}
+
+${OUTPUT_CONTRACTS['user-psychology']}`;
+};
+export const createUserPsychologyPromptWithContext = (productId, contextInfo, hasCodebase = false) => {
+    const codebaseInstructions = hasCodebase
+        ? `
+**Step 1 - Explore the codebase FIRST**: Before writing any persona or job, use your file reading tools to actually open this project. Look at:
+- README.md, CLAUDE.md, package.json for what the product claims to be
+- Landing pages, marketing copy, documentation
+- The 3-5 highest-leverage source files / features
+- Any UI flows that hint at the user's workflow
+
+**Step 2 - Build the profile**: Now, using what you discovered AND the context below:`
+        : `
+**Build the profile**: Using the product context below:`;
+    return `Please produce a rigorous user psychology profile for product ID: ${productId}
+
+${contextInfo}
+
+## Analysis Instructions
+${codebaseInstructions}
+1. Apply all 6 frameworks defined in your system prompt (Personas, JTBD, Pain Points, Motivations, Behavior Triggers, Messaging Angles).
+2. Every persona, job, and pain you produce must be traceable to a specific feature, file, or context line — cite the evidence inline.
+3. Cover at least one EMOTIONAL and one SOCIAL job in jobs_to_be_done — not only functional ones.
+4. Pain points must be written in the USER'S voice ("I keep losing track of…"), not yours ("users struggle with…").
+5. Messaging angles must each tie back to a specific persona name and a specific JTBD statement.
+
+**CRITICAL**: No placeholders. No "[insert role]". No generic "users want to be productive." Be concrete or be silent.
+
+Return ONLY the JSON response as specified in your instructions.`;
+};

package/dist/services/audit-logs.js

@@ -3,13 +3,26 @@
  * Provides functions to log issue lifecycle events to the database
  */
 import { callMcpEndpoint } from '../api/mcp-client.js';
+import { getSupabase, hasSupabaseSession } from '../supabase/client.js';
 import { logError, logInfo } from '../utils/logger.js';
+/** Insert one row into issue_audit_logs and return its id, or null on failure. */
+async function insertAuditLogSdk(payload) {
+    const { data, error } = await getSupabase()
+        .from('issue_audit_logs')
+        .insert(payload)
+        .select('id')
+        .single();
+    if (error) {
+        throw new Error(error.message);
+    }
+    return data?.id ?? null;
+}
 /**
  * Log a phase event (start, completion, or failure)
  */
 export async function logIssuePhaseEvent(params, verbose) {
     try {
-        const result = await callMcpEndpoint('issue_audit_logs/create', {
+        const payload = {
             issue_id: params.issueId,
             event_type: params.eventType,
             phase: params.phase,
@@ -17,7 +30,22 @@ export async function logIssuePhaseEvent(params, verbose) {
             result: params.result || 'info',
             metadata: params.metadata || {},
             error_message: params.errorMessage || null,
-        });
+        };
+        let logId = null;
+        let usedSdk = false;
+        if (hasSupabaseSession()) {
+            try {
+                logId = await insertAuditLogSdk(payload);
+                usedSdk = true;
+            }
+            catch {
+                // Fall through to MCP
+            }
+        }
+        if (!usedSdk) {
+            const result = await callMcpEndpoint('issue_audit_logs/create', payload);
+            logId = result?.id || null;
+        }
         if (verbose) {
             logInfo(`✅ Logged ${params.eventType} for phase ${params.phase}`);
         }
@@ -41,7 +69,7 @@ export async function logIssuePhaseEvent(params, verbose) {
                 }
             }
         }
-        return result?.id || null;
+        return logId;
     }
     catch (error) {
         // Always log errors, not just in verbose mode
@@ -57,7 +85,7 @@ export async function logIssuePhaseEvent(params, verbose) {
  */
 export async function logIssueChecklistEvent(params, verbose) {
     try {
-        const result = await callMcpEndpoint('issue_audit_logs/create', {
+        const payload = {
             issue_id: params.issueId,
             event_type: params.eventType,
             source: 'pipeline',
@@ -66,11 +94,26 @@ export async function logIssueChecklistEvent(params, verbose) {
                 checklist_id: params.checklistId,
                 ...(params.metadata || {}),
             },
-        });
+        };
+        let logId = null;
+        let usedSdk = false;
+        if (hasSupabaseSession()) {
+            try {
+                logId = await insertAuditLogSdk(payload);
+                usedSdk = true;
+            }
+            catch {
+                // Fall through to MCP
+            }
+        }
+        if (!usedSdk) {
+            const result = await callMcpEndpoint('issue_audit_logs/create', payload);
+            logId = result?.id || null;
+        }
         if (verbose) {
             logInfo(`✅ Logged ${params.eventType} for checklist ${params.checklistId}`);
         }
-        return result?.id || null;
+        return logId;
     }
     catch (error) {
         // Always log errors, not just in verbose mode
@@ -89,7 +132,7 @@ export async function logIssueVerificationEvent(params, verbose) {
         const eventType = params.result === 'success'
             ? 'verification_passed'
             : 'verification_failed';
-        const result = await callMcpEndpoint('issue_audit_logs/create', {
+        const payload = {
             issue_id: params.issueId,
             event_type: eventType,
             phase: params.phase,
@@ -99,11 +142,26 @@ export async function logIssueVerificationEvent(params, verbose) {
                 iteration: params.iteration,
                 ...params.verificationData,
             },
-        });
+        };
+        let logId = null;
+        let usedSdk = false;
+        if (hasSupabaseSession()) {
+            try {
+                logId = await insertAuditLogSdk(payload);
+                usedSdk = true;
+            }
+            catch {
+                // Fall through to MCP
+            }
+        }
+        if (!usedSdk) {
+            const result = await callMcpEndpoint('issue_audit_logs/create', payload);
+            logId = result?.id || null;
+        }
         if (verbose) {
             logInfo(`✅ Logged verification ${params.result} for phase ${params.phase} (iteration ${params.iteration})`);
         }
-        return result?.id || null;
+        return logId;
     }
     catch (error) {
         // Always log errors, not just in verbose mode