@intentius/chant-lexicon-gitlab 0.0.6 → 0.0.8

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "c72b64b58dec21e0",
+    "manifest.json": "3a48cdeca93a7a4d",
     "meta.json": "9ee0d2f2d1679f09",
     "types/index.d.ts": "4e56a7de40d655c0",
     "rules/missing-stage.ts": "6d5379e74209a735",
@@ -11,7 +11,7 @@
     "rules/wgl011.ts": "b6b97e5104d91267",
     "rules/yaml-helpers.ts": "a66cc193b4ef4f0a",
     "rules/wgl010.ts": "1548cad287cdf286",
-    "skills/gitlab-ci.md": "f860e40c2643c327"
+    "skills/chant-gitlab.md": "92ce73e97ee82ac9"
   },
-  "composite": "95b9f28f579d5862"
+  "composite": "c6ad87f69da787de"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/dist/skills/chant-gitlab.md

@@ -0,0 +1,59 @@
+---
+skill: chant-gitlab
+description: Build, validate, and deploy GitLab CI pipelines from a chant project
+user-invocable: true
+---
+
+# Deploying GitLab CI Pipelines from Chant
+
+This project defines GitLab CI jobs as TypeScript in `src/`. Use these steps to build, validate, and deploy.
+
+## Build the pipeline
+
+```bash
+chant build src/ --output .gitlab-ci.yml
+```
+
+## Validate before pushing
+
+```bash
+chant lint src/
+```
+
+For API-level validation against your GitLab instance:
+```bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/ci/lint" \
+  --data "{\"content\": \"$(cat .gitlab-ci.yml)\"}"
+```
+
+## Deploy
+
+Commit and push the generated `.gitlab-ci.yml` — GitLab runs the pipeline automatically:
+
+```bash
+chant build src/ --output .gitlab-ci.yml
+git add .gitlab-ci.yml
+git commit -m "Update pipeline"
+git push
+```
+
+## Check pipeline status
+
+- GitLab UI: project → CI/CD → Pipelines
+- API: `curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines?per_page=5"`
+
+## Retry a failed job
+
+- GitLab UI: click Retry on the failed job
+- API: `curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/retry"`
+
+## Cancel a running pipeline
+
+- API: `curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/cancel"`
+
+## Troubleshooting
+
+- Check job logs in GitLab UI: project → CI/CD → Jobs → click the job
+- `chant lint src/` catches: missing scripts (WGL002), deprecated only/except (WGL001), missing stages (WGL003), artifacts without expiry (WGL004)
+- Post-synth checks (WGL010, WGL011) run during build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "license": "Apache-2.0",
   "type": "module",
   "files": ["src/", "dist/"],

package/src/codegen/docs.ts

@@ -58,8 +58,7 @@ The generated file includes:
 | Chant (TypeScript) | YAML output | Rule |
 |--------------------|-------------|------|
 | \`export const buildApp = new Job({...})\` | \`build-app:\` | Export name → kebab-case job key |
-| \`expireIn: "1 week"\` | \`expire_in: 1 week\` | camelCase → snake_case |
-| \`ifCondition: ...\` | \`if: ...\` | Reserved word properties use suffixed names |
+| \`expire_in: "1 week"\` | \`expire_in: 1 week\` | Property names use spec-native snake_case |
 | \`new Image({ name: "node:20" })\` | \`image: node:20\` | Single-property objects are collapsed |
 
 ## Validating locally
@@ -108,7 +107,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
         description: "Jobs, stages, artifacts, caching, images, rules, environments, and triggers in the GitLab CI/CD lexicon",
         content: `Every exported \`Job\` declaration becomes a job entry in the generated \`.gitlab-ci.yml\`. The serializer handles the translation automatically:
 
-- Converts camelCase property names to snake_case (\`expireIn\` → \`expire_in\`)
+- Property names use spec-native snake_case (\`expire_in\`, \`allow_failure\`)
 - Converts export names to kebab-case job keys (\`buildApp\` → \`build-app\`)
 - Collects stages from all jobs into a \`stages:\` list
 - Collapses single-property objects (\`new Image({ name: "node:20" })\` → \`image: node:20\`)
@@ -539,6 +538,61 @@ deploy:
 5. **JUnit reports** — test artifacts include JUnit XML for GitLab MR display
 `,
       },
