S254: Git Operations — Graph Visualization, Sub-Components & Multi-App Integration

Date: 2026-03-21 Session: 254 Agent: Claude Code (claude-opus-4-6) Branch: session-252-255 (shared concurrent session)

1. Mission

Build a groundbreaking git graph visualization using a "Metro + Living Intelligence" visual paradigm, extract all UI into fine-grained reusable components within the @libs-structural/git-operations library, and wire the library into gograb-admin and vitto-studio alongside the existing gograb-dev integration.

2. Design Decisions

3. Architecture

3.1 Component Tree

All components live in libs/libs-structural/git-operations/src/lib/components/:

components/
├── git-graph/                        ★ Star component
│   ├── git-graph.component.ts
│   ├── git-graph.component.html
│   ├── git-graph.component.scss
│   ├── git-graph-lane.util.ts          # Pure fn: lane assignment algorithm
│   └── git-graph-renderer.util.ts      # Pure fn: SVG path/node generation
├── git-repo-card/
│   ├── git-repo-card.component.ts
│   ├── git-repo-card.component.html
│   └── git-repo-card.component.scss
├── git-branch-sidebar/
│   ├── git-branch-sidebar.component.ts
│   ├── git-branch-sidebar.component.html
│   └── git-branch-sidebar.component.scss
├── git-file-browser/
│   ├── git-file-browser.component.ts
│   ├── git-file-browser.component.html
│   └── git-file-browser.component.scss
├── git-commit-list/
│   ├── git-commit-list.component.ts
│   ├── git-commit-list.component.html
│   └── git-commit-list.component.scss
├── git-server-metrics/
│   ├── git-server-metrics.component.ts
│   ├── git-server-metrics.component.html
│   └── git-server-metrics.component.scss
└── git-commit-detail-panel/
    ├── git-commit-detail-panel.component.ts
    ├── git-commit-detail-panel.component.html
    └── git-commit-detail-panel.component.scss

3.2 Data Flow

• All components are dumb — they receive data via signal inputs and emit events via output callbacks
• The host page (in each app) injects GitOperationsStateService and wires signals to component inputs
• Exception: git-graph can accept an optional stateService input for convenience, since it orchestrates multiple sub-interactions internally

3.3 Component Inputs

git-graph:                commits, branches, selectedSha, templateFilter, compact, onCommitClick, onBranchSwitch
git-repo-card:            repo, onSelect
git-branch-sidebar:       branches, selectedBranch, features, onSwitch, onMerge, onDelete, onCreate
git-file-browser:         files, features, searchQuery, onFileSelect
git-commit-list:          commits, expandedSha, diff, features, onToggle
git-server-metrics:       metrics
git-commit-detail-panel:  diff, visible, onClose

4. Git Graph — The Star Component

4.1 Data Model

New types in git-operations.types.ts:

interface GitCommitNode {
  // From GitCommitInfo
  sha: string;
  shortSha: string;
  message: string;
  author: string;
  date: string;
  // NEW — from backend enrichment
  parentShas: string[];
  // Computed by lane algorithm
  laneIndex: number;
  color: string;
  isHead: boolean;              // tip of a branch
  isMerge: boolean;             // parentShas.length > 1
  branchName?: string;          // if this commit is a branch tip
  age: 'recent' | 'active' | 'aging' | 'old';
  // Optional enrichment
  filesChanged?: number;
  insertions?: number;
  deletions?: number;
  templateOnly?: boolean;       // true if commit only touches core libs
}

interface GitGraphLane {
  branchName: string;
  color: string;
  column: number;
  active: boolean;              // false = stale (dashed, faded)
  lastCommitDate: string;
}

4.2 Lane Assignment Algorithm

Pure function in git-graph-lane.util.ts:

1. Walk commits top-to-bottom (newest first)
2. First commit gets lane 0 (main line)
3. When a commit has a parent not in the current lane, fork: assign next available column
4. When a merge commit appears (2+ parents), mark the merging lane as "closing" — draw merge path back to target lane
5. Reuse closed lane columns to keep the graph narrow
6. Staleness: if a lane's last commit is >7 days old (old tier), mark active: false. Lanes in aging tier (2d–7d) remain active: true with solid lines but their commit nodes render at reduced opacity per the age tier rules. Only old (>7d) lanes get the dashed/faded treatment.

