@intentius/chant-lexicon-github 0.118.1 → 0.120.0

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8EH;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B9E"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmHH;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B9E"}

package/dist/codegen/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/codegen/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAEL,kBAAkB,IAAI,sBAAsB,EAG7C,MAAM,sCAAsC,CAAC;AAI9C,YAAY,EAAE,mBAAmB,EAAE,CAAC;AACpC,OAAO,EAAE,sBAAsB,IAAI,kBAAkB,EAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAyFD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAkB9E;AA0gBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/codegen/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAEL,kBAAkB,IAAI,sBAAsB,EAG7C,MAAM,sCAAsC,CAAC;AAI9C,YAAY,EAAE,mBAAmB,EAAE,CAAC;AACpC,OAAO,EAAE,sBAAsB,IAAI,kBAAkB,EAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAyFD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAkB9E;AAkiBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "9af8fb73c9fc467e40ba29223cd21acd9b359cf19abc6da410bc9f398b2d930e",
+    "manifest.json": "b90d05876520e11b56b19a89a89e02b3be6ba6410d8220685e5e2c70a8893868",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
-    "types/index.d.ts": "bdd54a4145a39a9dd4f7bbc8c500191acb6bc9057a87da0040475afac84db397",
+    "types/index.d.ts": "0ead95536e947ddfb98a5acf0ddb88547913b5a53a342df67711c59266f84b3e",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
     "rules/detect-secrets.ts": "5829832eb7b43993424971041ed386b196850183bffd34bddd6439f99061e4ae",
     "rules/extract-inline-structs.ts": "8f8147c200de8ffd0620dfdcca2e2cea76a520303ce431479ebecad6aa26aab5",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "138f25dc6c40d14fd2e8a099cc5823c7fcac2b600cee92cad3ad2cb06049707e"
+  "composite": "9c78bc700120d8f4aa2ea98b522a590fa33de3de88907b30b1080d3cc46a9bbe"
 }

package/dist/manifest.json

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

package/dist/okf/types/Job.md

@@ -12,6 +12,7 @@ resource_type: GitHub::Actions::Job
 
 - `runs-on` (`string | string[]`, required): The type of machine to run the job on. The machine can be either a GitHub-hosted runner, or a self-hosted runner.
 - `cache-mode` (`"read" | "write" | "write-only" | "none"`, optional)
+- `comment` (`string`, optional): YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line
 - `concurrency` (`Concurrency | string`, optional): Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. You can also specify concurrency at the workflow level. When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true.
 - `container` (`Container | string`, optional): A container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts. If you do not set a container, all steps will run directly on the host specified by runs-on unless a step refers to an action configured to run in a container.
 - `continue-on-error` (`boolean`, optional): Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

package/dist/okf/types/ReusableWorkflowCallJob.md

@@ -12,6 +12,7 @@ resource_type: GitHub::Actions::ReusableWorkflowCallJob
 
 - `uses` (`string`, required): The location and version of a reusable workflow file to run as a job, of the form './{path/to}/{localfile}.yml' or '{owner}/{repo}/{path}/{filename}@{ref}'. {ref} can be a SHA, a release tag, or a branch name. Using the commit SHA is the safest for stability and security.
 - `cache-mode` (`"read" | "write" | "write-only" | "none"`, optional)
+- `comment` (`string`, optional): YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line
 - `concurrency` (`string | Record<string, any>`, optional): Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. You can also specify concurrency at the workflow level. When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true.
 - `if` (`boolean | number | string`, optional): You can use the if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional. Expressions in an if conditional do not require the ${{ }} syntax. For more information, see https://help.github.com/en/articles/contexts-and-expression-syntax-for-github-actions.
 - `name` (`string`, optional): The name of the job displayed on GitHub.

package/dist/okf/types/Workflow.md

@@ -13,6 +13,7 @@ resource_type: GitHub::Actions::Workflow
 - `jobs` (`Record<string, unknown>`, required): A workflow run is made up of one or more jobs. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the jobs.<job_id>.needs keyword. Each job runs in a fresh instance of the virtual environment specified by runs-on. You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see https://help.github.com/en/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#usage-limits.
 - `on` (`Record<string, unknown>`, required): The name of the GitHub event that triggers the workflow. You can provide a single event string, array of events, array of event types, or an event configuration map that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see https://help.github.com/en/github/automating-your-workflow-with-github-actions/events-that-trigger-workflows.
 - `cache-mode` (`"read" | "write" | "write-only" | "none"`, optional)