+      {
+        slug: "skills",
+        title: "AI Skills",
+        description: "AI agent skills bundled with the GitLab CI/CD lexicon",
+        content: `The GitLab lexicon ships an AI skill called **chant-gitlab** that teaches AI coding agents (like Claude Code) how to build, validate, and deploy GitLab CI pipelines from a chant project.
+
+## What are skills?
+
+Skills are structured markdown documents bundled with a lexicon. When an AI agent works in a chant project, it discovers and loads relevant skills automatically — giving it operational knowledge about the deployment workflow without requiring the user to explain each step.
+
+## Installation
+
+When you scaffold a new project with \`chant init --lexicon gitlab\`, the skill is installed to \`.claude/skills/chant-gitlab/SKILL.md\` for automatic discovery by Claude Code.
+
+For existing projects, create the file manually:
+
+\`\`\`
+.claude/
+  skills/
+    chant-gitlab/
+      SKILL.md    # skill content (see below)
+\`\`\`
+
+## Skill: chant-gitlab
+
+The \`chant-gitlab\` skill covers the full deployment lifecycle:
+
+- **Build** — \`chant build src/ --output .gitlab-ci.yml\`
+- **Validate** — \`chant lint src/\` + GitLab CI Lint API
+- **Deploy** — commit and push the generated YAML
+- **Status** — GitLab UI or pipelines API
+- **Retry** — retry failed jobs via UI or API
+- **Cancel** — cancel running pipelines via API
+- **Troubleshooting** — job logs, lint rule codes (WGL001–WGL004), post-synth checks (WGL010, WGL011)
+
+The skill is invocable as a slash command: \`/chant-gitlab\`
+
+## MCP integration
+
+The lexicon also provides MCP (Model Context Protocol) tools and resources that AI agents can use programmatically:
+
+| MCP tool | Description |
+|----------|-------------|
+| \`build\` | Build the chant project |
+| \`lint\` | Run lint rules |
+| \`explain\` | Summarize project resources |
+| \`scaffold\` | Generate starter files |
+| \`search\` | Search available resource types |
+| \`gitlab:diff\` | Compare current build output against previous |
+
+| MCP resource | Description |
+|--------------|-------------|
+| \`resource-catalog\` | JSON list of all supported GitLab CI entity types |
+| \`examples/basic-pipeline\` | Example pipeline with build, test, and deploy jobs |`,
+      },
     ],
     basePath: "/chant/lexicons/gitlab/",
   };

package/src/codegen/package.ts

@@ -3,7 +3,9 @@
  * with GitLab-specific manifest building and skill collection.
  */
 
+import { createRequire } from "module";
 import { readFileSync } from "fs";
+const require = createRequire(import.meta.url);
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import type { IntrinsicDef } from "@intentius/chant/lexicon";

package/src/import/parser.test.ts

@@ -65,7 +65,7 @@ workflow:
     expect(workflow!.properties.name).toBe("My Pipeline");
   });
 
