@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/patch-preview-service.ts

@@ -0,0 +1,480 @@
+/**
+ * Narrow, bounded, read-only patch-preview service.
+ *
+ * This is the only path in the plugin that opens a file from the selected
+ * repository, and it is deliberately not a filesystem browser:
+ *
+ *   - Poetic remains authoritative. Every preview rereads the run's canonical
+ *     evidence through the injected readback and binds the submitted reference
+ *     to that freshly reread set, so evidence that moved or disappeared between
+ *     two previews is refused rather than served from a stale list.
+ *   - Only a reference whose canonical kind is `patch` reaches resolution. Every
+ *     other kind, including worktrees, artifacts, synthesis, and changed files,
+ *     is refused before any file is opened.
+ *   - The repository root and the candidate are canonicalized with realpath and
+ *     the resolved regular file must remain inside the canonical root. Symlinks,
+ *     non-regular files, and traversal are refused, and the final open uses
+ *     `O_NOFOLLOW` so a swap after resolution cannot be followed.
+ *   - Reading is a bounded stream with a fixed byte ceiling and an explicit
+ *     truncation state. There is no unbounded whole-file read here.
+ *   - Responses carry bounded text and metadata only; this feature adds no
+ *     absolute host path disclosure, and no write, apply, or merge action.
+ */
+
+import { constants as fsConstants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import {
+  PATCH_PREVIEW_MAX_BYTES,
+  type PatchPreviewInput,
+  type PatchPreviewRefusalReason,
+  type PatchPreviewResult,
+  type PatchPreviewUnavailableReason,
+  patchPreviewInputSchema,
+} from './patch-preview-schema.js';
+import { repositorySchema } from './repository-schema.js';
+import type { EvidenceReferenceView } from './result-readback-schema.js';
+import type { ResultReadbackResult } from './result-readback-service.js';
+
+/**
+ * Injected canonical reread. BRCS-02 owns the command, transport, and identity
+ * binding; this service never builds argv or spawns a process of its own.
+ */
+export type PatchPreviewReadback = (
+  repository: unknown,
+  input: {
+    projectId: string;
+    sourceId: string;
+    runId: string;
+    kind: PatchPreviewInput['kind'];
+  }
+) => Promise<ResultReadbackResult>;
+
+/** Compressed containers are refused rather than previewed as text. */
+const COMPRESSED_SUFFIXES: readonly string[] = [
+  '.br',
+  '.bz2',
+  '.gz',
+  '.lz4',
+  '.lzma',
+  '.rar',
+  '.tgz',
+  '.xz',
+  '.zip',
+  '.zst',
+  '.7z',
+];
+
+/** Leading bytes of the compressed containers a patch reference must not be. */
+const COMPRESSED_MAGIC: readonly (readonly number[])[] = [
+  [0x1f, 0x8b], // gzip
+  [0x42, 0x5a, 0x68], // bzip2
+  [0xfd, 0x37, 0x7a, 0x58, 0x5a], // xz
+  [0x28, 0xb5, 0x2f, 0xfd], // zstd
+  [0x50, 0x4b, 0x03, 0x04], // zip
+  [0x37, 0x7a, 0xbc, 0xaf], // 7z
+];
+
+const NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
+
+type Identity = { projectId: string; sourceId: string; runId: string };
+
+type ResolvedPath =
+  | { state: 'resolved'; path: string }
+  | { state: 'refused'; reason: 'unsafe-path' };
+
+function refused(
+  identity: Identity,
+  reason: PatchPreviewRefusalReason,
+  message: string
+): PatchPreviewResult {
+  return { state: 'refused', reason, message, ...identity };
+}
+
+function unavailable(
+  identity: Identity,
+  reason: PatchPreviewUnavailableReason,
+  message: string
+): PatchPreviewResult {
+  return { state: 'unavailable', reason, message, ...identity };
+}
+
+/**
+ * Map BRCS-02's canonical readback refusal onto this feature's vocabulary. A
+ * request-identity problem stays a refusal; an evidence problem is reported as
+ * unavailable so presentation can distinguish the two.
+ */
+function fromReadbackFailure(
+  identity: Identity,
+  result: Extract<ResultReadbackResult, { state: 'unavailable' }>
+): PatchPreviewResult {
+  if (result.reason === 'invalid-request') {
+    return refused(identity, 'invalid-request', 'Invalid patch preview request.');
+  }
+  if (result.reason === 'cross-repository') {
+    return refused(
+      identity,
+      'cross-repository',
+      'The canonical evidence does not belong to the selected repository.'
+    );
+  }
+  if (result.reason === 'cross-run' || result.reason === 'mismatched-kind') {
+    return refused(
+      identity,
+      'cross-run',
+      'The canonical evidence does not belong to the selected run.'
+    );
+  }
+  if (result.reason === 'malformed-output' || result.reason === 'unsupported-major') {
+    return unavailable(
+      identity,
+      'incompatible-evidence',
+      'The canonical evidence for this run is incompatible.'
+    );
+  }
+  return unavailable(
+    identity,
+    'evidence-unavailable',
+    'Poetic has no canonical evidence to preview for this run.'
+  );
+}
+
+/** Every reference the freshly reread run published, run-wide and per variant. */
+function canonicalEvidence(
+  result: Extract<ResultReadbackResult, { state: 'available' }>
+): readonly EvidenceReferenceView[] {
+  const view = result.view;
+  if (view.kind === 'competition') {
+    return [...view.evidence, ...view.candidates.flatMap((candidate) => candidate.evidence)];
+  }
+  if (view.kind === 'fusion') {
+    return [...view.evidence, ...view.contributors.flatMap((contributor) => contributor.evidence)];
+  }
+  return view.evidence;
+}
+
+/**
+ * Reduce a canonical reference value to one repository-relative path. Absolute
+ * paths, drive letters, home expansion, backslashes, NUL bytes, and any `..`
+ * segment are refused; nothing here consults the filesystem.
+ */
+function relativeReferencePath(value: string): ResolvedPath {
+  const unsafe: ResolvedPath = { state: 'refused', reason: 'unsafe-path' };
+  if (value.length === 0 || value.includes('\0') || value.includes('\\')) return unsafe;
+  if (value.startsWith('~') || isAbsolute(value) || /^[A-Za-z]:/.test(value)) return unsafe;
+
+  const segments = value.split('/').filter((segment) => segment !== '.');
+  if (segments.length === 0) return unsafe;
+  for (const segment of segments) {
+    if (segment.length === 0 || segment === '..') return unsafe;
+  }
+  return { state: 'resolved', path: segments.join(sep) };
+}
+
+/** True when `candidate` is the root itself or sits inside it. */
+function insideRoot(root: string, candidate: string): boolean {
+  const relativePath = relative(root, candidate);
+  if (relativePath === '') return true;
+  return relativePath !== '..' && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+
+/**
+ * Reject a symlink anywhere between the canonical root and the candidate, so a
+ * nested symlink cannot smuggle the read outside the repository.
+ */
+async function componentState(
+  root: string,
+  relativePath: string
+): Promise<'ok' | 'symlink' | 'missing' | 'read-failed'> {
+  let current = root;
+  for (const segment of relativePath.split(sep)) {
+    current = join(current, segment);
+    try {
+      const stats = await lstat(current);
+      if (stats.isSymbolicLink()) return 'symlink';
+    } catch (error) {
+      return (error as { code?: string }).code === 'ENOENT' ? 'missing' : 'read-failed';
+    }
+  }
+  return 'ok';
+}
+
+function compressedSuffix(value: string): boolean {
+  const lowered = value.toLowerCase();
+  return COMPRESSED_SUFFIXES.some((suffix) => lowered.endsWith(suffix));
+}
+
+function compressedMagic(bytes: Buffer): boolean {
+  return COMPRESSED_MAGIC.some(
+    (magic) =>
+      bytes.byteLength >= magic.length && magic.every((byte, index) => bytes[index] === byte)
+  );
+}
+
+function lineCount(text: string): number {
+  if (text.length === 0) return 0;
+  const lines = text.split('\n');
+  return text.endsWith('\n') ? lines.length - 1 : lines.length;
+}
+
+/** Read at most the ceiling plus one byte, so truncation is observed, not guessed. */
+async function readBounded(
+  handle: Awaited<ReturnType<typeof open>>
+): Promise<{ bytes: Buffer; truncated: boolean }> {
+  // `end` is inclusive, so at most the ceiling plus one byte reaches memory and
+  // the caller's `finally` keeps ownership of the handle.
+  const stream = handle.createReadStream({
+    start: 0,
+    end: PATCH_PREVIEW_MAX_BYTES,
+    autoClose: false,
+  });
+  const chunks: Buffer[] = [];
+  let read = 0;
+  try {
+    for await (const chunk of stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      chunks.push(buffer);
+      read += buffer.byteLength;
+      if (read > PATCH_PREVIEW_MAX_BYTES) break;
+    }
+  } finally {
+    stream.destroy();
+  }
+  const raw = Buffer.concat(chunks);
+  const truncated = raw.byteLength > PATCH_PREVIEW_MAX_BYTES;
+  return { bytes: truncated ? raw.subarray(0, PATCH_PREVIEW_MAX_BYTES) : raw, truncated };
+}
+
+function openFailure(error: unknown): PatchPreviewRefusalReason | 'read-failed' {
+  const code = (error as { code?: string }).code;
+  if (code === 'ELOOP' || code === 'EMLINK') return 'symlink';
+  if (code === 'ENOENT') return 'missing';
+  if (code === 'EISDIR') return 'not-a-regular-file';
+  return 'read-failed';
+}
+
+export class PatchPreviewService {
+  constructor(private readonly readback: PatchPreviewReadback) {}
+
+  async preview(repositoryValue: unknown, inputValue: unknown): Promise<PatchPreviewResult> {
+    const repository = repositorySchema.parse(repositoryValue);
+    const input = patchPreviewInputSchema.safeParse(inputValue);
+    const fallbackRunId =
+      inputValue &&
+      typeof inputValue === 'object' &&
+      'runId' in inputValue &&
+      typeof inputValue.runId === 'string'
+        ? inputValue.runId
+        : '';
+    if (!input.success) {
+      return refused(
+        { projectId: repository.projectId, sourceId: repository.sourceId, runId: fallbackRunId },
+        'invalid-request',
+        'Invalid patch preview request.'
+      );
+    }
+
+    const identity = {
+      projectId: repository.projectId,
+      sourceId: repository.sourceId,
+      runId: input.data.runId,
+    };
+    if (
+      input.data.projectId !== repository.projectId ||
+      input.data.sourceId !== repository.sourceId
+    ) {
+      return refused(
+        identity,
+        'cross-repository',
+        'The request does not identify the selected repository.'
+      );
+    }
+
+    const readback = await this.readback(repository, {
+      projectId: input.data.projectId,
+      sourceId: input.data.sourceId,
+      runId: input.data.runId,
+      kind: input.data.kind,
+    });
+    if (readback.state !== 'available') return fromReadbackFailure(identity, readback);
+    if (readback.runId !== input.data.runId || readback.view.runId !== input.data.runId) {
+      return refused(
+        identity,
+        'cross-run',
+        'The canonical evidence does not belong to the selected run.'
+      );
+    }
+
+    const requested = input.data.reference;
+    const requestedVariant = requested.variant ?? null;
+    const matches = canonicalEvidence(readback).filter(
+      (entry) => entry.value === requested.value && (entry.variant ?? null) === requestedVariant
+    );
+    if (matches.length === 0) {
+      return refused(
+        identity,
+        'unknown-reference',
+        'The freshly reread canonical evidence does not contain this reference.'
+      );
+    }
+    // The canonical kind decides, not the caller's claim, and both must be patch.
+    if (requested.kind !== 'patch' || matches.some((entry) => entry.kind !== 'patch')) {
+      return refused(
+        identity,
+        'unsupported-kind',
+        'Only canonical patch evidence can be previewed.'
+      );
+    }
+    // Every match must also be bound to this repository and this run.
+    if (
+      matches.some(
+        (entry) =>
+          entry.repository.projectId !== repository.projectId ||
+          entry.repository.sourceId !== repository.sourceId
+      )
+    ) {
+      return refused(
+        identity,
+        'cross-repository',
+        'The canonical evidence does not belong to the selected repository.'
+      );
+    }
+    if (matches.some((entry) => entry.runId !== input.data.runId)) {
+      return refused(
+        identity,
+        'cross-run',
+        'The canonical evidence does not belong to the selected run.'
+      );
+    }
+
+    return await this.read(identity, repository.path, {
+      value: requested.value,
+      variant: requestedVariant,
+    });
+  }
+
+  private async read(
+    identity: Identity,
+    repositoryPath: string,
+    reference: { value: string; variant: string | null }
+  ): Promise<PatchPreviewResult> {
+    const relativePath = relativeReferencePath(reference.value);
+    if (relativePath.state === 'refused') {
+      return refused(
+        identity,
+        'unsafe-path',
+        'The canonical patch reference is not a safe repository-relative path.'
+      );
+    }
+    if (compressedSuffix(reference.value)) {
+      return refused(identity, 'compressed', 'A compressed patch reference is not previewable.');
+    }
+
+    let root: string;
+    try {
+      root = await realpath(repositoryPath);
+    } catch {
+      return unavailable(
+        identity,
+        'read-failed',
+        'The selected repository root could not be canonicalized.'
+      );
+    }
+
+    const candidate = resolve(root, relativePath.path);
+    if (!insideRoot(root, candidate) || candidate === root) {
+      return refused(
+        identity,
+        'unsafe-path',
+        'The canonical patch reference resolves outside the selected repository.'
+      );
+    }
+
+    const components = await componentState(root, relativePath.path);
+    if (components === 'symlink') {
+      return refused(identity, 'symlink', 'A symlinked patch reference is not previewable.');
+    }
+    if (components === 'missing') {
+      return refused(identity, 'missing', 'The canonical patch evidence is no longer present.');
+    }
+    if (components === 'read-failed') {
+      return unavailable(identity, 'read-failed', 'The canonical patch evidence is not readable.');
+    }
+
+    let resolved: string;
+    try {
+      resolved = await realpath(candidate);
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      if (code === 'ENOENT') {
+        return refused(identity, 'missing', 'The canonical patch evidence is no longer present.');
+      }
+      if (code === 'ELOOP' || code === 'EMLINK') {
+        return refused(identity, 'symlink', 'A symlinked patch reference is not previewable.');
+      }
+      return unavailable(identity, 'read-failed', 'The canonical patch evidence is not readable.');
+    }
+    if (!insideRoot(root, resolved) || resolved === root) {
+      return refused(
+        identity,
+        'unsafe-path',
+        'The canonical patch reference resolves outside the selected repository.'
+      );
+    }
+
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+      handle = await open(resolved, fsConstants.O_RDONLY | NOFOLLOW);
+    } catch (error) {
+      const reason = openFailure(error);
+      if (reason === 'read-failed') {
+        return unavailable(
+          identity,
+          'read-failed',
+          'The canonical patch evidence is not readable.'
+        );
+      }
+      return refused(
+        identity,
+        reason,
+        reason === 'missing'
+          ? 'The canonical patch evidence is no longer present.'
+          : 'The canonical patch reference is not a previewable regular file.'
+      );
+    }
+
+    try {
+      const stats = await handle.stat();
+      if (!stats.isFile()) {
+        return refused(
+          identity,
+          'not-a-regular-file',
+          'The canonical patch reference is not a regular file.'
+        );
+      }
+
+      const { bytes, truncated } = await readBounded(handle);
+      if (compressedMagic(bytes)) {
+        return refused(identity, 'compressed', 'A compressed patch reference is not previewable.');
+      }
+      if (bytes.includes(0)) {
+        return refused(identity, 'binary', 'A binary patch reference is not previewable.');
+      }
+
+      const text = bytes.toString('utf8');
+      return {
+        ...identity,
+        state: 'previewed',
+        reference: { kind: 'patch', value: reference.value, variant: reference.variant },
+        byteLength: bytes.byteLength,
+        truncated,
+        lineCount: lineCount(text),
+        text,
+      };
+    } catch {
+      return unavailable(identity, 'read-failed', 'The canonical patch evidence is not readable.');
+    } finally {
+      await handle.close().catch(() => undefined);
+    }
+  }
+}

package/integrations/bb-plugin-poetic/src/patch-preview-view.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure presentation for BB's bounded, read-only patch preview.
+ *
+ * This module maps one already-decided preview result to plain rows and one
+ * bounded body. It holds the same authority boundary as the rest of the plugin:
+ *
+ *   - It never reads a file, resolves a path, or re-checks a refusal. The
+ *     service already decided; this only labels the decision.
+ *   - The four outcomes stay distinct: `previewed`, `truncated`, `unavailable`,
+ *     and `refused`. A truncated body is never presented as a complete patch,
+ *     and a refusal is never presented as an empty preview.
+ *   - It adds no absolute host path and no apply, write, or merge control.
+ */
+
+import {
+  PATCH_PREVIEW_MAX_BYTES,
+  PATCH_PREVIEW_VIEW_VERSION,
+  type PatchPreviewResult,
+  type PatchPreviewView,
+} from './patch-preview-schema.js';
+
+export { PATCH_PREVIEW_VIEW_VERSION };
+
+export type PatchPreviewViewState = PatchPreviewView['state'];
+
+type Row = PatchPreviewView['rows'][number];
+
+const REFUSAL_NOTICES: Readonly<Record<string, string>> = {
+  'invalid-request': 'The preview request was not a valid repository, run, and reference triple.',
+  'cross-repository': 'The reference does not belong to the selected repository.',
+  'cross-run': 'The reference does not belong to the selected run.',
+  'unknown-reference':
+    'Poetic no longer publishes this reference for the run, so there is nothing to preview.',
+  'unsupported-kind':
+    'Only canonical patch evidence is previewable. Other evidence stays a reference.',
+  'unsafe-path': 'The reference did not resolve to a file inside the selected repository.',
+  symlink: 'A symlinked reference is not previewable.',
+  'not-a-regular-file': 'Only a regular file is previewable.',
+  missing: 'The referenced patch is no longer present.',
+  compressed: 'A compressed reference is not previewable.',
+  binary: 'A binary reference is not previewable.',
+};
+
+const UNAVAILABLE_NOTICES: Readonly<Record<string, string>> = {
+  'evidence-unavailable': 'Poetic published no canonical evidence to preview for this run.',
+  'incompatible-evidence': 'Poetic published canonical evidence this plugin cannot interpret.',
+  'read-failed': 'The referenced patch could not be read.',
+};
+
+function row(id: string, label: string, value: string): Row {
+  return { id, label, value };
+}
+
+/** A truncated body is labelled partial so it is never mistaken for the change. */
+function truncationNotice(): string {
+  return `Only the first ${PATCH_PREVIEW_MAX_BYTES} bytes are shown. This is a partial patch, not the complete change.`;
+}
+
+/** Build one deterministic, read-only preview view from the decided result. */
+export function buildPatchPreviewView(result: PatchPreviewResult): PatchPreviewView {
+  if (result.state === 'refused') {
+    return {
+      viewVersion: PATCH_PREVIEW_VIEW_VERSION,
+      state: 'refused',
+      runId: result.runId,
+      headline: 'Patch preview refused',
+      reference: null,
+      rows: [row('reason', 'Reason', result.reason), row('detail', 'Detail', result.message)],
+      body: null,
+      notices: [REFUSAL_NOTICES[result.reason] ?? result.message],
+      controls: [],
+    };
+  }
+
+  if (result.state === 'unavailable') {
+    return {
+      viewVersion: PATCH_PREVIEW_VIEW_VERSION,
+      state: 'unavailable',
+      runId: result.runId,
+      headline: 'Patch preview unavailable',
+      reference: null,
+      rows: [row('reason', 'Reason', result.reason), row('detail', 'Detail', result.message)],
+      body: null,
+      notices: [UNAVAILABLE_NOTICES[result.reason] ?? result.message],
+      controls: [],
+    };
+  }
+
+  const rows: Row[] = [
+    row('reference', 'Patch', result.reference.value),
+    row('variant', 'Variant', result.reference.variant ?? 'unavailable'),
+    row('bytes', 'Bytes shown', String(result.byteLength)),
+    row('lines', 'Lines shown', String(result.lineCount)),
+    row('ceiling', 'Byte ceiling', String(PATCH_PREVIEW_MAX_BYTES)),
+    row('truncated', 'Truncated', result.truncated ? 'yes' : 'no'),
+  ];
+
+  return {
+    viewVersion: PATCH_PREVIEW_VIEW_VERSION,
+    state: result.truncated ? 'truncated' : 'previewed',
+    runId: result.runId,
+    headline: result.truncated ? 'Patch preview truncated' : 'Patch preview',
+    reference: result.reference,
+    rows,
+    body: result.text,
+    notices: result.truncated ? [truncationNotice()] : [],
+    controls: [],
+  };
+}