@intentius/chant-lexicon-forgejo 0.124.31 → 0.124.32

package/dist/dialect.js

@@ -0,0 +1,198 @@
+/**
+ * Forgejo dialect transform.
+ *
+ * Forgejo Actions (the engine behind Codeberg, self-hosted Forgejo, and Gitea)
+ * runs GitHub-Actions-compatible YAML, so the github lexicon's serializer emits
+ * the right shape. The dialect differs in three small ways, all handled here as
+ * a pre-pass over the resolved entity graph before the github serializer runs:
+ *
+ *  1. `continue-on-error` is silently ignored by the Forgejo runner — we drop
+ *     it from the output and warn per occurrence. `permissions` is reduced to
+ *     the one scope a Forgejo job can still use: `id-token`, which a job that
+ *     assumes a cloud role over OIDC needs (#3500). Every other scope
+ *     (`contents`, `pull-requests`, ...) is dropped without a warning, since
+ *     Forgejo reads none of them and flags the key in the run page's
+ *     "Workflow warnings" box. A `permissions` block with no `id-token` goes
+ *     away whole; one with it keeps only that line.
+ *  2. GitHub-hosted runner labels (`ubuntu-latest`, …) have no fixed meaning on
+ *     Forgejo — we map them to a default Forgejo label, overridable per project.
+ *  3. Anything we can't place (an unmapped runner label) passes through with a
+ *     warning rather than being dropped.
+ *
+ * Operating on the entity graph (rather than string-munging YAML) keeps the
+ * transform faithful: the github serializer still does the actual emission.
+ */
+// chant#2444 — core's `isDeclarable`, not a local copy. This file carried its
+// own, testing only that the marker was PRESENT where core also requires it to
+// be `true`, so the two disagreed about a value carrying `false`. Core's also
+// accepts an entity a host built, which a local identity check cannot.
+import { isDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
+import { resolveActionRef } from "./actions.js";
+/**
+ * Keys the Forgejo runner ignores. Emitting them is misleading (they look
+ * enforced but aren't), so the dialect drops them. Compared in kebab-case so
+ * both `continueOnError` and `continue-on-error` spellings are caught.
+ * `permissions` is handled apart, by {@link reducePermissions}.
+ */
+const DROPPED_KEYS = new Set(["continue-on-error"]);
+/** The one `permissions` scope kept: a job needs it to request an OIDC token. */
+const KEPT_PERMISSION = "id-token";
+const PERMISSION_LEVELS = new Set(["read", "write", "none"]);
+/**
+ * True for a GitHub `permissions` value: `read-all`/`write-all`, or a map of
+ * scope to `read`/`write`/`none`. Anything else (an action's `with: {
+ * permissions: ... }` input, say) is not one and passes through untouched.
+ */
+function isPermissionsValue(value) {
+    if (typeof value === "string")
+        return value === "read-all" || value === "write-all";
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entries = Object.values(value);
+    return entries.every((v) => typeof v === "string" && PERMISSION_LEVELS.has(v));
+}
+/**
+ * Reduce a `permissions` value to what Forgejo can use: the `id-token` scope,
+ * or `undefined` when there is none (the caller then omits the key).
+ */
+function reducePermissions(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const scope = value[KEPT_PERMISSION];
+    return scope === undefined ? undefined : { [KEPT_PERMISSION]: scope };
+}
+/** Property key whose value is a runner-label selector. */
+const RUNS_ON_KEY = "runs-on";
+/** Property key whose value is an action/workflow reference. */
+const USES_KEY = "uses";
+/**
+ * Default GitHub-hosted runner label → Forgejo label mapping. `docker` is the
+ * label a freshly-registered Forgejo `act_runner` exposes, and the one used
+ * throughout the Forgejo Actions docs, so it is the safest default target.
+ * Override per project via `forgejo.runnerLabels` in `chant.config.ts`.
+ */
+export const DEFAULT_RUNNER_LABELS = {
+    "ubuntu-latest": "docker",
+    "ubuntu-24.04": "docker",
+    "ubuntu-22.04": "docker",
+    "ubuntu-20.04": "docker",
+};
+/** Convert a camelCase or kebab-case key to a canonical kebab-case form. */
+function toKebabCase(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Map a single runner label, passing it through unchanged when unmapped. An
+ * unmapped label that survives into the output is reported by the WFJ011
+ * post-synth check (which surfaces in both `chant build` and `chant lint`),
+ * so the dialect doesn't also warn here — that would double-report.
+ */
+function mapLabel(label, ctx) {
+    return ctx.labels[label] ?? label;
+}
+/** Remap a `runs-on` value (string or string[]); leave other shapes untouched. */
+function remapRunsOn(value, ctx) {
+    if (typeof value === "string")
+        return mapLabel(value, ctx);
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value.map((v) => mapLabel(v, ctx));
+    }
+    return value;
+}
+function transformValue(value, ctx) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (isDeclarable(value))
+        return cloneDeclarable(value, ctx);
+    if (Array.isArray(value))
+        return value.map((v) => transformValue(v, ctx));
+    // Plain object: drop ignored keys, remap runs-on, recurse into the rest.
+    const result = {};
+    for (const [key, v] of Object.entries(value)) {
+        const kebab = toKebabCase(key);
+        if (DROPPED_KEYS.has(kebab)) {
+            ctx.warnings.push(`forgejo: dropped '${kebab}' in ${ctx.where} — the Forgejo runner ignores it. ` +
+                `Re-establish this control through your Forgejo/runner configuration.`);
+            continue;
+        }
+        if (kebab === "permissions" && isPermissionsValue(v)) {
+            const kept = reducePermissions(v);
+            if (kept)
+                result[key] = kept;
+            continue;
+        }
+        if (kebab === RUNS_ON_KEY) {
+            result[key] = remapRunsOn(v, ctx);
+            continue;
+        }
+        if (kebab === USES_KEY && typeof v === "string") {
+            // Rewrite to a Forgejo-resolvable form. An unresolved ref that survives
+            // is reported by the WFJ010 post-synth check (build + lint), so the
+            // dialect doesn't also warn here — that would double-report.
+            result[key] = resolveActionRef(v, { actionsRoot: ctx.actionsRoot }).rewritten;
+            continue;
+        }
+        result[key] = transformValue(v, ctx);
+    }
+    dropV4OnlyArtifactInputs(result);
+    return result;
+}
+/**
+ * The inputs only `upload-artifact` v4 has, which a step moved to v3
+ * (`FORGEJO_ARTIFACT_VERSION`, #4008) loses. v3 always uploads hidden files,
+ * so dropping `include-hidden-files` keeps what the step uploads; and a v3
+ * artifact is not immutable, so a second upload under one name needs no
+ * `overwrite`.
+ */
+const V4_ONLY_UPLOAD_INPUTS = new Set(["include-hidden-files", "overwrite"]);
+/** Drop {@link V4_ONLY_UPLOAD_INPUTS} from a step that uses `upload-artifact@v3`. */
+function dropV4OnlyArtifactInputs(step) {
+    const uses = step.uses;
+    const withs = step.with;
+    if (typeof uses !== "string" || !/\/actions\/upload-artifact@v3$/.test(uses))
+        return;
+    if (withs === null || typeof withs !== "object" || Array.isArray(withs))
+        return;
+    const kept = Object.fromEntries(Object.entries(withs).filter(([k]) => !V4_ONLY_UPLOAD_INPUTS.has(toKebabCase(k))));
+    step.with = kept;
+}
+/** Shallow-clone a Declarable, replacing its `props` with a transformed copy. */
+function cloneDeclarable(entity, ctx) {
+    const descriptors = Object.getOwnPropertyDescriptors(entity);
+    const clone = Object.create(Object.getPrototypeOf(entity), descriptors);
+    const rawProps = isResourceDeclarable(entity) ? entity.props : undefined;
+    const newProps = transformValue(rawProps, ctx);
+    Object.defineProperty(clone, "props", {
+        value: newProps,
+        enumerable: descriptors.props?.enumerable ?? false,
+        configurable: true,
+        writable: descriptors.props?.writable ?? true,
+    });
+    return clone;
+}
+/**
+ * Apply the Forgejo dialect to a plain object — e.g. a parsed GitHub Actions
+ * workflow during migration, rather than the resolved entity graph. Same
+ * rules as {@link applyForgejoDialect}: drop ignored keys, remap runner
+ * labels, resolve `uses:` refs.
+ */
+export function transformWorkflowObject(obj, options = {}) {
+    const labels = { ...DEFAULT_RUNNER_LABELS, ...(options.runnerLabels ?? {}) };
+    const warnings = [];
+    const ctx = { labels, actionsRoot: options.actionsRoot, warnings, where: "workflow" };
+    return { value: transformValue(obj, ctx), warnings };
+}
+/**
+ * Apply the Forgejo dialect to a resolved entity map. Returns transformed
+ * clones plus the diagnostics produced (dropped keys, unmapped labels).
+ */
+export function applyForgejoDialect(entities, options = {}) {
+    const labels = { ...DEFAULT_RUNNER_LABELS, ...(options.runnerLabels ?? {}) };
+    const warnings = [];
+    const out = new Map();
+    for (const [name, entity] of entities) {
+        const ctx = { labels, actionsRoot: options.actionsRoot, warnings, where: name };
+        out.set(name, cloneDeclarable(entity, ctx));
+    }
+    return { entities: out, warnings };
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+// Forgejo Actions lexicon — a thin dialect of the github lexicon.
+//
+// Serializer + plugin override only the dialect; everything a user writes
+// (entities, expression helpers, context variables, composites) is reused
+// directly from the github lexicon and re-exported here so a forgejo project
+// imports solely from "@intentius/chant-lexicon-forgejo".
+// Serializer
+export { forgejoSerializer } from "./serializer.js";
+// Plugin
+export { forgejoPlugin } from "./plugin.js";
+// Dialect (exposed for tooling/tests)
+export { applyForgejoDialect, transformWorkflowObject, DEFAULT_RUNNER_LABELS, } from "./dialect.js";
+// github → forgejo migration
+export { transform, detectGitHubWorkflow, } from "./migrate/from-github/index.js";
+export { analyzeForgejoSecurity, renderSecurityPosture, } from "./migrate/from-github/security.js";
+// Action-reference resolver (exposed for tooling/tests)
+export { resolveActionRef, DEFAULT_ACTIONS_ROOT, KNOWN_ACTIONS, } from "./actions.js";
+// Reuse the entire github authoring surface: generated entities, expression
+// system, context variables, and composites.
+export * from "@intentius/chant-lexicon-github";
+// The `forgejo` chant.config namespace (#1344). Exported as a type and, by
+// virtue of this module being part of the program, as the `ChantConfig`
+// augmentation that makes `forgejo: { … }` typecheck in a project config.
+export { forgejoConfigSchema } from "./config.js";

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "ab46d63a952c24ff719d4370ff7188c76232041fdadcb31af27c9be433197c05",
+    "manifest.json": "7885f3eea1327f2431dd65676726257cf9bd60253edeaa96bc9c1f9e18b2335f",
     "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": "f28d7fb69fb1cfd992496ef41fda0ea5ccd54a29b84ea1c501a44f6a3992c4d5"
   },