4.3 SVG Rendering

Pure functions in git-graph-renderer.util.ts that take GitCommitNode[] and GitGraphLane[] and return SVG element descriptors:

SVG column width: 20px + (laneCount × 28px). Each commit row: 32–48px tall depending on age tier.

4.4 Living Intelligence Rules

Template-aware commits: If templateOnly: true, the commit renders one age tier older (e.g., recent → active). For non-executive/developer roles, template-only commits are hidden entirely.

4.5 Interaction Model

• Click commit node/row → Inline expansion showing diff stats (files, +/−), file list with type icons
• Click "Full detail" button in expanded row → git-commit-detail-panel slides in from right
• Hover commit node → Tooltip with SHA, author, time (from existing commit data — no extra API call)
• Click branch pill label → Switches to that branch (emits onBranchSwitch)
• Compact mode ([compact]="true" for vitto-studio): Narrower rows, inline expansion only (no slide-out panel)

5. Sub-Components

5.1 git-repo-card

Overview card for a repository in the grid view.

• Inputs: repo: GitRepoInfo, onSelect: EventEmitter
• Shows: Org/repo name, branch count badge, file count badge, last commit message (truncated), last commit time (timeAgo)
• Visual: Card with subtle border, hover lifts with shadow. Org slug as colored dot prefix.

5.2 git-branch-sidebar

Branch list with role-gated management actions.

• Inputs: branches: GitBranchInfo[], selectedBranch: string, features: GitOpsFeatureFlags, onSwitch, onMerge, onDelete, onCreate
• Shows: Scrollable branch list with current-branch indicator, SHA prefix per branch
• Actions (role-gated): Merge to develop, delete, create new branch. Protected branches (main, develop) show lock icon, no delete.
• States: Loading/error for branch actions

5.3 git-file-browser

Grouped file tree with search and template filtering.

• Inputs: files: GitFileTreeItem[], features: GitOpsFeatureFlags, searchQuery: string, onFileSelect
• Shows: Files grouped by top-level directory, collapsible groups, file count per group, file type icons (TS, HTML, SCSS, JSON, etc.)
• Template filter: features.canViewTemplateSources === false → auto-filters TEMPLATE_CORE_PATHS. === true → shows toggle ("Show core libraries"), defaults to off.

5.4 git-commit-list

Non-graph commit list for use outside graph context.

• Inputs: commits: GitCommitInfo[], expandedSha: string | null, diff: GitCommitDiff | null, features: GitOpsFeatureFlags, onToggle
• Shows: Commit rows with SHA, message, author, timeAgo. Click toggles inline expansion with diff stats.
• Template awareness: Same rules as file browser — template-only commits dimmed or hidden based on role.

5.5 git-server-metrics

Host metrics strip for Hetzner infrastructure.

• Inputs: metrics: HetznerHostMetrics
• Shows: CPU load, memory usage %, disk %, active VMs, uptime. Compact horizontal strip with icon + value pairs. Color-coded thresholds (green < 60%, yellow 60-80%, red > 80%).

5.6 git-commit-detail-panel

Slide-out detail panel for full commit inspection.

• Inputs: diff: GitCommitDiff, visible: boolean, onClose
• Shows: Full commit info header (SHA, author, date, message), file list with per-file insertion/deletion bars, total stats summary.
• Behavior: Slides in from right, overlay with backdrop. Close via button or backdrop click.

6. Template-Aware Filtering

6.1 Template Core Paths

New file models/git-template-paths.config.ts:

export const TEMPLATE_CORE_PATHS = [
  'libs/core/',
  'libs/libs-foundational/',
  'libs/libs-ui/',
  'libs/libs-ui-core/',
  'libs/libs-ux/',
  'libs/libs-ai/',
  'libs/libs-api/',
  'libs/libs-dev-tools/',
  'libs/libs-private/',
  'libs/theme-system/',
] as const;

export function isTemplatePath(filePath: string): boolean {
  return TEMPLATE_CORE_PATHS.some(p => filePath.startsWith(p));
}

export function isTemplateOnlyCommit(files: { path: string }[]): boolean {
  return files.length > 0 && files.every(f => isTemplatePath(f.path));
}

