@neriros/ralphy 2.21.3 → 2.22.0

package/README.md

@@ -156,7 +156,15 @@ Linear is the source of truth for which issues Ralph has touched. The `linear.in
 | `clearConflicted` | `Marker` or `{apply: Marker[]}` | Label(s) removed when a conflict-fix succeeds (status removal is not supported) |
 | `clearReview`     | `Marker` or `{apply: Marker[]}` | Label(s) removed when a review pickup happens (status removal is not supported) |
 
-A `Marker` is `{type: "label", value: "ralph:foo"}` or `{type: "status", value: "In Progress"}`. Combine with `apply` when one event sets multiple — e.g. `setDone` flipping a status _and_ adding a label.
+A `Marker` is one of three types:
+
+| Marker type    | Example value         | Effect                                                                                                                                                                                                                                    |
+| -------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"label"`      | `"ralph:in-progress"` | Adds or removes a Linear label on the issue                                                                                                                                                                                               |
+| `"status"`     | `"In Progress"`       | Updates the Linear workflow status of the issue                                                                                                                                                                                           |
+| `"attachment"` | `"In Progress"`       | Upserts a single **Ralphy** attachment on the issue; `value` becomes the subtitle. The same entry is reused across every lifecycle transition — Ralph creates it on first apply and edits it on subsequent ones, so the issue stays tidy. |
+
+Combine with `apply` when one event sets multiple — e.g. `setDone` flipping a status _and_ adding a label _and_ updating the attachment subtitle.
 
 Example `ralphy.config.json`:
 

package/dist/cli/index.js

@@ -35029,8 +35029,8 @@ import { readFileSync as readFileSync2 } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("2.21.3")
-      return "2.21.3";
+    if ("2.22.0")
+      return "2.22.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -35079,8 +35079,8 @@ function parseIndicatorArg(raw) {
     err.key = key;
     throw err;
   }
-  if (type !== "label" && type !== "status") {
-    const err = new Error("indicator type must be 'label' or 'status'");
+  if (type !== "label" && type !== "status" && type !== "attachment") {
+    const err = new Error("indicator type must be 'label', 'status', or 'attachment'");
     err.type = type;
     throw err;
   }
@@ -35420,7 +35420,9 @@ var init_cli = __esm(() => {
     "                          Keys: getTodo, getInProgress, getConflicted, getReview, getAutoMerge,",
     "                                setInProgress, setDone, setError, setConflicted,",
     "                                clearConflicted, clearReview",
-    "                          Types: label, status",
+    "                          Types: label, status, attachment",
+    "                          --indicator setInProgress:attachment:In Progress",
+    "                          (attachment upserts a single 'Ralphy' entry; value = subtitle)",
     "  --create-pr             Push the worker branch and open a GitHub PR on success (needs --worktree)",
     "  --fix-ci                After opening the PR, re-run on CI failures until green (needs --create-pr)",
     "  --code-review           Watch open tracked PRs for unresolved review comments and prepend a code-review task",
@@ -59669,12 +59671,16 @@ var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, Ralp
 
       // Applied when Ralph picks up an issue.
       // "setInProgress": { "type": "label", "value": "ralph:in-progress" },
+      // \u2014 or use attachment type to stamp a single "Ralphy" entry on the issue:
+      // "setInProgress": { "type": "attachment", "value": "In Progress" },
 
       // Applied on clean success.
       // "setDone": { "type": "status", "value": "In Review" },
+      // "setDone": { "type": "attachment", "value": "Done" },
 
       // Applied when the task exits with an error (quarantine signal).
       // "setError": { "type": "label", "value": "ralph:error" },
+      // "setError": { "type": "attachment", "value": "Error" },
 
       // Applied when a PR merge conflict is detected.
       // "setConflicted": { "type": "label", "value": "ralph:conflict" },
@@ -59691,7 +59697,7 @@ var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, Ralp
 var init_config = __esm(() => {
   init_zod();
   MarkerSchema = exports_external.object({
-    type: exports_external.enum(["label", "status"]),
+    type: exports_external.enum(["label", "status", "attachment"]),
     value: exports_external.string().min(1)
   });
   GetIndicatorSchema = exports_external.object({
@@ -60007,6 +60013,44 @@ async function fetchIssueComments(apiKey, issueId) {
   const data = await linearRequest(apiKey, query, { id: issueId });
   return data.issue?.comments.nodes ?? [];
 }
+async function createRalphyAttachment(apiKey, issueId, issueUrl, subtitle) {
+  const mutation = `mutation CreateAttachment(
+    $issueId: String!, $url: String!, $title: String!, $subtitle: String!
+  ) {
+    attachmentCreate(input: { issueId: $issueId, url: $url, title: $title, subtitle: $subtitle }) {
+      success
+      attachment { id }
+    }
+  }`;
+  const data = await linearRequest(apiKey, mutation, {
+    issueId,
+    url: issueUrl,
+    title: RALPHY_ATTACHMENT_TITLE,
+    subtitle
+  });
+  const attachmentId = data.attachmentCreate.attachment?.id;
+  if (!attachmentId)
+    throw new Error("attachmentCreate returned no attachment id");
+  return attachmentId;
+}
+async function updateAttachmentSubtitle(apiKey, attachmentId, subtitle) {
+  const mutation = `mutation UpdateAttachment($id: String!, $subtitle: String!) {
+    attachmentUpdate(id: $id, input: { subtitle: $subtitle }) { success }
+  }`;
+  await linearRequest(apiKey, mutation, {
+    id: attachmentId,
+    subtitle
+  });
+}
+async function upsertRalphyAttachment(apiKey, issueId, issueUrl, subtitle) {
+  const attachments = await fetchIssueAttachments(apiKey, issueId);
+  const existing = attachments.find((a) => a.title === RALPHY_ATTACHMENT_TITLE);
+  if (existing) {
+    await updateAttachmentSubtitle(apiKey, existing.id, subtitle);
+  } else {
+    await createRalphyAttachment(apiKey, issueId, issueUrl, subtitle);
+  }
+}
 async function fetchIssueAttachments(apiKey, issueId) {
   const query = `query IssueAttachments($id: String!) {
     issue(id: $id) {
@@ -60127,7 +60171,7 @@ async function removeLabelFromIssue(apiKey, issueId, labelId) {
     labelId
   });
 }
-var LINEAR_API = "https://api.linear.app/graphql", BRANCH_LABEL_PREFIX = "ralph:branch:";
+var LINEAR_API = "https://api.linear.app/graphql", RALPHY_ATTACHMENT_TITLE = "Ralphy", BRANCH_LABEL_PREFIX = "ralph:branch:";
 
 // apps/cli/src/agent/coordinator.ts
 class AgentCoordinator {
@@ -61404,6 +61448,9 @@ function buildAgentCoordinator(input) {
       }
       await updateIssueState(apiKey, issue.id, id);
       onLog(`  \u2192 ${issue.identifier} status='${m.value}'`, "gray");
+    } else if (m.type === "attachment") {
+      await upsertRalphyAttachment(apiKey, issue.id, issue.url, m.value);
+      onLog(`  \u2192 ${issue.identifier} attachment='${m.value}'`, "gray");
     } else {
       const id = await resolveLabelId(issue, m.value);
       if (!id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.21.3",
+  "version": "2.22.0",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",