-  "composite": "baad2eae2dde1936145d5f3778f78a952accaddac9e956d1211a1125f955e75a"
+  "composite": "dcc44816420a6008af0661e553d724c0a9242ba2cea6720b9c63bf44bf7ce962"
 }

package/dist/lint/audit-catalog.js

@@ -0,0 +1,9 @@
+/**
+ * The forgejo lexicon's chant audit catalog — metadata for its post-synth rules
+ * (WFJ Forgejo rules). Contributed via forgejoPlugin.auditCatalog() (#687).
+ */
+import { auditRule } from "@intentius/chant/audit/catalog";
+export const forgejoAuditCatalog = {
+    WFJ010: auditRule("WFJ010", "merge-worthy", "guidance", "Unresolved action reference on Forgejo", "Use an action reference Forgejo can resolve (full URL or a mirrored action).", { category: "correctness" }),
+    WFJ011: auditRule("WFJ011", "merge-worthy", "guidance", "GitHub-hosted runner label with no Forgejo equivalent", "Use a runner label your Forgejo instance provides.", { category: "correctness" }),
+};

package/dist/lint/post-synth/index.js

@@ -0,0 +1,6 @@
+import { wfj010 } from "./wfj010.js";
+import { wfj011 } from "./wfj011.js";
+export const postSynthChecks = [
+    wfj010,
+    wfj011,
+];

package/dist/lint/post-synth/wfj010.js

@@ -0,0 +1,34 @@
+/**
+ * WFJ010: Unresolved action reference.
+ *
+ * After the forgejo dialect runs, every `uses:` should be a Forgejo-resolvable
+ * form (a full URL, a local `./` action, or `docker://`). A bare `owner/repo@ref`
+ * that survives into the output won't resolve — Forgejo has no GitHub
+ * Marketplace. Flags it so it's caught in `chant lint` / `forgejo:checks`, not
+ * only as a build-time warning.
+ */
+import { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { extractActionRefs } from "@intentius/chant-lexicon-github/lint/post-synth/yaml-helpers";
+import { resolveActionRef } from "../../actions.js";
+export const wfj010 = {
+    id: "WFJ010",
+    description: "Unresolved action reference (won't resolve on Forgejo)",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [, output] of ctx.outputs) {
+            const yaml = getPrimaryOutput(output);
+            for (const ref of extractActionRefs(yaml)) {
+                if (resolveActionRef(ref.ref).warning) {
+                    diagnostics.push({
+                        checkId: "WFJ010",
+                        severity: "warning",
+                        message: `Job "${ref.job}" references '${ref.ref}', which has no Forgejo-resolvable form. Use a full repository URL or map it under forgejo.actionsRoot.`,
+                        entity: ref.job,
+                        lexicon: "forgejo",
+                    });
+                }
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/wfj011.js

@@ -0,0 +1,36 @@
+/**
+ * WFJ011: GitHub-hosted runner label.
+ *
+ * `runs-on` labels like `macos-latest` / `windows-latest` name GitHub-hosted
+ * runners that don't exist on Forgejo, and `ubuntu-*` labels that the dialect
+ * didn't map (e.g. when mapping is overridden away) won't be advertised by a
+ * default Forgejo runner. Flags any such label that survives into the output.
+ */
+import { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { extractRunsOnByJob } from "@intentius/chant-lexicon-github/lint/post-synth/yaml-helpers";
+/** Labels that name a GitHub-hosted runner image (no fixed Forgejo equivalent). */
+const GITHUB_HOSTED = /^(ubuntu|macos|windows)-/;
+export const wfj011 = {
+    id: "WFJ011",
+    description: "GitHub-hosted runner label with no Forgejo equivalent",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [, output] of ctx.outputs) {
+            const yaml = getPrimaryOutput(output);
+            for (const [job, labels] of extractRunsOnByJob(yaml)) {
+                for (const label of labels) {
+                    if (GITHUB_HOSTED.test(label)) {
+                        diagnostics.push({
+                            checkId: "WFJ011",
+                            severity: "warning",
+                            message: `Job "${job}" runs on '${label}', a GitHub-hosted runner label with no Forgejo equivalent. Map it via forgejo.runnerLabels or target a label your Forgejo runners advertise.`,
+                            entity: job,
+                            lexicon: "forgejo",
+                        });
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/delegate-to-github.js

@@ -0,0 +1,30 @@
+/**
+ * Forgejo lint rules — wrapped from github, not duplicated.
+ *
+ * Forgejo has no lint rules of its own: entities, composites, and every
+ * expression helper a forgejo project imports are the exact same github
+ * classes (see src/index.ts's `export * from "@intentius/chant-lexicon-github"`).
+ * A forgejo workflow is TypeScript indistinguishable in shape from an
+ * equivalent github workflow, so github's lint rules (GHA001-GHA058 — typed
+ * composites, secret detection, supply-chain checks, etc.) apply to it
+ * unmodified. Re-implementing or forking any of them here would drift from
+ * github's the first time either side changed.
+ *
+ * Each rule is wrapped rather than re-exported verbatim under github's own
+ * id: `chant lint`/`chant audit` can load the github and forgejo plugins in
+ * the same process (e.g. `chant audit` scans a repo without knowing its CI
+ * provider up front — see packages/core/src/audit/core.ts's
+ * `defaultChecksProvider`, which already loads forgejo+github together for
+ * post-synth checks), and `loadPlugins`' cross-lexicon conflict check
+ * (packages/core/src/cli/conflict-check.ts) hard-fails on two plugins
+ * claiming the same rule id. Prefixing with `WFJ-` — forgejo's existing
+ * post-synth namespace — keeps every id globally unique while leaving the
+ * check (and fix, where one exists) exactly as github wrote it; only the
+ * `id` field changes.
+ */
+import { githubPlugin } from "@intentius/chant-lexicon-github";
+/** Wrap a github lint rule under forgejo's `WFJ-` namespace, unmodified otherwise. */
+export function wrapGithubRule(rule) {
+    return { ...rule, id: `WFJ-${rule.id}` };
+}
+export const forgejoLintRules = (githubPlugin.lintRules?.() ?? []).map(wrapGithubRule);

package/dist/lint/rules/index.js

@@ -0,0 +1,5 @@
+/**
+ * All lint rules provided by the Forgejo lexicon — delegated to github, see
+ * ./delegate-to-github.
+ */
+export { forgejoLintRules } from "./delegate-to-github.js";

package/dist/lsp/completions.js

@@ -0,0 +1,13 @@
+/**
+ * Forgejo LSP completions — delegated to github, not duplicated.
+ *
+ * Forgejo reuses github's entire authoring surface (entities, composites) —
+ * there is no forgejo-specific resource catalog to index. This forwards
+ * straight to `githubPlugin`'s own completion provider, which already reads
+ * github's generated entity catalog; forking a second copy of it here would
+ * only drift the moment github's catalog regenerates.
+ */
+import { githubPlugin } from "@intentius/chant-lexicon-github";
+export function forgejoCompletions(ctx) {
+    return githubPlugin.completionProvider?.(ctx) ?? [];
+}

package/dist/lsp/hover.js

@@ -0,0 +1,11 @@
+/**
+ * Forgejo LSP hover — delegated to github, not duplicated.
+ *
+ * Same reasoning as ./completions.ts: forgejo authors against github's
+ * exact classes, so hover information for them is github's hover
+ * information, unmodified.
+ */
+import { githubPlugin } from "@intentius/chant-lexicon-github";
+export function forgejoHover(ctx) {
+    return githubPlugin.hoverProvider?.(ctx);
+}

package/dist/manifest.json

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

package/dist/mcp/context-tools.js

@@ -0,0 +1,243 @@
+/**
+ * Read-only MCP tools for the forgejo lexicon.
+ *
+ * The forgejo counterpart to the github/gitlab context tools (#327): expose
+ * what `chant build` already computes about a Forgejo workflow — its triggers
+ * and jobs, what it pulls in from outside, its findings, where each job came
+ * from in source — plus `forgejo:compare`, the migration safety view. Because
+ * Forgejo emits GitHub-style YAML, the parsing reuses the github lexicon's
+ * yaml-helpers.
+ *
+ * Every tool builds from source and returns data. None touch a live forge,
+ * read run history, or write anything.
+ */
+import { build } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { postSynthChecks } from "../lint/post-synth/index.js";
+import { getProvenance } from "@intentius/chant/provenance";
+import { relative, isAbsolute, resolve } from "path";
+import { readFile } from "fs/promises";
+import { extractJobs, extractActionRefs, extractImageRefs, extractTriggers, extractWorkflowName, } from "@intentius/chant-lexicon-github/lint/post-synth/yaml-helpers";
+import { forgejoSerializer } from "../serializer.js";
+import { transform, detectGitHubWorkflow } from "../migrate/from-github/index.js";
+/**
+ * Build the project with the forgejo serializer and return the emitted YAML.
+ * The serializer is registered under the "github" lexicon (it serializes the
+ * reused github entities), so the output is keyed "github".
+ */
+async function buildForgejo(path) {
+    const result = await build(path, [forgejoSerializer]);
+    const out = result.outputs.get("github");
+    return { yaml: out ? getPrimaryOutput(out) : "", result };
+}
+/** Discover the forgejo post-synth checks without depending on the plugin. */
+function forgejoPostSynthChecks() {
+    return postSynthChecks;
+}
+/** Is a `uses:` ref pinned to a full commit SHA (the only immutable form)? */
+export function actionPinned(ref) {
+    const at = ref.lastIndexOf("@");
+    return at !== -1 && /^[0-9a-f]{40}$/.test(ref.slice(at + 1));
+}
+/** The YAML job name a build entity serializes to (camelCase → kebab-case). */
+export function jobNameOf(entityName) {
+    return entityName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Find the build entity whose serialized job name matches `job`. */
+function entityForJob(result, job) {
+    for (const [name, entity] of result.entities) {
+        if (name === job || jobNameOf(name) === job)
+            return { name, entity };
+    }
+    return undefined;
+}
+/** Render a source-file path relative to the project root, when possible. */
+function relSource(root, file) {
+    if (!file)
+        return undefined;
+    if (!isAbsolute(file))
+        return file;
+    const rel = relative(root, file);
+    return rel.startsWith("..") ? file : rel;
+}
+/** Jobs that would re-run because they depend (transitively) on `job`. */
+export function downstreamJobs(yaml, job) {
+    const jobs = extractJobs(yaml);
+    const downstreamOf = new Map();
+    for (const [name, j] of jobs) {
+        for (const dep of j.needs ?? []) {
+            const arr = downstreamOf.get(dep) ?? [];
+            arr.push(name);
+            downstreamOf.set(dep, arr);
+        }
+    }
+    const out = new Set();
+    const queue = [job];
+    while (queue.length) {
+        const cur = queue.shift();
+        for (const next of downstreamOf.get(cur) ?? []) {
+            if (!out.has(next)) {
+                out.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    return [...out];
+}
+const PATH_INPUT = {
+    type: "object",
+    properties: {
+        path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+    },
+};
+const JOB_INPUT = {
+    type: "object",
+    properties: {
+        path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+        job: { type: "string", description: "Job name (as it appears in the generated YAML)" },
+    },
+    required: ["job"],
+};
+/** The read-only context tools for the forgejo lexicon. */
+export function forgejoContextTools() {
+    return [
+        {
+            name: "forgejo:checks",
+            description: "Build the workflow and return its Forgejo-specific findings (the WFJ checks: unresolved action refs, GitHub-hosted runner labels) as JSON. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml, result } = await buildForgejo(params.path ?? ".");
+                if (!yaml)
+                    return { findings: [], note: "no Forgejo workflow produced from this project" };
+                const scoped = { ...result, outputs: new Map([["github", result.outputs.get("github")]]) };
+                const diags = runPostSynthChecks(forgejoPostSynthChecks(), scoped);
+                return {
+                    findings: diags.map((d) => ({ id: d.checkId, severity: d.severity, job: d.entity ?? null, message: d.message })),
+                };
+            },
+        },
+        {
+            name: "forgejo:workflow",
+            description: "Build the workflow and return its triggers and jobs as written (name, what each job runs after, step count) — before anything runs. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildForgejo(params.path ?? ".");
+                const jobs = [...extractJobs(yaml).values()].map((j) => ({
+                    name: j.name,
+                    runsAfter: j.needs ?? [],
+                    steps: j.steps?.length ?? 0,
+                }));
+                return { workflow: extractWorkflowName(yaml) ?? null, triggers: Object.keys(extractTriggers(yaml)), jobs };
+            },
+        },
+        {
+            name: "forgejo:references",
+            description: "Build the workflow and list everything it pulls in from outside (actions via uses:, container/service images) and whether each is pinned to an immutable commit SHA. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildForgejo(params.path ?? ".");
+                const actions = extractActionRefs(yaml).map((a) => ({
+                    kind: a.level === "job" ? "reusable-workflow" : "action",
+                    job: a.job,
+                    source: a.ref,
+                    pinned: actionPinned(a.ref),
+                }));
+                const images = extractImageRefs(yaml).map((i) => ({
+                    kind: "image",
+                    job: i.job,
+                    source: i.image,
+                    pinned: i.image.includes("@sha256:"),
+                }));
+                return [...actions, ...images];
+            },
+        },
+        {
+            name: "forgejo:affected",
+            description: "Build the workflow and, given a job name, list the jobs that would re-run because they depend on it (the needs chain). Read-only.",
+            inputSchema: JOB_INPUT,
+            async handler(params) {
+                const { yaml } = await buildForgejo(params.path ?? ".");
+                const job = params.job;
+                return { job, wouldRerun: downstreamJobs(yaml, job) };
+            },
+        },
+        {
+            name: "forgejo:workflow-yaml",
+            description: "Build the project and return the generated Forgejo Actions workflow YAML as a string. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildForgejo(params.path ?? ".");
+                return { yaml };
+            },
+        },
+        {
+            name: "forgejo:source",
+            description: "Build the project and, given a job name, say where it came from in the TypeScript source — the file that declared it and the composite that expanded it, if any. Entity-level provenance, not a YAML-line source map. Read-only.",
+            inputSchema: JOB_INPUT,
+            async handler(params) {
+                const root = params.path ?? ".";
+                const { result } = await buildForgejo(root);
+                const job = params.job;
+                const found = entityForJob(result, job);
+                if (!found)
+                    return { job, found: false, note: "no build entity serializes to that job name" };
+                const prov = getProvenance(found.entity);
+                return { job, found: true, entity: found.name, from: relSource(root, prov?.sourceFile) ?? null, via: prov?.composite ?? null };
+            },
+        },
+        {
+            name: "forgejo:owns",
+            description: "Build the project and report whether a job is declared (owned) by chant in this project's source. For workflow config, ownership means \"declared here\" — Forgejo Actions jobs are not taggable cloud resources, so there is no live ownership marker as there is for cloud lexicons. Read-only.",
+            inputSchema: JOB_INPUT,
+            async handler(params) {
+                const root = params.path ?? ".";
+                const { result } = await buildForgejo(root);
+                const job = params.job;
+                const found = entityForJob(result, job);
+                return {
+                    job,
+                    owned: Boolean(found),
+                    basis: "declared-in-source",
+                    note: "Forgejo Actions jobs are not taggable cloud resources; ownership here means the job is declared by chant in this project. Live ownership markers apply to cloud lexicons (aws/azure/k8s).",
+                };
+            },
+        },
+        {
+            name: "forgejo:compare",
+            description: "Given a GitHub Actions workflow file, migrate it to Forgejo and report which properties survive the move and which weaken or are lost (the migration safety view). Returns a per-property fate (translated/approximated/needs-review/lost) plus summary counts. Read-only — analyzes, never writes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file: { type: "string", description: "Path to a .github/workflows/*.yml workflow file to migrate and compare" },
+                },
+                required: ["file"],
+            },
+            async handler(params) {
+                const file = resolve(params.file ?? "");
+                let content;
+                try {
+                    content = await readFile(file, "utf8");
+                }
+                catch {
+                    return { file: params.file ?? null, found: false, note: "could not read the workflow file" };
+                }
+                if (!detectGitHubWorkflow(content)) {
+                    return { file: params.file ?? null, found: false, note: "file does not look like a GitHub Actions workflow" };
+                }
+                const migration = await transform(content, { security: true, sourceFile: file });
+                const properties = migration.provenance.map((r) => ({
+                    property: r.security.property,
+                    fate: r.security.fate,
+                    severity: r.security.severity,
+                    sourceKey: r.sourceKey,
+                    reestablish: r.security.reestablish ?? null,
+                    note: r.note ?? null,
+                }));
+                const summary = { translated: 0, approximated: 0, "needs-review": 0, lost: 0 };
+                for (const p of properties)
+                    summary[p.fate] = (summary[p.fate] ?? 0) + 1;
+                return { found: true, properties, summary };
+            },
+        },
+    ];
+}