@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/planning-workspace.ts

@@ -0,0 +1,323 @@
+/**
+ * Presentation types and derivation for the read-only planning workspace panel.
+ *
+ * Every value here comes from typed data injected by the caller. Nothing in this
+ * module reads Poetic internals, managed planning files, Git, the filesystem, or
+ * the network, and nothing mutates planning state: Poetic remains the planning
+ * authority and this is a projection of what it already reported.
+ *
+ * Missing, stale, blocked, and unavailable are separate rendered states. They are
+ * never collapsed into one another, and an unavailable input never renders as a
+ * healthy one.
+ */
+
+/** Presentation vocabulary for a task queue. `unknown` is never inferred away. */
+export type PlanningTaskStatus =
+  | 'todo'
+  | 'in-progress'
+  | 'review'
+  | 'blocked'
+  | 'done'
+  | 'cancelled'
+  | 'unknown';
+
+/** Fixed queue order, so the panel stays scannable across refreshes. */
+export const PLANNING_QUEUE_ORDER: readonly PlanningTaskStatus[] = [
+  'blocked',
+  'in-progress',
+  'review',
+  'todo',
+  'done',
+  'cancelled',
+  'unknown',
+];
+
+/** Human labels for the queue vocabulary, shared with the task-navigation view. */
+export const PLANNING_QUEUE_LABELS: Readonly<Record<PlanningTaskStatus, string>> = {
+  blocked: 'Blocked',
+  'in-progress': 'In progress',
+  review: 'Review',
+  todo: 'To do',
+  done: 'Done',
+  cancelled: 'Cancelled',
+  unknown: 'Unknown status',
+};
+
+/** Label used when injected data reports no owner for a task. */
+export const UNASSIGNED_OWNER_LABEL = 'Unassigned';
+
+/**
+ * Advisory synchronization health. `unavailable` means the caller could not
+ * observe synchronization at all, which is distinct from an observed `stale`.
+ */
+export type PlanningSyncState = 'in-sync' | 'ahead' | 'stale' | 'unavailable';
+
+export interface PlanningSyncHealth {
+  state: PlanningSyncState;
+  /** Caller-supplied detail, rendered verbatim. */
+  detail: string | null;
+  observedAt: string | null;
+}
+
+export interface PlanningSprintSummary {
+  id: string;
+  title: string;
+  status: string;
+  startedAt: string | null;
+  targetDate: string | null;
+}
+
+/**
+ * Structured dependency record as Poetic classified it. Presentation never
+ * re-decides satisfaction; `available` / `recorded-complete` / `missing` and
+ * `satisfied` remain distinct.
+ */
+export interface PlanningDependencyRecord {
+  id: string;
+  state: 'available' | 'recorded-complete' | 'missing';
+  status: string | null;
+  satisfied: boolean;
+}
+
+/** Structured blocker as Poetic published it (task-status or dependency). */
+export interface PlanningBlockerRecord {
+  kind: 'task-status' | 'dependency';
+  id: string;
+  reason: string | null;
+}
+
+export interface PlanningTaskView {
+  id: string;
+  title: string;
+  status: PlanningTaskStatus;
+  priority: string | null;
+  /** Lifecycle timestamps as Poetic published them; never recomputed here. */
+  created: string | null;
+  updated: string | null;
+  started: string | null;
+  completed: string | null;
+  archived: string | null;
+  cancelled: string | null;
+  /** Active/archive bucket location; null when the task was missing or unpublished. */
+  location: 'active' | 'archive' | null;
+  /** Null when the injected data reports no owner. */
+  owner: string | null;
+  estimates: { hours: number | null; runtimeMinutes: number | null };
+  /**
+   * Unsatisfied dependency ids only, preserved for existing queue presentation.
+   * Full classification lives on `dependencies`.
+   */
+  dependsOn: readonly string[];
+  /** Linked backlog item id when Poetic published one; never invented. */
+  linkedBacklogItemId: string | null;
+  /** Full dependency records in Poetic order, including satisfied ones. */
+  dependencies: readonly PlanningDependencyRecord[];
+  /** Structured blockers as Poetic reported them. */
+  blockers: readonly PlanningBlockerRecord[];
+}
+
+/**
+ * One next-work candidate in Poetic's published order. Presentation never
+ * re-ranks this list.
+ */
+export interface PlanningNextCandidateView {
+  id: string;
+  kind: string;
+  title: string;
+  status: string;
+  priority: string | null;
+  whyIncluded: string;
+}
+
+export interface PlanningWorkspaceData {
+  /** Null when no sprint summary was injected; rendered as missing, not empty. */
+  sprint: PlanningSprintSummary | null;
+  tasks: readonly PlanningTaskView[];
+  /**
+   * Next candidates in Poetic order. Empty when missing or unavailable; those
+   * states are disclosed via notes on the projection, not by inventing ranks.
+   */
+  nextCandidates: readonly PlanningNextCandidateView[];
+  syncHealth: PlanningSyncHealth;
+}
+
+export interface PlanningSprintView {
+  state: 'present' | 'missing';
+  title: string;
+  statusLine: string;
+  countsLine: string;
+}
+
+export interface PlanningQueueView {
+  status: PlanningTaskStatus;
+  label: string;
+  tasks: readonly PlanningTaskView[];
+}
+
+/**
+ * One dependency that still holds a task back. `unknown` means the dependency id
+ * is not present in the injected data, so its state cannot be claimed.
+ */
+export interface PlanningBlockerView {
+  id: string;
+  title: string | null;
+  state: 'blocking' | 'unknown';
+}
+
+export interface PlanningDependencyView {
+  task: PlanningTaskView;
+  blockers: readonly PlanningBlockerView[];
+}
+
+export interface PlanningOwnershipView {
+  label: string;
+  taskCount: number;
+  blockedCount: number;
+}
+
+export interface PlanningSyncHealthView {
+  state: PlanningSyncState;
+  label: string;
+  detail: string | null;
+  observedAt: string | null;
+  /** Always true: sync health never gates or explains a planning outcome. */
+  advisory: true;
+}
+
+export interface PlanningWorkspaceView {
+  sprint: PlanningSprintView;
+  queues: readonly PlanningQueueView[];
+  /** Pass-through of Poetic order; never re-ranked here. */
+  nextCandidates: readonly PlanningNextCandidateView[];
+  dependencies: readonly PlanningDependencyView[];
+  ownership: readonly PlanningOwnershipView[];
+  syncHealth: PlanningSyncHealthView;
+}
+
+const SYNC_LABELS: Readonly<Record<PlanningSyncState, string>> = {
+  'in-sync': 'Planning state is synchronized',
+  ahead: 'Local planning changes are not synchronized',
+  stale: 'Planning state is stale',
+  unavailable: 'Synchronization state unavailable',
+};
+
+function sprintView(
+  sprint: PlanningSprintSummary | null,
+  tasks: readonly PlanningTaskView[]
+): PlanningSprintView {
+  const counts = PLANNING_QUEUE_ORDER.map((status) => ({
+    status,
+    total: tasks.filter((task) => task.status === status).length,
+  })).filter((entry) => entry.total > 0);
+  const countsLine =
+    tasks.length === 0
+      ? 'No tasks reported'
+      : `${tasks.length} tasks: ${counts
+          .map((entry) => `${entry.total} ${PLANNING_QUEUE_LABELS[entry.status].toLowerCase()}`)
+          .join(', ')}`;
+  if (!sprint) {
+    return {
+      state: 'missing',
+      title: 'No sprint reported',
+      statusLine: 'Poetic reports no active sprint',
+      countsLine,
+    };
+  }
+  const window = [sprint.startedAt ?? 'no start date', sprint.targetDate ?? 'no target date'].join(
+    ' to '
+  );
+  return {
+    state: 'present',
+    title: sprint.title,
+    statusLine: `${sprint.id} | ${sprint.status} | ${window}`,
+    countsLine,
+  };
+}
+
+/**
+ * Prefer Poetic's structured dependency satisfaction when present. Fall back to
+ * `dependsOn` ids for older injected data so missing ids stay distinct from
+ * satisfied ones without re-deriving satisfaction for recorded-complete rows.
+ */
+function blockersFor(
+  task: PlanningTaskView,
+  byId: ReadonlyMap<string, PlanningTaskView>
+): PlanningBlockerView[] {
+  if (task.dependencies.length > 0) {
+    const blockers: PlanningBlockerView[] = [];
+    for (const dependency of task.dependencies) {
+      if (dependency.satisfied) continue;
+      const peer = byId.get(dependency.id);
+      if (dependency.state === 'missing' || !peer) {
+        blockers.push({ id: dependency.id, title: null, state: 'unknown' });
+        continue;
+      }
+      blockers.push({ id: dependency.id, title: peer.title, state: 'blocking' });
+    }
+    return blockers;
+  }
+
+  const blockers: PlanningBlockerView[] = [];
+  for (const id of task.dependsOn) {
+    const dependency = byId.get(id);
+    if (!dependency) {
+      blockers.push({ id, title: null, state: 'unknown' });
+      continue;
+    }
+    if (dependency.status !== 'done') {
+      blockers.push({ id, title: dependency.title, state: 'blocking' });
+    }
+  }
+  return blockers;
+}
+
+/**
+ * Project injected planning data into the panel's rendered shape. Pure: the same
+ * input always yields the same view, and the input is never mutated. Next
+ * candidates are copied in order and never re-ranked.
+ */
+export function buildPlanningWorkspaceView(data: PlanningWorkspaceData): PlanningWorkspaceView {
+  const tasks = [...data.tasks];
+  const byId = new Map(tasks.map((task) => [task.id, task] as const));
+
+  const queues = PLANNING_QUEUE_ORDER.map((status) => ({
+    status,
+    label: PLANNING_QUEUE_LABELS[status],
+    tasks: tasks.filter((task) => task.status === status),
+  })).filter((queue) => queue.tasks.length > 0);
+
+  const dependencies: PlanningDependencyView[] = [];
+  for (const task of tasks) {
+    const blockers = blockersFor(task, byId);
+    if (blockers.length > 0) dependencies.push({ task, blockers });
+  }
+
+  const ownership: PlanningOwnershipView[] = [];
+  for (const task of tasks) {
+    const label = task.owner ?? UNASSIGNED_OWNER_LABEL;
+    const blocked = task.status === 'blocked' || blockersFor(task, byId).length > 0;
+    const existing = ownership.find((entry) => entry.label === label);
+    if (existing) {
+      existing.taskCount += 1;
+      if (blocked) existing.blockedCount += 1;
+      continue;
+    }
+    ownership.push({ label, taskCount: 1, blockedCount: blocked ? 1 : 0 });
+  }
+
+  return {
+    sprint: sprintView(data.sprint, tasks),
+    queues,
+    // Order is Poetic's; this view never sorts or re-ranks candidates.
+    nextCandidates: [...data.nextCandidates],
+    dependencies,
+    ownership,
+    syncHealth: {
+      state: data.syncHealth.state,
+      label: SYNC_LABELS[data.syncHealth.state],
+      detail: data.syncHealth.detail,
+      observedAt: data.syncHealth.observedAt,
+      advisory: true,
+    },
+  };
+}

