@soleri/core 9.0.4 → 9.3.0

package/src/runtime/github-integration.ts

@@ -0,0 +1,162 @@
+/**
+ * GitHub integration helpers for the planning lifecycle.
+ *
+ * Provides lightweight wrappers around git and the `gh` CLI for:
+ *   - Detecting the GitHub remote from a project path
+ *   - Extracting issue numbers from text
+ *   - Closing issues with a comment
+ *   - Fetching issue details
+ *
+ * All functions degrade gracefully — if `gh` is not installed or not
+ * authenticated, they return null / no-op instead of throwing.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GitHubRemote {
+  owner: string;
+  repo: string;
+}
+
+export interface GitHubIssueDetails {
+  title: string;
+  body: string;
+  labels: string[];
+}
+
+// ---------------------------------------------------------------------------
+// detectGitHubRemote
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the GitHub owner/repo from the git remote in a project directory.
+ * Parses both HTTPS and SSH remote URLs.
+ * Returns null if not a git repo or no GitHub remote found.
+ */
+export async function detectGitHubRemote(projectPath: string): Promise<GitHubRemote | null> {
+  try {
+    const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], {
+      cwd: projectPath,
+      timeout: 10_000,
+      signal: AbortSignal.timeout(10_000),
+    });
+    return parseRemoteUrl(stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a GitHub owner/repo from a remote URL.
+ * Supports HTTPS and SSH formats.
+ */
+export function parseRemoteUrl(url: string): GitHubRemote | null {
+  // HTTPS: https://github.com/owner/repo.git
+  const https = url.match(/github\.com\/([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (https) return { owner: https[1], repo: https[2] };
+
+  // SSH: git@github.com:owner/repo.git
+  const ssh = url.match(/github\.com:([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (ssh) return { owner: ssh[1], repo: ssh[2] };
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// extractIssueNumber
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a GitHub issue number (#NNN) from arbitrary text.
+ * Matches patterns like "#123", "issue #456", "fixes #789", "closes #42".
+ * Returns the first match, or null if none found.
+ */
+export function extractIssueNumber(text: string): number | null {
+  const match = text.match(/#(\d+)/);
+  if (!match) return null;
+  const num = parseInt(match[1], 10);
+  return Number.isFinite(num) ? num : null;
+}
+
+// ---------------------------------------------------------------------------
+// getIssueDetails
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch issue details (title, body, labels) using the `gh` CLI.
+ * Returns null if `gh` is not available or the issue cannot be fetched.
+ */
+export async function getIssueDetails(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+): Promise<GitHubIssueDetails | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      'gh',
+      [
+        'issue',
+        'view',
+        String(issueNumber),
+        '--repo',
+        `${owner}/${repo}`,
+        '--json',
+        'title,body,labels',
+      ],
+      {
+        timeout: 10_000,
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      title: string;
+      body: string;
+      labels: Array<{ name: string }>;
+    };
+    return {
+      title: parsed.title,
+      body: parsed.body ?? '',
+      labels: (parsed.labels ?? []).map((l) => l.name),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// closeIssueWithComment
+// ---------------------------------------------------------------------------
+
+/**
+ * Close a GitHub issue and leave a comment summarizing what was done.
+ * No-ops gracefully if `gh` is not available.
+ */
+export async function closeIssueWithComment(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  comment: string,
+): Promise<void> {
+  const repoSlug = `${owner}/${repo}`;
+  try {
+    // Add comment first, then close
+    await execFileAsync(
+      'gh',
+      ['issue', 'comment', String(issueNumber), '--repo', repoSlug, '--body', comment],
+      { timeout: 10_000, signal: AbortSignal.timeout(10_000) },
+    );
+    await execFileAsync('gh', ['issue', 'close', String(issueNumber), '--repo', repoSlug], {
+      timeout: 10_000,
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch {
+    // Graceful degradation — gh not available or auth expired
+  }
+}

package/src/runtime/grading-ops.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createGradingOps } from './grading-ops.js';
+import type { AgentRuntime } from './types.js';
+import type { OpDefinition } from '../facades/types.js';
+
+function makeMockRuntime() {
+  return {
+    planner: {
+      grade: vi.fn().mockReturnValue({
+        grade: 'B',
+        score: 82,
+        iteration: 1,
+        gaps: [
+          {
+            severity: 'major',
+            category: 'scope',
+            description: 'Missing scope',
+            recommendation: 'Add scope',
+            location: 'plan.scope',
+          },
+          {
+            severity: 'minor',
+            category: 'detail',
+            description: 'Low detail',
+            recommendation: 'Add detail',
+          },
+          {
+            severity: 'critical',
+            category: 'risk',
+            description: 'No risk analysis',
+            recommendation: 'Add risks',
+          },
+        ],
+      }),
+      getCheckHistory: vi.fn().mockReturnValue([
+        { grade: 'C', score: 70, iteration: 1 },
+        { grade: 'B', score: 82, iteration: 2 },
+      ]),
+      getLatestCheck: vi.fn().mockReturnValue({ grade: 'B', score: 82, iteration: 2 }),
+      meetsGrade: vi.fn().mockReturnValue({ meets: true, currentScore: 92, threshold: 90 }),
+    },
+  } as unknown as AgentRuntime;
+}
+
+describe('createGradingOps', () => {
+  let ops: OpDefinition[];
+  let runtime: ReturnType<typeof makeMockRuntime>;
+
+  function findOp(name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  it('returns 5 ops', () => {
+    runtime = makeMockRuntime();
+    ops = createGradingOps(runtime);
+    expect(ops).toHaveLength(5);
+  });
+
+  it('has correct op names', () => {
+    runtime = makeMockRuntime();
+    ops = createGradingOps(runtime);
+    const names = ops.map((o) => o.name);
+    expect(names).toEqual([
+      'plan_grade',
+      'plan_check_history',
+      'plan_latest_check',
+      'plan_meets_grade',
+      'plan_auto_improve',
+    ]);
+  });
+
+  it('all ops have read auth', () => {
+    runtime = makeMockRuntime();
+    ops = createGradingOps(runtime);
+    for (const op of ops) {
+      expect(op.auth).toBe('read');
+    }
+  });
+
+  describe('plan_grade', () => {
+    it('delegates to planner.grade', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = await findOp('plan_grade').handler({ planId: 'p1' });
+      expect(runtime.planner.grade).toHaveBeenCalledWith('p1');
+      expect(result).toHaveProperty('grade', 'B');
+    });
+  });
+
+  describe('plan_check_history', () => {
+    it('returns count and checks array', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_check_history').handler({ planId: 'p1' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.planId).toBe('p1');
+      expect(result.count).toBe(2);
+      expect(result.checks).toHaveLength(2);
+    });
+  });
+
+  describe('plan_latest_check', () => {
+    it('returns the latest check', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = await findOp('plan_latest_check').handler({ planId: 'p1' });
+      expect(result).toHaveProperty('grade', 'B');
+    });
+
+    it('returns message when no checks found', async () => {
+      runtime = makeMockRuntime();
+      (runtime.planner.getLatestCheck as ReturnType<typeof vi.fn>).mockReturnValue(null);
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_latest_check').handler({ planId: 'p1' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.message).toBe('No checks found for this plan.');
+    });
+  });
+
+  describe('plan_meets_grade', () => {
+    it('delegates to planner.meetsGrade', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = await findOp('plan_meets_grade').handler({ planId: 'p1', targetGrade: 'A' });
+      expect(runtime.planner.meetsGrade).toHaveBeenCalledWith('p1', 'A');
+      expect(result).toHaveProperty('meets', true);
+    });
+  });
+
+  describe('plan_auto_improve', () => {
+    it('sorts gaps by severity and groups them', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_auto_improve').handler({ planId: 'p1' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.grade).toBe('B');
+      expect(result.score).toBe(82);
+      expect(result.totalGaps).toBe(3);
+      expect(result.nextAction).toBe('iterate');
+
+      const grouped = result.gapsBySeverity as Record<string, unknown[]>;
+      expect(grouped.critical).toHaveLength(1);
+      expect(grouped.major).toHaveLength(1);
+      expect(grouped.minor).toHaveLength(1);
+    });
+
+    it('returns approve as nextAction when score >= 90', async () => {
+      runtime = makeMockRuntime();
+      (runtime.planner.grade as ReturnType<typeof vi.fn>).mockReturnValue({
+        grade: 'A',
+        score: 92,
+        iteration: 3,
+        gaps: [],
+      });
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_auto_improve').handler({ planId: 'p1' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.nextAction).toBe('approve');
+      expect(result.totalGaps).toBe(0);
+    });
+  });
+});

package/src/runtime/grading-ops.ts

@@ -22,7 +22,7 @@ export function createGradingOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'plan_grade',
       description:
-        'Grade a plan using 7-pass gap analysis — severity-weighted scoring (critical=30, major=15, minor=2) with substance bonuses for vault-informed depth. Returns grade, score, gaps with recommendations, and iteration number.',
+        'Grade a plan using 8-pass gap analysis — severity-weighted scoring (critical=30, major=15, minor=2) with substance bonuses for vault-informed depth. Includes alternative analysis (pass 8) — plans without alternatives cap at ~85. Returns grade, score, gaps with recommendations, and iteration number.',
       auth: 'read',
       schema: z.object({
         planId: z.string().describe('The plan ID to grade.'),

package/src/runtime/intake-ops.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createIntakeOps } from './intake-ops.js';
+import type { OpDefinition } from '../facades/types.js';
+
+function makeMockPipeline() {
+  return {
+    ingestBook: vi.fn().mockResolvedValue({ jobId: 'j1', chunks: 5 }),
+    processChunks: vi.fn().mockResolvedValue({ processed: 3, stored: 2 }),
+    getJob: vi.fn().mockReturnValue({ id: 'j1', status: 'active' }),
+    getChunks: vi.fn().mockReturnValue([{ id: 'c1' }, { id: 'c2' }]),
+    listJobs: vi.fn().mockReturnValue([{ id: 'j1' }, { id: 'j2' }]),
+    preview: vi.fn().mockResolvedValue({ items: [{ text: 'sample' }] }),
+  };
+}
+
+function makeMockTextIngester() {
+  return {
+    ingestUrl: vi.fn().mockResolvedValue({ ingested: 3, duplicates: 1 }),
+    ingestText: vi.fn().mockResolvedValue({ ingested: 2, duplicates: 0 }),
+    ingestBatch: vi.fn().mockResolvedValue({ total: 4, ingested: 3, duplicates: 1 }),
+  };
+}
+
+describe('createIntakeOps', () => {
+  function findOp(ops: OpDefinition[], name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  it('returns 7 ops', () => {
+    const ops = createIntakeOps(makeMockPipeline() as never);
+    expect(ops).toHaveLength(7);
+  });
+
+  it('has all expected op names', () => {
+    const ops = createIntakeOps(makeMockPipeline() as never);
+    const names = ops.map((o) => o.name);
+    expect(names).toEqual([
+      'intake_ingest_book',
+      'intake_process',
+      'intake_status',
+      'intake_preview',
+      'ingest_url',
+      'ingest_text',
+      'ingest_batch',
+    ]);
+  });
+
+  describe('when pipeline is null', () => {
+    it('intake_ingest_book returns error', async () => {
+      const ops = createIntakeOps(null);
+      const result = (await findOp(ops, 'intake_ingest_book').handler({
+        pdfPath: '/test.pdf',
+        title: 'T',
+        domain: 'd',
+      })) as Record<string, unknown>;
+      expect(result.error).toBe('Intake pipeline not configured');
+    });
+
+    it('intake_process returns error', async () => {
+      const ops = createIntakeOps(null);
+      const result = (await findOp(ops, 'intake_process').handler({ jobId: 'j1' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.error).toBe('Intake pipeline not configured');
+    });
+
+    it('intake_status returns error', async () => {
+      const ops = createIntakeOps(null);
+      const result = (await findOp(ops, 'intake_status').handler({})) as Record<string, unknown>;
+      expect(result.error).toBe('Intake pipeline not configured');
+    });
+
+    it('intake_preview returns error', async () => {
+      const ops = createIntakeOps(null);
+      const result = (await findOp(ops, 'intake_preview').handler({
+        pdfPath: '/x.pdf',
+        title: 'T',
+        domain: 'd',
+        pageStart: 1,
+        pageEnd: 5,
+      })) as Record<string, unknown>;
+      expect(result.error).toBe('Intake pipeline not configured');
+    });
+  });
+
+  describe('when textIngester is null', () => {
+    it('ingest_url returns error', async () => {
+      const ops = createIntakeOps(makeMockPipeline() as never, null);
+      const result = (await findOp(ops, 'ingest_url').handler({
+        url: 'https://example.com',
+      })) as Record<string, unknown>;
+      expect(result.error).toContain('Text ingester not configured');
+    });
+
+    it('ingest_text returns error', async () => {
+      const ops = createIntakeOps(makeMockPipeline() as never, null);
+      const result = (await findOp(ops, 'ingest_text').handler({
+        text: 'hello',
+        title: 'T',
+      })) as Record<string, unknown>;
+      expect(result.error).toContain('Text ingester not configured');
+    });
+
+    it('ingest_batch returns error', async () => {
+      const ops = createIntakeOps(makeMockPipeline() as never, null);
+      const result = (await findOp(ops, 'ingest_batch').handler({
+        items: [{ text: 'a', title: 'A' }],
+      })) as Record<string, unknown>;
+      expect(result.error).toContain('Text ingester not configured');
+    });
+  });
+
+  describe('intake_ingest_book', () => {
+    it('delegates to pipeline.ingestBook', async () => {
+      const pipeline = makeMockPipeline();
+      const ops = createIntakeOps(pipeline as never);
+      const result = await findOp(ops, 'intake_ingest_book').handler({
+        pdfPath: '/book.pdf',
+        title: 'My Book',
+        domain: 'design',
+        author: 'Author',
+        chunkPageSize: 15,
+        tags: ['tag1'],
+      });
+      expect(pipeline.ingestBook).toHaveBeenCalledWith({
+        pdfPath: '/book.pdf',
+        title: 'My Book',
+        domain: 'design',
+        author: 'Author',
+        chunkPageSize: 15,
+        tags: ['tag1'],
+      });
+      expect(result).toEqual({ jobId: 'j1', chunks: 5 });
+    });
+  });
+
+  describe('intake_process', () => {
+    it('delegates to pipeline.processChunks', async () => {
+      const pipeline = makeMockPipeline();
+      const ops = createIntakeOps(pipeline as never);
+      await findOp(ops, 'intake_process').handler({ jobId: 'j1', count: 3 });
+      expect(pipeline.processChunks).toHaveBeenCalledWith('j1', 3);
+    });
+  });
+
+  describe('intake_status', () => {
+    it('returns job and chunks when jobId provided', async () => {
+      const pipeline = makeMockPipeline();
+      const ops = createIntakeOps(pipeline as never);
+      const result = (await findOp(ops, 'intake_status').handler({ jobId: 'j1' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.job).toEqual({ id: 'j1', status: 'active' });
+      expect(result.chunks).toHaveLength(2);
+    });
+
+    it('returns error when job not found', async () => {
+      const pipeline = makeMockPipeline();
+      pipeline.getJob.mockReturnValue(null);
+      const ops = createIntakeOps(pipeline as never);
+      const result = (await findOp(ops, 'intake_status').handler({ jobId: 'missing' })) as Record<
+        string,
+        unknown
+      >;
+      expect(result.error).toContain('Job not found');
+    });
+
+    it('lists all jobs when no jobId', async () => {
+      const pipeline = makeMockPipeline();
+      const ops = createIntakeOps(pipeline as never);
+      const result = (await findOp(ops, 'intake_status').handler({})) as Record<string, unknown>;
+      expect(result.jobs).toHaveLength(2);
+    });
+  });
+
+  describe('intake_preview', () => {
+    it('delegates to pipeline.preview', async () => {
+      const pipeline = makeMockPipeline();
+      const ops = createIntakeOps(pipeline as never);
+      await findOp(ops, 'intake_preview').handler({
+        pdfPath: '/x.pdf',
+        title: 'T',
+        domain: 'd',
+        pageStart: 1,
+        pageEnd: 10,
+      });
+      expect(pipeline.preview).toHaveBeenCalledWith(
+        { pdfPath: '/x.pdf', title: 'T', domain: 'd' },
+        1,
+        10,
+      );
+    });
+  });
+
+  describe('ingest_url', () => {
+    it('delegates to textIngester.ingestUrl', async () => {
+      const ingester = makeMockTextIngester();
+      const ops = createIntakeOps(makeMockPipeline() as never, ingester as never);
+      const result = await findOp(ops, 'ingest_url').handler({
+        url: 'https://example.com',
+        domain: 'test',
+        tags: ['t1'],
+      });
+      expect(ingester.ingestUrl).toHaveBeenCalledWith('https://example.com', {
+        domain: 'test',
+        tags: ['t1'],
+      });
+      expect(result).toEqual({ ingested: 3, duplicates: 1 });
+    });
+  });
+
+  describe('ingest_text', () => {
+    it('delegates to textIngester.ingestText with source', async () => {
+      const ingester = makeMockTextIngester();
+      const ops = createIntakeOps(makeMockPipeline() as never, ingester as never);
+      await findOp(ops, 'ingest_text').handler({
+        text: 'content',
+        title: 'My Notes',
+        sourceType: 'transcript',
+        url: 'https://x.com',
+        author: 'A',
+        domain: 'd',
+        tags: ['t'],
+      });
+      expect(ingester.ingestText).toHaveBeenCalledWith(
+        'content',
+        { type: 'transcript', title: 'My Notes', url: 'https://x.com', author: 'A' },
+        { domain: 'd', tags: ['t'] },
+      );
+    });
+  });
+
+  describe('ingest_batch', () => {
+    it('delegates to textIngester.ingestBatch', async () => {
+      const ingester = makeMockTextIngester();
+      const ops = createIntakeOps(makeMockPipeline() as never, ingester as never);
+      await findOp(ops, 'ingest_batch').handler({
+        items: [
+          { text: 'a', title: 'A', sourceType: 'article', domain: 'x' },
+          { text: 'b', title: 'B' },
+        ],
+      });
+      expect(ingester.ingestBatch).toHaveBeenCalledWith([
+        {
+          text: 'a',
+          source: { type: 'article', title: 'A', url: undefined, author: undefined },
+          opts: { domain: 'x', tags: undefined },
+        },
+        {
+          text: 'b',
+          source: { type: 'notes', title: 'B', url: undefined, author: undefined },
+          opts: { domain: undefined, tags: undefined },
+        },
+      ]);
+    });
+  });
+});