@aion0/forge 0.9.0 → 0.9.2

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 |