@companyhelm/cli 0.2.0 → 0.4.0

package/dist/core/runner/RunnerSupervisor.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
 const DEFAULT_HOST_DOCKER_PATH = "unix:///var/run/docker.sock";
 export class RunnerSupervisor {
@@ -15,15 +16,23 @@ export class RunnerSupervisor {
         };
     }
     buildStartArgs(input) {
-        const runnerCliPath = this.resolveRunnerCliPath();
         const logLevel = (input.logLevel ?? "info").toUpperCase();
         const hostDockerArgs = input.useHostDockerRuntime
             ? ["--use-host-docker-runtime", "--host-docker-path", this.resolveHostDockerPath()]
             : [];
+        const runnerEntrypoint = this.resolveRunnerEntrypointPath();
+        const runnerCliOverridePath = this.resolveRunnerCliOverridePath();
+        const env = input.workspaceMode === "current-working-directory" && input.projectRoot
+            ? {
+                COMPANYHELM_RUNNER_WORKSPACE_MODE: input.workspaceMode,
+                COMPANYHELM_RUNNER_PROJECT_ROOT: input.projectRoot,
+            }
+            : undefined;
         return {
             command: process.execPath,
             args: [
-                runnerCliPath,
+                runnerEntrypoint,
+                ...(runnerCliOverridePath ? [runnerCliOverridePath] : []),
                 "--config-path",
                 this.configPath,
                 "start",
@@ -39,7 +48,8 @@ export class RunnerSupervisor {
                 input.secret,
                 "--log-level",
                 logLevel
-            ]
+            ],
+            env
         };
     }
     buildStopArgs() {
@@ -63,6 +73,13 @@ export class RunnerSupervisor {
         const packageJsonPath = require.resolve("@companyhelm/runner/package.json");
         return path.resolve(path.dirname(packageJsonPath), "dist/cli.js");
     }
+    resolveRunnerCliOverridePath() {
+        const overridePath = String(process.env.COMPANYHELM_RUNNER_CLI_PATH || "").trim();
+        return overridePath || null;
+    }
+    resolveRunnerEntrypointPath() {
+        return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "runner-bootstrap.js");
+    }
     resolveHostDockerPath() {
         const dockerHost = String(process.env.DOCKER_HOST || "").trim();
         if (dockerHost) {

package/dist/core/runner/runner-bootstrap.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveRunnerCliEntrypointArg(argv: string[]): string | null;
+export declare function runRunnerBootstrap(): Promise<void>;

package/dist/core/runner/runner-bootstrap.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const require = createRequire(import.meta.url);
+function applyCurrentWorkingDirectoryMode(projectRoot) {
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    const fsModule = require("node:fs");
+    const originalRmSync = fsModule.rmSync.bind(fsModule);
+    fsModule.rmSync = ((target, options) => {
+        if (path.resolve(String(target)) === resolvedProjectRoot) {
+            return;
+        }
+        return originalRmSync(target, options);
+    });
+    const configModule = require("@companyhelm/runner/dist/config.js");
+    const originalParse = configModule.config.parse.bind(configModule.config);
+    configModule.config.parse = ((input = {}) => originalParse({
+        ...input,
+        workspaces_directory: resolvedProjectRoot
+    }));
+    const threadLifecycle = require("@companyhelm/runner/dist/service/thread_lifecycle.js");
+    threadLifecycle.resolveThreadDirectory = (() => resolvedProjectRoot);
+}
+export function resolveRunnerCliEntrypointArg(argv) {
+    const candidate = String(argv[2] || "").trim();
+    if (!candidate || candidate.startsWith("-")) {
+        return null;
+    }
+    return candidate;
+}
+const workspaceMode = String(process.env.COMPANYHELM_RUNNER_WORKSPACE_MODE || "").trim();
+const projectRoot = String(process.env.COMPANYHELM_RUNNER_PROJECT_ROOT || "").trim();
+export async function runRunnerBootstrap() {
+    if (workspaceMode === "current-working-directory" && projectRoot) {
+        applyCurrentWorkingDirectoryMode(projectRoot);
+    }
+    const runnerEntrypoint = resolveRunnerCliEntrypointArg(process.argv);
+    if (runnerEntrypoint) {
+        process.argv.splice(2, 1);
+    }
+    await import(runnerEntrypoint ? pathToFileURL(runnerEntrypoint).href : "@companyhelm/runner/dist/cli.js");
+}
+const invokedAsEntrypoint = process.argv[1]
+    ? pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url
+    : false;
+if (invokedAsEntrypoint) {
+    await runRunnerBootstrap();
+}

package/dist/core/runtime/CliPackageMetadata.d.ts

@@ -0,0 +1,3 @@
+export declare class CliPackageMetadata {
+    version(): string;
+}

package/dist/core/runtime/CliPackageMetadata.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+export class CliPackageMetadata {
+    version() {
+        const manifestPath = new URL("../../../package.json", import.meta.url);
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return manifest.version;
+    }
+}

package/dist/core/runtime/CliRoot.d.ts

@@ -0,0 +1,2 @@
+export declare function defaultCliRoot(): string;
+export declare function defaultCliConfigRoot(): string;

package/dist/core/runtime/CliRoot.js

@@ -0,0 +1,23 @@
+import os from "node:os";
+import path from "node:path";
+function defaultCliBaseRoot() {
+    return path.join(os.homedir(), ".companyhelm", "cli");
+}
+export function defaultCliRoot() {
+    const explicitRoot = String(process.env.COMPANYHELM_HOME || "").trim();
+    if (explicitRoot) {
+        return path.resolve(explicitRoot);
+    }
+    return path.join(defaultCliBaseRoot(), "runtime");
+}
+export function defaultCliConfigRoot() {
+    const explicitRoot = String(process.env.COMPANYHELM_CONFIG_HOME || "").trim();
+    if (explicitRoot) {
+        return path.resolve(explicitRoot);
+    }
+    const explicitRuntimeRoot = String(process.env.COMPANYHELM_HOME || "").trim();
+    if (explicitRuntimeRoot) {
+        return path.resolve(explicitRuntimeRoot);
+    }
+    return defaultCliBaseRoot();
+}

package/dist/core/runtime/ImageCatalog.js

@@ -1,8 +1,8 @@
-import { LocalConfigStore } from "./LocalConfigStore.js";
 import { defaultManagedImageReference } from "./ManagedImages.js";
+import { RepoConfigStore } from "./RepoConfigStore.js";
 export class ImageCatalog {
     resolve() {
-        const configuredImages = new LocalConfigStore().load().images;
+        const configuredImages = new RepoConfigStore().load().images;
         return {
             api: configuredImages.api || process.env.COMPANYHELM_API_IMAGE || defaultManagedImageReference("api"),
             frontend: configuredImages.frontend || process.env.COMPANYHELM_WEB_IMAGE || defaultManagedImageReference("frontend"),

package/dist/core/runtime/LocalConfigStore.d.ts

@@ -1,15 +1,15 @@
-import type { ManagedImageService } from "./ManagedImages.js";
+export type AgentWorkspaceMode = "dedicated" | "current-working-directory";
 export interface LocalConfig {
-    images: Partial<Record<ManagedImageService, string>>;
+    agentWorkspaceMode?: AgentWorkspaceMode;
 }
 export declare class LocalConfigStore {
     private readonly root;
     constructor(root?: string);
     configPath(): string;
     load(): LocalConfig;
-    setImage(service: ManagedImageService, image: string): {
+    setAgentWorkspaceMode(agentWorkspaceMode: AgentWorkspaceMode): {
         configPath: string;
-        image: string;
+        agentWorkspaceMode: AgentWorkspaceMode;
     };
     save(config: LocalConfig): void;
     private parse;

package/dist/core/runtime/LocalConfigStore.js

@@ -1,8 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import { defaultCliConfigRoot } from "./CliRoot.js";
+function defaultLocalConfigRoot() {
+    return defaultCliConfigRoot();
+}
 export class LocalConfigStore {
     root;
-    constructor(root = process.cwd()) {
+    constructor(root = defaultLocalConfigRoot()) {
         this.root = root;
     }
     configPath() {
@@ -11,49 +15,36 @@ export class LocalConfigStore {
     load() {
         const configPath = this.configPath();
         if (!fs.existsSync(configPath)) {
-            return { images: {} };
+            return {};
         }
         return this.parse(fs.readFileSync(configPath, "utf8"));
     }
-    setImage(service, image) {
+    setAgentWorkspaceMode(agentWorkspaceMode) {
         const nextConfig = this.load();
-        nextConfig.images[service] = image;
+        nextConfig.agentWorkspaceMode = agentWorkspaceMode;
         this.save(nextConfig);
-        return { configPath: this.configPath(), image };
+        return { configPath: this.configPath(), agentWorkspaceMode };
     }
     save(config) {
-        const lines = ["images:"];
-        if (config.images.api) {
-            lines.push(`  api: ${config.images.api}`);
-        }
-        if (config.images.frontend) {
-            lines.push(`  frontend: ${config.images.frontend}`);
+        const lines = [];
+        if (config.agentWorkspaceMode) {
+            lines.push(`agent_workspace_mode: ${config.agentWorkspaceMode}`);
         }
+        fs.mkdirSync(path.dirname(this.configPath()), { recursive: true });
         fs.writeFileSync(this.configPath(), `${lines.join("\n")}\n`, "utf8");
     }
     parse(content) {
-        const images = {};
-        let inImagesSection = false;
+        let agentWorkspaceMode;
         for (const rawLine of content.split(/\r?\n/)) {
             const line = rawLine.trimEnd();
             if (line.trim().length === 0 || line.trimStart().startsWith("#")) {
                 continue;
             }
-            if (line === "images:") {
-                inImagesSection = true;
-                continue;
-            }
-            if (inImagesSection && /^[^\s]/.test(line)) {
-                inImagesSection = false;
-            }
-            if (!inImagesSection) {
-                continue;
-            }
-            const match = line.match(/^  (api|frontend):\s*(.+)$/);
-            if (match) {
-                images[match[1]] = match[2];
+            const workspaceModeMatch = line.match(/^agent_workspace_mode:\s*(dedicated|current-working-directory)$/);
+            if (workspaceModeMatch) {
+                agentWorkspaceMode = workspaceModeMatch[1];
             }
         }
-        return { images };
+        return { agentWorkspaceMode };
     }
 }

package/dist/core/runtime/PublicImageTagRegistry.d.ts

@@ -12,5 +12,6 @@ export declare class PublicImageTagRegistry {
     private fetchJson;
     private parseRetryAfterMs;
     private sleep;
+    private mapWithConcurrency;
 }
 export {};

package/dist/core/runtime/PublicImageTagRegistry.js

@@ -2,6 +2,7 @@ import { buildManagedImageReference, getManagedImageDefinition } from "./Managed
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
 const MAX_FETCH_ATTEMPTS = 3;
 const DEFAULT_RETRY_DELAY_MS = 250;
+const METADATA_FETCH_CONCURRENCY = 6;
 class PublicRegistryRequestError extends Error {
     status;
     retryAfterMs;
@@ -31,15 +32,13 @@ export class PublicImageTagRegistry {
             throw new Error(payload.errors[0]?.message || `Unable to load ${service} image tags.`);
         }
         const uniqueTags = [...new Set(payload.tags ?? [])].map((tag, position) => ({ tag, position }));
+        const candidateTags = uniqueTags.slice(0, limit);
         const createdAtByDigest = new Map();
-        const tagsWithMetadata = [];
-        for (const { tag, position } of uniqueTags) {
-            tagsWithMetadata.push({
-                tag,
-                position,
-                createdAt: await this.fetchCreatedAt(repositoryPath, token, tag, createdAtByDigest)
-            });
-        }
+        const tagsWithMetadata = await this.mapWithConcurrency(candidateTags, METADATA_FETCH_CONCURRENCY, async ({ tag, position }) => ({
+            tag,
+            position,
+            createdAt: await this.fetchCreatedAt(repositoryPath, token, tag, createdAtByDigest)
+        }));
         return tagsWithMetadata
             .sort((left, right) => {
             const leftTimestamp = left.createdAt ? Date.parse(left.createdAt) : Number.NEGATIVE_INFINITY;
@@ -49,7 +48,6 @@ export class PublicImageTagRegistry {
             }
             return left.position - right.position;
         })
-            .slice(0, limit)
             .map(({ tag, createdAt }) => ({ tag, createdAt }));
     }
     buildImageReference(service, tag) {
@@ -89,14 +87,20 @@ export class PublicImageTagRegistry {
             if (!configDigest) {
                 return undefined;
             }
-            if (createdAtByDigest.has(configDigest)) {
-                return createdAtByDigest.get(configDigest);
+            const existingCreatedAt = createdAtByDigest.get(configDigest);
+            if (existingCreatedAt) {
+                return await existingCreatedAt;
             }
-            const config = await this.fetchJson(`https://public.ecr.aws/v2/${repositoryPath}/blobs/${configDigest}`, {
+            const createdAtPromise = this.fetchJson(`https://public.ecr.aws/v2/${repositoryPath}/blobs/${configDigest}`, {
                 Authorization: `Bearer ${token}`
+            })
+                .then((config) => config.created)
+                .catch((error) => {
+                createdAtByDigest.delete(configDigest);
+                throw error;
             });
-            createdAtByDigest.set(configDigest, config.created);
-            return config.created;
+            createdAtByDigest.set(configDigest, createdAtPromise);
+            return await createdAtPromise;
         }
         catch (error) {
             if (error instanceof PublicRegistryRequestError) {
@@ -145,4 +149,20 @@ export class PublicImageTagRegistry {
     async sleep(delayMs) {
         await new Promise((resolve) => setTimeout(resolve, delayMs));
     }
+    async mapWithConcurrency(items, concurrency, mapper) {
+        if (items.length === 0) {
+            return [];
+        }
+        const results = new Array(items.length);
+        let nextIndex = 0;
+        const workerCount = Math.min(concurrency, items.length);
+        await Promise.all(Array.from({ length: workerCount }, async () => {
+            while (nextIndex < items.length) {
+                const currentIndex = nextIndex;
+                nextIndex += 1;
+                results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+            }
+        }));
+        return results;
+    }
 }

package/dist/core/runtime/RepoConfigStore.d.ts

@@ -0,0 +1,16 @@
+import type { ManagedImageService } from "./ManagedImages.js";
+export interface RepoConfig {
+    images: Partial<Record<ManagedImageService, string>>;
+}
+export declare class RepoConfigStore {
+    private readonly root;
+    constructor(root?: string);
+    configPath(): string;
+    load(): RepoConfig;
+    setImage(service: ManagedImageService, image: string): {
+        configPath: string;
+        image: string;
+    };
+    save(config: RepoConfig): void;
+    private parse;
+}

package/dist/core/runtime/RepoConfigStore.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+function defaultRepoConfigRoot() {
+    return process.cwd();
+}
+export class RepoConfigStore {
+    root;
+    constructor(root = defaultRepoConfigRoot()) {
+        this.root = root;
+    }
+    configPath() {
+        return path.join(this.root, "config.yaml");
+    }
+    load() {
+        const configPath = this.configPath();
+        if (!fs.existsSync(configPath)) {
+            return { images: {} };
+        }
+        return this.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    setImage(service, image) {
+        const nextConfig = this.load();
+        nextConfig.images[service] = image;
+        this.save(nextConfig);
+        return { configPath: this.configPath(), image };
+    }
+    save(config) {
+        const lines = ["images:"];
+        if (config.images.api) {
+            lines.push(`  api: ${config.images.api}`);
+        }
+        if (config.images.frontend) {
+            lines.push(`  frontend: ${config.images.frontend}`);
+        }
+        fs.mkdirSync(path.dirname(this.configPath()), { recursive: true });
+        fs.writeFileSync(this.configPath(), `${lines.join("\n")}\n`, "utf8");
+    }
+    parse(content) {
+        const images = {};
+        let inImagesSection = false;
+        for (const rawLine of content.split(/\r?\n/)) {
+            const line = rawLine.trimEnd();
+            if (line.trim().length === 0 || line.trimStart().startsWith("#")) {
+                continue;
+            }
+            if (line === "images:") {
+                inImagesSection = true;
+                continue;
+            }
+            if (inImagesSection && /^[^\s]/.test(line)) {
+                inImagesSection = false;
+            }
+            if (!inImagesSection) {
+                continue;
+            }
+            const match = line.match(/^  (api|frontend):\s*(.+)$/);
+            if (match) {
+                images[match[1]] = match[2];
+            }
+        }
+        return { images };
+    }
+}

package/dist/core/runtime/RuntimePaths.d.ts

@@ -3,6 +3,8 @@ export declare class RuntimePaths {
     constructor(root: string);
     stateFilePath(): string;
     composeFilePath(): string;
+    apiDirectoryPath(): string;
+    apiEnvPath(): string;
     apiConfigPath(): string;
     frontendConfigPath(): string;
     seedFilePath(): string;

package/dist/core/runtime/RuntimePaths.js

@@ -10,6 +10,12 @@ export class RuntimePaths {
     composeFilePath() {
         return path.join(this.root, "docker-compose.yaml");
     }
+    apiDirectoryPath() {
+        return path.join(this.root, "api");
+    }
+    apiEnvPath() {
+        return path.join(this.apiDirectoryPath(), ".env");
+    }
     apiConfigPath() {
         return path.join(this.root, "api-config.yaml");
     }

package/dist/core/services/ManagedServiceNames.d.ts

@@ -0,0 +1,5 @@
+export declare const MANAGED_SERVICE_KEYS: readonly ["postgres", "api", "frontend", "runner"];
+export type ManagedServiceKey = (typeof MANAGED_SERVICE_KEYS)[number];
+export declare const MANAGED_SERVICE_NAMES: Record<ManagedServiceKey, string>;
+export declare const AVAILABLE_MANAGED_SERVICE_NAMES: string[];
+export declare function resolveManagedServiceKey(serviceName: string): ManagedServiceKey | null;

package/dist/core/services/ManagedServiceNames.js

@@ -0,0 +1,12 @@
+export const MANAGED_SERVICE_KEYS = ["postgres", "api", "frontend", "runner"];
+export const MANAGED_SERVICE_NAMES = {
+    postgres: "postgres",
+    api: "companyhelm-api",
+    frontend: "companyhelm-web",
+    runner: "companyhelm-runner"
+};
+const SERVICE_NAME_TO_KEY = new Map(Object.entries(MANAGED_SERVICE_NAMES).map(([key, value]) => [value, key]));
+export const AVAILABLE_MANAGED_SERVICE_NAMES = MANAGED_SERVICE_KEYS.map((key) => MANAGED_SERVICE_NAMES[key]);
+export function resolveManagedServiceKey(serviceName) {
+    return SERVICE_NAME_TO_KEY.get(serviceName.trim()) ?? null;
+}

package/dist/preflight/ApiPortPreflightCheck.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class ApiPortPreflightCheck implements PreflightCheck {
+    private readonly delegate;
+    constructor(port: number);
+    run(): Promise<void>;
+}

package/dist/preflight/ApiPortPreflightCheck.js

@@ -0,0 +1,10 @@
+import { PortAvailabilityPreflightCheck } from "./PortAvailabilityPreflightCheck.js";
+export class ApiPortPreflightCheck {
+    delegate;
+    constructor(port) {
+        this.delegate = new PortAvailabilityPreflightCheck("companyhelm-api", port);
+    }
+    run() {
+        return this.delegate.run();
+    }
+}

package/dist/preflight/DockerInstalledPreflightCheck.d.ts

@@ -0,0 +1,7 @@
+import { CommandRunner } from "../core/process/CommandRunner.js";
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class DockerInstalledPreflightCheck implements PreflightCheck {
+    private readonly commandRunner;
+    constructor(commandRunner?: CommandRunner);
+    run(): Promise<void>;
+}

package/dist/preflight/DockerInstalledPreflightCheck.js

@@ -0,0 +1,15 @@
+import { CommandRunner } from "../core/process/CommandRunner.js";
+export class DockerInstalledPreflightCheck {
+    commandRunner;
+    constructor(commandRunner = new CommandRunner()) {
+        this.commandRunner = commandRunner;
+    }
+    async run() {
+        try {
+            await this.commandRunner.capture("docker", ["--version"]);
+        }
+        catch {
+            throw new Error("Docker is required for `companyhelm up`, but the `docker` command is unavailable. Install Docker and make sure it is on your PATH.");
+        }
+    }
+}

package/dist/preflight/PortAvailabilityPreflightCheck.d.ts

@@ -0,0 +1,7 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class PortAvailabilityPreflightCheck implements PreflightCheck {
+    private readonly serviceName;
+    private readonly port;
+    constructor(serviceName: string, port: number);
+    run(): Promise<void>;
+}

package/dist/preflight/PortAvailabilityPreflightCheck.js

@@ -0,0 +1,31 @@
+import net from "node:net";
+export class PortAvailabilityPreflightCheck {
+    serviceName;
+    port;
+    constructor(serviceName, port) {
+        this.serviceName = serviceName;
+        this.port = port;
+    }
+    async run() {
+        await new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.once("error", (error) => {
+                if (error.code === "EADDRINUSE") {
+                    reject(new Error(`${this.serviceName} cannot start because port ${this.port} is already in use.`));
+                    return;
+                }
+                reject(new Error(`${this.serviceName} cannot verify port ${this.port}: ${error.message}`));
+            });
+            server.once("listening", () => {
+                server.close((closeError) => {
+                    if (closeError) {
+                        reject(closeError);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+            server.listen(this.port, "0.0.0.0");
+        });
+    }
+}

package/dist/preflight/PostgresPortPreflightCheck.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class PostgresPortPreflightCheck implements PreflightCheck {
+    private readonly delegate;
+    constructor(port?: number);
+    run(): Promise<void>;
+}

package/dist/preflight/PostgresPortPreflightCheck.js

@@ -0,0 +1,10 @@
+import { PortAvailabilityPreflightCheck } from "./PortAvailabilityPreflightCheck.js";
+export class PostgresPortPreflightCheck {
+    delegate;
+    constructor(port = 5432) {
+        this.delegate = new PortAvailabilityPreflightCheck("Postgres", port);
+    }
+    run() {
+        return this.delegate.run();
+    }
+}

package/dist/preflight/PreflightCheck.d.ts

@@ -0,0 +1,3 @@
+export interface PreflightCheck {
+    run(): Promise<void>;
+}

package/dist/preflight/PreflightCheck.js

@@ -0,0 +1 @@
+export {};

package/dist/preflight/WebPortPreflightCheck.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class WebPortPreflightCheck implements PreflightCheck {
+    private readonly delegate;
+    constructor(port: number);
+    run(): Promise<void>;
+}

package/dist/preflight/WebPortPreflightCheck.js

@@ -0,0 +1,10 @@
+import { PortAvailabilityPreflightCheck } from "./PortAvailabilityPreflightCheck.js";
+export class WebPortPreflightCheck {
+    delegate;
+    constructor(port) {
+        this.delegate = new PortAvailabilityPreflightCheck("companyhelm-web", port);
+    }
+    run() {
+        return this.delegate.run();
+    }
+}

package/dist/preflight/runStartupPreflightChecks.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedServiceSources } from "../core/local/LocalRepoSourceResolver.js";
+import type { CommandRunner } from "../core/process/CommandRunner.js";
+import type { RuntimePorts, RuntimeState } from "../core/runtime/RuntimeState.js";
+import type { ManagedServiceStatus } from "../core/status/StatusService.js";
+interface StartupStatusSnapshot {
+    postgres: ManagedServiceStatus;
+    api: ManagedServiceStatus;
+    frontend: ManagedServiceStatus;
+}
+interface StartupPreflightOptions {
+    commandRunner: CommandRunner;
+    currentState: RuntimeState | null;
+    desiredSources: ResolvedServiceSources;
+    ports: RuntimePorts;
+    readStatus: () => Promise<StartupStatusSnapshot>;
+}
+export declare function runStartupPreflightChecks(options: StartupPreflightOptions): Promise<void>;
+export {};