tabwright 1.0.0

package/src/replay-handoff.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from 'vitest'
+import type { ReplayAiIndex } from './replay-ai-index.js'
+import {
+  buildReplayCreateCommand,
+  buildReplayIndexCommand,
+  buildReplayMakeCommand,
+  buildReplayRunCommand,
+  replayCapabilityId,
+  toCompactReplayAiIndex,
+} from './replay-handoff.js'
+
+describe('replay handoff', () => {
+  test('builds one canonical capability id from a replay id', () => {
+    expect(replayCapabilityId('2026-07-11T08-09-10-123Z-ABC12345')).toBe('replay-07-11t08-09-10-123z-abc12345')
+    expect(replayCapabilityId('  Demo__Replay / With Spaces  ')).toBe('replay-demo-replay-with-spaces')
+    expect(replayCapabilityId('演示')).toBe('replay-workflow')
+    expect(replayCapabilityId('prefix-abcdefghijklmnopqrstuvwxyz-123456789')).toBe(
+      'replay-ijklmnopqrstuvwxyz-123456789',
+    )
+  })
+
+  test('builds a shell-safe make command with force and json output', () => {
+    expect(
+      buildReplayMakeCommand({
+        replayId: "demo ' $(touch should-not-run)",
+        capabilityId: "capability ' safe",
+        goal: "Repeat user's $(unsafe) workflow",
+      }),
+    ).toBe(
+      "tabwright replay make 'demo '\\'' $(touch should-not-run)' 'capability '\\'' safe' --force --goal 'Repeat user'\\''s $(unsafe) workflow' --json",
+    )
+  })
+
+  test('uses the canonical id and omits goal when none is supplied', () => {
+    expect(buildReplayMakeCommand({ replayId: 'Replay One' })).toBe(
+      "tabwright replay make 'Replay One' 'replay-replay-one' --force --json",
+    )
+    expect(buildReplayMakeCommand({ replayId: 'Replay One', goal: '   ' })).toBe(
+      "tabwright replay make 'Replay One' 'replay-replay-one' --force --json",
+    )
+  })
+
+  test('builds compact and full replay index commands', () => {
+    expect(buildReplayIndexCommand({ replayId: "replay ' one" })).toBe(
+      "tabwright replay index 'replay '\\'' one' --json",
+    )
+    expect(buildReplayIndexCommand({ replayId: 'replay-one', full: true })).toBe(
+      "tabwright replay index 'replay-one' --full --json",
+    )
+  })
+
+  test('builds a shell-safe browser capability scaffold command', () => {
+    expect(buildReplayCreateCommand({ capabilityId: 'replay-one' })).toBe(
+      "tabwright capability create 'replay-one' --project --runtime browser --force --json",
+    )
+    expect(
+      buildReplayCreateCommand({
+        capabilityId: "replay-user's-flow",
+        title: "User's workflow",
+        description: 'Repeat $(unsafe) work',
+      }),
+    ).toBe(
+      "tabwright capability create 'replay-user'\\''s-flow' --project --runtime browser --force --title 'User'\\''s workflow' --description 'Repeat $(unsafe) work' --json",
+    )
+  })
+
+  test('builds a confirmed user-browser run command with the exact capability id', () => {
+    expect(
+      buildReplayRunCommand({
+        capabilityId: "replay-user's-flow",
+        input: { value: "$(echo unsafe) user's value" },
+      }),
+    ).toBe(
+      "tabwright capability run 'replay-user'\\''s-flow' --browser user --force --confirm 'replay-user'\\''s-flow' --input-json '{\"value\":\"$(echo unsafe) user'\\''s value\"}' --json",
+    )
+    expect(buildReplayRunCommand({ capabilityId: 'replay-default' })).toContain('--input-json \'{"value":"..."}\'')
+  })
+
+  test('keeps actionable evidence while replacing bulky replay context with counts', () => {
+    const index: ReplayAiIndex = {
+      schemaVersion: 1,
+      replayId: 'replay-one',
+      url: 'https://example.com/form',
+      generatedAt: 123,
+      stats: {
+        eventCount: 12,
+        fullSnapshotCount: 1,
+        mutationEventCount: 2,
+        clickEventCount: 1,
+        inputEventCount: 1,
+        annotationCount: 1,
+      },
+      actions: [
+        {
+          kind: 'click',
+          timestamp: 124,
+          label: 'Save',
+          node: {
+            id: 7,
+            type: 'element',
+            tagName: 'button',
+            label: 'Save',
+            selectorHints: ['button[data-action="save"]'],
+            ancestorText: [],
+          },
+        },
+      ],
+      fields: [
+        {
+          key: 'title',
+          label: 'Title',
+          selectorHints: ['input[name="title"]'],
+          actionCount: 1,
+          updatedAt: 125,
+        },
+      ],
+      annotations: [
+        {
+          id: 'annotation-one',
+          text: 'This value changes each run.',
+          timestamp: 126,
+          target: {
+            selectorHints: ['input[name="title"]', '[data-testid="title"]'],
+          },
+        },
+      ],
+      interactiveElements: [
+        {
+          id: 8,
+          type: 'element',
+          selectorHints: ['button[data-action="save"]', 'button.primary'],
+          ancestorText: ['Editor'],
+        },
+        {
+          id: 9,
+          type: 'element',
+          selectorHints: [],
+          ancestorText: [],
+        },
+      ],
+      pageText: ['A very large page text block', 'Another large block'],
+      warnings: ['The page changed during the replay.'],
+    }
+
+    const compact = toCompactReplayAiIndex(index)
+
+    expect(compact).toMatchObject({
+      replayId: 'replay-one',
+      stats: index.stats,
+      actions: index.actions,
+      fields: index.fields,
+      annotations: index.annotations,
+      warnings: index.warnings,
+      selectorHints: ['button[data-action="save"]', 'input[name="title"]', '[data-testid="title"]', 'button.primary'],
+      omitted: {
+        interactiveElements: 2,
+        pageText: 2,
+      },
+    })
+    expect(compact).not.toHaveProperty('interactiveElements')
+    expect(compact).not.toHaveProperty('pageText')
+  })
+})

