@intentius/chant-lexicon-forgejo 0.124.31 → 0.124.33

package/dist/actions.js

@@ -0,0 +1,96 @@
+/**
+ * Forgejo `uses:` action-reference resolver.
+ *
+ * GitHub Actions resolves a bare `uses: actions/checkout@v4` against the GitHub
+ * Marketplace. Forgejo / Codeberg / Gitea runners have no Marketplace, so such a
+ * ref must be rewritten to a form their runner can fetch — a full repository URL,
+ * or a path under a configured actions root that mirrors the action.
+ *
+ * The resolver rewrites a built-in set of common actions and reports anything it
+ * can't place as a diagnostic (never dropping or silently passing it through).
+ */
+/**
+ * Default actions root. `code.forgejo.org` hosts the Forgejo `actions/*` mirror
+ * (checkout, setup-*, cache, upload/download-artifact, …). Override per project
+ * via `forgejo.actionsRoot` in `chant.config.ts`.
+ */
+export const DEFAULT_ACTIONS_ROOT = "https://code.forgejo.org";
+/**
+ * `upload-artifact` and `download-artifact` v4 and later use `@actions/artifact`
+ * v2, which refuses to run on GitHub Enterprise Server, and a Forgejo runner
+ * presents itself to an action as one: the step fails with "@actions/artifact
+ * v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently
+ * supported on GHES" (#4008). v3 talks to the artifact service Forgejo serves.
+ */
+export const FORGEJO_ARTIFACT_VERSION = "v3";
+/** Built-in mapping of GitHub action `owner/repo` → Forgejo-resolvable target. */
+export const KNOWN_ACTIONS = {
+    // actions/* — mirrored on the Forgejo actions root.
+    "actions/checkout": { kind: "mirror", repo: "actions/checkout" },
+    "actions/setup-node": { kind: "mirror", repo: "actions/setup-node" },
+    "actions/setup-go": { kind: "mirror", repo: "actions/setup-go" },
+    "actions/setup-python": { kind: "mirror", repo: "actions/setup-python" },
+    "actions/setup-java": { kind: "mirror", repo: "actions/setup-java" },
+    "actions/setup-dotnet": { kind: "mirror", repo: "actions/setup-dotnet" },
+    "actions/cache": { kind: "mirror", repo: "actions/cache" },
+    "actions/upload-artifact": { kind: "mirror", repo: "actions/upload-artifact", newest: FORGEJO_ARTIFACT_VERSION },
+    "actions/download-artifact": { kind: "mirror", repo: "actions/download-artifact", newest: FORGEJO_ARTIFACT_VERSION },
+    // docker/* — not on the Forgejo mirror; pin to the full GitHub URL, which
+    // Forgejo runners can fetch directly.
+    "docker/build-push-action": { kind: "url", url: "https://github.com/docker/build-push-action" },
+    "docker/login-action": { kind: "url", url: "https://github.com/docker/login-action" },
+    "docker/setup-buildx-action": { kind: "url", url: "https://github.com/docker/setup-buildx-action" },
+    "docker/setup-qemu-action": { kind: "url", url: "https://github.com/docker/setup-qemu-action" },
+    "docker/metadata-action": { kind: "url", url: "https://github.com/docker/metadata-action" },
+};
+/** A ref that already resolves on Forgejo as-is needs no rewrite and no warning. */
+function isAlreadyResolvable(ref) {
+    return (ref.startsWith("./") ||
+        ref.startsWith("../") ||
+        ref.startsWith(".\\") ||
+        ref.startsWith("docker://") ||
+        /^https?:\/\//.test(ref));
+}
+/**
+ * Resolve a single `uses:` action ref to a Forgejo-resolvable form.
+ */
+export function resolveActionRef(ref, options = {}) {
+    const trimmed = ref.trim();
+    if (trimmed === "" || isAlreadyResolvable(trimmed))
+        return { rewritten: ref };
+    const root = (options.actionsRoot ?? DEFAULT_ACTIONS_ROOT).replace(/\/+$/, "");
+    const known = options.known ?? KNOWN_ACTIONS;
+    const atIndex = trimmed.lastIndexOf("@");
+    const path = atIndex >= 0 ? trimmed.slice(0, atIndex) : trimmed;
+    const version = atIndex >= 0 ? trimmed.slice(atIndex + 1) : "";
+    const segments = path.split("/");
+    if (segments.length < 2) {
+        return { rewritten: ref, warning: unresolvedWarning(trimmed) };
+    }
+    const actionName = `${segments[0]}/${segments[1]}`;
+    const subpath = segments.slice(2).join("/");
+    const target = known[actionName];
+    if (!target) {
+        return { rewritten: ref, warning: unresolvedWarning(trimmed) };
+    }
+    const base = target.kind === "mirror" ? `${root}/${target.repo}` : target.url;
+    const withSubpath = subpath ? `${base}/${subpath}` : base;
+    const pinned = target.kind === "mirror" && target.newest && laterMajor(version, target.newest) ? target.newest : version;
+    const rewritten = pinned ? `${withSubpath}@${pinned}` : withSubpath;
+    return { rewritten };
+}
+/** Whether `version` (`v4`, `v4.1.0`) names a later major than `newest` (`v3`). A SHA or branch never does. */
+function laterMajor(version, newest) {
+    const major = (v) => {
+        const m = /^v?(\d+)(?:\.\d+)*$/.exec(v);
+        return m ? Number(m[1]) : undefined;
+    };
+    const a = major(version);
+    const b = major(newest);
+    return a !== undefined && b !== undefined && a > b;
+}
+function unresolvedWarning(ref) {
+    return (`forgejo: unresolved action ref '${ref}' — it has no built-in mapping and won't ` +
+        `resolve from a GitHub Marketplace on Forgejo. Use a full repository URL, or mirror ` +
+        `it under forgejo.actionsRoot in chant.config.ts.`);
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run docs` in lexicon-forgejo.
+ */
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,99 @@
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const OVERVIEW_CONTENT = `\`@intentius/chant-lexicon-forgejo\` targets **Forgejo Actions** — the CI behind
+[Codeberg](https://codeberg.org), self-hosted [Forgejo](https://forgejo.org),
+and [Gitea](https://about.gitea.com). Forgejo runs **GitHub-Actions-compatible**
+workflows, so the lexicon is a **thin dialect of the [github lexicon](/chant/lexicons/github/)**
+(chant #338): every entity, composite, and expression helper is the same class
+you'd import from the github package. This package supplies only what is
+genuinely Forgejo-specific — the serializer dialect and a github → forgejo
+migration path. One package covers Codeberg, self-hosted Forgejo, and Gitea.
+
+Author exactly as you would for GitHub Actions, importing from the forgejo
+package; see [The Forgejo Dialect](/chant/lexicons/forgejo/dialect/) for what
+changes on the way out.
+
+## Build
+
+Forgejo reads workflows from \`.forgejo/workflows/\` (or \`.gitea/workflows/\` for
+Gitea), so point the output there — the same way the github lexicon targets
+\`.github/workflows/\`:
+
+\`\`\`sh
+chant build src -o .forgejo/workflows/ci.yml
+\`\`\`
+
+## Configuration
+
+Override the runner-label map and the actions root in \`chant.config.ts\`:
+
+\`\`\`ts
+import type { ChantConfig } from "@intentius/chant/config";
+// Brings the \`forgejo\` key into ChantConfig (chant #1344).
+import "@intentius/chant-lexicon-forgejo";
+
+export default {
+  lexicons: ["forgejo"],
+  forgejo: {
+    runnerLabels: {
+      "ubuntu-latest": "docker",
+      "ubuntu-22.04": "ubuntu-lts",
+    },
+    actionsRoot: "https://code.forgejo.org",
+  },
+} satisfies ChantConfig;
+\`\`\`
+
+## Read-only context tools
+
+The forgejo lexicon ships the full \`forgejo:*\` [read-only context tools](/chant/guide/agent-integration/#read-only-context-tools)
+(\`checks\`, \`workflow\`, \`references\`, \`affected\`, \`workflow-yaml\`, \`source\`,
+\`owns\`, \`compare\`). Each builds from source and returns what chant already
+computes — without touching any live forge.
+
+## Runtime observation
+
+N/A — workflow definitions are git-tracked, so drift is a \`git diff\`, the same
+rationale as the github and gitlab lexicons. The lexicon implements neither
+\`describeResources()\` nor \`listArtifacts()\` and is warn-skipped on \`--live\`.
+
+## Validating execution
+
+A runtime E2E (\`just forgejo-runtime-e2e\`) builds a workflow and **runs** the
+generated \`.forgejo/workflows/ci.yml\` in Docker via a Forgejo runner
+(\`forgejo-runner\` / \`act_runner\` / \`act\` \`exec\`), proving Forgejo Actions
+accepts and executes chant's output. On-demand — it needs Docker and a runner
+tool, and is not part of the gating CI.
+
+A second harness (\`just forgejo-preview-e2e\`, chant #1223) drives a
+chant-declared per-PR preview workflow through stubbed \`pull_request\`
+opened/closed events: the on-open job deploys an isolated environment to a
+live emulator, the on-close job sweeps it by its ownership marker, and the
+harness asserts the environment's resources exist between the two runs and
+are gone after. Same on-demand terms.
+
+## Caveats
+
+Flow-style YAML (\`branches: [main]\`) is parsed by chant's lightweight core
+parser, which keeps it as a scalar — prefer block style in sources you intend to
+migrate. This is shared with the github import path.
+`;
+/**
+ * Generate documentation site for the Forgejo lexicon.
+ */
+export async function generateDocs(options) {
+    const config = {
+        name: "forgejo",
+        displayName: "Forgejo",
+        description: "Forgejo / Codeberg / Gitea Actions lexicon documentation — a thin GitHub Actions dialect",
+        distDir: "./dist",
+        outDir: "./docs",
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/forgejo/",
+        overview: OVERVIEW_CONTENT,
+        outputFormat: "The Forgejo lexicon serializes entities into the same YAML shape as GitHub Actions, then applies the Forgejo dialect (see [The Forgejo Dialect](/chant/lexicons/forgejo/dialect/)) before writing to `.forgejo/workflows/*.yml` (or `.gitea/workflows/*.yml` for Gitea).",
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (options?.verbose) {
+        console.error("Documentation generated");
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-forgejo.
+ */
+import { generate } from "./generate.js";
+const result = await generate({ verbose: true });
+console.error(`forgejo: ${result.resources} resources (reuses github's wholesale)`);

package/dist/codegen/generate.js

@@ -0,0 +1,31 @@
+/**
+ * Forgejo lexicon "generation" step.
+ *
+ * Forgejo has no spec of its own — every entity, property type, and enum a
+ * forgejo project uses comes from `@intentius/chant-lexicon-github` (see
+ * src/index.ts). There is nothing to fetch or parse here; this module exists
+ * only so `packagePipeline` (./package.ts) has a `GenerateResult` to build
+ * dist/manifest.json from. Refresh github's entities by running `chant
+ * generate` in the github lexicon, not here.
+ */
+// No entities of forgejo's own — the catalog is intentionally empty.
+const LEXICON_JSON = "{}";
+const TYPES_DTS = `// forgejo has no resource types of its own. Every entity a forgejo
+// project imports is declared in @intentius/chant-lexicon-github and
+// re-exported from this package's main entry point.
+export {};
+`;
+export async function generate(opts) {
+    if (opts?.verbose) {
+        console.error("forgejo: no spec of its own — reuses the github lexicon's entities wholesale (0 own resources)");
+    }
+    return {
+        lexiconJSON: LEXICON_JSON,
+        typesDTS: TYPES_DTS,
+        indexTS: "",
+        resources: 0,
+        properties: 0,
+        enums: 0,
+        warnings: [],
+    };
+}

package/dist/codegen/package-cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run bundle` in lexicon-forgejo.
+ */
+import { packageLexicon } from "./package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const { spec, stats } = await packageLexicon({ verbose: true });
+writeBundleSpec(spec, join(pkgDir, "dist"));
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);

package/dist/codegen/package.js

@@ -0,0 +1,42 @@
+/**
+ * Forgejo lexicon packaging — delegates to core packagePipeline.
+ *
+ * Bundles what forgejo actually ships (its post-synth checks, its skill,
+ * an empty resource catalog) into dist/manifest.json + dist/meta.json so
+ * the lexicon has a real, versioned package manifest like every other
+ * lexicon — see ./generate.ts for why the catalog itself is empty.
+ */
+import { readFileSync } from "fs";
+import { forgejoPlugin } from "../plugin.js";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+// package.ts is at src/codegen/package.ts — 2 dirname calls reach src/
+// then join(pkgDir, "..") is the package root where package.json lives
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
+/**
+ * Package the Forgejo lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: (_genResult) => {
+            return {
+                name: "forgejo",
+                version: pkgJson.version ?? "0.0.1",
+                chantVersion: ">=0.1.0",
+                namespace: "Forgejo",
+                intrinsics: [],
+                pseudoParameters: {},
+            };
+        },
+        srcDir: pkgDir,
+        collectSkills: () => {
+            const skillDefs = forgejoPlugin.skills?.() ?? [];
+            return collectSkills(skillDefs);
+        },
+        version: pkgJson.version ?? "0.0.1",
+    }, opts);
+}

package/dist/components/ci-jobs.js

@@ -0,0 +1,71 @@
+/**
+ * The Forgejo dialect of the three generated pipelines (#3765). Each forgejo
+ * generator builds github's document and hands it here: action refs and
+ * runner labels rewritten ({@link transformWorkflowObject}), `permissions:`
+ * dropped (the runner reads none), and a job's `environment:` dropped with a
+ * header note naming it, since Forgejo Actions has no environments.
+ */
+import { githubSecret } from "@intentius/chant/ci-jobs";
+import { transformWorkflowObject } from "../dialect.js";
+/** Apply the Forgejo dialect to one section of a pipeline doc. */
+export function forgejoize(value, dialect) {
+    return transformWorkflowObject(value, dialect).value;
+}
+/**
+ * Strip each job's `environment:` (#2257). Forgejo Actions has no
+ * environments, so the key would read as a deployment gate and hold nothing
+ * back. Dropped here rather than in the dialect's own `DROPPED_KEYS`, so it
+ * touches the generated pipelines alone and leaves every other document the
+ * dialect transforms as it is.
+ */
+export function withoutEnvironment(jobsDoc) {
+    return Object.fromEntries(Object.entries(jobsDoc).map(([jobName, job]) => {
+        if (typeof job !== "object" || job === null || !("environment" in job))
+            return [jobName, job];
+        const { environment: _dropped, ...rest } = job;
+        return [jobName, rest];
+    }));
+}
+/** The header of an Op's workflow whose environment gate did not survive the crossing. */
+export function droppedEnvironmentHeader(environmentName) {
+    return [
+        `# chant dropped \`environment: ${environmentName}\` from this workflow: Forgejo Actions has no`,
+        "# environments, so there is no protection rule, required reviewer or wait timer for the key to",
+        "# name. This job is not held back by anything on the forge. What still stops the apply is chant's",
+        "# own gate: the run records a pending fact on the chant/lifecycle branch and ends, and `chant",
+        "# approve <op> <gate>` is what lets the next run through.",
+    ];
+}
+/** The header of an Op waves workflow, naming each wave whose environment was dropped as `wave -> environment`. */
+export function droppedWaveEnvironmentsHeader(dropped) {
+    return [
+        `# chant dropped the environment of each of these waves: ${dropped.join(", ")}.`,
+        "# Forgejo Actions has no environments, so nothing on the forge holds these jobs.",
+        "# Each wave's own chant gate does: it records a pending fact on chant/lifecycle",
+        "# and the wave exits 3 until `chant approve` approves its set digest.",
+    ];
+}
+/**
+ * The token a Forgejo job uses for what the job token cannot do, such as
+ * dispatching a workflow: the `CHANT_FORGE_TOKEN` secret, a token with the
+ * `write:repository` scope.
+ */
+export const FORGE_TOKEN_ENV = { CHANT_FORGE_TOKEN: githubSecret("CHANT_FORGE_TOKEN") };
+/**
+ * A github workflow document under the Forgejo dialect: every section
+ * transformed, each job's `environment:` dropped, `permissions:` emptied, and
+ * `header` above it when given.
+ */
+export function forgejoWorkflowDoc(doc, dialect, header) {
+    return {
+        ...(header ? { header } : {}),
+        // Forgejo Actions reads `name:` as GitHub does (#2601).
+        ...(doc.name ? { name: doc.name } : {}),
+        on: forgejoize(doc.on, dialect),
+        ...(doc.env ? { env: forgejoize(doc.env, dialect) } : {}),
+        concurrency: forgejoize(doc.concurrency, dialect),
+        permissions: {},
+        jobsDoc: forgejoize(withoutEnvironment(doc.jobsDoc), dialect),
+        ...(doc.gatedNoticeDoc ? { gatedNoticeDoc: forgejoize(doc.gatedNoticeDoc, dialect) } : {}),
+    };
+}

package/dist/components/generate-op-pipeline.js

@@ -0,0 +1,116 @@
+/**
+ * Generate mode — scheduled Op → Forgejo Actions workflow YAML (#927).
+ *
+ * The forgejo counterpart to the github Op generator
+ * (`@intentius/chant-lexicon-github/components/generate-op-pipeline`, #927),
+ * exactly like `./generate-pipeline.ts` is the forgejo counterpart to
+ * github's component generator (#969). Reuses github's
+ * `buildGithubOpPipelineDocs` to build the same cron-trigger/concurrency/job
+ * structure, then applies the Forgejo dialect ({@link transformWorkflowObject})
+ * before emitting.
+ *
+ * One difference from the component generator: Forgejo Actions ignores
+ * the workflow-level `permissions:` section (the dialect drops every scope
+ * but `id-token`, see ../dialect.ts), so this omits the section outright rather
+ * than emitting a control the runner can't act on. The token a finding-mode
+ * needs still rides the trigger step's `env:` (`GH_TOKEN`/`GITHUB_TOKEN`,
+ * built by github's generator); actual write access on Forgejo is a property
+ * of the runner/token configuration, not the workflow YAML.
+ *
+ * That covers a spec's additive `permissions` too (#2242): an `id-token:
+ * write` added for OIDC is dropped here along with the mode's own scopes,
+ * because the Forgejo runner reads none of them and issues no OIDC token off
+ * a workflow permission. A Forgejo job authenticates to a cloud provider
+ * through whatever the runner already holds. A spec's `setup` steps do cross
+ * over unchanged: Forgejo runs `uses:` steps, so they are emitted in the
+ * position github puts them (after the checkout, ahead of the `beforeScript`
+ * lines) with the dialect's own action-ref rewrite applied — an action with
+ * no mapping in ../actions.ts passes through verbatim and resolves only if
+ * the runner can fetch it.
+ *
+ * `comment` (#2231) crosses over, since chant #2291: it posts onto the
+ * triggering pull request 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 reach 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. Since chant #3757 the post goes
+ * through the Forgejo client in `packages/core/src/pr-forge.ts` over `fetch`
+ * rather than through `gh`, so the job's image needs no `gh` either.
+ *
+ * `issue` crosses over too, since chant #2351. It was refused here from
+ * #2332 on, after chant #2315 drove the mode against a real Forgejo
+ * 12.0.4+gitea-1.22.0 instance: the paginated read and the `.pull_request ==
+ * null` filter behaved as on GitHub, but every POST and PATCH answered
+ * `{"message":"token is required"}` (HTTP 401), because `gh` sends
+ * `GH_TOKEN` only to github.com and `ghe.com` hosts. #2333 fixed that
+ * credential, and #3757 moved the mode off `gh` onto the Forgejo client in
+ * `packages/core/src/pr-forge.ts`, which sends `Authorization: token …`
+ * itself. The job this emits for a cron `issue` Op is github's, unchanged:
+ * the same trigger, and the same `GH_TOKEN`/`GITHUB_TOKEN` from
+ * `github.token` on the run step, which is the credential the mode reads.
+ * Only `permissions:` is dropped, as for every mode, so what that token may
+ * write on a scheduled run is the runner's configuration.
+ *
+ * A spec's `environment` (#2257) is dropped on the same terms as
+ * `permissions:`, and for a stronger reason: Forgejo Actions has no
+ * environments at all — no protection rules, no required reviewers, no
+ * per-environment secrets — so the key names an object that does not exist on
+ * the instance. Dropping it silently would be the worst outcome available,
+ * because the whole point of the option is a human holding an apply, so this
+ * also writes a comment into the generated file's header saying which
+ * environment was asked for and that nothing on Forgejo enforces it. What
+ * still holds the apply here is chant's own gate (#2119), which is a fact on
+ * the `chant/lifecycle` branch and needs nothing from the forge.
+ *
+ * The gated-apply notice job (#2243) crosses over since #3773. It used to
+ * shell to `gh` on GitHub's hosted runner image, which a Forgejo runner
+ * neither ships nor can point at its own instance, so it was dropped here
+ * along with the apply job's `gated`/`op`/`gate`/`approve` outputs that
+ * only it read (#2294). It now runs in the Op's own image and posts through
+ * `@intentius/chant/pr-forge`, whose Forgejo client finds the pull request
+ * a commit merged with `commits/{sha}/pull` and sends `Authorization: token`
+ * itself. So the doc rebuilt below carries `gatedNoticeDoc` through the
+ * same dialect transform as the jobs, which drops its `permissions:` the
+ * way it drops every scope but `id-token`. A `push` job also still runs
+ * with `--gated-exit 0`, and `chant run` still writes the gate and the
+ * approve command to `GITHUB_STEP_SUMMARY`.
+ *
+ * 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 { buildGithubOpPipelineDocs, emitOpPipelineYAML, } from "@intentius/chant-lexicon-github/components/generate-op-pipeline";
+import { droppedEnvironmentHeader, forgejoWorkflowDoc } from "./ci-jobs.js";
+/**
+ * Synthesize one `.forgejo/workflows/*.yml` per scheduled Op. Reuses github's
+ * trigger/job structure ({@link buildGithubOpPipelineDocs}) — its `setup`-step
+ * and additive-permission validation included, so an unpinned action ref is
+ * refused here on the same terms — then applies the Forgejo dialect and drops
+ * `permissions:` (ignored by the Forgejo runner).
+ * Wired into core's Op generate mode via the forgejo lexicon plugin's
+ * `generateOpPipeline` (../plugin.ts).
+ */
+export function generateForgejoOpPipeline(ops, options = {}, dialectOptions = {}) {
+    // `findingMode: "comment"` used to be refused by name here (#2231), and
+    // `findingMode: "issue"` from #2332 to #2351. Neither is now: both post
+    // through the Forgejo client — see the module doc above.
+    const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
+    return {
+        // One file per spec, in spec order, which is what lets the header below
+        // read its Op's own `environment` off the input by position.
+        files: files.map(({ name, doc }, index) => {
+            const environment = ops[index].environment;
+            // The Op's name carries over, and the gate-notice job (#3773) takes the
+            // dialect like the Op's own job.
+            const header = environment ? droppedEnvironmentHeader(environment.name) : undefined;
+            return { name, yaml: emitOpPipelineYAML(forgejoWorkflowDoc(doc, dialectOptions, header)) };
+        }),
+        jobs,
+    };
+}

package/dist/components/generate-op-waves-pipeline.js

@@ -0,0 +1,66 @@
+/**
+ * Op waves → Forgejo Actions workflow (#3679).
+ *
+ * The github workflow ({@link buildGithubOpWavesDoc}) under the Forgejo
+ * dialect: action refs rewritten, `permissions:` dropped (the runner reads
+ * none), and each wave's `environment:` dropped with a header line saying so,
+ * since Forgejo Actions has no environments. The wave's chant gate is what
+ * holds it there.
+ *
+ * With `resume` on the spec (#3683), `<name>-resume.yml` runs `chant run
+ * resume --op <name>` on that schedule. Forgejo has no API to re-run a run,
+ * so it dispatches the waves workflow again on its branch, with the
+ * `CHANT_FORGE_TOKEN` secret (a token with the `write:repository` scope).
+ *
+ * A `pr-review` wave (#3684) gets `<name>-plans.yml` on pull requests, as on
+ * GitHub. Forgejo's job token reads reviews with no permission to ask for.
+ *
+ * `runner` and a wave's `jobs` (#3914) render as on GitHub, with two limits:
+ * a runner is a label or a list of labels (a GitHub runner group is a spec
+ * error), and a job group cannot name an `environment`, since Forgejo has
+ * none to put in front of it. A job with id tokens keeps `permissions:
+ * id-token: write`, the one scope the dialect leaves, and reads each audience
+ * from `<NAME>_AUDIENCE` when it requests its token.
+ */
+import { buildGithubOpWavesDoc } from "@intentius/chant-lexicon-github/components/generate-op-waves-pipeline";
+import { emitOpPipelineYAML } from "@intentius/chant-lexicon-github/components/generate-op-pipeline";
+import { assertRunnerLabels } from "@intentius/chant/ci-jobs";
+import { droppedWaveEnvironmentsHeader, FORGE_TOKEN_ENV, forgejoWorkflowDoc } from "./ci-jobs.js";
+/** Render an Op waves spec as one Forgejo Actions workflow, `<name>.yml`. */
+export function generateForgejoOpWavesPipeline(spec, options, dialectOptions = {}) {
+    assertForgejoWaves(spec);
+    const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options);
+    const dropped = spec.waves.filter((w) => w.environment).map((w) => `${w.name} -> ${w.environment.name}`);
+    const header = dropped.length > 0 ? droppedWaveEnvironmentsHeader(dropped) : undefined;
+    const files = [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(forgejoWorkflowDoc(doc, dialectOptions, header)) }];
+    if (resumeDoc) {
+        // Forgejo has no API to re-run a run, so resume dispatches the workflow
+        // again, with a token that may.
+        const resume = forgejoWorkflowDoc(resumeDoc, dialectOptions);
+        for (const job of Object.values(resume.jobsDoc)) {
+            for (const step of job.steps)
+                if (step.env)
+                    step.env = { ...FORGE_TOKEN_ENV };
+        }
+        files.push({ name: `${spec.name}-resume.yml`, yaml: emitOpPipelineYAML(resume) });
+    }
+    if (plansDoc)
+        files.push({ name: `${spec.name}-plans.yml`, yaml: emitOpPipelineYAML(forgejoWorkflowDoc(plansDoc, dialectOptions)) });
+    return { files, jobs };
+}
+/** Refuse what Forgejo cannot carry (#3914): a runner group, and a job group's environment. */
+function assertForgejoWaves(spec) {
+    const subject = `Op waves "${spec.name}"`;
+    assertRunnerLabels(subject, "runner", spec.runner, "Forgejo");
+    for (const wave of spec.waves) {
+        assertRunnerLabels(subject, `wave "${wave.name}" runner`, wave.runner, "Forgejo");
+        for (const group of wave.jobs ?? []) {
+            const field = `wave "${wave.name}" job group "${group.name}"`;
+            assertRunnerLabels(subject, `${field} runner`, group.runner, "Forgejo");
+            if (group.environment) {
+                throw new Error(`${subject}: ${field} names the environment "${group.environment.name}", but Forgejo Actions has no environments, ` +
+                    "so nothing on the forge would hold the job or scope its secrets. Drop it; the group still renders as its own job with its own runner and variables.");
+            }
+        }
+    }
+}

package/dist/components/generate-pipeline.js

@@ -0,0 +1,51 @@
+/**
+ * Generate mode — component → Forgejo Actions workflow YAML (#969, epic #885).
+ *
+ * The forgejo counterpart to the github generator
+ * (`@intentius/chant-lexicon-github/components/generate-pipeline`, #891). Forgejo
+ * Actions is a GitHub-Actions dialect, and this lexicon is already a thin
+ * github-dialect serializer, so the pipeline SHAPE is identical: one job per
+ * component, `needs:` mirroring `dependsOn`, cross-stack outputs threaded as
+ * workflow artifacts, thin trigger jobs. Rather than re-derive the component
+ * graph, this reuses github's `buildGithubPipelineDoc` to build the exact same
+ * `on`/`env`/`jobs` structure, then applies the Forgejo dialect
+ * ({@link transformWorkflowObject}) before emitting — the same transform the
+ * forgejo serializer applies to authored workflows:
+ *
+ *  - runner labels: `runs-on: ubuntu-latest` → the project's Forgejo label
+ *    (default `docker`, the label a fresh `act_runner` exposes);
+ *  - `uses:` refs (`actions/checkout@v4`, `actions/upload-artifact@v4`, …)
+ *    rewritten to a Forgejo-resolvable form;
+ *  - keys the Forgejo runner ignores (`continue-on-error`, and `permissions` bar `id-token`)
+ *    dropped (`permissions` keeps only `id-token`, which OIDC needs).
+ *
+ * The output path convention is `.forgejo/workflows/` (vs github's
+ * `.github/workflows/`), set by the caller's `-o` flag — this module emits the
+ * workflow content, not its location, exactly like the github generator.
+ */
+import { buildGithubPipelineDoc, emitPipelineYAML, } from "@intentius/chant-lexicon-github/components/generate-pipeline";
+import { forgejoize } from "./ci-jobs.js";
+/**
+ * Synthesize a `.forgejo/workflows/*.yml` pipeline from a set of components.
+ * Reuses github's job/`needs:`/artifact structure ({@link buildGithubPipelineDoc}),
+ * then applies the Forgejo dialect. Wired into core's generate mode via the
+ * forgejo lexicon plugin's `generateComponentPipeline` (../plugin.ts).
+ */
+export function generateForgejoPipeline(components, options = {}, dialectOptions = {}) {
+    // The pull-request loop (#3183) talks to the forge, so its commands name Forgejo.
+    const doc = buildGithubPipelineDoc(components, options.prLoop ? { ...options, prLoop: { ...options.prLoop, forge: "forgejo" } } : options);
+    const forgejoDoc = {
+        // The environment identity (#2046) is dialect-neutral: name, environment,
+        // and the env-map's CHANT_ENV entry pass through untransformed.
+        name: doc.name,
+        environment: doc.environment,
+        on: forgejoize(doc.on, dialectOptions),
+        ...(doc.env ? { env: forgejoize(doc.env, dialectOptions) } : {}),
+        // A workspace member's working directory (#2542) reads the same on Forgejo.
+        ...(doc.defaults ? { defaults: doc.defaults } : {}),
+        jobsDoc: forgejoize(doc.jobsDoc, dialectOptions),
+        stages: doc.stages,
+        jobs: doc.jobs,
+    };
+    return { yaml: emitPipelineYAML(forgejoDoc), stages: doc.stages, jobs: doc.jobs, env: doc.environment };
+}

package/dist/config.js

@@ -0,0 +1,36 @@
+/**
+ * The `forgejo` namespace in `chant.config.ts` (#1344).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-forgejo";   // brings the `forgejo` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["forgejo"],
+ *   forgejo: {
+ *     runnerLabels: { "ubuntu-latest": "docker" },
+ *     actionsRoot: "https://code.forgejo.org",
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * One schema, three consumers: core validates the namespace against it at load,
+ * the type below is derived from it, and that derived type is what augments
+ * `ChantConfig` — so an unknown key fails at build time and at compile time for
+ * the same reason, rather than being silently ignored at both.
+ */
+import { z } from "zod";
+/**
+ * `strictObject`, not `object`. Core applies `.strict()` to the top level of a
+ * declared namespace itself, but nested objects are the lexicon's own to make
+ * strict — and `runnerLabels` is exactly where a typo would otherwise land.
+ */
+export const forgejoConfigSchema = z.strictObject({
+    /**
+     * GitHub-hosted runner label → Forgejo label. A label with no mapping falls
+     * back to the default Forgejo label and is flagged by WFJ011.
+     */
+    runnerLabels: z.record(z.string(), z.string()).optional(),
+    /** Root the common `actions/*` refs are rewritten under. */
+    actionsRoot: z.string().optional(),
+});