npm - @muggleai/works - Versions diffs - 4.11.3 → 4.12.0 - Mend

@muggleai/works 4.11.3 → 4.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/plugin/skills/muggle-pr-followup/output-templates/escalation.md ADDED Viewed

@@ -0,0 +1,32 @@
+# Escalation messages
+Emitted by `/muggle-do` in address-reviews mode. One per invocation, at most. Anchored here so wording stays consistent.
+## Ambiguous escalation
+```
+**Review-followup escalation — <owner>/<repo>#<n>**
+I can't act on <count> review(s) without your input. Listed below; reply on GitHub by submitting a new review with clearer direction, or tell me here which way to go.
+Review #<id> from <login>:
+> <body or "(no body)">
+Comments:
+- <file>:<line> — <body>
+- ...
+[Repeat per ambiguous review in the batch.]
+```
+## Design-adjustment escalation
+```
+**Design-adjustment needed — <owner>/<repo>#<n>**
+While addressing review #<id>, the cycle surfaced a conflict with the current design:
+  <one-paragraph description of the conflict>
+This is beyond a routine code change. Confirm the design intent (reply here, or update the requirements doc) before I retry.
+```

package/plugin/skills/muggle-pr-followup/output-templates/help.md ADDED Viewed

@@ -0,0 +1,17 @@
+# Help output
+For `/muggle:muggle-pr-followup` with no args, or with `help` / `?`:
+```
+muggle-pr-followup — watcher loop for PR review follow-ups
+Active loops:
+  <slug> → <owner>/<repo>#<n> (cursor @ review #<id>, <N> cycles)
+  ...
+  (or "no active loops")
+Usage:
+  /muggle:muggle-pr-followup <pr-url>            → bootstrap a new loop
+  /muggle:muggle-pr-followup <slug> <pr-number>  → run one tick (called by /loop)
+  /muggle:muggle-pr-followup <pr-number>         → run one tick (slug inferred from on-disk state)
+```

package/plugin/skills/muggle-pr-followup/output-templates/inline-reply.md ADDED Viewed

@@ -0,0 +1,17 @@
+# Per-comment inline reply
+Posted via `gh api .../comments/<comment-id>/replies` per cycle, one per line comment.
+```
+Addressed in <short-sha>: <one-line summary of the change made for THIS comment>.
+```
+`<short-sha>` is the first 7 chars of the new SHA. The body must contain that substring — the resolve-reminder stage greps for it to classify threads as addressed-by-loop.
+## Top-level fallback (review-body-only)
+When an actionable review has a non-empty body but zero line comments, GitHub has no `/replies` endpoint for the body. Post a top-level PR comment instead, at most once per such review:
+```
+Re: review #<review_id> — addressed in <short-sha>: <one-line summary>.
+```

package/plugin/skills/muggle-pr-followup/output-templates/resolve-reminder.md ADDED Viewed

@@ -0,0 +1,12 @@
+# Resolve-reminder top-level PR comment
+Posted via `gh pr comment` after the resolve-reminder stage scans threads. Only when at least one addressed-by-loop thread exists.
+```
+I addressed these threads in <short-sha> — mark them resolved when satisfied:
+- #<thread-id-1>
+- #<thread-id-2>
+- ...
+```
+If `addressed_by_loop == 0`, no comment is posted (silent).

package/plugin/skills/muggle-pr-followup/output-templates/watcher-log.md ADDED Viewed

@@ -0,0 +1,21 @@
+# Watcher tick log lines
+The watcher does **not** print to the user during normal operation. It only appends to `followup.log`. All user-facing escalations come from `/muggle-do`.
+## Idle tick
+```
+<ISO-8601> tick pr=<n> reviews_seen=0 idle
+```
+## Dispatching tick
+```
+<ISO-8601> tick pr=<n> reviews_seen=<count> dispatched=<id1>,<id2>,...
+```
+## Terminal tick
+```
+<ISO-8601> tick pr=<n> terminal=<merged|closed> result.md written
+```

package/plugin/skills/muggle-pr-followup/output-templates.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Output templates
+All user-facing message text used by the watcher, bootstrap, and `/muggle-do` in address-reviews mode. Each template group is its own file — load only what the current step emits.
+## Index
+| Group | Use case |
+| :---- | :------- |
+| [`bootstrap`](output-templates/bootstrap.md) | Bootstrap success summary + all bootstrap aborts. |
+| [`watcher-log`](output-templates/watcher-log.md) | The three `followup.log` line shapes (idle, dispatching, terminal). |
+| [`escalation`](output-templates/escalation.md) | `/muggle-do` terminal escalation messages (ambiguous, design-adjustment). |
+| [`inline-reply`](output-templates/inline-reply.md) | Per-comment inline reply + top-level fallback for body-only reviews. |
+| [`resolve-reminder`](output-templates/resolve-reminder.md) | Top-level PR comment for the resolve-reminder stage. |
+| [`help`](output-templates/help.md) | Skill help output (no args / `help` / `?`). |