6.2 Role Gating

New flag in GitOpsFeatureFlags:

canViewTemplateSources: boolean
  executive: true
  developer: true
  admin: false
  user: false

Component behavior:

• canViewTemplateSources === true → Show toggle ("Show core libraries"), default off. User can switch.
• canViewTemplateSources === false → Always filtered, no toggle visible.

6.3 Platform Convention

This pattern (TEMPLATE_CORE_PATHS + canViewTemplateSources flag) is designed to be promoted to a shared foundational location when other libs that show platform files need it. For S254, it lives in git-operations as the first consumer.

7. App Integration

7.1 gograb-dev (Refactor existing)

• Route: /platform/git-operations (unchanged)
• Change: Refactor monolithic component into thin shell composing library sub-components
• Layout: Overview = git-server-metrics + git-repo-card grid. Detail = git-branch-sidebar (left) + tabbed: git-graph (default tab), git-file-browser, git-commit-list. git-commit-detail-panel overlays.
• Graph becomes default tab in detail view (replacing files)
• Provider: Already configured — no changes
• Role: developer tier

7.2 gograb-admin (New)

• Nav: Add new platform nav group to adminNavGroups in admin-main-shell.component.ts
• Route: Add /platform/git-operations in app.routes.ts
• Provider: Add provideGitOperations() to app.config.ts
• Page: Thin component composing git-repo-card grid (overview) + git-graph + git-file-browser (detail). No branch management actions (merge disabled for admin tier).
• Role: admin tier — canViewTemplateSources: false, template files always filtered, no toggle
• Note: Current admin tier has showServerMetrics: true. Update to false for admin since admins don't need infrastructure visibility — server metrics are an executive/developer concern. This change goes in git-operations-role.config.ts.

7.3 vitto-studio (New dock panel)

• Registration: Add to STUDIO_DOCK_PANELS in studio-dock-panels.config.ts under the existing // === GIT === section:

  { id: 'studio-git-graph', title: 'Graph', icon: 'commit', component: StudioGitGraphPanelComponent, closable: true, draggable: true, singleton: true, category: 'git' }
  

  Note: Uses category: 'git' to match existing git panels (studio-history, studio-branches, studio-diff).
• Layout presets: Add 'studio-git-graph' to STUDIO_CODE_LAYOUT in the git tabs section (lines 123-125, alongside studio-branches, studio-diff, studio-history). Not needed in STUDIO_VISUAL_LAYOUT (visual builders rarely need git details).
• New panel wrapper file: libs/libs-structural/vitto-studio/src/lib/panels/git-graph-panel.component.ts — a thin wrapper component that:
  • Injects GitOperationsStateService and sets space filter
  • Gets universe context from route params (same pattern as studio-dock-shell.component.ts lines 135-138: reads spaceSlug and universeSlug from route paramMap)
  • Renders <git-graph [compact]="true">
• Provider: Add provideGitOperations() to studio's app config (via gograb-ai app.config.ts where studio providers are registered)
• Behavior: Scoped to current universe's repo, compact mode, inline expansion only
• State service: GitOperationsStateService.setSpaceFilter() already exists (line 349 in state service) — takes a string | null for the space slug

8. Backend Enrichment

8.1 Commit History — Add parentShas

File: APIs/sandbox-orchestrator/src/app/git/git.service.ts (lines 527-551)

Change: The current implementation uses git.log([branch, '--max-count=...']) with default log fields. We need to switch to custom format to include %P (parent SHAs).

Important: simple-git's LogOptions does NOT support { [branch]: true } as a dynamic key for branch filtering. The branch must be passed via the second argument array or customArgs. Keep the existing array-based approach and add --format manually:

// Approach: keep the working array-based git.log() pattern, add --format
const formatStr = '--format={"hash":"%H","shortHash":"%h","message":"%s","author":"%an","date":"%ai","parentHashes":"%P"}';
const result = await git.raw([
  'log',
  branch,
  `--max-count=${limit}`,
  formatStr,
]);

