@mgiles/perk 3.0.0 → 3.2.0

package/extension/doors/objectiveReviewBrowser.ts

@@ -324,22 +324,29 @@ export async function routeObjectiveReviewDecision(
 }
 
 /**
- * The background open: start the plan-review browser on the RENDERED objective draft, prime
- * BOTH companion surfaces the moment the port is picked (the URL is deterministic — see the
- * header note), observe readiness and the human decision in background tasks, and inject the
- * guidance immediately. While plannotator sets up, its in-process `console.error` chatter
- * re-routes through the TUI-safe report() seam (the debounce restores once setup goes quiet,
- * with the `finally` as a backstop). `deps` is the injectable browser-open seam (tests drive a
- * fake port picker/probe/clock). `rendered` is the reviewed markdown; `artifactRaw` is the raw
- * structured `objective-draft.json` bytes captured at open — the stale guard's baseline.
+ * The guidance-returning open core: start the plan-review browser on the RENDERED objective
+ * draft, prime BOTH companion surfaces the moment the port is picked (the URL is deterministic
+ * — see the header note), observe readiness and the human decision in background tasks, and
+ * RETURN the composed guidance string (template + the `command:objective-review-browser`
+ * binding suffix) — the caller decides how to deliver it (the door wrapper injects it via
+ * `sendUserMessage`; `plan_review`'s wave arm returns it as a non-terminating tool result,
+ * contracts.md §8.23). Returns `null` on the synchronous port-pick failure arm — loudly
+ * reported here, then CALLER-handled: the door wrapper simply injects nothing (the report
+ * already spoke), while `plan_review`'s wave arm — the one fallback caller — falls open to the
+ * plain blocking review. While plannotator sets up, its in-process `console.error`
+ * chatter re-routes through the TUI-safe report() seam (the debounce restores once setup goes
+ * quiet, with the `finally` as a backstop). `deps` is the injectable browser-open seam (tests
+ * drive a fake port picker/probe/clock). `rendered` is the reviewed markdown; `artifactRaw` is
+ * the raw structured `objective-draft.json` bytes captured at open — the stale guard's
+ * baseline.
  */
-export async function openObjectiveReviewAndGuide(
+export async function openObjectiveReviewSurface(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   gating: ToolGating,
   opts: { rendered: string; artifactRaw: string; custom?: string },
   deps: StartBrowserDeps = {},
-): Promise<void> {
+): Promise<string | null> {
   let started: StartedSurface<ReviewOutcome>;
   try {
     // The plan-review bridge sends arbitrary string bytes as `planContent` — the rendered
@@ -358,7 +365,7 @@ export async function openObjectiveReviewAndGuide(
       `could not pick a free local port for the plannotator plan-review server: ${detail}`,
       { alsoLog: true },
     );
-    return;
+    return null;
   }
 
   // Prime BOTH companion surfaces the moment the port is picked: push_annotations serves this
@@ -421,13 +428,29 @@ export async function openObjectiveReviewAndGuide(
       ? `working objective draft → plannotator browser review + draft reviewers (custom lane: ${opts.custom}) → APPROVE auto-saves / DENY returns feedback`
       : "working objective draft → plannotator browser review + draft reviewers → APPROVE auto-saves / DENY returns feedback",
   );
-  pi.sendUserMessage(
+  return (
     objectiveReviewBrowserGuidance({
       ...(opts.custom !== undefined ? { custom: opts.custom } : {}),
-    }) + bindingSuffix(ctx.cwd, `command:${SCOPE}`),
+    }) + bindingSuffix(ctx.cwd, `command:${SCOPE}`)
   );
 }
 
+/**
+ * The door-facing open: the thin `sendUserMessage` wrapper over `openObjectiveReviewSurface` —
+ * the command handler's delivery is the guidance injection; a `null` core return (port-pick
+ * failure, already loudly reported) injects nothing.
+ */
+export async function openObjectiveReviewAndGuide(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { rendered: string; artifactRaw: string; custom?: string },
+  deps: StartBrowserDeps = {},
+): Promise<void> {
+  const guidance = await openObjectiveReviewSurface(pi, ctx, gating, opts, deps);
+  if (guidance !== null) pi.sendUserMessage(guidance);
+}
+
 // ------------------------------------------------------------------------ registration
 
 /** Register the warm `/objective-review-browser` command (no tools — the companions are global). */