package/integrations/bb-plugin-poetic/src/poll-handoff.ts

@@ -0,0 +1,136 @@
+/**
+ * One-generation, process-local poll handoff.
+ *
+ * The background monitor reads Poetic, then the panel's follow-up `pollRuns`
+ * can consume that observation instead of inspecting and polling again. The
+ * slot is overwritten per target, deleted on consume, and never treated as
+ * authority: Reconnect/Refresh pass `fresh: true` and re-read Poetic.
+ */
+
+import type { RepositoryView, RunCard } from './model.js';
+
+/** How long a monitor observation may satisfy the next panel poll. */
+export const POLL_HANDOFF_TTL_MS = 5_000;
+
+export interface PollHandoffTarget {
+  projectId: string;
+  sourceId: string;
+}
+
+export interface PollHandoffSnapshot extends PollHandoffTarget {
+  observedAt: string;
+  repository: RepositoryView;
+  runs: RunCard[];
+}
+
+export interface PollRunsHandoffInput extends PollHandoffTarget {
+  observe?: boolean;
+  fresh?: boolean;
+}
+
+function targetKey(target: PollHandoffTarget): string {
+  return `${target.projectId}\n${target.sourceId}`;
+}
+
+/** Default-true: only an explicit `observe: false` skips the watch TTL refresh. */
+export function shouldRefreshWatch(observe: boolean | undefined): boolean {
+  return observe !== false;
+}
+
+/**
+ * In-memory, one-slot-per-target handoff. Not a run store: a matching snapshot
+ * is returned at most once, and only while it is younger than the TTL.
+ */
+export class PollHandoff {
+  private readonly slots = new Map<string, { storedAt: number; snapshot: PollHandoffSnapshot }>();
+  private readonly epochs = new Map<string, number>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /** Epoch captured when a monitor read starts. */
+  beginRead(target: PollHandoffTarget): number {
+    return this.epochs.get(targetKey(target)) ?? 0;
+  }
+
+  /**
+   * Store only if this read's epoch is still current. An omitted epoch is for
+   * tests that are not exercising the stale-read fence.
+   */
+  store(snapshot: PollHandoffSnapshot, startedEpoch?: number): boolean {
+    const key = targetKey(snapshot);
+    if (startedEpoch !== undefined && (this.epochs.get(key) ?? 0) !== startedEpoch) {
+      return false;
+    }
+    this.slots.set(key, { storedAt: this.now(), snapshot });
+    return true;
+  }
+
+  /**
+   * Return and delete a matching young snapshot. Stale or missing slots yield
+   * null; a stale slot is still deleted so it cannot be reused later.
+   */
+  consume(target: PollHandoffTarget): PollHandoffSnapshot | null {
+    const key = targetKey(target);
+    const entry = this.slots.get(key);
+    if (!entry) return null;
+    this.slots.delete(key);
+    if (this.now() - entry.storedAt >= POLL_HANDOFF_TTL_MS) return null;
+    return entry.snapshot;
+  }
+
+  /**
+   * Drop a slot and advance the epoch so an older in-flight monitor read cannot
+   * store after Refresh/reconnect has already started.
+   */
+  discard(target: PollHandoffTarget): void {
+    const key = targetKey(target);
+    this.slots.delete(key);
+    this.epochs.set(key, (this.epochs.get(key) ?? 0) + 1);
+  }
+
+  /**
+   * Advance the epoch and drop any slot stored during the fresh window. A
+   * monitor read that started after `discard` can store before this runs; the
+   * slot must not survive to rewind a later invalidate.
+   */
+  completeFresh(target: PollHandoffTarget): void {
+    const key = targetKey(target);
+    this.slots.delete(key);
+    this.epochs.set(key, (this.epochs.get(key) ?? 0) + 1);
+  }
+
+  /** Test/inspection helper. Production callers use `consume`. */
+  peek(target: PollHandoffTarget): PollHandoffSnapshot | null {
+    return this.slots.get(targetKey(target))?.snapshot ?? null;
+  }
+}
+
+/**
+ * Panel `pollRuns` resolution: consume a young handoff unless `fresh` is true
+ * (which discards any pending slot so a later invalidate cannot rewind), and
+ * refresh the monitor watch TTL unless `observe` is false.
+ */
+export async function resolvePollRuns(
+  input: PollRunsHandoffInput,
+  deps: {
+    handoff: PollHandoff;
+    refreshWatch: (target: PollHandoffTarget) => void;
+    readFresh: (observe: boolean) => Promise<{ repository: RepositoryView; runs: RunCard[] }>;
+  }
+): Promise<{ repository: RepositoryView; runs: RunCard[] }> {
+  const observe = shouldRefreshWatch(input.observe);
+  if (input.fresh === true) {
+    deps.handoff.discard(input);
+    try {
+      return await deps.readFresh(observe);
+    } finally {
+      deps.handoff.completeFresh(input);
+    }
+  }
+  const snapshot = deps.handoff.consume(input);
+  if (snapshot) {
+    if (observe) deps.refreshWatch(input);
+    return { repository: snapshot.repository, runs: snapshot.runs };
+  }
+  return deps.readFresh(observe);
+}

