coaia-visualizer 1.5.10 → 1.6.0

package/lib/github-provenance.ts

@@ -0,0 +1,316 @@
+import type { EntityRecord, RelationRecord } from "./types"
+
+export const GITHUB_SYNC_STATES = ["synced", "diverged", "conflict", "project-only", "chart-only"] as const
+
+export type GithubSyncState = (typeof GITHUB_SYNC_STATES)[number]
+
+export interface GithubIssueRef {
+  owner: string
+  repo: string
+  number: number
+  nodeId?: string
+  url?: string
+}
+
+export interface GithubProjectItemRef {
+  projectOwner?: string
+  projectNumber?: number
+  projectTitle?: string
+  itemId?: string
+  projectId?: string
+  url?: string
+  fields?: Record<string, unknown>
+  fieldValues?: Record<string, unknown>
+  projectFields?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export interface GithubSourceProvenance {
+  system?: string
+  toolName?: string
+  sessionId?: string
+  createdAt?: string
+  version?: string
+  [key: string]: unknown
+}
+
+export interface GithubEntityProvenance {
+  issue?: GithubIssueRef
+  projectItems: GithubProjectItemRef[]
+  syncState?: GithubSyncState
+  lastSyncedAt?: string
+  source?: GithubSourceProvenance
+  hasGithubMetadata: boolean
+}
+
+export interface GithubProjectFieldEntry {
+  key: string
+  label: string
+  value: string
+}
+
+export const GITHUB_PROJECT_FIELD_KEYS = [
+  "goal",
+  "current_reality",
+  "observations",
+  "question",
+  "Status",
+  "phase",
+  "session_id",
+  "four_dir_east",
+  "four_dir_south",
+  "four_dir_west",
+  "four_dir_north",
+  "relational_assessed",
+  "relational_principles",
+] as const
+
+export const GITHUB_BRIDGE_RELATION_TYPES = ["synced_to_github", "linked_to_issue", "project_lens_of"] as const
+
+export type GithubBridgeRelationType = (typeof GITHUB_BRIDGE_RELATION_TYPES)[number]
+
+const PROJECT_FIELD_LABELS: Record<string, string> = {
+  goal: "goal",
+  current_reality: "current reality",
+  observations: "observations",
+  question: "question",
+  Status: "Status",
+  phase: "phase",
+  session_id: "session",
+  four_dir_east: "East",
+  four_dir_south: "South",
+  four_dir_west: "West",
+  four_dir_north: "North",
+  relational_assessed: "relational assessed",
+  relational_principles: "relational principles",
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim()
+    }
+  }
+}
+
+function firstNumber(...values: unknown[]): number | undefined {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value
+    }
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number(value)
+      if (Number.isFinite(parsed)) {
+        return parsed
+      }
+    }
+  }
+}
+
+function normalizeIssueCandidate(candidate: unknown): GithubIssueRef | undefined {
+  if (!isRecord(candidate)) return undefined
+
+  const owner = firstString(candidate.owner, candidate.ownerLogin, candidate.repositoryOwner)
+  const repo = firstString(candidate.repo, candidate.repository, candidate.repositoryName)
+  const number = firstNumber(candidate.number, candidate.issue_number, candidate.issueNumber, candidate.issue)
+
+  if (!owner || !repo || !number) return undefined
+
+  return {
+    owner,
+    repo,
+    number,
+    nodeId: firstString(candidate.nodeId, candidate.node_id),
+    url: firstString(candidate.url, candidate.html_url) ?? `https://github.com/${owner}/${repo}/issues/${number}`,
+  }
+}
+
+function normalizeProjectItemCandidate(candidate: unknown, fallbackOwner?: string): GithubProjectItemRef | undefined {
+  if (!isRecord(candidate)) return undefined
+
+  const projectOwner = firstString(candidate.projectOwner, candidate.owner, candidate.ownerLogin, fallbackOwner)
+  const projectNumber = firstNumber(candidate.projectNumber, candidate.project_number, candidate.number)
+  const itemId = firstString(candidate.itemId, candidate.item_id, candidate.projectItemId, candidate.project_id)
+  const projectId = firstString(candidate.projectId, candidate.project_id)
+  const projectTitle = firstString(candidate.projectTitle, candidate.title, candidate.project)
+  const url = firstString(candidate.url)
+
+  if (!projectOwner && !projectNumber && !itemId && !projectId && !projectTitle && !url) {
+    return undefined
+  }
+
+  return {
+    ...candidate,
+    projectOwner,
+    projectNumber,
+    projectTitle,
+    itemId,
+    projectId,
+    url,
+  }
+}
+
+export function getGithubIssueRef(entity?: EntityRecord): GithubIssueRef | undefined {
+  if (!entity) return undefined
+
+  const metadata = entity.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const syncTarget = isRecord(metadata.sync_target) ? metadata.sync_target : undefined
+  const githubRef = isRecord(metadata.github_ref) ? metadata.github_ref : undefined
+
+  return normalizeIssueCandidate(github?.issue) ?? normalizeIssueCandidate(syncTarget) ?? normalizeIssueCandidate(githubRef)
+}
+
+export function getGithubProjectItems(entity?: EntityRecord): GithubProjectItemRef[] {
+  if (!entity) return []
+
+  const metadata = entity.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const syncTarget = isRecord(metadata.sync_target) ? metadata.sync_target : undefined
+  const fallbackOwner = getGithubIssueRef(entity)?.owner
+
+  if (Array.isArray(github?.projectItems)) {
+    return github.projectItems
+      .map((item) => normalizeProjectItemCandidate(item, fallbackOwner))
+      .filter((item): item is GithubProjectItemRef => Boolean(item))
+  }
+
+  const canonicalProjectItem = normalizeProjectItemCandidate(github?.projectItem, fallbackOwner)
+  if (canonicalProjectItem) {
+    return [canonicalProjectItem]
+  }
+
+  const legacyProjectItem = normalizeProjectItemCandidate(syncTarget, fallbackOwner)
+  return legacyProjectItem ? [legacyProjectItem] : []
+}
+
+export function getGithubSyncState(entityOrMetadata?: EntityRecord | Record<string, unknown>): GithubSyncState | undefined {
+  const metadata =
+    entityOrMetadata && "metadata" in entityOrMetadata && isRecord(entityOrMetadata.metadata)
+      ? entityOrMetadata.metadata
+      : entityOrMetadata
+
+  if (!isRecord(metadata)) return undefined
+
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const syncState = github?.syncState ?? metadata.syncState
+
+  return typeof syncState === "string" && GITHUB_SYNC_STATES.includes(syncState as GithubSyncState)
+    ? (syncState as GithubSyncState)
+    : undefined
+}
+
+export function getGithubSource(entity?: EntityRecord): GithubSourceProvenance | undefined {
+  if (!entity) return undefined
+
+  const source = entity.metadata?.source
+  return isRecord(source) ? (source as GithubSourceProvenance) : undefined
+}
+
+export function getGithubEntityProvenance(entity?: EntityRecord): GithubEntityProvenance {
+  const metadata = entity?.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const issue = getGithubIssueRef(entity)
+  const projectItems = getGithubProjectItems(entity)
+  const syncTarget = isRecord(metadata.sync_target) ? metadata.sync_target : undefined
+  const githubRef = isRecord(metadata.github_ref) ? metadata.github_ref : undefined
+  const source = getGithubSource(entity)
+
+  return {
+    issue,
+    projectItems,
+    syncState: getGithubSyncState(entity),
+    lastSyncedAt: firstString(github?.lastSyncedAt, metadata.lastSyncedAt),
+    source,
+    hasGithubMetadata:
+      Boolean(github) ||
+      Boolean(syncTarget) ||
+      Boolean(githubRef) ||
+      source?.system === "coaia-github" ||
+      Boolean(issue) ||
+      projectItems.length > 0,
+  }
+}
+
+export function formatGithubIssueRef(issue?: GithubIssueRef): string | undefined {
+  if (!issue) return undefined
+  return `${issue.owner}/${issue.repo}#${issue.number}`
+}
+
+export function formatProjectItemRef(projectItem?: GithubProjectItemRef): string | undefined {
+  if (!projectItem) return undefined
+
+  if (projectItem.projectOwner && projectItem.projectNumber) {
+    return `${projectItem.projectOwner}/${projectItem.projectNumber}`
+  }
+
+  return projectItem.projectTitle || projectItem.itemId || projectItem.projectId || projectItem.url
+}
+
+export function getProjectFieldEntries(
+  entity: EntityRecord | undefined,
+  projectItem?: GithubProjectItemRef,
+): GithubProjectFieldEntry[] {
+  const metadata = entity?.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const sources = [
+    projectItem?.fields,
+    projectItem?.fieldValues,
+    projectItem?.projectFields,
+    github?.fields,
+    github?.fieldValues,
+    github?.projectFields,
+    metadata,
+    github,
+  ].filter(isRecord)
+
+  return GITHUB_PROJECT_FIELD_KEYS.flatMap((key) => {
+    for (const source of sources) {
+      if (!(key in source)) continue
+      const value = stringifyFieldValue(source[key])
+      if (value) {
+        return [{ key, label: PROJECT_FIELD_LABELS[key], value }]
+      }
+    }
+    return []
+  })
+}
+
+export function getGithubBridgeRelationType(relation: RelationRecord): GithubBridgeRelationType | undefined {
+  const relationType = relation.relationType
+  if (GITHUB_BRIDGE_RELATION_TYPES.includes(relationType as GithubBridgeRelationType)) {
+    return relationType as GithubBridgeRelationType
+  }
+
+  const metadata = relation.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const context = firstString(
+    metadata.context,
+    metadata.relation,
+    metadata.relationName,
+    metadata.semanticType,
+    github?.context,
+    github?.relation,
+  )
+
+  return GITHUB_BRIDGE_RELATION_TYPES.includes(context as GithubBridgeRelationType)
+    ? (context as GithubBridgeRelationType)
+    : undefined
+}
+
+function stringifyFieldValue(value: unknown): string | undefined {
+  if (value === null || value === undefined) return undefined
+  if (typeof value === "string") return value.trim() || undefined
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  if (Array.isArray(value)) {
+    const rendered = value.map(stringifyFieldValue).filter(Boolean).join(", ")
+    return rendered || undefined
+  }
+  if (isRecord(value)) {
+    return firstString(value.name, value.text, value.value, value.title, value.label) ?? JSON.stringify(value)
+  }
+}

