@kaupang/core 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @kaupang/core
+
+[![npm](https://img.shields.io/npm/v/@kaupang/core.svg)](https://www.npmjs.com/package/@kaupang/core)
+[![license](https://img.shields.io/npm/l/@kaupang/core.svg)](https://github.com/kaupang-dev/kaupang/blob/main/LICENSE)
+
+> The engine + config-authoring API behind
+> [kaupang](https://github.com/kaupang-dev/kaupang).
+> **Most people want the CLI:** [`@kaupang/cli`](https://www.npmjs.com/package/@kaupang/cli)
+> (`npm i -g @kaupang/cli`).
+
+This package provides the typed helpers you use to author a kaupang config — you import
+it in your `kaupang.config.ts` and environment files:
+
+```ts
+import { defineConfig, defineEnvironment, secret, use } from "@kaupang/core";
+```
+
+- `defineConfig(config)` / `defineEnvironment(env)` — identity helpers with full
+  type-checking + autocomplete.
+- `secret("VAR")` — a value resolved from the environment at deploy time, never written
+  to the generated artifact or the ledger.
+- `use("preset", overrides?)` — reference a shared catalog preset.
+- `defineSolution` / `definePipeline` / `defineService` — for solutions, pipelines, and
+  reusable service specs.
+- All config **types** (`KaupangConfig`, `ServiceSpec`, `EnvironmentDefinition`, …).
+
+You don't import this to *run* deploys — that's the CLI's job; `@kaupang/cli` depends on
+it. It ships as a normal dependency so your config files resolve the helpers and types.
+
+> An engine surface is also exposed under `@kaupang/core/internal`, but that subpath is
+> **internal** — consumed by `@kaupang/cli`, not part of the stable public API.
+
+## Docs
+
+See the [project README](https://github.com/kaupang-dev/kaupang#readme).
+
+## License
+
+MIT © Andreas Quist Batista

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { K as KaupangConfig, E as EnvironmentDefinition, P as Pipeline, S as ServiceSpec, a as SolutionRecipe, b as SecretRef, C as CatalogRef } from './types-CNSMXHRO.js';
+export { B as BackendName, c as BuildConfig, d as CatalogConfig, e as CatalogSourceConfig, D as Dependable, f as EnvMap, g as EnvValue, H as HealthcheckConfig, h as HookCommand, i as Hooks, j as PipelineStep, k as PullPolicy, l as ServiceDefinition, m as ServiceInput, T as TargetConfig, W as WaitSpec } from './types-CNSMXHRO.js';
+
+/** Identity helper with full type-checking + autocomplete in kaupang.config.ts. */
+declare function defineConfig(config: KaupangConfig): KaupangConfig;
+/** Identity helper for environment files. */
+declare function defineEnvironment(env: EnvironmentDefinition): EnvironmentDefinition;
+/** Identity helper for a reusable service spec (e.g. shared in your repo). */
+declare function defineService(spec: ServiceSpec): ServiceSpec;
+/**
+ * Reference a service preset from the catalog, optionally overriding fields:
+ *
+ *   services: { db: use("postgres", { env: { POSTGRES_DB: "shop" } }) }
+ */
+declare function use(name: string, overrides?: Partial<ServiceSpec>): CatalogRef;
+/**
+ * Mark an env value as a secret. kaupang emits a `${NAME}` reference (resolved by
+ * Docker at runtime from the process env) instead of writing the value into the
+ * generated artifact or the ledger:
+ *
+ *   env: { DB_PASSWORD: secret("DB_PASSWORD") }       // same name
+ *   env: { DB_PASSWORD: secret("PROD_DB_PASSWORD") }  // different source var
+ */
+declare function secret(name: string): SecretRef;
+/** Identity helper for a solution recipe (a named composition of environments). */
+declare function defineSolution(recipe: SolutionRecipe): SolutionRecipe;
+/** Identity helper for a pipeline (ordered run / up / down / build / wait steps). */
+declare function definePipeline(pipeline: Pipeline): Pipeline;
+
+export { CatalogRef, EnvironmentDefinition, KaupangConfig, Pipeline, SecretRef, ServiceSpec, SolutionRecipe, defineConfig, defineEnvironment, definePipeline, defineService, defineSolution, secret, use };

package/dist/index.js

@@ -0,0 +1,31 @@
+// src/config/define.ts
+function defineConfig(config) {
+  return config;
+}
+function defineEnvironment(env) {
+  return env;
+}
+function defineService(spec) {
+  return spec;
+}
+function use(name, overrides) {
+  return overrides ? { $catalog: name, overrides } : { $catalog: name };
+}
+function secret(name) {
+  return { $secret: name };
+}
+function defineSolution(recipe) {
+  return recipe;
+}
+function definePipeline(pipeline) {
+  return pipeline;
+}
+export {
+  defineConfig,
+  defineEnvironment,
+  definePipeline,
+  defineService,
+  defineSolution,
+  secret,
+  use
+};

package/dist/internal.d.ts

@@ -0,0 +1,397 @@
+import { S as ServiceSpec, a as SolutionRecipe, d as CatalogConfig, l as ServiceDefinition, f as EnvMap, i as Hooks, E as EnvironmentDefinition, k as PullPolicy, D as Dependable, K as KaupangConfig, B as BackendName, g as EnvValue, b as SecretRef, h as HookCommand } from './types-CNSMXHRO.js';
+export { c as BuildConfig, C as CatalogRef, e as CatalogSourceConfig, H as HealthcheckConfig, P as Pipeline, j as PipelineStep, m as ServiceInput, T as TargetConfig, W as WaitSpec } from './types-CNSMXHRO.js';
+
+/** A catalog manifest: reusable service presets and/or solution recipes. */
+interface CatalogManifest {
+    services?: Record<string, ServiceSpec>;
+    solutions?: Record<string, SolutionRecipe>;
+}
+interface CatalogSource {
+    readonly describe: string;
+    load(): Promise<CatalogManifest>;
+}
+/** Resolves presets and solutions against one or more sources (earlier sources win). */
+interface CatalogResolver {
+    resolve(name: string): Promise<ServiceSpec>;
+    list(): Promise<string[]>;
+    resolveSolution(name: string): Promise<SolutionRecipe>;
+    listSolutions(): Promise<string[]>;
+}
+/** Build a resolver from config; lazily loads + caches each source's manifest. */
+declare function createCatalogResolver(config: CatalogConfig | undefined, rootDir: string): CatalogResolver;
+
+/** The normalized environment shape consumed by the resolver + backends. */
+interface NormalizedEnvironment {
+    name: string;
+    file: string;
+    services: Record<string, ServiceDefinition>;
+    dependsOn: string[];
+    env: EnvMap;
+    hooks?: Hooks;
+    networks?: string[];
+    volumes?: string[];
+}
+interface NormalizeContext {
+    dockerRepository?: string;
+    defaultPull?: PullPolicy;
+    catalog: CatalogResolver;
+}
+declare function toArray(value?: Dependable): string[];
+/**
+ * Prefix a bare image name with the docker repository.
+ * Fully-qualified names (anything containing "/") are left untouched, so
+ * public/official images should be written in full or pulled from the catalog.
+ */
+declare function resolveImage(image: string | undefined, repo?: string): string | undefined;
+declare function normalizeEnvironment(def: EnvironmentDefinition, name: string, file: string, ctx: NormalizeContext): Promise<NormalizedEnvironment>;
+
+/** Normalized environment, ready for the resolver. */
+type ResolvedEnvironment = NormalizedEnvironment;
+interface LoadedConfig {
+    config: KaupangConfig;
+    configPath: string;
+    rootDir: string;
+    cacheDir: string;
+    project: string;
+    catalog: CatalogResolver;
+    environments: Map<string, ResolvedEnvironment>;
+}
+declare function findConfig(cwd?: string): string | null;
+declare function loadConfig(cwd?: string): Promise<LoadedConfig>;
+
+interface EnvironmentPlan {
+    name: string;
+    file: string;
+    /** Environment-scoped env vars (merged over globalEnv, under service env). */
+    env: EnvMap;
+    /** Environments this one directly depends on. */
+    dependsOn: string[];
+    /** Services in a valid start order. */
+    order: string[];
+    /** Services grouped into waves that can be started in parallel. */
+    waves: string[][];
+    services: Record<string, ServiceDefinition>;
+    /** Lifecycle hooks for this environment. */
+    hooks?: Hooks;
+}
+interface DeploymentPlan {
+    /** The environment the user asked for. */
+    target: string;
+    backend: BackendName;
+    /** Environments in start order: dependencies first, target last. */
+    environments: EnvironmentPlan[];
+}
+interface TopoResult {
+    order: string[];
+    waves: string[][];
+}
+/**
+ * Kahn's algorithm. `deps.get(n)` is the set of nodes that must come BEFORE n.
+ * Returns a flat order plus waves (each wave can be started concurrently).
+ * Throws on cycles or references to unknown nodes.
+ */
+declare function topoSort(nodes: string[], deps: Map<string, string[]>, label: string): TopoResult;
+/** Build a full deployment plan for `target` (including its transitive deps). */
+declare function resolvePlan(target: string, environments: Map<string, ResolvedEnvironment>, backend: BackendName): DeploymentPlan;
+/** Like resolvePlan but for several root environments (used by solutions). */
+declare function resolveMultiPlan(roots: string[], label: string, environments: Map<string, ResolvedEnvironment>, backend: BackendName): DeploymentPlan;
+
+interface BackendContext {
+    /** Directory containing kaupang.config.ts (also the cwd for spawned commands). */
+    rootDir: string;
+    /** Absolute path to the .kaupang cache directory. */
+    cacheDir: string;
+    /** Project namespace. */
+    project: string;
+    /** globalEnv merged with per-environment env (service env still wins on top). */
+    baseEnv: EnvMap;
+    /** Per-target env overrides (above environment env, below service env). */
+    targetEnv: EnvMap;
+    /** When set, force this pull behavior for the whole run (from --pull). */
+    pull?: PullPolicy;
+}
+interface BackendAction {
+    /** Human-readable description shown in dry-run. */
+    description: string;
+    file: string;
+    args: string[];
+    /** Optional stdin payload. */
+    input?: string;
+}
+interface MaterializedEnvironment {
+    /** Files to write before running actions (compose files, manifests, ...). */
+    files: {
+        path: string;
+        content: string;
+    }[];
+    /** Commands to bring the environment up. */
+    up: BackendAction[];
+    /** Commands to tear the environment down. */
+    down: BackendAction[];
+    /** Commands to build images for services that declare a build context. */
+    build: BackendAction[];
+    /** Commands to push built images to the registry (compose backend). */
+    push?: BackendAction[];
+}
+/**
+ * A backend is a pure translator: given a resolved environment it produces the
+ * files + commands needed. It performs no side effects — the command layer
+ * decides whether to write/execute (real run) or just print them (dry-run).
+ */
+interface Backend {
+    readonly name: BackendName;
+    materialize(env: EnvironmentPlan, ctx: BackendContext): MaterializedEnvironment;
+}
+
+declare function makeContext(loaded: LoadedConfig, opts?: {
+    pull?: PullPolicy;
+    targetEnv?: EnvMap;
+}): BackendContext;
+
+declare function getBackend(name: BackendName): Backend;
+declare const backendNames: BackendName[];
+
+/** A resolved image: what was authored vs. the immutable digest we deploy. */
+interface ResolvedImage {
+    service: string;
+    /** The reference as authored, e.g. "ghcr.io/acme/shop-api:latest". */
+    ref: string;
+    /** The resolved digest, e.g. "sha256:abc…". */
+    digest: string;
+    /** The digest-pinned reference we actually deploy, e.g. "ghcr.io/acme/shop-api@sha256:abc…". */
+    pinned: string;
+    /** True when the authored ref can point somewhere new on a later deploy. */
+    floating: boolean;
+}
+declare function isPinned(ref: string): boolean;
+/**
+ * Resolve an image reference to a content digest by querying the registry.
+ * Uses `docker buildx imagetools inspect`, which returns the index/manifest
+ * digest (correct for multi-arch images). Already-pinned refs short-circuit.
+ */
+declare function resolveDigest(ref: string): Promise<string>;
+interface ResolveResult {
+    /** A copy of the plan with each service image rewritten to its pinned digest. */
+    env: EnvironmentPlan;
+    images: ResolvedImage[];
+}
+/**
+ * Resolve every registry-backed image in an environment to a pinned digest.
+ * Services with a local `build` context (and imageless services) are skipped —
+ * their images may not exist in any registry.
+ */
+declare function resolveEnvironmentImages(env: EnvironmentPlan): Promise<ResolveResult>;
+
+/** Everything deploying to a target implies: defaults, env overrides, and execution context. */
+interface TargetRuntime {
+    name: string;
+    backend?: BackendName;
+    pull?: PullPolicy;
+    /** Target env overrides (merged over globalEnv + env, under service env). */
+    env: EnvMap;
+    /** Prepended to `docker …` invocations (e.g. ["--context", "prod"]). */
+    dockerContextArgs: string[];
+    /** Prepended to `kubectl …` invocations. */
+    kubectlContextArgs: string[];
+    /** Extra env injected into spawned processes (DOCKER_HOST / KUBECONFIG). */
+    processEnv: Record<string, string>;
+}
+declare function resolveTarget(config: KaupangConfig, name: string, rootDir: string): TargetRuntime;
+interface AppliedAction {
+    file: string;
+    args: string[];
+    input?: string;
+    env?: Record<string, string>;
+}
+/** Apply a target's context flags + process env to a backend action. */
+declare function applyTarget(action: BackendAction, rt: TargetRuntime): AppliedAction;
+
+interface DeploymentRecord {
+    id: string;
+    environment: string;
+    /** Where it was deployed (defaults to "local"). Scopes the history. */
+    target: string;
+    backend: BackendName;
+    project: string;
+    ranAt: string;
+    status: "succeeded" | "failed";
+    /** When this deployment was a rollback, the id it restored. */
+    rollbackOf?: string;
+    /** The digests actually deployed (for display + auditing). */
+    images: ResolvedImage[];
+    /** Exactly what was applied, so a rollback replays it verbatim. */
+    files: {
+        path: string;
+        content: string;
+    }[];
+    up: BackendAction[];
+    down: BackendAction[];
+}
+interface Ledger {
+    version: number;
+    /** Keyed by `${environment}@${target}`. */
+    deployments: Record<string, DeploymentRecord[]>;
+}
+declare function readLedger(cacheDir: string): Ledger;
+/** Sortable, human-ish id, e.g. "20260612T103045-a1b2". */
+declare function newDeploymentId(date?: Date): string;
+declare function appendDeployment(cacheDir: string, record: DeploymentRecord): void;
+declare function history(cacheDir: string, environment: string, target: string): DeploymentRecord[];
+declare function latestSuccessful(cacheDir: string, environment: string, target: string): DeploymentRecord | undefined;
+/**
+ * The deployment to roll back TO. With `toId`, that exact (successful) record;
+ * otherwise the second-most-recent successful deployment (i.e. "the previous one").
+ */
+declare function rollbackTarget(cacheDir: string, environment: string, target: string, toId?: string): DeploymentRecord | undefined;
+
+interface ResolvedSolution {
+    name: string;
+    version?: string;
+    /** Top-level environments to deploy (their dependencies are resolved later). */
+    environments: string[];
+    /** Per-service image overrides, keyed by "environment.service". */
+    pins: Record<string, string>;
+    /** Env overlay applied across the solution. */
+    env: EnvMap;
+    /** Default target, if the recipe declares one. */
+    target?: string;
+}
+/**
+ * Resolve a solution by name. Inline `config.solutions` wins over the catalog,
+ * so a repo can override or define solutions locally; otherwise it falls back to
+ * the hosted catalog (the `service` / `http` / `file` sources).
+ */
+declare function resolveSolution(config: KaupangConfig, catalog: CatalogResolver, name: string): Promise<ResolvedSolution>;
+/** Override service images from solution pins (keyed by "environment.service"). */
+declare function applyPins(plan: DeploymentPlan, pins: Record<string, string>): void;
+
+declare const BUNDLE_MANIFEST = "manifest.json";
+declare function isOciRef(ref: string): boolean;
+interface BundleEnvironment {
+    name: string;
+    backend: BackendName;
+    images: ResolvedImage[];
+    /** Generated artifact, stored inside the bundle (path is bundle-relative). */
+    artifact: {
+        relPath: string;
+        content: string;
+    };
+    /** Commands whose file argument references `artifact.relPath` (bundle-relative). */
+    up: BackendAction[];
+    down: BackendAction[];
+}
+interface BundleManifest {
+    kaupang: string;
+    solution: string;
+    version?: string;
+    target: string;
+    project: string;
+    createdAt: string;
+    /** Whether image tarballs are included (airgap export). */
+    images: {
+        included: boolean;
+        tars: string[];
+    };
+    environments: BundleEnvironment[];
+}
+/**
+ * Rewrite a backend action's file argument from an absolute path to a
+ * bundle-relative one (used at bundle time), or back (at deploy time).
+ */
+declare function rewriteActionPath(action: BackendAction, from: string, to: string): BackendAction;
+declare function writeBundle(dir: string, manifest: BundleManifest): void;
+declare function readBundle(dir: string): BundleManifest;
+/** Package a bundle directory and push it as a single OCI artifact via oras. */
+declare function pushBundle(dir: string, ociRef: string): Promise<void>;
+/** Pull an OCI bundle artifact and extract it; returns the local bundle dir. */
+declare function pullBundle(ociRef: string, intoParent: string): Promise<string>;
+
+/** Render the full plan for a dry-run: environment graph + service waves + commands. */
+declare function renderPlan(plan: DeploymentPlan, ctx: BackendContext, rt?: TargetRuntime): void;
+
+interface RunOptions {
+    cwd: string;
+    /** When true, print the command but do not execute it. */
+    dryRun?: boolean;
+    /** Extra environment for the spawned process. */
+    env?: Record<string, string>;
+    /** Optional string piped to the process stdin (used for `kubectl apply -f -`). */
+    input?: string;
+}
+/** Toggle command echoing (set from the CLI's --verbose flag). */
+declare function setVerbose(value: boolean): void;
+/** Run a command with execa, echoing it first (verbose / dry-run). Honors dry-run. */
+declare function run(file: string, args: string[], opts: RunOptions): Promise<void>;
+/**
+ * True if a binary is resolvable on PATH (or is an existing absolute/relative path).
+ * Resolved by scanning PATH rather than spawning `<tool> --version` — the latter is
+ * unreliable cross-tool (`kubectl --version` is an unknown flag) and cross-platform
+ * (on Windows a missing binary and a bad flag both surface as a generic exit 1).
+ */
+declare function hasBinary(file: string): Promise<boolean>;
+/** Run a shell command (used for lifecycle hooks). Honors dry-run. */
+declare function runShell(command: string, opts: RunOptions): Promise<void>;
+/**
+ * The command-execution boundary. The real implementation shells out via execa;
+ * tests inject a fake that records calls, so the deploy/pipeline layers can be
+ * exercised — asserting which commands run, in what order, with which context —
+ * without a Docker daemon. Keep this surface tiny: it is the only seam between
+ * kaupang's pure logic and the outside world's side effects.
+ */
+interface Executor {
+    run(file: string, args: string[], opts: RunOptions): Promise<void>;
+    runShell(command: string, opts: RunOptions): Promise<void>;
+    hasBinary(file: string): Promise<boolean>;
+}
+/** The real executor: execa-backed `run` / `runShell` / `hasBinary`. */
+declare const defaultExecutor: Executor;
+/** Parse "500ms" / "2s" / "5m" / "1h" into milliseconds. Bare numbers are seconds. */
+declare function parseDuration(value: string | number): number;
+
+interface DeployOptions {
+    targetName: string;
+    targetEnv: EnvMap;
+    pull?: PullPolicy;
+    /** Resolve image references to pinned digests before deploying. */
+    resolve: boolean;
+}
+/**
+ * Bring up every environment in a plan: validate secrets, run hooks, resolve +
+ * pin images, materialize, apply the target context, and record the ledger.
+ * Shared by `kaupang up` and pipeline `up` steps so behavior is identical.
+ */
+declare function deployPlan(loaded: LoadedConfig, plan: DeploymentPlan, rt: TargetRuntime, opts: DeployOptions, executor?: Executor): Promise<DeploymentRecord[]>;
+
+interface RunPipelineOptions {
+    target?: string;
+    dryRun: boolean;
+}
+declare function runPipeline(loaded: LoadedConfig, name: string, opts: RunPipelineOptions, executor?: Executor): Promise<void>;
+
+declare function isSecret(value: EnvValue): value is SecretRef;
+/** Merge env maps left → right (later wins). Secret references are preserved. */
+declare function mergeEnv(...maps: (EnvMap | undefined)[]): EnvMap;
+/**
+ * Render for Docker Compose / Swarm: literals pass through, secrets become
+ * `${SOURCE}` interpolation references that Docker resolves at runtime from the
+ * process environment. The secret value is never written into the file.
+ */
+declare function renderComposeEnv(env: EnvMap): Record<string, string>;
+/** Distinct host env var names referenced by secrets across the given maps. */
+declare function requiredSecretVars(...maps: (EnvMap | undefined)[]): string[];
+
+/** Run a list of hook commands sequentially, relative to rootDir. */
+declare function runHooks(commands: HookCommand[] | undefined, opts: {
+    rootDir: string;
+    dryRun?: boolean;
+    executor?: Executor;
+}): Promise<void>;
+
+/** Lowercase, replace illegal chars; safe for compose projects + swarm stacks. */
+declare function sanitize(name: string): string;
+/** RFC 1123 label, used for kubernetes namespaces and resource names. */
+declare function k8sName(name: string): string;
+/** "project_env" stack/project identifier. */
+declare function stackName(project: string, env: string): string;
+
+export { type AppliedAction, BUNDLE_MANIFEST, type Backend, type BackendAction, type BackendContext, BackendName, type BundleEnvironment, type BundleManifest, CatalogConfig, type CatalogManifest, type CatalogResolver, type CatalogSource, Dependable, type DeployOptions, type DeploymentPlan, type DeploymentRecord, EnvMap, EnvValue, EnvironmentDefinition, type EnvironmentPlan, type Executor, HookCommand, Hooks, KaupangConfig, type Ledger, type LoadedConfig, type MaterializedEnvironment, type NormalizedEnvironment, PullPolicy, type ResolveResult, type ResolvedEnvironment, type ResolvedImage, type ResolvedSolution, type RunOptions, SecretRef, ServiceDefinition, ServiceSpec, SolutionRecipe, type TargetRuntime, appendDeployment, applyPins, applyTarget, backendNames, createCatalogResolver, defaultExecutor, deployPlan, findConfig, getBackend, hasBinary, history, isOciRef, isPinned, isSecret, k8sName, latestSuccessful, loadConfig, makeContext, mergeEnv, newDeploymentId, normalizeEnvironment, parseDuration, pullBundle, pushBundle, readBundle, readLedger, renderComposeEnv, renderPlan, requiredSecretVars, resolveDigest, resolveEnvironmentImages, resolveImage, resolveMultiPlan, resolvePlan, resolveSolution, resolveTarget, rewriteActionPath, rollbackTarget, run, runHooks, runPipeline, runShell, sanitize, setVerbose, stackName, toArray, topoSort, writeBundle };