redkite 0.1.6

package/src/presets/index.ts

@@ -0,0 +1,2 @@
+export * from "./nextApp.js";
+export * from "./nodeApp.js";

package/src/presets/nextApp.ts

@@ -0,0 +1,70 @@
+import type { BuildSpec } from "../types.js";
+import { nodeApp } from "./nodeApp.js";
+
+type NextAppOptions = {
+  builder?: string;
+  runtime?: string;
+  port?: number;
+  steps?: string[];
+  dependencies?: { files: string[]; step: string } | false;
+  // Whether next.config sets output: "standalone". Defaults to true, which is
+  // the layout worth deploying: a tree that runs on node alone
+  standalone?: boolean;
+};
+
+// The standalone layout is three directories that have to land in the right
+// places, which is the only part of a Next build that is not a node build
+export function nextApp(options: NextAppOptions = {}): BuildSpec {
+  const port = options.port ?? 3000;
+  const standalone = options.standalone ?? true;
+
+  const shared = {
+    builder: options.builder ?? "24-alpine",
+    runtime: options.runtime ?? "22-alpine",
+    steps: options.steps ?? ["yarn build"],
+    dependencies: options.dependencies,
+  };
+
+  // Relative, because the runtime starts at the app's root and a monorepo puts
+  // that under its own directory rather than at the top of the image
+  const start = (command: string) =>
+    ["sh", "-c", `HOSTNAME=0.0.0.0 PORT=${port} ${command}`];
+
+  if (!standalone) {
+    return {
+      ...nodeApp({
+        ...shared,
+        // The whole tree, because next start reads the source layout it built
+        // from and resolves its own dependencies at runtime
+        output: "/app",
+        // npx resolves the binary from node_modules/.bin upwards, so this
+        // finds it whether a workspace hoisted it or the app owns it
+        entrypoint: start("npx --no-install next start"),
+        // Without the modules cache, so node_modules is a layer of the image
+        // rather than a mount the runtime stage never sees
+        caches: ["yarn", "npm", "next-app"],
+      }),
+      preset: "nextApp",
+      keepsLayout: true,
+    };
+  }
+
+  return {
+    ...nodeApp({
+      ...shared,
+      output: "/app/.next/standalone",
+      // static is what the build produced and the server serves. public is
+      // whatever the repository put there, and plenty of apps have none
+      carry: ["/app/.next/static", { path: "/app/public", optional: true }],
+      entrypoint: start("node server.js"),
+      // app-modules is what makes the build fast: node_modules on a mount
+      // rather than in a layer, which the standalone tree makes safe by
+      // carrying its own copy of everything the server reaches
+      caches: ["yarn", "npm", "modules", "app-modules", "next-app"],
+    }),
+    preset: "nextApp",
+    // The standalone tree traces from the workspace root, so an app in a
+    // subdirectory arrives at that subdirectory and not at the top of it
+    keepsLayout: true,
+  };
+}

package/src/presets/nodeApp.ts

@@ -0,0 +1,46 @@
+import type { BuildSpec, CarryPath, SourcemapSpec } from "../types.js";
+
+type NodeAppOptions = {
+  builder?: string;
+  runtime?: string;
+  steps: string[];
+  // Defaults to yarn with a frozen lockfile. Set false where the build has no
+  // separable dependency phase
+  dependencies?: { files: string[]; step: string } | false;
+  output: string;
+  entrypoint: string[];
+  carry?: CarryPath[];
+  submodules?: boolean;
+  caches?: string[];
+  sourcemaps?: SourcemapSpec;
+};
+
+export function nodeApp(options: NodeAppOptions): BuildSpec {
+  return {
+    preset: "nodeApp",
+    builderImage: `node:${options.builder ?? "22-alpine"}`,
+    runtimeImage: `node:${options.runtime ?? "24-alpine"}`,
+    dependencies:
+      options.dependencies === false
+        ? undefined
+        : (options.dependencies ?? {
+            files: ["package.json", "yarn.lock"],
+            step: "yarn install --frozen-lockfile",
+            stripScripts: ["preinstall", "prepare", "postinstall"],
+          }),
+    steps: options.steps,
+    output: options.output,
+    carry: options.carry ?? [],
+    entrypoint: options.entrypoint,
+    // Not the app's own node_modules: a step after the build runs in this image
+    // without the mounts, and a migration that cannot find prisma is what a
+    // cache mount instead of a layer looks like from the outside
+    caches: options.caches ?? ["yarn", "npm", "modules"],
+    submodules: options.submodules ?? false,
+    // The checkout arrives complete, so this is what a build step itself needs
+    aptPackages: ["git"],
+    runtimePackages: ["curl"],
+    runtimeSteps: [],
+    sourcemaps: options.sourcemaps,
+  };
+}