+- `comment` (`string`, optional): YAML comment lines written at the top of the file, above `name:`. Not a workflow key; each line of the string becomes a `#` line
 - `concurrency` (`Concurrency | string`, optional): Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. You can also specify concurrency at the workflow level. When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true.
 - `defaults` (`Defaults`, optional): A map of default settings that will apply to all jobs in the workflow.
 - `env` (`Record<string, string>`, optional): A map of environment variables that are available to all jobs and steps in the workflow.

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AAuNhF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAwD9B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AAsRhF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAwD9B,CAAC"}

package/dist/types/index.d.ts

@@ -23,8 +23,8 @@ export declare class Container {
     env?: Record<string, string>;
     /** Docker options */
     options?: string;
-    /** Exposed ports */
-    ports?: number[];
+    /** Exposed ports: a container port (published on a random host port) or "host:container" */
+    ports?: (number | string)[];
     /** Volume mounts */
     volumes?: string[];
   });
@@ -52,6 +52,8 @@ export declare class Job {
     /** The type of machine to run the job on. The machine can be either a GitHub-hosted runner, or a self-hosted runner. */
     "runs-on": string | string[];
     "cache-mode"?: "read" | "write" | "write-only" | "none";
+    /** YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. 
 You can also specify concurrency at the workflow level. 
 When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. */
@@ -159,6 +161,8 @@ export declare class ReusableWorkflowCallJob {
     /** The location and version of a reusable workflow file to run as a job, of the form './{path/to}/{localfile}.yml' or '{owner}/{repo}/{path}/{filename}@{ref}'. {ref} can be a SHA, a release tag, or a branch name. Using the commit SHA is the safest for stability and security. */
     uses: string;
     "cache-mode"?: "read" | "write" | "write-only" | "none";
+    /** YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. 
 You can also specify concurrency at the workflow level. 
 When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. */
@@ -193,13 +197,16 @@ export declare class Service {
     credentials?: Record<string, string>;
     env?: Record<string, string>;
     options?: string;
-    ports?: number[];
+    /** Exposed ports: a container port (published on a random host port) or "host:container", which a step on the runner reaches at localhost:<host> */
+    ports?: (number | string)[];
     volumes?: string[];
   });
 }
 
 export declare class Step {
   constructor(props: {
+    /** YAML comment lines written above the step. Not a step key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Continue on error */
     "continue-on-error"?: boolean;
     /** Environment variables */
@@ -218,8 +225,8 @@ export declare class Step {
     "timeout-minutes"?: number;
     /** Action reference */
     uses?: string;
-    /** Action inputs */
-    with?: Record<string, string>;
+    /** Action inputs. The runner reads each as a string; a number or boolean renders as written (`fetch-depth: 0`) */
+    with?: Record<string, string | number | boolean>;
     /** Working directory */
     "working-directory"?: string;
   });
@@ -244,6 +251,8 @@ You can run an unlimited number of jobs as long as you are within the workflow u
     /** The name of the GitHub event that triggers the workflow. You can provide a single event string, array of events, array of event types, or an event configuration map that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see https://help.github.com/en/github/automating-your-workflow-with-github-actions/events-that-trigger-workflows. */
     on: Record<string, unknown>;
     "cache-mode"?: "read" | "write" | "write-only" | "none";
+    /** YAML comment lines written at the top of the file, above `name:`. Not a workflow key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. 
 You can also specify concurrency at the workflow level. 
 When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.118.1",
+  "version": "0.120.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.118.1",
+    "@intentius/chant": "^0.120.0",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/docs.ts

@@ -57,6 +57,43 @@ The generated file includes:
 | \`timeoutMinutes: 15\` | \`timeout-minutes: 15\` | camelCase → kebab-case for job properties |
 | \`new Step({ uses: "actions/checkout@v7" })\` | \`- uses: actions/checkout@v7\` | Steps serialize as sequence entries |
 
+## Comments
+
+\`Workflow\`, \`Job\` and \`Step\` take a \`comment\`. It is not a workflow key: the serializer writes it as \`#\` lines, one per line of the string, so the reasons a hand-written workflow keeps as YAML comments stay in the file a reader opens on GitHub. A workflow's comment is the file's header, above \`name:\`; a job's goes above its key and a step's above its \`- \`. The Forgejo lexicon renders the same declarations, so its files carry them too.
+
+\`\`\`typescript
+export const publish = new Workflow({
+  comment: "Publishes on a version tag.\\nKeep the file name: npm's trusted publisher names it.",
+  name: "Publish",
+  on: { push: { tags: ["v*"] } },
+  jobs: {
+    publish: new Job({
+      "runs-on": "ubuntu-latest",
+      steps: [new Step({ comment: "The registry times out now and then; retry once.", run: "npm publish || npm publish" })],
+    }),
+  },
+});
+\`\`\`
+
+\`\`\`yaml
+# Publishes on a version tag.
+# Keep the file name: npm's trusted publisher names it.
+
+name: Publish
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      # The registry times out now and then; retry once.
+      - run: npm publish || npm publish
+\`\`\`
+
 ## Validating locally
 
 The output is standard GitHub Actions YAML. Validate locally with \`act\` or push to GitHub:

package/src/codegen/parse.ts

@@ -175,7 +175,7 @@ function extractEntity(
       resource: {
         typeName: entity.typeName,
         description: entity.description,
-        properties: buildFallbackProperties(entity.typeName),
+        properties: addCommentProperty(entity.typeName, buildFallbackProperties(entity.typeName)),
         attributes: [],
         deprecatedProperties: [],
       },
@@ -197,6 +197,7 @@ function extractEntity(
       }
     }
   }
+  addCommentProperty(entity.typeName, properties);
 
   return {
     resource: {
@@ -490,7 +491,7 @@ const PROPERTY_OVERRIDES: Record<string, Record<string, string>> = {
   },
   "GitHub::Actions::Step": {
     env: "Record<string, string>",
-    with: "Record<string, string>",
+    with: "Record<string, string | number | boolean>",
     "if": "string",
     "timeout-minutes": "number",
     "continue-on-error": "boolean",
@@ -500,6 +501,29 @@ const PROPERTY_OVERRIDES: Record<string, Record<string, string>> = {
   },
 };
 
+// ── Comments ──────────────────────────────────────────────────────
+
+/**
+ * Entities that carry a `comment`: not a workflow key, but `# ...` lines the
+ * serializer writes above the entry (above `name:` for a workflow, the file's
+ * header), so the reasons a hand-written workflow keeps as YAML comments
+ * reach the rendered file (#3667).
+ */
+const COMMENTED_ENTITIES: Record<string, string> = {
+  "GitHub::Actions::Workflow": "YAML comment lines written at the top of the file, above `name:`. Not a workflow key; each line of the string becomes a `#` line",
+  "GitHub::Actions::Job": "YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line",
+  "GitHub::Actions::ReusableWorkflowCallJob": "YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line",
+  "GitHub::Actions::Step": "YAML comment lines written above the step. Not a step key; each line of the string becomes a `#` line",
+};
+
+function addCommentProperty(typeName: string, properties: ParsedProperty[]): ParsedProperty[] {
+  const description = COMMENTED_ENTITIES[typeName];
+  if (description && !properties.some((p) => p.name === "comment")) {
+    properties.push({ name: "comment", tsType: "string", required: false, description, constraints: {} });
+  }
+  return properties;
+}
+
 // ── Fallback properties ───────────────────────────────────────────
 
 /**
@@ -548,7 +572,7 @@ function buildFallbackProperties(typeName: string): ParsedProperty[] {
       { name: "name", tsType: "string", required: false, description: "Step display name" },
       { name: "uses", tsType: "string", required: false, description: "Action reference" },
       { name: "run", tsType: "string", required: false, description: "Shell command" },
-      { name: "with", tsType: "Record<string, string>", required: false, description: "Action inputs" },
+      { name: "with", tsType: "Record<string, string | number | boolean>", required: false, description: "Action inputs. The runner reads each as a string; a number or boolean renders as written (`fetch-depth: 0`)" },
       { name: "env", tsType: "Record<string, string>", required: false, description: "Environment variables" },
       { name: "if", tsType: "string", required: false, description: "Conditional expression" },
       { name: "id", tsType: "string", required: false, description: "Step ID for output references" },
@@ -583,7 +607,7 @@ function buildFallbackProperties(typeName: string): ParsedProperty[] {
       { name: "image", tsType: "string", required: true, description: "Docker image" },
       { name: "credentials", tsType: "Record<string, string>", required: false, description: "Registry credentials" },
       { name: "env", tsType: "Record<string, string>", required: false, description: "Environment variables" },
-      { name: "ports", tsType: "number[]", required: false, description: "Exposed ports" },
+      { name: "ports", tsType: "(number | string)[]", required: false, description: "Exposed ports: a container port (published on a random host port) or \"host:container\"" },
       { name: "volumes", tsType: "string[]", required: false, description: "Volume mounts" },
       { name: "options", tsType: "string", required: false, description: "Docker options" },
     ],
@@ -591,7 +615,7 @@ function buildFallbackProperties(typeName: string): ParsedProperty[] {
       { name: "image", tsType: "string", required: true, description: "Docker image" },
       { name: "credentials", tsType: "Record<string, string>", required: false },
       { name: "env", tsType: "Record<string, string>", required: false },
-      { name: "ports", tsType: "number[]", required: false },
+      { name: "ports", tsType: "(number | string)[]", required: false, description: "Exposed ports: a container port (published on a random host port) or \"host:container\", which a step on the runner reaches at localhost:<host>" },
       { name: "volumes", tsType: "string[]", required: false },
       { name: "options", tsType: "string", required: false },
     ],

package/src/generated/index.d.ts

@@ -23,8 +23,8 @@ export declare class Container {
     env?: Record<string, string>;
     /** Docker options */
     options?: string;
-    /** Exposed ports */
-    ports?: number[];
+    /** Exposed ports: a container port (published on a random host port) or "host:container" */
+    ports?: (number | string)[];
     /** Volume mounts */
     volumes?: string[];
   });
