@rigkit/fragments 0.0.0-canary-20260518T014918-c5bc0c2

package/README.md

@@ -0,0 +1,143 @@
+# @rigkit/fragments
+
+Reusable workflow fragments for Rigkit configs.
+
+The package currently exports `freestyleCompanyBaseFragment` and
+`withFreestyleCompanyBase`, an opinionated global Freestyle base fragment and a
+wrapper that runs a local GitHub auth check after repo-specific setup. The base
+creates a Freestyle VM, installs common development tooling, initializes the
+enabled interactive CLIs, snapshots the VM, and stores that snapshot in Rigkit's
+global fragment cache. Repos can then build their project-specific setup on top
+of the same base snapshot.
+
+Installed by default:
+
+- Git and common build packages
+- GitHub CLI
+- Node.js 22 and npm
+- Bun
+- Codex CLI
+- Claude Code
+
+```ts
+import { freestyle } from "@rigkit/provider-freestyle";
+import {
+  withFreestyleCompanyBase,
+  type FreestyleCompanyBaseFragmentContext,
+} from "@rigkit/fragments";
+import { workflow } from "@rigkit/sdk";
+
+const app = workflow("my-app", {
+  providers: {
+    freestyle: freestyle.provider(),
+    terminal: freestyle.terminal(),
+  },
+});
+
+const repoSetup = app
+  .sequence<FreestyleCompanyBaseFragmentContext>("repo-setup")
+  .task("clone-repo", async ({ freestyle, step }) => {
+    const created = await freestyle.client.vms.create({
+      snapshotId: step.ctx.snapshotId,
+      idleTimeoutSeconds: step.ctx.freestyleCompanyBase.idleTimeoutSeconds,
+      logger: console.log,
+    });
+    const { vm, vmId } = created;
+    try {
+      await vm.exec("git clone https://github.com/acme/app.git /workspace/app");
+      const snapshot = await vm.snapshot();
+      return { ctx: { ...step.ctx, snapshotId: snapshot.snapshotId, repoPath: "/workspace/app" } };
+    } finally {
+      await freestyle.client.vms.delete({ vmId });
+    }
+  });
+
+export default app
+  .sequence("my-app")
+  .add(withFreestyleCompanyBase(repoSetup));
+```
+
+Repos can pass environment-backed overrides when individual developers need to
+choose their own tool set or VM size. See
+`examples/base-freestyle-fragment/rig.config.ts` for that pattern.
+
+`freestyleCompanyBaseFragment(...)` and `withFreestyleCompanyBase(...)`
+intentionally expose a small API: `github`, `codex`, `claude`, and VM sizing.
+Those options are normalized into `.configure(...)`, so they are part of the
+global fragment fingerprint. For example, enabling Claude and disabling Claude
+produce different global cache fragments.
+
+## `withFreestyleCompanyBase` Execution Model
+
+`withFreestyleCompanyBase(repoSetup)` is a wrapper sequence. It does not just
+prepend the base fragment. It also appends a company-owned check after the
+sequence you pass in.
+
+```mermaid
+flowchart LR
+  wrapper["withFreestyleCompanyBase(repoSetup)"]
+  base["1. freestyle-company-base\nbefore: global base snapshot"]
+  repo["2. repoSetup\nyour sequence"]
+  check["3. freestyle-company-base-auth-check\nafter: local uncached check"]
+
+  wrapper --> base
+  base --> repo
+  repo --> check
+```
+
+Conceptually, the wrapper expands to:
+
+```ts
+sequence("with-freestyle-company-base")
+  .add(freestyleCompanyBaseFragment(options))
+  .add(repoSetup)
+  .add(freestyleCompanyBaseAuthCheckFragment(options));
+```
+
+In execution order:
+
+1. `freestyle-company-base` creates or reuses the shared global base snapshot.
+2. `repoSetup` starts from that base snapshot and adds repo-specific state.
+3. `freestyle-company-base-auth-check` runs after repo setup and can invalidate
+   stale global auth before Rigkit finishes the composed workflow.
+
+`withFreestyleCompanyBase(repoSetup)` requires the wrapped setup to preserve
+`freestyleCompanyBase` in its returned ctx. That lets the trailing auth check
+use the base snapshot context after repo-specific setup has added its own
+fields. The supporting TypeScript types are intentionally stricter than a
+minimal fragment: they make ctx preservation a compile-time contract while
+carrying forward any repo-specific ctx fields.
+
+The trailing check currently verifies GitHub with `gh auth status`. If GitHub
+auth is stale, it invalidates the global `github-auth` task and replays the
+wrapped local setup from the refreshed base.
+
+## Advanced Rigkit Use Cases
+
+This wrapper is the advanced part of the example. It is useful when a company
+wants a reusable base fragment that runs before repo setup and still owns checks
+after repo setup. That is a different pattern than asking every repo to add
+fragments one after another in its root sequence.
+
+Use this pattern when a reusable Rigkit fragment needs to:
+
+- sandwich repo setup between company-managed preparation and validation
+- combine global cached setup with local uncached health checks
+- thread a shared ctx contract through repo-specific setup without losing
+  repo-specific fields
+- invalidate an earlier global task from a later local task when credentials
+  or other long-lived state are stale
+- publish a company base fragment that teams can consume without copying the
+  full workflow shape into every repo config
+
+Enabling a tool installs it and runs its auth/init task:
+
+- `github: true` installs GitHub CLI, runs `gh auth login`, and configures Git
+  author identity from the authenticated account.
+- `codex: true` installs Codex CLI and opens `codex` in a Freestyle terminal for
+  login/initialization.
+- `claude: true` installs Claude Code and opens `claude` in a Freestyle terminal
+  for login/initialization.
+
+Authenticated global fragments can contain developer or org credentials. Use
+them only when that is the intended cache boundary.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@rigkit/fragments",
+  "version": "0.0.0-canary-20260518T014918-c5bc0c2",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freestyle-sh/rigkit.git",
+    "directory": "packages/fragments"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rigkit/provider-freestyle": "0.0.0-canary-20260518T014918-c5bc0c2",
+    "@rigkit/sdk": "0.0.0-canary-20260518T014918-c5bc0c2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/freestyleCompanyBaseFragment/index.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from "bun:test";
+import { freestyle } from "@rigkit/provider-freestyle";
+import { workflow } from "@rigkit/sdk";
+import {
+  freestyleCompanyBaseFragment,
+  withFreestyleCompanyBase,
+  type FreestyleCompanyBaseFragmentContext,
+} from "./index.ts";
+
+describe("freestyleCompanyBaseFragment", () => {
+  test("creates a global fragment with resolved tool config", () => {
+    const fragment = freestyleCompanyBaseFragment({
+      claude: false,
+      vm: {
+        home: "/home/runner",
+        memSizeGb: 8,
+      },
+    });
+
+    expect(fragment.name).toBe("freestyle-company-base");
+    expect(fragment.cacheScope).toBe("global");
+    expect(fragment.config).toMatchObject({
+      github: true,
+      codex: true,
+      claude: false,
+      bun: true,
+      nodeMajor: 22,
+      npmPackages: ["@openai/codex"],
+      vm: {
+        home: "/home/runner",
+        idleTimeoutSeconds: 600,
+        memSizeGb: 8,
+        vcpuCount: 4,
+        rootfsSizeGb: 24,
+      },
+    });
+    expect(fragment.config?.systemPackages).toContain("git");
+  });
+
+  test("tool toggles control install and auth tasks together", () => {
+    const fragment = freestyleCompanyBaseFragment({
+      github: false,
+      codex: false,
+      claude: true,
+    });
+
+    expect(fragment.name).toBe("freestyle-company-base");
+    expect(fragment.config).toMatchObject({
+      github: false,
+      codex: false,
+      claude: true,
+      npmPackages: ["@anthropic-ai/claude-code"],
+    });
+  });
+
+  test("composes with a Freestyle workflow and a typed dependent sequence", () => {
+    const app = workflow("example", {
+      providers: {
+        freestyle: freestyle.provider(),
+        terminal: freestyle.terminal(),
+      },
+    });
+
+    const repoSetup = app
+      .sequence<FreestyleCompanyBaseFragmentContext>("repo-setup")
+      .task("repo-ready", async ({ step }) => ({
+        ctx: {
+          ...step.ctx,
+          repoPath: "/workspace/app",
+        },
+      }));
+
+    const root = app
+      .sequence("root")
+      .add(freestyleCompanyBaseFragment({ claude: false }))
+      .add(repoSetup);
+
+    expect(root.children.map((child) => child.name)).toEqual([
+      "freestyle-company-base",
+      "repo-setup",
+    ]);
+  });
+
+  test("wraps a dependent sequence with the base fragment and auth check", () => {
+    const app = workflow("wrapped-example", {
+      providers: {
+        freestyle: freestyle.provider(),
+        terminal: freestyle.terminal(),
+      },
+    });
+
+    const repoSetup = app
+      .sequence<FreestyleCompanyBaseFragmentContext>("repo-setup")
+      .task("repo-ready", async ({ step }) => ({
+        ctx: {
+          ...step.ctx,
+          repoPath: "/workspace/app",
+        },
+      }));
+
+    const wrapped = withFreestyleCompanyBase(repoSetup, { claude: false });
+
+    expect(wrapped.name).toBe("with-freestyle-company-base");
+    expect(wrapped.nodeKind).toBe("sequence");
+    expect((wrapped as any).children.map((child: { name: string }) => child.name)).toEqual([
+      "freestyle-company-base",
+      "repo-setup",
+      "freestyle-company-base-auth-check",
+    ]);
+  });
+});
+
+if (false) {
+  const app = workflow("wrapped-typecheck", {
+    providers: {
+      freestyle: freestyle.provider(),
+      terminal: freestyle.terminal(),
+    },
+  });
+
+  const preservingSetup = app
+    .sequence<FreestyleCompanyBaseFragmentContext>("preserving-setup")
+    .task("preserve", async ({ step }) => ({
+      ctx: {
+        ...step.ctx,
+        repoPath: "/workspace/app",
+      },
+    }));
+  withFreestyleCompanyBase(preservingSetup);
+
+  const droppingSetup = app
+    .sequence<FreestyleCompanyBaseFragmentContext>("dropping-setup")
+    .task("drop", async () => ({
+      ctx: {
+        repoPath: "/workspace/app",
+      },
+    }));
+
+  // @ts-expect-error wrapped setup must preserve freestyleCompanyBase in ctx
+  withFreestyleCompanyBase(droppingSetup);
+}