package/src/replay-handoff.ts

@@ -0,0 +1,109 @@
+import type { ReplayAiIndex } from './replay-ai-index.js'
+
+export type CompactReplayAiIndex = Omit<ReplayAiIndex, 'interactiveElements' | 'pageText'> & {
+  selectorHints: string[]
+  omitted: {
+    interactiveElements: number
+    pageText: number
+  }
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+export function replayCapabilityId(replayId: string): string {
+  const normalized = replayId
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  const suffix = normalized.slice(-28).replace(/^-+|-+$/g, '') || 'workflow'
+  return `replay-${suffix}`
+}
+
+export function buildReplayIndexCommand(options: { replayId: string; full?: boolean }): string {
+  return ['tabwright replay index', shellQuote(options.replayId), ...(options.full ? ['--full'] : []), '--json'].join(
+    ' ',
+  )
+}
+
+export function buildReplayCreateCommand(options: {
+  capabilityId: string
+  title?: string
+  description?: string
+}): string {
+  const titleArgs: string[] = options.title?.trim() ? ['--title', shellQuote(options.title)] : []
+  const descriptionArgs: string[] = options.description?.trim() ? ['--description', shellQuote(options.description)] : []
+  return [
+    'tabwright capability create',
+    shellQuote(options.capabilityId),
+    '--project',
+    '--runtime browser',
+    '--force',
+    ...titleArgs,
+    ...descriptionArgs,
+    '--json',
+  ].join(' ')
+}
+
+export function buildReplayMakeCommand(options: { replayId: string; capabilityId?: string; goal?: string }): string {
+  const capabilityId = options.capabilityId || replayCapabilityId(options.replayId)
+  const goalArgs: string[] = options.goal?.trim() ? ['--goal', shellQuote(options.goal)] : []
+  return [
+    'tabwright replay make',
+    shellQuote(options.replayId),
+    shellQuote(capabilityId),
+    '--force',
+    ...goalArgs,
+    '--json',
+  ].join(' ')
+}
+
+export function buildReplayRunCommand(options: { capabilityId: string; input?: Record<string, unknown> }): string {
+  const input = options.input || { value: '...' }
+  return [
+    'tabwright capability run',
+    shellQuote(options.capabilityId),
+    '--browser user',
+    '--force',
+    '--confirm',
+    shellQuote(options.capabilityId),
+    '--input-json',
+    shellQuote(JSON.stringify(input)),
+    '--json',
+  ].join(' ')
+}
+
+export function toCompactReplayAiIndex(index: ReplayAiIndex): CompactReplayAiIndex {
+  const { interactiveElements, pageText, ...core } = index
+  const selectorHints: string[] = Array.from(
+    new Set(
+      [
+        ...index.actions.flatMap((action) => {
+          return action.node?.selectorHints || []
+        }),
+        ...index.fields.flatMap((field) => {
+          return field.selectorHints
+        }),
+        ...index.annotations.flatMap((annotation) => {
+          return annotation.target?.selectorHints || []
+        }),
+        ...interactiveElements.flatMap((element) => {
+          return element.selectorHints
+        }),
+      ].filter((hint) => {
+        return hint.length > 0
+      }),
+    ),
+  )
+
+  return {
+    ...core,
+    selectorHints,
+    omitted: {
+      interactiveElements: interactiveElements.length,
+      pageText: pageText.length,
+    },
+  }
+}

package/src/replay-workflow-compiler.test.ts

@@ -0,0 +1,250 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { afterEach, describe, expect, test } from 'vitest'
+import { readCapabilityScript } from './capability-registry.js'
+import {
+  analyzeReplayWorkflow,
+  compileReplayWorkflow,
+  UnsupportedReplayWorkflowError,
+} from './replay-workflow-compiler.js'
+import type { RrwebEvent } from './protocol.js'
+
+let previousHome: string | undefined
+let testHome: string | null = null
+
+function createTempDir(prefix: string): string {
+  const tempRoot = path.join(process.cwd(), 'tmp')
+  fs.mkdirSync(tempRoot, { recursive: true })
+  return fs.mkdtempSync(path.join(tempRoot, prefix))
+}
+
+function useTempHome(): string {
+  previousHome = process.env.HOME
+  testHome = createTempDir('replay-workflow-compiler-home-')
+  process.env.HOME = testHome
+  return testHome
+}
+
+function writeJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+function textNode(id: number, textContent: string): Record<string, unknown> {
+  return { id, type: 3, textContent }
+}
+
+function elementNode(options: {
+  id: number
+  tagName: string
+  attributes?: Record<string, string>
+  childNodes?: Array<Record<string, unknown>>
+}): Record<string, unknown> {
+  return {
+    id: options.id,
+    type: 2,
+    tagName: options.tagName,
+    attributes: options.attributes || {},
+    childNodes: options.childNodes || [],
+  }
+}
+
+function clickEvent(options: { timestamp: number; id: number }): RrwebEvent {
+  return {
+    type: 3,
+    timestamp: options.timestamp,
+    data: {
+      source: 2,
+      type: 2,
+      id: options.id,
+      x: 10,
+      y: 10,
+      pointerType: 0,
+    },
+  }
+}
+
+function inputEvent(options: { timestamp: number; id: number; text: string }): RrwebEvent {
+  return {
+    type: 3,
+    timestamp: options.timestamp,
+    data: {
+      source: 5,
+      id: options.id,
+      text: options.text,
+      isChecked: false,
+    },
+  }
+}
+
+function createListAppendReplayEvents(): RrwebEvent[] {
+  return [
+    {
+      type: 2,
+      timestamp: 1000,
+      data: {
+        node: {
+          id: 1,
+          type: 0,
+          childNodes: [
+            {
+              id: 2,
+              type: 1,
+              childNodes: [
+                elementNode({
+                  id: 3,
+                  tagName: 'body',
+                  childNodes: [
+                    elementNode({ id: 10, tagName: 'button', childNodes: [textNode(11, '编辑')] }),
+                    elementNode({
+                      id: 12,
+                      tagName: 'button',
+                      attributes: { class: 'designer-formily-array-base-addition' },
+                    }),
+                    elementNode({ id: 14, tagName: 'textarea', attributes: { class: 'designer-input' } }),
+                    elementNode({ id: 16, tagName: 'button', childNodes: [textNode(17, '提交')] }),
+                    elementNode({ id: 18, tagName: 'button', childNodes: [textNode(19, 'OK')] }),
+                  ],
+                }),
+              ],
+            },
+          ],
+        },
+      },
+    },
+    clickEvent({ timestamp: 1100, id: 10 }),
+    clickEvent({ timestamp: 1200, id: 12 }),
+    inputEvent({ timestamp: 1300, id: 14, text: 'test2' }),
+    clickEvent({ timestamp: 1400, id: 16 }),
+    clickEvent({ timestamp: 1500, id: 18 }),
+  ]
+}
+
+afterEach(() => {
+  if (previousHome === undefined) {
+    delete process.env.HOME
+  } else {
+    process.env.HOME = previousHome
+  }
+  previousHome = undefined
+
+  if (testHome) {
+    fs.rmSync(testHome, { recursive: true, force: true })
+    testHome = null
+  }
+})
+
+describe('replay workflow compiler', () => {
+  test('infers a list append script from rrweb DOM events', () => {
+    const home = useTempHome()
+    const cwd = createTempDir('replay-workflow-compiler-cwd-')
+    const replayPath = path.join(home, '.tabwright', 'rrweb-recordings', 'replay-list-add.json')
+    const events = createListAppendReplayEvents()
+    writeJson(replayPath, events)
+    writeJson(path.join(home, '.tabwright', 'rrweb-recordings', 'index.json'), [
+      {
+        id: 'replay-list-add',
+        path: replayPath,
+        startedAt: 1000,
+        savedAt: 2000,
+        duration: 1000,
+        size: 100,
+        eventCount: events.length,
+        tabId: 1,
+        url: 'https://admin.example.com/#/config?key=config_demo_simple_COPY123',
+      },
+    ])
+
+    try {
+      const analysis = analyzeReplayWorkflow({
+        replayId: 'replay-list-add',
+        url: 'https://admin.example.com/#/config?key=config_demo_simple_COPY123',
+        events,
+      })
+      expect(analysis).toMatchObject({
+        actionKind: 'list-append',
+        demonstratedValue: 'test2',
+        confidence: 'high',
+      })
+      expect(analysis.clickedTexts).toEqual(expect.arrayContaining(['编辑', 'Add entry', '提交', 'OK']))
+
+      const compiled = compileReplayWorkflow({
+        replayId: 'replay-list-add',
+        id: 'compiled-list-add',
+        cwd,
+        overwrite: true,
+      })
+      const script = readCapabilityScript({ id: 'compiled-list-add', cwd })
+
+      expect(compiled.analysis.actionKind).toBe('list-append')
+      expect(script).toContain('replayWorkflow.compile')
+      expect(script).toContain('button:has-text(\\"Add entry\\")')
+      expect(script).toContain('const expectedPageKey = "config_demo_simple_COPY123"')
+      expect(script).toContain('needs_ai')
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+
+  test('throws a structured error before saving an unsupported workflow', () => {
+    const home = useTempHome()
+    const cwd = createTempDir('replay-workflow-compiler-unsupported-cwd-')
+    const replayPath = path.join(home, '.tabwright', 'rrweb-recordings', 'replay-unsupported.json')
+    const events: RrwebEvent[] = [
+      {
+        type: 2,
+        timestamp: 1000,
+        data: {
+          node: {
+            id: 1,
+            type: 0,
+            childNodes: [],
+          },
+        },
+      },
+    ]
+    writeJson(replayPath, events)
+    writeJson(path.join(home, '.tabwright', 'rrweb-recordings', 'index.json'), [
+      {
+        id: 'replay-unsupported',
+        path: replayPath,
+        startedAt: 1000,
+        savedAt: 2000,
+        duration: 1000,
+        size: 100,
+        eventCount: events.length,
+        tabId: 1,
+        url: 'https://example.com/',
+      },
+    ])
+
+    try {
+      let thrown: unknown
+      try {
+        compileReplayWorkflow({
+          replayId: 'replay-unsupported',
+          id: 'unsupported-workflow',
+          cwd,
+          overwrite: true,
+        })
+      } catch (error) {
+        thrown = error
+      }
+
+      expect(thrown).toBeInstanceOf(UnsupportedReplayWorkflowError)
+      if (!(thrown instanceof UnsupportedReplayWorkflowError)) {
+        throw new Error('Expected UnsupportedReplayWorkflowError')
+      }
+      expect(thrown.analysis.actionKind).toBe('unknown')
+      expect(thrown.analysis.reasons).toEqual(
+        expect.arrayContaining(['Could not classify the replay into a known workflow template.']),
+      )
+      expect(thrown.message).toBe(
+        `Replay compiler could not infer a supported workflow: ${thrown.analysis.reasons.join(' ')}`,
+      )
+      expect(fs.existsSync(path.join(cwd, '.tabwright', 'capabilities', 'unsupported-workflow'))).toBe(false)
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+})