@devosurf/vynt 0.1.2

package/src/cli.ts

@@ -0,0 +1,1449 @@
+import { execFile } from "node:child_process"
+import { access, mkdir, readFile, writeFile } from "node:fs/promises"
+import { basename, join, resolve } from "node:path"
+import process from "node:process"
+import { createInterface } from "node:readline/promises"
+import { promisify } from "node:util"
+import { Command, CommanderError } from "commander"
+import { startBridgeServer } from "./bridge.js"
+import { applySelectionsToWorkspace, getLatestSnapshot, rollbackWorkspaceToSnapshot } from "./switch.js"
+import { createEmptyStore, loadState, saveState, upsertObjective, upsertProfile, upsertVariant } from "./state.js"
+import type { Objective, PreviewProfile, VariantArtifact, VariantStore } from "./types.js"
+
+const execFileAsync = promisify(execFile)
+
+interface AddCommandOptions {
+  files?: string
+  notes?: string
+  session?: string
+}
+
+interface OpenCodeRegisterOptions {
+  files?: string
+  notes?: string
+  quiet?: boolean
+}
+
+interface OpenCodeRegisterAutoOptions extends OpenCodeRegisterOptions {
+  objective?: string
+}
+
+interface OpenCodeCaptureOptions {
+  objective?: string
+  notes?: string
+  quiet?: boolean
+  reset?: boolean
+}
+
+interface AutoResolvedObjective {
+  nextState: VariantStore
+  objective: Objective
+  autoCreated: boolean
+}
+
+interface JsonOutputOption {
+  json?: boolean
+}
+
+interface IdOption {
+  id?: string
+}
+
+interface ApplyCommandOptions {
+  objective?: string
+  review?: boolean
+  variant?: string
+}
+
+interface BridgeServeOptions {
+  host?: string
+  port?: string
+}
+
+function slugify(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "")
+}
+
+function makeVariantId(name: string): string {
+  return `${slugify(name)}-${Date.now().toString(36)}`
+}
+
+function makeObjectiveId(name: string): string {
+  return slugify(name)
+}
+
+function makeProfileId(name: string): string {
+  return slugify(name)
+}
+
+async function runGitRaw(cwd: string, args: string[]): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      cwd,
+      encoding: "utf8",
+    })
+    return stdout
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`git ${args.join(" ")} failed: ${message}`)
+  }
+}
+
+async function runGit(cwd: string, args: string[]): Promise<string> {
+  return (await runGitRaw(cwd, args)).trim()
+}
+
+async function resolveBaseRef(cwd: string, baseRef: string): Promise<string> {
+  const candidate = baseRef.trim()
+  if (candidate.length === 0) {
+    throw new Error("base ref cannot be empty")
+  }
+
+  try {
+    return await runGit(cwd, ["rev-parse", "--verify", `${candidate}^{commit}`])
+  } catch {
+    return candidate
+  }
+}
+
+function parseChangedFiles(files: string | undefined): string[] {
+  if (!files || files.trim().length === 0) {
+    return []
+  }
+
+  return files
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+}
+
+async function inferChangedFilesFromPatch(patchFile: string): Promise<string[]> {
+  const raw = await readFile(patchFile, "utf8")
+  const files = new Set<string>()
+
+  for (const line of raw.split(/\r?\n/g)) {
+    if (!line.startsWith("+++ ")) continue
+
+    const source = line.slice(4).trim()
+    if (source === "/dev/null" || source.length === 0) continue
+
+    const normalized = source.startsWith("b/") ? source.slice(2) : source
+    if (normalized.length > 0) {
+      files.add(normalized)
+    }
+  }
+
+  return [...files]
+}
+
+const OBJECTIVE_MARKER_EXTENSIONS = new Set([
+  ".html",
+  ".htm",
+  ".xhtml",
+  ".tsx",
+  ".jsx",
+  ".vue",
+  ".svelte",
+  ".astro",
+])
+
+function hasObjectiveMarkupFile(changedFiles: string[]): boolean {
+  return changedFiles.some((filePath) => {
+    const normalized = normalizeRepoPath(filePath).toLowerCase()
+    const dot = normalized.lastIndexOf(".")
+    if (dot < 0) return false
+    const ext = normalized.slice(dot)
+    return OBJECTIVE_MARKER_EXTENSIONS.has(ext)
+  })
+}
+
+function escapeRegex(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function patchContainsObjectiveMarker(patchContent: string, objectiveId: string): boolean {
+  const escapedObjective = escapeRegex(objectiveId)
+  const directAttribute = new RegExp(
+    `data-vynt-objective\\s*=\\s*["']${escapedObjective}["']`,
+    "i",
+  )
+  if (directAttribute.test(patchContent)) return true
+
+  const jsxLiteralAttribute = new RegExp(
+    `data-vynt-objective\\s*=\\s*\\{\\s*["']${escapedObjective}["']\\s*\\}`,
+    "i",
+  )
+  return jsxLiteralAttribute.test(patchContent)
+}
+
+async function validateObjectiveMarkerForAutoRegister(
+  patchFile: string,
+  objectiveId: string,
+  changedFiles: string[],
+): Promise<void> {
+  if (!hasObjectiveMarkupFile(changedFiles)) return
+
+  const patchContent = await readFile(patchFile, "utf8")
+  if (patchContainsObjectiveMarker(patchContent, objectiveId)) return
+
+  throw new Error(
+    [
+      `Objective marker contract failed for objective ${objectiveId}.`,
+      "Changed files include UI markup but patch is missing data-vynt-objective.",
+      `Add data-vynt-objective=\"${objectiveId}\" on the objective wrapper container in this variant.`,
+    ].join(" "),
+  )
+}
+
+function makePatchFileName(sessionId: string): string {
+  const safeSession = slugify(sessionId).slice(0, 12) || "session"
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
+  return `capture-${timestamp}-${safeSession}.patch`
+}
+
+async function captureCurrentDiffAsPatch(
+  cwd: string,
+  sessionId: string,
+): Promise<{ patchPath: string; changedFiles: string[] }> {
+  const changedFilesRaw = await runGit(cwd, ["diff", "--name-only"])
+  const changedFiles = changedFilesRaw
+    .split("\n")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+
+  if (changedFiles.length === 0) {
+    throw new Error("No tracked changes to capture. Make edits before running opencode capture.")
+  }
+
+  const patchContent = await runGitRaw(cwd, ["diff", "--binary"])
+  if (patchContent.trim().length === 0) {
+    throw new Error("Could not create patch from current diff")
+  }
+
+  const patchDir = join(cwd, ".vynt", "patches")
+  await mkdir(patchDir, { recursive: true })
+
+  const patchPath = join(patchDir, makePatchFileName(sessionId))
+  const patchPayload = patchContent.endsWith("\n") ? patchContent : `${patchContent}\n`
+  await writeFile(patchPath, patchPayload, "utf8")
+
+  return { patchPath, changedFiles }
+}
+
+async function restoreWorkspaceToBaseRef(cwd: string, baseRef: string): Promise<void> {
+  await runGit(cwd, ["restore", `--source=${baseRef}`, "--staged", "--worktree", "."])
+  await runGit(cwd, ["clean", "-fd"])
+}
+
+const COMMON_OBJECTIVE_TOKENS = new Set([
+  "src",
+  "app",
+  "apps",
+  "lib",
+  "libs",
+  "utils",
+  "shared",
+  "components",
+  "component",
+  "page",
+  "layout",
+  "index",
+  "main",
+  "style",
+  "styles",
+  "css",
+  "ts",
+  "tsx",
+  "js",
+  "jsx",
+])
+
+function normalizeRepoPath(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "")
+}
+
+function splitTokens(input: string): string[] {
+  return input
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2 && !COMMON_OBJECTIVE_TOKENS.has(token))
+}
+
+function objectiveTokenSet(objective: Objective): Set<string> {
+  const tokens = new Set<string>()
+  for (const token of splitTokens(`${objective.id} ${objective.name}`)) {
+    tokens.add(token)
+  }
+  return tokens
+}
+
+function fileDir(filePath: string): string {
+  const normalized = normalizeRepoPath(filePath)
+  const index = normalized.lastIndexOf("/")
+  if (index <= 0) return ""
+  return normalized.slice(0, index)
+}
+
+function scoreObjectiveAgainstFiles(objective: Objective, changedFiles: string[]): number {
+  if (changedFiles.length === 0) return 0
+
+  const objectiveFiles = new Set(
+    objective.variants.flatMap((variant) => variant.changedFiles).map((file) => normalizeRepoPath(file).toLowerCase()),
+  )
+  const objectiveDirs = new Set(
+    objective.variants.map((variant) => variant.changedFiles).flat().map((file) => fileDir(file).toLowerCase()),
+  )
+  const objectiveTokens = objectiveTokenSet(objective)
+
+  let score = 0
+  const matchedTokens = new Set<string>()
+
+  for (const file of changedFiles.map((item) => normalizeRepoPath(item).toLowerCase())) {
+    if (objectiveFiles.has(file)) {
+      score += 12
+    }
+
+    const directory = fileDir(file)
+    if (directory.length > 0 && objectiveDirs.has(directory)) {
+      score += 6
+    }
+
+    for (const token of splitTokens(file)) {
+      if (objectiveTokens.has(token) && !matchedTokens.has(token)) {
+        matchedTokens.add(token)
+        score += 2
+      }
+    }
+  }
+
+  return score
+}
+
+function inferObjectiveId(state: VariantStore, changedFiles: string[]): string | undefined {
+  if (state.objectives.length === 0) return undefined
+  if (state.objectives.length === 1) return state.objectives[0]?.id
+
+  const ranked = state.objectives
+    .map((objective) => ({
+      objective,
+      score: scoreObjectiveAgainstFiles(objective, changedFiles),
+    }))
+    .sort((left, right) => right.score - left.score)
+
+  const top = ranked[0]
+  const next = ranked[1]
+
+  if (!top || top.score <= 0) return undefined
+  if (next && next.score === top.score) return undefined
+
+  return top.objective.id
+}
+
+function extractObjectiveSeed(changedFiles: string[], variantName: string): string {
+  for (const file of changedFiles) {
+    const normalized = normalizeRepoPath(file)
+    const segments = normalized.split("/").filter(Boolean)
+    const fileName = segments[segments.length - 1]
+    const baseName = fileName ? fileName.replace(/\.[^.]+$/, "") : ""
+
+    for (const candidate of [baseName, segments[segments.length - 2], segments[segments.length - 3]]) {
+      if (!candidate) continue
+      const tokenized = splitTokens(candidate)
+      if (tokenized.length > 0) {
+        return tokenized.join("-")
+      }
+    }
+  }
+
+  const fromName = splitTokens(variantName)
+  if (fromName.length > 0) return fromName.join("-")
+  return "auto-objective"
+}
+
+function toTitleCase(input: string): string {
+  return input
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part[0]?.toUpperCase() + part.slice(1))
+    .join(" ")
+}
+
+function ensureUniqueObjectiveId(state: VariantStore, baseId: string): string {
+  const existing = new Set(state.objectives.map((objective) => objective.id))
+  if (!existing.has(baseId)) return baseId
+
+  let index = 2
+  while (existing.has(`${baseId}-${index}`)) {
+    index += 1
+  }
+  return `${baseId}-${index}`
+}
+
+function createAutoObjective(state: VariantStore, seed: string): { nextState: VariantStore; objective: Objective } {
+  const rawId = slugify(seed)
+  const baseId = rawId.length > 0 ? rawId : "auto-objective"
+  const objectiveId = ensureUniqueObjectiveId(state, baseId)
+  const now = new Date().toISOString()
+
+  const objective: Objective = {
+    id: objectiveId,
+    name: `Auto ${toTitleCase(objectiveId)}`,
+    baseRef: state.baseRef,
+    status: "open",
+    variants: [],
+    createdAt: now,
+    updatedAt: now,
+  }
+
+  return {
+    nextState: upsertObjective(state, objective),
+    objective,
+  }
+}
+
+function resolveObjectiveForAutoRegister(
+  state: VariantStore,
+  changedFiles: string[],
+  variantName: string,
+  explicitObjectiveId?: string,
+): AutoResolvedObjective {
+  if (explicitObjectiveId && explicitObjectiveId.trim().length > 0) {
+    const normalizedId = ensureNonEmptyId(explicitObjectiveId.trim(), "objective id")
+    const existing = state.objectives.find((objective) => objective.id === normalizedId)
+    if (existing) {
+      return { nextState: state, objective: existing, autoCreated: false }
+    }
+
+    const { nextState, objective } = createAutoObjective(state, normalizedId)
+    return { nextState, objective, autoCreated: true }
+  }
+
+  const inferredId = inferObjectiveId(state, changedFiles)
+  if (inferredId) {
+    return { nextState: state, objective: findObjective(state, inferredId), autoCreated: false }
+  }
+
+  const seed = extractObjectiveSeed(changedFiles, variantName)
+  const { nextState, objective } = createAutoObjective(state, seed)
+  return { nextState, objective, autoCreated: true }
+}
+
+async function registerOpenCodeVariant(
+  cwd: string,
+  state: VariantStore,
+  sessionId: string,
+  name: string,
+  patchInput: string,
+  options: OpenCodeRegisterAutoOptions,
+): Promise<{ nextState: VariantStore; variant: VariantArtifact; resolvedObjective: Objective; autoCreated: boolean }> {
+  const patchFile = resolve(cwd, patchInput)
+  await assertFileExists(patchFile)
+
+  const explicitChangedFiles = parseChangedFiles(options.files)
+  const changedFiles = explicitChangedFiles.length > 0 ? explicitChangedFiles : await inferChangedFilesFromPatch(patchFile)
+  const resolved = resolveObjectiveForAutoRegister(state, changedFiles, name, options.objective)
+  await validateObjectiveMarkerForAutoRegister(patchFile, resolved.objective.id, changedFiles)
+  const registration = await registerVariantArtifact(cwd, resolved.nextState, resolved.objective.id, name, patchInput, {
+    files: changedFiles.join(","),
+    notes: options.notes,
+    session: sessionId,
+  })
+
+  return {
+    nextState: registration.nextState,
+    variant: registration.variant,
+    resolvedObjective: resolved.objective,
+    autoCreated: resolved.autoCreated,
+  }
+}
+
+async function assertFileExists(filePath: string): Promise<void> {
+  await access(filePath)
+}
+
+async function registerVariantArtifact(
+  cwd: string,
+  state: VariantStore,
+  objectiveId: string,
+  name: string,
+  patchInput: string,
+  options: AddCommandOptions,
+): Promise<{ nextState: VariantStore; variant: VariantArtifact }> {
+  const targetObjective = findObjective(state, objectiveId)
+  const patchFile = resolve(cwd, patchInput)
+  await assertFileExists(patchFile)
+
+  const explicitChangedFiles = parseChangedFiles(options.files)
+  const changedFiles = explicitChangedFiles.length > 0 ? explicitChangedFiles : await inferChangedFilesFromPatch(patchFile)
+
+  const now = new Date().toISOString()
+  const variant: VariantArtifact = {
+    id: makeVariantId(name),
+    objectiveId,
+    name,
+    baseRef: state.baseRef,
+    patchFile,
+    changedFiles,
+    sessionId: options.session,
+    screenshots: [],
+    notes: options.notes,
+    status: "ready",
+    createdAt: now,
+    updatedAt: now,
+  }
+
+  const nextState = upsertVariant(state, variant)
+  const nextObjective = findObjective(nextState, targetObjective.id)
+  const objectiveStatus = nextObjective.status === "open" ? "review" : nextObjective.status
+  const finalState = upsertObjective(nextState, {
+    ...nextObjective,
+    status: objectiveStatus,
+    updatedAt: now,
+  })
+
+  return {
+    nextState: finalState,
+    variant,
+  }
+}
+
+function requireState(state: VariantStore | undefined): VariantStore {
+  if (!state) {
+    throw new Error("Variant store not initialized. Run: init <base-ref>")
+  }
+  return state
+}
+
+function findObjective(state: VariantStore, objectiveId: string): Objective {
+  const found = state.objectives.find((objective) => objective.id === objectiveId)
+  if (!found) {
+    throw new Error(`Objective not found: ${objectiveId}`)
+  }
+  return found
+}
+
+function findVariant(objective: Objective, variantId: string): VariantArtifact {
+  const found = objective.variants.find((variant) => variant.id === variantId)
+  if (!found) {
+    throw new Error(`Variant not found in objective ${objective.id}: ${variantId}`)
+  }
+  return found
+}
+
+function findProfile(state: VariantStore, profileId: string): PreviewProfile {
+  const found = state.profiles.find((profile) => profile.id === profileId)
+  if (!found) {
+    throw new Error(`Profile not found: ${profileId}`)
+  }
+  return found
+}
+
+function findVariantAcrossObjectives(
+  state: VariantStore,
+  variantId: string,
+): { objective: Objective; variant: VariantArtifact } {
+  const matches: Array<{ objective: Objective; variant: VariantArtifact }> = []
+
+  for (const objective of state.objectives) {
+    const variant = objective.variants.find((item) => item.id === variantId)
+    if (variant) {
+      matches.push({ objective, variant })
+    }
+  }
+
+  if (matches.length === 0) {
+    throw new Error(`Variant not found: ${variantId}`)
+  }
+
+  if (matches.length > 1) {
+    const objectiveIds = matches.map((item) => item.objective.id).join(", ")
+    throw new Error(
+      `Variant id ${variantId} is ambiguous across objectives (${objectiveIds}). Use: apply --objective <objective-id> --variant <variant-id>`,
+    )
+  }
+
+  return matches[0] as { objective: Objective; variant: VariantArtifact }
+}
+
+function resolveApplyTarget(
+  state: VariantStore,
+  variantIdArg: string | undefined,
+  options: ApplyCommandOptions,
+): { objective: Objective; variant: VariantArtifact } {
+  const hasObjective = typeof options.objective === "string" && options.objective.trim().length > 0
+  const hasVariantOption = typeof options.variant === "string" && options.variant.trim().length > 0
+
+  if (variantIdArg && (hasObjective || hasVariantOption)) {
+    throw new Error(
+      "Use either positional apply <variant-id> OR apply --objective <objective-id> --variant <variant-id>",
+    )
+  }
+
+  if (variantIdArg) {
+    return findVariantAcrossObjectives(state, variantIdArg)
+  }
+
+  if (!hasObjective || !hasVariantOption) {
+    throw new Error(
+      "apply requires either <variant-id> or both --objective <objective-id> and --variant <variant-id>",
+    )
+  }
+
+  const objectiveItem = findObjective(state, options.objective as string)
+  const variantItem = findVariant(objectiveItem, options.variant as string)
+  return { objective: objectiveItem, variant: variantItem }
+}
+
+function markVariantSelectedInState(state: VariantStore, objectiveId: string, variantId: string): VariantStore {
+  const objectiveItem = findObjective(state, objectiveId)
+  const now = new Date().toISOString()
+
+  const nextObjective = upsertObjective(state, {
+    ...objectiveItem,
+    activeVariantId: variantId,
+    status: objectiveItem.status === "open" ? "review" : objectiveItem.status,
+    updatedAt: now,
+    variants: objectiveItem.variants.map((item) => {
+      if (item.id === variantId) {
+        return {
+          ...item,
+          status: "selected" as const,
+          updatedAt: now,
+        }
+      }
+
+      if (item.status === "selected") {
+        return {
+          ...item,
+          status: "ready" as const,
+          updatedAt: now,
+        }
+      }
+
+      return item
+    }),
+  })
+
+  return {
+    ...nextObjective,
+    activeProfileId: undefined,
+  }
+}
+
+function clearActiveSelections(state: VariantStore): VariantStore {
+  const now = new Date().toISOString()
+
+  return {
+    ...state,
+    activeProfileId: undefined,
+    objectives: state.objectives.map((objectiveItem) => ({
+      ...objectiveItem,
+      activeVariantId: undefined,
+      updatedAt: now,
+      variants: objectiveItem.variants.map((variant) => {
+        if (variant.status !== "selected") return variant
+        return {
+          ...variant,
+          status: "ready" as const,
+          updatedAt: now,
+        }
+      }),
+    })),
+  }
+}
+
+function collectActiveSelectionChangedFiles(state: VariantStore): string[] {
+  const files = new Set<string>()
+
+  for (const objective of state.objectives) {
+    if (!objective.activeVariantId) continue
+    const activeVariant = objective.variants.find((variant) => variant.id === objective.activeVariantId)
+    if (!activeVariant) continue
+
+    for (const file of activeVariant.changedFiles) {
+      files.add(file)
+    }
+  }
+
+  return [...files]
+}
+
+function snapshotIdFromPath(snapshotPath: string): string | undefined {
+  const fileName = basename(snapshotPath)
+  if (!fileName.endsWith(".json")) return undefined
+  return fileName.slice(0, -".json".length)
+}
+
+async function waitForReviewConfirmation(): Promise<void> {
+  const input = process.stdin
+  const output = process.stdout
+  const reader = createInterface({
+    input,
+    output,
+  })
+
+  try {
+    await reader.question("Review in browser, then press Enter to rollback to baseline... ")
+  } finally {
+    reader.close()
+  }
+}
+
+async function rollbackAndResetState(
+  cwd: string,
+  state: VariantStore,
+  snapshotId?: string,
+): Promise<{ nextState: VariantStore; snapshotHead: string; snapshotId: string }> {
+  const { snapshot } = await rollbackWorkspaceToSnapshot(cwd, snapshotId, {
+    allowDirtyFiles: collectActiveSelectionChangedFiles(state),
+  })
+  return {
+    nextState: clearActiveSelections(state),
+    snapshotHead: snapshot.head,
+    snapshotId: snapshot.id,
+  }
+}
+
+function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+function ensureNonEmptyId(input: string, field: string): string {
+  if (input.trim().length === 0) {
+    throw new Error(`${field} cannot be empty`)
+  }
+  return input
+}
+
+function ensureUniqueId(existing: string[], candidate: string, kind: string): void {
+  if (existing.includes(candidate)) {
+    throw new Error(`${kind} already exists: ${candidate}`)
+  }
+}
+
+function formatSelections(selections: Record<string, string>): string {
+  const entries = Object.entries(selections)
+  if (entries.length === 0) return "-"
+  return entries
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([objectiveId, variantId]) => `${objectiveId}=${variantId}`)
+    .join(", ")
+}
+
+function parsePortOption(value: string | undefined, defaultPort: number): number {
+  if (!value) return defaultPort
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+    throw new Error(`Invalid port: ${value}`)
+  }
+  return parsed
+}
+
+function createProgram(cwd: string): Command {
+  const program = new Command()
+
+  program
+    .name("vynt")
+    .description("vynt CLI")
+    .exitOverride()
+    .configureOutput({
+      outputError: () => undefined,
+    })
+    .showSuggestionAfterError()
+
+  program.command("init <base-ref>").description("Initialize variant store").action(async (baseRef: string) => {
+    const existing = await loadState(cwd)
+    if (existing) {
+      throw new Error("Variant store already exists in this directory")
+    }
+
+    const resolvedBaseRef = await resolveBaseRef(cwd, baseRef)
+    await saveState(cwd, createEmptyStore(cwd, resolvedBaseRef))
+    process.stdout.write(`Initialized variant store with base ref: ${resolvedBaseRef}\n`)
+  })
+
+  const objective = program.command("objective").description("Manage objectives")
+
+  objective
+    .command("create <name>")
+    .description("Create a new objective")
+    .option("--id <id>", "Explicit objective id")
+    .action(async (name: string, options: IdOption) => {
+      const state = requireState(await loadState(cwd))
+      const candidate = options.id ?? makeObjectiveId(name)
+      const objectiveId = ensureNonEmptyId(candidate, "objective id")
+
+      ensureUniqueId(
+        state.objectives.map((item) => item.id),
+        objectiveId,
+        "Objective",
+      )
+
+      const now = new Date().toISOString()
+      const next = upsertObjective(state, {
+        id: objectiveId,
+        name,
+        baseRef: state.baseRef,
+        status: "open",
+        variants: [],
+        createdAt: now,
+        updatedAt: now,
+      })
+
+      await saveState(cwd, next)
+      process.stdout.write(`Created objective ${objectiveId}\n`)
+    })
+
+  objective
+    .command("list")
+    .description("List objectives")
+    .option("--json", "Output as JSON")
+    .action(async (options: JsonOutputOption) => {
+      const state = requireState(await loadState(cwd))
+      if (options.json) {
+        printJson(state.objectives)
+        return
+      }
+
+      if (state.objectives.length === 0) {
+        process.stdout.write("No objectives\n")
+        return
+      }
+
+      const lines = state.objectives.map(
+        (item) =>
+          `${item.id} | ${item.status} | active=${item.activeVariantId ?? "-"} | winner=${item.winnerVariantId ?? "-"} | variants=${item.variants.length} | ${item.name}`,
+      )
+      process.stdout.write(lines.join("\n") + "\n")
+    })
+
+  objective
+    .command("finalize <objective-id> <variant-id>")
+    .description("Set winner for an objective")
+    .action(async (objectiveId: string, variantId: string) => {
+      const state = requireState(await loadState(cwd))
+      const current = findObjective(state, objectiveId)
+      findVariant(current, variantId)
+
+      const now = new Date().toISOString()
+      const next = upsertObjective(state, {
+        ...current,
+        status: "finalized",
+        winnerVariantId: variantId,
+        activeVariantId: current.activeVariantId ?? variantId,
+        updatedAt: now,
+      })
+
+      await saveState(cwd, next)
+      process.stdout.write(`Objective ${objectiveId} finalized with winner ${variantId}\n`)
+    })
+
+  program
+    .command("add <objective-id> <name> <patch-file>")
+    .description("Register a variant artifact under an objective")
+    .option("--files <files>", "Comma-separated changed files")
+    .option("--session <id>", "Session ID")
+    .option("--notes <text>", "Additional notes")
+    .action(async (objectiveId: string, name: string, patchInput: string, options: AddCommandOptions) => {
+      const state = requireState(await loadState(cwd))
+      const { nextState, variant } = await registerVariantArtifact(cwd, state, objectiveId, name, patchInput, options)
+
+      await saveState(cwd, nextState)
+      process.stdout.write(`Added variant ${variant.id} to objective ${objectiveId}\n`)
+    })
+
+  const opencode = program.command("opencode").description("OpenCode registration helpers")
+
+  opencode
+    .command("register <objective-id> <session-id> <name> <patch-file>")
+    .description("Register an OpenCode session result as a variant")
+    .option("--files <files>", "Comma-separated changed files")
+    .option("--notes <text>", "Additional notes")
+    .option("--quiet", "Suppress success output")
+    .action(
+      async (
+        objectiveId: string,
+        sessionId: string,
+        name: string,
+        patchInput: string,
+        options: OpenCodeRegisterOptions,
+      ) => {
+        const state = requireState(await loadState(cwd))
+        const { nextState, variant } = await registerVariantArtifact(cwd, state, objectiveId, name, patchInput, {
+          ...options,
+          session: sessionId,
+        })
+
+        await saveState(cwd, nextState)
+        if (!options.quiet) {
+          process.stdout.write(
+            `Registered OpenCode session ${sessionId} as variant ${variant.id} in objective ${objectiveId}\n`,
+          )
+        }
+      },
+    )
+
+  opencode
+    .command("register-auto <session-id> <name> <patch-file>")
+    .description("Register an OpenCode session result with automatic objective routing")
+    .option("--objective <objective-id>", "Optional objective override; auto-created if missing")
+    .option("--files <files>", "Comma-separated changed files")
+    .option("--notes <text>", "Additional notes")
+    .option("--quiet", "Suppress success output")
+    .action(
+      async (
+        sessionId: string,
+        name: string,
+        patchInput: string,
+        options: OpenCodeRegisterAutoOptions,
+      ) => {
+        const state = requireState(await loadState(cwd))
+        const { nextState, variant, resolvedObjective, autoCreated } = await registerOpenCodeVariant(
+          cwd,
+          state,
+          sessionId,
+          name,
+          patchInput,
+          options,
+        )
+
+        await saveState(cwd, nextState)
+
+        if (!options.quiet) {
+          if (autoCreated) {
+            process.stdout.write(`Auto-created objective ${resolvedObjective.id} (${resolvedObjective.name})\n`)
+          }
+          process.stdout.write(
+            `Registered OpenCode session ${sessionId} as variant ${variant.id} in objective ${resolvedObjective.id}\n`,
+          )
+        }
+      },
+    )
+
+  opencode
+    .command("capture <session-id> <name>")
+    .description("Capture current git diff into patch and register variant automatically")
+    .option("--objective <objective-id>", "Optional objective override; auto-created if missing")
+    .option("--notes <text>", "Additional notes")
+    .option("--reset", "Restore workspace to base ref after capture")
+    .option("--quiet", "Suppress success output")
+    .action(async (sessionId: string, name: string, options: OpenCodeCaptureOptions) => {
+      const state = requireState(await loadState(cwd))
+      const { patchPath, changedFiles } = await captureCurrentDiffAsPatch(cwd, sessionId)
+      const { nextState, variant, resolvedObjective, autoCreated } = await registerOpenCodeVariant(
+        cwd,
+        state,
+        sessionId,
+        name,
+        patchPath,
+        {
+          objective: options.objective,
+          files: changedFiles.join(","),
+          notes: options.notes,
+        },
+      )
+
+      await saveState(cwd, nextState)
+
+      if (options.reset) {
+        await restoreWorkspaceToBaseRef(cwd, state.baseRef)
+      }
+
+      if (!options.quiet) {
+        if (autoCreated) {
+          process.stdout.write(`Auto-created objective ${resolvedObjective.id} (${resolvedObjective.name})\n`)
+        }
+        process.stdout.write(`Captured patch ${patchPath}\n`)
+        process.stdout.write(
+          `Registered OpenCode session ${sessionId} as variant ${variant.id} in objective ${resolvedObjective.id}\n`,
+        )
+        if (options.reset) {
+          process.stdout.write(`Workspace reset to base ${state.baseRef}\n`)
+        }
+      }
+    })
+
+  program.command("list").description("List objectives, variants, and profiles").option("--json", "Output as JSON").action(async (options: JsonOutputOption) => {
+    const state = requireState(await loadState(cwd))
+
+    if (options.json) {
+      printJson(state)
+      return
+    }
+
+    process.stdout.write(`Base ref: ${state.baseRef}\n`)
+
+    if (state.objectives.length === 0) {
+      process.stdout.write("No objectives registered yet\n")
+    } else {
+      for (const objectiveItem of state.objectives) {
+        process.stdout.write(
+          `${objectiveItem.id}: ${objectiveItem.name} [${objectiveItem.status}] base=${objectiveItem.baseRef} active=${objectiveItem.activeVariantId ?? "-"} winner=${objectiveItem.winnerVariantId ?? "-"}\n`,
+        )
+
+        if (objectiveItem.variants.length === 0) {
+          process.stdout.write("  - no variants\n")
+          continue
+        }
+
+        for (const variant of objectiveItem.variants) {
+          process.stdout.write(
+            `  - ${variant.id} [${variant.status}] files=${variant.changedFiles.length} session=${variant.sessionId ?? "-"} ${variant.name}\n`,
+          )
+        }
+      }
+    }
+
+    process.stdout.write("\nProfiles:\n")
+    if (state.profiles.length === 0) {
+      process.stdout.write("  - none\n")
+      return
+    }
+
+    for (const profile of state.profiles) {
+      const activeMarker = state.activeProfileId === profile.id ? "*" : " "
+      process.stdout.write(
+        `${activeMarker} ${profile.id} | ${profile.name} | selections=${formatSelections(profile.selections)} | lastApplied=${profile.lastAppliedAt ?? "-"}\n`,
+      )
+    }
+  })
+
+  program
+    .command("status")
+    .description("Show active profile/objective state and latest snapshot")
+    .option("--json", "Output as JSON")
+    .action(async (options: JsonOutputOption) => {
+      const state = requireState(await loadState(cwd))
+      const latestSnapshot = await getLatestSnapshot(cwd)
+
+      if (options.json) {
+        printJson({
+          baseRef: state.baseRef,
+          activeProfileId: state.activeProfileId ?? null,
+          objectives: state.objectives.map((objectiveItem) => ({
+            id: objectiveItem.id,
+            status: objectiveItem.status,
+            activeVariantId: objectiveItem.activeVariantId ?? null,
+            winnerVariantId: objectiveItem.winnerVariantId ?? null,
+            variants: objectiveItem.variants.length,
+          })),
+          latestSnapshot: latestSnapshot
+            ? {
+                id: latestSnapshot.id,
+                createdAt: latestSnapshot.createdAt,
+                head: latestSnapshot.head,
+                baseRef: latestSnapshot.baseRef,
+                selections: latestSnapshot.selections,
+                filePath: latestSnapshot.filePath,
+              }
+            : null,
+        })
+        return
+      }
+
+      process.stdout.write(`Base ref: ${state.baseRef}\n`)
+      process.stdout.write(`Active profile: ${state.activeProfileId ?? "-"}\n`)
+
+      process.stdout.write("Objectives:\n")
+      if (state.objectives.length === 0) {
+        process.stdout.write("  - none\n")
+      } else {
+        for (const objectiveItem of state.objectives) {
+          process.stdout.write(
+            `  - ${objectiveItem.id} [${objectiveItem.status}] active=${objectiveItem.activeVariantId ?? "-"} winner=${objectiveItem.winnerVariantId ?? "-"}\n`,
+          )
+        }
+      }
+
+      process.stdout.write("Latest snapshot:\n")
+      if (!latestSnapshot) {
+        process.stdout.write("  - none\n")
+        return
+      }
+
+      process.stdout.write(`  - id=${latestSnapshot.id} createdAt=${latestSnapshot.createdAt}\n`)
+      process.stdout.write(`  - head=${latestSnapshot.head} baseRef=${latestSnapshot.baseRef}\n`)
+      process.stdout.write(`  - file=${latestSnapshot.filePath}\n`)
+
+      if (latestSnapshot.selections.length === 0) {
+        process.stdout.write("  - selections=none\n")
+        return
+      }
+
+      for (const selection of latestSnapshot.selections) {
+        process.stdout.write(`  - selection ${selection.objectiveId}=${selection.variantId}\n`)
+      }
+    })
+
+  program
+    .command("activate <objective-id> <variant-id>")
+    .description("Set active variant for a specific objective")
+    .action(async (objectiveId: string, variantId: string) => {
+      const state = requireState(await loadState(cwd))
+      const current = findObjective(state, objectiveId)
+      findVariant(current, variantId)
+
+      const now = new Date().toISOString()
+      const next = upsertObjective(state, {
+        ...current,
+        activeVariantId: variantId,
+        status: current.status === "open" ? "review" : current.status,
+        updatedAt: now,
+        variants: current.variants.map((item) => {
+          if (item.id === variantId) {
+              return {
+                ...item,
+                status: "selected" as const,
+                updatedAt: now,
+              }
+            }
+
+            if (item.status === "selected") {
+              return {
+                ...item,
+                status: "ready" as const,
+                updatedAt: now,
+              }
+            }
+
+          return item
+        }),
+      })
+
+      await saveState(cwd, next)
+      process.stdout.write(`Objective ${objectiveId} active variant set to ${variantId}\n`)
+    })
+
+  program
+    .command("apply [variant-id]")
+    .description("Restore base state and apply selected variant patch(es) to workspace")
+    .option("--objective <objective-id>", "Explicit objective id")
+    .option("--variant <variant-id>", "Variant id used with --objective")
+    .option("--review", "Wait for confirmation and rollback automatically after preview")
+    .action(async (variantIdArg: string | undefined, options: ApplyCommandOptions) => {
+      const state = requireState(await loadState(cwd))
+
+      const target = resolveApplyTarget(state, variantIdArg, options)
+
+      const { snapshotPath } = await applySelectionsToWorkspace(cwd, state.baseRef, [
+        {
+          objectiveId: target.objective.id,
+          variantId: target.variant.id,
+          patchFile: target.variant.patchFile,
+          changedFiles: target.variant.changedFiles,
+        },
+      ])
+
+      const nextState = markVariantSelectedInState(state, target.objective.id, target.variant.id)
+      await saveState(cwd, nextState)
+      process.stdout.write(
+        `Applied ${target.objective.id}:${target.variant.id} from base ${state.baseRef}. Snapshot: ${snapshotPath}\n`,
+      )
+
+      if (options.review) {
+        await waitForReviewConfirmation()
+        const snapshotId = snapshotIdFromPath(snapshotPath)
+        const rolled = await rollbackAndResetState(cwd, nextState, snapshotId)
+        await saveState(cwd, rolled.nextState)
+        process.stdout.write(`Rolled back to snapshot ${rolled.snapshotId} (head ${rolled.snapshotHead})\n`)
+      }
+    })
+
+  program
+    .command("rollback [snapshot-id]")
+    .description("Restore workspace to the latest or specified pre-apply snapshot")
+    .action(async (snapshotId: string | undefined) => {
+      const state = requireState(await loadState(cwd))
+      const rolled = await rollbackAndResetState(cwd, state, snapshotId)
+
+      await saveState(cwd, rolled.nextState)
+      process.stdout.write(`Rolled back to snapshot ${rolled.snapshotId} (head ${rolled.snapshotHead})\n`)
+    })
+
+  const profile = program.command("profile").description("Manage preview profiles")
+
+  profile
+    .command("create <name>")
+    .description("Create a profile")
+    .option("--id <id>", "Explicit profile id")
+    .action(async (name: string, options: IdOption) => {
+      const state = requireState(await loadState(cwd))
+      const candidate = options.id ?? makeProfileId(name)
+      const profileId = ensureNonEmptyId(candidate, "profile id")
+
+      ensureUniqueId(
+        state.profiles.map((item) => item.id),
+        profileId,
+        "Profile",
+      )
+
+      const now = new Date().toISOString()
+      const next = upsertProfile(state, {
+        id: profileId,
+        name,
+        selections: {},
+        createdAt: now,
+        updatedAt: now,
+      })
+
+      await saveState(cwd, next)
+      process.stdout.write(`Created profile ${profileId}\n`)
+    })
+
+  profile
+    .command("list")
+    .description("List profiles")
+    .option("--json", "Output as JSON")
+    .action(async (options: JsonOutputOption) => {
+      const state = requireState(await loadState(cwd))
+
+      if (options.json) {
+        printJson(state.profiles)
+        return
+      }
+
+      if (state.profiles.length === 0) {
+        process.stdout.write("No profiles\n")
+        return
+      }
+
+      const lines = state.profiles.map((item) => {
+        const activeMarker = state.activeProfileId === item.id ? "*" : " "
+        return `${activeMarker} ${item.id} | ${item.name} | selections=${formatSelections(item.selections)} | lastApplied=${item.lastAppliedAt ?? "-"}`
+      })
+
+      process.stdout.write(lines.join("\n") + "\n")
+    })
+
+  profile
+    .command("set <profile-id> <objective-id> <variant-id>")
+    .description("Set one objective selection in a profile")
+    .action(async (profileId: string, objectiveId: string, variantId: string) => {
+      const state = requireState(await loadState(cwd))
+      const currentProfile = findProfile(state, profileId)
+      const objectiveItem = findObjective(state, objectiveId)
+      findVariant(objectiveItem, variantId)
+
+      const now = new Date().toISOString()
+      const next = upsertProfile(state, {
+        ...currentProfile,
+        selections: {
+          ...currentProfile.selections,
+          [objectiveId]: variantId,
+        },
+        updatedAt: now,
+      })
+
+      await saveState(cwd, next)
+      process.stdout.write(`Profile ${profileId} set ${objectiveId}=${variantId}\n`)
+    })
+
+  profile
+    .command("clear <profile-id> <objective-id>")
+    .description("Remove one objective selection from a profile")
+    .action(async (profileId: string, objectiveId: string) => {
+      const state = requireState(await loadState(cwd))
+      const currentProfile = findProfile(state, profileId)
+
+      const nextSelections = { ...currentProfile.selections }
+      delete nextSelections[objectiveId]
+
+      const now = new Date().toISOString()
+      const next = upsertProfile(state, {
+        ...currentProfile,
+        selections: nextSelections,
+        updatedAt: now,
+      })
+
+      await saveState(cwd, next)
+      process.stdout.write(`Profile ${profileId} cleared objective ${objectiveId}\n`)
+    })
+
+  profile
+    .command("apply <profile-id>")
+    .description("Validate and activate a profile selection plan")
+    .action(async (profileId: string) => {
+      const state = requireState(await loadState(cwd))
+      const profileItem = findProfile(state, profileId)
+      const selectionEntries = Object.entries(profileItem.selections)
+
+      if (selectionEntries.length === 0) {
+        throw new Error(`Profile ${profileId} has no selections`)
+      }
+
+      const resolved = selectionEntries.map(([objectiveId, variantId]) => {
+        const objectiveItem = findObjective(state, objectiveId)
+        const variant = findVariant(objectiveItem, variantId)
+        return {
+          objective: objectiveItem,
+          variant,
+        }
+      })
+
+      const fileOwners = new Map<string, string[]>()
+      for (const item of resolved) {
+        for (const file of item.variant.changedFiles) {
+          const owners = fileOwners.get(file) ?? []
+          owners.push(`${item.objective.id}:${item.variant.id}`)
+          fileOwners.set(file, owners)
+        }
+      }
+
+      const conflicts = Array.from(fileOwners.entries()).filter(([, owners]) => owners.length > 1)
+      if (conflicts.length > 0) {
+        const conflictText = conflicts
+          .map(([file, owners]) => `${file} -> ${owners.join(", ")}`)
+          .join("\n")
+        throw new Error(`Profile ${profileId} has overlapping file selections:\n${conflictText}`)
+      }
+
+      const { snapshotPath } = await applySelectionsToWorkspace(
+        cwd,
+        state.baseRef,
+        resolved.map((item) => ({
+          objectiveId: item.objective.id,
+          variantId: item.variant.id,
+          patchFile: item.variant.patchFile,
+          changedFiles: item.variant.changedFiles,
+        })),
+      )
+
+      const now = new Date().toISOString()
+      const selectionByObjective = new Map(selectionEntries)
+      const nextObjectives = state.objectives.map((objectiveItem) => {
+        const selectedVariantId = selectionByObjective.get(objectiveItem.id)
+        if (!selectedVariantId) return objectiveItem
+
+        return {
+          ...objectiveItem,
+          activeVariantId: selectedVariantId,
+          status: objectiveItem.status === "open" ? "review" : objectiveItem.status,
+          updatedAt: now,
+          variants: objectiveItem.variants.map((variant) => {
+            if (variant.id === selectedVariantId) {
+              return {
+                ...variant,
+                status: "selected" as const,
+                updatedAt: now,
+              }
+            }
+
+            if (variant.status === "selected") {
+              return {
+                ...variant,
+                status: "ready" as const,
+                updatedAt: now,
+              }
+            }
+
+            return variant
+          }),
+        }
+      })
+
+      const nextProfiles = state.profiles.map((current) => {
+        if (current.id !== profileId) return current
+        return {
+          ...current,
+          lastAppliedAt: now,
+          updatedAt: now,
+        }
+      })
+
+      const nextState: VariantStore = {
+        ...state,
+        activeProfileId: profileId,
+        objectives: nextObjectives,
+        profiles: nextProfiles,
+      }
+
+      await saveState(cwd, nextState)
+
+      const plan = resolved
+        .map((item) => `- ${item.objective.id} -> ${item.variant.id}`)
+        .join("\n")
+
+      process.stdout.write(`Profile ${profileId} applied:\n${plan}\n`)
+      process.stdout.write(`Workspace updated from base ${state.baseRef}. Snapshot: ${snapshotPath}\n`)
+    })
+
+  const bridge = program.command("bridge").description("Browser devtools bridge")
+
+  bridge
+    .command("serve")
+    .description("Start local HTTP bridge and serve toolbar script")
+    .option("--host <host>", "Host interface", "127.0.0.1")
+    .option("--port <port>", "Port", "4173")
+    .action(async (options: BridgeServeOptions) => {
+      const host = options.host ?? "127.0.0.1"
+      const port = parsePortOption(options.port, 4173)
+      const server = await startBridgeServer({
+        host,
+        port,
+        projectRoot: cwd,
+      })
+
+      process.stdout.write(`Bridge server listening on ${server.url}\n`)
+      process.stdout.write(`Toolbar script: ${server.url}/toolbar.js\n`)
+      process.stdout.write(`Status endpoint: ${server.url}/status\n`)
+      process.stdout.write("Press Ctrl+C to stop.\n")
+
+      await new Promise<void>((resolvePromise) => {
+        let closed = false
+
+        const shutdown = async () => {
+          if (closed) return
+          closed = true
+          process.stdout.write("Stopping bridge server...\n")
+          await server.close()
+          process.off("SIGINT", onSigint)
+          process.off("SIGTERM", onSigterm)
+          resolvePromise()
+        }
+
+        const onSigint = () => {
+          void shutdown()
+        }
+
+        const onSigterm = () => {
+          void shutdown()
+        }
+
+        process.on("SIGINT", onSigint)
+        process.on("SIGTERM", onSigterm)
+      })
+    })
+
+  return program
+}
+
+async function run(): Promise<void> {
+  const program = createProgram(process.cwd())
+  if (process.argv.length <= 2) {
+    program.outputHelp()
+    return
+  }
+
+  try {
+    await program.parseAsync(process.argv)
+  } catch (error: unknown) {
+    if (error instanceof CommanderError && error.code === "commander.helpDisplayed") {
+      return
+    }
+
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(message.replace(/^error:\s*/i, ""))
+  }
+}
+
+run().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`Error: ${message}\n`)
+  process.exit(1)
+})