package/src/secrets/bitwarden.ts

@@ -0,0 +1,7 @@
+import type { SecretRef } from "../types.js";
+
+// Names an item in a Bitwarden vault. The id is not a secret, it is a pointer,
+// so it belongs in the config while the credentials arrive at deploy time
+export function bitwarden(id: string): SecretRef {
+  return { provider: "bitwarden", id };
+}

package/src/secrets/refs.ts

@@ -0,0 +1,32 @@
+import type { SecretRef, SecretRefs } from "../types.js";
+
+// Resolves an item to its contents. One per provider named by a ref
+export type SecretStore = {
+  read(id: string): Promise<string>;
+};
+
+export type SecretStores = Record<string, SecretStore>;
+
+export function listRefs(refs: SecretRefs | undefined): SecretRef[] {
+  if (!refs) return [];
+  return Array.isArray(refs) ? refs : [refs];
+}
+
+export async function readRef(ref: SecretRef, stores: SecretStores) {
+  const store = stores[ref.provider];
+  if (store) return await store.read(ref.id);
+
+  const known = Object.keys(stores).join(", ") || "none";
+  throw new Error(`No store for provider ${ref.provider}, deploy was given ${known}`);
+}
+
+// Concatenated in the order written. Every dotenv parser builds an object as it
+// reads, so a key that appears twice takes its later value, which is the
+// precedence the config file reads as having
+export async function readEnv(refs: SecretRefs | undefined, stores: SecretStores) {
+  const contents = await Promise.all(
+    listRefs(refs).map(async (ref) => await readRef(ref, stores)),
+  );
+
+  return contents.map((text) => (text.endsWith("\n") ? text : `${text}\n`)).join("");
+}

package/src/secrets/store.ts

