@podosoft/podokit 0.16.4 → 0.17.1

package/dist/deploy-compose-sync.js

@@ -0,0 +1,412 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeSyncArtifacts = composeSyncArtifacts;
+exports.excludesWithin = excludesWithin;
+exports.runtimeDependenciesOf = runtimeDependenciesOf;
+exports.planComposeSync = planComposeSync;
+exports.syncComposeDeployment = syncComposeDeployment;
+exports.readComposeSyncDrift = readComposeSyncDrift;
+exports.revertComposeSync = revertComposeSync;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const deploy_compose_exec_1 = require("./deploy-compose-exec");
+const deploy_compose_render_1 = require("./deploy-compose-render");
+const deploy_driver_1 = require("./deploy-driver");
+const lockfile_1 = require("./lockfile");
+/** Where the marker lands. `/app` is the image's root for every generated service. */
+const MARKER_PATH = "/app/.podokit-sync.json";
+const MARKER_NOTE = "Locally built artifacts were copied into this container. It is not running the code its image tag describes. Recreate the container to restore the image.";
+const DEFAULT_HEALTH_TIMEOUT_MS = 120_000;
+const HEALTH_POLL_INTERVAL_MS = 2_000;
+/**
+ * What the images ship outside their dependency tree.
+ *
+ * Every entry mirrors a `COPY --from=build` line in the generated Dockerfiles, which
+ * is what makes the copy equivalent to a rebuild for code-only changes. Two entries
+ * exist for a reason worth keeping:
+ *
+ * - `apps/web/server.js` and `apps/web/src/lib/server` ship as SOURCE, outside the
+ *   bundle, because the entry point has to run before the adapter does. Syncing only
+ *   `build/` would leave a stale entry running new routes.
+ * - `packages/*` are copied as real directories rather than the symlinks npm leaves
+ *   behind, so their `dist/` is a separate destination from the apps'.
+ *
+ * `node_modules` is deliberately absent: the image installs a production-only,
+ * workspace-scoped tree for its own platform, and a developer's tree is neither.
+ */
+function composeSyncArtifacts(projectRoot) {
+    const artifacts = [];
+    const push = (source, destination, kind, roles) => {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, source))) {
+            artifacts.push({ source, destination, kind, roles });
+        }
+    };
+    const packagesDir = (0, node_path_1.join)(projectRoot, "packages");
+    if ((0, node_fs_1.existsSync)(packagesDir)) {
+        for (const entry of (0, node_fs_1.readdirSync)(packagesDir).sort()) {
+            if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(packagesDir, entry, "package.json")))
+                continue;
+            push(`packages/${entry}/dist`, `/app/packages/${entry}/dist`, "directory", ["api", "web", "worker"]);
+        }
+    }
+    push("apps/api/dist", "/app/apps/api/dist", "directory", ["api", "worker"]);
+    push("apps/api/scripts", "/app/apps/api/scripts", "directory", ["api", "worker"]);
+    push("apps/web/build", "/app/apps/web/build", "directory", ["web"]);
+    push("apps/web/server.js", "/app/apps/web/server.js", "file", ["web"]);
+    push("apps/web/src/lib/server", "/app/apps/web/src/lib/server", "directory", ["web"]);
+    return artifacts;
+}
+/** The excludes that fall inside one artifact, as paths relative to it. */
+function excludesWithin(artifact, excludes) {
+    const prefix = `${artifact.source}/`;
+    return excludes
+        .filter((entry) => entry.startsWith(prefix))
+        .map((entry) => entry.slice(prefix.length));
+}
+/**
+ * Whether the image's dependency tree can still run this code.
+ *
+ * Only the runtime dependency sets matter: `npm ci --omit=dev` installed what these
+ * declare and nothing else, so a change to any of them means the container is
+ * missing a package the new code imports -- a failure that surfaces as a crash loop
+ * after the restart rather than as a copy error. `devDependencies` are absent from
+ * the image by design and a `version` bump changes nothing at runtime, so neither
+ * takes part.
+ */
+function runtimeDependenciesOf(manifest) {
+    return JSON.stringify({
+        dependencies: manifest.dependencies ?? {},
+        optionalDependencies: manifest.optionalDependencies ?? {},
+        peerDependencies: manifest.peerDependencies ?? {},
+    });
+}
+/** The manifests whose runtime dependencies a role's container was built from. */
+function manifestPathsFor(projectRoot, role) {
+    const app = role === "web" ? "web" : "api";
+    const pairs = [
+        [(0, node_path_1.join)(projectRoot, "apps", app, "package.json"), `/app/apps/${app}/package.json`],
+    ];
+    const packagesDir = (0, node_path_1.join)(projectRoot, "packages");
+    if ((0, node_fs_1.existsSync)(packagesDir)) {
+        for (const entry of (0, node_fs_1.readdirSync)(packagesDir).sort()) {
+            const local = (0, node_path_1.join)(packagesDir, entry, "package.json");
+            if ((0, node_fs_1.existsSync)(local))
+                pairs.push([local, `/app/packages/${entry}/package.json`]);
+        }
+    }
+    return pairs;
+}
+function inspectContainer(profile, container, runner) {
+    const output = (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, ["inspect", container, "--format", "{{json .}}"]));
+    return (0, deploy_compose_exec_1.parseJson)(output, `docker inspect ${container}`);
+}
+/**
+ * The running container for a Compose service, found by label rather than by name.
+ *
+ * Compose derives container names from the project, the service and an index, and a
+ * project whose name is also the service prefix produces names that look duplicated.
+ * Reconstructing that string is guesswork; the labels are what Compose itself
+ * matches on.
+ */
+function findContainer(profile, service, runner) {
+    const output = (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, [
+        "ps",
+        "--filter",
+        `label=com.docker.compose.project=${profile.target.project}`,
+        "--filter",
+        `label=com.docker.compose.service=${service}`,
+        "--format",
+        "{{.Names}}",
+    ]));
+    const names = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return names[0] ?? null;
+}
+function rolesOf(profile) {
+    return profile.workloads.worker ? ["api", "web", "worker"] : ["api", "web"];
+}
+function planComposeSync(projectRoot, profileName, runner = deploy_compose_exec_1.defaultRunner) {
+    const profile = (0, deploy_driver_1.loadComposeProfile)(projectRoot, profileName);
+    const excluded = profile.sync?.exclude ?? [];
+    const artifacts = composeSyncArtifacts(projectRoot);
+    const warnings = [];
+    const targets = [];
+    for (const role of rolesOf(profile)) {
+        const service = (0, deploy_compose_render_1.serviceName)(profile, role);
+        const container = findContainer(profile, service, runner);
+        if (!container) {
+            warnings.push(`Service ${service} has no running container; it is skipped.`);
+            continue;
+        }
+        const inspected = inspectContainer(profile, container, runner);
+        targets.push({ role, service, container, user: inspected.Config?.User?.trim() || null });
+    }
+    warnings.push("Restarting a container drops every connection it is serving, including WebSocket sessions.");
+    warnings.push("This does not run migrations. A change that needs one belongs in a release, not a sync.");
+    return {
+        profile: profileName,
+        project: profile.target.project,
+        artifacts,
+        excluded,
+        targets,
+        warnings,
+    };
+}
+/**
+ * Build what the images build, in the order the images build it.
+ *
+ * Not the root `build` script: npm runs workspaces in the order the root manifest
+ * lists them, and `apps/*` is conventionally listed before `packages/*`. An app then
+ * compiles against a workspace package's previous output, or against none at all.
+ * The Dockerfiles build every package first for exactly this reason.
+ */
+function buildArtifacts(projectRoot, runner) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    const pm = manifest?.packageManager ?? "npm";
+    const packagesDir = (0, node_path_1.join)(projectRoot, "packages");
+    if ((0, node_fs_1.existsSync)(packagesDir)) {
+        for (const entry of (0, node_fs_1.readdirSync)(packagesDir).sort()) {
+            if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(packagesDir, entry, "package.json")))
+                continue;
+            (0, deploy_compose_exec_1.checked)(runner, pm, ["run", "build", "--if-present", "--workspace", `packages/${entry}`], false);
+        }
+    }
+    for (const app of ["api", "web"]) {
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, "apps", app, "package.json")))
+            continue;
+        (0, deploy_compose_exec_1.checked)(runner, pm, ["run", "build", "--if-present", "--workspace", `apps/${app}`], false);
+    }
+}
+function assertNoManifestDrift(projectRoot, profile, targets, runner) {
+    const drifted = [];
+    for (const target of targets) {
+        for (const [local, inContainer] of manifestPathsFor(projectRoot, target.role)) {
+            const result = runner("docker", (0, deploy_compose_exec_1.dockerArgs)(profile, ["exec", target.container, "cat", inContainer]), { capture: true });
+            if (result.status !== 0) {
+                drifted.push(`${target.container}:${inContainer} could not be read`);
+                continue;
+            }
+            const deployed = runtimeDependenciesOf((0, deploy_compose_exec_1.parseJson)(result.stdout, `${target.container}:${inContainer}`));
+            const current = runtimeDependenciesOf(JSON.parse((0, node_fs_1.readFileSync)(local, "utf8")));
+            if (deployed !== current)
+                drifted.push(`${inContainer} (in ${target.container})`);
+        }
+    }
+    if (drifted.length) {
+        throw new Error("Runtime dependencies have changed since these containers were built, so their node_modules " +
+            `cannot run this code: ${drifted.join(", ")}. Build and deploy a release instead.`);
+    }
+}
+/**
+ * A copy of one artifact with the excluded paths removed.
+ *
+ * `docker cp` has no exclude, and it merges rather than replaces -- so filtering has
+ * to happen before the copy. Staging costs one local copy of a few megabytes and
+ * keeps the rule in one place.
+ */
+function stageArtifact(projectRoot, artifact, excludes) {
+    const source = (0, node_path_1.join)(projectRoot, artifact.source);
+    const within = excludesWithin(artifact, excludes);
+    if (artifact.kind === "file" || within.length === 0) {
+        return { path: source, cleanup: () => undefined };
+    }
+    const staging = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "podokit-sync-"));
+    const staged = (0, node_path_1.join)(staging, "artifact");
+    (0, node_fs_1.cpSync)(source, staged, { recursive: true });
+    for (const relative of within)
+        (0, node_fs_1.rmSync)((0, node_path_1.join)(staged, relative), { recursive: true, force: true });
+    return { path: staged, cleanup: () => (0, node_fs_1.rmSync)(staging, { recursive: true, force: true }) };
+}
+async function waitForContainer(profile, container, timeoutMs, runner) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const inspected = inspectContainer(profile, container, runner);
+        const health = inspected.State?.Health?.Status;
+        const status = inspected.State?.Status ?? "unknown";
+        // A container without a HEALTHCHECK reports no health at all, and waiting for a
+        // status it will never publish would hang every sync on such an image.
+        if (health === "healthy")
+            return { state: health, ok: true };
+        if (!health && status === "running")
+            return { state: status, ok: true };
+        if (health === "unhealthy")
+            return { state: health, ok: false };
+        if (Date.now() >= deadline)
+            return { state: health ?? status, ok: false };
+        await new Promise((resolve) => setTimeout(resolve, HEALTH_POLL_INTERVAL_MS));
+    }
+}
+async function syncComposeDeployment(projectRoot, profileName, options = {}, runner = deploy_compose_exec_1.defaultRunner) {
+    const profile = (0, deploy_driver_1.loadComposeProfile)(projectRoot, profileName);
+    const holder = (0, deploy_compose_exec_1.composeLockHolder)(profile, runner);
+    if (holder) {
+        throw new Error(`Deployment lock for ${profile.target.project} is held by ${holder}. A release is in progress; wait for it to finish.`);
+    }
+    if (options.build)
+        buildArtifacts(projectRoot, runner);
+    const plan = planComposeSync(projectRoot, profileName, runner);
+    if (!plan.targets.length) {
+        throw new Error(`No running container found for Compose project ${profile.target.project}. Deploy a release before syncing into it.`);
+    }
+    if (!plan.artifacts.length) {
+        throw new Error("No build output to sync. Build the project first, or pass --build to build it here.");
+    }
+    if (options.clean) {
+        const conflicting = plan.artifacts.filter((artifact) => excludesWithin(artifact, plan.excluded).length > 0);
+        if (conflicting.length) {
+            throw new Error(`--clean cannot be used while ${conflicting.map((a) => a.source).join(", ")} contains an excluded path: ` +
+                "emptying the destination would delete artifacts this machine cannot rebuild.");
+        }
+    }
+    assertNoManifestDrift(projectRoot, profile, plan.targets, runner);
+    const copied = [];
+    for (const artifact of plan.artifacts) {
+        const staged = stageArtifact(projectRoot, artifact, plan.excluded);
+        try {
+            for (const target of plan.targets) {
+                if (!artifact.roles.includes(target.role))
+                    continue;
+                if (options.clean && artifact.kind === "directory") {
+                    (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, [
+                        "exec",
+                        "--user",
+                        "0:0",
+                        target.container,
+                        "sh",
+                        "-c",
+                        `rm -rf ${artifact.destination}/* ${artifact.destination}/.[!.]*  2>/dev/null || true`,
+                    ]));
+                }
+                // `<dir>/.` copies the CONTENTS into an existing directory; without it the
+                // directory would be nested one level deeper on every sync.
+                const source = artifact.kind === "directory" ? `${staged.path}/.` : staged.path;
+                (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, ["cp", source, `${target.container}:${artifact.destination}`]));
+                // `docker cp` without --archive gives the files to the daemon's root, and
+                // these images run as an unprivileged user. Readable is not enough for a
+                // directory the application also has to traverse.
+                if (target.user) {
+                    (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, [
+                        "exec",
+                        "--user",
+                        "0:0",
+                        target.container,
+                        "chown",
+                        "-R",
+                        target.user,
+                        artifact.destination,
+                    ]));
+                }
+                copied.push({
+                    container: target.container,
+                    source: artifact.source,
+                    destination: artifact.destination,
+                });
+            }
+        }
+        finally {
+            staged.cleanup();
+        }
+    }
+    const now = options.now ?? (() => new Date());
+    const marker = {
+        syncedAt: now().toISOString(),
+        profile: profileName,
+        artifacts: plan.artifacts.map((artifact) => artifact.source),
+        note: MARKER_NOTE,
+    };
+    const markerDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "podokit-sync-marker-"));
+    const markerFile = (0, node_path_1.join)(markerDir, "marker.json");
+    (0, node_fs_1.writeFileSync)(markerFile, `${JSON.stringify(marker, null, 2)}\n`);
+    try {
+        for (const target of plan.targets) {
+            (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, ["cp", markerFile, `${target.container}:${MARKER_PATH}`]));
+        }
+    }
+    finally {
+        (0, node_fs_1.rmSync)(markerDir, { recursive: true, force: true });
+    }
+    const restarted = [];
+    for (const target of plan.targets) {
+        (0, deploy_compose_exec_1.checked)(runner, "docker", (0, deploy_compose_exec_1.dockerArgs)(profile, ["restart", target.container]));
+        restarted.push(target.container);
+    }
+    // A sync that leaves a container unable to come back is a failed sync, and saying
+    // so is the whole value of waiting: the copy already happened, so the operator has
+    // to know the deployment is now serving from artifacts that do not work.
+    const unhealthy = [];
+    for (const target of plan.targets) {
+        const health = await waitForContainer(profile, target.container, options.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS, runner);
+        if (!health.ok)
+            unhealthy.push(`${target.container} (${health.state})`);
+    }
+    if (unhealthy.length) {
+        throw new Error(`Restarted container(s) did not become healthy: ${unhealthy.join(", ")}. ` +
+            "The synced artifacts are still in place; podo deploy sync --revert restores the image.");
+    }
+    return { plan, copied, restarted, marker };
+}
+/**
+ * Which containers are running synced artifacts rather than their image's.
+ *
+ * Reporting-only, so it never throws: `podo deploy status` folds this in, and a
+ * target that cannot answer right now is a reason to report less, not a reason for
+ * status to fail. An empty result therefore means "no drift found", which is also
+ * what an unreachable target produces -- the services list beside it already shows
+ * that case for what it is.
+ */
+function readComposeSyncDrift(projectRoot, profileName, runner = deploy_compose_exec_1.defaultRunner) {
+    const profile = (0, deploy_driver_1.loadComposeProfile)(projectRoot, profileName);
+    const drift = [];
+    for (const role of rolesOf(profile)) {
+        try {
+            const container = findContainer(profile, (0, deploy_compose_render_1.serviceName)(profile, role), runner);
+            if (!container)
+                continue;
+            const result = runner("docker", (0, deploy_compose_exec_1.dockerArgs)(profile, ["exec", container, "cat", MARKER_PATH]), {
+                capture: true,
+            });
+            if (result.status !== 0 || !result.stdout.trim())
+                continue;
+            drift.push({
+                container,
+                marker: (0, deploy_compose_exec_1.parseJson)(result.stdout, `${container}:${MARKER_PATH}`),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return drift;
+}
+/**
+ * Put the deployment back on its image.
+ *
+ * The release to restore comes from the ledger, and the project is rendered from
+ * that entry's own release, images and rollout state -- the same way a rollback
+ * reproduces a revision.
+ *
+ * ⚠ Not from the Compose file sitting on the target, which was the first attempt.
+ * That file is written by whichever command last ran a compose mutation, and one of
+ * them renders a placeholder release to obtain a file path. The revert then tried to
+ * pull an image tag that never existed and refused to recreate anything. Measured
+ * against a live deployment; the read path was fixed at the same time so a status
+ * call can no longer overwrite the target's project.
+ */
+async function revertComposeSync(projectRoot, profileName, runner = deploy_compose_exec_1.defaultRunner) {
+    const profile = (0, deploy_driver_1.loadComposeProfile)(projectRoot, profileName);
+    const probe = (0, deploy_compose_exec_1.probeImage)(profile);
+    if (!probe) {
+        throw new Error("Cannot read the release ledger: no managed dependency image to borrow a shell from.");
+    }
+    const current = (0, deploy_compose_exec_1.currentLedgerEntry)((0, deploy_compose_exec_1.readLedger)(profile, probe, runner));
+    if (!current) {
+        throw new Error("No release has been applied to this deployment, so there is no image state to restore.");
+    }
+    const runtime = (0, deploy_compose_render_1.renderComposeDeployment)(projectRoot, profileName, profile, current.release, current.images, current.rolloutStateDigest);
+    const services = rolesOf(profile).map((role) => (0, deploy_compose_render_1.serviceName)(profile, role));
+    (0, deploy_compose_exec_1.runCompose)(profile, runtime, "compose", ["up", "-d", "--force-recreate", "--wait", ...services], runner, false);
+    return { services, project: profile.target.project, release: current.release };
+}

package/dist/deploy-compose.d.ts

@@ -0,0 +1,98 @@
+import type { CommandRunner } from "./dev";
+import { type ComposeSyncDrift } from "./deploy-compose-sync";
+import { type ComposeImages } from "./deploy-compose-render";
+/**
+ * The Docker Compose deployment driver.
+ *
+ * Every safety property the Kubernetes driver has is reproduced here with the
+ * primitives Compose offers: a fingerprint pins the target endpoint, a plan binds
+ * resolved image digests and rendered bytes to one hash that apply must echo back, a
+ * lock file in a state volume replaces the Kubernetes Lease, and a release ledger in
+ * that same volume replaces Helm revisions.
+ */
+export interface ComposeDoctorFinding {
+    code: string;
+    ok: boolean;
+    message: string;
+}
+export interface ComposePlanAction {
+    order: number;
+    kind: "dependencies" | "migration" | "application" | "verification" | "rollback";
+    description: string;
+}
+export interface ComposePlan {
+    profile: string;
+    release: string;
+    planHash: string;
+    profileDigest: string;
+    currentRevision: number | null;
+    currentRelease: string | null;
+    hostStateDigest: string;
+    rolloutStateDigest: string;
+    composeDocumentDigest: string;
+    target: {
+        context: string;
+        endpointFingerprint: string;
+        project: string;
+    };
+    images: ComposeImages;
+    actions: ComposePlanAction[];
+    warnings: string[];
+}
+export interface ComposeStatus {
+    profile: string;
+    revision: number | null;
+    release: string | null;
+    services: Array<{
+        name: string;
+        running: number;
+        desired: number;
+        images: string[];
+        health: string;
+        restartCount: number;
+    }>;
+    /**
+     * Containers running locally synced artifacts instead of their image's.
+     *
+     * Reported beside the release because the two disagree when it is non-empty: the
+     * tag says one thing and the running code is another. Empty is the normal state.
+     */
+    syncDrift: ComposeSyncDrift[];
+}
+export interface ComposeVerificationResult {
+    profile: string;
+    baseUrl: string;
+    ok: boolean;
+    paths: Array<{
+        path: string;
+        status: number | null;
+        ok: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * The endpoint identity a profile is pinned to.
+ *
+ * The Kubernetes driver fingerprints the cluster server and CA; the closest stable
+ * equivalent here is the context's Docker endpoint plus the daemon's own ID, so
+ * repointing a context at a different host invalidates the profile instead of
+ * silently deploying somewhere else.
+ */
+export declare function inspectComposeEndpointFingerprint(context: string, runner?: CommandRunner): string;
+export declare function doctorComposeDeployment(projectRoot: string, profileName: string, runner?: CommandRunner, release?: string): ComposeDoctorFinding[];
+export declare function planComposeDeployment(projectRoot: string, profileName: string, release: string, runner?: CommandRunner): ComposePlan;
+export declare function applyComposeDeployment(projectRoot: string, profileName: string, release: string, confirm: string, runner?: CommandRunner, fetcher?: typeof fetch): Promise<{
+    plan: ComposePlan;
+    status: ComposeStatus;
+    verification: ComposeVerificationResult;
+}>;
+export declare function getComposeStatus(projectRoot: string, profileName: string, runner?: CommandRunner): ComposeStatus;
+export declare function verifyComposeDeployment(projectRoot: string, profileName: string, fetcher?: typeof fetch): Promise<ComposeVerificationResult>;
+export declare function planComposeRollback(projectRoot: string, profileName: string, revision: number, runner?: CommandRunner): ComposePlan;
+export declare function rollbackComposeDeployment(projectRoot: string, profileName: string, revision: number, confirm: string, runner?: CommandRunner, fetcher?: typeof fetch): Promise<{
+    plan: ComposePlan;
+    status: ComposeStatus;
+    verification: ComposeVerificationResult;
+}>;
+/** Where the rendered project lands, for callers that want to show it. */
+export declare function composeRuntimeRoot(projectRoot: string, profileName: string): string;