@@ -52,6 +52,8 @@ export declare class Job {
     /** The type of machine to run the job on. The machine can be either a GitHub-hosted runner, or a self-hosted runner. */
     "runs-on": string | string[];
     "cache-mode"?: "read" | "write" | "write-only" | "none";
+    /** YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. 
 You can also specify concurrency at the workflow level. 
 When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. */
@@ -159,6 +161,8 @@ export declare class ReusableWorkflowCallJob {
     /** The location and version of a reusable workflow file to run as a job, of the form './{path/to}/{localfile}.yml' or '{owner}/{repo}/{path}/{filename}@{ref}'. {ref} can be a SHA, a release tag, or a branch name. Using the commit SHA is the safest for stability and security. */
     uses: string;
     "cache-mode"?: "read" | "write" | "write-only" | "none";
+    /** YAML comment lines written above the job's key. Not a job key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. 
 You can also specify concurrency at the workflow level. 
 When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. */
@@ -193,13 +197,16 @@ export declare class Service {
     credentials?: Record<string, string>;
     env?: Record<string, string>;
     options?: string;
-    ports?: number[];
+    /** Exposed ports: a container port (published on a random host port) or "host:container", which a step on the runner reaches at localhost:<host> */
+    ports?: (number | string)[];
     volumes?: string[];
   });
 }
 
 export declare class Step {
   constructor(props: {
+    /** YAML comment lines written above the step. Not a step key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Continue on error */
     "continue-on-error"?: boolean;
     /** Environment variables */
@@ -218,8 +225,8 @@ export declare class Step {
     "timeout-minutes"?: number;
     /** Action reference */
     uses?: string;
-    /** Action inputs */
-    with?: Record<string, string>;
+    /** Action inputs. The runner reads each as a string; a number or boolean renders as written (`fetch-depth: 0`) */
+    with?: Record<string, string | number | boolean>;
     /** Working directory */
     "working-directory"?: string;
   });
@@ -244,6 +251,8 @@ You can run an unlimited number of jobs as long as you are within the workflow u
     /** The name of the GitHub event that triggers the workflow. You can provide a single event string, array of events, array of event types, or an event configuration map that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see https://help.github.com/en/github/automating-your-workflow-with-github-actions/events-that-trigger-workflows. */
     on: Record<string, unknown>;
     "cache-mode"?: "read" | "write" | "write-only" | "none";
+    /** YAML comment lines written at the top of the file, above `name:`. Not a workflow key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. 
 You can also specify concurrency at the workflow level. 
 When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. By default any previously pending job or workflow in the concurrency group will be canceled; this behavior can be changed with `queue`. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. */

package/src/generated-types.test.ts

@@ -0,0 +1,45 @@
+/**
+ * The generated declarations (`src/generated/index.d.ts`) hold a declaration
+ * to what GitHub Actions accepts (#3670). Each snippet is compiled against
+ * them in memory, so a type narrower than the workflow syntax fails here.
+ */
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+
+const DTS = readFileSync(join(import.meta.dirname, "generated", "index.d.ts"), "utf-8");
+
+/** The diagnostics from compiling `body` against the generated declarations. */
+function diagnostics(body: string): string[] {
+  const files: Record<string, string> = {
+    "/gh.d.ts": DTS,
+    "/main.ts": `import { Container, Service, Step } from "./gh";\n${body}\n`,
+  };
+  const options: ts.CompilerOptions = { strict: true, noEmit: true, target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler, types: [], lib: ["lib.es2022.d.ts"] };
+  const host = ts.createCompilerHost(options);
+  const read = host.getSourceFile.bind(host);
+  host.getSourceFile = (name, lang) => (name in files ? ts.createSourceFile(name, files[name], lang) : read(name, lang));
+  host.fileExists = (name) => name in files || ts.sys.fileExists(name);
+  host.readFile = (name) => files[name] ?? ts.sys.readFile(name);
+  const program = ts.createProgram(["/main.ts"], options, host);
+  return ts.getPreEmitDiagnostics(program, program.getSourceFile("/main.ts")).map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
+}
+
+describe("generated types (#3670)", () => {
+  test("Service and Container ports take host:container strings as well as numbers", () => {
+    expect(diagnostics(`
+      new Service({ image: "clickhouse/clickhouse-server:24", ports: ["8123:8123", 9000] });
+      new Container({ image: "node:22", ports: ["3000:3000"] });
+    `)).toEqual([]);
+  });
+
+  test("Step with takes numbers and booleans as well as strings", () => {
+    expect(diagnostics(`new Step({ uses: "actions/checkout@v4", with: { "fetch-depth": 0, lfs: true, ref: "main" } });`)).toEqual([]);
+  });
+
+  test("the declarations still reject what the syntax does not take", () => {
+    expect(diagnostics(`new Service({ image: "x", ports: [{ port: 1 }] });`)).not.toEqual([]);
+    expect(diagnostics(`new Step({ with: { inputs: ["a"] } });`)).not.toEqual([]);
+  });
+});

package/src/serializer.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect } from "vitest";
 import { githubSerializer } from "./serializer";
 import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { parseYAML } from "@intentius/chant/yaml";
 
 // ── Mock entities ──────────────────────────────────────────────────
 
@@ -407,3 +408,82 @@ describe("YAML key ordering", () => {
     expect(envIdx).toBeLessThan(jobsIdx);
   });
 });
+
+describe("ports and step inputs render as written (#3670)", () => {
+  test("a host:container port stays a mapping and a numeric input stays a number", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("workflow", new MockWorkflow({
+      name: "CI",
+      on: { push: null },
+      jobs: {
+        test: new MockJob({
+          "runs-on": "ubuntu-latest",
+          services: { clickhouse: { image: "clickhouse/clickhouse-server:24", ports: ["8123:8123", 9000] } },
+          steps: [new MockStep({ uses: "actions/checkout@v4", with: { "fetch-depth": 0, lfs: true } })],
+        }),
+      },
+    }));
+
+    const output = githubSerializer.serialize(entities) as string;
+    expect(output).toContain("        ports:\n          - '8123:8123'\n          - 9000");
+    expect(output).toContain("        with:\n          fetch-depth: 0\n          lfs: true\n");
+  });
+});
+
+describe("comments (#3667)", () => {
+  const declare = (comments: boolean): Map<string, Declarable> => {
+    const c = <T>(v: T): T | undefined => (comments ? v : undefined);
+    const entities = new Map<string, Declarable>();
+    entities.set("workflow", new MockWorkflow({
+      comment: c("What this workflow is for.\n\nKeep the file name: npm's trusted publisher names it."),
+      name: "Publish",
+      on: { push: { tags: ["v*"] } },
+      jobs: {
+        build: new MockJob({ "runs-on": "ubuntu-latest", steps: [new MockStep({ run: "npm ci" })] }),
+        publish: new MockJob({
+          comment: c("Runs after build; holds the id-token."),
+          "runs-on": "ubuntu-latest",
+          needs: ["build"],
+          steps: [
+            new MockStep({ uses: "actions/checkout@v4" }),
+            new MockStep({ comment: c("The registry is flaky; retry once."), name: "Publish", run: "npm publish || npm publish", env: { NODE_AUTH_TOKEN: "x" } }),
+          ],
+        }),
+      },
+    }));
+    return entities;
+  };
+
+  test("a workflow, job and step comment render as # lines above their entries", () => {
+    const output = githubSerializer.serialize(declare(true)) as string;
+    expect(output.startsWith("# What this workflow is for.\n#\n# Keep the file name: npm's trusted publisher names it.\n\nname: Publish\n")).toBe(true);
+    expect(output).toContain("  # Runs after build; holds the id-token.\n  publish:\n    runs-on: ubuntu-latest\n");
+    expect(output).toContain("      - uses: actions/checkout@v4\n      # The registry is flaky; retry once.\n      - name: Publish\n        run: npm publish || npm publish\n");
+    expect(output).not.toContain("comment:");
+  });
+
+  test("the comments are the only difference, and the YAML parses to the same document", () => {
+    const withComments = githubSerializer.serialize(declare(true)) as string;
+    const without = githubSerializer.serialize(declare(false)) as string;
+    expect(withComments.split("\n").filter((l) => !/^\s*#/.test(l)).join("\n").replace(/^\n/, "")).toBe(without);
+    expect(parseYAML(withComments)).toEqual(parseYAML(without));
+  });
+
+  test("standalone Job and Step entities carry their comments too", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("ci", new MockWorkflow({ comment: "Header", name: "CI", on: { push: null } }));
+    entities.set("test", new MockJob({ comment: "Unit tests", "runs-on": "ubuntu-latest", steps: [new MockStep({ comment: "Why", run: "npm test" })] }));
+    const output = githubSerializer.serialize(entities) as string;
+    expect(output).toContain("# Header\n\nname: CI");
+    expect(output).toContain("jobs:\n  # Unit tests\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      # Why\n      - run: npm test\n");
+  });
+
+  test("each file of a multi-workflow build gets its own header", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("ci", new MockWorkflow({ comment: "CI header", name: "CI", on: { push: null }, jobs: { a: new MockJob({ "runs-on": "x" }) } }));
+    entities.set("release", new MockWorkflow({ comment: "Release header", name: "Release", on: { push: null }, jobs: { b: new MockJob({ "runs-on": "x" }) } }));
+    const result = githubSerializer.serialize(entities) as { primary: string; files: Record<string, string> };
+    expect(result.primary.startsWith("# CI header\n\nname: CI")).toBe(true);
+    expect(result.files["release.yml"].startsWith("# Release header\n\nname: Release")).toBe(true);
+  });
+});

