@neriros/ralphy 2.21.3 → 2.22.1

package/README.md

@@ -142,21 +142,29 @@ The cycle repeats every poll. For code-review-iteration in particular, `setDone`
 
 Linear is the source of truth for which issues Ralph has touched. The `linear.indicators` map declares how Ralph queries and mutates Linear at each lifecycle event. All keys are optional; an unset key means "Ralph doesn't perform that action".
 
-| Key               | Type                            | Purpose                                                                         |
-| ----------------- | ------------------------------- | ------------------------------------------------------------------------------- |
-| `getTodo`         | `{filter: Marker[]}`            | Issues to pick up (fresh)                                                       |
-| `getInProgress`   | `{filter: Marker[]}`            | Issues to resume after restart                                                  |
-| `getConflicted`   | `{filter: Marker[]}`            | Issues whose PR is conflicted (re-fix run)                                      |
-| `getReview`       | `{filter: Marker[]}`            | Done issues flagged for review follow-up                                        |
-| `getAutoMerge`    | `{filter: Marker[]}`            | Issues whose PR should be auto-merged once required checks pass                 |
-| `setInProgress`   | `Marker` or `{apply: Marker[]}` | Applied when a worker spawns (any non-resume mode)                              |
-| `setDone`         | `Marker` or `{apply: Marker[]}` | Applied on clean exit                                                           |
-| `setError`        | `Marker` or `{apply: Marker[]}` | Applied on non-zero exit (quarantine signal — issue is _not_ auto-resumed)      |
-| `setConflicted`   | `Marker` or `{apply: Marker[]}` | Applied when a done-PR is detected as conflicted                                |
-| `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.
+| Key               | Type                   | Purpose                                                                         |
+| ----------------- | ---------------------- | ------------------------------------------------------------------------------- |
+| `getTodo`         | `{filter: Marker[]}`   | Issues to pick up (fresh)                                                       |
+| `getInProgress`   | `{filter: Marker[]}`   | Issues to resume after restart                                                  |
+| `getConflicted`   | `{filter: Marker[]}`   | Issues whose PR is conflicted (re-fix run)                                      |
+| `getReview`       | `{filter: Marker[]}`   | Done issues flagged for review follow-up                                        |
+| `getAutoMerge`    | `{filter: Marker[]}`   | Issues whose PR should be auto-merged once required checks pass                 |
+| `setInProgress`   | `Marker` or `Marker[]` | Applied when a worker spawns (any non-resume mode)                              |
+| `setDone`         | `Marker` or `Marker[]` | Applied on clean exit                                                           |
+| `setError`        | `Marker` or `Marker[]` | Applied on non-zero exit (quarantine signal — issue is _not_ auto-resumed)      |
+| `setConflicted`   | `Marker` or `Marker[]` | Applied when a done-PR is detected as conflicted                                |
+| `clearConflicted` | `Marker` or `Marker[]` | Label(s) removed when a conflict-fix succeeds (status removal is not supported) |
+| `clearReview`     | `Marker` or `Marker[]` | Label(s) removed when a review pickup happens (status removal is not supported) |
+
+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. |
+
+Use an array when one event sets multiple — e.g. `setDone` flipping a status _and_ adding a label _and_ updating the attachment subtitle.
 
 Example `ralphy.config.json`:
 
@@ -192,12 +200,10 @@ Example `ralphy.config.json`:
         "filter": [{ "type": "label", "value": "ralph:auto-merge" }],
       },
       "setInProgress": { "type": "status", "value": "In Progress" },
-      "setDone": {
-        "apply": [
-          { "type": "status", "value": "In Review" },
-          { "type": "label", "value": "ralphy-done" },
-        ],
-      },
+      "setDone": [
+        { "type": "status", "value": "In Review" },
+        { "type": "label", "value": "ralphy-done" },
+      ],
       "setError": { "type": "label", "value": "ralph:error" },
       "setConflicted": { "type": "label", "value": "ralph:conflicted" },
       "clearConflicted": { "type": "label", "value": "ralph:conflicted" },

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.1")
+      return "2.22.1";
   } 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;
   }
@@ -35095,13 +35095,7 @@ function mergeIndicator(bag, key, marker) {
     bag[key] = { filter: filter2 };
   } else {
     const existing = bag[key];
-    let next;
-    if (!existing)
-      next = marker;
-    else if ("apply" in existing)
-      next = { apply: [...existing.apply, marker] };
-    else
-      next = { apply: [existing, marker] };
+    const next = existing ? [...Array.isArray(existing) ? existing : [existing], marker] : marker;
     bag[key] = next;
   }
 }
@@ -35420,7 +35414,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",
@@ -39408,7 +39404,7 @@ var init_zod = __esm(() => {
 
 // packages/types/src/types.ts
 function markersOf(set2) {
-  return "apply" in set2 ? set2.apply : [set2];
+  return Array.isArray(set2) ? set2 : [set2];
 }
 var IterationUsageSchema, UsageSchema, HistoryEntrySchema, StateSchema, PhaseFrontmatterSchema;
 var init_types2 = __esm(() => {
@@ -59536,8 +59532,26 @@ async function loadRalphyConfig(projectRoot) {
     return RalphyConfigSchema.parse({});
   }
   const text = await file.text();
-  const raw = JSON.parse(stripJsonComments(text));
-  return RalphyConfigSchema.parse(raw);
+  let raw;
+  try {
+    raw = JSON.parse(stripJsonComments(text));
+  } catch (error) {
+    throw new Error(`ralphy.config.json is not valid JSON.
+` + `  File: ${path}
+` + `  ${error instanceof Error ? error.message : String(error)}
+
+` + `Run \`ralph init\` to see the full default config with all available settings.`);
+  }
+  const result2 = RalphyConfigSchema.safeParse(raw);
+  if (!result2.success) {
+    const issues = result2.error.issues.map((issue) => `  \u2022 ${issue.path.join(".") || "(root)"}: ${issue.message}`).join(`
+`);
+    throw new Error(`ralphy.config.json has invalid settings:
+${issues}
+
+` + `Run \`ralph init\` to see the full default config with all available settings.`);
+  }
+  return result2.data;
 }
 async function ensureRalphyConfig(projectRoot) {
   const path = join11(projectRoot, "ralphy.config.json");
@@ -59667,14 +59681,18 @@ var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, Ralp
       // after opening the PR so the PR merges as soon as required checks pass.
       // "getAutoMerge": { "filter": [{ "type": "label", "value": "ralph:auto-merge" }] },
 
-      // Applied when Ralph picks up an issue.
+      // Applied when Ralph picks up an issue. Single marker or array of markers.
       // "setInProgress": { "type": "label", "value": "ralph:in-progress" },
+      // "setInProgress": { "type": "attachment", "value": "In Progress" },
+      // "setInProgress": [{ "type": "status", "value": "In Progress" }, { "type": "attachment", "value": "In Progress" }],
 
       // Applied on clean success.
       // "setDone": { "type": "status", "value": "In Review" },
+      // "setDone": [{ "type": "status", "value": "In Review" }, { "type": "attachment", "value": "Done" }],
 
       // Applied when the task exits with an error (quarantine signal).
       // "setError": { "type": "label", "value": "ralph:error" },
+      // "setError": [{ "type": "label", "value": "ralph:error" }, { "type": "attachment", "value": "Error" }],
 
       // Applied when a PR merge conflict is detected.
       // "setConflicted": { "type": "label", "value": "ralph:conflict" },
@@ -59691,16 +59709,13 @@ 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({
     filter: exports_external.array(MarkerSchema).default([])
   });
-  SetIndicatorSchema = exports_external.union([
-    MarkerSchema,
-    exports_external.object({ apply: exports_external.array(MarkerSchema).min(1) })
-  ]);
+  SetIndicatorSchema = exports_external.union([exports_external.array(MarkerSchema).min(1), MarkerSchema]);
   IndicatorsSchema = exports_external.object({
     getTodo: GetIndicatorSchema.optional(),
     getInProgress: GetIndicatorSchema.optional(),
@@ -59718,7 +59733,7 @@ var init_config = __esm(() => {
       const clear = value[key];
       if (!clear)
         continue;
-      const markers = "apply" in clear ? clear.apply : [clear];
+      const markers = Array.isArray(clear) ? clear : [clear];
       for (const m of markers) {
         if (m.type !== "label") {
           ctx.addIssue({
@@ -60007,6 +60022,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 +60180,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 +61457,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) {
@@ -61436,7 +61492,7 @@ function buildAgentCoordinator(input) {
   async function fetchByGet(inc, excl) {
     if (!inc)
       return [];
-    const include = "filter" in inc ? inc.filter : [];
+    const include = !Array.isArray(inc) && "filter" in inc ? inc.filter : [];
     if (include.length === 0)
       return [];
     const spec = {

package/package.json

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