@staff0rd/assist 0.416.0 → 0.418.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.416.0",
+  version: "0.418.0",
   type: "module",
   main: "dist/index.js",
   bin: {
@@ -6431,6 +6431,20 @@ function sendToDaemon(message) {
   });
 }
 
+// src/commands/sessions/daemon/readSocketLines.ts
+function readSocketLines(socket, onLine) {
+  let buffer = "";
+  socket.on("data", (chunk) => {
+    buffer += chunk.toString("utf8");
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      onLine(buffer.slice(0, newline));
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+    }
+  });
+}
+
 // src/commands/sessions/daemon/sendToDaemonAwaitAck.ts
 var ACK_TIMEOUT_MS = 1e3;
 function sendToDaemonAwaitAck(message) {
@@ -6449,16 +6463,8 @@ function sendToDaemonAwaitAck(message) {
         () => finish(new Error("timed out awaiting daemon ack")),
         ACK_TIMEOUT_MS
       );
-      let buffer = "";
-      socket.on("data", (chunk) => {
-        buffer += chunk.toString("utf8");
-        let newline = buffer.indexOf("\n");
-        while (newline !== -1) {
-          const line = buffer.slice(0, newline);
-          buffer = buffer.slice(newline + 1);
-          if (isAck(line)) return finish();
-          newline = buffer.indexOf("\n");
-        }
+      readSocketLines(socket, (line) => {
+        if (isAck(line)) finish();
       });
       socket.on("error", (error) => finish(error));
       socket.on(
@@ -18123,7 +18129,23 @@ async function prs(options2) {
   }
 }
 
-// src/commands/prs/raise.ts
+// src/commands/prs/buildValidatedBody.ts
+function buildValidatedBody(options2, usage) {
+  if (!options2.title || !options2.what || !options2.why) {
+    console.error(usage);
+    process.exit(1);
+  }
+  const body = buildPrBody({
+    what: options2.what,
+    why: options2.why,
+    how: options2.how,
+    resolves: options2.resolves
+  });
+  validatePrContent(options2.title, body);
+  return { title: options2.title, body };
+}
+
+// src/commands/prs/placePr.ts
 import { execFileSync as execFileSync7 } from "child_process";
 
 // src/commands/prs/buildCreateArgs.ts
@@ -18181,40 +18203,159 @@ function readSessionPrRef() {
   }
 }
 
-// src/commands/prs/raise.ts
-async function raise(options2) {
-  if (!options2.title || !options2.what || !options2.why) {
-    console.error(
-      "Usage: assist prs raise --title <title> --what <what> --why <why> [--how <how>] [--resolves <key>] [--force]"
+// src/commands/prs/recordPrActivity.ts
+async function recordPrActivity() {
+  if (resolveSessionItemId() === null) return;
+  const pr = readSessionPrRef();
+  if (pr) await recordSessionRefs([pr]);
+}
+
+// src/commands/prs/placePr.ts
+function hasUpstream() {
+  try {
+    execFileSync7(
+      "git",
+      ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+      { stdio: "pipe" }
     );
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ensureBranchPushed() {
+  const args = hasUpstream() ? ["push"] : ["push", "--set-upstream", "origin", "HEAD"];
+  execFileSync7("git", args, { stdio: "inherit" });
+}
+async function placePr(prNumber, title, body, options2) {
+  const args = prNumber !== null ? buildEditArgs(prNumber, title, body) : buildCreateArgs(title, body, options2);
+  try {
+    if (prNumber === null && !options2.head) ensureBranchPushed();
+    execFileSync7("gh", args, { stdio: "inherit" });
+  } catch {
     process.exit(1);
   }
-  const body = buildPrBody({
-    what: options2.what,
-    why: options2.why,
-    how: options2.how,
-    resolves: options2.resolves
+  await recordPrActivity();
+}
+
+// src/commands/prs/previewAndPlace.ts
+import { randomUUID as randomUUID4 } from "crypto";
+
+// src/commands/prs/parseIncoming.ts
+function parseIncoming(line, requestId) {
+  try {
+    const msg = JSON.parse(line);
+    if (msg.type === "error" && (msg.message ?? "").includes("pr-preview"))
+      return { kind: "error", message: msg.message ?? "pr-preview failed" };
+    if (msg.type !== "pr-decision" || msg.requestId !== requestId) return null;
+    if (msg.decision !== "approve" && msg.decision !== "reject") return null;
+    return {
+      kind: "decision",
+      decision: {
+        decision: msg.decision,
+        reason: msg.reason,
+        comments: Array.isArray(msg.comments) ? msg.comments : void 0
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/prs/requestPrDecision.ts
+function requestPrDecision(request) {
+  return new Promise((resolve19, reject) => {
+    connectToDaemon().then((socket) => {
+      let settled = false;
+      const finish = (error, decision) => {
+        if (settled) return;
+        settled = true;
+        socket.destroy();
+        if (error) reject(error);
+        else resolve19(decision);
+      };
+      readSocketLines(socket, (line) => {
+        const incoming = parseIncoming(line, request.requestId);
+        if (!incoming) return;
+        if (incoming.kind === "error") finish(new Error(incoming.message));
+        else finish(void 0, incoming.decision);
+      });
+      socket.on("error", (error) => finish(error));
+      socket.on(
+        "close",
+        () => finish(new Error("daemon closed before a decision was made"))
+      );
+      socket.write(`${JSON.stringify({ type: "pr-preview", ...request })}
+`);
+    }, reject);
   });
-  validatePrContent(options2.title, body);
-  const existing = findCurrentPrNumber();
-  if (existing !== null && !options2.force) {
+}
+
+// src/commands/prs/previewAndPlace.ts
+async function previewAndPlace(args) {
+  console.log("Awaiting your approval in the assist web UI preview pane\u2026");
+  let decision;
+  try {
+    decision = await requestPrDecision({
+      sessionId: args.sessionId,
+      requestId: randomUUID4(),
+      title: args.title,
+      body: args.body,
+      prNumber: args.prNumber
+    });
+  } catch (error) {
     console.error(
-      `Error: A pull request already exists for this branch (#${existing}). Pass --force to overwrite it, or use 'assist prs edit' to update individual sections.`
+      `Error: ${error instanceof Error ? error.message : String(error)}`
     );
     process.exit(1);
   }
-  const args = existing !== null ? buildEditArgs(existing, options2.title, body) : buildCreateArgs(options2.title, body, options2);
-  try {
-    execFileSync7("gh", args, { stdio: "inherit" });
-  } catch {
+  if (decision.decision === "reject") {
+    console.error(
+      `PR preview rejected${decision.reason ? `: ${decision.reason}` : "."}`
+    );
+    const comments3 = decision.comments ?? [];
+    if (comments3.length > 0) {
+      console.error(
+        `
+The reviewer left ${comments3.length} comment${comments3.length === 1 ? "" : "s"} on the preview. Address each one, then re-run this command:
+`
+      );
+      for (const [i, c] of comments3.entries()) {
+        const quoted = c.quote.split("\n").map((line) => `  > ${line}`).join("\n");
+        console.error(`${i + 1}. On:
+${quoted}
+   Comment: ${c.note}
+`);
+      }
+    }
     process.exit(1);
   }
-  await recordPrActivity();
+  await placePr(args.prNumber, args.title, args.body, args.options);
 }
-async function recordPrActivity() {
-  if (resolveSessionItemId() === null) return;
-  const pr = readSessionPrRef();
-  if (pr) await recordSessionRefs([pr]);
+
+// src/commands/prs/raise.ts
+var USAGE = "Usage: assist prs raise --title <title> --what <what> --why <why> [--how <how>] [--resolves <key>] [--force]";
+async function raise(options2) {
+  const { title, body } = buildValidatedBody(options2, USAGE);
+  const existing = findCurrentPrNumber();
+  const sessionId = process.env.ASSIST_SESSION_ID;
+  if (process.env.ASSIST_SESSION === "1" && sessionId) {
+    await previewAndPlace({
+      sessionId,
+      title,
+      body,
+      prNumber: existing,
+      options: options2
+    });
+    return;
+  }
+  if (existing !== null && !options2.force) {
+    console.error(
+      `Error: A pull request already exists for this branch (#${existing}). Pass --force to overwrite it, or use 'assist prs edit' to update individual sections.`
+    );
+    process.exit(1);
+  }
+  await placePr(existing, title, body, options2);
 }
 
 // src/commands/prs/reply.ts
@@ -18316,6 +18457,86 @@ function registerPrsEdit(prsCommand) {
   ).action(edit);
 }
 
+// src/commands/prs/raiseHelpText.ts
+var GUIDANCE = `Raise a pull request for the current branch. Use a concise description with no
+headers, and do not reference Claude or any AI assistance in the title or body.
+
+The body is assembled from discrete section options; supply at minimum --title,
+--what, and --why:
+
+  --title <title>   short PR title.
+  --what <what>     what the change does (rendered as ## What).
+  --why <why>       why the change is needed (rendered as ## Why).
+  --how <how>       optional; how the change works (rendered as ## How). Omit it
+                    unless the approach genuinely needs explaining.
+  --resolves <key>  Jira issue key resolved by this PR; repeatable. Each key's
+                    browse URL is appended inline to ## Why. Unless a Jira key is
+                    already known from the session, ask the user whether this PR
+                    resolves a Jira issue and for the key before raising; omit
+                    --resolves only if they say there isn't one.
+
+Wrap symbols, file paths, function names, class names, variable names, config
+keys, CLI commands, and flag names in backticks.
+
+One section, one question. Each section answers exactly one thing, and
+implementation detail lives only in ## How:
+
+  ## What  what is observably different for someone using or calling this, and
+           nothing else. Not how it's built, not which functions/files changed.
+  ## Why   the problem or motivation that made the change worth doing. Not how
+           the solution works.
+  ## How   only the non-obvious decisions the diff alone won't explain: a
+           deliberate trade-off, a workaround, a reason the obvious approach was
+           rejected. Omit it entirely by default. Never restate ## What as
+           mechanism, and never walk through the diff.
+
+The most common failure is altitude bleed: an implementation detail gets sprayed
+into whichever section is being written \u2014 ## What narrates the diff, ## How
+restates ## What, ## Why smuggles in mechanism. If a sentence describes a
+mechanism, it belongs in ## How, and probably shouldn't exist at all unless it's
+a genuine non-obvious decision. Litmus \u2014 a sentence is almost certainly mechanism
+(so ## How, or cut it) if it contains "by \u2026ing", "so that it can", "because the
+X filters/needs/uses", or names an internal component, property, function, or
+file.
+
+Brevity budget \u2014 keep each section within these limits:
+
+  ## What  a few sentences (2\u20133).
+  ## Why   1\u20132 sentences.
+  ## How   omit by default; a sentence or two, only for non-obvious decisions.
+
+Write prose. A short paragraph is the natural form for ## What and ## Why \u2014
+bullets in ## What are a smell. Use bullets only when there are genuinely several
+independent, parallel items (3+); a single bullet is never right. A single
+non-list paragraph over ~600 characters or ~4 sentences is a wall of text and
+will be rejected.
+
+If a pull request already exists for the branch, this command errors \u2014 pass
+--force to fully overwrite its title and body, or use 'assist prs edit' to update
+only individual sections (every other section of the existing body is preserved).`;
+var TERMINAL_CONFIRM = `Before running this command, the user must see the full proposed title and body \u2014
+do not assume they can see your reasoning or earlier tool output. Write the
+complete title and body verbatim in your visible reply, then use the
+AskUserQuestion tool to ask whether to create the PR, putting the full title and
+body in the approve option's preview field. This confirmation is mandatory in
+every permission mode, including auto-accept and bypass-permissions. If the user
+requests changes, revise and confirm again before running.`;
+var WEB_CONFIRM = `You are running inside an assist web session. When you run this command the
+drafted title and body are shown automatically in a preview pane beside the
+terminal in the web UI, for the user to approve or reject there \u2014 do NOT display
+the title and body or ask for confirmation in the terminal. The command blocks
+until the user decides: on approval it creates or updates the PR and reports it;
+on rejection it exits non-zero with the reason, which you must address before
+running again. Just compose the sections and run the command.`;
+function raiseHelpText() {
+  const confirm = process.env.ASSIST_SESSION === "1" ? WEB_CONFIRM : TERMINAL_CONFIRM;
+  return `
+${GUIDANCE}
+
+${confirm}
+`;
+}
+
 // src/commands/registerPrsRaise.ts
 function collect5(value, previous) {
   return previous.concat([value]);
@@ -18341,7 +18562,7 @@ function registerPrsRaise(prsCommand) {
     "Request a review (repeatable)",
     collect5,
     []
-  ).option("-m, --milestone <name>", "Add the pull request to a milestone").action(raise);
+  ).option("-m, --milestone <name>", "Add the pull request to a milestone").addHelpText("after", () => raiseHelpText()).action(raise);
 }
 
 // src/commands/registerPrs.ts
@@ -24838,7 +25059,8 @@ function toSessionInfo({
   autoAdvance,
   starred,
   usedPct,
-  design
+  design,
+  pendingPrPreview
 }) {
   return {
     id,
@@ -24865,7 +25087,8 @@ function toSessionInfo({
     autoAdvance,
     starred,
     usedPct,
-    design
+    design,
+    pendingPrPreview
   };
 }
 
@@ -25026,7 +25249,7 @@ function createAssistSession(id, assistArgs, cwd, meta) {
 }
 
 // src/commands/sessions/daemon/createSession.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 
 // src/commands/sessions/daemon/resolveRunConfig.ts
 function resolveRunConfig(name, cwd) {
@@ -25107,7 +25330,7 @@ function sessionBase(id, status3) {
 }
 function createSession(id, prompt, cwd, design, harness) {
   if (harness === "pi") return createPiSession(id, prompt, cwd);
-  const claudeSessionId = randomUUID4();
+  const claudeSessionId = randomUUID5();
   return {
     ...sessionBase(id, prompt ? "running" : "waiting"),
     name: prompt?.slice(0, 40) || `Session ${id}`,
@@ -25258,6 +25481,86 @@ function logSpawnedSession(session) {
   );
 }
 
+// src/commands/sessions/daemon/decidePrPreview.ts
+function decidePrPreview(sessions, waiters, notify2, d) {
+  const id = d.sessionId;
+  const requestId = d.requestId;
+  const session = sessions.get(id);
+  if (!session || session.pendingPrPreview?.requestId !== requestId) {
+    daemonLog(
+      `pr-decision for stale/unknown preview id=${id} requestId=${requestId} (ignoring)`
+    );
+    return;
+  }
+  const commentCount = Array.isArray(d.comments) ? d.comments.length : 0;
+  daemonLog(
+    `pr-decision received: id=${id} requestId=${requestId} decision=${d.decision} comments=${commentCount}`
+  );
+  const waiter = waiters.get(id);
+  if (waiter)
+    sendTo(waiter, {
+      type: "pr-decision",
+      requestId,
+      decision: d.decision,
+      reason: d.reason,
+      comments: d.comments
+    });
+  waiters.delete(id);
+  session.pendingPrPreview = void 0;
+  notify2();
+}
+
+// src/commands/sessions/daemon/setPrPreview.ts
+function setPrPreview(sessions, waiters, notify2, client, d) {
+  const id = d.sessionId;
+  const session = sessions.get(id);
+  if (!session) {
+    daemonLog(`pr-preview for unknown session id=${id} (ignoring)`);
+    sendTo(client, {
+      type: "error",
+      message: `No live session ${id} for pr-preview`
+    });
+    return;
+  }
+  const prNumber = typeof d.prNumber === "number" ? d.prNumber : null;
+  session.pendingPrPreview = {
+    requestId: d.requestId,
+    title: d.title,
+    body: d.body,
+    prNumber
+  };
+  waiters.set(id, client);
+  daemonLog(
+    `pr-preview set: id=${id} requestId=${d.requestId} target=${prNumber === null ? "create" : `edit #${prNumber}`}`
+  );
+  notify2();
+}
+
+// src/commands/sessions/daemon/PrPreviewCoordinator.ts
+var PrPreviewCoordinator = class {
+  constructor(sessions, notify2) {
+    this.sessions = sessions;
+    this.notify = notify2;
+  }
+  waiters = /* @__PURE__ */ new Map();
+  set(client, d) {
+    setPrPreview(this.sessions, this.waiters, this.notify, client, d);
+  }
+  decide(d) {
+    decidePrPreview(this.sessions, this.waiters, this.notify, d);
+  }
+  clearWaiter(client) {
+    for (const [id, waiter] of this.waiters) {
+      if (waiter !== client) continue;
+      this.waiters.delete(id);
+      const session = this.sessions.get(id);
+      if (session) session.pendingPrPreview = void 0;
+      daemonLog(`pr-preview cleared: id=${id} (waiting client disconnected)`);
+      this.notify();
+    }
+  }
+};
+
 // src/commands/sessions/daemon/applySetStatus.ts
 function applySetStatus(sessions, id, status3, source, onStatusChange) {
   const session = sessions.get(id);
@@ -25698,7 +26001,7 @@ function respawnSession(session, respawn, status3, clients, onStatusChange) {
 }
 
 // src/commands/sessions/daemon/respawnPlan.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 
 // src/commands/sessions/daemon/assistResumeArgs.ts
 function assistResumeArgs(session) {
@@ -25737,7 +26040,7 @@ function respawnPlan(session) {
   return null;
 }
 function freshClaudePlan(session, prompt, cwd) {
-  const claudeSessionId = randomUUID5();
+  const claudeSessionId = randomUUID6();
   return {
     spawn: () => {
       session.claudeSessionId = claudeSessionId;
@@ -27144,6 +27447,10 @@ var SessionManager = class {
     this.onIdleChange = onIdleChange;
   }
   sessions = /* @__PURE__ */ new Map();
+  prPreview = new PrPreviewCoordinator(
+    this.sessions,
+    () => this.notify()
+  );
   // why: dispatch calls active.set() on card click; broadcasts include active.toJSON()
   active = new ActiveSelection(() => this.notify());
   clients = new ClientHub(persistUsagePeak);
@@ -27159,6 +27466,7 @@ var SessionManager = class {
   removeClient(client) {
     this.clients.delete(client);
     this.clients.unsubscribeLogs(client);
+    this.prPreview.clearWaiter(client);
     this.onIdleChange?.(this.isIdle());
   }
   isIdle = () => this.sessions.size === 0 && this.clients.size === 0;
@@ -27531,6 +27839,8 @@ var messageHandlers = {
   ),
   "set-active": (_client, m, d) => m.active.set(d.cwd, d.sessionId),
   "set-status": handleSetStatus,
+  "pr-preview": (client, m, d) => m.prPreview.set(client, d),
+  "pr-decision": (_client, m, d) => m.prPreview.decide(d),
   "ui-status": (_client, _m, d) => daemonLog(`ui rendered: id=${d.sessionId} status=${d.status}`)
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@staff0rd/assist",
-	"version": "0.416.0",
+	"version": "0.418.0",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {