@dmgnr/kuber 1.0.0 → 1.1.0

package/README.md

@@ -37,6 +37,10 @@ Not required locally:
 
 Docker is not required because builds happen on the remote builder after `kuber` syncs your repo state there. `kubectl` is not required because cluster access is handled through the bundled Kubernetes client.
 
+## Next.js Example
+
+[`example/`](example/) contains a documented deployment template for adding kuber to an existing Bun-powered Next.js project without initializing or bundling an application in this repository. It includes a standalone-output Dockerfile, `.dockerignore`, `compose.yml`, and the required Next.js configuration.
+
 ## Running
 
 During development:
@@ -65,6 +69,14 @@ bun run index.ts restart
 bun run index.ts db ls
 ```
 
+All commands accept `--config` to use a configuration file other than
+`.kuberrc.ts`:
+
+```bash
+kuber --config deploy/production.kuberrc.ts up
+kuber up --config deploy/production.kuberrc.ts
+```
+
 ### Shell Completion
 
 Generate and load completions for your shell:
@@ -91,6 +103,61 @@ For a permanent setup, write the generated script to a file and source it from y
 - `db ls`: list managed Postgres claims declared in the current Compose file
 - `db creds <service>`: print the generated connection details for a managed Postgres claim
 
+## Configuration
+
+Kuber optionally loads `.kuberrc.ts` from the working directory. The file must
+default export an object satisfying the published `KuberConfig` type:
+
+```ts
+import type { KuberConfig } from "@dmgnr/kuber";
+
+export default {
+  project: "my-app",
+  composeFile: "compose.production.yml",
+  registry: "registry.example.com",
+  builders: {
+    amd64: "kuber@amd-builder",
+    arm64: "kuber@arm-builder",
+    remoteRoot: "kuber-build",
+  },
+  rolloutTimeoutMs: 10 * 60_000,
+
+  async compose(compose) {
+    const app = compose.services?.app;
+    if (app && !Array.isArray(app.environment)) {
+      app.environment ??= {};
+      app.environment.NEXT_PUBLIC_BUILD_ID =
+        await Bun.$`git rev-parse --short HEAD`
+          .text()
+          .then((value) => value.trim());
+    }
+  },
+} satisfies KuberConfig;
+```
+
+Operational defaults:
+
+- `project`: current working directory name
+- `composeFile`: the first recognized Compose filename in the working directory
+- `registry`: `registry.neko-piranha.ts.net`
+- `builders.amd64`: `kuber@astral-th`
+- `builders.arm64`: `kuber@astral`
+- `builders.remoteRoot`: `kuber-build`
+- `rolloutTimeoutMs`: `300000`
+
+Configuration hooks can be synchronous or asynchronous and receive mutable
+values:
+
+- `compose(compose, context)`: once after parsing and validation; affects every command that reads Compose
+- `preBuild(compose, context)`: before build eligibility is evaluated when builds are enabled
+- `postBuild(result, context)`: after images are built; `result` contains `built` and `changed` service names
+- `postRender(resources, context)`: after rendering and before reconciliation planning; also runs for `export`
+- `postApply(resources, context)`: after desired resources are successfully applied
+
+Hook context contains the resolved `cwd`, `project`, `composeFile`, and optional
+`configFile`. A hook error aborts the command and is reported by the normal CLI
+error handler.
+
 ## Compose Conventions
 
 `kuber` supports a few project-specific Compose conventions on top of normal service translation.