package/integrations/bb-plugin-poetic/src/project-target-server.ts

@@ -0,0 +1,21 @@
+import { realpath } from 'node:fs/promises';
+import type { BbProject, ProjectTarget } from './project-target.js';
+
+export async function resolveProjectTarget(
+  projects: readonly BbProject[],
+  input: { projectId: string; sourceId: string }
+): Promise<ProjectTarget> {
+  const project = projects.find((candidate) => candidate.id === input.projectId);
+  if (!project) throw new Error('The selected BB project is no longer available.');
+  const source = project.sources.find((candidate) => candidate.id === input.sourceId);
+  if (!source || source.type !== 'local_path') {
+    throw new Error('The selected BB source is not an available local repository.');
+  }
+  return {
+    projectId: project.id,
+    projectName: project.name,
+    sourceId: source.id,
+    hostId: source.hostId,
+    path: await realpath(source.path),
+  };
+}

package/integrations/bb-plugin-poetic/src/project-target.ts

@@ -0,0 +1,45 @@
+export interface BbLocalSource {
+  id: string;
+  type: string;
+  hostId: string;
+  path: string;
+}
+
+export interface BbProject {
+  id: string;
+  name: string;
+  sources: readonly BbLocalSource[];
+}
+
+export interface ProjectTarget {
+  projectId: string;
+  projectName: string;
+  sourceId: string;
+  hostId: string;
+  path: string;
+}
+
+export function listLocalProjects(projects: readonly BbProject[]) {
+  return projects
+    .map((project) => ({
+      id: project.id,
+      name: project.name,
+      sources: project.sources
+        .filter((source) => source.type === 'local_path')
+        .map((source) => ({ id: source.id, path: source.path })),
+    }))
+    .filter((project) => project.sources.length > 0);
+}
+
+/**
+ * Auto-associate a BB project/source only when exactly one local source exists.
+ * Zero or multiple candidates return empty so the UI asks the user.
+ */
+export function automaticProjectSelection(
+  projects: ReadonlyArray<{ id: string; sources: ReadonlyArray<{ id: string }> }>
+): string {
+  const candidates = projects.flatMap((project) =>
+    project.sources.map((source) => `${project.id}\n${source.id}`)
+  );
+  return candidates.length === 1 ? (candidates[0] ?? '') : '';
+}