@synopackageland/cli 0.1.0

package/dist/compose/analyze.js

@@ -0,0 +1,346 @@
+import { existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { parseDocument } from "yaml";
+import { composeSpan, makeError } from "../errors.js";
+import { undeclaredPrivilegeFindings } from "./privilege.js";
+const DOCKER_SOCKET_PATHS = [
+    "/var/run/docker.sock",
+    "/var/run/docker.sock/",
+    "/var/run/containers/container-manager.sock",
+    "/var/run/containers/container-manager.sock/",
+];
+export function loadCompose(composePath) {
+    if (!existsSync(composePath)) {
+        return null;
+    }
+    const source = readFileSync(composePath, "utf8");
+    const doc = parseDocument(source);
+    const compose = (doc.toJSON() ?? {});
+    return { compose, source };
+}
+export function listServiceNames(compose) {
+    if (!compose.services || typeof compose.services !== "object") {
+        return [];
+    }
+    return Object.keys(compose.services);
+}
+export function extractPublishedTcpPorts(service) {
+    const ports = service.ports;
+    if (!ports) {
+        return [];
+    }
+    const values = Array.isArray(ports) ? ports : [ports];
+    const published = [];
+    for (const entry of values) {
+        const hostPort = parsePortEntry(entry);
+        if (hostPort !== null) {
+            published.push(hostPort);
+        }
+    }
+    return published;
+}
+function parsePortEntry(entry) {
+    if (typeof entry === "number") {
+        return entry;
+    }
+    if (typeof entry === "string") {
+        const trimmed = entry.trim();
+        if (!trimmed || trimmed.startsWith("/")) {
+            return null;
+        }
+        const hostPart = trimmed.split(":")[0]?.replace(/^\[/, "").replace(/\]$/, "");
+        const parsed = Number(hostPart);
+        return Number.isInteger(parsed) ? parsed : null;
+    }
+    if (entry && typeof entry === "object") {
+        const record = entry;
+        if (typeof record.published === "number") {
+            return record.published;
+        }
+        if (typeof record.target === "number" && record.published === undefined) {
+            return record.target;
+        }
+    }
+    return null;
+}
+export function collectPublishedTcpPorts(compose) {
+    const result = new Map();
+    if (!compose.services) {
+        return result;
+    }
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        for (const port of extractPublishedTcpPorts(service)) {
+            const services = result.get(port) ?? [];
+            services.push(serviceName);
+            result.set(port, services);
+        }
+    }
+    return result;
+}
+export function collectComposeInterpolations(compose) {
+    const names = new Set();
+    walkForInterpolation(compose, names);
+    return names;
+}
+function walkForInterpolation(value, names) {
+    if (typeof value === "string") {
+        for (const match of value.matchAll(/\$\{([A-Z0-9_]+)\}/g)) {
+            names.add(match[1]);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            walkForInterpolation(item, names);
+        }
+        return;
+    }
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value)) {
+            walkForInterpolation(child, names);
+        }
+    }
+}
+export function validateComposeSecurity(compose, composeFile, options) {
+    const errors = [];
+    if (!compose.services) {
+        return errors;
+    }
+    const undeclaredSeverity = options.profile === "listing" ? "error" : "warning";
+    for (const finding of undeclaredPrivilegeFindings(compose, options.declaredPrivilege)) {
+        errors.push(makeError(finding.code, composeSpan(composeFile, 1, 1, finding.path), finding.message, finding.suggestion, undeclaredSeverity));
+    }
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        const basePath = `services.${serviceName}`;
+        errors.push(...validateSocketMounts(service, composeFile, basePath));
+        const dependsOn = normalizeDependsOn(service.depends_on);
+        for (const dependency of dependsOn) {
+            if (!compose.services?.[dependency]) {
+                errors.push(makeError("COMPOSE_SERVICE_NOT_FOUND", composeSpan(composeFile, 1, 1, `${basePath}.depends_on`), `Compose 引用了不存在的 service「${dependency}」。`, "請修正 depends_on，或補上對應的 service 定義。"));
+            }
+        }
+    }
+    return errors;
+}
+function normalizeDependsOn(value) {
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.map(String);
+    }
+    if (typeof value === "object") {
+        return Object.keys(value);
+    }
+    return [String(value)];
+}
+function validateSocketMounts(service, composeFile, basePath) {
+    const errors = [];
+    const volumes = normalizeVolumes(service.volumes);
+    for (const mount of volumes) {
+        const source = mount.split(":")[0]?.trim() ?? "";
+        if (isForbiddenSocketMount(source)) {
+            errors.push(makeError("COMPOSE_SOCKET_MOUNT_FORBIDDEN", composeSpan(composeFile, 1, 1, `${basePath}.volumes`), "Managed Profile 不允許掛載 Docker 或 Container Manager socket。", "請移除 docker.sock／container-manager socket 的 volume mount。"));
+        }
+    }
+    return errors;
+}
+function normalizeVolumes(volumes) {
+    if (!volumes) {
+        return [];
+    }
+    const entries = Array.isArray(volumes) ? volumes : [volumes];
+    return entries
+        .map((entry) => {
+        if (typeof entry === "string") {
+            return entry;
+        }
+        if (entry && typeof entry === "object" && "source" in entry) {
+            return String(entry.source);
+        }
+        return "";
+    })
+        .filter(Boolean);
+}
+function isForbiddenSocketMount(source) {
+    const normalized = source.replace(/\/+$/, "");
+    return DOCKER_SOCKET_PATHS.some((path) => normalized === path.replace(/\/+$/, "") || normalized.endsWith("/docker.sock"));
+}
+const PLATFORM_BIND_VARS = new Set(["SYNOPKG_PKGVAR", "SYNO_APP_SECRETS_DIR"]);
+const INTERPOLATED_SOURCE = /^\$\{([A-Z0-9_]+)\}(.*)$/;
+const VALID_SUFFIX_SEGMENT = /^[A-Za-z0-9._-]+$/;
+function collectNamedVolumeNames(compose) {
+    const volumes = compose.volumes;
+    if (!volumes || typeof volumes !== "object" || Array.isArray(volumes)) {
+        return new Set();
+    }
+    return new Set(Object.keys(volumes));
+}
+export function collectVolumeSourceInterpolations(compose) {
+    const names = new Set();
+    for (const mount of listVolumeMounts(compose)) {
+        const match = mount.source.match(INTERPOLATED_SOURCE);
+        if (match) {
+            names.add(match[1]);
+        }
+    }
+    return names;
+}
+export function validateComposeHostBinds(compose, composeFile, context) {
+    const errors = [];
+    if (!compose.services) {
+        return errors;
+    }
+    const namedVolumes = collectNamedVolumeNames(compose);
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        const spanPath = `services.${serviceName}.volumes`;
+        for (const mount of parseVolumeMounts(service.volumes)) {
+            const error = classifyVolumeSource(mount, namedVolumes, context, composeFile, spanPath);
+            if (error) {
+                errors.push(error);
+            }
+        }
+    }
+    return errors;
+}
+function listVolumeMounts(compose) {
+    if (!compose.services) {
+        return [];
+    }
+    const mounts = [];
+    for (const service of Object.values(compose.services)) {
+        mounts.push(...parseVolumeMounts(service.volumes));
+    }
+    return mounts;
+}
+function parseVolumeMounts(volumes) {
+    if (!volumes) {
+        return [];
+    }
+    const entries = Array.isArray(volumes) ? volumes : [volumes];
+    const mounts = [];
+    for (const entry of entries) {
+        if (typeof entry === "string") {
+            const source = parseShortVolumeSource(entry);
+            if (source !== null) {
+                mounts.push({ source });
+            }
+            continue;
+        }
+        if (entry && typeof entry === "object") {
+            const record = entry;
+            if (typeof record.source !== "string" || !record.source.trim()) {
+                continue;
+            }
+            mounts.push({
+                source: record.source.trim(),
+                type: typeof record.type === "string" ? record.type : undefined,
+            });
+        }
+    }
+    return mounts;
+}
+function parseShortVolumeSource(entry) {
+    const trimmed = entry.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const colon = trimmed.indexOf(":");
+    if (colon <= 0) {
+        return null;
+    }
+    return trimmed.slice(0, colon).trim();
+}
+function classifyVolumeSource(mount, namedVolumes, context, composeFile, spanPath) {
+    const source = mount.source;
+    if (!source || isForbiddenSocketMount(source)) {
+        return null;
+    }
+    const span = composeSpan(composeFile, 1, 1, spanPath);
+    if (source.includes("$")) {
+        const match = source.match(INTERPOLATED_SOURCE);
+        const varName = match?.[1];
+        const suffix = match?.[2];
+        if (!varName || suffix === undefined || !isValidatedBindSuffix(suffix)) {
+            return invalidBindSuffix(span);
+        }
+        if (PLATFORM_BIND_VARS.has(varName) || context.sharedFolderParams.has(varName)) {
+            return null;
+        }
+        if (context.installParamNames.has(varName)) {
+            return makeError("COMPOSE_BIND_SOURCE_FORBIDDEN", span, `參數「${varName}」不能作為 host bind source。`, "請改用 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR} 或 type 為 shared_folder 的 install 參數。");
+        }
+        return makeError("COMPOSE_BIND_SOURCE_UNDECLARED", span, `volume source 引用了未宣告的參數「${varName}」。`, `請在 synology-app.yaml 的 install 宣告 ${varName}，且 type 為 shared_folder。`);
+    }
+    if (isLiteralHostPath(source)) {
+        return makeError("COMPOSE_HOST_BIND_FORBIDDEN", span, "禁止將 /volume*、絕對路徑或開發者機器路徑寫成 Compose volume source。", "請改用 install 參數 type: shared_folder，並以 ${參數名} 作為 bind source。");
+    }
+    if (mount.type === "tmpfs") {
+        return null;
+    }
+    if (mount.type === "bind") {
+        return makeError("COMPOSE_BIND_SOURCE_FORBIDDEN", span, "禁止使用 type: bind 掛載非平台允許的 host source。", "請改用 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR} 或契約中的 ${shared_folder 參數}。");
+    }
+    if (!namedVolumes.has(source)) {
+        return makeError("COMPOSE_NAMED_VOLUME_UNDECLARED", span, `短語法 named volume「${source}」未在頂層 volumes 宣告，無法判斷它是 Docker volume 還是 Share 名。`, `請在頂層 volumes 宣告 ${source}，或改用 \${參數名} 作為 shared_folder bind source。`);
+    }
+    return null;
+}
+function invalidBindSuffix(span) {
+    return makeError("COMPOSE_BIND_SUFFIX_INVALID", span, "volume source 的路徑後綴不合法。", "後綴只能是 / 加上一段或多段 [A-Za-z0-9._-]，不可含 ..、${ 或絕對路徑。");
+}
+function isValidatedBindSuffix(suffix) {
+    if (suffix === "") {
+        return true;
+    }
+    if (suffix.includes("${") || suffix.includes(":")) {
+        return false;
+    }
+    if (!/^(\/[A-Za-z0-9._-]+)+$/.test(suffix)) {
+        return false;
+    }
+    return suffix
+        .split("/")
+        .filter(Boolean)
+        .every((segment) => VALID_SUFFIX_SEGMENT.test(segment) && segment !== "." && segment !== "..");
+}
+function isLiteralHostPath(source) {
+    return source.startsWith("/") || source.startsWith(".") || source.startsWith("~");
+}
+const NUMERIC_USER = /^(0|[1-9][0-9]*)(:(0|[1-9][0-9]*))?$/;
+const ROOT_USERS = new Set(["0", "0:0", "root"]);
+export function validateComposeRunAs(compose, composeFile, context) {
+    const errors = [];
+    if (!compose.services) {
+        return errors;
+    }
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        const raw = service.user;
+        if (typeof raw !== "string" || raw.trim() === "") {
+            continue;
+        }
+        const user = raw.trim();
+        const span = composeSpan(composeFile, 1, 1, `services.${serviceName}.user`);
+        if (user.includes("${")) {
+            continue;
+        }
+        if (context.hasSharedFolder && ROOT_USERS.has(user)) {
+            errors.push(makeError("COMPOSE_USER_ROOT_FORBIDDEN", span, "有 Shared Folder 時容器不可用 uid 0／root 寫入 Share。", "請宣告 dsm_user，並以 ${NAME_UID}:${NAME_GID} 當 Compose user。", "warning"));
+            continue;
+        }
+        if (NUMERIC_USER.test(user)) {
+            errors.push(makeError("COMPOSE_USER_NUMERIC_FORBIDDEN", span, "契約不准寫死數字 uid。", "請改用 install dsm_user 參數的 ${NAME_UID}:${NAME_GID}。"));
+        }
+    }
+    return errors;
+}
+export function validateAdminPortMapping(adminport, compose, composeFile) {
+    const published = collectPublishedTcpPorts(compose);
+    const services = published.get(adminport) ?? [];
+    if (services.length !== 1) {
+        return [
+            makeError("CONTRACT_ADMINPORT_UNMAPPED", composeSpan(composeFile, 1, 1, `adminport:${adminport}`), `adminport ${adminport} 必須對應 Compose 中恰好一個 published TCP port。`, "請在 compose.yaml 發佈與 adminport 相同的 host port，並確認只有一個 service 使用它。"),
+        ];
+    }
+    return [];
+}

