edsger 0.68.0 → 0.70.0

package/dist/commands/sequence-diagram/index.js

@@ -0,0 +1,55 @@
+/**
+ * CLI command: edsger sequence-diagram <productId> --diagram-id <id>
+ *
+ * Traces one scenario through the product's code and maps the participants
+ * and the ordered messages between them into a structured flow stored in
+ * diagrams / diagram_nodes / diagram_edges (rows tagged type='sequence').
+ *
+ * The desktop UI creates a pending diagrams row first, then invokes the CLI
+ * with --diagram-id; the CLI flips status running → success/failed and
+ * populates the nodes/edges tables.
+ */
+import { runSequenceDiagramPhase } from '../../phases/sequence-diagram/index.js';
+import { deregisterSession, registerSession, } from '../../system/session-manager.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+export async function runSequenceDiagram(productId, options) {
+    const { diagramId, repoId, guidance, verbose } = options;
+    if (!productId && !repoId) {
+        throw new Error('Either a product ID or --repo-id is required for sequence-diagram');
+    }
+    if (!diagramId) {
+        throw new Error('--diagram-id is required (the pending diagrams row id)');
+    }
+    await registerSession({
+        command: 'sequence-diagram',
+        ...(productId ? { productId } : {}),
+    });
+    if (productId) {
+        logInfo(`Starting sequence diagram generation for product ${productId}`);
+    }
+    else {
+        logInfo(`Starting sequence diagram generation for repository ${repoId}`);
+    }
+    try {
+        const result = await runSequenceDiagramPhase({
+            productId,
+            repoId,
+            diagramId,
+            guidance,
+            verbose,
+        });
+        if (result.status === 'success') {
+            logSuccess(result.message);
+            if (result.summary) {
+                logInfo(`\nSummary: ${result.summary}`);
+            }
+        }
+        else {
+            logError(result.message);
+            process.exit(1);
+        }
+    }
+    finally {
+        await deregisterSession();
+    }
+}

package/dist/commands/state-diagram/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI command: edsger state-diagram <productId> --diagram-id <id>
+ * Maps a state machine into the diagrams tables (type='state').
+ */
+import { type DiagramCommandOptions } from '../diagram-shared/index.js';
+export type StateDiagramCliOptions = DiagramCommandOptions;
+export declare function runStateDiagram(productId: string | undefined, options: StateDiagramCliOptions): Promise<void>;

package/dist/commands/state-diagram/index.js

@@ -0,0 +1,9 @@
+/**
+ * CLI command: edsger state-diagram <productId> --diagram-id <id>
+ * Maps a state machine into the diagrams tables (type='state').
+ */
+import { runStateDiagramPhase } from '../../phases/state-diagram/index.js';
+import { runDiagramCommand, } from '../diagram-shared/index.js';
+export function runStateDiagram(productId, options) {
+    return runDiagramCommand('state-diagram', productId, options, runStateDiagramPhase);
+}

package/dist/index.js

@@ -9,17 +9,21 @@ import { runLogin, runLogout, runStatus } from './auth/login.js';
 import { runAgentWorkflow } from './commands/agent-workflow/index.js';
 import { runAnalyzeLogs } from './commands/analyze-logs/index.js';
 import { runAppStoreGeneration } from './commands/app-store/index.js';
+import { runArchitectureDiagram } from './commands/architecture-diagram/index.js';
 import { runBuild } from './commands/build/index.js';
 import { runChatServeCommand } from './commands/chat-serve/index.js';
 import { runChecklists } from './commands/checklists/index.js';
+import { runClassDiagram } from './commands/class-diagram/index.js';
 import { runCodeReview } from './commands/code-review/index.js';
 import { runConfigGet, runConfigList, runConfigSet, runConfigUnset, } from './commands/config/index.js';
 import { runDataFlow } from './commands/data-flow/index.js';
+import { runErDiagram } from './commands/er-diagram/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';
 import { runFindFeatures } from './commands/find-features/index.js';
 import { parseCategoriesOption, runFindSmells, } from './commands/find-smells/index.js';