// Parse JSON lines (one per commit)
const commits = result
  .trim()
  .split('\n')
  .filter(Boolean)
  .map(line => {
    const entry = JSON.parse(line);
    return {
      sha: entry.hash,
      shortSha: entry.shortHash,
      message: entry.message,
      author: entry.author,
      date: entry.date,
      parentShas: entry.parentHashes ? entry.parentHashes.split(' ').filter(Boolean) : [],
    };
  });

Impact: Additive change, no breaking changes. Existing consumers ignore the new parentShas field. Uses git.raw() instead of git.log() to avoid simple-git's LogOptions limitations with custom format + branch filtering.

9. Files Summary

New Files (24 source files)

Modified Files (9)

10. Edge Cases

• Root commit: Has no parents — parentShas: []. Lane algorithm treats as lane 0 origin.
• Octopus merges: 3+ parents (rare). Render as multi-merge interchange station, connecting all source lanes.
• Protected branches: main, develop — lock icon, no delete action. Backend guard already exists.
• Empty repos: No commits — graph shows "No commits yet" placeholder.
• 100+ commits: Use Angular CDK ScrollingModule (cdk-virtual-scroll-viewport) for virtual scrolling. Each commit row is a fixed-height virtual scroll item (32–48px depending on age tier). Living intelligence naturally compresses old commits visually.
• 3-level repo paths: parseRepoPath takes last 2 segments (existing fix from S251).
• Stale branches >7d: Dashed lines, 0.25 opacity. Visible but clearly secondary.
• Template-only repos: If ALL files are template, the file browser shows "Only core library files" message with toggle hint (if role permits).

11. Implementation Ordering

The following dependency order must be followed:

1. Models first: Update git-operations.types.ts (add GitCommitNode, GitGraphLane, parentShas on GitCommitInfo) and git-operations-role.config.ts (add canViewTemplateSources, change admin.showServerMetrics). Create git-template-paths.config.ts. All components depend on these types compiling.
2. API service: Update git-operations-api.service.ts return type for getCommitHistory.
3. Backend: Update sandbox-orchestrator/git.service.ts to return parentShas.
4. Pure utilities: git-graph-lane.util.ts and git-graph-renderer.util.ts — no Angular dependencies, highly testable.
5. Sub-components: Can be built in parallel — git-repo-card, git-branch-sidebar, git-file-browser, git-commit-list, git-server-metrics, git-commit-detail-panel.
6. Star component: git-graph — depends on lane util, renderer util, and the commit detail panel.
7. Index exports: Update src/index.ts to export all new components, types (GitCommitNode, GitGraphLane), and template config utils (isTemplatePath, isTemplateOnlyCommit, TEMPLATE_CORE_PATHS).
8. App integrations: gograb-dev refactor, gograb-admin page + nav + route, vitto-studio dock panel. These depend on all library components being built.

12. Diff Stats Loading Strategy

Commit diff stats (filesChanged, insertions, deletions, file list) are loaded lazily on click, NOT pre-fetched:

• On commit click (inline expand): Call getCommitDiff(org, repo, sha) — same existing endpoint. Cache the result in the state service's commitDiff signal.
• On hover (tooltip): Show only data already available from the commit history response (sha, author, date, message). No API call on hover — avoids N+1 problem.
• Template-only detection: The templateOnly flag on GitCommitNode can only be computed after the diff is loaded (since we need the file paths). For the initial graph render, templateOnly defaults to false. Once a diff is loaded, the flag is updated and the graph re-renders that node's visual treatment. This means template-only dimming is progressive — it appears as users interact, which aligns with the "living" metaphor.

13. Admin Nav Group Definition

New nav group to add to adminNavGroups in admin-main-shell.component.ts:

{
  id: 'platform',
  label: 'Platform',
  items: [
    { id: 'git-operations', label: 'Git Operations', icon: 'commit', route: '/platform/git-operations' },
  ],
}

This creates the Platform section in admin sidebar. Future platform tools (deployment status, environment config, etc.) can be added here.

14. Constraints

• Angular 20+ patterns: standalone, signals, OnPush, inject()
• Separate .ts, .html, .scss files — no inline templates
• DI tokens for config — never hardcode URLs or API keys
• No git commits during this session (concurrent session conflict avoidance)
• TEMPLATE_CORE_PATHS must stay in sync with the actual platform-base-template structure
• Angular CDK ScrollingModule for virtual scrolling (already available in the monorepo)