@intentius/chant-lexicon-forgejo 0.60.0 → 0.62.0

package/dist/components/generate-op-pipeline.d.ts

@@ -28,12 +28,20 @@
  * no mapping in ../actions.ts passes through verbatim and resolves only if
  * the runner can fetch it.
  *
- * One finding-mode does not cross over: `comment` (#2231) posts onto the
- * triggering pull request by shelling to `gh` against the GitHub API and
- * reading the GitHub Actions event payload. Forgejo's API is
- * GitHub-compatible in shape, but chant has no Forgejo client and no host
- * configuration to point `gh` at a Forgejo instance, so this refuses the mode
- * by name rather than generating a job whose finding step fails on every run.
+ * `comment` (#2231) crosses over too, since chant #2291: it posts onto the
+ * triggering pull request by shelling to `gh` against `${GITHUB_API_URL}`,
+ * and a Forgejo Actions job already sets that (and `github.token`) the same
+ * way a GitHub Actions job does. This generator used to refuse the mode by
+ * name here, on the premise that chant had no way to point `gh` at a Forgejo
+ * instance; that premise was checked against a real Forgejo
+ * 12.0.4+gitea-1.22.0 instance during INTENTIUS/choudoufu#1027 and found
+ * false — the failure was `gh api` resolving a *relative* path against
+ * `/api/v3`, which Forgejo does not serve, not an unreachable forge. See
+ * `reconcilePr`'s `postOrUpdateComment` (`packages/core/src/op/activities/reconcile.ts`)
+ * for the fix. `issue` mode (`gh issue create`) was not part of that
+ * verification — only the comment endpoints were exercised on the real
+ * instance — so it remains un-refused-but-unverified here, exactly as it was
+ * on GitHub before this change.
  *
  * A spec's `environment` (#2257) is dropped on the same terms as
  * `permissions:`, and for a stronger reason: Forgejo Actions has no
@@ -56,6 +64,24 @@
  * Forgejo apply that stops at its gate is a green run rather than a red one,
  * and `chant run` still writes the gate and the approve command to
  * `GITHUB_STEP_SUMMARY`, which Forgejo Actions sets like GitHub does.
+ *
+ * The gate-notice job's own reason for being — `outputs: { gated, op, gate,
+ * approve }` on the Op's job, and the `node -e` step that writes them to
+ * `$GITHUB_OUTPUT` — does not survive it either (#2294). Both existed only for
+ * that job to read via `needs.<job>.outputs`; with the job gone, so is every
+ * reader, and `buildGithubOpPipelineDocs` is asked for neither
+ * (`emitGatedOutputs: false` below) rather than emitting them here and
+ * stripping them back out. Should the Forgejo posting work in #2291 grow a
+ * notice job of its own, this is the one flag that brings both back.
+ *
+ * A spec's own `variables` (#2290) crosses over unchanged: forgejo reuses the
+ * same job-level `env:` github's builder emits, and the dialect transform
+ * touches only `permissions:`/`environment:`/action refs, never a job's `env:`
+ * mapping. That is what makes a per-Op credential expressible here at all —
+ * `ComponentPipelineOptions.variables` is workflow-scoped and, on Forgejo,
+ * Actions mints no OIDC token to put in `setup` instead, so a job-level
+ * `variables` entry is the only way one Op's job can hold a credential no
+ * sibling Op's job receives.
  */
 import type { ComponentPipelineOptions, OpPipelineResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
 import { type ForgejoDialectOptions } from "../dialect.js";

package/dist/components/generate-op-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAOH,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAmCjF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,wBAA6B,EACtC,cAAc,GAAE,qBAA0B,GACzC,gBAAgB,CA+BlB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAOH,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAmCjF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,wBAA6B,EACtC,cAAc,GAAE,qBAA0B,GACzC,gBAAgB,CA2BlB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "56a899fd87d95111c56cb551f5a4961c91af788fb0a11c3ef4f9fb207f5abd3f",
+    "manifest.json": "3f69907e1588ef81d9bbf78e57ba60a06e4657ad54692aad9cc172ac21246ce6",
     "meta.json": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
     "types/index.d.ts": "66204549b2a864ab5489e3f02c1878e73ab4b3c9d938cfb480b66f71543a43de",
     "rules/delegate-to-github.ts": "1060cda40f4b73d6cca3ba3fa13b80b4886147d4034c88584c2d80c5510dbe5e",
@@ -9,5 +9,5 @@
     "rules/wfj011.ts": "fcb8bf6685d744af20ad804ce929488257995c74b9a3353b2eacae3768d1c83e",
     "skills/chant-forgejo.md": "a1a560429db736c187e0b34cf8dd9efc6ad771afefcbf6f802d160d3d5274257"
   },
-  "composite": "390ec307dcfc42c1e376d49ee30e4f78429b316ded7bce20355efded9327d04e"
+  "composite": "c1b979e353a7bd9fbc449e1f98b765979d89d4e386ed94d8fce9ec20754ee514"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "forgejo",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Forgejo",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-forgejo",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Forgejo / Codeberg / Gitea Actions lexicon for chant — a thin GitHub Actions dialect",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -54,8 +54,8 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.60.0",
-    "@intentius/chant-lexicon-github": "^0.60.0"
+    "@intentius/chant": "^0.62.0",
+    "@intentius/chant-lexicon-github": "^0.62.0"
   },
   "scripts": {
     "generate": "tsx src/codegen/generate-cli.ts",

package/src/components/generate-op-pipeline.test.ts

@@ -14,9 +14,11 @@ import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
 
 interface ParsedJob {
   "runs-on"?: string;
+  container?: string;
   environment?: Record<string, string>;
   outputs?: Record<string, string>;
-  steps: Array<{ id?: string; uses?: string; run?: string }>;
+  env?: Record<string, string>;
+  steps: Array<{ id?: string; uses?: string; run?: string; shell?: string }>;
 }
 interface ParsedDoc {
   on?: Record<string, unknown>;
@@ -105,27 +107,45 @@ describe("generateForgejoOpPipeline: non-cron trigger survives the dialect trans
   });
 });
 
-describe("generateForgejoOpPipeline: no comment finding mode (#2231)", () => {
-  test("findingMode comment is refused by name, on the pull_request trigger it would otherwise fit", () => {
-    // Forgejo Actions runs the same workflow shape and Forgejo's API is
-    // GitHub-compatible, but the activity behind the mode shells to `gh`
-    // against github.com and reads the GitHub Actions event payload. Nothing
-    // in chant points either at a Forgejo instance, so the mode is refused
-    // here rather than generating a job that fails at its Report step.
+describe("generateForgejoOpPipeline: comment finding mode crosses over (#2291)", () => {
+  // Used to be refused by name here (#2231), on the premise that chant had no
+  // way to point `gh` at a Forgejo instance. Checked against a real Forgejo
+  // 12.0.4+gitea-1.22.0 instance during INTENTIUS/choudoufu#1027 and found
+  // false: Forgejo's own `/api/v1` takes the same GET/POST/PATCH calls
+  // `reconcilePr`'s `postOrUpdateComment` makes, once it targets the right
+  // URL. See `packages/core/src/op/activities/reconcile.test.ts` for the
+  // mocked-transport proof of that fix; this file only proves the generator
+  // no longer refuses the mode and produces the same job shape github does.
+  test("findingMode comment generates cleanly on the pull_request trigger it needs", () => {
     const specs: ScheduledOpSpec[] = [
       { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
     ];
-    expect(() => generateForgejoOpPipeline(specs)).toThrow(
-      /Scheduled Op "app-plan".*findingMode "comment".*no Forgejo API client/s,
-    );
+    expect(() => generateForgejoOpPipeline(specs)).not.toThrow();
   });
 
-  test("github generates the same spec, so the refusal is forgejo's and not the shared builder's", () => {
+  test("job/trigger/findingMode parity with the github generator (same input, same job list)", () => {
     const specs: ScheduledOpSpec[] = [
       { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
     ];
-    const gh = parseFile(generateGithubOpPipeline(specs).files[0].yaml);
-    expect(gh.permissions).toEqual({ contents: "read", "pull-requests": "write" });
+    const fj = generateForgejoOpPipeline(specs);
+    const gh = generateGithubOpPipeline(specs);
+    expect(fj.jobs).toEqual(gh.jobs);
+  });
+
+  test("the run step carries GH_TOKEN/GITHUB_TOKEN, same as github's — permissions: still dropped by the dialect", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
+    ];
+    const fjYaml = generateForgejoOpPipeline(specs).files[0].yaml;
+    const ghDoc = parseFile(generateGithubOpPipeline(specs).files[0].yaml);
+
+    expect(fjYaml).toContain("GH_TOKEN: '${{ github.token }}'");
+    expect(fjYaml).toContain("GITHUB_TOKEN: '${{ github.token }}'");
+    expect(fjYaml).not.toMatch(/^permissions:/m);
+    // github still declares the scope the mode needs — proving the omission
+    // above is the Forgejo dialect dropping `permissions:` wholesale, not a
+    // sign the mode generated with no token.
+    expect(ghDoc.permissions).toEqual({ contents: "read", "pull-requests": "write" });
   });
 });
 
@@ -198,6 +218,24 @@ describe("generateForgejoOpPipeline: the gated apply on push (#2243)", () => {
     expect(Object.keys(fj.jobs ?? {})).toEqual(["app-apply"]);
     expect(gh.jobs).toHaveProperty("app-apply-gate-notice");
   });
+
+  /**
+   * chant #2299 — Forgejo Actions runs the same act_runner semantics as
+   * GitHub Actions: a job with `container:` (which this generator's Op job
+   * always carries, unconditionally) defaults to `sh`, and `sh` rejects `set
+   * -o pipefail`. This generator reuses github's `buildGithubOpPipelineDocs`
+   * to build the job, then the dialect transform in ../dialect.ts to cross
+   * it, so the fix has to survive both: neither step drops or renames
+   * `shell:`.
+   */
+  test("the pipefail step keeps shell: bash across the Forgejo dialect — its job runs in a container, whose default shell is sh", () => {
+    const doc = parseFile(generateForgejoOpPipeline([pushSpec]).files[0].yaml);
+    const job = doc.jobs!["app-apply"];
+    expect(job.container).toBe("node:22-slim");
+    const step = job.steps.find((s) => s.id === "chant-run");
+    expect(step?.run).toContain("set -o pipefail");
+    expect(step?.shell).toBe("bash");
+  });
 });
 
 /**
@@ -277,3 +315,129 @@ describe("generateForgejoOpPipeline: a dropped deployment environment (#2257)",
     ).toThrow(/neither an absolute http\(s\) URL nor a/);
   });
 });
+
+/**
+ * chant #2290 — per-Op credentials, so a pull-request job need not hold the
+ * apply credential. The consuming project's own shape: `live-check` (no
+ * `variables`) carries no credential while `live-apply` (`variables` set)
+ * carries one, both generated from forge-wide `options.variables` that name
+ * no credential at all.
+ */
+describe("generateForgejoOpPipeline: per-Op variables land on the job, not the workflow (#2290)", () => {
+  const FORGE_WIDE = { CHANT_FORGE: "forgejo", AWS_REGION: "${{ vars.AWS_REGION }}" };
+  const CREDENTIAL = { AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}" };
+
+  test("a job whose spec declares no variables carries none, even when the forge-wide options do", () => {
+    const doc = parseFile(
+      generateForgejoOpPipeline([{ name: "live-check", trigger: { kind: "pull_request", branches: ["main"] } }], {
+        variables: FORGE_WIDE,
+      }).files[0].yaml,
+    );
+    expect(doc.jobs!["live-check"].env).toBeUndefined();
+  });
+
+  test("a job whose spec declares variables carries them as the job's own env:, beside the workflow env:", () => {
+    const doc = parseFile(
+      generateForgejoOpPipeline(
+        [{ name: "live-apply", trigger: { kind: "push", branches: ["main"] }, variables: CREDENTIAL }],
+        { variables: FORGE_WIDE },
+      ).files[0].yaml,
+    );
+    expect(doc.jobs!["live-apply"].env).toEqual(CREDENTIAL);
+  });
+
+  /**
+   * The proof the issue names: a generated workflow whose `live-check` job
+   * carries no credential while its `live-apply` job does, from one forge-wide
+   * options object that itself names no credential — the property the
+   * consuming project (`examples/ci-pipelines`) needs to be able to state.
+   */
+  test("live-check carries no credential while live-apply does, from the same forge-wide options", () => {
+    const files = generateForgejoOpPipeline(
+      [
+        { name: "live-check", trigger: { kind: "pull_request", branches: ["main"] } },
+        { name: "live-apply", trigger: { kind: "push", branches: ["main"] }, variables: CREDENTIAL },
+      ],
+      { variables: FORGE_WIDE },
+    ).files;
+    const check = parseFile(files.find((f) => f.name === "live-check.yml")!.yaml);
+    const apply = parseFile(files.find((f) => f.name === "live-apply.yml")!.yaml);
+
+    expect(JSON.stringify(check.jobs!["live-check"])).not.toContain("AWS_ACCESS_KEY_ID");
+    expect(apply.jobs!["live-apply"].env).toEqual(CREDENTIAL);
+  });
+
+  test("a per-Op key wins over a same-named forge-wide one — the job is more specific", () => {
+    const doc = parseFile(
+      generateForgejoOpPipeline(
+        [
+          {
+            name: "live-apply",
+            trigger: { kind: "push", branches: ["main"] },
+            variables: { CHANT_FORGE: "overridden" },
+          },
+        ],
+        { variables: FORGE_WIDE },
+      ).files[0].yaml,
+    );
+    expect(doc.jobs!["live-apply"].env).toEqual({ CHANT_FORGE: "overridden" });
+  });
+
+  test("a spec declaring variables changes exactly the job's env: block and nothing else", () => {
+    const spec: ScheduledOpSpec = { name: "live-apply", trigger: { kind: "push", branches: ["main"] } };
+    const before = generateForgejoOpPipeline([spec]).files[0].yaml;
+    const after = generateForgejoOpPipeline([{ ...spec, variables: CREDENTIAL }]).files[0].yaml;
+    expect(after).toContain("    env:\n      AWS_ACCESS_KEY_ID: '${{ secrets.AWS_ACCESS_KEY_ID }}'\n");
+    expect(
+      after.replace("    env:\n      AWS_ACCESS_KEY_ID: '${{ secrets.AWS_ACCESS_KEY_ID }}'\n", ""),
+    ).toBe(before);
+  });
+});
+
+/**
+ * chant #2294 — the gated-apply outputs survive the notice job that consumed
+ * them. Asserted directly against forgejo's own output: no `outputs:` on the
+ * push job, no `node -e` line writing to `$GITHUB_OUTPUT`, while github's
+ * generator (same spec) still carries both because its notice job still reads
+ * them.
+ */
+describe("generateForgejoOpPipeline: no unconsumed outputs (#2294)", () => {
+  const pushSpec: ScheduledOpSpec = { name: "live-apply", trigger: { kind: "push", branches: ["main"] } };
+
+  test("the push job carries no outputs: block", () => {
+    const doc = parseFile(generateForgejoOpPipeline([pushSpec]).files[0].yaml);
+    expect(doc.jobs!["live-apply"].outputs).toBeUndefined();
+  });
+
+  test("the run step carries no node -e line writing to $GITHUB_OUTPUT", () => {
+    const doc = parseFile(generateForgejoOpPipeline([pushSpec]).files[0].yaml);
+    const step = doc.jobs!["live-apply"].steps.find((s) => s.id === "chant-run");
+    expect(step?.run).not.toContain("node -e");
+    expect(step?.run).not.toContain("GITHUB_OUTPUT");
+    // The tee'd invocation survives — it's what puts the run's own record in
+    // the log, gate-notice job or not.
+    expect(step?.run).toContain("| tee");
+    expect(step?.run).toContain("chant run live-apply --gated-exit 0 --json");
+  });
+
+  test("github, generated from the same spec, still carries both — the drop is forgejo's dialect, not the shared builder", () => {
+    const gh = parseFile(generateGithubOpPipeline([pushSpec]).files[0].yaml);
+    const ghStep = gh.jobs!["live-apply"].steps.find((s) => s.id === "chant-run");
+    expect(gh.jobs!["live-apply"].outputs).toEqual({
+      gated: "${{ steps.chant-run.outputs.gated }}",
+      op: "${{ steps.chant-run.outputs.op }}",
+      gate: "${{ steps.chant-run.outputs.gate }}",
+      approve: "${{ steps.chant-run.outputs.approve }}",
+    });
+    expect(ghStep?.run).toContain("node -e");
+  });
+
+  test("a non-push (cron) job carries no outputs and no gate script either way", () => {
+    const doc = parseFile(
+      generateForgejoOpPipeline([{ name: "live-discover", schedule: "0 6 * * *" }]).files[0].yaml,
+    );
+    expect(doc.jobs!["live-discover"].outputs).toBeUndefined();
+    const step = doc.jobs!["live-discover"].steps.find((s) => typeof s.run === "string");
+    expect(step?.run).not.toContain("node -e");
+  });
+});

package/src/components/generate-op-pipeline.ts

@@ -28,12 +28,20 @@
  * no mapping in ../actions.ts passes through verbatim and resolves only if
  * the runner can fetch it.
  *
- * One finding-mode does not cross over: `comment` (#2231) posts onto the
- * triggering pull request by shelling to `gh` against the GitHub API and
- * reading the GitHub Actions event payload. Forgejo's API is
- * GitHub-compatible in shape, but chant has no Forgejo client and no host
- * configuration to point `gh` at a Forgejo instance, so this refuses the mode
- * by name rather than generating a job whose finding step fails on every run.
+ * `comment` (#2231) crosses over too, since chant #2291: it posts onto the
+ * triggering pull request by shelling to `gh` against `${GITHUB_API_URL}`,
+ * and a Forgejo Actions job already sets that (and `github.token`) the same
+ * way a GitHub Actions job does. This generator used to refuse the mode by
+ * name here, on the premise that chant had no way to point `gh` at a Forgejo
+ * instance; that premise was checked against a real Forgejo
+ * 12.0.4+gitea-1.22.0 instance during INTENTIUS/choudoufu#1027 and found
+ * false — the failure was `gh api` resolving a *relative* path against
+ * `/api/v3`, which Forgejo does not serve, not an unreachable forge. See
+ * `reconcilePr`'s `postOrUpdateComment` (`packages/core/src/op/activities/reconcile.ts`)
+ * for the fix. `issue` mode (`gh issue create`) was not part of that
+ * verification — only the comment endpoints were exercised on the real
+ * instance — so it remains un-refused-but-unverified here, exactly as it was
+ * on GitHub before this change.
  *
  * A spec's `environment` (#2257) is dropped on the same terms as
  * `permissions:`, and for a stronger reason: Forgejo Actions has no
@@ -56,6 +64,24 @@
  * Forgejo apply that stops at its gate is a green run rather than a red one,
  * and `chant run` still writes the gate and the approve command to
  * `GITHUB_STEP_SUMMARY`, which Forgejo Actions sets like GitHub does.
+ *
+ * The gate-notice job's own reason for being — `outputs: { gated, op, gate,
+ * approve }` on the Op's job, and the `node -e` step that writes them to
+ * `$GITHUB_OUTPUT` — does not survive it either (#2294). Both existed only for
+ * that job to read via `needs.<job>.outputs`; with the job gone, so is every
+ * reader, and `buildGithubOpPipelineDocs` is asked for neither
+ * (`emitGatedOutputs: false` below) rather than emitting them here and
+ * stripping them back out. Should the Forgejo posting work in #2291 grow a
+ * notice job of its own, this is the one flag that brings both back.
+ *
+ * A spec's own `variables` (#2290) crosses over unchanged: forgejo reuses the
+ * same job-level `env:` github's builder emits, and the dialect transform
+ * touches only `permissions:`/`environment:`/action refs, never a job's `env:`
+ * mapping. That is what makes a per-Op credential expressible here at all —
+ * `ComponentPipelineOptions.variables` is workflow-scoped and, on Forgejo,
+ * Actions mints no OIDC token to put in `setup` instead, so a job-level
+ * `variables` entry is the only way one Op's job can hold a credential no
+ * sibling Op's job receives.
  */
 
 import {
@@ -117,18 +143,14 @@ export function generateForgejoOpPipeline(
   options: ComponentPipelineOptions = {},
   dialectOptions: ForgejoDialectOptions = {},
 ): OpPipelineResult {
-  for (const spec of ops) {
-    if (spec.findingMode === "comment") {
-      throw new Error(
-        `Scheduled Op "${spec.name}" has findingMode "comment", which posts its finding on the pull request ` +
-          `that triggered the run. That activity shells to \`gh\` against the GitHub API and reads the ` +
-          `GitHub Actions event payload; chant carries no Forgejo API client to post the equivalent comment ` +
-          `(#2231). Use findingMode "issue" here, or generate this Op for github.`,
-      );
-    }
-  }
+  // `findingMode: "comment"` used to be refused by name here (#2231); lifted
+  // in #2291 once a real Forgejo instance showed the forge itself was never
+  // the obstacle — see the module doc above.
 
