@flisk-sh/flisk-export 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flisk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# flisk-export
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write a Render Blueprint (`render.yaml`) or a Cloudflare `wrangler.toml` from the `service.json` files of a [Flisk](https://github.com/flisk-sh/flisk) project.
+
+It writes files only. It never deploys, never creates DNS records, never calls a cloud API, and writes environment variable **names**, never values. The Flisk CLI runs it at a pinned version as `flisk export`.
+
+## Use
+
+```sh
+npx @flisk-sh/flisk-export render [dir] [--resource <name>] [--out <dir>] [--dry-run] [--force]
+npx @flisk-sh/flisk-export wrangler [dir] --resource <name> [--route <host>] [--out <dir>] [--allow-non-worker] [--dry-run] [--force]
+```
+
+Or, from a Flisk project: `flisk export render --dry-run`.
+
+### render
+
+- Exports every resource whose `appType` is `backend`, `frontend`, `agent`, `mcp` or `bring-your-own` (a resource with no `appType` is not exported), or one with `--resource`.
+- A resource with a Dockerfile becomes `runtime: docker`; one with a `package.json` becomes `runtime: node`.
+- The `service.json` `port` is written as `PORT`, because Render routes traffic to `$PORT`.
+- Every other env name is written with `sync: false`, so Render asks for the value. Names that are not valid variable names are left out with a warning.
+- `healthCheckPath` comes from `service.json` (default `/health`).
+- Paths are relative to the **git repository root**, which is where Render reads them, and the file is written there by default. `--out` moves the file but not the paths.
+- Two resources that become the same service name (`api_v1` and `api-v1`) are refused.
+
+### wrangler
+
+- One resource. `main` comes from `package.json` `main`, or the first of `src/index.ts`, `src/index.js`, `src/worker.ts`, `src/worker.js`, `index.ts`, `index.js`.
+- A resource with a Dockerfile, or without a `wrangler`, `@cloudflare/workers-types` or `hono` dependency, is refused unless `--allow-non-worker`.
+- `--route api.example.com` writes a Custom Domain route. Wildcards are refused: Custom Domains do not accept them.
+- Env names are listed in a comment for `wrangler secret put`.
+
+## Develop
+
+```sh
+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/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+process.exitCode = await main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+});

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/discover.js

@@ -0,0 +1,97 @@
+/**
+ * Finds the Flisk project root and the service.json files in it. This is a small read-only copy of how the Flisk
+ * CLI discovers resources: it never writes, never runs anything but `git rev-parse` and never calls a network.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { ExportError } from "./errors.js";
+const SKIP_DIRECTORIES = new Set(["node_modules", "dist", "build", "coverage", "vendor"]);
+const MAX_DEPTH = 5;
+/** The nearest directory at or above `start` holding `.flisk/project.json`, or `start` itself when there is none. */
+export function findProjectRoot(start) {
+    // The real path, so paths compare with what `git rev-parse` prints (macOS /var is a link to /private/var).
+    const from = existsSync(start) ? realpathSync(resolve(start)) : resolve(start);
+    let dir = from;
+    while (true) {
+        if (existsSync(join(dir, ".flisk", "project.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return from;
+        dir = parent;
+    }
+}
+/**
+ * The root of the git repository holding `dir`, or `dir` when it is not in one. Render reads every path in a
+ * Blueprint relative to the repository root, so the Blueprint is written against this.
+ */
+export function findRepoRoot(dir) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: dir,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out ? resolve(out) : dir;
+    }
+    catch {
+        return dir;
+    }
+}
+function findServiceJsonFiles(dir, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return [];
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRECTORIES.has(entry.name) || entry.name.startsWith("."))
+                continue;
+            results.push(...findServiceJsonFiles(full, depth + 1));
+        }
+        else if (entry.isFile() && entry.name === "service.json") {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/** Every resource under the project root. A service.json that is not a JSON object with appName is skipped. */
+export function discoverResources(projectRoot, warn = () => { }) {
+    const resources = [];
+    for (const file of findServiceJsonFiles(projectRoot)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf-8"));
+        }
+        catch {
+            warn(`skipped ${file}: invalid JSON`);
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            warn(`skipped ${file}: not a JSON object`);
+            continue;
+        }
+        const config = parsed;
+        if (typeof config.appName !== "string" || !config.appName) {
+            warn(`skipped ${file}: missing appName`);
+            continue;
+        }
+        resources.push({
+            name: config.appName,
+            path: dirname(file),
+            type: typeof config.appType === "string" && config.appType ? config.appType : undefined,
+            config,
+        });
+    }
+    return resources.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findResource(resources, name) {
+    const found = resources.find((resource) => resource.name === name);
+    if (!found) {
+        throw new ExportError(`No resource named "${name}" was found`, [
+            `Resources found: ${resources.map((resource) => resource.name).join(", ") || "none"}`,
+        ]);
+    }
+    return found;
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** A refusal the CLI prints as "Error: <message>" followed by one "-> <hint>" line per hint, then exits 1. */
+export class ExportError extends Error {
+    hints;
+    constructor(message, hints = []) {
+        super(message);
+        this.name = "ExportError";
+        this.hints = hints;
+    }
+}

package/dist/generate.js

@@ -0,0 +1,256 @@
+/**
+ * Builds the text of a Render Blueprint (render.yaml) and a Cloudflare Workers config (wrangler.toml) from Flisk
+ * service.json files.
+ *
+ * These functions only return text. Nothing here deploys, creates DNS records or calls a cloud API, and no
+ * environment value is ever copied, only the names (Render asks for each value itself because of `sync: false`).
+ * The one value written is the service port, which is not a secret.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { ExportError } from "./errors.js";
+/** The resource types that serve HTTP, which is what a Render web service and a Worker are. */
+export const EXPORTABLE_TYPES = [
+    "backend",
+    "frontend",
+    "agent",
+    "mcp",
+    "bring-your-own",
+];
+/** Health check path a service gets when service.json sets none (the same default the Flisk healthcheck uses). */
+export const DEFAULT_HEALTH_CHECK_PATH = "/health";
+/** Candidate Worker entry points, relative to the resource directory, tried in order when package.json has no main. */
+export const WORKER_ENTRY_CANDIDATES = [
+    "src/index.ts",
+    "src/index.js",
+    "src/worker.ts",
+    "src/worker.js",
+    "index.ts",
+    "index.js",
+];
+/** A package.json dependency that marks a resource as written for Cloudflare Workers. */
+export const WORKER_DEPENDENCIES = [
+    "wrangler",
+    "@cloudflare/workers-types",
+    "hono",
+];
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// No wildcard: Cloudflare Custom Domains (custom_domain = true) do not accept one.
+const HOSTNAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+/** A name Render and Cloudflare both accept: lowercase letters, digits and dashes. */
+export function deployName(name) {
+    const cleaned = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "service";
+}
+function envKeys(resource) {
+    const env = resource.config.env;
+    if (!env || typeof env !== "object" || Array.isArray(env))
+        return [];
+    return Object.keys(env);
+}
+/** The environment variable names a service declares in service.json `env`. Values are never read out. */
+export function envVarNames(resource) {
+    return envKeys(resource)
+        .filter((name) => ENV_NAME.test(name))
+        .sort();
+}
+/** The env names that are not valid variable names and so are left out of the export (the CLI warns about them). */
+export function skippedEnvNames(resource) {
+    return envKeys(resource)
+        .filter((name) => !ENV_NAME.test(name))
+        .sort();
+}
+/** The port service.json declares, or undefined. */
+export function servicePort(resource) {
+    const port = resource.config.port;
+    const value = typeof port === "string" ? Number(port) : port;
+    return typeof value === "number" && Number.isInteger(value) && value > 0 && value < 65536
+        ? value
+        : undefined;
+}
+/** A string quoted the way both YAML and TOML read it (a JSON string is a valid double-quoted scalar in each). */
+function quote(value) {
+    return JSON.stringify(value);
+}
+function relPath(from, to) {
+    return relative(from, to).split(sep).join("/");
+}
+/** A repository-relative path written with forward slashes and a leading `./`. */
+function repoPath(repoRoot, absolute) {
+    const rel = relPath(repoRoot, absolute);
+    return rel ? `./${rel}` : ".";
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readPackageJson(dir) {
+    const file = join(dir, "package.json");
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const pkg = parsed;
+    return {
+        main: typeof pkg.main === "string" && pkg.main ? pkg.main : undefined,
+        scripts: record(pkg.scripts),
+        dependencies: { ...record(pkg.devDependencies), ...record(pkg.dependencies) },
+    };
+}
+function dockerfileOf(resource) {
+    const declared = resource.config.dockerfile;
+    const file = join(resource.path, typeof declared === "string" ? declared : "Dockerfile");
+    return existsSync(file) ? file : null;
+}
+/** Whether a resource is exported: it must declare one of EXPORTABLE_TYPES. A resource with no type is not. */
+export function isExportable(resource) {
+    return resource.type !== undefined && EXPORTABLE_TYPES.includes(resource.type);
+}
+/** Refuses a resource that does not serve HTTP, so the export never writes a web service for a library or a job. */
+export function assertExportable(resource) {
+    if (isExportable(resource))
+        return;
+    const what = resource.type ? `a ${resource.type}` : "a resource with no appType";
+    throw new ExportError(`Resource "${resource.name}" is ${what}, which does not serve HTTP, so it is not exported`, [`Exported types: ${EXPORTABLE_TYPES.join(", ")}`, "Set appType in its service.json"]);
+}
+/** Refuses two resources whose deploy names are the same, which Render would reject as one name used twice. */
+export function assertUniqueDeployNames(resources) {
+    const seen = new Map();
+    for (const resource of resources) {
+        const name = deployName(resource.name);
+        const other = seen.get(name);
+        if (other !== undefined) {
+            throw new ExportError(`Resources "${other}" and "${resource.name}" both become the service name "${name}"`, ["Rename one of them (appName in service.json)", "Or export one with --resource <name>"]);
+        }
+        seen.set(name, resource.name);
+    }
+}
+/** One service block of a Render Blueprint, indented for the `services:` list. */
+function renderService(repoRoot, resource) {
+    assertExportable(resource);
+    const lines = ["  - type: web", `    name: ${quote(deployName(resource.name))}`];
+    const dockerfile = dockerfileOf(resource);
+    const pkg = readPackageJson(resource.path);
+    if (dockerfile) {
+        lines.push("    runtime: docker", `    dockerfilePath: ${quote(repoPath(repoRoot, dockerfile))}`, `    dockerContext: ${quote(repoPath(repoRoot, resource.path))}`);
+    }
+    else if (pkg) {
+        const hasBuild = typeof pkg.scripts.build === "string";
+        lines.push("    runtime: node", `    rootDir: ${quote(relPath(repoRoot, resource.path) || ".")}`, `    buildCommand: ${quote(hasBuild ? "npm install && npm run build" : "npm install")}`, `    startCommand: ${quote("npm start")}`);
+    }
+    else {
+        throw new ExportError(`Resource "${resource.name}" has neither a Dockerfile nor a package.json, so Render has nothing to build`, ["Add a Dockerfile to the resource directory, or set dockerfile in service.json"]);
+    }
+    const health = resource.config.healthCheckPath;
+    lines.push(`    healthCheckPath: ${quote(typeof health === "string" && health ? health : DEFAULT_HEALTH_CHECK_PATH)}`);
+    const port = servicePort(resource);
+    // Render routes traffic to $PORT (10000 by default), so a service listening on its own port needs PORT set.
+    const names = envVarNames(resource).filter((name) => port === undefined || name !== "PORT");
+    if (port !== undefined || names.length > 0) {
+        lines.push("    envVars:");
+        if (port !== undefined)
+            lines.push("      - key: PORT", `        value: ${quote(String(port))}`);
+        for (const name of names)
+            lines.push(`      - key: ${name}`, "        sync: false");
+    }
+    return lines;
+}
+/**
+ * A Render Blueprint for the given resources. `repoRoot` is the git repository root, which Render reads every path
+ * against. Every env var is listed by name with `sync: false`, never a value.
+ */
+export function buildRenderBlueprint(repoRoot, resources) {
+    assertUniqueDeployNames(resources);
+    const header = [
+        "# Render Blueprint written by `flisk export render` from service.json. Nothing was deployed.",
+        "# Review it, commit it at the root of the git repository, then on render.com: New -> Blueprint.",
+        "# Render asks for every envVars value marked sync: false; no secret value is in this file.",
+        "services:",
+    ];
+    const blocks = resources.flatMap((resource) => renderService(repoRoot, resource));
+    return `${[...header, ...blocks].join("\n")}\n`;
+}
+/** The Worker entry point, relative to the resource directory. */
+export function workerEntry(resource) {
+    const pkg = readPackageJson(resource.path);
+    if (pkg?.main && existsSync(join(resource.path, pkg.main))) {
+        return pkg.main.replace(/^\.\//, "");
+    }
+    const found = WORKER_ENTRY_CANDIDATES.find((candidate) => existsSync(join(resource.path, candidate)));
+    if (!found) {
+        throw new ExportError(`Resource "${resource.name}" has no Worker entry point`, [
+            `Set "main" in its package.json, or add one of: ${WORKER_ENTRY_CANDIDATES.join(", ")}`,
+        ]);
+    }
+    return found;
+}
+/**
+ * Refuses a resource that does not look like a Cloudflare Worker: one with a Dockerfile, or one whose package.json
+ * has none of WORKER_DEPENDENCIES. A Docker or Express service cannot run as a Worker, so its wrangler.toml would
+ * look valid and then fail.
+ */
+export function assertWorkerShaped(resource) {
+    const hints = [
+        "Pass --allow-non-worker if it really is a Worker",
+        "Use `flisk export render` for a Docker or Node service",
+    ];
+    if (dockerfileOf(resource)) {
+        throw new ExportError(`Resource "${resource.name}" has a Dockerfile, so it does not run as a Cloudflare Worker`, hints);
+    }
+    const deps = readPackageJson(resource.path)?.dependencies ?? {};
+    if (!WORKER_DEPENDENCIES.some((name) => name in deps)) {
+        throw new ExportError(`Resource "${resource.name}" does not depend on ${WORKER_DEPENDENCIES.join(", ")}, so it does not look like a Cloudflare Worker`, hints);
+    }
+}
+/** Validates a --route value: a bare host name such as api.example.com, no scheme, port, path or wildcard. */
+export function assertRouteHost(host) {
+    if (!HOSTNAME.test(host)) {
+        const hints = host.startsWith("*.")
+            ? [
+                "Cloudflare Custom Domains do not accept a wildcard; name one host such as api.example.com",
+            ]
+            : ["Leave out https:// and any path"];
+        throw new ExportError(`--route must be a host name such as api.example.com, got "${host}"`, hints);
+    }
+}
+/**
+ * A wrangler.toml for one resource. `outDir` is where the file will be written, so `main` is relative to it.
+ * Secrets are listed by name in a comment, for `wrangler secret put`; no value is ever written.
+ */
+export function buildWranglerToml(resource, outDir, options = {}) {
+    assertExportable(resource);
+    if (!options.allowNonWorker)
+        assertWorkerShaped(resource);
+    if (options.route)
+        assertRouteHost(options.route);
+    const entry = join(resource.path, workerEntry(resource));
+    const main = relPath(outDir, entry);
+    const date = (options.now ?? new Date()).toISOString().slice(0, 10);
+    const lines = [
+        "# Written by `flisk export wrangler` from service.json. Nothing was deployed and no DNS record was created.",
+        `name = ${quote(deployName(resource.name))}`,
+        `main = ${quote(main)}`,
+        `compatibility_date = ${quote(date)}`,
+    ];
+    if (options.route) {
+        lines.push("", `routes = [{ pattern = ${quote(options.route)}, custom_domain = true }]`);
+    }
+    const names = envVarNames(resource);
+    if (names.length > 0) {
+        lines.push("", "# Environment from service.json, by name only. Set each one with `wrangler secret put <NAME>`:");
+        for (const name of names)
+            lines.push(`#   ${name}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./discover.js";
+export * from "./errors.js";
+export * from "./generate.js";
+export { main, NOTHING_DEPLOYED } from "./main.js";

package/dist/main.js

@@ -0,0 +1,155 @@
+/**
+ * `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, 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";
+export const NOTHING_DEPLOYED = "Nothing was deployed, no DNS record was created and no cloud API was called.";
+function emit(io, filePath, content, options) {
+    const shown = relative(realDir(io.cwd), filePath) || filePath;
+    if (options.dryRun) {
+        io.out(`Dry run - would write ${shown} (nothing written, nothing deployed):\n\n`);
+        io.out(content);
+        return;
+    }
+    if (existsSync(filePath) && !options.force) {
+        throw new ExportError(`${shown} already exists and was left unchanged`, [
+            "Pass --force to replace it",
+            "Pass --dry-run to see what would be written",
+            "Pass --out <dir> to write it somewhere else",
+        ]);
+    }
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, "utf-8");
+    io.out(`Wrote ${shown}.\n${NOTHING_DEPLOYED}\n`);
+}
+/** `dir` with its nearest existing ancestor resolved through links, so it compares with the resource paths. */
+function realDir(dir) {
+    if (existsSync(dir))
+        return realpathSync(dir);
+    const parent = dirname(dir);
+    return parent === dir ? dir : join(realDir(parent), basename(dir));
+}
+function warnSkippedEnv(io, resources) {
+    for (const resource of resources) {
+        const skipped = skippedEnvNames(resource);
+        if (skipped.length > 0) {
+            io.err(`Warning: ${resource.name}: env names left out because they are not valid variable names: ${skipped.join(", ")}. Set them by hand on the platform.\n`);
+        }
+    }
+}
+function program(io) {
+    const root = (dir) => findProjectRoot(resolve(io.cwd, dir ?? "."));
+    const discover = (projectRoot) => discoverResources(projectRoot, (message) => io.err(`Warning: ${message}\n`));
+    const cli = new Command("flisk-export")
+        .description("Write deploy files (render.yaml, wrangler.toml) from service.json; never deploys")
+        .exitOverride()
+        .configureOutput({ writeOut: io.out, writeErr: io.err });
+    cli
+        .command("render")
+        .description("Write a Render Blueprint (render.yaml) from service.json; never deploys")
+        .argument("[dir]", "The Flisk project (default: the current directory)")
+        .option("--resource <name>", "Export only this resource (default: every resource that serves HTTP)")
+        .option("--out <dir>", "Directory to write render.yaml in (default: the git repository root). Paths inside are always relative to the git repository root, which is where Render reads them")
+        .option("--dry-run", "Print render.yaml instead of writing it", false)
+        .option("--force", "Replace an existing render.yaml", false)
+        .action((dir, options) => {
+        const projectRoot = root(dir);
+        const repoRoot = findRepoRoot(projectRoot);
+        const all = discover(projectRoot);
+        let resources;
+        if (options.resource) {
+            const resource = findResource(all, options.resource);
+            assertExportable(resource);
+            resources = [resource];
+        }
+        else {
+            resources = all.filter(isExportable);
+            if (resources.length === 0) {
+                throw new ExportError("No resource that serves HTTP was found to export", [
+                    `Exported types: ${EXPORTABLE_TYPES.join(", ")}`,
+                ]);
+            }
+        }
+        const content = buildRenderBlueprint(repoRoot, resources);
+        warnSkippedEnv(io, resources);
+        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")
+        .argument("[dir]", "The Flisk project (default: the current directory)")
+        .requiredOption("--resource <name>", "The resource to export")
+        .option("--route <host>", "Custom domain for the Worker (no wildcard; custom_domain = true)")
+        .option("--out <dir>", "Directory to write wrangler.toml in (default: the resource directory)")
+        .option("--allow-non-worker", "Export a resource that does not look like a Worker", false)
+        .option("--dry-run", "Print wrangler.toml instead of writing it", false)
+        .option("--force", "Replace an existing wrangler.toml", false)
+        .action((dir, options) => {
+        const resource = findResource(discover(root(dir)), options.resource);
+        const outDir = options.out ? realDir(resolve(io.cwd, options.out)) : resource.path;
+        const content = buildWranglerToml(resource, outDir, {
+            route: options.route,
+            allowNonWorker: options.allowNonWorker,
+        });
+        warnSkippedEnv(io, [resource]);
+        emit(io, join(outDir, "wrangler.toml"), content, options);
+    });
+    for (const sub of cli.commands) {
+        sub.exitOverride().configureOutput({ writeOut: io.out, writeErr: io.err });
+    }
+    return cli;
+}
+/** Runs the CLI with `args` (without node and the script) and resolves to the exit code. */
+export async function main(args, io) {
+    try {
+        await program(io).parseAsync(args, { from: "user" });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            return error.exitCode === 0 ? 0 : error.exitCode || 1;
+        }
+        if (error instanceof ExportError) {
+            io.err(`Error: ${error.message}\n`);
+            for (const hint of error.hints)
+                io.err(`-> ${hint}\n`);
+            return 1;
+        }
+        io.err(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@flisk-sh/flisk-export",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "flisk-export": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flisk-sh/flisk-export.git"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc --project tsconfig.build.json && chmod +x dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "~2.5.15",
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/flisk-sh/flisk-export#readme",
+  "bugs": {
+    "url": "https://github.com/flisk-sh/flisk-export/issues"
+  }
+}