@cat-factory/app 0.6.0 → 0.7.3

package/app/types/tasks.ts

@@ -1,82 +1,82 @@
-// ---------------------------------------------------------------------------
-// Task-source integration. Individual issues imported from external task
-// trackers (Jira, …) can be attached to a board task as agent context. These
-// mirror the `@cat-factory/contracts` task schemas; the abstraction is
-// source-agnostic, keyed by `source`. Unlike document sources there is no
-// plan/spawn — an issue is linked for context, never expanded into structure.
-// ---------------------------------------------------------------------------
-
-import type { CredentialField } from './documents'
-
-/** The external task trackers cat-factory can link to. */
-export type TaskSourceKind = 'jira' | 'github'
-
-export type { CredentialField }
-
-/** A source's self-description: drives the generic connect + import UI. */
-export interface TaskSourceDescriptor {
-  source: TaskSourceKind
-  label: string
-  /** Lucide icon name for the source. */
-  icon: string
-  credentialFields: CredentialField[]
-  refLabel: string
-  refPlaceholder: string
-  /** Whether the source supports searching its catalogue by title/content. */
-  searchable?: boolean
-}
-
-/** A workspace's connection to a task source (never carries credentials). */
-export interface TaskConnection {
-  source: TaskSourceKind
-  /** Human-friendly label for what we're connected to (site URL). */
-  label: string
-  /** When the connection was established (epoch ms). */
-  connectedAt: number
-}
-
-/** A single comment on an issue, with its body as lightweight Markdown. */
-export interface TaskComment {
-  author: string
-  createdAt: string
-  body: string
-}
-
-/** An issue imported from a source into the workspace, as a structured record. */
-export interface SourceTask {
-  source: TaskSourceKind
-  /** The source's canonical key for the issue (e.g. `PROJ-123`). */
-  externalId: string
-  title: string
-  url: string
-  /** Workflow status name, e.g. `In Progress`. */
-  status: string
-  /** Issue type name, e.g. `Bug`. */
-  type: string
-  /** Assignee display name, or null when unassigned. */
-  assignee: string | null
-  /** Priority name, or null when none. */
-  priority: string | null
-  labels: string[]
-  /** Issue description as lightweight Markdown. */
-  description: string
-  comments: TaskComment[]
-  /** Short plain-text preview of the issue. */
-  excerpt: string
-  /** The board block this issue is attached to as context, if any. */
-  linkedBlockId: string | null
-  syncedAt: number
-}
-
-/** A lean hit from searching a tracker's issues (not yet imported). */
-export interface TaskSearchResult {
-  source: TaskSourceKind
-  /** The source's canonical key for the issue (re-usable as an import ref). */
-  externalId: string
-  title: string
-  url: string
-  /** Workflow status name, e.g. `In Progress` (may be empty). */
-  status: string
-  /** Short plain-text preview (may be empty). */
-  excerpt: string
-}
+// ---------------------------------------------------------------------------
+// Task-source integration. Individual issues imported from external task
+// trackers (Jira, …) can be attached to a board task as agent context. These
+// mirror the `@cat-factory/contracts` task schemas; the abstraction is
+// source-agnostic, keyed by `source`. Unlike document sources there is no
+// plan/spawn — an issue is linked for context, never expanded into structure.
+// ---------------------------------------------------------------------------
+
+import type { CredentialField } from './documents'
+
+/** The external task trackers cat-factory can link to. */
+export type TaskSourceKind = 'jira' | 'github'
+
+export type { CredentialField }
+
+/** A source's self-description: drives the generic connect + import UI. */
+export interface TaskSourceDescriptor {
+  source: TaskSourceKind
+  label: string
+  /** Lucide icon name for the source. */
+  icon: string
+  credentialFields: CredentialField[]
+  refLabel: string
+  refPlaceholder: string
+  /** Whether the source supports searching its catalogue by title/content. */
+  searchable?: boolean
+}
+
+/** A workspace's connection to a task source (never carries credentials). */
+export interface TaskConnection {
+  source: TaskSourceKind
+  /** Human-friendly label for what we're connected to (site URL). */
+  label: string
+  /** When the connection was established (epoch ms). */
+  connectedAt: number
+}
+
+/** A single comment on an issue, with its body as lightweight Markdown. */
+export interface TaskComment {
+  author: string
+  createdAt: string
+  body: string
+}
+
+/** An issue imported from a source into the workspace, as a structured record. */
+export interface SourceTask {
+  source: TaskSourceKind
+  /** The source's canonical key for the issue (e.g. `PROJ-123`). */
+  externalId: string
+  title: string
+  url: string
+  /** Workflow status name, e.g. `In Progress`. */
+  status: string
+  /** Issue type name, e.g. `Bug`. */
+  type: string
+  /** Assignee display name, or null when unassigned. */
+  assignee: string | null
+  /** Priority name, or null when none. */
+  priority: string | null
+  labels: string[]
+  /** Issue description as lightweight Markdown. */
+  description: string
+  comments: TaskComment[]
+  /** Short plain-text preview of the issue. */
+  excerpt: string
+  /** The board block this issue is attached to as context, if any. */
+  linkedBlockId: string | null
+  syncedAt: number
+}
+
+/** A lean hit from searching a tracker's issues (not yet imported). */
+export interface TaskSearchResult {
+  source: TaskSourceKind
+  /** The source's canonical key for the issue (re-usable as an import ref). */
+  externalId: string
+  title: string
+  url: string
+  /** Workflow status name, e.g. `In Progress` (may be empty). */
+  status: string
+  /** Short plain-text preview (may be empty). */
+  excerpt: string
+}