package/lib/types.ts

@@ -3,7 +3,14 @@
 export interface EntityRecord {
   type: "entity"
   name: string
-  entityType: "structural_tension_chart" | "desired_outcome" | "current_reality" | "action_step" | "narrative_beat"
+  entityType:
+    | "structural_tension_chart"
+    | "desired_outcome"
+    | "current_reality"
+    | "action_step"
+    | "narrative_beat"
+    | "custom"
+    | (string & {})
   observations: string[]
   metadata: Record<string, any>
 }
@@ -12,7 +19,13 @@ export interface RelationRecord {
   type: "relation"
   from: string
   to: string
-  relationType: "contains" | "creates_tension_with" | "advances_toward" | "documents"
+  relationType:
+    | "contains"
+    | "creates_tension_with"
+    | "advances_toward"
+    | "documents"
+    | "custom"
+    | (string & {})
   metadata: Record<string, any>
 }
 

package/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coaia-visualizer",
-  "version": "1.5.10",
+  "version": "1.6.0",
   "private": false,
   "type": "module",
   "main": "./index.tsx",
@@ -9,6 +9,7 @@
     ".": "./index.tsx",
     "./lib/types": "./lib/types.ts",
     "./lib/jsonl-parser": "./lib/jsonl-parser.ts",
+    "./lib/github-provenance": "./lib/github-provenance.ts",
     "./lib/utils": "./lib/utils.ts",
     "./hooks/*": "./hooks/*.ts",
     "./components/*": "./components/*.tsx",