package/src/serializer.ts

@@ -12,7 +12,7 @@ import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
-import { emitYAMLEntry } from "@intentius/chant/yaml";
+import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
 
 // ── Key conversion ────────────────────────────────────────────────
 
@@ -51,6 +51,62 @@ function isTriggerType(entityType: string): boolean {
   return entityType in TRIGGER_TYPE_TO_EVENT;
 }
 
+// ── Comments ──────────────────────────────────────────────────────
+
+/**
+ * Entity types whose `comment` prop is YAML comment lines, not a key (#3667):
+ * the workflow's above `name:`, a job's above its key, a step's above its
+ * `- `. The prop never reaches the emitted mapping.
+ */
+const COMMENTED_TYPES = new Set([
+  "GitHub::Actions::Workflow",
+  "GitHub::Actions::Job",
+  "GitHub::Actions::ReusableWorkflowCallJob",
+  "GitHub::Actions::Step",
+]);
+
+/**
+ * The comment for each serialized job or step mapping, keyed by the object
+ * the emitter will see. Attached after key conversion, which builds new
+ * objects, and read by `emitJobs`.
+ */
+const COMMENTS = new WeakMap<object, string>();
+
+/** The `comment` of a workflow, job or step entity, if it has one. */
+function commentOf(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || !("entityType" in value) || !("props" in value)) return undefined;
+  if (!COMMENTED_TYPES.has((value as { entityType: string }).entityType)) return undefined;
+  const comment = ((value as { props: unknown }).props as Record<string, unknown> | undefined)?.comment;
+  return typeof comment === "string" && comment !== "" ? comment : undefined;
+}
+
+/** `props` without its `comment`, for an entity whose comment is not a key. */
+function withoutComment(props: unknown): unknown {
+  if (!props || typeof props !== "object" || !("comment" in props)) return props;
+  const { comment: _comment, ...rest } = props as Record<string, unknown>;
+  return rest;
+}
+
+/** A comment as `#` lines at `indent` (two spaces each), one per line of the string. */
+function commentLines(comment: string, indent: number): string {
+  const prefix = "  ".repeat(indent);
+  return comment.split("\n").map((l) => `${prefix}#${l.trimEnd() ? ` ${l.trimEnd()}` : ""}`).join("\n");
+}
+
+/** Record a serialized job's comment and its steps' comments, from the job entity it came from. */
+function attachComments(source: unknown, job: Record<string, unknown> | undefined): void {
+  if (!job) return;
+  const comment = commentOf(source);
+  if (comment) COMMENTS.set(job, comment);
+  const rawSteps = (source as { props?: { steps?: unknown } } | undefined)?.props?.steps;
+  if (!Array.isArray(rawSteps) || !Array.isArray(job.steps)) return;
+  rawSteps.forEach((raw, i) => {
+    const stepComment = commentOf(raw);
+    const step = (job.steps as unknown[])[i];
+    if (stepComment && step && typeof step === "object") COMMENTS.set(step, stepComment);
+  });
+}
+
 // ── Visitor ───────────────────────────────────────────────────────
 
 function githubVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