package/app/types/tracker.ts

@@ -1,18 +1,27 @@
-// Issue-tracker selection shapes, mirroring `@cat-factory/contracts` (tracker.ts).
-// A workspace designates one tracker — GitHub Issues or Jira — where the tech-debt
-// recurring pipeline files its ticket before implementation starts.
-
-export type TrackerKind = 'github' | 'jira'
-
-export interface TrackerSettings {
-  /** The selected tracker, or null when none is configured. */
-  tracker: TrackerKind | null
-  /** Jira project key new tickets are filed under (e.g. 'ENG'); null unless Jira. */
-  jiraProjectKey: string | null
-  updatedAt: number
-}
-
-export interface PutTrackerSettingsInput {
-  tracker: TrackerKind | null
-  jiraProjectKey?: string | null
-}
+// Issue-tracker selection shapes, mirroring `@cat-factory/contracts` (tracker.ts).
+// A workspace designates one tracker — GitHub Issues or Jira — where the tech-debt
+// recurring pipeline files its ticket before implementation starts.
+
+export type TrackerKind = 'github' | 'jira'
+
+export interface TrackerSettings {
+  /** The selected tracker, or null when none is configured. */
+  tracker: TrackerKind | null
+  /** Jira project key new tickets are filed under (e.g. 'ENG'); null unless Jira. */
+  jiraProjectKey: string | null
+  /** Writeback: comment on a task's linked issue when its PR opens. Per-task overridable. */
+  writebackCommentOnPrOpen: boolean
+  /** Writeback: comment + close a task's linked issue as resolved when its PR merges. */
+  writebackResolveOnMerge: boolean
+  updatedAt: number
+}
+
+export interface PutTrackerSettingsInput {
+  tracker: TrackerKind | null
+  jiraProjectKey?: string | null
+  writebackCommentOnPrOpen?: boolean
+  writebackResolveOnMerge?: boolean
+}
+
+/** Per-task writeback override; absent ⇒ inherit the workspace setting. */
+export type WritebackOverride = 'on' | 'off'

package/app/utils/agentOutput.spec.ts

@@ -1,128 +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')
-  })
-})
+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')
+  })
+})