@cat-factory/app 0.6.0

package/app/utils/agentOutput.spec.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest'
+import { parseOutputOutline, sliceSource } from '~/utils/agentOutput'
+
+describe('parseOutputOutline', () => {
+  it('splits on headings and builds a ToC', () => {
+    const out = parseOutputOutline(
+      ['# Overview', 'intro text', '', '## Findings', '- a', '- b'].join('\n'),
+    )
+    expect(out.hasToc).toBe(true)
+    expect(out.minDepth).toBe(1)
+    expect(out.sections.map((s) => s.title)).toEqual(['Overview', 'Findings'])
+    expect(out.sections[0]!.depth).toBe(1)
+    expect(out.sections[1]!.depth).toBe(2)
+    const findings = out.sections[1]!.bodyHtml
+    // top-level blocks now carry data-src-* anchors, so match the open tag loosely
+    expect(findings).toContain('<ul')
+    expect(findings).toContain('<li>a</li>')
+  })
+
+  it('keeps text before the first heading as an untitled preamble (no ToC entry)', () => {
+    const out = parseOutputOutline('loose intro\n\n## Section')
+    expect(out.sections[0]!.title).toBe('')
+    expect(out.sections[0]!.depth).toBe(0)
+    expect(out.sections[0]!.bodyHtml).toContain('loose intro')
+    expect(out.sections.filter((s) => s.depth > 0)).toHaveLength(1)
+  })
+
+  it('reports no ToC when there are no headings', () => {
+    const out = parseOutputOutline('just a paragraph of prose')
+    expect(out.hasToc).toBe(false)
+    expect(out.sections).toHaveLength(1)
+  })
+
+  it('gives every section a unique id even with duplicate titles', () => {
+    const out = parseOutputOutline('## Risks\na\n## Risks\nb')
+    const ids = out.sections.map((s) => s.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it('captures fenced code verbatim without treating its lines as headings', () => {
+    const out = parseOutputOutline('## Code\n```ts\nconst x = 1\n# not a heading\n```')
+    expect(out.sections).toHaveLength(1)
+    const body = out.sections[0]!.bodyHtml
+    expect(body).toContain('<pre>')
+    expect(body).toContain('# not a heading')
+  })
+
+  it('escapes raw HTML rather than injecting it (html: false)', () => {
+    const out = parseOutputOutline('## S\n<img src=x onerror=alert(1)>')
+    const body = out.sections[0]!.bodyHtml
+    expect(body).not.toContain('<img')
+    expect(body).toContain('&lt;img')
+  })
+
+  it('renders inline marks and decorates links to open safely in a new tab', () => {
+    const out = parseOutputOutline('## S\nsee **bold** and [site](https://example.com)')
+    const body = out.sections[0]!.bodyHtml
+    expect(body).toContain('<strong>bold</strong>')
+    expect(body).toContain('href="https://example.com"')
+    expect(body).toContain('target="_blank"')
+    expect(body).toContain('rel="noopener noreferrer"')
+  })
+
+  it('does not create a link for javascript: URLs (markdown-it validateLink)', () => {
+    // validateLink rejects the scheme, so it stays inert plain text — never an <a>.
+    const out = parseOutputOutline('## S\n[x](javascript:alert(1))')
+    const body = out.sections[0]!.bodyHtml
+    expect(body).not.toContain('<a ')
+    expect(body).not.toContain('href')
+  })
+
+  it('tolerates empty / nullish input', () => {
+    expect(parseOutputOutline('').sections).toHaveLength(0)
+    expect(parseOutputOutline(undefined as unknown as string).sections).toHaveLength(0)
+  })
+})
+
+describe('sliceSource', () => {
+  it('returns the verbatim line range (0-based, end-exclusive)', () => {
+    const text = ['line0', 'line1', 'line2', 'line3'].join('\n')
+    expect(sliceSource(text, 1, 3)).toBe('line1\nline2')
+    expect(sliceSource(text, 0, 1)).toBe('line0')
+  })
+
+  it('tolerates nullish input', () => {
+    expect(sliceSource(undefined as unknown as string, 0, 1)).toBe('')
+  })
+})
+
+describe('source-line stamping (approval-mode block anchors)', () => {
+  // Find a rendered block by its text and round-trip its `data-src-*` range back
+  // through `sliceSource` against the ORIGINAL output — this is the contract the
+  // approval reader relies on to quote the agent's own markdown back to it.
+  const blockFor = (output: string, contains: string) => {
+    const { sections } = parseOutputOutline(output)
+    const host = document.createElement('div')
+    host.innerHTML = sections.map((s) => s.bodyHtml).join('\n')
+    const el = Array.from(host.querySelectorAll('[data-src-start]')).find((e) =>
+      (e.textContent ?? '').includes(contains),
+    )
+    if (!el) throw new Error(`no source-stamped block containing "${contains}"`)
+    return {
+      start: Number(el.getAttribute('data-src-start')),
+      end: Number(el.getAttribute('data-src-end')),
+    }
+  }
+
+  it('round-trips a paragraph block to its original source lines', () => {
+    const output = ['## Summary', '', 'First paragraph.', '', 'Second paragraph here.'].join('\n')
+    const { start, end } = blockFor(output, 'First paragraph.')
+    expect(sliceSource(output, start, end)).toBe('First paragraph.')
+  })
+
+  it('round-trips a multi-line fenced code block verbatim', () => {
+    const code = ['```ts', 'const x = 1', 'const y = 2', '```'].join('\n')
+    const output = ['## Code', '', code].join('\n')
+    const { start, end } = blockFor(output, 'const x = 1')
+    expect(sliceSource(output, start, end)).toBe(code)
+  })
+
+  it('stamps top-level blocks only (a comment targets a whole block, not a nested item)', () => {
+    const output = ['Intro paragraph.', '', '- item one', '- item two'].join('\n')
+    const { start, end } = blockFor(output, 'item one')
+    // The whole list is the top-level block, so the slice spans both items.
+    expect(sliceSource(output, start, end)).toContain('- item one')
+    expect(sliceSource(output, start, end)).toContain('- item two')
+  })
+})

package/app/utils/agentOutput.ts

@@ -0,0 +1,173 @@
+// Turn an agent's prose output (markdown) into a heading-delimited outline so it
+// can be read in the dedicated reader overlay: a navigable table of contents on
+// one side, collapsible sections on the other.
+//
+// Markdown → HTML is done by `markdown-it` (a mature CommonMark parser) with
+// `html: false`, so it is secure by default: any raw HTML in the agent's output
+// is escaped rather than injected, and its `validateLink` blocks dangerous URL
+// schemes — no separate sanitizer needed for the LLM-generated text we feed it.
+// This module only adds the one thing markdown-it doesn't: SEGMENTATION — split
+// the rendered document at each heading into sections we can collapse
+// independently and link from a ToC. That split is done over the parsed DOM, so
+// it is independent of markdown-it's token internals.
+import MarkdownIt from 'markdown-it'
+
+/**
+ * Stamp every TOP-LEVEL block element with its source line range
+ * (`data-src-start`/`data-src-end`, 0-based, end-exclusive — straight from
+ * markdown-it's `token.map`). The approval-mode reader uses these to let a human
+ * comment on a specific block and quote that block's verbatim raw markdown back to
+ * the agent on a "request changes" re-run. Only top-level blocks are tagged (depth
+ * tracked over the flat token stream) so a comment targets a whole paragraph/list/
+ * heading rather than a nested fragment.
+ */
+function sourceLinePlugin(md: MarkdownIt): void {
+  md.core.ruler.push('source_lines', (state) => {
+    let depth = 0
+    for (const token of state.tokens) {
+      const atTopLevel = depth === 0
+      // Annotate a top-level block's opening token (nesting 1) or a self-contained
+      // block token (nesting 0, e.g. fence/hr/code_block/html_block).
+      if (atTopLevel && token.block && token.type !== 'inline' && token.map && token.nesting >= 0) {
+        token.attrSet('data-src-start', String(token.map[0]))
+        token.attrSet('data-src-end', String(token.map[1]))
+      }
+      if (token.nesting === 1) depth++
+      else if (token.nesting === -1) depth--
+    }
+    return true
+  })
+}
+
+/**
+ * The verbatim raw-markdown source of a block, given the original output text and a
+ * 0-based, end-exclusive line range (as captured from `data-src-start/end`).
+ */
+export function sliceSource(output: string, start: number, end: number): string {
+  return (output ?? '').split('\n').slice(start, end).join('\n')
+}
+
+/** One heading-delimited section. `depth` 0 / empty `title` is the preamble that
+ * precedes the first heading (rendered, but never shown in the ToC). */
+export interface OutputSection {
+  id: string
+  depth: number
+  /** Plain-text heading, for the ToC. */
+  title: string
+  /** Inline-rendered heading HTML (code/bold/… preserved), for the section header. */
+  titleHtml: string
+  /** HTML of everything under this heading up to the next one. */
+  bodyHtml: string
+}
+
+export interface OutputOutline {
+  sections: OutputSection[]
+  /** True once there is at least one real heading worth a ToC entry. */
+  hasToc: boolean
+  /** Shallowest heading depth present, so the ToC can indent relative to it. */
+  minDepth: number
+}
+
+const md = new MarkdownIt({
+  html: false, // secure by default: escape raw HTML rather than render it
+  linkify: true, // turn bare URLs into links
+  breaks: true, // single newlines → <br>, matching how agents lay out prose
+  typographer: true,
+}).use(sourceLinePlugin)
+
+const HEADINGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6'])
+const LINK_CLASS = 'text-indigo-300 underline decoration-indigo-500/40 hover:text-indigo-200'
+
+function slugify(title: string, used: Set<string>): string {
+  const base =
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'section'
+  let slug = base
+  let n = 2
+  while (used.has(slug)) slug = `${base}-${n++}`
+  used.add(slug)
+  return slug
+}
+
+/** Make every link open safely in a new tab and pick up the reader's link style. */
+function decorateLinks(root: HTMLElement): void {
+  for (const a of Array.from(root.querySelectorAll('a'))) {
+    a.setAttribute('target', '_blank')
+    a.setAttribute('rel', 'noopener noreferrer')
+    a.setAttribute('class', LINK_CLASS)
+  }
+}
+
+/** Build the heading-based outline for an agent's prose output. */
+export function parseOutputOutline(text: string): OutputOutline {
+  const source = text ?? ''
+  if (!source.trim()) return { sections: [], hasToc: false, minDepth: 1 }
+
+  const html = md.render(source)
+
+  // No DOM (SSR / non-browser): fall back to one un-segmented section. The reader
+  // overlay is client-only, so this path is effectively dead outside any runtime
+  // without `document`.
+  if (typeof document === 'undefined') {
+    return {
+      sections: [{ id: 'overview', depth: 0, title: '', titleHtml: '', bodyHtml: html }],
+      hasToc: false,
+      minDepth: 1,
+    }
+  }
+
+  const root = document.createElement('div')
+  root.innerHTML = html
+  decorateLinks(root)
+
+  const used = new Set<string>()
+  const sections: OutputSection[] = []
+  let current: OutputSection | null = null
+  let body: HTMLElement | null = null
+
+  const flush = () => {
+    if (current && body) current.bodyHtml = body.innerHTML.trim()
+    if (current) sections.push(current)
+  }
+
+  for (const node of Array.from(root.childNodes)) {
+    const el = node.nodeType === 1 ? (node as HTMLElement) : null
+    if (el && HEADINGS.has(el.tagName)) {
+      flush()
+      const title = (el.textContent ?? '').trim()
+      current = {
+        id: slugify(title, used),
+        depth: Number(el.tagName[1]),
+        title,
+        titleHtml: el.innerHTML,
+        bodyHtml: '',
+      }
+      body = document.createElement('div')
+    } else {
+      if (!current) {
+        // Content before the first heading → untitled preamble section.
+        current = {
+          id: slugify('overview', used),
+          depth: 0,
+          title: '',
+          titleHtml: '',
+          bodyHtml: '',
+        }
+        body = document.createElement('div')
+      }
+      body!.appendChild(node.cloneNode(true))
+    }
+  }
+  flush()
+
+  // A preamble that turned out to hold nothing renderable is noise — drop it.
+  const cleaned = sections.filter((s) => s.title || s.bodyHtml)
+  const headed = cleaned.filter((s) => s.depth > 0)
+  return {
+    sections: cleaned,
+    hasToc: headed.length > 0,
+    minDepth: headed.length ? Math.min(...headed.map((s) => s.depth)) : 1,
+  }
+}

package/app/utils/catalog.spec.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest'
+import type { AgentKind, BlockStatus, BlockType } from '~/types/domain'
+import {
+  AGENT_ARCHETYPES,
+  AGENT_BY_KIND,
+  BLOCK_TYPE_META,
+  STATUS_META,
+  SYSTEM_AGENT_META,
+  agentKindMeta,
+  uid,
+} from '~/utils/catalog'
+
+const AGENT_KINDS: AgentKind[] = [
+  'requirements-review',
+  'clarity-review',
+  'bug-investigator',
+  'task-estimator',
+  'architect',
+  'researcher',
+  'coder',
+  'tester',
+  'reviewer',
+  'documenter',
+  'integrator',
+  'architect-companion',
+  'spec-companion',
+  'playwright',
+  'mocker',
+  'business-documenter',
+  'business-reviewer',
+]
+const BLOCK_TYPES: BlockType[] = [
+  'frontend',
+  'service',
+  'api',
+  'database',
+  'queue',
+  'integration',
+  'external',
+]
+const BLOCK_STATUSES: BlockStatus[] = [
+  'planned',
+  'ready',
+  'in_progress',
+  'blocked',
+  'pr_ready',
+  'done',
+]
+
+describe('catalog', () => {
+  it('indexes every archetype by its kind', () => {
+    expect(Object.keys(AGENT_BY_KIND).sort()).toEqual([...AGENT_KINDS].sort())
+    for (const a of AGENT_ARCHETYPES) {
+      expect(AGENT_BY_KIND[a.kind]).toBe(a)
+    }
+  })
+
+  it('resolves usable metadata for every kind via agentKindMeta', () => {
+    // Palette archetypes resolve to their own entry.
+    for (const a of AGENT_ARCHETYPES) {
+      expect(agentKindMeta(a.kind)).toBe(a)
+    }
+    // Engine system kinds (present in seeded pipelines but not the palette) resolve
+    // to their system metadata rather than blowing up an undefined access.
+    for (const kind of [
+      'spec-writer',
+      'blueprints',
+      'conflicts',
+      'conflict-resolver',
+      'ci',
+      'ci-fixer',
+      'merger',
+      'post-release-health',
+    ]) {
+      expect(agentKindMeta(kind)).toBe(SYSTEM_AGENT_META[kind])
+      expect(agentKindMeta(kind).icon).toEqual(expect.any(String))
+    }
+    // An unknown/custom kind still returns a usable fallback (never undefined).
+    const unknown = agentKindMeta('totally-made-up')
+    expect(unknown).toMatchObject({
+      label: expect.any(String),
+      icon: expect.any(String),
+      color: expect.any(String),
+    })
+  })
+
+  it('provides metadata for every block type', () => {
+    for (const t of BLOCK_TYPES) {
+      expect(BLOCK_TYPE_META[t]).toMatchObject({
+        label: expect.any(String),
+        icon: expect.any(String),
+        accent: expect.any(String),
+      })
+    }
+  })
+
+  it('provides metadata for every block status', () => {
+    for (const s of BLOCK_STATUSES) {
+      expect(STATUS_META[s]).toMatchObject({
+        label: expect.any(String),
+        color: expect.any(String),
+        chip: expect.any(String),
+        icon: expect.any(String),
+      })
+    }
+  })
+
+  it('uid produces prefixed, unique-ish ids', () => {
+    expect(uid('blk')).toMatch(/^blk_[a-z0-9]+$/)
+    expect(uid('blk')).not.toBe(uid('blk'))
+  })
+})