@@ -0,0 +1,147 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import type { SecretStore } from "./refs.js";
+
+// One implementation of the interface deploy consumes. A second provider only
+// has to satisfy read().
+//
+// The CLI runs here as an ordinary process. It used to run inside a container
+// purely as a sandbox, which meant installing several thousand packages on
+// every deploy to read three items.
+
+const run = promisify(execFile);
+
+export type BitwardenCredentials = {
+  clientId: string;
+  clientSecret: string;
+  password: string;
+  detail?: (message: string) => void;
+};
+
+// Used when bw is not already on PATH. Pinned, because an unpinned CLI is a
+// different program on a machine that has never run a deploy before
+const CLI = "@bitwarden/cli@2026.4.2";
+
+// Where that install lands. Keyed by the pinned version, so bumping it installs
+// beside the old one rather than over a vault command that is mid-flight
+const CLIS = join(homedir(), ".cache", "redkite", "cli");
+
+export async function bitwardenStore(
+  credentials: BitwardenCredentials,
+): Promise<SecretStore> {
+  const detail = credentials.detail ?? (() => {});
+
+  // Its own state directory, so a deploy neither reads nor disturbs whatever
+  // vault the person running it happens to be logged into
+  const appdata = join(homedir(), ".cache", "redkite", "bitwarden");
+  await mkdir(appdata, { recursive: true });
+
+  const command = await resolveCli(detail);
+
+  const bw = async (args: string[], env: Record<string, string> = {}) =>
+    await run(command.file, [...command.prefix, ...args], {
+      env: {
+        ...process.env,
+        BITWARDENCLI_APPDATA_DIR: appdata,
+        ...env,
+      },
+      maxBuffer: 32 * 1024 * 1024,
+    });
+
+  detail("unlocking the vault");
+
+  // Already logged in is not an error, the session is what matters
+  await bw(["login", "--apikey"], {
+    BW_CLIENTID: credentials.clientId,
+    BW_CLIENTSECRET: credentials.clientSecret,
+  }).catch(() => undefined);
+
+  const unlocked = await bw(["unlock", "--passwordenv", "BW_PASSWORD", "--raw"], {
+    BW_PASSWORD: credentials.password,
+  }).catch((error: unknown) => {
+    throw new Error(`Could not unlock the Bitwarden vault: ${messageOf(error)}`);
+  });
+
+  const session = unlocked.stdout.trim();
+  if (!session) throw new Error("Bitwarden unlocked without a session");
+
+  // An item added since the last deploy is not in the local vault otherwise,
+  // and bw get answers "not found" rather than fetching it
+  await bw(["sync"], { BW_SESSION: session }).catch(() => undefined);
+
+  // Fetched once each. A second read of the same item during a deploy is the
+  // same answer, and this avoids a process per call site
+  const cache = new Map<string, Promise<string>>();
+
+  const fetch = async (id: string) => {
+    const item = await bw(["get", "notes", id, "--raw"], {
+      BW_SESSION: session,
+    }).catch((error: unknown) => {
+      throw new Error(`Could not read ${id} from Bitwarden: ${messageOf(error)}`);
+    });
+
+    return item.stdout;
+  };
+
+  return {
+    read: async (id) => {
+      const pending = cache.get(id) ?? fetch(id);
+      cache.set(id, pending);
+      return await pending;
+    },
+  };
+}
+
+type Cli = { file: string; prefix: string[] };
+
+// A machine with the CLI installed pays nothing. One without it installs the
+// pinned version once, rather than resolving it again on every call below
+async function resolveCli(detail: (message: string) => void): Promise<Cli> {
+  const override = process.env["REDKITE_BW_BIN"];
+  if (override) return { file: override, prefix: [] };
+
+  const found = await run("bw", ["--version"]).then(
+    () => true,
+    () => false,
+  );
+
+  if (found) return { file: "bw", prefix: [] };
+
+  return { file: await install(detail), prefix: [] };
+}
+
+// npx resolves the package again on every invocation, and unlocking a vault is
+// three commands plus one per secret. That was most of a second, six times over
+async function install(detail: (message: string) => void) {
+  const directory = join(CLIS, CLI.replace(/[^\w.]+/g, "-"));
+  const binary = join(directory, "node_modules", ".bin", "bw");
+
+  if (existsSync(binary)) return binary;
+
+  detail(`installing ${CLI}, once for this machine`);
+  await mkdir(directory, { recursive: true });
+
+  await run(
+    "npm",
+    ["install", "--prefix", directory, "--no-save", "--no-audit", "--no-fund", CLI],
+    { maxBuffer: 32 * 1024 * 1024 },
+  ).catch((error: unknown) => {
+    throw new Error(`Could not install ${CLI}: ${messageOf(error)}`);
+  });
+
+  return binary;
+}
+
+function messageOf(error: unknown) {
+  if (error instanceof Error && "stderr" in error) {
+    const stderr = String(error.stderr).trim();
+    if (stderr) return stderr;
+  }
+
+  return error instanceof Error ? error.message : String(error);
+}

package/src/services/ensure.ts

