@defrex/autobuild 0.8.0 → 0.10.0

package/skills/tickets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tickets
-description: Work this repo's local ticket tracker — create or edit a ticket, amend blockedBy dependencies, report the backlog, move work between triage/ready/doing/done, or answer "what's the status of ticket X". Use whenever the user asks about tickets, blockers, the backlog, or wants something queued for autobuild to build.
+description: Work this repo's local ticket tracker — create or edit a ticket, amend blockedBy dependencies, report the backlog, triage the inbox, move work between the lifecycle directories and any repository-defined states such as the icebox, or answer "what's the status of ticket X". Use whenever the user asks about tickets, blockers, the backlog, or wants something queued for autobuild to build.
 ---
 
 # /tickets
@@ -12,7 +12,11 @@ content and blocker relationships. The default file source needs no secret.
 ## Where it lives
 
 `.autobuild/tickets/` by default (if `autobuild.toml` has a `[tickets] dir`,
-that directory instead), holding exactly four state directories:
+that directory instead), holding the four lifecycle state directories plus any others this repo adds.
+`triage/`, `ready/`, `doing/`, and `done/` are the lifecycle directories the
+dispatcher uses. Any other directory is a repository-defined state: the
+dispatcher never moves tickets into it and never dispatches from it unless
+`autobuild.toml` names it (for example `readyState` or `proposalState`).
 
 ```
 .autobuild/tickets/
@@ -20,6 +24,7 @@ that directory instead), holding exactly four state directories:
   ready/    # groomed; file lifecycle-state gate satisfied
   doing/    # claimed; a build is running
   done/     # merged
+  icebox/   # example of a repo-added state, present only once created
 ```
 
 **A ticket's state is the directory it is in.** There is no `state` field
@@ -71,13 +76,17 @@ retry, and adding validates the blocker exists and is not the ticket itself.
 ## Report the backlog
 
 ```
+ab ticket states                # every state, lifecycle and custom: role, count, purpose
 ls .autobuild/tickets/ready     # groomed candidates in the ready lifecycle state
 ls .autobuild/tickets/doing     # what's building right now
 ```
 
 The filename is the id. For a title, read the file's frontmatter. To report
-the whole backlog, list all four directories — that listing is complete and
-current by construction.
+the whole backlog, cover every state — lifecycle and custom — via
+`ab ticket states` or by listing every directory under the tracker root, so the
+report includes `icebox/` and any other category. `ab ticket list` without
+filters shows only the ready state, regardless of custom states, so it is not a
+backlog report.
 
 ## Groom / transition a ticket
 
@@ -113,6 +122,49 @@ bounces.
 **Don't hand-move anything out of `doing/`** — a build owns it. If you need to
 stop a build, that's `ab` (or a human), not `mv`.
 
+## Icebox
+
+`icebox/` is work deliberately deferred, groomed or not, that nothing
+dispatches from. The first time it is needed, create it:
+
+```
+ab ticket state create icebox --about "Deferred on purpose; nothing dispatches from here"
+```
+
+Move a ticket in with `ab ticket move file-3 icebox`. To revive one, move it to
+`triage/` when it needs regrooming, or to `ready/` when its spec still holds.
+
+## Triage the backlog
+
+To run a pass over `triage/`:
+
+1. Run `ab ticket states` to see which destinations exist.
+2. For each ticket in `triage/`, read it with `ab ticket show <id>` and judge
+   whether its body meets the
+   [spec standard](../ab-guide/references/spec-standard.md).
+3. Move it to `ready/` if it conforms and should be built; to `icebox/` if it
+   should wait; to another existing category if one fits; otherwise leave it in
+   `triage/` and tell the user why.
+4. Report every move to the user in the session — id, title, destination, and
+   reason. A move leaves no comment on the ticket, so the report is the only
+   record of why.
+
+## Inventing categories
+
+Run `ab ticket states` before creating anything. Reuse an existing state whose
+purpose fits. Create a new one only for a recurring reason that no existing
+state covers, with a lowercase hyphenated noun name and a one-line `--about`
+purpose. `icebox` is the first worked example; `rejected` is a second:
+
+```
+ab ticket state create rejected --about "Considered and declined; kept for the record"
+```
+
+Never invent a second ready, doing, or done state, never move anything out of
+`doing/`, and never create states for a build's internal progress — the
+lifecycle belongs to the dispatcher. Remember that `ab ticket list` without
+filters still shows only the ready state, however many custom states exist.
+
 ## Rules
 
 - Never edit frontmatter to change state — the directory is the state.