-  const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
+  // `emitGatedOutputs: false` (#2294): forgejo never carries a gate-notice job
+  // (`gatedNoticeDoc` never crosses the dialect, below), so the job outputs
+  // and the `node -e` step that populate them would have no reader.
+  const { files, jobs } = buildGithubOpPipelineDocs(ops, options, { emitGatedOutputs: false });
 
   return {
     // One file per spec, in spec order, which is what lets the header below

package/src/serializer.test.ts

@@ -128,10 +128,27 @@ describe("forgejoSerializer — multi-workflow output", () => {
 // "@intentius/chant-lexicon-github"`); nothing forgejo-specific is written for
 // it. This is the functional check that inheritance actually holds, not just
 // that the type is importable: the dialect still drops the job's
-// `permissions` and remaps its runner label, while the sticky-comment step —
-// a plain `gh api` script with no `uses:` at all — passes through untouched,
-// since Forgejo's API accepts the same calls against its GitHub-compatible
-// surface.
+// `permissions` and remaps its runner label, and the sticky-comment step — a
+// plain `gh api` script with no `uses:` at all — passes through the dialect
+// transform untouched, because the dialect only ever rewrites job-level
+// `permissions:`/`environment:`/action refs and never looks at step content.
+//
+// That passing-through is a fact about serialization, not about whether the
+// script would work if run: chant #2291 settled, against a real Forgejo
+// 12.0.4+gitea-1.22.0 instance, that Forgejo's `/api/v1` does accept the same
+// GET/POST/PATCH calls this script makes — but only when they target a full
+// URL. Until chant #2305, this script's `gh api "repos/$REPO/issues/…"` took
+// a bare relative path, which `gh` resolves against `/api/v3` on any host but
+// github.com, and Forgejo does not serve `/api/v3`. `reconcilePr`'s
+// `postOrUpdateComment` got the URL fix #2291 made
+// (`packages/core/src/op/activities/reconcile.ts`), and `PrPlanReport`'s own
+// script (`lexicons/github/src/composites/pr-plan-report.ts`) — out of
+// #2291's scope, being the component composite rather than the Op generator —
+// got the equivalent fix in #2305: every call now targets `$api_base`, built
+// from `$GITHUB_API_URL` inline in the shell script. The dialect still leaves
+// step content untouched, so that base-URL construction crosses over exactly
+// as written, which is what makes the untouched script below a working
+// Forgejo comment rather than just a passed-through one.
 describe("forgejoSerializer — inherits PrPlanReport from github (#1983)", () => {
   test("dialect still applies to a github-lexicon composite's job", () => {
     const workflow = new Workflow({
@@ -154,6 +171,10 @@ describe("forgejoSerializer — inherits PrPlanReport from github (#1983)", () =
     // Including the `-F` that reads the body from plan.md — forgejo renders
     // the same script, so the #2236 regression would show up here as well.
     expect(result.primary).toContain("-F body=@plan.md");
+    // And the #2305 fix: the resolved-base construction and every `gh api`
+    // call built from it cross the dialect untouched too.
+    expect(result.primary).toContain('api_base="${GITHUB_API_URL%/}"');
+    expect(result.primary).not.toMatch(/gh api[^\n]*"repos\//);
     expect(result.primary).not.toContain("-f body=@");
   });
 });