@flisk-sh/flisk-import 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDK Landscape
+
+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,24 @@
-# Temporary Holding Version
+# tdk import
 
-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.
+Import the services in a repo's root `docker-compose.yml` into [TDK](https://github.com/flisk-sh/flisk) as `service.json` files. This is the Compose first tier of flisk-sh/flisk#511.
+
+```bash
+tdk import . --dry-run     # plan only
+tdk import .               # plan, then ask before writing
+tdk import . --yes         # write service.json files and project setup
+```
+
+## What to expect
+
+- **Reads one file:** the root `docker-compose.yml`. Not `compose.yaml`, override files, nested Compose files, Dockerfiles on their own, `package.json`, or Procfiles.
+- **Writes:** one bring-your-own `service.json` per Compose service, plus `.tdk/project.json` if the repo is not a TDK project yet. It never edits the Compose file or overwrites a `service.json` without `--force`.
+- **Keeps:** the build context and Dockerfile (or the image), the container port, `depends_on`, and an HTTP health path. Databases and brokers are private, with no proxy route.
+- **Drops, and says so:** env values, volumes, `command`, `env_file` and every other untranslated key; services with `profiles`, `extends`, an out-of-tree build or a `${VAR}` image.
+- **Does not start anything.** Put env values in `.env`, then run `tdk up` with TDK core **1.3.145 or later**. The importer does not check the core version.
+- **Exit codes:** `0` when the plan succeeds (`--dry-run`, files written, or all `service.json` files already exist), `1` when no root `docker-compose.yml` or mappable service is found, and `2` when the write prompt is declined or closed without an answer (`Nothing written.`).
+
+See [docs/import.md](docs/import.md) for the full mapping and limits. `tdk import` is the core CLI command backed by this package.
+
+```bash
+bun install && bun run build && bun run test
+```

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Command } from "commander";
+import "./detectors/index.js";
+import { ImportError } from "./errors.js";
+import { formatPlan } from "./format.js";
+import { buildPlan } from "./plan.js";
+import { MIN_CORE_VERSION } from "./tdk.js";
+import { applyWrites, manifestRelPath, planWrites } from "./write.js";
+async function confirm(message) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const closed = new Promise((resolve) => rl.once("close", () => resolve(null)));
+        const answer = await Promise.race([rl.question(`${message} (Y/n) `), closed]);
+        if (answer === null)
+            return false;
+        const trimmed = answer.trim().toLowerCase();
+        return trimmed === "" || trimmed === "y" || trimmed === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+const program = new Command("flisk-import")
+    .version(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version)
+    .description("Import services from the root docker-compose.yml into Flisk")
+    .argument("[dir]", "Directory containing docker-compose.yml", ".")
+    .option("--dry-run", "Print the plan and write nothing", false)
+    .option("--yes", "Write without prompting", false)
+    .option("--force", "Overwrite an existing service.json", false)
+    .action(async (dir, options) => {
+    const plan = buildPlan(dir);
+    const writes = planWrites(plan, options.force);
+    console.log(formatPlan(plan, writes));
+    const pending = writes.items.filter((i) => i.status !== "exists");
+    if (plan.services.length === 0) {
+        console.log("Nothing to import: no service in docker-compose.yml could be mapped.");
+        process.exitCode = 1;
+        return;
+    }
+    if (options.dryRun)
+        return void console.log("Dry run: nothing written.");
+    if (pending.length === 0 && !writes.projectConfig) {
+        return void console.log("Nothing to write: every service.json already exists.");
+    }
+    if (!options.yes &&
+        !(await confirm(`Write ${pending.length} service.json file(s)${writes.projectConfig ? " and create .tdk/project.json" : ""}?`))) {
+        console.log("Nothing written.");
+        process.exitCode = 2;
+        return;
+    }
+    const written = applyWrites(writes);
+    for (const item of written) {
+        console.log(`  wrote ${relative(process.cwd(), item.path) || manifestRelPath(plan, item)}`);
+    }
+    console.log(`\nWrote ${written.length} service.json file(s)${writes.projectConfig ? " and created .tdk/project.json" : ""}.`);
+    const envFile = relative(process.cwd(), join(writes.projectRoot, ".env")) || ".env";
+    console.log("\nNext:");
+    if (plan.services.some((s) => s.envKeys.length))
+        console.log(`  - Put the environment values these services need in ${envFile}; values in docker-compose.yml were not copied.`);
+    console.log(`  - Run \`flisk up\` with Flisk core ${MIN_CORE_VERSION} or later. The import did not start anything.`);
+});
+try {
+    await program.parseAsync();
+}
+catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    if (err instanceof ImportError)
+        for (const s of err.suggestions)
+            console.error(`  -> ${s}`);
+    process.exit(err instanceof ImportError && err.exitCode ? err.exitCode : 1);
+}