package/src/freestyleCompanyBaseFragment/index.ts

@@ -0,0 +1,472 @@
+import {
+  VmSpec,
+  type FreestyleProviderDefinition,
+  type FreestyleTerminalProviderDefinition,
+} from "@rigkit/provider-freestyle";
+import {
+  sequence,
+  type JsonObject,
+  type WorkflowNodeInput,
+  type WorkflowNodeOutput,
+  type WorkflowNodeDefinition,
+  type WorkflowProviderMap,
+} from "@rigkit/sdk";
+
+export type FreestyleCompanyBaseFragmentOptions = {
+  github?: boolean;
+  codex?: boolean;
+  claude?: boolean;
+  vm?: {
+    home?: string;
+    memSizeGb?: number;
+    vcpuCount?: number;
+    rootfsSizeGb?: number;
+  };
+};
+
+export type FreestyleCompanyBaseFragmentProviderMap = WorkflowProviderMap & {
+  freestyle: FreestyleProviderDefinition;
+  terminal: FreestyleTerminalProviderDefinition;
+};
+
+type FreestyleCompanyBaseFragmentConfig = JsonObject & {
+  github: boolean;
+  codex: boolean;
+  claude: boolean;
+  bun: boolean;
+  nodeMajor: number;
+  codexPackage: string;
+  claudePackage: string;
+  systemPackages: string[];
+  npmPackages: string[];
+  vm: {
+    home: string;
+    idleTimeoutSeconds: number;
+    memSizeGb: number;
+    vcpuCount: number;
+    rootfsSizeGb: number;
+  };
+};
+
+export type FreestyleCompanyBaseFragmentContext = JsonObject & {
+  snapshotId: string;
+  freestyleCompanyBase: {
+    snapshotId: string;
+    home: string;
+    idleTimeoutSeconds: number;
+    tools: {
+      github: boolean;
+      codex: boolean;
+      claude: boolean;
+      bun: boolean;
+      nodeMajor: number;
+    };
+    systemPackages: string[];
+    npmPackages: string[];
+    authenticated: {
+      github: boolean;
+      codex: boolean;
+      claude: boolean;
+    };
+  };
+};
+
+export type FreestyleCompanyBaseFragment = WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, {}, FreestyleCompanyBaseFragmentContext>;
+
+/**
+ * `withFreestyleCompanyBase` is an intentionally advanced wrapper pattern.
+ *
+ * A company base fragment usually needs to do two things that are easy to lose
+ * in simpler examples:
+ *
+ * - seed the workflow with a global, shared base snapshot
+ * - let repo-specific setup add fields to ctx while preserving the base ctx
+ *   needed by later company checks
+ *
+ * The types below encode that contract. They reject a child setup that drops
+ * `freestyleCompanyBase`, but keep any extra fields the child adds so callers
+ * can continue with their repo-specific ctx shape.
+ */
+export type FreestyleCompanyBaseWrappedFragment<Context extends FreestyleCompanyBaseFragmentContext> =
+  WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, {}, Context>;
+
+type FreestyleCompanyBasePreservingChild<Child extends WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, any, any>> =
+  FreestyleCompanyBaseFragmentContext extends WorkflowNodeInput<Child>
+    ? WorkflowNodeOutput<Child> extends FreestyleCompanyBaseFragmentContext
+      ? Child
+      : never
+    : never;
+
+type FreestyleCompanyBasePreservedOutput<Child extends WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, any, any>> =
+  WorkflowNodeOutput<Child> extends FreestyleCompanyBaseFragmentContext
+    ? WorkflowNodeOutput<Child>
+    : never;
+
+const defaultSystemPackages = [
+  "build-essential",
+  "ca-certificates",
+  "curl",
+  "git",
+  "gnupg",
+  "jq",
+  "pkg-config",
+  "python3",
+  "python3-pip",
+  "ripgrep",
+  "unzip",
+  "xz-utils",
+] as const;
+
+const bun = true;
+const nodeMajor = 22;
+const codexPackage = "@openai/codex";
+const claudePackage = "@anthropic-ai/claude-code";
+const idleTimeoutSeconds = 600;
+
+export function freestyleCompanyBaseFragment(options: FreestyleCompanyBaseFragmentOptions = {}): FreestyleCompanyBaseFragment {
+  const github = options.github ?? true;
+  const codex = options.codex ?? true;
+  const claude = options.claude ?? true;
+  const systemPackages = [...defaultSystemPackages];
+  const npmPackages = [
+    ...(codex ? [codexPackage] : []),
+    ...(claude ? [claudePackage] : []),
+  ];
+
+  const config = {
+    github,
+    codex,
+    claude,
+    bun,
+    nodeMajor,
+    codexPackage,
+    claudePackage,
+    systemPackages,
+    npmPackages,
+    vm: {
+      home: options.vm?.home ?? "/root",
+      idleTimeoutSeconds,
+      memSizeGb: options.vm?.memSizeGb ?? 16,
+      vcpuCount: options.vm?.vcpuCount ?? 4,
+      rootfsSizeGb: options.vm?.rootfsSizeGb ?? 24,
+    },
+  } satisfies FreestyleCompanyBaseFragmentConfig;
+
+  return sequence<FreestyleCompanyBaseFragmentProviderMap, {}>("freestyle-company-base")
+    .global()
+    .configure(config)
+    .task(
+      "install-tooling",
+      { version: "freestyle-company-base-tooling-v1" },
+      async ({ config, freestyle, step }) => {
+        const { vm, vmId } = await freestyle.client.vms.create({
+          spec: createVmSpec(config),
+          logger: console.log,
+        });
+        try {
+          const snapshot = await vm.snapshot();
+          return {
+            ctx: {
+              snapshotId: snapshot.snapshotId,
+              freestyleCompanyBase: {
+                snapshotId: snapshot.snapshotId,
+                home: config.vm.home,
+                idleTimeoutSeconds: config.vm.idleTimeoutSeconds,
+                tools: {
+                  github: config.github,
+                  codex: config.codex,
+                  claude: config.claude,
+                  bun: config.bun,
+                  nodeMajor: config.nodeMajor,
+                },
+                systemPackages: config.systemPackages,
+                npmPackages: config.npmPackages,
+                authenticated: {
+                  github: false,
+                  codex: false,
+                  claude: false,
+                },
+              },
+            },
+          };
+        } finally {
+          await freestyle.client.vms.delete({ vmId });
+        }
+      },
+    )
+    .task(
+      "github-auth",
+      { version: "freestyle-company-base-github-auth-v1" },
+      async ({ config, freestyle, terminal, step }) => {
+        if (!config.github) return { ctx: { ...step.ctx } };
+
+        const created = await freestyle.client.vms.create({
+          snapshotId: step.ctx.snapshotId,
+          idleTimeoutSeconds: config.vm.idleTimeoutSeconds,
+          logger: console.log,
+        });
+        const { vm, vmId } = created;
+        try {
+          const authenticated = await vm.exec(withHome(config.vm.home, "gh auth status -h github.com >/dev/null 2>&1"));
+          if ((authenticated.statusCode ?? 0) !== 0) {
+            await terminal.open("Log in to GitHub", {
+              ssh: await freestyle.createSSHOptions({ vmId }),
+              command: "gh auth login --hostname github.com --git-protocol https --web",
+              keepOpenAfterCommand: true,
+              instructions:
+                "Complete the GitHub browser login in this terminal. After gh succeeds, type exit to continue.",
+            });
+
+            const verified = await vm.exec(withHome(config.vm.home, "gh auth status -h github.com >/dev/null 2>&1"));
+            if ((verified.statusCode ?? 0) !== 0) {
+              const status = await vm.exec(withHome(config.vm.home, "gh auth status -h github.com 2>&1"));
+              throw new Error(
+                `GitHub CLI is not authenticated:\n${status.stdout || status.stderr}`.trim(),
+              );
+            }
+          }
+
+          const gitIdentity = await vm.exec({
+            command: configureGitIdentityCommand(config.vm.home),
+            timeoutMs: 60 * 1000,
+          });
+          if ((gitIdentity.statusCode ?? 0) !== 0) {
+            throw new Error(
+              `Git author identity configuration failed:\n${gitIdentity.stdout ?? ""}${gitIdentity.stderr ?? ""}`.trim(),
+            );
+          }
+
+          const snapshot = await vm.snapshot();
+          return { ctx: updateCompanyBaseSnapshot(step.ctx, snapshot.snapshotId, { github: true }) };
+        } finally {
+          await freestyle.client.vms.delete({ vmId });
+        }
+      },
+    )
+    .task(
+      "codex-auth",
+      { version: "freestyle-company-base-codex-auth-v1" },
+      async ({ config, freestyle, terminal, step }) => {
+        if (!config.codex) return { ctx: { ...step.ctx } };
+
+        const { vm, vmId } = await freestyle.client.vms.create({
+          snapshotId: step.ctx.snapshotId,
+          idleTimeoutSeconds: config.vm.idleTimeoutSeconds,
+          logger: console.log,
+        });
+        try {
+          await terminal.open("Initialize Codex CLI", {
+            ssh: await freestyle.createSSHOptions({ vmId }),
+            command: agentCliInitCommand(config.vm.home, "codex"),
+            keepOpenAfterCommand: true,
+            instructions:
+              "Complete Codex login and initialization in this terminal. Exit Codex, then type exit to continue.",
+          });
+
+          const snapshot = await vm.snapshot();
+          return { ctx: updateCompanyBaseSnapshot(step.ctx, snapshot.snapshotId, { codex: true }) };
+        } finally {
+          await freestyle.client.vms.delete({ vmId });
+        }
+      },
+    )
+    .task(
+      "claude-auth",
+      { version: "freestyle-company-base-claude-auth-v1" },
+      async ({ config, freestyle, terminal, step }) => {
+        if (!config.claude) return { ctx: { ...step.ctx } };
+
+        const { vm, vmId } = await freestyle.client.vms.create({
+          snapshotId: step.ctx.snapshotId,
+          idleTimeoutSeconds: config.vm.idleTimeoutSeconds,
+          logger: console.log,
+        });
+        try {
+          await terminal.open("Initialize Claude CLI", {
+            ssh: await freestyle.createSSHOptions({ vmId }),
+            command: agentCliInitCommand(config.vm.home, "claude"),
+            keepOpenAfterCommand: true,
+            instructions:
+              "Complete Claude login and initialization in this terminal. Exit Claude, then type exit to continue.",
+          });
+
+          const snapshot = await vm.snapshot();
+          return { ctx: updateCompanyBaseSnapshot(step.ctx, snapshot.snapshotId, { claude: true }) };
+        } finally {
+          await freestyle.client.vms.delete({ vmId });
+        }
+      },
+    ) as unknown as FreestyleCompanyBaseFragment;
+}
+
+export function withFreestyleCompanyBase<
+  Child extends WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, any, any>,
+>(
+  child: FreestyleCompanyBasePreservingChild<Child>,
+  options: FreestyleCompanyBaseFragmentOptions = {},
+): FreestyleCompanyBaseWrappedFragment<FreestyleCompanyBasePreservedOutput<Child>> {
+  return sequence<FreestyleCompanyBaseFragmentProviderMap, {}>("with-freestyle-company-base")
+    .add(freestyleCompanyBaseFragment(options))
+    .add(child as any)
+    .add(freestyleCompanyBaseAuthCheckFragment<FreestyleCompanyBasePreservedOutput<Child>>(options) as any) as unknown as FreestyleCompanyBaseWrappedFragment<FreestyleCompanyBasePreservedOutput<Child>>;
+}
+
+function freestyleCompanyBaseAuthCheckFragment<Context extends FreestyleCompanyBaseFragmentContext>(
+  options: FreestyleCompanyBaseFragmentOptions,
+): WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, Context, Context> {
+  const handler = async ({ freestyle, step }: any) => {
+    const { vm, vmId } = await freestyle.client.vms.create({
+      snapshotId: step.ctx.snapshotId,
+      idleTimeoutSeconds: step.ctx.freestyleCompanyBase.idleTimeoutSeconds,
+      logger: console.log,
+    });
+    try {
+      if (options.github ?? true) {
+        const github = await vm.exec(withHome(step.ctx.freestyleCompanyBase.home, "gh auth status -h github.com >/dev/null 2>&1"));
+        if ((github.statusCode ?? 0) !== 0) {
+          return step.invalidate("github-auth" as never);
+        }
+      }
+
+      return { ctx: { ...step.ctx } as Context };
+    } finally {
+      await freestyle.client.vms.delete({ vmId });
+    }
+  };
+
+  return sequence<FreestyleCompanyBaseFragmentProviderMap, Context>("freestyle-company-base-auth-check")
+    .local()
+    .task("check-auth", { cacheTTL: 0 }, handler as any) as unknown as WorkflowNodeDefinition<FreestyleCompanyBaseFragmentProviderMap, Context, Context>;
+}
+
+function createVmSpec(config: FreestyleCompanyBaseFragmentConfig): VmSpec {
+  return new VmSpec()
+    .runCommands(installToolingCommand(config))
+    .memSizeGb(config.vm.memSizeGb)
+    .vcpuCount(config.vm.vcpuCount)
+    .rootfsSizeGb(config.vm.rootfsSizeGb)
+    .idleTimeoutSeconds(config.vm.idleTimeoutSeconds);
+}
+
+function installToolingCommand(config: FreestyleCompanyBaseFragmentConfig): string {
+  const aptPackages = [...config.systemPackages];
+  if (config.github && !aptPackages.includes("gh")) aptPackages.push("gh");
+  if (!aptPackages.includes("nodejs")) aptPackages.push("nodejs");
+
+  const lines = [
+    "set -e",
+    "export DEBIAN_FRONTEND=noninteractive",
+    `export HOME=${shellQuote(config.vm.home)}`,
+    "apt-get update -qq",
+    "apt-get install -y -qq ca-certificates curl gnupg",
+    "mkdir -p /etc/apt/keyrings",
+  ];
+
+  if (config.github) {
+    lines.push(
+      "curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o /etc/apt/keyrings/githubcli-archive-keyring.gpg",
+      "chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg",
+      "printf 'deb [arch=%s signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main\\n' \"$(dpkg --print-architecture)\" > /etc/apt/sources.list.d/github-cli.list",
+    );
+  }
+
+  lines.push(
+    `curl -fsSL https://deb.nodesource.com/setup_${config.nodeMajor}.x | bash -`,
+    `apt-get install -y -qq ${aptPackages.map(shellQuote).join(" ")}`,
+    "corepack enable || true",
+    "npm config set prefix /usr/local",
+  );
+
+  const backgroundInstalls: string[] = [];
+  if (config.bun) {
+    backgroundInstalls.push("curl -fsSL https://bun.sh/install | BUN_INSTALL=/opt/bun bash");
+  }
+  for (const npmPackage of config.npmPackages) {
+    backgroundInstalls.push(`npm install -g ${shellQuote(npmPackage)}`);
+  }
+
+  backgroundInstalls.forEach((command, index) => {
+    const pid = `install_pid_${index}`;
+    lines.push(`${command} &`, `${pid}=$!`);
+  });
+  backgroundInstalls.forEach((_, index) => {
+    lines.push(`wait "$install_pid_${index}"`);
+  });
+
+  if (config.bun) {
+    lines.push(
+      "ln -sf /opt/bun/bin/bun /usr/local/bin/bun",
+      "ln -sf /opt/bun/bin/bunx /usr/local/bin/bunx",
+    );
+  }
+  if (config.codex) {
+    lines.push(
+      `mkdir -p ${shellQuote(`${config.vm.home}/.codex`)}`,
+      `printf 'cli_auth_credentials_store = "file"\\n' > ${shellQuote(`${config.vm.home}/.codex/config.toml`)}`,
+    );
+  }
+
+  lines.push(
+    "git config --system init.defaultBranch main",
+    "git --version",
+    ...(config.github ? ["gh --version"] : []),
+    "node --version",
+    "npm --version",
+    ...(config.bun ? ["bun --version"] : []),
+    ...(config.codex ? ["codex --version"] : []),
+    ...(config.claude ? ["claude --version"] : []),
+    "rm -rf /var/lib/apt/lists/*",
+  );
+
+  return lines.join("\n");
+}
+
+function withHome(home: string, command: string): string {
+  return `HOME=${shellQuote(home)} ${command}`;
+}
+
+function agentCliInitCommand(home: string, command: "codex" | "claude"): string {
+  return [
+    "set -e",
+    `export HOME=${shellQuote(home)}`,
+    command,
+  ].join("\n");
+}
+
+function configureGitIdentityCommand(home: string): string {
+  return [
+    "set -e",
+    `export HOME=${shellQuote(home)}`,
+    "login=$(gh api user --jq '.login')",
+    "name=$(gh api user --jq '.name // empty')",
+    "id=$(gh api user --jq '.id')",
+    "email=$(gh api user --jq '.email // empty')",
+    'if [ -z "$name" ]; then name="$login"; fi',
+    'if [ -z "$email" ]; then email="${id}+${login}@users.noreply.github.com"; fi',
+    'git config --global user.name "$name"',
+    'git config --global user.email "$email"',
+  ].join("\n");
+}
+
+function updateCompanyBaseSnapshot(
+  ctx: Readonly<FreestyleCompanyBaseFragmentContext>,
+  snapshotId: string,
+  authenticated: Partial<FreestyleCompanyBaseFragmentContext["freestyleCompanyBase"]["authenticated"]>,
+): FreestyleCompanyBaseFragmentContext {
+  return {
+    ...ctx,
+    snapshotId,
+    freestyleCompanyBase: {
+      ...ctx.freestyleCompanyBase,
+      snapshotId,
+      authenticated: {
+        ...ctx.freestyleCompanyBase.authenticated,
+        ...authenticated,
+      },
+    },
+  };
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./freestyleCompanyBaseFragment/index.ts";

package/src/version.ts

@@ -0,0 +1 @@
+export const RIGKIT_FRAGMENTS_VERSION = "0.0.0-canary-20260518T014918-c5bc0c2";