+import { runFlowchart } from './commands/flowchart/index.js';
 import { runGrowthAnalysis } from './commands/growth-analysis/index.js';
 import { runInit } from './commands/init/index.js';
 import { runIntelligence } from './commands/intelligence/index.js';
@@ -33,9 +37,11 @@ import { runRefactor } from './commands/refactor/refactor.js';
 import { runReleaseSyncCommand } from './commands/release-sync/index.js';
 import { runRunSheetCommand } from './commands/run-sheet/index.js';
 import { runScreenFlow } from './commands/screen-flow/index.js';
+import { runSequenceDiagram } from './commands/sequence-diagram/index.js';
 import { runSessionServeCommand } from './commands/session-serve/index.js';
 import { runSessionTurnCommand } from './commands/session-turn/index.js';
 import { runSmokeTestCommand } from './commands/smoke-test/index.js';
+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';
@@ -172,15 +178,20 @@ program
 // Subcommand: edsger screen-flow <productId>
 // ============================================================
 program
-    .command('screen-flow <productId>')
-    .description('Generate a structured screen flow (screens + transitions) for a product from its source code')
-    .requiredOption('--flow-id <id>', 'Pending flows row id to populate')
+    .command('screen-flow [productId]')
+    .description('Generate a structured screen flow (screens + transitions) for a product (or standalone repository) from its source code')
+    .requiredOption('--diagram-id <id>', 'Pending diagrams row id to populate')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
     .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 screen-flow');
+        }
         await runScreenFlow(productId, {
-            flowId: opts.flowId,
+            diagramId: opts.diagramId,
+            repoId: opts.repoId,
             guidance: opts.guidance,
             verbose: opts.verbose,
         });
@@ -194,15 +205,74 @@ program
 // Subcommand: edsger data-flow <productId>
 // ============================================================
 program
-    .command('data-flow <productId>')
-    .description('Generate a structured data flow (sources, datasets, transforms, sinks, queues, models) for a product from its source code')
-    .requiredOption('--flow-id <id>', 'Pending flows row id to populate')
+    .command('data-flow [productId]')
+    .description('Generate a structured data flow (sources, datasets, transforms, sinks, queues, models) for a product (or standalone repository) from its source code')
+    .requiredOption('--diagram-id <id>', 'Pending diagrams row id to populate')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
     .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 data-flow');
+        }
         await runDataFlow(productId, {
-            flowId: opts.flowId,
+            diagramId: opts.diagramId,
+            repoId: opts.repoId,
+            guidance: opts.guidance,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
+// Subcommand: edsger er-diagram <productId>
+// ============================================================
+program
+    .command('er-diagram [productId]')
+    .description('Generate a structured entity-relationship diagram (tables, views, enums, junctions + their relationships) for a product (or standalone repository) from its schema source')
+    .requiredOption('--diagram-id <id>', 'Pending diagrams row id to populate')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
+    .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
+    .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 er-diagram');
+        }
+        await runErDiagram(productId, {
+            diagramId: opts.diagramId,
+            repoId: opts.repoId,
+            guidance: opts.guidance,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
+// Subcommand: edsger sequence-diagram <productId>
+// ============================================================
+program
+    .command('sequence-diagram [productId]')
+    .description('Generate a structured sequence diagram (participants + ordered messages for one scenario) for a product (or standalone repository) from its source code')
+    .requiredOption('--diagram-id <id>', 'Pending diagrams row id to populate')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
+    .option('-g, --guidance <text>', 'Human direction for the AI — the scenario to map (e.g. "user checkout")')
+    .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 sequence-diagram');
+        }
+        await runSequenceDiagram(productId, {
+            diagramId: opts.diagramId,
+            repoId: opts.repoId,
             guidance: opts.guidance,
             verbose: opts.verbose,
         });
@@ -212,6 +282,58 @@ program
         process.exit(1);
     }
 });