package/dist/detectors/compose.js

@@ -0,0 +1,218 @@
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path/posix";
+import { isAlias, isMap, parseDocument, visit } from "yaml";
+import { registerDetector } from "../registry.js";
+import { HEALTH_CHECK_PATH_PATTERN } from "../tdk.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Container-side port of one `ports:` entry, in short or long syntax. */
+function containerPort(entry) {
+    if (typeof entry === "number")
+        return entry;
+    if (isObj(entry))
+        return typeof entry.target === "number" ? entry.target : undefined;
+    if (typeof entry !== "string")
+        return undefined;
+    const last = entry.split("/")[0]?.split(":").pop() ?? "";
+    const first = last.split("-")[0] ?? "";
+    return /^\d+$/.test(first) ? Number.parseInt(first, 10) : undefined;
+}
+/** Well-known non-HTTP ports: SSH, SMTP, ZooKeeper, MQTT, then databases and brokers. */
+const NON_HTTP_PORTS = new Set([
+    22, 25, 1883, 2181, 3306, 5432, 5672, 6379, 9092, 9200, 11211, 27017,
+]);
+/**
+ * Service keys this detector translates. Every other key is named in the report: Flisk runs a
+ * bring-your-own container without volumes, command overrides, env files and the rest.
+ * `healthcheck` only contributes an HTTP path; `environment` only contributes names.
+ */
+const TRANSLATED_KEYS = new Set([
+    "image",
+    "build",
+    "ports",
+    "environment",
+    "depends_on",
+    "healthcheck",
+]);
+function envNames(environment) {
+    if (Array.isArray(environment)) {
+        return environment
+            .filter((e) => typeof e === "string")
+            .map((e) => e.split("=")[0]);
+    }
+    return isObj(environment) ? Object.keys(environment) : [];
+}
+function commandOf(command) {
+    if (typeof command === "string")
+        return command;
+    if (Array.isArray(command) && command.every((c) => typeof c === "string"))
+        return command.join(" ");
+    return undefined;
+}
+function healthPathOf(healthcheck) {
+    if (!isObj(healthcheck) || !Array.isArray(healthcheck.test))
+        return undefined;
+    const test = healthcheck.test
+        .filter((part) => typeof part === "string")
+        .join(" ");
+    const match = test.match(/(?:https?:\/\/[^\s"'/]+|(?:^|(?<=[\s"']))(?:[a-z0-9.-]+:\d+|localhost|127\.0\.0\.1))(\/[^\s"']*)/i);
+    if (!match)
+        return undefined;
+    try {
+        const raw = match[0];
+        return new URL(/^https?:\/\//i.test(raw) ? raw : `http://${raw}`).pathname || "/";
+    }
+    catch {
+        return undefined;
+    }
+}
+registerDetector({
+    id: "compose",
+    claim: (relPath) => relPath === "docker-compose.yml",
+    parse(absPath, relPath) {
+        const composeDir = dirname(relPath) === "." ? "" : dirname(relPath);
+        const base = { file: relPath, detector: "compose" };
+        const skips = [];
+        const candidates = [];
+        const doc = parseDocument(readFileSync(absPath, "utf8"), { merge: true });
+        if (doc.errors.length > 0) {
+            return {
+                candidates,
+                skips: [{ ...base, reason: `invalid YAML: ${doc.errors[0]?.message}` }],
+            };
+        }
+        let usesAnchors = false;
+        visit(doc, {
+            Alias() {
+                usesAnchors = true;
+            },
+            Node(_key, node) {
+                if (node.anchor || isAlias(node))
+                    usesAnchors = true;
+            },
+        });
+        if (usesAnchors) {
+            skips.push({
+                ...base,
+                reason: "uses YAML anchors/aliases; values were read after resolution",
+            });
+        }
+        const root = doc.toJS();
+        const services = isObj(root) && isObj(root.services) ? root.services : null;
+        if (!services || !isMap(doc.get("services", true))) {
+            return { candidates, skips: [...skips, { ...base, reason: "no `services:` map" }] };
+        }
+        for (const [name, raw] of Object.entries(services)) {
+            if (!isObj(raw)) {
+                skips.push({ ...base, reason: `service "${name}" is not a map` });
+                continue;
+            }
+            if (raw.extends !== undefined) {
+                skips.push({
+                    ...base,
+                    reason: `service "${name}" uses \`extends\`; values are not resolved`,
+                });
+                continue;
+            }
+            if (raw.profiles !== undefined) {
+                skips.push({
+                    ...base,
+                    reason: `service "${name}" has profiles ${JSON.stringify(raw.profiles)}; profiles are not enforced by Flisk`,
+                });
+                continue;
+            }
+            let dir = composeDir;
+            let dockerfile;
+            let standalone = true;
+            if (raw.build !== undefined) {
+                const build = isObj(raw.build) ? raw.build : { context: raw.build };
+                const context = typeof build.context === "string" ? build.context : ".";
+                const resolved = normalize(join(composeDir, context));
+                if (isAbsolute(context) ||
+                    context.includes("://") ||
+                    resolved === ".." ||
+                    resolved.startsWith("../")) {
+                    skips.push({
+                        ...base,
+                        reason: `service "${name}" build context "${context}" is outside the imported directory; not imported`,
+                    });
+                    continue;
+                }
+                dir = resolved === "." ? "" : resolved;
+                standalone = false;
+                dockerfile = typeof build.dockerfile === "string" ? build.dockerfile : "Dockerfile";
+            }
+            const ports = [
+                ...new Set((Array.isArray(raw.ports) ? raw.ports : [])
+                    .map(containerPort)
+                    .filter((p) => p !== undefined)),
+            ];
+            const unreadable = (Array.isArray(raw.ports) ? raw.ports : []).filter((entry) => containerPort(entry) === undefined);
+            if (unreadable.length > 0) {
+                skips.push({
+                    ...base,
+                    reason: ports.length === 0
+                        ? `service "${name}" ports not understood (${JSON.stringify(unreadable)}); it is imported as a private service with no route`
+                        : `service "${name}" has port entries that were not understood and ignored (${JSON.stringify(unreadable)}); only ${ports.join(", ")} was read`,
+                });
+            }
+            const httpPorts = ports.filter((port) => port <= 5999 && !NON_HTTP_PORTS.has(port));
+            const selectedPort = httpPorts.length === 1 ? httpPorts[0] : ports.length === 1 ? ports[0] : undefined;
+            if (ports.length > 1 && selectedPort === undefined) {
+                skips.push({
+                    ...base,
+                    reason: `service "${name}" lists several ports (${ports.join(", ")}); no single HTTP container port could be identified`,
+                });
+            }
+            else if (ports.length > 1) {
+                skips.push({
+                    ...base,
+                    reason: `service "${name}" publishes extra container ports (${ports.filter((port) => port !== selectedPort).join(", ")}); Flisk routes only ${selectedPort}`,
+                });
+            }
+            const dependsOn = Array.isArray(raw.depends_on)
+                ? raw.depends_on.filter((d) => typeof d === "string")
+                : isObj(raw.depends_on)
+                    ? Object.keys(raw.depends_on)
+                    : [];
+            const command = commandOf(raw.command);
+            const envKeys = envNames(raw.environment);
+            const foundHealthPath = healthPathOf(raw.healthcheck);
+            const healthCheckPath = foundHealthPath && HEALTH_CHECK_PATH_PATTERN.test(foundHealthPath)
+                ? foundHealthPath
+                : undefined;
+            if (foundHealthPath && !healthCheckPath) {
+                skips.push({
+                    ...base,
+                    reason: `service "${name}" health path "${foundHealthPath}" has characters Flisk does not accept (only a-z, 0-9, / and -); not used`,
+                });
+            }
+            const untranslated = Object.keys(raw).filter((key) => !TRANSLATED_KEYS.has(key));
+            if (untranslated.length) {
+                skips.push({
+                    ...base,
+                    reason: `service "${name}" keys not translated: ${untranslated.join(", ")}`,
+                });
+            }
+            // Any single published port that is not a known database/broker port is treated as HTTP,
+            // including 8000 and 8080; a service with no published port stays private, as in Compose.
+            const exposeViaProxy = selectedPort !== undefined && !NON_HTTP_PORTS.has(selectedPort);
+            candidates.push({
+                kind: "service",
+                name,
+                dir,
+                standalone,
+                ...(typeof raw.image === "string" ? { image: raw.image } : {}),
+                ...(dockerfile ? { dockerfile } : {}),
+                ...(command ? { command } : {}),
+                ...(selectedPort !== undefined ? { port: selectedPort } : {}),
+                ...(healthCheckPath ? { healthCheckPath } : {}),
+                exposeViaProxy,
+                ...(envKeys.length ? { envKeys } : {}),
+                ...(dependsOn.length ? { dependsOn } : {}),
+                confidence: "high",
+                sources: [base],
+            });
+        }
+        return { candidates, skips };
+    },
+});

package/dist/detectors/dockerfile.js

@@ -0,0 +1,103 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path/posix";
+import { registerDetector } from "../registry.js";
+/** Joins `\` continuations and drops comments, keeping the first physical line number of each instruction. */
+function instructions(text) {
+    const out = [];
+    let pending = null;
+    text.split(/\r?\n/).forEach((raw, index) => {
+        const trimmed = raw.trim();
+        if (!pending && (trimmed === "" || trimmed.startsWith("#")))
+            return;
+        if (pending && trimmed.startsWith("#"))
+            return;
+        const continued = trimmed.endsWith("\\");
+        const piece = continued ? trimmed.slice(0, -1).trim() : trimmed;
+        pending = pending
+            ? { line: pending.line, text: `${pending.text} ${piece}`.trim() }
+            : { line: index + 1, text: piece };
+        if (!continued) {
+            out.push(pending);
+            pending = null;
+        }
+    });
+    if (pending)
+        out.push(pending);
+    return out;
+}
+function cmdToString(args) {
+    if (args.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(args);
+            if (Array.isArray(parsed) && parsed.every((p) => typeof p === "string")) {
+                return parsed.join(" ");
+            }
+        }
+        catch {
+            // not exec form after all: fall through and keep the text
+        }
+    }
+    return args;
+}
+registerDetector({
+    id: "dockerfile",
+    claim: (relPath) => basename(relPath) === "Dockerfile",
+    parse(absPath, relPath) {
+        const dir = dirname(relPath) === "." ? "" : dirname(relPath);
+        let skips = [];
+        // Only the last build stage is the image that runs.
+        let ports = [];
+        let command;
+        for (const ins of instructions(readFileSync(absPath, "utf8"))) {
+            const [keyword = "", ...rest] = ins.text.split(/\s+/);
+            const args = rest.join(" ");
+            switch (keyword.toUpperCase()) {
+                case "FROM":
+                    ports = [];
+                    skips = [];
+                    command = undefined;
+                    break;
+                case "EXPOSE":
+                    for (const token of rest) {
+                        if (!token)
+                            continue;
+                        const rawPort = token.split("/")[0] ?? "";
+                        const port = /^\d+$/.test(rawPort) ? Number.parseInt(rawPort, 10) : Number.NaN;
+                        if (Number.isInteger(port) && port > 0 && port < 65536) {
+                            ports.push(port);
+                        }
+                        else {
+                            skips.push({
+                                file: relPath,
+                                detector: "dockerfile",
+                                line: ins.line,
+                                reason: "EXPOSE uses a variable; port not imported",
+                            });
+                        }
+                    }
+                    break;
+                case "CMD":
+                    command = cmdToString(args);
+                    break;
+            }
+        }
+        const distinct = [...new Set(ports)];
+        if (distinct.length > 1) {
+            skips.push({
+                file: relPath,
+                detector: "dockerfile",
+                reason: `EXPOSE lists several ports (${distinct.join(", ")}); port not imported`,
+            });
+        }
+        const candidate = {
+            kind: "service",
+            dir,
+            dockerfile: "Dockerfile",
+            ...(distinct.length === 1 ? { port: distinct[0] } : {}),
+            ...(command ? { command } : {}),
+            confidence: "high",
+            sources: [{ file: relPath, detector: "dockerfile" }],
+        };
+        return { candidates: [candidate], skips };
+    },
+});

