@flisk-sh/flisk-export 0.6.0 → 0.8.0

package/README.md

@@ -47,9 +47,9 @@ 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`,
 `secrets.required`, `envFile`, `profiles`, `models`, `volumes`, `extraPorts`, `dependsOn`, `healthCheck`, `sidecarOf`, `container`). It runs without Flisk (`docker compose --env-file .env -f .autogenerated/docker-compose.yml up -d` from the project root, since Compose looks for `.env` next to the file it reads): no external
 networks, no `FLISK_*` variables, no generated secrets. `${VAR}` references in `env`, and every name in `secrets.required`, pass through as `${NAME}` for Compose to read from `.env`.
-A volume's `name` (the Docker volume an install already has) is kept, and the project is named after its stack, so `docker compose up` finds the same data as before.
+A volume's `name` (the Docker volume an install already has) is kept, and the project is named after its stack (or, when `.flisk/project.json` has `composeProjectNames.<stack>` from flisk-import, the Compose project name it had before, such as `pl_mail`), so `docker compose up` finds the same data as before.
 An `image` with Compose variables (`postgres:${POSTGRES_VERSION:-18}-alpine`) is written as it is, for Compose to resolve; `restart: "on-failure:N"` keeps N. From `container`: `stopGracePeriod` becomes `stop_grace_period`, `networkAliases` become `networks: { default: { aliases } }` (not on a `sidecarOf` service, which has no network of its own), `extraHosts` become `extra_hosts` and `ulimits` stay `ulimits`. Each value is checked so it cannot add YAML keys; one that does not fit is an error.
-`healthCheck.command` becomes a Compose `healthcheck`; a service that lists a checked service in `dependsOn` waits for `service_healthy`, and one that lists a `restart: "no"` job waits for `service_completed_successfully`.
+`healthCheck.command` becomes a Compose `healthcheck` (with `startPeriod` as `start_period`); a service that lists a checked service in `dependsOn` waits for `service_healthy` (only when that healthcheck is written: a service with only `healthCheckPath`, or `enabled: false`, is waited for with `service_started`), and a `dependsOn` entry written as `{ name, condition }` (flisk#2983) keeps its condition. `buildArgs` become `build.args`. A service with no `restart` gets none (Compose's default), as the project's own Compose file had it. and one that lists a `restart: "no"` job waits for `service_completed_successfully`.
 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.
 

package/dist/compose.js

@@ -5,7 +5,8 @@
  * 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 { existsSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
 import { ExportError } from "./errors.js";
 /** extraPorts `publish`: digits, dots, colons and `${NAME:-default}` / `${NAME-default}`, as flisk core accepts it (flisk#2947). */
 const PUBLISH = /^(?:[0-9.:]|\$\{[A-Za-z_][A-Za-z0-9_]*:?-[0-9.:]+\})+$/;
@@ -14,6 +15,11 @@ const IMAGE = /^(?:[A-Za-z0-9._/:@-]|\$\{[A-Za-z_][A-Za-z0-9_]*(?::?-[A-Za-z0-9.
 /** 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 CONDITIONS = new Set([
+    "service_started",
+    "service_healthy",
+    "service_completed_successfully",
+]);
 /** `on-failure:N` with a retry limit from 1 to 100. */
 const RESTART_LIMIT = /^on-failure:([1-9][0-9]?|100)$/;
 /** A Compose duration such as 30s, 1m30s or 500ms. */
@@ -85,6 +91,16 @@ function serviceLines(resource, outDir, services) {
         lines.push("    build:", `      context: ${q(context)}`);
         if (dockerfile)
             lines.push(`      dockerfile: ${q(dockerfile)}`);
+        // buildArgs (flisk#2983): NAME to a string, which may use Compose variables such as ${NODE_VERSION:-22}.
+        const args = Object.entries(record(c.buildArgs));
+        for (const [arg, value] of args) {
+            if (!ENV_NAME.test(arg) || typeof value !== "string") {
+                throw new ExportError(`${name}: buildArgs "${arg}" needs a name of letters, digits and _ and a string`);
+            }
+        }
+        if (args.length > 0) {
+            lines.push("      args:", ...args.map(([arg, value]) => `        ${arg}: ${q(value)}`));
+        }
     }
     const container = record(c.container);
     if (container.init !== false)
@@ -95,9 +111,7 @@ function serviceLines(resource, outDir, services) {
         }
         lines.push(`    restart: ${q(c.restart)}`);
     }
-    else {
-        lines.push('    restart: "unless-stopped"');
-    }
+    // No restart in service.json is written as none: Compose's default, as the project's own Compose file had it.
     const sidecarOf = typeof c.sidecarOf === "string" ? c.sidecarOf : undefined;
     if (sidecarOf) {
         if (!known.has(sidecarOf)) {
@@ -181,11 +195,26 @@ function serviceLines(resource, outDir, services) {
             lines.push(`      - ${q(`${bind}:${hostPort}:${port}/${protocol}`)}`);
         }
     }
-    const dependsOn = strings(c.dependsOn).filter((d) => known.has(d));
+    // dependsOn entries are names or { name, condition } (flisk#2983); a stated condition wins over the guess.
+    const dependsOn = (Array.isArray(c.dependsOn) ? c.dependsOn : [])
+        .map((entry) => typeof entry === "string"
+        ? { name: entry, condition: undefined }
+        : { name: record(entry).name, condition: record(entry).condition })
+        .filter((d) => typeof d.name === "string" && known.has(d.name));
     if (dependsOn.length > 0) {
         lines.push("    depends_on:");
         for (const d of dependsOn) {
-            lines.push(`      ${d}:`, `        condition: ${dependencyCondition(known.get(d))}`);
+            const dep = known.get(d.name);
+            if (d.condition !== undefined && !CONDITIONS.has(d.condition)) {
+                throw new ExportError(`${name}: dependsOn "${d.name}" condition is not a Compose condition`, ["Use service_started, service_healthy or service_completed_successfully"]);
+            }
+            // service_healthy needs a healthcheck in this file; without one Compose would refuse to start.
+            const condition = d.condition === undefined
+                ? dependencyCondition(dep)
+                : d.condition === "service_healthy" && !hasProbeCommand(dep.config.healthCheck)
+                    ? "service_started"
+                    : d.condition;
+            lines.push(`      ${d.name}:`, `        condition: ${condition}`);
         }
     }
     lines.push(...healthcheckLines(name, c.healthCheck));
@@ -305,7 +334,10 @@ function dependencyCondition(dep) {
         return "service_completed_successfully";
     return "service_started";
 }
+/** Whether the output has a healthcheck for this value: a command, and not turned off. Only then can a dependent wait for service_healthy. */
 function hasProbeCommand(value) {
+    if (value === false || record(value).enabled === false)
+        return false;
     return strings(record(value).command).length > 0;
 }
 /** A Compose `healthcheck` from `healthCheck.command` (exit 0 is ready); `healthCheck: false` turns it off. */
@@ -318,14 +350,18 @@ function healthcheckLines(name, value) {
     if (command.length === 0)
         return [];
     const lines = ["    healthcheck:", `      test: [${['"CMD"', ...command.map(q)].join(", ")}]`];
-    for (const key of ["interval", "timeout"]) {
+    for (const [key, composeKey] of [
+        ["interval", "interval"],
+        ["timeout", "timeout"],
+        ["startPeriod", "start_period"],
+    ]) {
         if (h[key] === undefined)
             continue;
         const seconds = Number(h[key]);
         if (!Number.isFinite(seconds) || seconds <= 0) {
             throw new ExportError(`${name}: healthCheck.${key} must be a number of seconds above 0`);
         }
-        lines.push(`      ${key}: ${q(`${seconds}s`)}`);
+        lines.push(`      ${composeKey}: ${q(`${seconds}s`)}`);
     }
     if (h.retries !== undefined) {
         const retries = Number(h.retries);
@@ -352,8 +388,26 @@ function joinPosix(base, rel) {
     }
     return (base.startsWith("/") ? "/" : "") + out.join("/");
 }
+/** A Compose project name as `docker compose` accepts it. */
+const PROJECT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * `.flisk/project.json` `composeProjectNames`: the project name each stack had as a Compose project before the import
+ * (flisk-import records it), so the export keeps its container names (pl_mail-php-1). Empty when absent or unreadable.
+ */
+export function composeProjectNames(projectRoot) {
+    const path = join(projectRoot, ".flisk", "project.json");
+    if (!existsSync(path))
+        return {};
+    try {
+        const names = record(record(JSON.parse(readFileSync(path, "utf8"))).composeProjectNames);
+        return Object.fromEntries(Object.entries(names).filter((entry) => typeof entry[1] === "string" && PROJECT_NAME.test(entry[1])));
+    }
+    catch {
+        return {};
+    }
+}
 /** The text of a docker-compose.yml for `resources`, written for a file in `outDir`. */
-export function buildCompose(outDir, resources) {
+export function buildCompose(outDir, resources, options = {}) {
     const services = resources.filter(isComposeExportable);
     if (services.length === 0) {
         throw new ExportError("No bring-your-own resource was found to export", [
@@ -364,6 +418,10 @@ export function buildCompose(outDir, resources) {
     const stacks = new Set(services
         .map((s) => s.config.stack)
         .filter((v) => typeof v === "string" && /^[a-z0-9][a-z0-9_-]*$/.test(v)));
+    const projectName = (stack) => {
+        const recorded = options.composeProjectNames?.[stack];
+        return recorded && PROJECT_NAME.test(recorded) ? recorded : stack;
+    };
     const body = [];
     const volumes = new Map();
     const models = new Map();
@@ -392,7 +450,8 @@ export function buildCompose(outDir, resources) {
         "",
         // Without a name Compose takes the folder's (autogenerated), so containers and unnamed volumes would not match the
         // project the app had before. One stack gives the project its name.
-        ...(stacks.size === 1 ? [`name: ${q([...stacks][0])}`, ""] : []),
+        // The Compose project name the stack had before the import, when flisk-import recorded it, else the stack.
+        ...(stacks.size === 1 ? [`name: ${q(projectName([...stacks][0]))}`, ""] : []),
         "services:",
     ];
     const tail = [

package/dist/main.js

@@ -5,7 +5,7 @@
 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 { buildCompose, composeProjectNames } 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";
@@ -94,7 +94,9 @@ function program(io) {
         const outDir = options.out
             ? realDir(resolve(io.cwd, options.out))
             : join(projectRoot, ".autogenerated");
-        const content = buildCompose(outDir, discover(projectRoot));
+        const content = buildCompose(outDir, discover(projectRoot), {
+            composeProjectNames: composeProjectNames(projectRoot),
+        });
         const file = join(outDir, "docker-compose.yml");
         if (options.check) {
             const shown = relative(realDir(io.cwd), file) || file;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flisk-sh/flisk-export",
-  "version": "0.6.0",
+  "version": "0.8.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",