package/plugin/skills/muggle-pr-followup/state-schemas.md ADDED Viewed

@@ -0,0 +1,104 @@
+# Session State Schemas
+Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `.muggle-do/sessions/<slug>/` (the caller's session dir; `muggle-do` is the current and only caller).
+All files are atomic writes — the caller rewrites the whole file each time, never mutates in place. Use a temp file + rename if the platform supports it.
+## `prs.json`
+A list of one entry. (Historical: the file is an array for forward-compat with the original session-wide model. Today, each PR has its own session slot, so the array always has exactly one entry.)
+```json
+[
+  {
+    "repo": "<owner>/<repo>",
+    "number": <int>,
+    "url": "https://github.com/<owner>/<repo>/pull/<number>",
+    "head_sha": "<40-char-hex-sha>",
+    "state": "open" | "merged" | "closed"
+  }
+]
+```
+- `state` is the **observed** state from the last `gh pr view`. The watcher refreshes it each tick.
+- Terminal states (`merged`, `closed`) are sticky — once set, the watcher writes `result.md` and exits without rescheduling.
+## `last_seen.json`
+Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
+```json
+{
+  "<owner>/<repo>#<n>": {
+    "reviewId": <int>,
+    "last_pushed_sha": "<sha-or-null>",
+    "idle_tick_count": <int>,
+    "cycles_completed": <int>,
+    "escalated_review_ids": [<int>, ...],
+    "pushed_shas": ["<sha>", ...]
+  }
+}
+```
+- `reviewId`: the cursor. The watcher fetches reviews with `id > reviewId`. Bootstrap pins this to the highest existing submitted review id (or `0` if none).
+- `last_pushed_sha`: most recent SHA `/muggle-do` pushed in this PR's life; `null` until the first push.
+- `idle_tick_count`: incremented each tick that sees zero new reviews. Reset to 0 on any tick that dispatches `/muggle-do`. Diagnostic only — does not gate behavior.
+- `cycles_completed`: incremented each time `/muggle-do` completes an address-reviews invocation (regardless of actionable/ambiguous/mixed).
+- `escalated_review_ids`: review ids classified as ambiguous by `/muggle-do`. The watcher excludes these from future review fetches so the same ambiguous review is never re-dispatched.
+- `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
+## `state.md`
+Free-form markdown. No required schema beyond a few well-known fields the caller-agnostic code reads:
+```markdown
+# Session — <slug>
+**PR:** <url>
+**Slug:** <slug>
+**Loop user:** <github-login>          ← cached from `gh api user`
+**Created:** <ISO-8601>
+**Bootstrapped from URL:** <yes | no>
+...free-form notes added by /muggle-do and bootstrap...
+```
+The watcher does **not** read or write `state.md`. Only bootstrap, `/muggle-do`, and the caller's stages touch it.
+## `followup.log`
+Append-only line-per-tick log. One line per watcher tick, plus one line per `/muggle-do` invocation. Format is loose, but each line starts with an ISO-8601 timestamp:
+```
+2026-05-20T12:34:56Z tick pr=154 reviews_seen=0 idle
+2026-05-20T12:35:56Z tick pr=154 reviews_seen=1 dispatched=4295962800
+2026-05-20T12:36:14Z muggle-do cycle review_ids=[4295962800] outcome=pushed head_sha=abc1234
+```
+Used for forensics only — never read back by skills.
+## `result.md`
+Written exactly once when the PR's watcher exits terminally (PR merged or closed). Free-form markdown summarizing the PR's life under this loop:
+```markdown
+# Result — <slug>
+**PR:** <url>
+**Final state:** merged | closed
+**Cycles completed:** <int>
+**Pushed SHAs:** <comma-separated list>
+**Escalated review ids:** <comma-separated list or "none">
+## Timeline
+- <ISO-8601> bootstrap (cursor pinned at <reviewId>)
+- <ISO-8601> review <id> from <login> — actionable, pushed <sha>
+- <ISO-8601> review <id> from <login> — ambiguous, escalated
+- ...
+- <ISO-8601> PR <merged|closed> — watcher terminal
+```
+## Not in the slot
+`cycle.json` and `requirements.md` are not seeded or read. `/muggle-do` reads reviews off GitHub each invocation.

package/plugin/skills/muggle-test-regenerate-missing/SKILL.md CHANGED Viewed

@@ -180,15 +180,15 @@ Bulk regen does not run replays, so the section B (replay) router does not apply
 ### Step 8 — Open the Dashboard
-Open the Muggle AI dashboard so the user can watch progress visually:
+Open the Muggle AI dashboard so the user can watch progress visually. Point them at the **scripts** page (where DRAFT → GENERATING → ACTIVE transitions are visible), not `/runs` (which is for replay batches and shows nothing for a regen):
 ```bash
-open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
+open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts"
 ```
 Tell them:
-> "I've opened the project's runs page. Generation jobs typically take a few minutes each — they'll appear here as they progress. Your test cases will move into `ACTIVE` status as scripts complete."
+> "I've opened the project's scripts page. Generation jobs typically take a few minutes each — your test cases will move from `DRAFT` through `GENERATING` to `ACTIVE` as scripts complete."
 ### Step 9 (optional) — Poll Status

package/scripts/postinstall.mjs CHANGED Viewed

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* global AbortController */
 /**
  * Postinstall script for @muggleai/works.
  * Downloads the Electron app binary for local testing.
@@ -30,6 +31,8 @@ const VERSION_DIRECTORY_NAME_PATTERN = /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/;
 const INSTALL_METADATA_FILE_NAME = ".install-metadata.json";
 const INSTALL_MANIFEST_FILE_NAME = "install-manifest.json";
 const LOG_FILE_NAME = "postinstall.log";
+const FETCH_TIMEOUT_MS = 90_000;
+const STREAM_TIMEOUT_MS = 5 * 60_000;
 const VERSION_OVERRIDE_FILE_NAME = "electron-app-version-override.json";
 const CURSOR_SKILLS_DIRECTORY_NAME = ".cursor";
 const CURSOR_SKILLS_SUBDIRECTORY_NAME = "skills";
@@ -625,9 +628,22 @@ async function downloadElectronApp() {
         // Create directories
         mkdirSync(versionDir, { recursive: true });
-        // Download using fetch
+        // Download using fetch. Both fetch and pipeline get hard timeouts so a
+        // hung CDN/proxy can never pin this process — see issue #167.
         log("Fetching...");
-        const response = await fetch(downloadUrl);
+        const fetchController = new AbortController();
+        const fetchTimer = setTimeout(() => fetchController.abort(), FETCH_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(downloadUrl, { signal: fetchController.signal });
+        } catch (error) {
+            if (error && error.name === "AbortError") {
+                throw new Error(`Fetch timed out after ${FETCH_TIMEOUT_MS}ms — ${downloadUrl}`, { cause: error });
+            }
+            throw error;
+        } finally {
+            clearTimeout(fetchTimer);
+        }
         if (!response.ok) {
             const errorBody = await response.text().catch(() => "");
             throw new Error(
@@ -642,7 +658,18 @@ async function downloadElectronApp() {
         const tempFile = join(versionDir, binaryName);
         const fileStream = createWriteStream(tempFile);
-        await pipeline(response.body, fileStream);
+        const streamController = new AbortController();
+        const streamTimer = setTimeout(() => streamController.abort(), STREAM_TIMEOUT_MS);
+        try {
+            await pipeline(response.body, fileStream, { signal: streamController.signal });
+        } catch (error) {
+            if (error && error.name === "AbortError") {
+                throw new Error(`Download stream stalled — aborted after ${STREAM_TIMEOUT_MS}ms`, { cause: error });
+            }
+            throw error;
+        } finally {
+            clearTimeout(streamTimer);
+        }
         log("Download complete, verifying checksum...");
@@ -895,10 +922,14 @@ function syncClaudePluginCache() {
     }
 }
-// Run postinstall
+// Run postinstall. The explicit `process.exit` guarantees the script doesn't
+// linger when something below (a hung socket, an EPERM rmSync retry on
+// Windows) keeps the event loop alive — see issue #167.
 initLogFile();
 removeVersionOverrideFile();
 syncCursorSkills();
 syncClaudePluginCache();
 upsertCursorMcpConfig();
-downloadElectronApp().catch(logError);
+downloadElectronApp()
+    .catch(logError)
+    .finally(() => process.exit(0));