@@ -0,0 +1,160 @@
+import { SPEC_LABEL, type Docker } from "../docker.js";
+import type { Host } from "../host.js";
+import type { Log } from "../log.js";
+import { LISTEN_PORT } from "../nginx.js";
+import { readEnv, type SecretStores } from "../secrets/refs.js";
+import type { ServiceTopology, Topology } from "../topology.js";
+import type { ServiceSpec } from "../types.js";
+
+import { fingerprintOf, type PlannedService } from "./planned.js";
+
+// redis.ts and nginx.ts were the same object described twice: ensure a sidecar
+// from an image is running, at an address, with a configuration file.
+
+export type EnsureContext = {
+  host: Host;
+  docker: Docker;
+  topology: Topology;
+  // Rendered by the caller, so this file does not have to know what nginx is
+  files: Record<string, string>;
+  // One store per provider a service names. A service without secrets never
+  // opens one
+  secrets: SecretStores;
+  log: Log;
+  // Set for the proxy alone. Nothing else is reachable from outside the host,
+  // and nothing else has to resolve the apps by name
+  publish?: number;
+};
+
+// What became of one service, for a deploy that says what it did rather than
+// whether something changed
+export type Ensured = "adopted" | "started" | "created" | "recreated";
+
+export async function ensureService(
+  spec: ServiceSpec,
+  service: ServiceTopology,
+  context: EnsureContext,
+): Promise<Ensured> {
+  const { docker } = context;
+  const name = service.container;
+  const fingerprint = fingerprintOf(plannedFrom(spec, service, context), context.topology);
+
+  if (await docker.container.exists(name)) {
+    // A service outlives a deploy, so being there is usually the whole answer.
+    // Being there having been created from something else is not: a changed
+    // public port or a rendered config only reaches a container that is made
+    if (await docker.container.specOf(name) === fingerprint) {
+      if (await docker.container.isRunning(name)) return "adopted";
+
+      context.log.warn(`${name} was not running, starting it`);
+      await docker.container.start(name);
+      return "started";
+    }
+
+    context.log(`${name} is not what the deployment says, recreating it`);
+    await docker.container.stop(name);
+    await docker.container.remove(name);
+    await createService(spec, service, context, fingerprint);
+    await docker.container.start(name);
+    return "recreated";
+  }
+
+  context.log(`Creating ${name} at ${service.address}`);
+  await createService(spec, service, context, fingerprint);
+  await docker.container.start(name);
+
+  return "created";
+}
+
+// The same shape the plan compares against, assembled from what this call was
+// handed. Two spellings of it would drift from each other rather than from the
+// host, which is the one drift nothing here would report
+function plannedFrom(
+  spec: ServiceSpec,
+  service: ServiceTopology,
+  context: EnsureContext,
+): PlannedService {
+  return { spec, service, files: context.files, publish: context.publish };
+}
+
+async function createService(
+  spec: ServiceSpec,
+  service: ServiceTopology,
+  context: EnsureContext,
+  fingerprint: string,
+) {
+  const { docker, topology } = context;
+  const name = service.container;
+
+  await buildImage(spec, name, context);
+
+  const builder = docker.container
+    .builder()
+    .name(name)
+    .image(name)
+    .network(topology.network)
+    .label(SPEC_LABEL, fingerprint)
+    .ip(service.address);
+
+  if (spec.restart) builder.restart(spec.restart);
+
+  for (const [name, value] of Object.entries(spec.environment ?? {})) {
+    builder.env(name, value);
+  }
+
+  // Written to the host and handed over as a file, so the value never appears
+  // in an argument list. Docker reads it when the container is created and
+  // keeps the values, so the file goes with the rest of the deploy's scratch
+  if (spec.secrets) {
+    const contents = await readEnv(spec.secrets, context.secrets);
+    builder.envFile(await context.host.write(`services/${name}/env`, contents));
+  }
+
+  for (const volume of service.volumes) {
+    builder.volume(volume.volume, volume.mountPath);
+  }
+
+  if (context.publish) {
+    for (const [host, ip] of Object.entries(topology.extraHosts)) {
+      builder.extraHost(host, ip);
+    }
+
+    builder.port(context.publish, LISTEN_PORT);
+  }
+
+  await builder.create();
+}
+
+// Three lines of Dockerfile on the host, in place of a container assembled in
+// an engine, exported as a tarball and loaded back in
+async function buildImage(
+  spec: ServiceSpec,
+  name: string,
+  context: EnsureContext,
+) {
+  const { host, docker } = context;
+  const directory = `services/${name}`;
+
+  const copies = await Promise.all(
+    Object.entries(context.files).map(async ([path, contents], index) => {
+      await host.write(`${directory}/file.${index}`, contents);
+      return `COPY file.${index} ${path}`;
+    }),
+  );
+
+  const dockerfile = await host.write(
+    `${directory}/Dockerfile`,
+    [
+      `FROM ${spec.image}`,
+      ...copies,
+      ...(context.publish ? [`EXPOSE ${LISTEN_PORT}`] : []),
+      "",
+    ].join("\n"),
+  );
+
+  await docker.image.build({
+    context: `${host.directory}/${directory}`,
+    dockerfile,
+    tags: [name],
+  });
+}

package/src/services/index.ts

@@ -0,0 +1,48 @@
+import type { SecretRefs, ServiceSpec } from "../types.js";
+
+type RedisOptions = {
+  image?: string;
+  alias?: string;
+  address?: number;
+  volumes?: Record<string, string>;
+};
+
+export function redis(options: RedisOptions = {}): ServiceSpec {
+  return {
+    name: "redis",
+    image: options.image ?? "redis:7",
+    alias: options.alias ?? "redis",
+    restart: "always",
+    address: options.address,
+    // The image declares VOLUME /data, so without this the data lands in an
+    // anonymous volume that survives nothing and can be named by no one
+    volumes: options.volumes ?? { data: "/data" },
+  };
+}
+
+type PostgresOptions = {
+  // The image refuses to start without POSTGRES_PASSWORD, so this is required
+  // rather than optional: a service that cannot come up is not a default
+  secrets: SecretRefs;
+  image?: string;
+  alias?: string;
+  address?: number;
+  volumes?: Record<string, string>;
+  // POSTGRES_DB and POSTGRES_USER, which are settings rather than credentials
+  environment?: Record<string, string>;
+};
+
+export function postgres(options: PostgresOptions): ServiceSpec {
+  return {
+    name: "postgres",
+    image: options.image ?? "postgres:17-alpine",
+    alias: options.alias ?? "postgres",
+    restart: "always",
+    address: options.address,
+    secrets: options.secrets,
+    environment: options.environment,
+    // The image declares VOLUME on this path, so without naming it the data
+    // lands in an anonymous volume that survives nothing and nobody can name
+    volumes: options.volumes ?? { data: "/var/lib/postgresql/data" },
+  };
+}