@@ -18,6 +19,30 @@
   "bin": {
     "coaia-visualizer": "dist/cli.js"
   },
+  "files": [
+    "app/**/*",
+    "components/**/*",
+    "dist/**/*",
+    "hooks/**/*",
+    "lib/**/*",
+    "mcp/**/*",
+    "public/**/*",
+    "rispecs/**/*",
+    "styles/**/*",
+    "cli.ts",
+    "index.tsx",
+    "next-env.d.ts",
+    "next.config.mjs",
+    "postcss.config.mjs",
+    "Dockerfile",
+    "Dockerfile.app",
+    "docker-build-push.sh",
+    "docker-entrypoint.sh",
+    "mcp-config.json",
+    "README.md",
+    "KINSHIP.md",
+    "NAMING.md"
+  ],
   "scripts": {
     "build": "next build",
     "build:cli": "tsc cli.ts --outDir dist --module esnext --target es2022 --moduleResolution bundler --esModuleInterop --skipLibCheck",
@@ -27,6 +52,7 @@
     "start": "next start",
     "test": "playwright test",
     "test:global-cli": "playwright test test-scripts/test-global-cli.spec.ts",
+    "verify:github-provenance": "node --experimental-strip-types test-scripts/verify-github-provenance.mjs",
     "docker:build": "docker build -t jgwill/coaia:visualizer .",
     "docker:push": "docker push jgwill/coaia:visualizer",
     "docker:build-push": "npm run docker:build && npm run docker:push",

package/.coaia/jgwill-coaia-visualizer.jsonl

@@ -1,6 +0,0 @@
-{"type":"entity","name":"chart_1770523106343_chart","entityType":"structural_tension_chart","observations":["Chart created for jgwill/coaia-visualizer on 2026-02-08T03:58:26.343Z"],"metadata":{"chartId":"chart_1770523106343","repository":"jgwill/coaia-visualizer","level":0,"createdAt":"2026-02-08T03:58:26.343Z","updatedAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"entity","name":"chart_1770523106343_desired_outcome","entityType":"desired_outcome","observations":["Successful development and collaboration on jgwill/coaia-visualizer"],"metadata":{"chartId":"chart_1770523106343","createdAt":"2026-02-08T03:58:26.343Z","updatedAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"entity","name":"chart_1770523106343_current_reality","entityType":"current_reality","observations":["Repository initialized with STC bot integration","[2026-02-08T03:58:26.404Z] @stcissue triggered: Issue #8 - LIVE_MODE_DESIGN.md (issues.opened)","[2026-02-08T04:38:12.548Z] @stcissue triggered: Issue #8 - Live Narrative Witness Mode (issues.edited)","[2026-02-12T04:05:37.474Z] @stcissue triggered: Issue #9 - file watching issue (issues.opened)","[2026-02-18T19:29:54.244Z] @stcissue triggered: Issue #10 - Containerization (issues.opened)"],"metadata":{"chartId":"chart_1770523106343","createdAt":"2026-02-08T03:58:26.343Z","updatedAt":"2026-02-18T19:29:54.244Z"}}
-{"type":"relation","from":"chart_1770523106343_chart","to":"chart_1770523106343_desired_outcome","relationType":"contains","metadata":{"createdAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"relation","from":"chart_1770523106343_chart","to":"chart_1770523106343_current_reality","relationType":"contains","metadata":{"createdAt":"2026-02-08T03:58:26.343Z"}}
-{"type":"relation","from":"chart_1770523106343_current_reality","to":"chart_1770523106343_desired_outcome","relationType":"creates_tension_with","metadata":{"createdAt":"2026-02-08T03:58:26.343Z"}}

package/.dockerignore

@@ -1,9 +0,0 @@
-node_modules
-dist
-.next
-.git
-.env.local
-.env*.local
-test-results
-*.log
-.DS_Store

package/COMPLETE_IMPLEMENTATION_REPORT.md

@@ -1,215 +0,0 @@
-# ✅ Telescoped Chart Navigation - FINAL IMPLEMENTATION
-
-## Summary
-
-Successfully implemented **telescoped chart navigation with proper UI placement** in the action hover toolbar.
-
-## The Correct Implementation
-
-### What You See Now
-
-When viewing a chart's **Action Steps** section:
-
-1. **Hover over any action** to reveal the toolbar (right side)
-2. **For telescoped charts**, you'll see these icons in the toolbar:
-   - 👁️ **Eye icon** (Telescope) - Opens the chart ← **THIS IS THE KEY**
-   - 📅 **Calendar icon** - Edit due date
-   - ✏️ **Pencil icon** - Edit description
-   - 🗑️ **Trash icon** - Delete
-
-3. **Visual indicators**:
-   - "📊 Chart" badge next to action number
-   - Gradient background (subtle primary color)
-   - Colored border that brightens on hover
-   - Shadow appears on hover
-
-### Action Toolbar Layout
-
-\`\`\`
-┌──────────────────────────────────────────────────────────┐
-│ ○ Action 1  📊 Chart                                     │
-│   Fix chart-editor to create telescoped charts          │
-│                              [👁] [📅] [✏️] [🗑️] ← Hover │
-└──────────────────────────────────────────────────────────┘
-                               ↑
-                         Telescope icon!
-\`\`\`
-
-## How To Use
-
-### Step 1: Identify Telescoped Charts
-Look for the **"📊 Chart"** badge next to the action number.
-
-### Step 2: Hover Over the Action
-Move your mouse over the action card to reveal the toolbar on the right.
-
-### Step 3: Click the Eye Icon 👁️
-The **Eye icon** (first in the toolbar) opens the telescoped chart.
-
-### Step 4: Navigate the Chart
-You're now viewing the action as a full structural tension chart:
-- **"← Back to Parent Chart"** button at the top
-- Full chart editor (desired outcome, current reality, actions)
-- Can add sub-actions (creates Level 2 charts)
-
-## Technical Implementation
-
-### Files Modified
-
-**components/edit-action-step.tsx**:
-\`\`\`typescript
-// Added Eye icon to hover toolbar (line ~97)
-{isTelescopedChart && onNavigateToChart && (
-  <Button
-    variant="ghost"
-    size="sm"
-    className="h-7 px-2 text-primary hover:text-primary hover:bg-primary/10"
-    onClick={onNavigateToChart}
-    title="Open telescoped chart"
-  >
-    <Eye className="w-4 h-4" />
-  </Button>
-)}
-\`\`\`
-
-**Placement**: First button in the hover toolbar, before Calendar/Pencil/Trash
-
-**Visual Design**:
-- Primary color text (stands out)
-- Primary/10 background on hover
-- Size: w-4 h-4 (slightly larger than other icons for prominence)
-- Title tooltip: "Open telescoped chart"
-
-### Navigation Stack
-
-**app/page.tsx**:
-- `chartNavigationStack: Chart[]` - Tracks navigation history
-- `handleNavigateToSubChart()` - Pushes current, navigates to sub-chart
-- `handleNavigateBack()` - Pops from stack, returns to parent
-
-**components/chart-detail-editable.tsx**:
-- Finds sub-chart matching the action
-- Passes `onNavigateToChart` callback to EditActionStep
-- Shows "← Back" button when viewing sub-charts
-
-## Testing Results
-
-✅ **Automated Tests** (Playwright):
-- Found 2 Eye icons (telescope) in hover toolbar
-- Successfully clicked Eye icon
-- Navigated to sub-chart (back button appeared)
-- Navigation works correctly
-
-✅ **Build Status**:
-- TypeScript: Zero errors
-- Next.js: Production build successful
-- Version: 1.4.0
-
-✅ **Visual Verification**:
-- Screenshots confirm Eye icon appears in toolbar
-- Icon is properly styled (primary color)
-- Hover state works correctly
-- Navigation successful
-
-## Design Specifications
-
-### Icon Order in Toolbar
-1. 👁️ **Eye** (Telescope) - Only for telescoped charts
-2. 📅 **Calendar** - Due date
-3. ✏️ **Pencil** - Edit description
-4. 🗑️ **Trash** - Delete
-
-### Color Coding
-- **Eye icon**: `text-primary` (blue/theme color)
-- **Eye hover**: `hover:bg-primary/10` (subtle highlight)
-- Other icons: Default ghost button styling
-
-### Size & Spacing
-- **All toolbar icons**: `h-7 px-2` (consistent)
-- **Eye icon size**: `w-4 h-4` (slightly larger for emphasis)
-- **Toolbar gap**: `gap-1` (tight spacing)
-- **Opacity**: `opacity-0 group-hover:opacity-100` (reveal on hover)
-
-## User Experience
-
-### Visual Hierarchy
-1. **Badge first**: "📊 Chart" immediately identifies telescoped charts
-2. **Gradient + border**: Card stands out visually
-3. **Hover reveals tools**: Toolbar appears smoothly on hover
-4. **Eye icon first**: Positioned first in toolbar for prominence
-5. **Primary color**: Eye icon uses primary color to stand out
-
-### Interaction Flow
-\`\`\`
-1. User sees action with "📊 Chart" badge
-   ↓
-2. User hovers over action
-   ↓
-3. Toolbar appears with Eye icon first
-   ↓
-4. User clicks Eye icon
-   ↓
-5. Navigate to full chart view
-   ↓
-6. User works in chart (edit, add actions)
-   ↓
-7. User clicks "← Back to Parent Chart"
-   ↓
-8. Return to previous level
-\`\`\`
-
-## Comparison: Before vs After
-
-### Before (WRONG)
-- ❌ "Open" button below text (out of sight)
-- ❌ Not in the toolbar where users expect tools
-- ❌ Easy to miss
-
-### After (CORRECT)
-- ✅ Eye icon in hover toolbar (with other tools)
-- ✅ Consistent with Calendar/Pencil/Trash placement
-- ✅ Primary color makes it stand out
-- ✅ Tooltips explain functionality
-- ✅ Positioned first in toolbar
-
-## Accessibility
-
-✅ **Keyboard Navigation**: Tab through actions, reach toolbar buttons
-✅ **Focus Indicators**: Visible focus rings on all buttons
-✅ **Tooltips**: "Open telescoped chart" on hover
-✅ **Icons + Semantic HTML**: Proper button elements
-✅ **Color Contrast**: Primary color meets WCAG standards
-
-## Mobile Responsive
-
-✅ **Touch Targets**: All toolbar buttons ≥44px touch target
-✅ **Hover Alternative**: On mobile, toolbar always visible on telescoped charts
-✅ **Icon Size**: Large enough for easy tapping
-✅ **Spacing**: Adequate gap between toolbar buttons
-
-## Known Issues
-
-None. All functionality verified and working correctly.
-
-## Future Enhancements
-
-- [ ] Keyboard shortcut to open telescoped chart (e.g., Enter when focused)
-- [ ] Breadcrumb trail showing full navigation path
-- [ ] Visual tree view of chart hierarchy
-- [ ] Quick preview on hover (tooltip with chart summary)
-
-## Conclusion
-
-The telescope functionality is now **correctly placed in the action hover toolbar** alongside other action tools (Calendar, Edit, Delete). The Eye icon provides:
-
-✅ **Discoverability**: In the toolbar where users expect action tools
-✅ **Visual Prominence**: Primary color, positioned first
-✅ **Consistency**: Matches the pattern of other toolbar icons
-✅ **Accessibility**: Proper tooltips and keyboard navigation
-✅ **Functionality**: Tested and verified working
-
-**Status: PRODUCTION READY** 🚀
-
-Version: 1.4.0
-Build: Successful
-Tests: All passing