@@ -62,8 +118,10 @@ function githubVisitor(entityNames: Map<Declarable, string>): SerializerVisitor
         return undefined;
       }
       const props = entity.props as Record<string, unknown>;
+      const commented = COMMENTED_TYPES.has(entity.entityType);
       const result: Record<string, unknown> = {};
       for (const [key, value] of Object.entries(props)) {
+        if (commented && key === "comment") continue;
         if (value !== undefined) {
           result[key] = walk(value);
         }
@@ -134,10 +192,12 @@ function serializeInlineJob(
 
   if ("entityType" in obj && "props" in obj && JOB_ENTITY_TYPES.has(obj.entityType as string)) {
     // Job entity: serialize its props inline (not as a resource reference)
-    const props = toYAMLValue(obj.props, entityNames);
-    return props && typeof props === "object"
+    const props = toYAMLValue(withoutComment(obj.props), entityNames);
+    const job = props && typeof props === "object"
       ? convertKeys(props as Record<string, unknown>)
       : undefined;
+    attachComments(obj, job);
+    return job;
   }
 
   // Plain object job definition (JSON-style)
@@ -173,10 +233,13 @@ function buildStandaloneJobsSection(
   const jobsSection: Record<string, unknown> = {};
   for (const [name, job] of jobs) {
     const jProps = toYAMLValue(
-      isResourceDeclarable(job) ? job.props : undefined,
+      withoutComment(isResourceDeclarable(job) ? job.props : undefined),
       entityNames,
     ) as Record<string, unknown> | undefined;
-    if (jProps) jobsSection[toKebabCase(name)] = convertKeys(jProps);
+    if (!jProps) continue;
+    const converted = convertKeys(jProps);
+    attachComments(job, converted);
+    jobsSection[toKebabCase(name)] = converted;
   }
   return Object.keys(jobsSection).length > 0 ? jobsSection : undefined;
 }
@@ -358,7 +421,7 @@ function serializeSingleWorkflow(
   if (!jobsSection) jobsSection = buildStandaloneJobsSection(jobs, entityNames);
   if (jobsSection) doc.jobs = jobsSection;
 
-  return emitYAMLDocument(doc);
+  return emitYAMLDocument(doc, workflows.length > 0 ? commentOf(workflows[0][1]) : undefined);
 }
 
 function serializeMultiWorkflow(
@@ -409,7 +472,7 @@ function serializeMultiWorkflow(
     const jobsSection = inlineJobs ?? (i === 0 ? buildStandaloneJobsSection(jobs, entityNames) : undefined);
     if (jobsSection) doc.jobs = jobsSection;
 
-    const content = emitYAMLDocument(doc);
+    const content = emitYAMLDocument(doc, commentOf(wf));
     if (i === 0) {
       primary = content;
       // primary is written to the -o path by the CLI; don't also add it to files[]
@@ -443,8 +506,9 @@ function convertTriggerProps(on: unknown): unknown {
 /**
  * Emit a complete YAML document from a structured object.
  */
-function emitYAMLDocument(doc: Record<string, unknown>): string {
+function emitYAMLDocument(doc: Record<string, unknown>, header?: string): string {
   const sections: string[] = [];
+  if (header) sections.push(commentLines(header, 0));
 
   // Emit in canonical order: name, run-name, on, permissions, env, concurrency, defaults, jobs
   const order = ["name", "run-name", "on", "permissions", "env", "concurrency", "defaults", "jobs"];
@@ -456,6 +520,8 @@ function emitYAMLDocument(doc: Record<string, unknown>): string {
       const value = doc[key];
       if (value === null) {
         sections.push(`${key}:`);
+      } else if (key === "jobs" && hasComments(value)) {
+        sections.push(emitJobs(value as Record<string, unknown>));
       } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         sections.push(`${key}: ${yamlScalar(value)}`);
       } else {
@@ -477,6 +543,56 @@ function emitYAMLDocument(doc: Record<string, unknown>): string {
   return unquotePinComments(sections.join("\n\n") + "\n");
 }
 
+/** Whether any job in a jobs section, or any of its steps, carries a comment. */
+function hasComments(jobs: unknown): boolean {
+  if (!jobs || typeof jobs !== "object") return false;
+  return Object.values(jobs as Record<string, unknown>).some((job) =>
+    !!job && typeof job === "object" && (COMMENTS.has(job) || stepsOf(job).some((s) => !!s && typeof s === "object" && COMMENTS.has(s))));
+}
+
+const stepsOf = (job: object): unknown[] => {
+  const steps = (job as { steps?: unknown }).steps;
+  return Array.isArray(steps) ? steps : [];
+};
+
+/**
+ * The jobs section with each comment above its job or step. Everything else
+ * is what `emitYAMLEntry("jobs", jobs)` writes: the job at indent 1, its keys
+ * at 2, its step items at 3.
+ */
+function emitJobs(jobs: Record<string, unknown>): string {
+  const lines = ["jobs:"];
+  for (const [name, job] of Object.entries(jobs)) {
+    if (job === undefined) continue;
+    if (!job || typeof job !== "object" || Array.isArray(job)) {
+      lines.push(emitYAMLEntry(name, job, 1));
+      continue;
+    }
+    const comment = COMMENTS.get(job);
+    if (comment) lines.push(commentLines(comment, 1));
+    const steps = stepsOf(job);
+    if (!steps.some((s) => !!s && typeof s === "object" && COMMENTS.has(s))) {
+      lines.push(emitYAMLEntry(name, job, 1));
+      continue;
+    }
+    lines.push(`  ${name}:`);
+    for (const [key, value] of Object.entries(job as Record<string, unknown>)) {
+      if (value === undefined) continue;
+      if (key !== "steps") {
+        lines.push(emitYAMLEntry(key, value, 2));
+        continue;
+      }
+      lines.push("    steps:");
+      for (const step of steps) {
+        const stepComment = step && typeof step === "object" ? COMMENTS.get(step) : undefined;
+        if (stepComment) lines.push(commentLines(stepComment, 3));
+        lines.push(emitYAML([step], 3).slice(1));
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * A SHA-pinned `uses:` carries its version as a trailing comment
  * (`actions/checkout@<sha> # v7.0.1`). The YAML emitter quotes any string with