+const diagramSubcommands = [
+    {
+        name: 'state-diagram',
+        description: 'Generate a state diagram (states + transitions for one lifecycle) for a product (or standalone repository) from its source code',
+        guidance: 'Human direction for the AI — the lifecycle to map',
+        run: runStateDiagram,
+    },
+    {
+        name: 'class-diagram',
+        description: 'Generate a UML class diagram (types + relationships) for a product (or standalone repository) from its source code',
+        guidance: 'Human direction for the AI (focus areas, exclusions)',
+        run: runClassDiagram,
+    },
+    {
+        name: 'architecture-diagram',
+        description: 'Generate an architecture/component diagram (components + dependencies) for a product (or standalone repository) from its source code',
+        guidance: 'Human direction for the AI (focus areas, exclusions)',
+        run: runArchitectureDiagram,
+    },
+    {
+        name: 'flowchart',
+        description: 'Generate a flowchart (control flow of one process/function) for a product (or standalone repository) from its source code',
+        guidance: 'Human direction for the AI — the process to map',
+        run: runFlowchart,
+    },
+];
+for (const sub of diagramSubcommands) {
+    program
+        .command(`${sub.name} [productId]`)
+        .description(sub.description)
+        .requiredOption('--diagram-id <id>', 'Pending diagrams row id to populate')
+        .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
+        .option('-g, --guidance <text>', sub.guidance)
+        .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 ${sub.name}`);
+            }
+            await sub.run(productId, {
+                diagramId: opts.diagramId,
+                repoId: opts.repoId,
+                guidance: opts.guidance,
+                verbose: opts.verbose,
+            });
+        }
+        catch (error) {
+            logError(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+}
 // ============================================================
 // Subcommand: edsger user-psychology <productId>
 // ============================================================
@@ -646,10 +768,10 @@ program
 // Subcommand: edsger quality-benchmark <productId>
 // ============================================================
 program
-    .command('quality-benchmark <productId>')
-    .description("Run an industrial-grade code quality benchmark against the product's GitHub repo")
+    .command('quality-benchmark [productId]')
+    .description("Run an industrial-grade code quality benchmark against the product's (or a standalone repository's) GitHub repo")
     .option('--repo <path>', "Override the auto-clone with a local checkout (default: clone the product's repo into ~/edsger/quality-<owner>-<repo>)")
-    .option('--repo-id <id>', "Benchmark a specific linked repository (id) instead of the product's primary repo")
+    .option('--repo-id <id>', 'Benchmark a specific repository (id). With a productId, targets that linked repo; without a productId, runs in repo-only mode (no product)')
     .option('--branch <name>', 'Override the detected default branch on the report envelope')
     .option('--pkg-manager <name>', 'npm | pnpm | yarn (auto-detected if absent)')
     .option('--no-install', 'Refuse to install missing tools; mark them unmeasured')
@@ -659,7 +781,10 @@ program
     .option('-v, --verbose', 'Print every progress event')
     .action(async (productId, opts) => {
     try {
-        await runQualityBenchmarkCli(productId, opts);
+        if (!productId && !opts.repoId) {
+            throw new Error('Provide a productId or --repo-id (repo-only mode) for quality-benchmark');
+        }
+        await runQualityBenchmarkCli(productId ?? '', opts);
     }
     catch (error) {
         logError(error instanceof Error ? error.message : String(error));
@@ -888,15 +1013,20 @@ program
 // Subcommand: edsger recipes <productId>
 // ============================================================
 program
-    .command('recipes <productId>')
-    .description("Scan a product's repo for the implementation recipes it uses (which services/tools are chained together to deliver each capability) and persist them via the recipes / product_recipes tables. Writes against the pending recipe_scans row identified by --scan-id.")
+    .command('recipes [productId]')
+    .description("Scan a product's (or standalone repository's) repo for the implementation recipes it uses (which services/tools are chained together to deliver each capability) and persist them via the recipes / product_recipes (or repository_recipes) tables. Writes against the pending recipe_scans row identified by --scan-id.")
     .requiredOption('--scan-id <id>', 'Pending recipe_scans row id to drive (created by the desktop UI before invocation)')
+    .option('--repo-id <id>', 'Run in repo-only mode against a single repositories row (no product context)')
     .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
     .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 recipes');
+        }
         await runRecipes(productId, {
             scanId: opts.scanId,
+            repoId: opts.repoId,
             guidance: opts.guidance,
             verbose: opts.verbose,
         });

package/dist/phases/architecture-diagram/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * architecture-diagram phase: map a component/dependency diagram (C4-ish) —
+ * the modules / services / packages / datastores / external systems that make
+ * up the product and how they depend on one another. Persisted to the
+ * diagrams tables with `type = 'architecture'`.
+ */
+import { type DiagramPhaseResult } from '../diagram-shared/generate.js';
+export interface ArchitectureDiagramPhaseOptions {
+    productId?: string;
+    repoId?: string;
+    diagramId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runArchitectureDiagramPhase(options: ArchitectureDiagramPhaseOptions): Promise<DiagramPhaseResult>;

package/dist/phases/architecture-diagram/index.js

@@ -0,0 +1,51 @@
+/**
+ * architecture-diagram phase: map a component/dependency diagram (C4-ish) —
+ * the modules / services / packages / datastores / external systems that make
+ * up the product and how they depend on one another. Persisted to the
+ * diagrams tables with `type = 'architecture'`.
+ */
+import { z } from 'zod';
+import { generateDiagram, } from '../diagram-shared/generate.js';
+import { buildDiagramSystemPrompt, buildDiagramUserPrompt, } from '../diagram-shared/prompts.js';
+const archNode = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['module', 'service', 'package', 'ui', 'datastore', 'external']),
+    file: z.string().optional(),
+    description: z.string().optional(),
+    tech: z.string().optional(),
+    responsibilities: z.array(z.string()).optional(),
+});
+const archEdge = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum(['depends-on', 'calls', 'imports', 'data']),
+    label: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function runArchitectureDiagramPhase(options) {
+    return generateDiagram({
+        ...options,
+        workspaceKey: 'architecture-diagram',
+        fenceName: 'architecture_diagram',
+        nounPlural: 'components',
+        edgeNounPlural: 'dependencies',
+        mcpConfig: {
+            name: 'architecture-diagram',
+            toolName: 'architecture_diagram',
+            summaryDescribe: '1-3 sentence narrative of the system architecture and its main building blocks.',
+            nodesSchema: z.array(archNode),
+            nodesDescribe: 'Every component: module / service / package / ui / datastore / external. slug MUST be unique.',
+            edgesSchema: z.array(archEdge),
+            edgesDescribe: 'Dependencies. kind = depends-on / calls / imports / data. fromSlug is the depender. Endpoints MUST reference emitted components.',
+        },
+        buildSystemPrompt: (a) => buildDiagramSystemPrompt('phase/architecture-diagram', 'architecture-diagram', a),
+        buildUserPrompt: (a) => buildDiagramUserPrompt({
+            ...a,
+            task: 'Map the architecture (component & dependency) diagram for',
+            mcpName: 'architecture-diagram',
+            toolName: 'architecture_diagram',
+            process: 'Detect the stack and the top-level structure (workspaces/packages, service boundaries, top-level src dirs, deployment units). Treat each meaningful unit as a component of the right kind (a UI/front-end, backend services, internal modules/packages, datastores, third-party/external systems). Wire dependency edges from the import graph, cross-service calls, and datastore/external access. Aim for a readable ~10-25 components — group leaf files into their module; do not draw a file-level graph.',
+        }),
+    });
+}

package/dist/phases/class-diagram/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * class-diagram phase: map a UML class diagram — classes / interfaces / enums
+ * with their members, and the inheritance / composition / association edges
+ * between them. Persisted to the diagrams tables with `type = 'class'`.
+ */
+import { type DiagramPhaseResult } from '../diagram-shared/generate.js';
+export interface ClassDiagramPhaseOptions {
+    productId?: string;
+    repoId?: string;
+    diagramId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runClassDiagramPhase(options: ClassDiagramPhaseOptions): Promise<DiagramPhaseResult>;

package/dist/phases/class-diagram/index.js

@@ -0,0 +1,76 @@
+/**
+ * class-diagram phase: map a UML class diagram — classes / interfaces / enums
+ * with their members, and the inheritance / composition / association edges
+ * between them. Persisted to the diagrams tables with `type = 'class'`.
+ */
+import { z } from 'zod';
+import { generateDiagram, } from '../diagram-shared/generate.js';
+import { buildDiagramSystemPrompt, buildDiagramUserPrompt, } from '../diagram-shared/prompts.js';
+const visibility = z.enum(['public', 'private', 'protected']);
+const classNode = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['class', 'interface', 'abstract', 'enum']),
+    file: z.string().optional(),
+    description: z.string().optional(),
+    stereotype: z.string().optional(),
+    attributes: z
+        .array(z.object({
+        name: z.string(),
+        type: z.string().optional(),
+        visibility: visibility.optional(),
+        isStatic: z.boolean().optional(),
+    }))
+        .optional(),
+    methods: z
+        .array(z.object({
+        name: z.string(),
+        params: z.string().optional(),
+        returnType: z.string().optional(),
+        visibility: visibility.optional(),
+        isStatic: z.boolean().optional(),
+        isAbstract: z.boolean().optional(),
+    }))
+        .optional(),
+});
+const classEdge = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum([
+        'inheritance',
+        'implementation',
+        'composition',
+        'aggregation',
+        'association',
+        'dependency',
+    ]),
+    /** Role name or multiplicity, e.g. "1..*", "owns". */
+    label: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function runClassDiagramPhase(options) {
+    return generateDiagram({
+        ...options,
+        workspaceKey: 'class-diagram',
+        fenceName: 'class_diagram',
+        nounPlural: 'classes',
+        edgeNounPlural: 'relationships',
+        mcpConfig: {
+            name: 'class-diagram',
+            toolName: 'class_diagram',
+            summaryDescribe: '1-3 sentence narrative of the core types and how they relate.',
+            nodesSchema: z.array(classNode),
+            nodesDescribe: 'Every class / interface / abstract / enum with its key attributes and methods. slug MUST be unique.',
+            edgesSchema: z.array(classEdge),
+            edgesDescribe: 'Relationships. kind = inheritance / implementation / composition / aggregation / association / dependency. fromSlug is the child / owner / dependent side. Endpoints MUST reference emitted classes.',
+        },
+        buildSystemPrompt: (a) => buildDiagramSystemPrompt('phase/class-diagram', 'class-diagram', a),
+        buildUserPrompt: (a) => buildDiagramUserPrompt({
+            ...a,
+            task: 'Map a UML class diagram for',
+            mcpName: 'class-diagram',
+            toolName: 'class_diagram',
+            process: 'Detect the language/OO model, then map the core domain types — classes, interfaces, abstract base types, enums — capturing each one\'s defining attributes and methods (visibility + static/abstract where it matters; you need not list every member of huge types). Wire edges: `inheritance` (extends), `implementation` (implements), `composition`/`aggregation` (owns/holds), `association` (references), `dependency` (uses). Prefer the ~30 most important types if there are many.',
+        }),
+    });
+}

package/dist/phases/data-flow/index.d.ts

@@ -2,7 +2,7 @@
  * data-flow phase: clone the product's repo, ask Claude to map every data
  * node (source / dataset / transform / sink / queue / model) and the
  * connections between them into a structured DataFlowExtraction, then
- * persist the result to flows / flow_nodes / flow_edges (rows tagged
+ * persist the result to diagrams / diagram_nodes / diagram_edges (rows tagged
  * `type = 'data'`) via the Supabase SDK.
  *
  * Companion to screen-flow: same generation pattern (workspace clone +
@@ -10,8 +10,11 @@
  * domain.
  */
 export interface DataFlowPhaseOptions {
-    productId: string;
-    flowId: string;
+    /** Product-scoped flow. Mutually exclusive with `repoId`. */
+    productId?: string;
+    /** Repo-only flow: a single repositories row, no product context. */
+    repoId?: string;
+    diagramId: string;
     guidance?: string;
     verbose?: boolean;
 }