package/dist/compose/env.d.ts

@@ -0,0 +1,7 @@
+export interface ComposeEnvironment {
+    SYNOPKG_PKGVAR: string;
+    SYNO_APP_SECRETS_DIR: string;
+}
+export declare function prepareComposeEnvironment(projectRoot: string): ComposeEnvironment;
+export declare function materializeComposePaths(projectRoot: string, composePath: string): ComposeEnvironment;
+export declare function composeEnvDirsExist(projectRoot: string): boolean;

package/dist/compose/env.js

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export function prepareComposeEnvironment(projectRoot) {
+    const varDir = join(projectRoot, ".synopkgland", "var");
+    const secretsDir = join(projectRoot, ".synopkgland", "secrets");
+    mkdirSync(varDir, { recursive: true });
+    mkdirSync(secretsDir, { recursive: true });
+    return {
+        SYNOPKG_PKGVAR: varDir,
+        SYNO_APP_SECRETS_DIR: secretsDir,
+    };
+}
+export function materializeComposePaths(projectRoot, composePath) {
+    const env = prepareComposeEnvironment(projectRoot);
+    if (!existsSync(composePath)) {
+        return env;
+    }
+    const source = readFileSync(composePath, "utf8");
+    for (const match of source.matchAll(/\$\{SYNOPKG_PKGVAR\}([^:\s"'`]+)/g)) {
+        const subpath = match[1].replace(/^\/+/, "");
+        if (subpath) {
+            mkdirSync(join(env.SYNOPKG_PKGVAR, subpath), { recursive: true });
+        }
+    }
+    for (const match of source.matchAll(/\$\{SYNO_APP_SECRETS_DIR\}([^:\s"'`]+)/g)) {
+        const subpath = match[1].replace(/^\/+/, "");
+        if (subpath) {
+            mkdirSync(join(env.SYNO_APP_SECRETS_DIR, subpath), { recursive: true });
+        }
+    }
+    return env;
+}
+export function composeEnvDirsExist(projectRoot) {
+    return (existsSync(join(projectRoot, ".synopkgland", "var")) &&
+        existsSync(join(projectRoot, ".synopkgland", "secrets")));
+}

package/dist/compose/privilege.d.ts

@@ -0,0 +1,14 @@
+import type { AppContract, ComposeDocument } from "../types.js";
+export declare const PRIVILEGE_FLAGS: readonly ["privileged", "host_network", "host_pid", "host_ipc", "devices", "cap_add"];
+export type PrivilegeFlag = (typeof PRIVILEGE_FLAGS)[number];
+export interface PrivilegeFinding {
+    flag: PrivilegeFlag;
+    code: string;
+    serviceName: string;
+    path: string;
+    message: string;
+    suggestion: string;
+}
+export declare function declaredPrivilegeFlags(contract: AppContract): Set<PrivilegeFlag>;
+export declare function scanComposePrivilege(compose: ComposeDocument): PrivilegeFinding[];
+export declare function undeclaredPrivilegeFindings(compose: ComposeDocument, declared: ReadonlySet<PrivilegeFlag>): PrivilegeFinding[];

package/dist/compose/privilege.js

@@ -0,0 +1,102 @@
+export const PRIVILEGE_FLAGS = [
+    "privileged",
+    "host_network",
+    "host_pid",
+    "host_ipc",
+    "devices",
+    "cap_add",
+];
+const FLAG_ERRORS = {
+    privileged: {
+        code: "COMPOSE_PRIVILEGED_FORBIDDEN",
+        message: "Compose 使用 privileged 容器，契約未宣告 privilege.privileged。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.privileged: true，或移除 privileged: true。",
+    },
+    host_network: {
+        code: "COMPOSE_HOST_NETWORK_FORBIDDEN",
+        message: "Compose 使用 host network，契約未宣告 privilege.host_network。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.host_network: true，或改用受控網路模式。",
+    },
+    host_pid: {
+        code: "COMPOSE_HOST_PID_FORBIDDEN",
+        message: "Compose 使用 host PID，契約未宣告 privilege.host_pid。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.host_pid: true，或移除 pid: host。",
+    },
+    host_ipc: {
+        code: "COMPOSE_HOST_IPC_FORBIDDEN",
+        message: "Compose 使用 host IPC，契約未宣告 privilege.host_ipc。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.host_ipc: true，或移除 ipc: host。",
+    },
+    devices: {
+        code: "COMPOSE_DEVICES_FORBIDDEN",
+        message: "Compose 掛載 devices，契約未宣告 privilege.devices。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.devices: true，或移除 devices。",
+    },
+    cap_add: {
+        code: "COMPOSE_CAP_ADD_FORBIDDEN",
+        message: "Compose 使用額外 cap_add，契約未宣告 privilege.cap_add。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.cap_add: true，或移除 cap_add。",
+    },
+};
+export function declaredPrivilegeFlags(contract) {
+    const raw = contract.privilege;
+    const flags = new Set();
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return flags;
+    }
+    const record = raw;
+    for (const flag of PRIVILEGE_FLAGS) {
+        if (record[flag] === true) {
+            flags.add(flag);
+        }
+    }
+    return flags;
+}
+export function scanComposePrivilege(compose) {
+    const findings = [];
+    if (!compose.services) {
+        return findings;
+    }
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        const basePath = `services.${serviceName}`;
+        const add = (flag, path) => {
+            const spec = FLAG_ERRORS[flag];
+            findings.push({
+                flag,
+                code: spec.code,
+                serviceName,
+                path,
+                message: spec.message,
+                suggestion: spec.suggestion,
+            });
+        };
+        if (service.privileged === true) {
+            add("privileged", `${basePath}.privileged`);
+        }
+        if (service.network_mode === "host") {
+            add("host_network", `${basePath}.network_mode`);
+        }
+        if (service.pid === "host") {
+            add("host_pid", `${basePath}.pid`);
+        }
+        if (service.ipc === "host") {
+            add("host_ipc", `${basePath}.ipc`);
+        }
+        if (hasEntries(service.devices)) {
+            add("devices", `${basePath}.devices`);
+        }
+        if (hasEntries(service.cap_add)) {
+            add("cap_add", `${basePath}.cap_add`);
+        }
+    }
+    return findings;
+}
+export function undeclaredPrivilegeFindings(compose, declared) {
+    return scanComposePrivilege(compose).filter((item) => !declared.has(item.flag));
+}
+function hasEntries(value) {
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    return typeof value === "string" && value.trim() !== "";
+}

package/dist/compose/runner.d.ts

@@ -0,0 +1,32 @@
+import { type ComposeEnvironment } from "./env.js";
+export interface ComposeContainerState {
+    Health?: string;
+    State?: string;
+}
+export interface ComposeRunner {
+    up(projectRoot: string): Promise<void>;
+    waitReady(projectRoot: string): Promise<void>;
+    down?(projectRoot: string): Promise<void>;
+}
+export interface ComposeInvocation {
+    command: string;
+    args: string[];
+    env?: ComposeEnvironment;
+}
+export interface ComposePollOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function evaluateComposeReady(containers: ComposeContainerState[]): {
+    ready: boolean;
+    hasHealthcheck: boolean;
+};
+export declare function pollUntilComposeReady(inspect: () => Promise<ComposeContainerState[]>, options?: ComposePollOptions): Promise<void>;
+export declare class RecordingComposeRunner implements ComposeRunner {
+    readonly invocations: ComposeInvocation[];
+    up(_projectRoot: string): Promise<void>;
+    waitReady(_projectRoot: string): Promise<void>;
+}
+export declare function createDockerComposeRunner(options?: ComposePollOptions): ComposeRunner;
+export declare function isDockerAvailable(): Promise<boolean>;

package/dist/compose/runner.js

@@ -0,0 +1,84 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { materializeComposePaths } from "./env.js";
+import { COMPOSE_FILENAME } from "../discovery.js";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+export function evaluateComposeReady(containers) {
+    if (containers.length === 0) {
+        return { ready: false, hasHealthcheck: false };
+    }
+    const hasHealthcheck = containers.some((c) => c.Health && c.Health !== "");
+    if (hasHealthcheck) {
+        const ready = containers.every((c) => !c.Health || c.Health === "healthy");
+        return { ready, hasHealthcheck: true };
+    }
+    const ready = containers.every((c) => c.State === "running");
+    return { ready, hasHealthcheck: false };
+}
+export async function pollUntilComposeReady(inspect, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const intervalMs = options.intervalMs ?? 1_000;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const containers = await inspect();
+        const { ready } = evaluateComposeReady(containers);
+        if (ready) {
+            return;
+        }
+        await sleep(intervalMs);
+    }
+    const containers = await inspect();
+    const { hasHealthcheck } = evaluateComposeReady(containers);
+    throw new Error(hasHealthcheck ? "COMPOSE_NOT_HEALTHY" : "COMPOSE_NOT_RUNNING");
+}
+export class RecordingComposeRunner {
+    invocations = [];
+    async up(_projectRoot) {
+        this.invocations.push({ command: "compose", args: ["up", "-d"] });
+    }
+    async waitReady(_projectRoot) {
+        this.invocations.push({ command: "compose", args: ["ps", "--format", "json"] });
+    }
+}
+async function runDockerCompose(projectRoot, args, env) {
+    const { stdout } = await execFileAsync("docker", ["compose", ...args], {
+        cwd: projectRoot,
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024,
+        env: env ? { ...process.env, ...env } : process.env,
+    });
+    return stdout;
+}
+async function inspectComposeContainers(projectRoot) {
+    const stdout = await runDockerCompose(projectRoot, ["ps", "--format", "json"]);
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return lines.map((line) => JSON.parse(line));
+}
+export function createDockerComposeRunner(options = {}) {
+    return {
+        async up(projectRoot) {
+            const env = materializeComposePaths(projectRoot, join(projectRoot, COMPOSE_FILENAME));
+            await runDockerCompose(projectRoot, ["up", "-d"], env);
+        },
+        async waitReady(projectRoot) {
+            await pollUntilComposeReady(() => inspectComposeContainers(projectRoot), options);
+        },
+        async down(projectRoot) {
+            await runDockerCompose(projectRoot, ["down", "--remove-orphans"]);
+        },
+    };
+}
+export async function isDockerAvailable() {
+    try {
+        await execFileAsync("docker", ["info"], { encoding: "utf8" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/contract/load.d.ts

@@ -0,0 +1,25 @@
+import { type Document } from "yaml";
+import type { AppContract, InstallParameter } from "../types.js";
+export interface ParsedContract {
+    contract: AppContract;
+    doc: Document;
+}
+export declare function loadContract(contractPath: string): ParsedContract;
+export declare function getScalarPosition(doc: Document, keyPath: string[]): {
+    line: number;
+    column: number;
+} | null;
+export declare function getValuePosition(doc: Document, keyPath: string[]): {
+    line: number;
+    column: number;
+} | null;
+export declare function collectInstallParameters(contract: AppContract): Array<{
+    name: string;
+    param: InstallParameter;
+}>;
+export declare function isDeveloperAuthoredString(value: unknown): value is string;
+export declare function stringViolations(value: string): {
+    hasControlChars: boolean;
+    hasInterpolation: boolean;
+    tooLong: boolean;
+};