@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@poetic-ai/bb-plugin-poetic",
+  "version": "0.4.0",
+  "description": "Optional local BB panel for Poetic backlog, Fusion, and tracked execution",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "app.tsx",
+    "app.css",
+    "server.ts",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bb": ">=0.0",
+    "bbPluginSdk": "^0.4.1"
+  },
+  "bb": {
+    "name": "Poetic",
+    "description": "Inspect Poetic backlog items and run local Fusion panels.",
+    "branding": {
+      "icon": "Workflow"
+    },
+    "server": "./server.ts",
+    "app": "./app.tsx"
+  },
+  "keywords": [
+    "bb-plugin",
+    "poetic"
+  ],
+  "scripts": {
+    "build": "bb plugin build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^6.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/integrations/bb-plugin-poetic/server.ts

@@ -0,0 +1,444 @@
+import type { BbPluginApi } from '@bb/plugin-sdk';
+import { PoeticAdapter } from './src/adapter.js';
+import { BacklogAuthoringService } from './src/backlog-authoring-service.js';
+import { CompetitionDefaultsService } from './src/competition-defaults-service.js';
+import { buildCompetitionDefaultsView } from './src/competition-defaults-view.js';
+import { poeticRpcContract } from './src/contract.js';
+import { BacklogFinalizeService } from './src/finalize-service.js';
+import type { RepositoryView } from './src/model.js';
+import {
+  HOST_TRUST_DISCLOSURE,
+  TASK_PLANNING_DISCLOSURE,
+  TRACKED_EXECUTION_DISCLOSURE,
+} from './src/model.js';
+import { RunMonitorService } from './src/monitor-service.js';
+import { PatchPreviewService } from './src/patch-preview-service.js';
+import { buildPatchPreviewView } from './src/patch-preview-view.js';
+import { PollHandoff, resolvePollRuns } from './src/poll-handoff.js';
+import { type BbProject, listLocalProjects } from './src/project-target.js';
+import { resolveProjectTarget } from './src/project-target-server.js';
+import { LaunchReferenceIndex } from './src/reference-index.js';
+import { buildResultExplorerView } from './src/result-explorer-view.js';
+import { ResultReadbackService } from './src/result-readback-service.js';
+import { SetupConfigService } from './src/setup-config-service.js';
+import { buildSetupConfigView } from './src/setup-config-view.js';
+import { SprintCloseService } from './src/sprint-close-service.js';
+import {
+  SprintCompositionRequestError,
+  SprintCompositionService,
+} from './src/sprint-composition-service.js';
+import type { TaskAuthoringSprintFacts } from './src/task-authoring-schema.js';
+import { TaskAuthoringService } from './src/task-authoring-service.js';
+
+export const POETIC_PLUGIN_NAME = 'Poetic';
+export const POETIC_PLUGIN_VERSION = '0.4.0';
+
+export const POETIC_MONITOR_SERVICE_NAME = 'run-monitor';
+
+export default async function plugin(bb: BbPluginApi): Promise<void> {
+  const settings = bb.settings.define({
+    poeticExecutable: {
+      type: 'string',
+      label: 'Poetic executable',
+      description:
+        'Command name or absolute path used by the BB server. Reload the plugin after changing it.',
+      default: 'poetic',
+    },
+  });
+  const configured = await settings.get();
+  // Bounded, expiring discovery index for BB-launched runs. It holds identity
+  // only; every card is rehydrated from Poetic.
+  const references = new LaunchReferenceIndex(bb.storage.kv);
+  const adapter = new PoeticAdapter(
+    configured.poeticExecutable,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    references
+  );
+
+  async function projects(): Promise<BbProject[]> {
+    const primaryHostId = (await bb.sdk.system.config()).primaryHostId;
+    const available = await bb.sdk.projects.list({ includePersonal: true });
+    return available.map((project) => ({
+      id: project.id,
+      name: project.name,
+      sources: (project.sources ?? []).flatMap((source) =>
+        source.type === 'local_path' && primaryHostId !== null && source.hostId === primaryHostId
+          ? [{ id: source.id, type: source.type, hostId: source.hostId, path: source.path }]
+          : []
+      ),
+    }));
+  }
+
+  /**
+   * Resolve one repository. `panelRequest` distinguishes real panel activity from
+   * the monitor's own background read: only the former refreshes the watch TTL,
+   * so the service cannot keep a closed panel's repository alive by polling it.
+   */
+  async function context(input: { projectId: string; sourceId: string }, panelRequest = true) {
+    const target = await resolveProjectTarget(await projects(), input);
+    const repository = await adapter.inspect(target);
+    if (panelRequest) monitor.observe(input);
+    return { repository, target };
+  }
+
+  /**
+   * Isolated read-only services. Each one owns its own fixed argv and receives
+   * only the adapter's executable-resolving runner, so BB adds no second command
+   * builder, cache, or result authority. The patch preview reads the run's
+   * canonical evidence through the same readback service rather than a list of
+   * its own.
+   */
+  const resultReadbackService = new ResultReadbackService((command) =>
+    adapter.runReadCommand(command)
+  );
+  const patchPreviewService = new PatchPreviewService((repository, input) =>
+    resultReadbackService.read(repository, input)
+  );
+  const competitionDefaultsService = new CompetitionDefaultsService((command) =>
+    adapter.runReadCommand(command)
+  );
+  const setupConfigService = new SetupConfigService((command) => adapter.runReadCommand(command));
+
+  /**
+   * Adapt the adapter's exit-status-preserving seam to the strict-exit-code
+   * runner the backlog and sprint-composition lanes declare.
+   *
+   * A timeout is raised as an `ETIMEDOUT` error rather than reduced to an exit
+   * status, because those lanes report an interrupted command as an undetermined
+   * effect and would otherwise read it as a plain failure.
+   */
+  async function runAuthoringWithExitCode(command: {
+    file: 'poetic' | 'git';
+    args: readonly string[];
+    cwd: string;
+    timeoutMs: number;
+    maxOutputBytes?: number;
+  }): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const result = await adapter.runAuthoringCommand(command);
+    if (result.timedOut || result.exitCode === null) {
+      const error = new Error(
+        `${command.file} ${command.args.join(' ')} did not report an exit status.`
+      ) as Error & { code?: string };
+      error.code = 'ETIMEDOUT';
+      throw error;
+    }
+    return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
+  }
+
+  /**
+   * Isolated planning-authoring services. Each one owns its own fixed argv,
+   * consent object, timeouts, and admission; this registration only injects the
+   * adapter's executable-resolving runner and the canonical reads it already
+   * performs. BB adds no second command builder, planning mirror, or authority.
+   */
+  const backlogAuthoringService = new BacklogAuthoringService(runAuthoringWithExitCode);
+  const backlogFinalizeService = new BacklogFinalizeService(runAuthoringWithExitCode);
+  const sprintCompositionService = new SprintCompositionService(runAuthoringWithExitCode);
+  const sprintCloseService = new SprintCloseService(runAuthoringWithExitCode);
+  const taskAuthoringService = new TaskAuthoringService({
+    run: (command) => adapter.runAuthoringCommand(command),
+    readTask: (repository, taskId) => adapter.readTaskStatus(repository, taskId),
+    readSprint: (repository, sprintId) => readSprintFacts(repository, sprintId),
+    readWorkspace: (repository) => adapter.planningWorkspace(repository),
+    requireFreshRepositoryIdentity: (repository) =>
+      adapter.requireSelectedRepositoryIdentity(repository),
+  });
+
+  /**
+   * The minimal sprint facts task authoring rereads, taken from the sprint lane's
+   * own read-only projection so there is only one sprint reader. `null` means
+   * Poetic reported no such sprint; any other unavailable reason is raised, so a
+   * failed read is never reported as a missing sprint.
+   */
+  async function readSprintFacts(
+    repository: RepositoryView,
+    sprintId: string
+  ): Promise<TaskAuthoringSprintFacts | null> {
+    const output = await sprintCompositionService.getSprint(repository, {
+      projectId: repository.projectId,
+      sourceId: repository.sourceId,
+      sprintId,
+    });
+    if (output.sprint.state === 'unavailable') {
+      if (output.sprint.reason === 'Poetic reported a failed read.') return null;
+      throw new Error(output.sprint.reason);
+    }
+    const sprint = output.sprint.value;
+    return {
+      id: sprint.sprintId,
+      taskIds: sprint.tasks.map((task) => task.id),
+      capacity: {
+        allocatedHours: sprint.capacity.allocatedHours,
+        totalHours: sprint.capacity.totalHours,
+      },
+    };
+  }
+
+  const handoff = new PollHandoff();
+
+  const monitor = new RunMonitorService({
+    async pollTarget(target) {
+      const startedEpoch = handoff.beginRead(target);
+      const { repository } = await context(target, false);
+      if (repository.state === 'blocked') {
+        handoff.store(
+          {
+            projectId: target.projectId,
+            sourceId: target.sourceId,
+            observedAt: new Date().toISOString(),
+            repository,
+            runs: [],
+          },
+          startedEpoch
+        );
+        return { terminal: true, runs: 0 };
+      }
+      // Authoritative background read: narration stays off, so the cadence
+      // itself never issues a model call.
+      const runs = await adapter.poll(repository, undefined, { narrate: false });
+      handoff.store(
+        {
+          projectId: target.projectId,
+          sourceId: target.sourceId,
+          observedAt: new Date().toISOString(),
+          repository,
+          runs,
+        },
+        startedEpoch
+      );
+      return { terminal: runs.every((run) => run.terminal), runs: runs.length };
+    },
+    publish(channel, payload) {
+      bb.realtime.publish(channel, payload);
+    },
+    log(message) {
+      bb.log.warn(message);
+    },
+  });
+
+  bb.background.service(POETIC_MONITOR_SERVICE_NAME, {
+    start: (signal) => monitor.start(signal),
+  });
+
+  bb.rpc.register(poeticRpcContract, {
+    async listProjects() {
+      return { projects: listLocalProjects(await projects()) };
+    },
+    async capabilities(input) {
+      const { repository } = await context(input);
+      return {
+        repository,
+        disclosure: HOST_TRUST_DISCLOSURE,
+        trackedExecutionDisclosure: TRACKED_EXECUTION_DISCLOSURE,
+      };
+    },
+    async listBacklog(input) {
+      const { repository } = await context(input);
+      return { repository, items: await adapter.listBacklog(repository) };
+    },
+    async planningWorkspace(input) {
+      const { repository } = await context(input);
+      return { repository, workspace: await adapter.planningWorkspace(repository) };
+    },
+    async getBacklog(input) {
+      const { repository } = await context(input);
+      return {
+        repository,
+        item: await adapter.getBacklog(repository, input.backlogItemId),
+      };
+    },
+    async getTask(input) {
+      const { repository } = await context(input);
+      const detail = await adapter.getTask(repository, input.taskId);
+      return {
+        repository,
+        schemaVersion: detail.schemaVersion,
+        task: detail.task,
+      };
+    },
+    async launchFusion(input) {
+      const { repository } = await context(input);
+      const item = await adapter.getBacklog(repository, input.backlogItemId);
+      return { repository, run: await adapter.launchFusion(repository, item) };
+    },
+    async launchCompetition(input) {
+      const { repository } = await context(input);
+      const item = await adapter.getBacklog(repository, input.backlogItemId);
+      return { repository, run: await adapter.launchCompetition(repository, item) };
+    },
+    async launchTrackedBacklog(input) {
+      const { repository } = await context(input);
+      const item = await adapter.getBacklog(repository, input.backlogItemId);
+      return {
+        repository,
+        disclosure: TRACKED_EXECUTION_DISCLOSURE,
+        run: await adapter.launchTrackedBacklog(repository, item),
+      };
+    },
+    async observeCompetition(input) {
+      const { repository } = await context(input);
+      return {
+        repository,
+        run: await adapter.observeCompetition(repository, input.runId),
+      };
+    },
+    async pollRuns(input) {
+      return resolvePollRuns(input, {
+        handoff,
+        refreshWatch: (target) => monitor.observe(target),
+        readFresh: async (observe) => {
+          const { repository } = await context(input, observe);
+          return {
+            repository,
+            runs: await adapter.poll(repository, input.operationIds, {
+              narrate: input.narrate,
+              fresh: input.fresh === true,
+            }),
+          };
+        },
+      });
+    },
+    async cancelRun(input) {
+      const { repository } = await context(input);
+      return {
+        repository,
+        run: await adapter.cancel(repository, input.operationId),
+      };
+    },
+    /**
+     * Apply one closed-vocabulary task action. The host validated input carries no
+     * argv, flags, cwd, env, or executable, and the response reports Poetic's
+     * authoritative readback rather than the child process exit status.
+     */
+    async applyTaskAction(input) {
+      const { repository } = await context(input);
+      const outcome = await adapter.applyTaskAction(repository, input);
+      return {
+        repository,
+        disclosure: TASK_PLANNING_DISCLOSURE,
+        action: outcome.action,
+        taskId: outcome.taskId,
+        command: outcome.command,
+        syncWarnings: outcome.syncWarnings,
+        workspace: outcome.workspace,
+        taskDetail: outcome.taskDetail,
+      };
+    },
+    /**
+     * Read one run's canonical result readback. The service binds the response to
+     * the selected repository and run identity, and the explorer view is pure
+     * presentation over that one observation.
+     */
+    async readResult(input) {
+      const { repository } = await context(input);
+      const result = await resultReadbackService.read(repository, input);
+      return { repository, view: buildResultExplorerView(input.kind, result) };
+    },
+    /**
+     * Preview exactly one canonical patch reference. This is the only registered
+     * method that reads file content, and it refuses every reference that is not
+     * canonical patch evidence for this repository and run.
+     */
+    async previewPatch(input) {
+      const { repository } = await context(input);
+      const result = await patchPreviewService.preview(repository, input);
+      return { repository, view: buildPatchPreviewView(result) };
+    },
+    /** Read-only defaults disclosure. It changes no configuration. */
+    async competitionDefaults(input) {
+      const { repository } = await context(input);
+      const result = await competitionDefaultsService.read(repository);
+      return { repository, view: buildCompetitionDefaultsView(result) };
+    },
+    /**
+     * Read-only setup and configuration status. It is available for a warning or
+     * blocked repository too, because that is exactly when setup status is needed;
+     * guidance stays copyable text and is never executed here.
+     */
+    async setupStatus(input) {
+      const { repository } = await context(input);
+      const result = await setupConfigService.read(repository);
+      return { repository, view: buildSetupConfigView(result) };
+    },
+    /**
+     * Apply one closed-vocabulary backlog authoring action. Every refusal this
+     * lane reports happens before the command is launched, so it is raised as an
+     * error; once a process has run the outcome envelope is always returned,
+     * including on a nonzero exit, so partial-effect evidence is never discarded.
+     */
+    async applyBacklogAuthoring(input) {
+      const { repository } = await context(input);
+      const result = await backlogAuthoringService.apply(repository, input);
+      if ('state' in result) throw new Error(result.message);
+      return result;
+    },
+    /**
+     * Apply one custom task authoring or relationship action. A refusal never
+     * reached a process and becomes an error; a completed attempt returns the
+     * lane's outcome envelope with Poetic's own rereads.
+     */
+    async applyTaskAuthoring(input) {
+      const { repository } = await context(input);
+      const result = await taskAuthoringService.apply(repository, input);
+      if (result.state === 'refused') throw new Error(result.message);
+      return result.outcome;
+    },
+    /**
+     * Apply one sprint-composition action. This lane reports a pre-launch refusal
+     * inside its own outcome envelope, so only a request that names no accepted
+     * action becomes an error.
+     */
+    async applySprintComposition(input) {
+      const { repository } = await context(input);
+      try {
+        return await sprintCompositionService.apply(repository, input);
+      } catch (error) {
+        if (error instanceof SprintCompositionRequestError) throw new Error(error.message);
+        throw error;
+      }
+    },
+    /** Read-only sprint enumeration. Poetic's list payload is carried verbatim. */
+    async listSprints(input) {
+      const { repository } = await context(input);
+      return await sprintCompositionService.listSprints(repository, input);
+    },
+    /** Read-only single-sprint projection, always with an explicit sprint id. */
+    async getSprint(input) {
+      const { repository } = await context(input);
+      return await sprintCompositionService.getSprint(repository, input);
+    },
+    /**
+     * Finalize one backlog item. A refusal never reached a process and becomes
+     * an error; a completed attempt returns the outcome envelope with Poetic's
+     * own rereads. There is no `--auto` finalize.
+     */
+    async applyBacklogFinalize(input) {
+      const { repository } = await context(input);
+      const result = await backlogFinalizeService.apply(repository, input);
+      if ('state' in result) throw new Error(result.message);
+      return result;
+    },
+    /**
+     * Close one sprint after a fresh closable read. A refusal never reached a
+     * process and becomes an error; a completed attempt returns the outcome
+     * envelope with Poetic's own rereads.
+     */
+    async applySprintClose(input) {
+      const { repository } = await context(input);
+      const result = await sprintCloseService.apply(repository, input);
+      if ('state' in result) throw new Error(result.message);
+      return result;
+    },
+  });
+
+  // The service's own abort signal already ends the loop on reload/disable/
+  // shutdown; this hook makes the teardown explicit and observable.
+  bb.onDispose(() => {
+    bb.log.info(`${POETIC_PLUGIN_NAME} ${POETIC_PLUGIN_VERSION} monitor stopped`);
+  });
+
+  bb.log.info(`${POETIC_PLUGIN_NAME} ${POETIC_PLUGIN_VERSION} loaded`);
+}