-  test("converts snake_case keys to camelCase", () => {
+  test("preserves spec-native snake_case property keys", () => {
     const yaml = `
 test-job:
   stage: test
@@ -77,8 +77,8 @@ test-job:
     - npm test
 `;
     const ir = parser.parse(yaml);
-    expect(ir.resources[0].properties.beforeScript).toEqual(["echo setup"]);
-    expect(ir.resources[0].properties.afterScript).toEqual(["echo done"]);
+    expect(ir.resources[0].properties.before_script).toEqual(["echo setup"]);
+    expect(ir.resources[0].properties.after_script).toEqual(["echo done"]);
   });
 
   test("converts kebab-case job names to camelCase", () => {

package/src/import/parser.ts

@@ -10,6 +10,14 @@ import type { TemplateParser, TemplateIR, ResourceIR } from "@intentius/chant/im
 /**
  * Reserved top-level keys in .gitlab-ci.yml that are NOT job definitions.
  */
+/**
+ * Convert snake_case to camelCase — used only for TS variable names (logicalId),
+ * NOT for spec property names.
+ */
+function snakeToCamelCase(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
 const RESERVED_KEYS = new Set([
   "stages",
   "variables",
@@ -24,28 +32,6 @@ const RESERVED_KEYS = new Set([
   "pages",
 ]);
 
-/**
- * Map snake_case GitLab CI keys to camelCase for Chant properties.
- */
-function toCamelCase(name: string): string {
-  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
-}
-
-/**
- * Recursively convert snake_case keys in an object to camelCase.
- */
-function camelCaseKeys(value: unknown): unknown {
-  if (value === null || value === undefined) return value;
-  if (Array.isArray(value)) return value.map(camelCaseKeys);
-  if (typeof value === "object") {
-    const result: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
-      result[toCamelCase(key)] = camelCaseKeys(val);
-    }
-    return result;
-  }
-  return value;
-}
 
 /**
  * Parse a YAML document into a plain object.
@@ -227,7 +213,7 @@ export class GitLabParser implements TemplateParser {
       resources.push({
         logicalId: "defaults",
         type: "GitLab::CI::Default",
-        properties: camelCaseKeys(doc.default) as Record<string, unknown>,
+        properties: doc.default as Record<string, unknown>,
       });
     }
 
@@ -236,7 +222,7 @@ export class GitLabParser implements TemplateParser {
       resources.push({
         logicalId: "workflow",
         type: "GitLab::CI::Workflow",
-        properties: camelCaseKeys(doc.workflow) as Record<string, unknown>,
+        properties: doc.workflow as Record<string, unknown>,
       });
     }
 
@@ -256,9 +242,9 @@ export class GitLabParser implements TemplateParser {
         obj.needs !== undefined
       ) {
         resources.push({
-          logicalId: toCamelCase(key.replace(/-/g, "_")),
+          logicalId: snakeToCamelCase(key.replace(/-/g, "_")),
           type: "GitLab::CI::Job",
-          properties: camelCaseKeys(obj) as Record<string, unknown>,
+          properties: obj as Record<string, unknown>,
           metadata: {
             originalName: key,
             stage: typeof obj.stage === "string" ? obj.stage : undefined,

package/src/lsp/completions.ts

@@ -1,5 +1,7 @@
+import { createRequire } from "module";
 import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/lsp/hover.ts

@@ -1,5 +1,7 @@
+import { createRequire } from "module";
 import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/plugin.test.ts

@@ -159,9 +159,12 @@ describe("gitlabPlugin", () => {
   test("returns skills", () => {
     const skills = gitlabPlugin.skills!();
     expect(skills).toHaveLength(1);
-    expect(skills[0].name).toBe("gitlab-ci");
+    expect(skills[0].name).toBe("chant-gitlab");
     expect(skills[0].description).toBeDefined();
-    expect(skills[0].content).toContain("GitLab CI/CD");
+    expect(skills[0].content).toContain("skill: chant-gitlab");
+    expect(skills[0].content).toContain("user-invocable: true");
+    expect(skills[0].content).toContain("chant build");
+    expect(skills[0].content).toContain("chant lint");
     expect(skills[0].triggers).toHaveLength(2);
     expect(skills[0].examples).toHaveLength(1);
   });
@@ -217,10 +220,6 @@ describe("gitlabPlugin", () => {
     expect(typeof gitlabPlugin.coverage).toBe("function");
   });
 
-  test("has rollback method", () => {
-    expect(typeof gitlabPlugin.rollback).toBe("function");
-  });
-
   test("has docs method", () => {
     expect(typeof gitlabPlugin.docs).toBe("function");
   });

package/src/plugin.ts

@@ -5,7 +5,9 @@
  * for GitLab CI/CD pipelines.
  */
 
+import { createRequire } from "module";
 import type { LexiconPlugin, IntrinsicDef, SkillDefinition } from "@intentius/chant/lexicon";
+const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
 import { gitlabSerializer } from "./serializer";
@@ -169,31 +171,6 @@ export const test = new Job({
     console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
   },
 
-  async rollback(options?: { restore?: string; verbose?: boolean }): Promise<void> {
-    const { listSnapshots, restoreSnapshot } = await import("./codegen/rollback");
-    const { join, dirname } = await import("path");
-    const { fileURLToPath } = await import("url");
-
-    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
-    const snapshotsDir = join(pkgDir, ".snapshots");
-
-    if (options?.restore) {
-      const generatedDir = join(pkgDir, "src", "generated");
-      restoreSnapshot(String(options.restore), generatedDir);
-      console.error(`Restored snapshot: ${options.restore}`);
-    } else {
-      const snapshots = listSnapshots(snapshotsDir);
-      if (snapshots.length === 0) {
-        console.error("No snapshots available.");
-      } else {
-        console.error(`Available snapshots (${snapshots.length}):`);
-        for (const s of snapshots) {
-          console.error(`  ${s.timestamp}  ${s.resourceCount} resources  ${s.path}`);
-        }
-      }
-    }
-  },
-
   mcpTools() {
     return [
       {
@@ -283,45 +260,67 @@ export const deploy = new Job({
   skills(): SkillDefinition[] {
     return [
       {
-        name: "gitlab-ci",
-        description: "GitLab CI/CD best practices and common patterns",
+        name: "chant-gitlab",
+        description: "GitLab CI/CD pipeline management — workflows, patterns, and troubleshooting",
         content: `---
-name: gitlab-ci
-description: GitLab CI/CD best practices and common patterns
+skill: chant-gitlab
+description: Build, validate, and deploy GitLab CI pipelines from a chant project
+user-invocable: true
 ---
 
-# GitLab CI/CD with Chant
-
-## Common Entity Types
-
-- \`Job\` — Pipeline job definition
-- \`Default\` — Default settings inherited by all jobs
-- \`Workflow\` — Pipeline-level configuration
-- \`Artifacts\` — Job artifact configuration
-- \`Cache\` — Cache configuration
-- \`Image\` — Docker image for a job
-- \`Rule\` — Conditional execution rule
-- \`Environment\` — Deployment environment
-- \`Trigger\` — Trigger downstream pipeline
-- \`Include\` — Include external CI configuration
-
-## Predefined Variables
-
-- \`CI.CommitBranch\` — Current branch name
-- \`CI.CommitSha\` — Current commit SHA
-- \`CI.PipelineSource\` — What triggered the pipeline
-- \`CI.ProjectPath\` — Project path (group/project)
-- \`CI.Registry\` — Container registry URL
-- \`CI.MergeRequestIid\` — MR internal ID
-
-## Best Practices
-
-1. **Use stages** — Organize jobs into logical stages (build, test, deploy)
-2. **Cache dependencies** — Cache node_modules, pip packages, etc.
-3. **Use rules** — Prefer \`rules:\` over \`only:/except:\` for conditional execution
-4. **Minimize artifacts** — Only preserve files needed by later stages
-5. **Use includes** — Share common configuration across projects
-6. **Set timeouts** — Prevent stuck jobs from blocking pipelines
+# Deploying GitLab CI Pipelines from Chant
+
+This project defines GitLab CI jobs as TypeScript in \`src/\`. Use these steps to build, validate, and deploy.
+
+## Build the pipeline
+
+\`\`\`bash
+chant build src/ --output .gitlab-ci.yml
+\`\`\`
+
+## Validate before pushing
+
+\`\`\`bash
+chant lint src/
+\`\`\`
+
+For API-level validation against your GitLab instance:
+\`\`\`bash
+curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \\
+  "https://gitlab.com/api/v4/ci/lint" \\
+  --data "{\\"content\\": \\"$(cat .gitlab-ci.yml)\\"}"
+\`\`\`
+
+## Deploy
+
+Commit and push the generated \`.gitlab-ci.yml\` — GitLab runs the pipeline automatically:
+
+\`\`\`bash
+chant build src/ --output .gitlab-ci.yml
+git add .gitlab-ci.yml
+git commit -m "Update pipeline"
+git push
+\`\`\`
+
+## Check pipeline status
+
+- GitLab UI: project → CI/CD → Pipelines
+- API: \`curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines?per_page=5"\`
+
+## Retry a failed job
+
+- GitLab UI: click Retry on the failed job
+- API: \`curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/retry"\`
+
+## Cancel a running pipeline
+
+- API: \`curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/cancel"\`
+
+## Troubleshooting
+
+- Check job logs in GitLab UI: project → CI/CD → Jobs → click the job
+- \`chant lint src/\` catches: missing scripts (WGL002), deprecated only/except (WGL001), missing stages (WGL003), artifacts without expiry (WGL004)
+- Post-synth checks (WGL010, WGL011) run during build
 `,
         triggers: [
           { type: "file-pattern", value: "**/*.gitlab.ts" },

package/src/serializer.test.ts

@@ -121,12 +121,12 @@ describe("gitlabSerializer.serialize", () => {
     expect(output).toContain("my-test-job:");
   });
 
-  test("converts camelCase property keys to snake_case", () => {
+  test("passes through spec-native snake_case property keys", () => {
     const entities = new Map<string, Declarable>();
     entities.set("job", new MockJob({
-      beforeScript: ["echo hello"],
-      afterScript: ["echo done"],
-      expireIn: "1 week",
+      before_script: ["echo hello"],
+      after_script: ["echo done"],
+      expire_in: "1 week",
     }));
 
     const output = gitlabSerializer.serialize(entities);
@@ -270,7 +270,7 @@ describe("nested objects and arrays", () => {
 
     const output = gitlabSerializer.serialize(entities);
     expect(output).toContain("variables:");
-    expect(output).toContain("node_env: production");
+    expect(output).toContain("NODE_ENV: production");
   });
 
   test("serializes arrays of strings", () => {
@@ -289,7 +289,7 @@ describe("nested objects and arrays", () => {
     const entities = new Map<string, Declarable>();
     entities.set("job", new MockJob({
       interruptible: true,
-      allowFailure: false,
+      allow_failure: false,
     }));
 
     const output = gitlabSerializer.serialize(entities);

package/src/serializer.ts

@@ -14,13 +14,6 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 
-/**
- * Convert camelCase or PascalCase to snake_case.
- */
-function toSnakeCase(name: string): string {
-  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
-}
-
 /**
  * GitLab CI visitor for the generic serializer walker.
  */
@@ -36,12 +29,11 @@ function gitlabVisitor(entityNames: Map<Declarable, string>): SerializerVisitor
       const result: Record<string, unknown> = {};
       for (const [key, value] of Object.entries(props)) {
         if (value !== undefined) {
-          result[toSnakeCase(key)] = walk(value);
+          result[key] = walk(value);
         }
       }
       return Object.keys(result).length > 0 ? result : undefined;
     },
-    transformKey: toSnakeCase,
   };
 }
 

package/dist/skills/gitlab-ci.md

@@ -1,37 +0,0 @@
----
-name: gitlab-ci
-description: GitLab CI/CD best practices and common patterns
----
-
-# GitLab CI/CD with Chant
-
-## Common Entity Types
-
-- `Job` — Pipeline job definition
-- `Default` — Default settings inherited by all jobs
-- `Workflow` — Pipeline-level configuration
-- `Artifacts` — Job artifact configuration
-- `Cache` — Cache configuration
-- `Image` — Docker image for a job
-- `Rule` — Conditional execution rule
-- `Environment` — Deployment environment
-- `Trigger` — Trigger downstream pipeline
-- `Include` — Include external CI configuration
-
-## Predefined Variables
-
-- `CI.CommitBranch` — Current branch name
-- `CI.CommitSha` — Current commit SHA
-- `CI.PipelineSource` — What triggered the pipeline
-- `CI.ProjectPath` — Project path (group/project)
-- `CI.Registry` — Container registry URL
-- `CI.MergeRequestIid` — MR internal ID
-
-## Best Practices
-
-1. **Use stages** — Organize jobs into logical stages (build, test, deploy)
-2. **Cache dependencies** — Cache node_modules, pip packages, etc.
-3. **Use rules** — Prefer `rules:` over `only:/except:` for conditional execution
-4. **Minimize artifacts** — Only preserve files needed by later stages
-5. **Use includes** — Share common configuration across projects
-6. **Set timeouts** — Prevent stuck jobs from blocking pipelines

package/src/codegen/rollback.ts

@@ -1,26 +0,0 @@
-/**
- * Rollback and snapshot management for GitLab CI lexicon.
- *
- * Wraps the core rollback module with GitLab-specific artifact names.
- */
-
-export type { ArtifactSnapshot, SnapshotInfo } from "@intentius/chant/codegen/rollback";
-export {
-  snapshotArtifacts,
-  saveSnapshot,
-  restoreSnapshot,
-  listSnapshots,
-} from "@intentius/chant/codegen/rollback";
-
-/**
- * GitLab-specific artifact filenames to snapshot.
- */
-export const GITLAB_ARTIFACT_NAMES = ["lexicon-gitlab.json", "index.d.ts", "index.ts"];
-
-/**
- * Snapshot GitLab lexicon artifacts.
- */
-export function snapshotGitLabArtifacts(generatedDir: string) {
-  const { snapshotArtifacts } = require("@intentius/chant/codegen/rollback");
-  return snapshotArtifacts(generatedDir, GITLAB_ARTIFACT_NAMES);
-}