@intentius/chant-lexicon-github 0.124.30 → 0.124.32

package/dist/lint/rules/validate-concurrency.js

@@ -0,0 +1,59 @@
+/**
+ * GHA016: Validate Concurrency
+ *
+ * Flags `new Concurrency({cancelInProgress: true})` without `group`.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+export const validateConcurrencyRule = {
+    id: "GHA016",
+    severity: "warning",
+    category: "correctness",
+    description: "Concurrency with cancel-in-progress should specify a group",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function visit(node) {
+            if (ts.isNewExpression(node)) {
+                let isConcurrency = false;
+                if (ts.isIdentifier(node.expression) && node.expression.text === "Concurrency")
+                    isConcurrency = true;
+                if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "Concurrency")
+                    isConcurrency = true;
+                if (isConcurrency && node.arguments?.length) {
+                    const arg = node.arguments[0];
+                    if (ts.isObjectLiteralExpression(arg)) {
+                        let hasCancelInProgress = false;
+                        let hasGroup = false;
+                        for (const prop of arg.properties) {
+                            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                                if (prop.name.text === "cancelInProgress" || prop.name.text === "cancel-in-progress") {
+                                    // Check if it's set to true
+                                    if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                                        hasCancelInProgress = true;
+                                    }
+                                }
+                                if (prop.name.text === "group") {
+                                    hasGroup = true;
+                                }
+                            }
+                        }
+                        if (hasCancelInProgress && !hasGroup) {
+                            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                            diagnostics.push({
+                                file: sourceFile.fileName,
+                                line: line + 1,
+                                column: character + 1,
+                                ruleId: "GHA016",
+                                severity: "warning",
+                                message: "Concurrency with cancel-in-progress should specify a group to avoid cancelling unrelated runs.",
+                            });
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lsp/completions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAE1E"}
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAE1E"}

package/dist/lsp/completions.js

@@ -0,0 +1,18 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-github.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide GitHub Actions completions based on context.
+ */
+export function githubCompletions(ctx) {
+    return lexiconCompletions(ctx, getIndex(), "GitHub Actions entity");
+}

package/dist/lsp/hover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAEpE"}

package/dist/lsp/hover.js

@@ -0,0 +1,33 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-github.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide hover information for GitHub Actions entity types.
+ */
+export function githubHover(ctx) {
+    return lexiconHover(ctx, getIndex(), resourceHover);
+}
+function resourceHover(className, entry) {
+    const lines = [];
+    lines.push(`**${className}**`);
+    lines.push("");
+    lines.push(`GitHub Actions type: \`${entry.resourceType}\``);
+    if (entry.kind === "resource") {
+        lines.push("");
+        lines.push("*Resource entity — serialized as a top-level workflow/job entry*");
+    }
+    else {
+        lines.push("");
+        lines.push("*Property entity — used as a nested value in resources*");
+    }
+    return { contents: lines.join("\n") };
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.124.30",
+  "version": "0.124.32",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/dist/mcp/context-tools.js

@@ -0,0 +1,152 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * GitHub Actions workflow — its jobs and run order, what it pulls in from
+ * outside (actions, images), and its security findings — so an agent can ask
+ * about a change *before it runs or merges* (#327).
+ *
+ * The GitHub counterpart to the GitLab context tools. Every tool builds from
+ * source and returns data. None of them touch the live GitHub instance, read
+ * run history, or write anything — that boundary is what keeps chant a context
+ * producer and not a copy of the live tooling.
+ */
+import { build } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { postSynthChecks } from "../lint/post-synth/index.js";
+import { githubSerializer } from "../serializer.js";
+import { extractJobs, extractActionRefs, extractImageRefs, extractTriggers, extractWorkflowName, } from "../lint/post-synth/yaml-helpers.js";
+/** Build the project and return the emitted GitHub workflow YAML plus the raw result. */
+async function buildGithub(path) {
+    const result = await build(path, [githubSerializer]);
+    const out = result.outputs.get("github");
+    return { yaml: out ? getPrimaryOutput(out) : "", result };
+}
+/** Discover the lexicon's post-synth checks without depending on the plugin. */
+function githubPostSynthChecks() {
+    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));
+}
+/** Jobs that would re-run because they depend (transitively) on `job`. */
+export function downstreamJobs(yaml, job) {
+    const jobs = extractJobs(yaml);
+    // edge: upstream -> downstream (J depends on each of its needs)
+    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)" },
+    },
+};
+/** The read-only context tools for the GitHub lexicon. */
+export function githubContextTools() {
+    return [
+        {
+            name: "github:checks",
+            description: "Build the workflow and return its security and correctness findings (the GHA checks) as JSON. Read-only — does not touch the live GitHub instance.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml, result } = await buildGithub(params.path ?? ".");
+                if (!yaml)
+                    return { findings: [], note: "no GitHub workflow produced from this project" };
+                const scoped = { ...result, outputs: new Map([["github", result.outputs.get("github")]]) };
+                const diags = runPostSynthChecks(githubPostSynthChecks(), scoped);
+                return {
+                    findings: diags.map((d) => ({
+                        id: d.checkId,
+                        severity: d.severity,
+                        job: d.entity ?? null,
+                        message: d.message,
+                    })),
+                };
+            },
+        },
+        {
+            name: "github: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 buildGithub(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: "github: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 buildGithub(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: "github: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: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+                    job: { type: "string", description: "Job name to trace downstream from" },
+                },
+                required: ["job"],
+            },
+            async handler(params) {
+                const { yaml } = await buildGithub(params.path ?? ".");
+                const job = params.job;
+                return { job, wouldRerun: downstreamJobs(yaml, job) };
+            },
+        },
+        {
+            name: "github:workflow-yaml",
+            description: "Build the project and return the generated GitHub Actions workflow YAML as a string. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildGithub(params.path ?? ".");
+                return { yaml };
+            },
+        },
+    ];
+}

package/dist/package-cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-github.
+ */
+import { generate, writeGeneratedFiles } from "./codegen/generate.js";
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+// 1. Generate src/generated/ files
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult, pkgDir);
+console.error(`Generated ${genResult.resources} entities, ${genResult.properties} property types, ${genResult.enums} enums`);
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+const distDir = join(pkgDir, "dist");
+writeBundleSpec(spec, distDir);
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/dist/plugin.js

@@ -0,0 +1,344 @@
+/**
+ * GitHub Actions lexicon plugin.
+ *
+ * Provides serializer, template detection, and code generation
+ * for GitHub Actions workflows.
+ */
+import { compositeCatalog } from "./composites/catalog.js";
+import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
+import { githubAuditCatalog } from "./lint/audit-catalog.js";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { githubSerializer } from "./serializer.js";
+import { githubGraphEdges } from "./graph-edges.js";
+import { useTypedActionsRule } from "./lint/rules/use-typed-actions.js";
+import { useConditionBuildersRule } from "./lint/rules/use-condition-builders.js";
+import { noHardcodedSecretsRule } from "./lint/rules/no-hardcoded-secrets.js";
+import { useMatrixBuilderRule } from "./lint/rules/use-matrix-builder.js";
+import { extractInlineStructsRule } from "./lint/rules/extract-inline-structs.js";
+import { fileJobLimitRule } from "./lint/rules/file-job-limit.js";
+import { noRawExpressionsRule } from "./lint/rules/no-raw-expressions.js";
+import { missingRecommendedInputsRule } from "./lint/rules/missing-recommended-inputs.js";
+import { deprecatedActionVersionRule } from "./lint/rules/deprecated-action-version.js";
+import { jobTimeoutRule } from "./lint/rules/job-timeout.js";
+import { suggestCacheRule } from "./lint/rules/suggest-cache.js";
+import { validateConcurrencyRule } from "./lint/rules/validate-concurrency.js";
+import { detectSecretsRule } from "./lint/rules/detect-secrets.js";
+import { githubCompletions } from "./lsp/completions.js";
+import { githubHover } from "./lsp/hover.js";
+import { GitHubActionsParser } from "./import/parser.js";
+import { GitHubActionsGenerator } from "./import/generator.js";
+import { githubContextTools } from "./mcp/context-tools.js";
+import { generateGithubPipeline } from "./components/generate-pipeline.js";
+import { generateGithubOpPipeline } from "./components/generate-op-pipeline.js";
+import { generateGithubOpWavesPipeline } from "./components/generate-op-waves-pipeline.js";
+export const githubPlugin = {
+    name: "github",
+    auditCatalog: () => githubAuditCatalog,
+    // Generate mode (#891): synthesize a GitHub Actions workflow from the component graph.
+    generateComponentPipeline: (components, options) => generateGithubPipeline(components, options),
+    // Generate mode, Op counterpart (#927): synthesize one cron-triggered workflow per scheduled Op.
+    generateOpPipeline: (ops, options) => generateGithubOpPipeline(ops, options),
+    // Ordered waves of Op runs, each behind one gate (#3679).
+    generateOpWavesPipeline: (spec, options) => generateGithubOpWavesPipeline(spec, options),
+    serializer: githubSerializer,
+    // `needs`, reusable-workflow `uses:` and `workflow_run` as graph edges (#3910).
+    graphEdges: (entities) => githubGraphEdges(entities),
+    lintRules() {
+        return [
+            useTypedActionsRule,
+            useConditionBuildersRule,
+            noHardcodedSecretsRule,
+            useMatrixBuilderRule,
+            extractInlineStructsRule,
+            fileJobLimitRule,
+            noRawExpressionsRule,
+            missingRecommendedInputsRule,
+            deprecatedActionVersionRule,
+            jobTimeoutRule,
+            suggestCacheRule,
+            validateConcurrencyRule,
+            detectSecretsRule,
+        ];
+    },
+    postSynthChecks() {
+        return postSynthCheckList;
+    },
+    intrinsics() {
+        return [
+            {
+                name: "Expression",
+                description: "Typed class wrapping a raw GitHub Actions expression, serializing to `${{ }}` (chant #1069 — was registered as \"expression\", which src/index.ts never exported)",
+                outputKey: "expression",
+                isTag: false,
+            },
+            // chant #1966 — src/expression.ts's context-accessor and condition
+            // helpers, each a pure function of its arguments building an
+            // `Expression` (or, for `steps`/`needs`, a plain object of one).
+            // `foldsEagerly: true` (not `foldsAsCall`) because their usual use is
+            // embedded directly in a template literal (`` `${matrix("os")}` ``),
+            // which needs the real, already-live `Expression` at fold time to
+            // stringify correctly — see IntrinsicDef.foldsEagerly's doc.
+            { name: "secrets", description: "Access a secret by name.", isTag: false, foldsEagerly: true },
+            { name: "matrix", description: "Access a matrix value by key.", isTag: false, foldsEagerly: true },
+            { name: "steps", description: "Access a step output.", isTag: false, foldsEagerly: true },
+            { name: "needs", description: "Access a job output from a needed job.", isTag: false, foldsEagerly: true },
+            { name: "inputs", description: "Access a workflow input.", isTag: false, foldsEagerly: true },
+            { name: "vars", description: "Access a configuration variable.", isTag: false, foldsEagerly: true },
+            { name: "env", description: "Access an environment variable.", isTag: false, foldsEagerly: true },
+            { name: "always", description: "Always run, regardless of status.", isTag: false, foldsEagerly: true },
+            { name: "failure", description: "Run only if a previous step has failed.", isTag: false, foldsEagerly: true },
+            { name: "success", description: "Run only if all previous steps succeeded.", isTag: false, foldsEagerly: true },
+            { name: "cancelled", description: "Run only if the workflow was cancelled.", isTag: false, foldsEagerly: true },
+            { name: "contains", description: "Check if a string contains a substring.", isTag: false, foldsEagerly: true },
+            { name: "startsWith", description: "Check if a string starts with a prefix.", isTag: false, foldsEagerly: true },
+            { name: "toJSON", description: "Convert a value to JSON.", isTag: false, foldsEagerly: true },
+            { name: "fromJSON", description: "Parse a JSON string.", isTag: false, foldsEagerly: true },
+            { name: "format", description: "Format a string with placeholders.", isTag: false, foldsEagerly: true },
+            { name: "branch", description: "Check if the ref matches a branch name.", isTag: false, foldsEagerly: true },
+            { name: "tag", description: "Check if the ref matches a tag prefix.", isTag: false, foldsEagerly: true },
+        ];
+    },
+    initTemplates(template) {
+        if (template === "node-ci") {
+            return {
+                src: {
+                    "pipeline.ts": `import { NodeCI } from "@intentius/chant-lexicon-github";
+
+export const app = NodeCI({
+  nodeVersion: "22",
+  installCommand: "npm ci",
+  buildScript: "build",
+  testScript: "test",
+});
+`,
+                },
+            };
+        }
+        if (template === "docker-build") {
+            return {
+                src: {
+                    "pipeline.ts": `import { Job, Step, Workflow, PushTrigger, Checkout } from "@intentius/chant-lexicon-github";
+
+export const push = new PushTrigger({ branches: ["main"] });
+
+export const workflow = new Workflow({
+  name: "Docker Build",
+  on: { push: { branches: ["main"] } },
+});
+
+export const build = new Job({
+  "runs-on": "ubuntu-latest",
+  steps: [
+    Checkout({}).step,
+    new Step({
+      name: "Build and push",
+      run: "docker build -t myapp .",
+    }),
+  ],
+});
+`,
+                },
+            };
+        }
+        // Default template
+        return {
+            src: {
+                "pipeline.ts": `import { Workflow, Job, Step, Checkout, SetupNode } from "@intentius/chant-lexicon-github";
+
+export const workflow = new Workflow({
+  name: "CI",
+  on: {
+    push: { branches: ["main"] },
+    pull_request: { branches: ["main"] },
+  },
+});
+
+export const build = new Job({
+  "runs-on": "ubuntu-latest",
+  steps: [
+    Checkout({}).step,
+    SetupNode({ nodeVersion: "22", cache: "npm" }).step,
+    new Step({ name: "Install", run: "npm ci" }),
+    new Step({ name: "Build", run: "npm run build" }),
+    new Step({ name: "Test", run: "npm test" }),
+  ],
+});
+`,
+            },
+        };
+    },
+    detectTemplate(data) {
+        if (typeof data !== "object" || data === null)
+            return false;
+        const obj = data;
+        // GitHub Actions workflows have `on:` + `jobs:` keys
+        if (obj.on !== undefined && obj.jobs !== undefined)
+            return true;
+        // Check for job-like entries with runs-on
+        for (const value of Object.values(obj)) {
+            if (typeof value === "object" && value !== null) {
+                const entry = value;
+                if (entry["runs-on"] !== undefined || entry.steps !== undefined) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    },
+    completionProvider(ctx) {
+        return githubCompletions(ctx);
+    },
+    hoverProvider(ctx) {
+        return githubHover(ctx);
+    },
+    templateParser() {
+        return new GitHubActionsParser();
+    },
+    templateGenerator() {
+        return new GitHubActionsGenerator();
+    },
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const result = await generate({ verbose: options?.verbose ?? true });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeGeneratedFiles(result, pkgDir);
+        console.error(`Generated ${result.resources} entities, ${result.properties} property types, ${result.enums} enums`);
+        if (result.warnings.length > 0) {
+            console.error(`${result.warnings.length} warnings`);
+        }
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeGitHubCoverage } = await import("./coverage.js");
+        await analyzeGitHubCoverage({
+            verbose: options?.verbose,
+            minOverall: options?.minOverall,
+        });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        const distDir = join(pkgDir, "dist");
+        writeBundleSpec(spec, distDir);
+        console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [
+            createDiffTool(githubSerializer, "Compare current build output against previous output for GitHub Actions", "github"),
+            ...githubContextTools(),
+        ];
+    },
+    mcpResources() {
+        return [
+            createCatalogResource(import.meta.url, "GitHub Actions Entity Catalog", "JSON list of all supported GitHub Actions entity types", "lexicon-github.json", "github"),
+            {
+                uri: "examples/basic-ci",
+                name: "Basic CI Example",
+                description: "A basic GitHub Actions CI workflow with build and test",
+                mimeType: "text/typescript",
+                async handler() {
+                    return `import { Workflow, Job, Step, Checkout, SetupNode } from "@intentius/chant-lexicon-github";
+
+export const workflow = new Workflow({
+  name: "CI",
+  on: {
+    push: { branches: ["main"] },
+    pull_request: { branches: ["main"] },
+  },
+  permissions: { contents: "read" },
+});
+
+export const build = new Job({
+  "runs-on": "ubuntu-latest",
+  steps: [
+    Checkout({}).step,
+    SetupNode({ nodeVersion: "22", cache: "npm" }).step,
+    new Step({ name: "Install", run: "npm ci" }),
+    new Step({ name: "Build", run: "npm run build" }),
+    new Step({ name: "Test", run: "npm test" }),
+  ],
+});
+`;
+                },
+            },
+        ];
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        await generateDocs(options);
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-github.md",
+            name: "chant-github",
+            description: "GitHub Actions workflow lifecycle — build, validate, deploy",
+            triggers: [
+                { type: "file-pattern", value: "**/*.github.ts" },
+                { type: "file-pattern", value: "**/.github/workflows/*.yml" },
+                { type: "context", value: "github actions" },
+                { type: "context", value: "workflow" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Basic CI workflow",
+                    description: "Create a CI workflow with build and test",
+                    input: "Create a CI workflow",
+                    output: `new Workflow({ name: "CI", on: { push: { branches: ["main"] }, pull_request: { branches: ["main"] } } })`,
+                },
+            ],
+        },
+        {
+            file: "chant-github-patterns.md",
+            name: "chant-github-patterns",
+            description: "GitHub Actions workflow patterns — triggers, jobs, matrix, caching, artifacts",
+            triggers: [
+                { type: "context", value: "github actions" },
+                { type: "context", value: "workflow" },
+                { type: "context", value: "matrix" },
+                { type: "context", value: "cache" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Matrix strategy",
+                    input: "Set up a Node.js matrix build",
+                    output: `new Strategy({ matrix: { "node-version": ["18", "20", "22"] } })`,
+                },
+            ],
+        },
+        {
+            file: "chant-github-security.md",
+            name: "chant-github-security",
+            description: "GitHub Actions security — secret scanning, OIDC, permissions hardening, supply chain",
+            triggers: [
+                { type: "context", value: "github security" },
+                { type: "context", value: "workflow security" },
+                { type: "context", value: "oidc" },
+                { type: "context", value: "permissions" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Permissions hardening",
+                    input: "Lock down workflow permissions",
+                    output: `new Workflow({ permissions: { contents: "read" } })`,
+                },
+            ],
+        },
+    ]),
+};