feat(core): add nix base flavor for generated containers

Author: skulidropek

README.md

@@ -28,6 +28,9 @@ pnpm run docker-git clone https://github.com/agiens/crm/issues/123 --force-env
 
 # Same, but also enable Playwright MCP + Chromium sidecar for Codex
 pnpm run docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright
+
+# Experimental: generate project with Nix-based container flavor
+pnpm run docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --nix
 ```
 
 ## Parallel Issues / PRs
@@ -46,6 +49,16 @@ Agent context for issue workspaces:
 - Global `${CODEX_HOME}/AGENTS.md` includes workspace path + issue/PR context.
 - For `issue-*` workspaces, docker-git creates `${TARGET_DIR}/AGENTS.md` (if missing) with issue context and auto-adds it to `.git/info/exclude`.
 
+## Container Base Flavor (Ubuntu/Nix)
+
+By default, generated projects use an Ubuntu-based Dockerfile (`--base-flavor ubuntu`).
+
+For migration experiments you can switch to Nix-based container setup:
+- `--base-flavor nix`
+- or shorthand `--nix`
+
+This keeps the same docker-git workflow (SSH, compose, entrypoint logic), but installs toolchain packages via `nix profile install` instead of `apt`.
+
 ## Projects Root Layout
 
 The projects root is:

packages/app/src/docker-git/cli/parser-options.ts

@@ -22,6 +22,7 @@ interface ValueOptionSpec {
     | "codexHome"
     | "archivePath"
     | "scrapMode"
+    | "baseFlavor"
     | "label"
     | "token"
     | "scopes"
@@ -50,6 +51,7 @@ const valueOptionSpecs: ReadonlyArray<ValueOptionSpec> = [
   { flag: "--codex-home", key: "codexHome" },
   { flag: "--archive", key: "archivePath" },
   { flag: "--mode", key: "scrapMode" },
+  { flag: "--base-flavor", key: "baseFlavor" },
   { flag: "--label", key: "label" },
   { flag: "--token", key: "token" },
   { flag: "--scopes", key: "scopes" },
@@ -73,6 +75,8 @@ const booleanFlagUpdaters: Readonly<Record<string, (raw: RawOptions) => RawOptio
   "--no-ssh": (raw) => ({ ...raw, openSsh: false }),
   "--force": (raw) => ({ ...raw, force: true }),
   "--force-env": (raw) => ({ ...raw, forceEnv: true }),
+  "--nix": (raw) => ({ ...raw, baseFlavor: "nix" }),
+  "--ubuntu": (raw) => ({ ...raw, baseFlavor: "ubuntu" }),
   "--mcp-playwright": (raw) => ({ ...raw, enableMcpPlaywright: true }),
   "--no-mcp-playwright": (raw) => ({ ...raw, enableMcpPlaywright: false }),
   "--wipe": (raw) => ({ ...raw, wipe: true }),
@@ -98,6 +102,7 @@ const valueFlagUpdaters: { readonly [K in ValueKey]: (raw: RawOptions, value: st
   codexHome: (raw, value) => ({ ...raw, codexHome: value }),
   archivePath: (raw, value) => ({ ...raw, archivePath: value }),
   scrapMode: (raw, value) => ({ ...raw, scrapMode: value }),
+  baseFlavor: (raw, value) => ({ ...raw, baseFlavor: value }),
   label: (raw, value) => ({ ...raw, label: value }),
   token: (raw, value) => ({ ...raw, token: value }),
   scopes: (raw, value) => ({ ...raw, scopes: value }),

packages/app/src/docker-git/cli/usage.ts

@@ -46,6 +46,8 @@ Options:
   --env-project <path>      Host path to project env file (default: ./.orch/env/project.env)
   --codex-auth <path>       Host path for Codex auth cache (default: <projectsRoot>/.orch/auth/codex)
   --codex-home <path>       Container path for Codex auth (default: /home/dev/.codex)
+  --base-flavor <flavor>    Container base/toolchain flavor: ubuntu|nix (default: ubuntu)
+  --nix | --ubuntu          Shorthand for --base-flavor nix|ubuntu
   --out-dir <path>          Output directory (default: <projectsRoot>/<org>/<repo>[/issue-<id>|/pr-<id>])
   --project-dir <path>      Project directory for attach (default: .)
   --archive <path>          Scrap snapshot directory (default: .orch/scrap/session)

packages/app/src/docker-git/menu-create.ts

@@ -45,7 +45,15 @@ type CreateReturnContext = CreateContext & {
 }
 
 export const buildCreateArgs = (input: CreateInputs): ReadonlyArray<string> => {
-  const args: Array<string> = ["create", "--repo-url", input.repoUrl, "--secrets-root", input.secretsRoot]
+  const args: Array<string> = [
+    "create",
+    "--repo-url",
+    input.repoUrl,
+    "--secrets-root",
+    input.secretsRoot,
+    "--base-flavor",
+    input.baseFlavor
+  ]
   if (input.repoRef.length > 0) {
     args.push("--repo-ref", input.repoRef)
   }
@@ -114,6 +122,7 @@ export const resolveCreateInputs = (
     repoRef: values.repoRef ?? resolvedRepoRef ?? "main",
     outDir,
     secretsRoot,
+    baseFlavor: values.baseFlavor ?? "ubuntu",
     runUp: values.runUp !== false,
     enableMcpPlaywright: values.enableMcpPlaywright === true,
     force: values.force === true,
@@ -132,6 +141,20 @@ const parseYesDefault = (input: string, fallback: boolean): boolean => {
   return fallback
 }
 
+const parseBaseFlavorDefault = (
+  input: string,
+  fallback: CreateInputs["baseFlavor"]
+): CreateInputs["baseFlavor"] => {
+  const normalized = input.trim().toLowerCase()
+  if (normalized === "nix") {
+    return "nix"
+  }
+  if (normalized === "ubuntu") {
+    return "ubuntu"
+  }
+  return fallback
+}
+
 const applyCreateCommand = (
   state: MenuState,
   create: CreateCommand
@@ -196,6 +219,13 @@ const applyCreateStep = (input: {
       input.nextValues.outDir = input.buffer.length > 0 ? input.buffer : input.currentDefaults.outDir
       return true
     }),
+    Match.when("baseFlavor", () => {
+      input.nextValues.baseFlavor = parseBaseFlavorDefault(
+        input.buffer,
+        input.currentDefaults.baseFlavor
+      )
+      return true
+    }),
     Match.when("runUp", () => {
       input.nextValues.runUp = parseYesDefault(input.buffer, input.currentDefaults.runUp)
       return true

packages/app/src/docker-git/menu-render.ts

@@ -29,6 +29,7 @@ export const renderStepLabel = (step: CreateStep, defaults: CreateInputs): strin
     Match.when("repoUrl", () => "Repo URL"),
     Match.when("repoRef", () => `Repo ref [${defaults.repoRef}]`),
     Match.when("outDir", () => `Output dir [${defaults.outDir}]`),
+    Match.when("baseFlavor", () => `Container base flavor [${defaults.baseFlavor}]`),
     Match.when("runUp", () => `Run docker compose up now? [${defaults.runUp ? "Y" : "n"}]`),
     Match.when(
       "mcpPlaywright",

packages/app/src/docker-git/menu-types.ts

@@ -47,6 +47,7 @@ export type CreateInputs = {
   readonly repoRef: string
   readonly outDir: string
   readonly secretsRoot: string
+  readonly baseFlavor: "ubuntu" | "nix"
   readonly runUp: boolean
   readonly enableMcpPlaywright: boolean
   readonly force: boolean
@@ -57,6 +58,7 @@ export type CreateStep =
   | "repoUrl"
   | "repoRef"
   | "outDir"
+  | "baseFlavor"
   | "runUp"
   | "mcpPlaywright"
   | "force"
@@ -65,6 +67,7 @@ export const createSteps: ReadonlyArray<CreateStep> = [
   "repoUrl",
   "repoRef",
   "outDir",
+  "baseFlavor",
   "runUp",
   "mcpPlaywright",
   "force"

packages/app/tests/docker-git/parser.test.ts

@@ -47,6 +47,7 @@ const expectCreateCommand = (
 const expectCreateDefaults = (command: CreateCommand) => {
   expect(command.config.repoUrl).toBe("https://github.com/org/repo.git")
   expect(command.config.repoRef).toBe(defaultTemplateConfig.repoRef)
+  expect(command.config.baseFlavor).toBe(defaultTemplateConfig.baseFlavor)
   expect(command.outDir).toBe(".docker-git/org/repo")
   expect(command.runUp).toBe(true)
   expect(command.forceEnv).toBe(false)
@@ -113,6 +114,31 @@ describe("parseArgs", () => {
       expect(command.forceEnv).toBe(true)
     }))
 
+  it.effect("parses nix shorthand flag", () =>
+    expectCreateCommand(["clone", "https://github.com/org/repo.git", "--nix"], (command) => {
+      expect(command.config.baseFlavor).toBe("nix")
+    }))
+
+  it.effect("parses explicit base flavor", () =>
+    expectCreateCommand(
+      ["clone", "https://github.com/org/repo.git", "--base-flavor", "ubuntu"],
+      (command) => {
+        expect(command.config.baseFlavor).toBe("ubuntu")
+      }
+    ))
+
+  it.effect("fails on unsupported base flavor value", () =>
+    Effect.sync(() => {
+      Either.match(parseArgs(["clone", "https://github.com/org/repo.git", "--base-flavor", "guix"]), {
+        onLeft: (error) => {
+          expect(error._tag).toBe("InvalidOption")
+        },
+        onRight: () => {
+          throw new Error("expected parse error")
+        }
+      })
+    }))
+
   it.effect("parses GitHub tree url as repo + ref", () =>
     expectCreateCommand(["clone", "https://github.com/agiens/crm/tree/vova-fork"], (command) => {
       expect(command.config.repoUrl).toBe("https://github.com/agiens/crm.git")

packages/docker-git/tests/core/templates.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "@effect/vitest"
 import { Effect } from "effect"
 
-import { planFiles } from "../../src/core/templates.js"
 import { type TemplateConfig } from "../../src/core/domain.js"
+import { planFiles } from "../../src/core/templates.js"
 
 describe("planFiles", () => {
   it.effect("includes docker and config files", () =>
@@ -22,6 +22,7 @@ describe("planFiles", () => {
         codexAuthPath: "./.orch/auth/codex",
         codexSharedAuthPath: "../../.orch/auth/codex",
         codexHome: "/home/dev/.codex",
+        baseFlavor: "ubuntu",
         enableMcpPlaywright: false,
         pnpmVersion: "10.27.0"
       }
@@ -97,6 +98,7 @@ describe("planFiles", () => {
         codexAuthPath: "./.orch/auth/codex",
         codexSharedAuthPath: "../../.orch/auth/codex",
         codexHome: "/home/dev/.codex",
+        baseFlavor: "ubuntu",
         enableMcpPlaywright: true,
         pnpmVersion: "10.27.0"
       }
@@ -113,6 +115,40 @@ describe("planFiles", () => {
       expect(browserScript !== undefined && browserScript._tag === "File").toBe(true)
     }))
 
+  it.effect("renders Nix flavor Dockerfile when requested", () =>
+    Effect.sync(() => {
+      const config: TemplateConfig = {
+        containerName: "dg-test",
+        serviceName: "dg-test",
+        sshUser: "dev",
+        sshPort: 2222,
+        repoUrl: "https://github.com/org/repo.git",
+        repoRef: "main",
+        targetDir: "/home/dev/app",
+        volumeName: "dg-test-home",
+        authorizedKeysPath: "./authorized_keys",
+        envGlobalPath: "./.orch/env/global.env",
+        envProjectPath: "./.orch/env/project.env",
+        codexAuthPath: "./.orch/auth/codex",
+        codexSharedAuthPath: "../../.orch/auth/codex",
+        codexHome: "/home/dev/.codex",
+        baseFlavor: "nix",
+        enableMcpPlaywright: false,
+        pnpmVersion: "10.27.0"
+      }
+
+      const specs = planFiles(config)
+      const dockerfileSpec = specs.find(
+        (spec) => spec._tag === "File" && spec.relativePath === "Dockerfile"
+      )
+      expect(dockerfileSpec !== undefined && dockerfileSpec._tag === "File").toBe(true)
+      if (dockerfileSpec && dockerfileSpec._tag === "File") {
+        expect(dockerfileSpec.contents).toContain("FROM nixos/nix:latest")
+        expect(dockerfileSpec.contents).toContain("nix profile install --profile /nix/var/nix/profiles/default")
+        expect(dockerfileSpec.contents).not.toContain("FROM ubuntu:24.04")
+      }
+    }))
+
   it.effect("embeds issue workspace AGENTS context in entrypoint", () =>
     Effect.sync(() => {
       const config: TemplateConfig = {
@@ -130,6 +166,7 @@ describe("planFiles", () => {
         codexAuthPath: "./.orch/auth/codex",
         codexSharedAuthPath: "../../.orch/auth/codex",
         codexHome: "/home/dev/.codex",
+        baseFlavor: "ubuntu",
         enableMcpPlaywright: false,
         pnpmVersion: "10.27.0"
       }
@@ -169,6 +206,7 @@ describe("planFiles", () => {
         codexAuthPath: "./.orch/auth/codex",
         codexSharedAuthPath: "../../.orch/auth/codex",
         codexHome: "/home/dev/.codex",
+        baseFlavor: "ubuntu",
         enableMcpPlaywright: false,
         pnpmVersion: "10.27.0"
       }

packages/lib/src/core/command-builders.ts

@@ -30,6 +30,20 @@ const parsePort = (value: string): Either.Either<number, ParseError> => {
   return Either.right(parsed)
 }
 
+const parseBaseFlavor = (
+  value: string | undefined
+): Either.Either<"ubuntu" | "nix", ParseError> => {
+  const candidate = value?.trim() ?? defaultTemplateConfig.baseFlavor
+  if (candidate === "ubuntu" || candidate === "nix") {
+    return Either.right(candidate)
+  }
+  return Either.left({
+    _tag: "InvalidOption",
+    option: "--base-flavor",
+    reason: `expected one of: ubuntu, nix (got: ${candidate})`
+  })
+}
+
 export const nonEmpty = (
   option: string,
   value: string | undefined,
@@ -203,6 +217,7 @@ export const buildCreateCommand = (
     const openSsh = raw.openSsh ?? false
     const force = raw.force ?? false
     const forceEnv = raw.forceEnv ?? false
+    const baseFlavor = yield* _(parseBaseFlavor(raw.baseFlavor))
     const enableMcpPlaywright = raw.enableMcpPlaywright ?? false
 
     return {
@@ -229,6 +244,7 @@ export const buildCreateCommand = (
         codexAuthPath: paths.codexAuthPath,
         codexSharedAuthPath: paths.codexSharedAuthPath,
         codexHome: paths.codexHome,
+        baseFlavor,
         enableMcpPlaywright,
         pnpmVersion: defaultTemplateConfig.pnpmVersion
       }

packages/lib/src/core/command-options.ts

@@ -25,6 +25,7 @@ export interface RawOptions {
   readonly envProjectPath?: string
   readonly codexAuthPath?: string
   readonly codexHome?: string
+  readonly baseFlavor?: string
   readonly enableMcpPlaywright?: boolean
   readonly archivePath?: string
   readonly scrapMode?: string