@soleri/core 9.0.4 → 9.3.0

package/src/planning/gap-types.ts

@@ -15,9 +15,11 @@ export type GapCategory =
   | 'clarity'
   | 'semantic-quality'
   | 'knowledge-depth'
+  | 'alternative-analysis'
   | 'tool-feasibility'
   | 'flow-alignment'
-  | 'anti-pattern';
+  | 'anti-pattern'
+  | 'rationalization';
 
 export interface PlanGap {
   id: string;
@@ -48,6 +50,7 @@ export const SEVERITY_WEIGHTS: Record<GapSeverity, number> = {
  */
 export const CATEGORY_PENALTY_CAPS: Record<string, number> = {
   clarity: 10,
+  'alternative-analysis': 15,
 };
 
 /**

package/src/planning/github-projection.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseGitHubRemote,
+  findMatchingMilestone,
+  findDuplicateIssue,
+  formatIssueBody,
+} from './github-projection.js';
+import type { GitHubMilestone, GitHubIssue, PlanMetadataForIssue } from './github-projection.js';
+
+describe('github-projection', () => {
+  // ─── parseGitHubRemote ──────────────────────────────────────────
+
+  describe('parseGitHubRemote', () => {
+    it('should parse HTTPS remote', () => {
+      const result = parseGitHubRemote('https://github.com/adrozdenko/deckforge.git');
+      expect(result).toEqual({ owner: 'adrozdenko', repo: 'deckforge' });
+    });
+
+    it('should parse HTTPS remote without .git suffix', () => {
+      const result = parseGitHubRemote('https://github.com/adrozdenko/deckforge');
+      expect(result).toEqual({ owner: 'adrozdenko', repo: 'deckforge' });
+    });
+
+    it('should parse SSH remote', () => {
+      const result = parseGitHubRemote('git@github.com:adrozdenko/deckforge.git');
+      expect(result).toEqual({ owner: 'adrozdenko', repo: 'deckforge' });
+    });
+
+    it('should parse SSH remote without .git suffix', () => {
+      const result = parseGitHubRemote('git@github.com:adrozdenko/deckforge');
+      expect(result).toEqual({ owner: 'adrozdenko', repo: 'deckforge' });
+    });
+
+    it('should return null for non-GitHub URLs', () => {
+      expect(parseGitHubRemote('https://gitlab.com/user/repo.git')).toBeNull();
+      expect(parseGitHubRemote('https://bitbucket.org/user/repo.git')).toBeNull();
+    });
+
+    it('should return null for invalid URLs', () => {
+      expect(parseGitHubRemote('')).toBeNull();
+      expect(parseGitHubRemote('not a url')).toBeNull();
+    });
+
+    it('should handle repos with hyphens and dots', () => {
+      const result = parseGitHubRemote('https://github.com/org-name/my-repo.js.git');
+      expect(result).toEqual({ owner: 'org-name', repo: 'my-repo.js' });
+    });
+  });
+
+  // ─── findMatchingMilestone ──────────────────────────────────────
+
+  describe('findMatchingMilestone', () => {
+    const milestones: GitHubMilestone[] = [
+      { number: 1, title: 'Phase 1: Auth + Persistence', state: 'open' },
+      { number: 2, title: 'Phase 2: UI Components', state: 'open' },
+      { number: 3, title: 'Phase 3: API Integration', state: 'closed' },
+    ];
+
+    it('should find matching milestone by word overlap', () => {
+      const match = findMatchingMilestone('Auth and Persistence', milestones);
+      expect(match).toBeDefined();
+      expect(match!.number).toBe(1);
+    });
+
+    it('should find second milestone', () => {
+      const match = findMatchingMilestone('UI Components redesign', milestones);
+      expect(match).toBeDefined();
+      expect(match!.number).toBe(2);
+    });
+
+    it('should skip closed milestones', () => {
+      const match = findMatchingMilestone('API Integration', milestones);
+      expect(match).toBeNull();
+    });
+
+    it('should return null for no match', () => {
+      const match = findMatchingMilestone('Completely unrelated topic', milestones);
+      expect(match).toBeNull();
+    });
+
+    it('should return null for empty milestones', () => {
+      const match = findMatchingMilestone('Something', []);
+      expect(match).toBeNull();
+    });
+  });
+
+  // ─── findDuplicateIssue ─────────────────────────────────────────
+
+  describe('findDuplicateIssue', () => {
+    const issues: GitHubIssue[] = [
+      { number: 10, title: 'Add user authentication flow', state: 'open' },
+      { number: 11, title: 'Fix login timeout error', state: 'open' },
+      { number: 12, title: 'Implement dark mode toggle', state: 'open' },
+    ];
+
+    it('should detect duplicate by title similarity', () => {
+      const dup = findDuplicateIssue('Implement user authentication flow', issues);
+      expect(dup).toBeDefined();
+      expect(dup!.number).toBe(10);
+    });
+
+    it('should return null for unique task', () => {
+      const dup = findDuplicateIssue('Add payment processing', issues);
+      expect(dup).toBeNull();
+    });
+
+    it('should return null for empty issues list', () => {
+      const dup = findDuplicateIssue('Something', []);
+      expect(dup).toBeNull();
+    });
+
+    it('should handle short titles gracefully', () => {
+      const dup = findDuplicateIssue('Fix', issues);
+      expect(dup).toBeNull(); // "Fix" alone is too short (< 3 chars filtered)
+    });
+  });
+
+  // ─── formatIssueBody ───────────────────────────────────────────
+
+  describe('formatIssueBody', () => {
+    const planMeta: PlanMetadataForIssue = {
+      planId: 'plan-123456-abc',
+      grade: 'A+',
+      score: 100,
+      objective: 'Build user authentication',
+      decisions: [
+        'Use JWT tokens for session management',
+        { decision: 'OAuth2 for third-party', rationale: 'Industry standard, wide support' },
+      ],
+      tasks: [
+        { id: 'task-1', title: 'Design auth schema', description: 'Create DB tables' },
+        {
+          id: 'task-2',
+          title: 'Implement login',
+          description: 'Login endpoint',
+          dependsOn: ['task-1'],
+        },
+      ],
+    };
+
+    it('should include plan ID and grade', () => {
+      const body = formatIssueBody(planMeta, 'Design auth schema', 'Create DB tables');
+      expect(body).toContain('`plan-123456-abc`');
+      expect(body).toContain('Grade: A+');
+      expect(body).toContain('100/100');
+    });
+
+    it('should include objective', () => {
+      const body = formatIssueBody(planMeta, 'Design auth schema', 'Create DB tables');
+      expect(body).toContain('Build user authentication');
+    });
+
+    it('should include string decisions', () => {
+      const body = formatIssueBody(planMeta, 'Design auth schema', 'Create DB tables');
+      expect(body).toContain('Use JWT tokens');
+    });
+
+    it('should include structured decisions with rationale', () => {
+      const body = formatIssueBody(planMeta, 'Design auth schema', 'Create DB tables');
+      expect(body).toContain('OAuth2 for third-party');
+      expect(body).toContain('Industry standard');
+    });
+
+    it('should include task table', () => {
+      const body = formatIssueBody(planMeta, 'Design auth schema', 'Create DB tables');
+      expect(body).toContain('| task-1 |');
+      expect(body).toContain('| task-2 |');
+      expect(body).toContain('task-1'); // dependency
+    });
+
+    it('should include task description', () => {
+      const body = formatIssueBody(planMeta, 'Design auth schema', 'Create DB tables');
+      expect(body).toContain('Create DB tables');
+    });
+
+    it('should handle plan with no decisions', () => {
+      const meta = { ...planMeta, decisions: [] };
+      const body = formatIssueBody(meta, 'Test', 'Desc');
+      expect(body).not.toContain('## Decisions');
+    });
+  });
+});

package/src/planning/github-projection.ts

@@ -0,0 +1,446 @@
+/**
+ * GitHub Projection — auto-link Ernesto plans to GitHub issues.
+ *
+ * After plan_split (tasks defined), the agent can detect a GitHub repo
+ * and project plan tasks as GitHub issues with plan metadata linked.
+ *
+ * The plan is the source of truth; GitHub issues are the projection.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GitHubRepo {
+  owner: string;
+  repo: string;
+}
+
+export interface GitHubMilestone {
+  number: number;
+  title: string;
+  state: string;
+}
+
+export interface GitHubIssue {
+  number: number;
+  title: string;
+  state: string;
+  body?: string;
+}
+
+export interface GitHubLabel {
+  name: string;
+  color?: string;
+}
+
+export interface GitHubContext {
+  repo: GitHubRepo;
+  authenticated: boolean;
+  milestones: GitHubMilestone[];
+  existingIssues: GitHubIssue[];
+  labels: GitHubLabel[];
+}
+
+export interface GitHubProjection {
+  repo: string;
+  milestone?: number;
+  issues: Array<{
+    taskId: string;
+    issueNumber: number;
+  }>;
+  projectedAt: number;
+}
+
+export interface ProjectedIssue {
+  taskId: string;
+  issueNumber: number;
+  issueUrl: string;
+}
+
+// ---------------------------------------------------------------------------
+// Git remote detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a GitHub owner/repo from a git remote URL.
+ * Supports HTTPS (github.com/owner/repo.git) and SSH (git@github.com:owner/repo.git).
+ */
+export function parseGitHubRemote(remoteUrl: string): GitHubRepo | null {
+  // HTTPS: https://github.com/owner/repo.git
+  const httpsMatch = remoteUrl.match(/github\.com\/([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (httpsMatch) {
+    return { owner: httpsMatch[1], repo: httpsMatch[2] };
+  }
+
+  // SSH: git@github.com:owner/repo.git
+  const sshMatch = remoteUrl.match(/github\.com:([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (sshMatch) {
+    return { owner: sshMatch[1], repo: sshMatch[2] };
+  }
+
+  return null;
+}
+
+/**
+ * Detect the GitHub remote from a project directory.
+ * Returns null if no GitHub remote found or not a git repo.
+ */
+export function detectGitHubRemote(projectPath: string): GitHubRepo | null {
+  try {
+    const output = execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return parseGitHubRemote(output);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the `gh` CLI is authenticated.
+ */
+export function isGhAuthenticated(): boolean {
+  try {
+    execFileSync('gh', ['auth', 'status'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GitHub API helpers (via `gh` CLI)
+// ---------------------------------------------------------------------------
+
+/**
+ * List milestones for a GitHub repo.
+ */
+export function listMilestones(repo: GitHubRepo): GitHubMilestone[] {
+  try {
+    const output = execFileSync(
+      'gh',
+      [
+        'api',
+        `repos/${repo.owner}/${repo.repo}/milestones`,
+        '--jq',
+        '.[] | {number, title, state}',
+      ],
+      {
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    ).trim();
+
+    if (!output) return [];
+
+    // gh --jq outputs one JSON object per line
+    return output
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as GitHubMilestone);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List open issues for a GitHub repo.
+ */
+export function listOpenIssues(repo: GitHubRepo, limit: number = 100): GitHubIssue[] {
+  try {
+    const output = execFileSync(
+      'gh',
+      [
+        'issue',
+        'list',
+        '--repo',
+        `${repo.owner}/${repo.repo}`,
+        '--state',
+        'open',
+        '--limit',
+        String(limit),
+        '--json',
+        'number,title,state,body',
+      ],
+      {
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    ).trim();
+
+    if (!output) return [];
+    return JSON.parse(output) as GitHubIssue[];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List labels for a GitHub repo.
+ */
+export function listLabels(repo: GitHubRepo): GitHubLabel[] {
+  try {
+    const output = execFileSync(
+      'gh',
+      ['label', 'list', '--repo', `${repo.owner}/${repo.repo}`, '--json', 'name,color'],
+      {
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    ).trim();
+
+    if (!output) return [];
+    return JSON.parse(output) as GitHubLabel[];
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Full context detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect full GitHub context for a project.
+ * Returns null if not a GitHub project or gh CLI not available.
+ */
+export function detectGitHubContext(projectPath: string): GitHubContext | null {
+  const repo = detectGitHubRemote(projectPath);
+  if (!repo) return null;
+
+  const authenticated = isGhAuthenticated();
+  if (!authenticated) return null;
+
+  const milestones = listMilestones(repo);
+  const existingIssues = listOpenIssues(repo);
+  const labels = listLabels(repo);
+
+  return { repo, authenticated, milestones, existingIssues, labels };
+}
+
+// ---------------------------------------------------------------------------
+// Milestone matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the best matching milestone by name similarity.
+ * Uses simple word overlap scoring.
+ */
+export function findMatchingMilestone(
+  phaseName: string,
+  milestones: GitHubMilestone[],
+): GitHubMilestone | null {
+  if (milestones.length === 0) return null;
+
+  const phaseWords = new Set(phaseName.toLowerCase().split(/\s+/));
+
+  let bestMatch: GitHubMilestone | null = null;
+  let bestScore = 0;
+
+  for (const ms of milestones) {
+    if (ms.state !== 'open') continue;
+    const msWords = ms.title.toLowerCase().split(/\s+/);
+    let overlap = 0;
+    for (const w of msWords) {
+      if (phaseWords.has(w)) overlap++;
+    }
+    const score = overlap / Math.max(phaseWords.size, msWords.length);
+    if (score > bestScore && score > 0.2) {
+      bestScore = score;
+      bestMatch = ms;
+    }
+  }
+
+  return bestMatch;
+}
+
+// ---------------------------------------------------------------------------
+// Duplicate detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Find an existing issue that likely covers the same task.
+ * Uses title similarity (word overlap).
+ */
+export function findDuplicateIssue(
+  taskTitle: string,
+  existingIssues: GitHubIssue[],
+): GitHubIssue | null {
+  const taskWords = new Set(
+    taskTitle
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 2),
+  );
+
+  for (const issue of existingIssues) {
+    const issueWords = issue.title
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 2);
+    let overlap = 0;
+    for (const w of issueWords) {
+      if (taskWords.has(w)) overlap++;
+    }
+    const score = overlap / Math.max(taskWords.size, issueWords.length, 1);
+    if (score >= 0.5) return issue;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Issue body formatting
+// ---------------------------------------------------------------------------
+
+export interface PlanMetadataForIssue {
+  planId: string;
+  grade: string;
+  score: number;
+  objective: string;
+  decisions: Array<string | { decision: string; rationale: string }>;
+  tasks: Array<{
+    id: string;
+    title: string;
+    description: string;
+    dependsOn?: string[];
+  }>;
+}
+
+/**
+ * Format an issue body with plan metadata.
+ */
+export function formatIssueBody(
+  plan: PlanMetadataForIssue,
+  taskTitle: string,
+  taskDescription: string,
+): string {
+  const lines: string[] = [];
+
+  lines.push(`## Ernesto Plan: \`${plan.planId}\` (Grade: ${plan.grade}, ${plan.score}/100)`);
+  lines.push('');
+  lines.push(`**Objective:** ${plan.objective}`);
+  lines.push('');
+
+  if (plan.decisions.length > 0) {
+    lines.push('## Decisions');
+    for (const d of plan.decisions) {
+      if (typeof d === 'string') {
+        lines.push(`- ${d}`);
+      } else {
+        lines.push(`- **${d.decision}** — ${d.rationale}`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('## Task');
+  lines.push(taskDescription);
+  lines.push('');
+
+  lines.push('## All Plan Tasks');
+  lines.push('| # | Task | Depends On |');
+  lines.push('|---|------|------------|');
+  for (const t of plan.tasks) {
+    const deps = t.dependsOn?.join(', ') || '—';
+    lines.push(`| ${t.id} | ${t.title} | ${deps} |`);
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Issue creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a GitHub issue using the `gh` CLI.
+ * Returns the issue number, or null on failure.
+ */
+export function createGitHubIssue(
+  repo: GitHubRepo,
+  title: string,
+  body: string,
+  options?: {
+    milestone?: number;
+    labels?: string[];
+  },
+): number | null {
+  try {
+    const args = [
+      'issue',
+      'create',
+      '--repo',
+      `${repo.owner}/${repo.repo}`,
+      '--title',
+      title,
+      '--body',
+      body,
+    ];
+
+    if (options?.milestone) {
+      args.push('--milestone', String(options.milestone));
+    }
+
+    if (options?.labels && options.labels.length > 0) {
+      args.push('--label', options.labels.join(','));
+    }
+
+    const output = execFileSync('gh', args, {
+      encoding: 'utf-8',
+      timeout: 15000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    // gh issue create returns the issue URL: https://github.com/owner/repo/issues/123
+    const match = output.match(/\/issues\/(\d+)/);
+    return match ? parseInt(match[1], 10) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update an existing GitHub issue body (for linking plans to existing issues).
+ */
+export function updateGitHubIssueBody(
+  repo: GitHubRepo,
+  issueNumber: number,
+  body: string,
+): boolean {
+  try {
+    execFileSync(
+      'gh',
+      [
+        'issue',
+        'edit',
+        '--repo',
+        `${repo.owner}/${repo.repo}`,
+        String(issueNumber),
+        '--body',
+        body,
+      ],
+      {
+        encoding: 'utf-8',
+        timeout: 15000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}