@intentius/chant-lexicon-docker 0.124.21 → 0.124.23

package/dist/skills/chant-docker.md

@@ -39,15 +39,21 @@ export const nfsdata = new Volume({ driver: "local", driver_opts: { type: "nfs",
 
 ## Dockerfile — generates Dockerfile.{name}:
 
+Each stage is `from` plus `steps`. A step is an object with one key naming one instruction. Steps are written exactly in the order listed.
+
 ```typescript
-// Single-stage:
-export const builder = new Dockerfile({
+// Single stage. Manifests before source, so the install layer is cached; root setup before USER.
+export const server = new Dockerfile({
   from: "node:20-alpine",
-  workdir: "/app",
-  copy: ["package*.json ./"],
-  run: ["npm ci --only=production"],
-  user: "node",
-  cmd: `["node", "dist/index.js"]`,
+  steps: [
+    { workdir: "/app" },
+    { copy: "package.json package-lock.json ./" },
+    { run: "npm ci --omit=dev" },
+    { copy: "src/ ./src/" },
+    { user: "node" },
+    { expose: 3000 },
+    { cmd: ["node", "src/index.js"] },  // a list is written in JSON exec form
+  ],
 });
 
 // Multi-stage build:
@@ -56,21 +62,37 @@ export const app = new Dockerfile({
     {
       from: "node:20-alpine",
       as: "build",
-      workdir: "/app",
-      copy: ["package*.json ./"],
-      run: ["npm ci", "npm run build"],
+      steps: [
+        { workdir: "/app" },
+        { copy: "package.json package-lock.json ./" },
+        { run: "npm ci" },
+        { copy: ". ." },
+        { run: "npm run build" },
+        { run: "npm prune --omit=dev" },
+      ],
     },
     {
       from: "node:20-alpine",
-      workdir: "/app",
-      copy: ["--from=build /app/dist ./dist", "--from=build /app/node_modules ./node_modules"],
-      user: "node",
-      cmd: `["node", "dist/index.js"]`,
+      steps: [
+        { workdir: "/app" },
+        { copy: "--from=build /app/node_modules ./node_modules" },
+        { copy: "--from=build /app/dist ./dist" },
+        { user: "node" },
+        { cmd: ["node", "dist/index.js"] },
+      ],
     },
   ],
 });
 ```
 
+Step keys: `arg`, `env`, `workdir`, `user`, `run`, `copy`, `add`, `expose`, `volume`, `label`, `entrypoint`, `cmd`, `healthcheck`, `shell`, `stopsignal`, `onbuild`. `from` and `as` are stage fields, and `globalArgs: ["NAME=value"]` writes `ARG` lines before the first `FROM`. `run`, `cmd`, `entrypoint` and `shell` take a string or a list (exec form); `expose` takes a number too.
+
+Rules:
+- Use `steps`. The older per-kind fields (`run: [...]`, `copy: [...]`, `user`) are written in a fixed order (ARG, ENV, WORKDIR, USER, RUN, COPY, ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK), not the order written, so every RUN lands before every COPY. Lint rule DKRS002 flags this, and `chant lint --fix` rewrites them as steps.
+- A stage can't have both `steps` and per-kind fields, and a step can't name two instructions. Both are build errors.
+- Props are type-checked: `Dockerfile` takes `DockerfileProps` and the Compose constructors take `ServiceProps`, `VolumeProps`, `NetworkProps`, `DockerConfigProps` and `DockerSecretProps`. A misspelled key or a wrong value type is a TypeScript error, so run `tsc` (or read the editor's errors) before `chant build`.
+- To share stages or steps between Dockerfiles in different modules, export a `const` stage (`DockerfileStage`) or step list (`DockerfileStep[]`) and import it. List the stage in `stages`, or spread the steps: `steps: [...nodeRuntime, { cmd: ["node", "dist/server.js"] }]`. This is chant's equivalent of an INCLUDE. Spreading a function call's result is a lint error (EVL004); put parameterized Dockerfiles in a `Composite`.
+
 ## Variable interpolation with env():
 
 ```typescript
@@ -112,7 +134,10 @@ export const api = new Service({
   },
   ports: ["8080:8080"],
 });
-export const builder = new Dockerfile({ from: "node:20-alpine", ... });
+export const builder = new Dockerfile({
+  from: "node:20-alpine",
+  steps: [{ workdir: "/app" }, { copy: ". ." }, { run: "npm ci" }, { user: "node" }, { cmd: ["node", "index.js"] }],
+});
 ```
 
 ## Output structure
@@ -126,4 +151,6 @@ export const builder = new Dockerfile({ from: "node:20-alpine", ... });
 - `DKRD001`: Post-synth: no `:latest` images in generated YAML
 - `DKRD002`: Post-synth: no unused named volumes
 - `DKRD003`: Post-synth: SSH port 22 not exposed externally
-- `DKRD010–012`: Dockerfile best practices (apt recommends, COPY vs ADD, USER)
+- `DKRS002`: Dockerfile per-kind fields declared in an order the fixed order changes; use `steps`
+- `DKRD010–012`: Dockerfile best practices (apt recommends, COPY vs ADD, final stage USER)
+- `DKRD013–020`: order-aware Dockerfile checks: COPY . before a dependency install, root-only RUN after USER, repeated CMD/ENTRYPOINT, COPY --from an undefined stage, unused ARG before FROM, relative WORKDIR, ADD of a URL without --checksum, apt-get update in its own RUN

package/dist/spec/parse-compose.d.ts

@@ -19,9 +19,36 @@ export interface ComposeProperty {
     required?: boolean;
     enum?: string[];
 }
+/**
+ * The TypeScript type of a Compose string slot. Compose interpolates every
+ * value, so `env()` fits where a string does; an entity (a service, network,
+ * volume, config, secret or Dockerfile) is written as its name.
+ */
+export declare const COMPOSE_STRING = "ComposeString";
+interface JsonSchema {
+    $ref?: string;
+    type?: string | string[];
+    description?: string;
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, JsonSchema>;
+    patternProperties?: Record<string, JsonSchema>;
+    additionalProperties?: boolean | JsonSchema;
+    required?: string[];
+    items?: JsonSchema;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+}
 /**
  * Parse the Compose Spec JSON Schema buffer into ParsedResult entries.
- * Returns one entry per top-level Compose resource type.
+ * Returns one entry per top-level Compose resource type, with a property for
+ * every field the spec defines on it (#3934). Each property's `type` is a
+ * TypeScript type converted from the schema; string slots use
+ * {@link COMPOSE_STRING}.
  */
-export declare function parseComposeSpec(_data: Buffer): ComposeParseResult[];
+export declare function parseComposeSpec(data: Buffer): ComposeParseResult[];
+/** Convert one JSON Schema node to a TypeScript type. `seen` guards $ref cycles. */
+export declare function toTsType(schema: JsonSchema | boolean | undefined, defs: Record<string, JsonSchema>, seen?: Set<string>): string;
+export {};
 //# sourceMappingURL=parse-compose.d.ts.map

package/dist/spec/parse-compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-compose.d.ts","sourceRoot":"","sources":["../../src/spec/parse-compose.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA8FpE"}
+{"version":3,"file":"parse-compose.d.ts","sourceRoot":"","sources":["../../src/spec/parse-compose.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAE9C,UAAU,UAAU;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC/C,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB;AAUD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAenE;AAWD,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAAG,MAAM,CAmD1I"}

package/dist/spec/parse-engine.d.ts

@@ -14,6 +14,15 @@ export interface DockerfileInstruction {
     name: string;
     description?: string;
     multi?: boolean;
+    /**
+     * Only available as a step (`{ shell: ... }` in `steps`), not as a per-kind
+     * field. The per-kind fields keep the set and fixed order they always had.
+     */
+    stepOnly?: boolean;
+    /** As a step, the value may be a JSON exec-form array as well as a string. */
+    execForm?: boolean;
+    /** As a step, the value may be a number as well as a string. */
+    numeric?: boolean;
 }
 /**
  * Parse the Docker Engine API YAML buffer for Dockerfile instruction types.

package/dist/spec/parse-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-engine.d.ts","sourceRoot":"","sources":["../../src/spec/parse-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,qBAAqB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAsBnE"}
+{"version":3,"file":"parse-engine.d.ts","sourceRoot":"","sources":["../../src/spec/parse-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,qBAAqB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAyBnE"}

package/dist/types/index.d.ts

@@ -1,94 +1,397 @@
 // Code generated by chant generate. DO NOT EDIT.
 import type { Declarable } from "@intentius/chant/declarable";
 
+/** An `env()` interpolation, as returned by the lexicon's `env`. */
+interface EnvIntrinsic { toJSON(): string; toString(): string; }
+
+/**
+ * A Compose string value: a string, an `env()` interpolation, or an entity
+ * (service, network, volume, config, secret or Dockerfile), which is written as its name.
+ */
+export type ComposeString = string | EnvIntrinsic | Declarable;
+
+/** A containerized service definition in Docker Compose */
 export interface ServiceProps {
-  image?: string;
-  build?: object;
-  command?: string | string[];
-  entrypoint?: string | string[];
-  environment?: Record<string, string>;
-  ports?: string[];
-  volumes?: string[];
-  networks?: string[];
-  depends_on?: string[] | Record<string, { condition: "service_started" | "service_healthy" | "service_completed_successfully"; restart?: boolean; required?: boolean }>;
-  restart?: string;
-  labels?: Record<string, string>;
-  healthcheck?: object;
-  deploy?: object;
-  secrets?: string[];
-  configs?: Array<string | { source: string | Declarable; target?: string; uid?: string; gid?: string; mode?: number }>;
+  develop?: { watch?: Array<{ ignore?: ComposeString | Array<ComposeString>; include?: ComposeString | Array<ComposeString>; path: ComposeString; action: "rebuild" | "sync" | "restart" | "sync+restart" | "sync+exec"; target?: ComposeString; exec?: { command: null | ComposeString | Array<ComposeString>; user?: ComposeString; privileged?: boolean | ComposeString; working_dir?: ComposeString; environment?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; [key: `x-${string}`]: unknown }; initial_sync?: boolean; [key: `x-${string}`]: unknown }>; [key: `x-${string}`]: unknown } | null;
+  deploy?: { mode?: ComposeString; endpoint_mode?: ComposeString; replicas?: number | ComposeString; labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; rollback_config?: { parallelism?: number | ComposeString; delay?: ComposeString; failure_action?: ComposeString; monitor?: ComposeString; max_failure_ratio?: number | ComposeString; order?: "start-first" | "stop-first"; [key: `x-${string}`]: unknown }; update_config?: { parallelism?: number | ComposeString; delay?: ComposeString; failure_action?: ComposeString; monitor?: ComposeString; max_failure_ratio?: number | ComposeString; order?: "start-first" | "stop-first"; [key: `x-${string}`]: unknown }; resources?: { limits?: { cpus?: number | ComposeString; memory?: ComposeString; pids?: number | ComposeString; [key: `x-${string}`]: unknown }; reservations?: { cpus?: number | ComposeString; memory?: ComposeString; generic_resources?: Array<{ discrete_resource_spec?: { kind?: ComposeString; value?: number | ComposeString; [key: `x-${string}`]: unknown }; [key: `x-${string}`]: unknown }>; devices?: Array<{ capabilities: Array<ComposeString>; count?: ComposeString | number; device_ids?: Array<ComposeString>; driver?: ComposeString; options?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; [key: `x-${string}`]: unknown }>; [key: `x-${string}`]: unknown }; [key: `x-${string}`]: unknown }; restart_policy?: { condition?: ComposeString; delay?: ComposeString; max_attempts?: number | ComposeString; window?: ComposeString; [key: `x-${string}`]: unknown }; placement?: { constraints?: Array<ComposeString>; preferences?: Array<{ spread?: ComposeString; [key: `x-${string}`]: unknown }>; max_replicas_per_node?: number | ComposeString; [key: `x-${string}`]: unknown }; [key: `x-${string}`]: unknown } | null;
+  annotations?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  attach?: boolean | ComposeString;
+  /** Configuration options for building the service's image. */
+  build?: ComposeString | { context?: ComposeString; dockerfile?: ComposeString; dockerfile_inline?: ComposeString; entitlements?: Array<ComposeString>; args?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; ssh?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; cache_from?: Array<ComposeString>; cache_to?: Array<ComposeString>; no_cache?: boolean | ComposeString; no_cache_filter?: ComposeString | Array<ComposeString>; additional_contexts?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; network?: ComposeString; provenance?: ComposeString | boolean; sbom?: ComposeString | boolean; pull?: boolean | ComposeString; target?: ComposeString; shm_size?: number | ComposeString; extra_hosts?: Record<string, ComposeString | Array<ComposeString>> | Array<ComposeString>; isolation?: ComposeString; privileged?: boolean | ComposeString; secrets?: Array<ComposeString | { source?: ComposeString; target?: ComposeString; uid?: ComposeString; gid?: ComposeString; mode?: number | ComposeString; [key: `x-${string}`]: unknown }>; tags?: Array<ComposeString>; ulimits?: Record<string, number | ComposeString | { hard: number | ComposeString; soft: number | ComposeString; [key: `x-${string}`]: unknown }>; platforms?: Array<ComposeString>; [key: `x-${string}`]: unknown };
+  /** Block IO configuration for the service. */
+  blkio_config?: { device_read_bps?: Array<{ path?: ComposeString; rate?: number | ComposeString }>; device_read_iops?: Array<{ path?: ComposeString; rate?: number | ComposeString }>; device_write_bps?: Array<{ path?: ComposeString; rate?: number | ComposeString }>; device_write_iops?: Array<{ path?: ComposeString; rate?: number | ComposeString }>; weight?: number | ComposeString; weight_device?: Array<{ path?: ComposeString; weight?: number | ComposeString }> };
+  /** Add Linux capabilities. For example, 'CAP_SYS_ADMIN', 'SYS_ADMIN', or 'NET_ADMIN'. */
+  cap_add?: Array<ComposeString>;
+  /** Drop Linux capabilities. For example, 'CAP_SYS_ADMIN', 'SYS_ADMIN', or 'NET_ADMIN'. */
+  cap_drop?: Array<ComposeString>;
+  /** Specify the cgroup namespace to join. Use 'host' to use the host's cgroup namespace, or 'private' to use a private cgroup namespace. */
+  cgroup?: "host" | "private";
+  /** Specify an optional parent cgroup for the container. */
+  cgroup_parent?: ComposeString;
+  /** Override the default command declared by the container image, for example 'CMD' in Dockerfile. */
+  command?: null | ComposeString | Array<ComposeString>;
+  /** Grant access to Configs on a per-service basis. */
+  configs?: Array<ComposeString | { source?: ComposeString; target?: ComposeString; uid?: ComposeString; gid?: ComposeString; mode?: number | ComposeString; [key: `x-${string}`]: unknown }>;
+  /** Specify a custom container name, rather than a generated default name. */
+  container_name?: ComposeString;
+  /** Number of usable CPUs. */
+  cpu_count?: ComposeString | number;
+  /** Percentage of CPU resources to use. */
+  cpu_percent?: ComposeString | number;
+  /** CPU shares (relative weight) for the container. */
+  cpu_shares?: number | ComposeString;
+  /** Limit the CPU CFS (Completely Fair Scheduler) quota. */
+  cpu_quota?: number | ComposeString;
+  /** Limit the CPU CFS (Completely Fair Scheduler) period. */
+  cpu_period?: number | ComposeString;
+  /** Limit the CPU real-time period in microseconds or a duration. */
+  cpu_rt_period?: number | ComposeString;
+  /** Limit the CPU real-time runtime in microseconds or a duration. */
+  cpu_rt_runtime?: number | ComposeString;
+  /** Number of CPUs to use. A floating-point value is supported to request partial CPUs. */
+  cpus?: number | ComposeString;
+  /** CPUs in which to allow execution (0-3, 0,1). */
+  cpuset?: ComposeString;
+  /** Configure the credential spec for managed service account. */
+  credential_spec?: { config?: ComposeString; file?: ComposeString; registry?: ComposeString; [key: `x-${string}`]: unknown };
+  /** Express dependency between services. Service dependencies cause services to be started in dependency order. The dependent service will wait for the dependency to be ready before starting. */
+  depends_on?: Array<ComposeString> | Record<string, { restart?: boolean | ComposeString; required?: boolean; condition: "service_started" | "service_healthy" | "service_completed_successfully"; [key: `x-${string}`]: unknown }>;
+  /** Add rules to the cgroup allowed devices list. */
+  device_cgroup_rules?: Array<ComposeString>;
+  /** List of device mappings for the container. */
+  devices?: Array<ComposeString | { source: ComposeString; target?: ComposeString; permissions?: ComposeString; [key: `x-${string}`]: unknown }>;
+  /** Custom DNS servers to set for the service container. */
+  dns?: ComposeString | Array<ComposeString>;
+  /** Custom DNS options to be passed to the container's DNS resolver. */
+  dns_opt?: Array<ComposeString>;
+  /** Custom DNS search domains to set on the service container. */
+  dns_search?: ComposeString | Array<ComposeString>;
+  /** Custom domain name to use for the service container. */
+  domainname?: ComposeString;
+  /** Override the default entrypoint declared by the container image, for example 'ENTRYPOINT' in Dockerfile. */
+  entrypoint?: null | ComposeString | Array<ComposeString>;
+  /** Add environment variables from a file or multiple files. Can be a single file path or a list of file paths. */
+  env_file?: ComposeString | Array<ComposeString | { path: ComposeString; format?: ComposeString; required?: boolean | ComposeString }>;
+  /** Add metadata to containers using files containing Docker labels. */
+  label_file?: ComposeString | Array<ComposeString>;
+  /** Add environment variables. You can use either an array or a list of KEY=VAL pairs. */
+  environment?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** Expose ports without publishing them to the host machine - they'll only be accessible to linked services. */
+  expose?: Array<ComposeString | number>;
+  /** Extend another service, in the current file or another file. */
+  extends?: ComposeString | { service: ComposeString; file?: ComposeString };
+  /** Specify a service which will not be manage by Compose directly, and delegate its management to an external provider. */
+  provider?: { type: ComposeString; options?: Record<string, ComposeString | number | boolean | Array<ComposeString | number | boolean>>; [key: `x-${string}`]: unknown };
+  /** Link to services started outside this Compose application. Specify services as <service_name>:<alias>. */
+  external_links?: Array<ComposeString>;
+  /** Add hostname mappings to the container network interface configuration. */
+  extra_hosts?: Record<string, ComposeString | Array<ComposeString>> | Array<ComposeString>;
+  /** Define GPU devices to use. Can be set to 'all' to use all GPUs, or a list of specific GPU devices. */
+  gpus?: "all" | Array<{ capabilities?: Array<ComposeString>; count?: ComposeString | number; device_ids?: Array<ComposeString>; driver?: ComposeString; options?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString> }>;
+  /** Add additional groups which user inside the container should be member of. */
+  group_add?: Array<ComposeString | number>;
+  /** Configure a health check for the container to monitor its health status. */
+  healthcheck?: { disable?: boolean | ComposeString; interval?: ComposeString; retries?: number | ComposeString; test?: ComposeString | Array<ComposeString>; timeout?: ComposeString; start_period?: ComposeString; start_interval?: ComposeString; [key: `x-${string}`]: unknown };
+  /** Define a custom hostname for the service container. */
+  hostname?: ComposeString;
+  /** Specify the image to start the container from. Can be a repository/tag, a digest, or a local image ID. */
+  image?: ComposeString;
+  /** Run as an init process inside the container that forwards signals and reaps processes. */
+  init?: boolean | ComposeString;
+  /** IPC sharing mode for the service container. Use 'host' to share the host's IPC namespace, 'service:[service_name]' to share with another service, or 'shareable' to allow other services to share this service's IPC namespace. */
+  ipc?: ComposeString;
+  /** Container isolation technology to use. Supported values are platform-specific. */
+  isolation?: ComposeString;
+  /** Add metadata to containers using Docker labels. You can use either an array or a list. */
+  labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** Link to containers in another service. Either specify both the service name and a link alias (SERVICE:ALIAS), or just the service name. */
+  links?: Array<ComposeString>;
+  /** Logging configuration for the service. */
+  logging?: { driver?: ComposeString; options?: Record<string, ComposeString | number | null>; [key: `x-${string}`]: unknown };
+  /** Container MAC address to set. */
+  mac_address?: ComposeString;
+  /** Memory limit for the container. A string value can use suffix like '2g' for 2 gigabytes. */
+  mem_limit?: number | ComposeString;
+  /** Memory reservation for the container. */
+  mem_reservation?: ComposeString | number;
+  /** Container memory swappiness as percentage (0 to 100). */
+  mem_swappiness?: number | ComposeString;
+  /** Amount of memory the container is allowed to swap to disk. Set to -1 to enable unlimited swap. */
+  memswap_limit?: number | ComposeString;
+  /** Network mode. Values can be 'bridge', 'host', 'none', 'service:[service name]', or 'container:[container name]'. */
+  network_mode?: ComposeString;
+  /** AI Models to use, referencing entries under the top-level models key. */
+  models?: Array<ComposeString> | Record<string, { endpoint_var?: ComposeString; model_var?: ComposeString; [key: `x-${string}`]: unknown } | null>;
+  /** Networks to join, referencing entries under the top-level networks key. Can be a list of network names or a mapping of network name to network configuration. */
+  networks?: Array<ComposeString> | Record<string, { aliases?: Array<ComposeString>; interface_name?: ComposeString; ipv4_address?: ComposeString; ipv6_address?: ComposeString; link_local_ips?: Array<ComposeString>; mac_address?: ComposeString; driver_opts?: Record<string, ComposeString | number>; priority?: number; gw_priority?: number; [key: `x-${string}`]: unknown } | null>;
+  /** Disable OOM Killer for the container. */
+  oom_kill_disable?: boolean | ComposeString;
+  /** Tune host's OOM preferences for the container (accepts -1000 to 1000). */
+  oom_score_adj?: ComposeString | number;
+  /** PID mode for container. */
+  pid?: ComposeString | null;
+  /** Tune a container's PIDs limit. Set to -1 for unlimited PIDs. */
+  pids_limit?: number | ComposeString;
+  /** Target platform to run on, e.g., 'linux/amd64', 'linux/arm64', or 'windows/amd64'. */
+  platform?: ComposeString;
+  /** Expose container ports. Short format ([HOST:]CONTAINER[/PROTOCOL]). */
+  ports?: Array<number | ComposeString | { name?: ComposeString; mode?: ComposeString; host_ip?: ComposeString; target?: number | ComposeString; published?: ComposeString | number; protocol?: ComposeString; app_protocol?: ComposeString; [key: `x-${string}`]: unknown }>;
+  /** Init containers to run to completion before the service container is started. Each step runs in its own ephemeral container, in declared order; a non-zero exit fails the bring-up of the service and its dependents. */
+  pre_start?: Array<{ command?: null | ComposeString | Array<ComposeString>; image?: ComposeString; user?: ComposeString; privileged?: boolean | ComposeString; working_dir?: ComposeString; environment?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; per_replica?: boolean | ComposeString; [key: `x-${string}`]: unknown }>;
+  /** Commands to run after the container starts. If any command fails, the container stops. */
+  post_start?: Array<{ command: null | ComposeString | Array<ComposeString>; user?: ComposeString; privileged?: boolean | ComposeString; working_dir?: ComposeString; environment?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; [key: `x-${string}`]: unknown }>;
+  /** Commands to run before the container stops. If any command fails, the container stop is aborted. */
+  pre_stop?: Array<{ command: null | ComposeString | Array<ComposeString>; user?: ComposeString; privileged?: boolean | ComposeString; working_dir?: ComposeString; environment?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; [key: `x-${string}`]: unknown }>;
+  /** Give extended privileges to the service container. */
+  privileged?: boolean | ComposeString;
+  /** List of profiles for this service. When profiles are specified, services are only started when the profile is activated. */
+  profiles?: Array<ComposeString>;
+  /** Policy for pulling images. Options include: 'always', 'never', 'if_not_present', 'missing', 'build', or time-based refresh policies. */
+  pull_policy?: ComposeString;
+  /** Time after which to refresh the image. Used with pull_policy=refresh. */
+  pull_refresh_after?: ComposeString;
+  /** Mount the container's filesystem as read only. */
+  read_only?: boolean | ComposeString;
+  /** Restart policy for the service container. Options include: 'no', 'always', 'on-failure', and 'unless-stopped'. */
+  restart?: ComposeString;
+  /** Runtime to use for this container, e.g., 'runc'. */
+  runtime?: ComposeString;
+  /** Number of containers to deploy for this service. */
+  scale?: number | ComposeString;
+  /** Override the default labeling scheme for each container. */
+  security_opt?: Array<ComposeString>;
+  /** Size of /dev/shm. A string value can use suffix like '2g' for 2 gigabytes. */
+  shm_size?: number | ComposeString;
+  /** Grant access to Secrets on a per-service basis. */
+  secrets?: Array<ComposeString | { source?: ComposeString; target?: ComposeString; uid?: ComposeString; gid?: ComposeString; mode?: number | ComposeString; [key: `x-${string}`]: unknown }>;
+  /** Kernel parameters to set in the container. You can use either an array or a list. */
+  sysctls?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** Keep STDIN open even if not attached. */
+  stdin_open?: boolean | ComposeString;
+  /** Time to wait for the container to stop gracefully before sending SIGKILL (e.g., '1s', '1m30s'). */
+  stop_grace_period?: ComposeString;
+  /** Signal to stop the container (e.g., 'SIGTERM', 'SIGINT'). */
+  stop_signal?: ComposeString;
+  /** Storage driver options for the container. */
+  storage_opt?: Record<string, unknown>;
+  /** Mount a temporary filesystem (tmpfs) into the container. Can be a single value or a list. */
+  tmpfs?: ComposeString | Array<ComposeString>;
+  /** Allocate a pseudo-TTY to service container. */
+  tty?: boolean | ComposeString;
+  /** Override the default ulimits for a container. */
+  ulimits?: Record<string, number | ComposeString | { hard: number | ComposeString; soft: number | ComposeString; [key: `x-${string}`]: unknown }>;
+  /** Bind mount Docker API socket and required auth. */
+  use_api_socket?: boolean;
+  /** Username or UID to run the container process as. */
+  user?: ComposeString;
+  /** UTS namespace to use. 'host' shares the host's UTS namespace. */
+  uts?: ComposeString;
+  /** User namespace to use. 'host' shares the host's user namespace. */
+  userns_mode?: ComposeString;
+  /** Mount host paths or named volumes accessible to the container. Short syntax (VOLUME:CONTAINER_PATH[:MODE]) */
+  volumes?: Array<ComposeString | { type: "bind" | "volume" | "tmpfs" | "cluster" | "npipe" | "image"; source?: ComposeString; target?: ComposeString; read_only?: boolean | ComposeString; consistency?: ComposeString; bind?: { propagation?: ComposeString; create_host_path?: boolean | ComposeString; recursive?: "enabled" | "disabled" | "writable" | "readonly"; selinux?: "z" | "Z"; [key: `x-${string}`]: unknown }; volume?: { labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>; nocopy?: boolean | ComposeString; subpath?: ComposeString; [key: `x-${string}`]: unknown }; tmpfs?: { size?: number | ComposeString; mode?: number | ComposeString; [key: `x-${string}`]: unknown }; image?: { subpath?: ComposeString; [key: `x-${string}`]: unknown }; [key: `x-${string}`]: unknown }>;
+  /** Mount volumes from another service or container. Optionally specify read-only access (ro) or read-write (rw). */
+  volumes_from?: Array<ComposeString>;
+  /** The working directory in which the entrypoint or command will be run */
+  working_dir?: ComposeString;
 }
-export declare const Service: new (props?: ServiceProps) => Declarable;
 
+/** A named volume definition in Docker Compose */
 export interface VolumeProps {
-  driver?: string;
-  driver_opts?: Record<string, string>;
-  external?: boolean;
-  labels?: Record<string, string>;
-  name?: string;
+  /** Custom name for this volume. */
+  name?: ComposeString;
+  /** Specify which volume driver should be used for this volume. */
+  driver?: ComposeString;
+  /** Specify driver-specific options. */
+  driver_opts?: Record<string, ComposeString | number>;
+  /** Specifies that this volume already exists and was created outside of Compose. */
+  external?: boolean | ComposeString | { name?: ComposeString; [key: `x-${string}`]: unknown };
+  /** Add metadata to the volume using labels. */
+  labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
 }
-export declare const Volume: new (props?: VolumeProps) => Declarable;
 
+/** A network definition in Docker Compose */
 export interface NetworkProps {
-  driver?: string;
-  driver_opts?: Record<string, string>;
-  external?: boolean;
-  labels?: Record<string, string>;
-  internal?: boolean;
-  ipam?: object;
+  /** Custom name for this network. */
+  name?: ComposeString;
+  /** Specify which driver should be used for this network. Default is 'bridge'. */
+  driver?: ComposeString;
+  /** Specify driver-specific options defined as key/value pairs. */
+  driver_opts?: Record<string, ComposeString | number>;
+  /** Custom IP Address Management configuration for this network. */
+  ipam?: { driver?: ComposeString; config?: Array<{ subnet?: ComposeString; ip_range?: ComposeString; gateway?: ComposeString; aux_addresses?: Record<string, ComposeString>; [key: `x-${string}`]: unknown }>; options?: Record<string, ComposeString>; [key: `x-${string}`]: unknown };
+  /** Specifies that this network already exists and was created outside of Compose. */
+  external?: boolean | ComposeString | { name?: ComposeString; [key: `x-${string}`]: unknown };
+  /** Create an externally isolated network. */
+  internal?: boolean | ComposeString;
+  /** Enable IPv4 networking. */
+  enable_ipv4?: boolean | ComposeString;
+  /** Enable IPv6 networking. */
+  enable_ipv6?: boolean | ComposeString;
+  /** If true, standalone containers can attach to this network. */
+  attachable?: boolean | ComposeString;
+  /** Add metadata to the network using labels. */
+  labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
 }
-export declare const Network: new (props?: NetworkProps) => Declarable;
 
+/** A config definition in Docker Compose */
 export interface DockerConfigProps {
-  file?: string;
-  content?: string;
-  external?: boolean;
-  labels?: Record<string, string>;
-  name?: string;
+  /** Custom name for this config. */
+  name?: ComposeString;
+  /** Inline content of the config. */
+  content?: ComposeString;
+  /** Name of an environment variable from which to get the config value. */
+  environment?: ComposeString;
+  /** Path to a file containing the config value. */
+  file?: ComposeString;
+  /** Specifies that this config already exists and was created outside of Compose. */
+  external?: boolean | ComposeString | { name?: ComposeString };
+  /** Add metadata to the config using labels. */
+  labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** Driver to use for templating the config's value. */
+  template_driver?: ComposeString;
 }
-export declare const DockerConfig: new (props?: DockerConfigProps) => Declarable;
 
+/** A secret definition in Docker Compose */
 export interface DockerSecretProps {
-  file?: string;
-  external?: boolean;
-  labels?: Record<string, string>;
-  name?: string;
+  /** Custom name for this secret. */
+  name?: ComposeString;
+  /** Name of an environment variable from which to get the secret value. */
+  environment?: ComposeString;
+  /** Path to a file containing the secret value. */
+  file?: ComposeString;
+  /** Specifies that this secret already exists and was created outside of Compose. */
+  external?: boolean | ComposeString | { name?: ComposeString };
+  /** Add metadata to the secret using labels. */
+  labels?: Record<string, ComposeString | number | boolean | null> | Array<ComposeString>;
+  /** Specify which secret driver should be used for this secret. */
+  driver?: ComposeString;
+  /** Specify driver-specific options. */
+  driver_opts?: Record<string, ComposeString | number>;
+  /** Driver to use for templating the secret's value. */
+  template_driver?: ComposeString;
 }
-export declare const DockerSecret: new (props?: DockerSecretProps) => Declarable;
 
+export declare const Service: new (props?: ServiceProps, attributes?: Record<string, unknown>) => Declarable;
+export declare const Volume: new (props?: VolumeProps, attributes?: Record<string, unknown>) => Declarable;
+export declare const Network: new (props?: NetworkProps, attributes?: Record<string, unknown>) => Declarable;
+export declare const DockerConfig: new (props?: DockerConfigProps, attributes?: Record<string, unknown>) => Declarable;
+export declare const DockerSecret: new (props?: DockerSecretProps, attributes?: Record<string, unknown>) => Declarable;
+
+/** The Dockerfile instructions a step can name. FROM is the stage's own `from` field. */
+export type DockerfileInstructionName = "arg" | "env" | "run" | "copy" | "add" | "workdir" | "user" | "expose" | "volume" | "label" | "entrypoint" | "cmd" | "healthcheck" | "shell" | "stopsignal" | "onbuild";
+type DockerfileStepOf<K extends DockerfileInstructionName, V> = { [P in K]: V } & { [P in Exclude<DockerfileInstructionName, K>]?: never };
+/**
+ * One Dockerfile instruction, named by its single key: `{ run: "npm ci" }` is `RUN npm ci`.
+ * A string[] value (run, cmd, entrypoint, shell) is written in JSON exec form.
+ */
+export type DockerfileStep =
+  /** ARG: Build-time argument */
+  | DockerfileStepOf<"arg", string>
+  /** ENV: Environment variable */
+  | DockerfileStepOf<"env", string>
+  /** RUN: Run a command during build */
+  | DockerfileStepOf<"run", string | string[]>
+  /** COPY: Copy files from build context */
+  | DockerfileStepOf<"copy", string>
+  /** ADD: Add files (supports URLs and archives) */
+  | DockerfileStepOf<"add", string>
+  /** WORKDIR: Set working directory */
+  | DockerfileStepOf<"workdir", string>
+  /** USER: Set user for subsequent instructions */
+  | DockerfileStepOf<"user", string>
+  /** EXPOSE: Document exposed ports */
+  | DockerfileStepOf<"expose", string | number>
+  /** VOLUME: Create mount points */
+  | DockerfileStepOf<"volume", string>
+  /** LABEL: Add metadata labels */
+  | DockerfileStepOf<"label", string>
+  /** ENTRYPOINT: Set the entrypoint executable */
+  | DockerfileStepOf<"entrypoint", string | string[]>
+  /** CMD: Default command arguments */
+  | DockerfileStepOf<"cmd", string | string[]>
+  /** HEALTHCHECK: Health check instruction */
+  | DockerfileStepOf<"healthcheck", string>
+  /** SHELL: Set the shell for shell-form commands (JSON array form) */
+  | DockerfileStepOf<"shell", string | string[]>
+  /** STOPSIGNAL: Signal sent to stop the container */
+  | DockerfileStepOf<"stopsignal", string>
+  /** ONBUILD: Instruction to run when the image is used as a base */
+  | DockerfileStepOf<"onbuild", string>;
+/**
+ * One build stage: FROM, then its instructions.
+ * Without `steps`, the per-kind fields are written in a fixed order: ARG, ENV, WORKDIR, USER, RUN, COPY, ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK.
+ */
 export interface DockerfileStage {
   from: string;
   as?: string;
+  /** Instructions after FROM, written exactly in this order. Can't be combined with the per-kind fields. */
+  steps?: DockerfileStep[];
+  /** ARG as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   arg?: string[];
+  /** ENV as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   env?: string[];
+  /** RUN as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   run?: string[];
+  /** COPY as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   copy?: string[];
+  /** ADD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   add?: string[];
+  /** WORKDIR as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   workdir?: string;
+  /** USER as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   user?: string;
+  /** EXPOSE as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   expose?: string[];
+  /** VOLUME as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   volume?: string[];
+  /** LABEL as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   label?: string[];
+  /** ENTRYPOINT as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   entrypoint?: string;
+  /** CMD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   cmd?: string;
+  /** HEALTHCHECK as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   healthcheck?: string;
 }
+/**
+ * A Dockerfile: `stages` for a multi-stage build, or `from` and the stage fields for one stage.
+ * Without `steps`, the per-kind fields are written in a fixed order: ARG, ENV, WORKDIR, USER, RUN, COPY, ADD, EXPOSE, VOLUME, LABEL, ENTRYPOINT, CMD, HEALTHCHECK.
+ */
 export interface DockerfileProps {
   name?: string;
+  /** ARG instructions written before the first FROM, e.g. `["NODE_VERSION=20"]`. */
+  globalArgs?: string[];
   from?: string;
+  as?: string;
   stages?: DockerfileStage[];
+  /** Instructions after FROM, written exactly in this order. Can't be combined with the per-kind fields. */
+  steps?: DockerfileStep[];
+  /** ARG as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   arg?: string[];
+  /** ENV as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   env?: string[];
+  /** RUN as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   run?: string[];
+  /** COPY as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   copy?: string[];
+  /** ADD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   add?: string[];
+  /** WORKDIR as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   workdir?: string;
+  /** USER as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   user?: string;
+  /** EXPOSE as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   expose?: string[];
+  /** VOLUME as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   volume?: string[];
+  /** LABEL as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   label?: string[];
+  /** ENTRYPOINT as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   entrypoint?: string;
+  /** CMD as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   cmd?: string;
+  /** HEALTHCHECK as a per-kind field, written in the fixed order. Use `steps` to choose the order. */
   healthcheck?: string;
 }
-export declare const Dockerfile: new (props?: DockerfileProps) => Declarable;
+export declare const Dockerfile: new (props?: DockerfileProps, attributes?: Record<string, unknown>) => Declarable;