package/dist/detectors/index.js

@@ -0,0 +1,5 @@
+// This release deliberately imports one source: the repository's root docker-compose.yml.
+// The standalone detectors in `./dockerfile.ts`, `./package-json.ts`, and `./procfile.ts`
+// are staged for later releases and tested directly, so they are not imported here or
+// selected by `buildPlan` (`selectDetectors(["compose"])`).
+import "./compose.js";

package/dist/detectors/package-json.js

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path/posix";
+import { registerDetector } from "../registry.js";
+/** `bun` or `node` as the program, after any `KEY=value` prefixes. Anything else is not sure. */
+function runtimeOf(command) {
+    const words = command.trim().split(/\s+/);
+    const program = words.find((w) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
+    return program === "bun" || program === "node" ? program : undefined;
+}
+registerDetector({
+    id: "package-json",
+    claim: (relPath) => basename(relPath) === "package.json",
+    parse(absPath, relPath) {
+        const dir = dirname(relPath) === "." ? "" : dirname(relPath);
+        const source = { file: relPath, detector: "package-json" };
+        let scripts = {};
+        try {
+            const parsed = JSON.parse(readFileSync(absPath, "utf8"));
+            if (parsed && typeof parsed === "object" && typeof parsed.scripts === "object") {
+                scripts = parsed.scripts ?? {};
+            }
+        }
+        catch (err) {
+            return {
+                candidates: [],
+                skips: [{ ...source, reason: `invalid JSON: ${err.message}` }],
+            };
+        }
+        const pick = (key) => typeof scripts[key] === "string" ? scripts[key] : "";
+        const command = pick("start") || pick("dev");
+        if (!command) {
+            return {
+                candidates: [],
+                skips: [{ ...source, reason: "no `start` or `dev` script" }],
+            };
+        }
+        const language = runtimeOf(command);
+        return {
+            candidates: [
+                {
+                    kind: "service",
+                    dir,
+                    command,
+                    ...(language ? { language } : {}),
+                    confidence: language ? "high" : "low",
+                    sources: [source],
+                },
+            ],
+            skips: [],
+        };
+    },
+});

package/dist/detectors/procfile.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path/posix";
+import { registerDetector } from "../registry.js";
+const LINE = /^([A-Za-z0-9_-]+):\s*(.*)$/;
+registerDetector({
+    id: "procfile",
+    claim: (relPath) => /^Procfile(\..+)?$/.test(basename(relPath)),
+    parse(absPath, relPath) {
+        const dir = dirname(relPath) === "." ? "" : dirname(relPath);
+        const candidates = [];
+        const skips = [];
+        const lines = readFileSync(absPath, "utf8").split(/\r?\n/);
+        lines.forEach((raw, index) => {
+            const line = raw.trim();
+            if (!line || line.startsWith("#"))
+                return;
+            const match = LINE.exec(line);
+            if (!match) {
+                skips.push({
+                    file: relPath,
+                    detector: "procfile",
+                    line: index + 1,
+                    reason: "not a `name: command` line",
+                });
+                return;
+            }
+            const [, name, command] = match;
+            if (!command) {
+                skips.push({
+                    file: relPath,
+                    detector: "procfile",
+                    line: index + 1,
+                    reason: `process "${name}" has no command`,
+                });
+                return;
+            }
+            candidates.push({
+                kind: name === "release" ? "job" : "service",
+                name,
+                dir,
+                command,
+                confidence: "high",
+                sources: [{ file: relPath, detector: "procfile" }],
+            });
+        });
+        return { candidates, skips };
+    },
+});

package/dist/errors.js

@@ -0,0 +1,11 @@
+/** A user-facing failure: the message, plus what to try. */
+export class ImportError extends Error {
+    suggestions;
+    exitCode;
+    constructor(message, suggestions = [], exitCode) {
+        super(message);
+        this.suggestions = suggestions;
+        this.exitCode = exitCode;
+        this.name = "ImportError";
+    }
+}

package/dist/format.js

@@ -0,0 +1,66 @@
+import { manifestRelPath } from "./write.js";
+const STATUS_TEXT = {
+    create: "create",
+    overwrite: "overwrite (--force)",
+    exists: "exists, kept (use --force to overwrite)",
+};
+/** The printed plan: what was found, where it came from, what conflicts, what was not translated. */
+export function formatPlan(plan, writes) {
+    const out = [];
+    const jobs = plan.services.filter((s) => s.kind === "job").length;
+    out.push(`Found ${plan.services.length - jobs} service(s) and ${jobs} job(s) in ${plan.root}`, `Read only: ${plan.files.join(", ")}. Lines below name what was not translated.`, "");
+    if (writes.projectConfig)
+        out.push(`  .tdk/project.json  [create Flisk project]`, "");
+    for (const service of plan.services) {
+        const item = writes.items.find((i) => i.service === service);
+        out.push(`  ${service.name}  (${service.kind}${service.dir ? `, ${service.dir}/` : ""})`);
+        out.push(`    from:      ${service.sources.map((s) => `${s.file} [${s.detector}]`).join(", ")}`);
+        if (service.dockerfile)
+            out.push(`    build:     ${service.dir || "."}/ with ${service.dockerfile}`);
+        else if (service.image)
+            out.push(`    image:     ${service.image}`);
+        const manifest = item && item.status !== "exists" ? item.manifest : undefined;
+        if (manifest) {
+            out.push(`    port:      ${manifest.port} ${manifest.port === service.port ? "(from Compose)" : "(assigned)"}`);
+            out.push(manifest.exposeViaProxy === false
+                ? `    proxy:     none, private (${service.port === undefined ? "no single published port" : `${service.port} is a database or broker port`})`
+                : "    proxy:     routed through Traefik");
+            if (manifest.healthCheckPath)
+                out.push(`    health:    ${manifest.healthCheckPath}${service.healthCheckPath ? "" : " (assumed)"}`);
+        }
+        if (service.dependsOn.length)
+            out.push(`    depends:   ${service.dependsOn.join(", ")}`);
+        if (service.language)
+            out.push(`    runtime:   ${service.language} (detected, not mapped to a native provider)`);
+        if (service.envKeys.length)
+            out.push(`    env:       ${service.envKeys.join(", ")} (names only)`);
+        for (const conflict of service.conflicts) {
+            const values = conflict.values
+                .map((v) => `${v.value} (${v.sources.map((s) => s.file).join(", ")})`)
+                .join(" vs ");
+            out.push(`    CONFLICT ${conflict.field}: ${values}; not used`);
+        }
+        if (item) {
+            out.push(`    write:     ${manifestRelPath(plan, item)}  [${STATUS_TEXT[item.status]}]`);
+            for (const note of item.notes)
+                out.push(`    note:      ${note}`);
+        }
+        out.push("");
+    }
+    for (const r of writes.rejected)
+        out.push(`  not written: ${r.name}: ${r.reason}`, "");
+    if (plan.skips.length) {
+        out.push("Skipped / not fully imported:");
+        for (const skip of plan.skips) {
+            out.push(`  ${skip.file}${skip.line ? `:${skip.line}` : ""} [${skip.detector}]: ${skip.reason}`);
+        }
+        out.push("");
+    }
+    if (plan.notes.length) {
+        out.push("Scan notes:");
+        for (const note of plan.notes)
+            out.push(`  ${note}`);
+        out.push("");
+    }
+    return out.join("\n");
+}