@aion0/forge 0.9.1 → 0.9.3

package/lib/help-docs/20-mantis-bug-fix.md

@@ -1,115 +0,0 @@
-# Mantis → Bug Fix → MR pipeline
-
-End-to-end: a Mantis bug surfaces (via a Forge **Job** polling mantis.get_bug
-/ mantis.search_bugs) → triggers a Pipeline → Pipeline checks out the right
-base branch in a worktree → headless Claude implements the fix → pipeline
-opens a GitLab MR via `glab` → pipeline pings the assignee + reporter on
-Teams with the MR URL.
-
-Mirrors the `gitlab-issue-fix-and-review` builtin but driven by Mantis
-content (description / priority / category / assignee / reporter), MR
-opens against an explicit `base_branch` you pass in from the Job (because
-Mantis doesn't carry milestones the way GitLab issues do).
-
-## Builtin name
-
-`mantis-bug-fix-and-mr` — registered in Forge's built-in workflow set,
-visible in the Pipelines view's workflow dropdown and pickable from the
-extension Jobs tab when you wire a Pipeline-dispatch Job.
-
-## Inputs (set by the Job's `input_template`)
-
-| Key | Required | Source |
-|---|---|---|
-| `bug_id` | yes | `{{item.id}}` |
-| `project` | yes | injected by `triggerPipeline` from the Job's project setting |
-| `base_branch` | **yes** | `{{item.product_version}}` mapped to a branch, OR a literal like `"release/25.4"` you write into the template |
-| `summary` | yes | `{{item.summary}}` |
-| `description` | yes | `{{item.description}}` |
-| `priority` | opt | `{{item.priority}}` |
-| `category` | opt | `{{item.category}}` |
-| `assignee` | opt | `{{item.assignee}}` — used as Teams chat name |
-| `reporter` | opt | `{{item.reporter}}` — used as Teams chat name |
-| `extra_context` | opt | literal hint text for Claude |
-| `mr_title_template` | opt | default `Fix Mantis #{bug_id}: {summary}` |
-| `mr_body_template` | opt | default closes-ref + Claude summary; vars `{bug_id} {summary} {description} {claude_summary}` |
-| `teams_message_template` | opt | default `🤖 Mantis #{bug_id} fixed — please review MR: {mr_url}\nBug: {summary}`; vars `{bug_id} {summary} {role} {mr_url}` |
-
-## Nodes
-
-```
-resolve              parse git remote → HOST + PROJECT_PATH; check glab; require base_branch
-worktree-setup       git worktree add -b fix/mantis-<id> .forge/worktrees/mantis-<id> origin/<base>
-fix-code             headless Claude — reads bug context, edits in worktree, commits
-push-and-mr          if any commits: push fix/mantis-<id>, glab mr create → MR_URL
-notify-teams         curl /api/connector-tool teams.send_message twice (assignee + reporter)
-```
-
-`fix-code` runs as a normal Claude task (not shell) so it can think, browse,
-edit, and commit. `notify-teams` short-circuits if `push-and-mr` couldn't
-create an MR (e.g. Claude made no changes).
-
-## Talking to connectors from a pipeline
-
-`notify-teams` calls `POST http://127.0.0.1:8403/api/connector-tool` —
-a loopback-only endpoint that wraps `lib/chat/tool-dispatcher`. Body:
-
-```json
-{ "plugin_id": "teams", "tool": "send_message",
-  "input": { "name": "Alice", "text": "MR: https://..." } }
-```
-
-Returns the standard `{ content, is_error }` tool-result shape. Works for
-`browser` / `http` / `shell` protocol connectors. Browser-protocol calls
-need the extension bridge connected at pipeline runtime (Chrome open +
-extension signed in).
-
-## Wiring it up from a Job
-
-1. Confirm `glab` is installed + authed for the target host:
-   `glab auth login --hostname <your-gitlab.example.com>`
-2. Make sure the project has a git remote (`git remote get-url origin`) the
-   `glab mr create` call can reach.
-3. Forge extension → Jobs → + New job. Pick:
-   - Connector / tool: `mantis` / `get_bug` (single bug) or `search_bugs` (a query)
-   - dispatch: Pipeline → workflow `mantis-bug-fix-and-mr` → your project
-   - `input_template` (auto-prefilled when you pick the workflow; map item
-     keys to inputs, hardcode `base_branch` if Mantis doesn't carry it):
-     ```json
-     {
-       "bug_id":      "{{item.id}}",
-       "summary":     "{{item.summary}}",
-       "description": "{{item.description}}",
-       "priority":    "{{item.priority}}",
-       "category":    "{{item.category}}",
-       "assignee":    "{{item.assignee}}",
-       "reporter":    "{{item.reporter}}",
-       "base_branch": "release/25.4"
-     }
-     ```
-4. Save → Run now (first tick is a backfill-no-op; click Reset dedup +
-   Run now to force one actual dispatch for testing).
-
-## Customising
-
-- Branch derivation rules (e.g. `target_version` → `release/<major.minor>`):
-  edit the `resolve` node in your local copy at
-  `~/.forge/data/flows/mantis-bug-fix-and-mr.yaml` (a copy will be created
-  when you click Edit in the Pipelines view; once a local file exists it
-  overrides the builtin).
-- MR title / body templates: set via the Job's `input_template` — no
-  pipeline edit needed.
-- Teams routing: today it uses the Mantis username verbatim as the Teams
-  chat name (substring match). For better mapping, post-process in
-  `notify-teams` to convert username → real name via a lookup table or
-  a second connector call.
-
-## Troubleshooting
-
-| Symptom | Cause + fix |
-|---|---|
-| `ERROR: base_branch is required` | The Job's `input_template` didn't supply it — Mantis bugs don't always carry one. Hardcode it in the template or map from `product_version`. |
-| `NO_CHANGES — Claude did not commit` | Bug description was too thin or Claude couldn't find the affected code. Add hints via `extra_context` or open the worktree manually and iterate. |
-| `glab mr create` returns nothing | Token expired / target branch protected / source branch already has an open MR. The pipeline falls back to `glab mr view` to surface the existing URL — check Pipelines log. |
-| Teams send returns `No extension connected to the bridge` | The pipeline ran when Chrome / extension weren't online. Notification fails but the MR still landed; re-fire the `notify-teams` node manually or message the people yourself. |
-| Mantis username doesn't match any Teams chat | The fuzzy substring match in `teams.send_message` falls back to whatever the LLM-less DOM script can match. Add a lookup step before `notify-teams` to translate names. |

package/lib/help-docs/22-recipes.md

@@ -1,124 +0,0 @@
-# Recipes & GitLab MR auto-fix
-
-A **Recipe** is a parameterized template for a Job + its dispatched pipeline. Instead of hand-filling 12 fields in the Jobs form, you pick a recipe, fill 3-4 high-level params, and Forge instantiates the rest.
-
-Recipes live under `~/.forge/data/recipes/*.yaml`. The canonical catalog is `aiwatching/forge-workflow` on GitHub; Marketplace ↓ Sync pulls the latest registry.
-
-## Built-in recipes
-
-| Name | What it does | Source tool |
-|---|---|---|
-| `gitlab-mr-watch` | Watch ONE specific MR for new review comments → run `mr-review-fix` | `gitlab.get_mr` |
-| `gitlab-my-mrs-watch` | Watch all MRs assigned to you → run `mr-review-fix` per MR | `gitlab.list_my_mrs` |
-| `mantis-bug-fix` | Manual fire — fix a single Mantis bug → run `mantis-bug-fix-and-mr` | `mantis.get_bug` |
-| `mantis-bug-watch` | Periodic — fix bugs matching a filter | `mantis.search_bugs` |
-
-## Creating a Job from a recipe
-
-Extension → Jobs tab → **+ From recipe…** → pick one → fill the form → Create.
-
-For `gitlab-mr-watch` you fill:
-- **Local project name** (picks a directory under `projectRoots`)
-- **MR URL** — paste the full URL like `https://gitlab.example.com/namespace/repo/-/merge_requests/123`. Forge auto-extracts namespace/repo + iid.
-- **Poll interval** (minutes, default 5)
-- **Triage policy** (free-form, optional — ships with a sensible default)
-
-## Special param types
-
-- `project_picker` — dropdown of dirs under your configured `projectRoots`
-- `gitlab_mr_url` — single MR URL; Forge parses out `<name>__path` (`namespace/repo`) + `<name>__iid` (numeric iid) at instantiation time. Reference them in templates via `{{params.mr_url__path}}` / `{{params.mr_url__iid}}`.
-- `number` — coerces string → number
-- `boolean` — coerces truthy strings
-
-## The `mr-review-fix` pipeline — 5 nodes
-
-1. **ingest** (shell, no worktree) — `glab api` pulls MR meta + ALL notes + diff into `/tmp/mr-<iid>-*.{json,txt}`. Emits `SOURCE_BRANCH`, `MR_TITLE`, `MR_AUTHOR`, `LATEST_COMMENTER`, file paths.
-2. **triage** (AI, no worktree, no shell) — reads all notes holistically, decides action.
-3. **fix** (AI, branch `mr-<iid>` worktree) — runs the git work only on ACT path.
-4. **reply** (shell) — posts a comment on the MR describing the outcome; adds a label; closes the MR if needed.
-5. **cleanup** (shell) — Teams notify + worktree removal + tmp file cleanup.
-
-### Four triage actions
-
-| ACTION | Meaning | Reply posted? | Label | MR state |
-|---|---|---|---|---|
-| `act`   | Comments name a concrete fix → apply it | yes (with diff summary) | `forge:fix-applied` | push fixup to source_branch |
-| `skip`  | Substantive but no change needed (lgtm, nits, questions) | yes (explanation) | `forge:no-fix-needed` | unchanged |
-| `close` | MR itself shouldn't merge (duplicate, wrong direction, already-fixed-elsewhere) | yes (rationale) | `forge:no-merge` | **closed** via `glab api PUT state_event=close` |
-| `noop`  | Latest non-system comment is Forge's own or this Job's user → nothing changed since last run | **no** (silent) | none | unchanged |
-
-The `noop` case is the loop-breaker. Without it, Forge's auto-reply bumps `user_notes_count`, the next tick sees a new state, fires again, posts another reply — endless self-conversation.
-
-### Required GitLab labels (one-time)
-
-Create these in **GitLab → Project → Labels → New label** (any colors):
-
-```
-forge:fix-applied      (suggest green)
-forge:no-fix-needed    (suggest blue)
-forge:no-merge         (suggest red)
-```
-
-If a label is missing, the label-add step logs a failure but the rest of the pipeline still runs.
-
-### Triage prompt — when to customize
-
-The recipe ships with a default `triage_instructions` covering common cases. Overwrite when you need project-specific rules. Examples:
-
-```
-Only act if the reviewer is from team @backend. Skip everything else.
-```
-
-```
-Act ONLY on Code Review Bot 'error' findings; skip all human comments.
-```
-
-```
-Treat any comment containing "MUST" as actionable; everything else SKIP.
-```
-
-Keep the noop clause at the bottom of any custom policy:
-
-```
-NOOP when the latest non-system comment is authored by @<your-username>
-or starts with '🤖 Forge:'.
-```
-
-## Per-MR vs per-comment dispatch
-
-Older recipe versions used `gitlab.list_mr_notes` and fired ONE pipeline per new comment — 50 historical comments on first Fire meant 50 pipelines. Current recipes use `gitlab.get_mr` + dedup on `user_notes_count`:
-
-- Fetches the MR object once; scheduler wraps as 1-item list
-- `user_notes_count` only changes when comments are added/removed → label flips, status changes, assignee changes don't false-trigger
-- First Fire registers the current count as "seen" via `__mark_existing_as_seen: true` — no backfill stampede
-
-## Marketplace ↔ local copy split
-
-- **Marketplace** (Settings → Marketplace → Templates → Recipes / Pipelines) lists ONLY items from the registry (`forge-workflow` repo). Editing-by-hand or "Import as new copy" workflows don't appear here.
-- **Pipelines tab** lists ALL local workflow yamls — registry-sourced installs, your custom edits, anything in `~/.forge/data/flows/`.
-- **Reinstall** button overwrites a local copy with the current registry version (use after a version bump).
-- Local copies are **independent** of marketplace — Forge will never silently overwrite a local file you've edited.
-
-## Cleanup recipes
-
-```bash
-# Delete a Job + its dedup state + any pending pipeline runs
-sqlite3 ~/.forge/data/workflow.db <<'SQL'
-DELETE FROM jobs WHERE name='mr-watch-FortiNAC-14636';
-DELETE FROM job_dedup_keys WHERE job_id NOT IN (SELECT id FROM jobs);
-DELETE FROM pipelines WHERE workflow_name='mr-review-fix' AND status IN ('pending','running');
-SQL
-
-# Force re-trigger on next tick — clears dedup so any state looks "new"
-sqlite3 ~/.forge/data/workflow.db "DELETE FROM job_dedup_keys WHERE job_id IN (SELECT id FROM jobs WHERE source_tool='get_mr');"
-```
-
-## Where things live on disk
-
-| Path | Purpose |
-|---|---|
-| `~/.forge/data/recipes/*.yaml` | Local recipe copies |
-| `~/.forge/data/flows/*.yaml` | Local workflow copies (mr-review-fix, mantis-bug-fix-and-mr, custom) |
-| `~/.forge/data/workflow.db` | Job rows, dedup keys, run history |
-| `~/.forge/data/pipelines/*.json` | Per-run state for each pipeline execution |
-| `~/.forge/data/workflow-cache.json` | Last-synced registry from `forge-workflow` repo |