@@ -132,7 +184,7 @@ listing under default config. That does not make `ready/` sufficient;
 unresolved blockers are an independent dispatch gate.
 
 No Linear lifecycle UI. Directory-based lifecycle operations (`ls`, `mv`, and
-the four state directories) are file-tracker-only. If this repo's
+the state directories) are file-tracker-only. If this repo's
 `autobuild.toml` sets `[tickets] source = "linear"`, do not apply that lifecycle
 guidance: state and labels live in Linear. The source-agnostic `ab ticket block`
 and `ab ticket unblock` commands still edit blocker relationships through the

package/packages/core/src/cli/dashboard/frame-image.ts

@@ -1,373 +0,0 @@
-import { readdirSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { dirname, join } from 'node:path'
-import { Resvg } from '@resvg/resvg-js'
-import { distributionPath } from '../../distribution'
-import { graphemes } from './cells'
-
-/**
- * Deterministic dashboard-frame rendering.
- *
- * The dashboard deliberately emits a tiny terminal vocabulary: SGR reset,
- * bold/dim and six named foreground colours, plus OSC 8 hyperlinks. This
- * adapter accepts exactly that vocabulary. Unknown control traffic is an
- * error rather than evidence that merely looks plausible after bytes were
- * dropped.
- */
-
-const ESC = '\x1b'
-const BEL = '\x07'
-const FONT_FAMILY = 'DejaVu Sans Mono'
-const FONT_FAMILIES = [
-  FONT_FAMILY,
-  'Dashboard CJK 113',
-  'Dashboard CJK 117',
-  'Dashboard CJK 118',
-  'Dashboard Emoji Flags',
-  'Dashboard Emoji Food',
-  'Dashboard Emoji People',
-].join(', ')
-const FONT_SIZE = 16
-const CELL_WIDTH = 10
-const LINE_HEIGHT = 20
-const PADDING_X = 12
-const PADDING_Y = 10
-const BASELINE = 16
-const EMOJI_CLUSTER = /\p{Extended_Pictographic}|\p{Regional_Indicator}/u
-
-const PALETTE = {
-  background: '#0d1117',
-  foreground: '#c9d1d9',
-  red: '#ff7b72',
-  green: '#3fb950',
-  yellow: '#d29922',
-  blue: '#58a6ff',
-  cyan: '#39c5cf',
-} as const
-
-type Foreground = Exclude<keyof typeof PALETTE, 'background'>
-
-interface Style {
-  foreground: Foreground
-  bold: boolean
-  dim: boolean
-  href?: string
-}
-
-interface TextRun {
-  column: number
-  cells: number
-  text: string
-  style: Style
-}
-
-interface ParsedLine {
-  text: string
-  cells: number
-  runs: TextRun[]
-}
-
-export interface FrameImageOptions {
-  /** Declared terminal width. Every parsed line must fit this grid. */
-  columns: number
-}
-
-export interface RenderedFrameImage {
-  /** ANSI/OSC-free text from the exact parsed cells, with a final newline. */
-  text: string
-  svg: string
-  png: Uint8Array
-  width: number
-  height: number
-  rows: number
-  columns: number
-}
-
-function cloneStyle(style: Style): Style {
-  return {
-    foreground: style.foreground,
-    bold: style.bold,
-    dim: style.dim,
-    ...(style.href !== undefined ? { href: style.href } : {}),
-  }
-}
-
-function sameStyle(left: Style, right: Style): boolean {
-  return (
-    left.foreground === right.foreground &&
-    left.bold === right.bold &&
-    left.dim === right.dim &&
-    left.href === right.href
-  )
-}
-
-function applySgr(style: Style, raw: string, line: number): void {
-  const codes = raw === '' ? [0] : raw.split(';').map((part) => Number(part))
-  if (codes.some((code) => !Number.isInteger(code))) {
-    throw new Error(`dashboard frame line ${line}: malformed SGR sequence ESC[${raw}m`)
-  }
-  for (const code of codes) {
-    switch (code) {
-      case 0:
-        style.foreground = 'foreground'
-        style.bold = false
-        style.dim = false
-        break
-      case 1:
-        style.bold = true
-        break
-      case 2:
-        style.dim = true
-        break
-      case 22:
-        style.bold = false
-        style.dim = false
-        break
-      case 31:
-        style.foreground = 'red'
-        break
-      case 32:
-        style.foreground = 'green'
-        break
-      case 33:
-        style.foreground = 'yellow'
-        break
-      case 34:
-        style.foreground = 'blue'
-        break
-      case 36:
-        style.foreground = 'cyan'
-        break
-      case 39:
-        style.foreground = 'foreground'
-        break
-      default:
-        throw new Error(`dashboard frame line ${line}: unsupported SGR code ${code} in ESC[${raw}m`)
-    }
-  }
-}
-
-function parseLine(value: string, lineNumber: number): ParsedLine {
-  const style: Style = {
-    foreground: 'foreground',
-    bold: false,
-    dim: false,
-  }
-  const runs: TextRun[] = []
-  let text = ''
-  let cells = 0
-
-  const append = (cluster: string, width: number): void => {
-    const previous = runs.at(-1)
-    // ASCII runs may coalesce. Unicode clusters stay independently pinned to
-    // their terminal cell columns so font fallback/advance cannot shift the
-    // run that follows a wide glyph.
-    if (
-      previous !== undefined &&
-      previous.column + previous.cells === cells &&
-      /^[\x20-\x7e]*$/.test(previous.text) &&
-      /^[\x20-\x7e]$/.test(cluster) &&
-      sameStyle(previous.style, style)
-    ) {
-      previous.text += cluster
-      previous.cells += width
-    } else {
-      runs.push({ column: cells, cells: width, text: cluster, style: cloneStyle(style) })
-    }
-    text += cluster
-    cells += width
-  }
-
-  for (let index = 0; index < value.length; ) {
-    if (value[index] === ESC) {
-      const family = value[index + 1]
-      if (family === '[') {
-        const rest = value.slice(index + 2)
-        const match = /^([0-9;]*)m/.exec(rest)
-        if (match === null) {
-          throw new Error(
-            `dashboard frame line ${lineNumber}: unsupported or unterminated CSI sequence`,
-          )
-        }
-        applySgr(style, match[1]!, lineNumber)
-        index += 2 + match[0].length
-        continue
-      }
-      if (family === ']') {
-        const end = value.indexOf(BEL, index + 2)
-        if (end === -1) {
-          throw new Error(`dashboard frame line ${lineNumber}: unterminated OSC sequence`)
-        }
-        const payload = value.slice(index + 2, end)
-        const match = /^8;;(.*)$/.exec(payload)
-        if (match === null) {
-          throw new Error(
-            `dashboard frame line ${lineNumber}: unsupported OSC sequence ${JSON.stringify(payload)}`,
-          )
-        }
-        const href = match[1]!
-        style.href = href === '' ? undefined : href
-        index = end + 1
-        continue
-      }
-      throw new Error(
-        `dashboard frame line ${lineNumber}: unsupported escape family ${JSON.stringify(family ?? '')}`,
-      )
-    }
-
-    const nextEscape = value.indexOf(ESC, index)
-    const stop = nextEscape === -1 ? value.length : nextEscape
-    const plain = value.slice(index, stop)
-    for (const character of plain) {
-      const code = character.codePointAt(0)!
-      if (code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) {
-        throw new Error(
-          `dashboard frame line ${lineNumber}: unsupported control U+${code
-            .toString(16)
-            .toUpperCase()
-            .padStart(4, '0')}`,
-        )
-      }
-    }
-    for (const cluster of graphemes(plain)) append(cluster.text, cluster.width)
-    index = stop
-  }
-
-  if (style.href !== undefined) {
-    throw new Error(`dashboard frame line ${lineNumber}: OSC 8 hyperlink was not closed`)
-  }
-  if (style.foreground !== 'foreground' || style.bold || style.dim) {
-    throw new Error(
-      `dashboard frame line ${lineNumber}: SGR style was not reset before end of line`,
-    )
-  }
-  return { text, cells, runs }
-}
-
-function xml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&apos;')
-}
-
-function svgFor(
-  parsed: ParsedLine[],
-  columns: number,
-): {
-  svg: string
-  width: number
-  height: number
-} {
-  const width = PADDING_X * 2 + columns * CELL_WIDTH
-  const height = PADDING_Y * 2 + Math.max(1, parsed.length) * LINE_HEIGHT
-  const content: string[] = []
-
-  for (const [row, line] of parsed.entries()) {
-    for (const run of line.runs) {
-      const x = PADDING_X + run.column * CELL_WIDTH
-      const y = PADDING_Y + BASELINE + row * LINE_HEIGHT
-      const opacity = run.style.dim ? ' fill-opacity="0.58"' : ''
-      const weight = run.style.bold ? ' font-weight="700"' : ' font-weight="400"'
-      // DejaVu's native advance is slightly narrower than the 10 px evidence
-      // grid. Fit coalesced ASCII runs to their exact terminal cells so the
-      // error cannot accumulate into a visible gap before a pinned Unicode
-      // cluster. Emoji get the same exact fit at a slightly larger size: the
-      // monochrome fallback remains readable without crossing its cell range.
-      const emoji = EMOJI_CLUSTER.test(run.text)
-      const geometry =
-        /^[\x20-\x7e]+$/.test(run.text) || emoji
-          ? ` textLength="${run.cells * CELL_WIDTH}" lengthAdjust="spacingAndGlyphs"`
-          : ''
-      const size = emoji ? ' font-size="18"' : ''
-      const node =
-        `<text x="${x}" y="${y}" fill="${PALETTE[run.style.foreground]}"` +
-        `${weight}${opacity}${geometry}${size}>${xml(run.text)}</text>`
-      content.push(
-        run.style.href === undefined ? node : `<a href="${xml(run.style.href)}">${node}</a>`,
-      )
-    }
-  }
-
-  return {
-    width,
-    height,
-    svg: [
-      `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`,
-      `<rect width="${width}" height="${height}" fill="${PALETTE.background}"/>`,
-      `<g font-family="${FONT_FAMILIES}" font-size="${FONT_SIZE}" xml:space="preserve" text-rendering="geometricPrecision">`,
-      ...content,
-      '</g>',
-      '</svg>',
-    ].join(''),
-  }
-}
-
-function fontFiles(): string[] {
-  const require = createRequire(import.meta.url)
-  const root = dirname(require.resolve('dejavu-fonts-ttf/package.json'))
-  const fallbacks = distributionPath('tools', 'fonts')
-  return [
-    join(root, 'ttf', 'DejaVuSansMono.ttf'),
-    join(root, 'ttf', 'DejaVuSansMono-Bold.ttf'),
-    ...readdirSync(fallbacks)
-      .filter((name) => name.endsWith('.ttf'))
-      .sort()
-      .map((name) => join(fallbacks, name)),
-  ]
-}
-
-/** Parse once, then derive both evidence forms from the same exact cells. */
-export function renderDashboardFrameImage(
-  lines: readonly string[],
-  options: FrameImageOptions,
-): RenderedFrameImage {
-  if (!Number.isInteger(options.columns) || options.columns <= 0) {
-    throw new Error(`dashboard frame columns must be a positive integer, got ${options.columns}`)
-  }
-  if (lines.length === 0) {
-    throw new Error('dashboard frame is empty')
-  }
-  const parsed = lines.map((line, index) => parseLine(line, index + 1))
-  for (const [index, line] of parsed.entries()) {
-    if (line.cells > options.columns) {
-      throw new Error(
-        `dashboard frame line ${index + 1} is ${line.cells} cells wide, exceeding declared terminal width ${options.columns}`,
-      )
-    }
-  }
-
-  const { svg, width, height } = svgFor(parsed, options.columns)
-  const rendered = new Resvg(svg, {
-    fitTo: { mode: 'original' },
-    background: PALETTE.background,
-    font: {
-      fontFiles: fontFiles(),
-      loadSystemFonts: false,
-      defaultFontFamily: FONT_FAMILY,
-      monospaceFamily: FONT_FAMILY,
-      defaultFontSize: FONT_SIZE,
-    },
-    shapeRendering: 2,
-    textRendering: 2,
-    imageRendering: 0,
-    logLevel: 'off',
-  }).render()
-  if (rendered.width !== width || rendered.height !== height) {
-    throw new Error(
-      `dashboard PNG dimensions ${rendered.width}x${rendered.height} did not match SVG ${width}x${height}`,
-    )
-  }
-
-  return {
-    text: `${parsed.map((line) => line.text).join('\n')}\n`,
-    svg,
-    png: new Uint8Array(rendered.asPng()),
-    width,
-    height,
-    rows: lines.length,
-    columns: options.columns,
-  }
-}