@flisk-sh/flisk-export 0.1.0 → 0.2.0

package/README.md

@@ -37,6 +37,19 @@ npm install
 npm run typecheck && npm run lint && npm run build && npm test
 ```
 
+## Compose
+
+```sh
+flisk-export compose            # writes .autogenerated/docker-compose.yml
+flisk-export compose --check    # exit 1 when that file is out of date (for CI)
+```
+
+Writes a **standalone** `docker-compose.yml` from the bring-your-own `service.json` files (`image` or `dockerfile`, `env`,
+`volumes`, `extraPorts`, `dependsOn`, `sidecarOf`, `container`). It runs with plain `docker compose up` and no Flisk: no external
+networks, no `FLISK_*` variables, no generated secrets. `${VAR}` references in `env` pass through for Compose to read from `.env`.
+Other resource types and `command` (native) services are not exported. The file is generated: change `service.json` and run it
+again with `--force`. It never starts a container or calls an API.
+
 ## License
 
 MIT

package/dist/compose.js

@@ -0,0 +1,199 @@
+/**
+ * Builds a standalone docker-compose.yml from the bring-your-own service.json files of a Flisk project.
+ *
+ * The result runs with plain `docker compose up` and no Flisk: no external networks, no injected Flisk variables and no
+ * generated secrets. `${VAR}` references in `env` pass through for Compose to resolve from the project `.env`. These
+ * functions only return text; nothing here starts a container, deploys or calls an API.
+ */
+import { relative, sep } from "node:path";
+import { ExportError } from "./errors.js";
+/** The only resource type the Compose export covers: it is the one whose service.json is a Compose service. */
+export const COMPOSE_TYPE = "bring-your-own";
+const RESTART_POLICIES = new Set(["no", "on-failure", "unless-stopped", "always"]);
+const SERVICE_NAME = /^[a-z0-9][a-z0-9_.-]*$/i;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SHM_SIZE = /^\d+(b|k|kb|m|mb|g|gb)?$/i;
+export function isComposeExportable(resource) {
+    return resource.type === COMPOSE_TYPE && typeof resource.config.command !== "string";
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** A YAML double-quoted scalar. JSON strings are valid ones; `$` is kept so Compose can interpolate. */
+function q(value) {
+    return JSON.stringify(value);
+}
+function relPath(from, to) {
+    const rel = relative(from, to).split(sep).join("/");
+    return rel === "" ? "." : rel;
+}
+/** A host path written for a Compose file in `outDir`: `./x` for children, `../x` for parents. */
+function hostPath(outDir, absolute) {
+    const rel = relPath(outDir, absolute);
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function isNamedVolume(source) {
+    return !/[\\/]/.test(source) && !source.startsWith(".") && !source.startsWith("~");
+}
+function serviceLines(resource, outDir, known) {
+    const c = resource.config;
+    const name = resource.name;
+    if (!SERVICE_NAME.test(name)) {
+        throw new ExportError(`"${name}" is not a valid Compose service name`, [
+            "Use letters, digits, dashes, dots and underscores",
+        ]);
+    }
+    const lines = [`  ${name}:`];
+    const namedVolumes = new Set();
+    const image = typeof c.image === "string" && c.image ? c.image : undefined;
+    const dockerfile = typeof c.dockerfile === "string" && c.dockerfile ? c.dockerfile : undefined;
+    const buildContext = typeof c.buildContext === "string" ? c.buildContext : undefined;
+    if (image)
+        lines.push(`    image: ${q(image)}`);
+    if (dockerfile || !image) {
+        const context = hostPath(outDir, resolveFrom(resource.path, buildContext ?? "."));
+        lines.push("    build:", `      context: ${q(context)}`);
+        if (dockerfile)
+            lines.push(`      dockerfile: ${q(dockerfile)}`);
+    }
+    const container = record(c.container);
+    if (container.init !== false)
+        lines.push("    init: true");
+    if (typeof c.restart === "string") {
+        if (!RESTART_POLICIES.has(c.restart)) {
+            throw new ExportError(`${name}: restart "${c.restart}" is not a Compose restart policy`);
+        }
+        lines.push(`    restart: ${q(c.restart)}`);
+    }
+    else {
+        lines.push('    restart: "unless-stopped"');
+    }
+    const sidecarOf = typeof c.sidecarOf === "string" ? c.sidecarOf : undefined;
+    if (sidecarOf) {
+        if (!known.has(sidecarOf)) {
+            throw new ExportError(`${name}: sidecarOf "${sidecarOf}" is not a bring-your-own resource`);
+        }
+        lines.push(`    network_mode: ${q(`service:${sidecarOf}`)}`);
+    }
+    const env = record(c.env);
+    const envNames = Object.keys(env)
+        .filter((k) => ENV_NAME.test(k))
+        .sort();
+    if (envNames.length > 0) {
+        lines.push("    environment:");
+        for (const key of envNames)
+            lines.push(`      ${key}: ${q(String(env[key]))}`);
+    }
+    const volumes = Array.isArray(c.volumes) ? c.volumes : [];
+    if (volumes.length > 0) {
+        lines.push("    volumes:");
+        for (const raw of volumes) {
+            const v = record(raw);
+            if (typeof v.source !== "string" || typeof v.target !== "string") {
+                throw new ExportError(`${name}: a volume needs a source and a target`);
+            }
+            let source = v.source;
+            if (isNamedVolume(source)) {
+                namedVolumes.add(source);
+            }
+            else {
+                source = hostPath(outDir, resolveFrom(resource.path, source));
+            }
+            lines.push(`      - ${q(`${source}:${v.target}${v.readOnly === true ? ":ro" : ""}`)}`);
+        }
+    }
+    const ports = Array.isArray(c.extraPorts) ? c.extraPorts : [];
+    if (ports.length > 0) {
+        if (sidecarOf) {
+            throw new ExportError(`${name}: a sidecar shares another service's network and cannot publish ports`);
+        }
+        lines.push("    ports:");
+        for (const raw of ports) {
+            const p = record(raw);
+            const port = Number(p.port);
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                throw new ExportError(`${name}: extraPorts needs a port from 1 to 65535`);
+            }
+            const hostPort = p.hostPort === undefined ? port : Number(p.hostPort);
+            const bind = typeof p.bind === "string" && p.bind ? p.bind : "127.0.0.1";
+            const protocol = p.protocol === "udp" ? "udp" : "tcp";
+            lines.push(`      - ${q(`${bind}:${hostPort}:${port}/${protocol}`)}`);
+        }
+    }
+    const dependsOn = strings(c.dependsOn).filter((d) => known.has(d));
+    if (dependsOn.length > 0) {
+        lines.push("    depends_on:", ...dependsOn.map((d) => `      - ${q(d)}`));
+    }
+    const capAdd = strings(container.capAdd);
+    const capDrop = strings(container.capDrop);
+    const securityOpt = strings(container.securityOpt);
+    if (capAdd.length > 0)
+        lines.push("    cap_add:", ...capAdd.map((v) => `      - ${q(v)}`));
+    if (capDrop.length > 0)
+        lines.push("    cap_drop:", ...capDrop.map((v) => `      - ${q(v)}`));
+    if (container.readOnly === true)
+        lines.push("    read_only: true");
+    if (typeof container.user === "string")
+        lines.push(`    user: ${q(container.user)}`);
+    if (securityOpt.length > 0) {
+        lines.push("    security_opt:", ...securityOpt.map((v) => `      - ${q(v)}`));
+    }
+    if (typeof container.shmSize === "string") {
+        if (!SHM_SIZE.test(container.shmSize)) {
+            throw new ExportError(`${name}: shmSize "${container.shmSize}" is not a Compose size`);
+        }
+        lines.push(`    shm_size: ${q(container.shmSize)}`);
+    }
+    return { lines, namedVolumes };
+}
+function resolveFrom(base, rel) {
+    return rel.startsWith("/") ? rel : joinPosix(base, rel);
+}
+function joinPosix(base, rel) {
+    const parts = base.split(sep).concat(rel.split("/"));
+    const out = [];
+    for (const part of parts) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            out.pop();
+        else
+            out.push(part);
+    }
+    return (base.startsWith("/") ? "/" : "") + out.join("/");
+}
+/** The text of a docker-compose.yml for `resources`, written for a file in `outDir`. */
+export function buildCompose(outDir, resources) {
+    const services = resources.filter(isComposeExportable);
+    if (services.length === 0) {
+        throw new ExportError("No bring-your-own resource was found to export", [
+            `Exported type: ${COMPOSE_TYPE} (a service.json with an image or a Dockerfile, and no command)`,
+        ]);
+    }
+    const known = new Set(services.map((s) => s.name));
+    const body = [];
+    const volumes = new Set();
+    for (const service of services) {
+        const built = serviceLines(service, outDir, known);
+        body.push(...built.lines, "");
+        for (const v of built.namedVolumes)
+            volumes.add(v);
+    }
+    const header = [
+        "###############################################################################",
+        "# GENERATED by `flisk export compose` from the service.json files. DO NOT EDIT.",
+        "# Change service.json and run `flisk export compose --force`; CI can run",
+        "# `flisk export compose --check` to fail when this file is out of date.",
+        "# Runs with plain `docker compose up`; Flisk is not needed to start it.",
+        "###############################################################################",
+        "",
+        "services:",
+    ];
+    const tail = volumes.size > 0 ? ["volumes:", ...[...volumes].sort().map((v) => `  ${v}:`), ""] : [];
+    return [...header, ...body, ...tail].join("\n").replace(/\n{3,}/g, "\n\n");
+}