package/src/services/planned.ts

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+
+import type { Docker } from "../docker.js";
+import { LISTEN_PORT, renderNginx } from "../nginx.js";
+import type { Run } from "../pipeline.js";
+import type { ServiceTopology, Topology } from "../topology.js";
+import type { Deployment, ServiceSpec } from "../types.js";
+
+// What a deployment says should be running, and how that compares to what is.
+// Services outlive a deploy, so the config that created one is not the config
+// the file now holds: a changed public port or a rendered nginx block lands in
+// an image the running container was never created from.
+
+export type PlannedService = {
+  spec: ServiceSpec;
+  service: ServiceTopology;
+  // Rendered by the deployment, and part of the image the container runs
+  files: Record<string, string>;
+  publish?: number;
+};
+
+export function plannedServices(
+  config: Deployment,
+  topology: Topology,
+  run: Run = "deploy",
+): PlannedService[] {
+  const rest = config.services.map((spec) => {
+    const service = topology.services.find((item) => item.name === spec.name);
+    if (!service) throw new Error(`No topology for service ${spec.name}`);
+
+    return { spec, service, files: spec.files ?? {} };
+  });
+
+  // Nothing serves in a verify run, so a proxy there would resolve upstreams
+  // that were never created and publish a port for them
+  if (run === "verify") return rest;
+
+  const proxy: PlannedService = {
+    spec: router(config),
+    service: topology.router,
+    files: {
+      "/etc/nginx/conf.d/default.conf": renderNginx(topology, config.maxBodySize),
+    },
+    publish: topology.publicPort,
+  };
+
+  return [proxy, ...rest];
+}
+
+// Not something a deployment lists. Apps carry routes, routes need a proxy to
+// resolve them, and the one that renders them is this
+export function router(config: Deployment): ServiceSpec {
+  return {
+    name: "nginx",
+    image: config.proxyImage ?? "nginx:stable",
+    restart: "always",
+  };
+}
+
+// Everything a recreate would change, and nothing a deploy resolves. Secrets
+// are named by their refs rather than their values: whether the config is the
+// one running is a question a plan should answer without unlocking a vault
+export function fingerprintOf(planned: PlannedService, topology: Topology) {
+  const { spec, service, files, publish } = planned;
+
+  const shape = {
+    image: spec.image,
+    restart: spec.restart,
+    address: service.address,
+    network: topology.network,
+    volumes: service.volumes,
+    environment: spec.environment,
+    secrets: spec.secrets,
+    files,
+    // The proxy alone, and the two things being published costs it
+    publish: publish && { host: publish, container: LISTEN_PORT },
+    extraHosts: publish ? topology.extraHosts : undefined,
+  };
+
+  return createHash("sha256").update(JSON.stringify(shape)).digest("hex").slice(0, 16);
+}
+
+// Why a service is not what the deployment says it should be. Absent from the
+// list means it is
+export type Drift = {
+  container: string;
+  name: string;
+  reason: "missing" | "stopped" | "changed" | "unrecognised";
+};
+
+export async function driftOf(
+  planned: PlannedService[],
+  topology: Topology,
+  docker: Docker,
+): Promise<Drift[]> {
+  const drifted: Drift[] = [];
+
+  for (const item of planned) {
+    const reason = await reasonFor(item, topology, docker);
+    if (reason) drifted.push({ container: item.service.container, name: item.spec.name, reason });
+  }
+
+  return drifted;
+}
+
+async function reasonFor(planned: PlannedService, topology: Topology, docker: Docker) {
+  const name = planned.service.container;
+  if (!(await docker.container.exists(name))) return "missing" as const;
+
+  const held = await docker.container.specOf(name);
+  // Created by hand, or by a redkite that did not record what it created from.
+  // Either way nothing here can say it matches, so it is rebuilt once
+  if (!held) return "unrecognised" as const;
+
+  if (held !== fingerprintOf(planned, topology)) return "changed" as const;
+  if (!(await docker.container.isRunning(name))) return "stopped" as const;
+
+  return undefined;
+}