package/dist/main.js

@@ -2,9 +2,10 @@
  * `flisk-export render|wrangler`: writes a deploy file from service.json and stops there. It never deploys, never
  * creates DNS records and never calls a cloud API. The Flisk CLI runs it as `flisk export` at a pinned version.
  */
-import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { Command, CommanderError } from "commander";
+import { buildCompose } from "./compose.js";
 import { discoverResources, findProjectRoot, findRepoRoot, findResource, } from "./discover.js";
 import { ExportError } from "./errors.js";
 import { assertExportable, buildRenderBlueprint, buildWranglerToml, EXPORTABLE_TYPES, isExportable, skippedEnvNames, } from "./generate.js";
@@ -80,6 +81,33 @@ function program(io) {
         const outDir = options.out ? realDir(resolve(io.cwd, options.out)) : repoRoot;
         emit(io, join(outDir, "render.yaml"), content, options);
     });
+    cli
+        .command("compose")
+        .description("Write a standalone docker-compose.yml from bring-your-own service.json files; runs without Flisk, never deploys")
+        .argument("[dir]", "The Flisk project (default: the current directory)")
+        .option("--out <dir>", "Directory to write docker-compose.yml in (default: <project>/.autogenerated)")
+        .option("--dry-run", "Print docker-compose.yml instead of writing it", false)
+        .option("--force", "Replace an existing docker-compose.yml", false)
+        .option("--check", "Exit 1 when the file on disk differs from what would be written", false)
+        .action((dir, options) => {
+        const projectRoot = root(dir);
+        const outDir = options.out
+            ? realDir(resolve(io.cwd, options.out))
+            : join(projectRoot, ".autogenerated");
+        const content = buildCompose(outDir, discover(projectRoot));
+        const file = join(outDir, "docker-compose.yml");
+        if (options.check) {
+            const shown = relative(realDir(io.cwd), file) || file;
+            if (!existsSync(file) || readFileSync(file, "utf-8") !== content) {
+                throw new ExportError(`${shown} is out of date`, [
+                    "Run `flisk export compose --force` and commit the result",
+                ]);
+            }
+            io.out(`${shown} is up to date.\n`);
+            return;
+        }
+        emit(io, file, content, options);
+    });
     cli
         .command("wrangler")
         .description("Write a Cloudflare wrangler.toml for one resource from service.json; never deploys")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flisk-sh/flisk-export",
-  "version": "0.1.0",
-  "description": "Write a Render Blueprint (render.yaml) or a Cloudflare wrangler.toml from Flisk service.json files. Never deploys.",
+  "version": "0.2.0",
+  "description": "Write a Render Blueprint (render.yaml), a Cloudflare wrangler.toml or a standalone docker-compose.yml from Flisk service.json files. Never deploys.",
   "type": "module",
   "license": "MIT",
   "bin": {