@companyhelm/cli 0.1.4 → 0.1.5

package/dist/commands/dependencies.d.ts

@@ -1,8 +1,12 @@
 import { type RuntimeVersions } from "../core/runtime/VersionCatalog.js";
 import { type StatusSnapshot } from "../core/status/StatusService.js";
 export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LocalRepoOptionValue = string | true | undefined;
 export interface UpOptions {
     logLevel?: LogLevel;
+    useHostDockerRuntime?: boolean;
+    apiRepoPath?: LocalRepoOptionValue;
+    webRepoPath?: LocalRepoOptionValue;
 }
 export interface ResetOptions {
     removeGithubAppConfig?: boolean;

package/dist/commands/dependencies.js

@@ -5,6 +5,10 @@ import { DeploymentBootstrapper } from "../core/bootstrap/DeploymentBootstrapper
 import { ApiEnvFileWriter } from "../core/config/ApiEnvFileWriter.js";
 import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
 import { DockerStackManager } from "../core/docker/DockerStackManager.js";
+import { ApiLocalService } from "../core/local/ApiLocalService.js";
+import { LocalRepoSourceResolver } from "../core/local/LocalRepoSourceResolver.js";
+import { LocalServiceProcessManager } from "../core/local/LocalServiceProcessManager.js";
+import { WebLocalService } from "../core/local/WebLocalService.js";
 import { LogsService } from "../core/logs/LogsService.js";
 import { CommandRunner } from "../core/process/CommandRunner.js";
 import { ProjectPaths } from "../core/runtime/ProjectPaths.js";
@@ -31,8 +35,24 @@ export function createDefaultDependencies() {
     const githubAppConfigStore = new GithubAppConfigStore();
     const apiEnvFileWriter = new ApiEnvFileWriter(process.cwd());
     const projectPaths = new ProjectPaths(process.cwd());
+    const localRepoSourceResolver = new LocalRepoSourceResolver(process.cwd());
+    const localServiceProcessManager = new LocalServiceProcessManager();
+    const apiLocalService = new ApiLocalService(localServiceProcessManager, commandRunner);
+    const webLocalService = new WebLocalService(localServiceProcessManager, commandRunner);
     const versionCatalog = new VersionCatalog();
     const statusService = new StatusService(() => dockerStackManager.runningServices(), {
+        api: () => {
+            const state = stateStore.load();
+            return state?.services.api.source === "local"
+                ? localServiceProcessManager.isRunning(state.services.api)
+                : undefined;
+        },
+        frontend: () => {
+            const state = stateStore.load();
+            return state?.services.frontend.source === "local"
+                ? localServiceProcessManager.isRunning(state.services.frontend)
+                : undefined;
+        },
         runner: async () => {
             try {
                 const statusCommand = runnerSupervisor.buildStatusArgs();
@@ -51,56 +71,140 @@ export function createDefaultDependencies() {
             }
             return;
         }
+        const state = stateStore.load();
+        if (service === "api" && state?.services.api.source === "local") {
+            localServiceProcessManager.printLogs(state.services.api);
+            return;
+        }
+        if (service === "frontend" && state?.services.frontend.source === "local") {
+            localServiceProcessManager.printLogs(state.services.frontend);
+            return;
+        }
         await dockerStackManager.logs(service);
     });
     return {
         async up(options = {}) {
             const logLevel = options.logLevel ?? "info";
+            const useHostDockerRuntime = options.useHostDockerRuntime ?? false;
             const githubAppConfig = await ensureGithubAppConfig(githubAppConfigStore, process.stdin, process.stdout);
             const state = stateStore.initialize();
+            process.stdout.write(`${renderer.renderBanner()}\n`);
+            const runnerAlreadyRunning = await isRunnerRunning(commandRunner, runnerSupervisor);
+            const desiredSources = localRepoSourceResolver.resolve(options);
             const versions = versionCatalog.resolve();
             const passwordRecord = createPasswordHash(state.auth.password);
+            const startedLocalServices = [];
+            let runnerStarted = false;
             fs.mkdirSync(root, { recursive: true });
+            fs.mkdirSync(runtimePaths.serviceRuntimePath(), { recursive: true });
             apiEnvFileWriter.write(githubAppConfig);
             bootstrapper.writeSeedSql(root, state, passwordRecord.passwordHash, passwordRecord.passwordSalt);
-            bootstrapper.writeApiConfig(root, state, logLevel);
-            bootstrapper.writeFrontendConfig(root, state);
-            process.stdout.write(`${renderer.renderBanner()}\n`);
-            await dockerStackManager.up(state, { frontendLogLevel: logLevel });
-            process.stdout.write(`${renderer.progress("Initializing the database...")}\n`);
-            process.stdout.write(`${renderer.progress("Waiting for database migrations...")}\n`);
-            await dockerStackManager.applySeedSql(state.auth.username);
-            const configureSdkCommand = runnerSupervisor.buildUseHostAuthArgs();
-            process.stdout.write(`${renderer.progress("Configuring runner authentication...")}\n`);
-            await commandRunner.run(configureSdkCommand.command, configureSdkCommand.args);
-            const startCommand = runnerSupervisor.buildStartArgs({
-                serverUrl: `127.0.0.1:${state.ports.runnerGrpc}`,
-                agentApiUrl: `127.0.0.1:${state.ports.agentCliGrpc}`,
-                logPath: runtimePaths.runnerLogPath(),
-                secret: state.runner.secret,
-                logLevel
+            bootstrapper.writeApiConfig(root, state, logLevel, {
+                databaseHost: desiredSources.api.source === "local" ? "127.0.0.1" : "postgres"
             });
-            process.stdout.write(`${renderer.progress("Starting the runner...")}\n`);
-            await commandRunner.run(startCommand.command, startCommand.args);
-            const apiUrl = `http://127.0.0.1:${state.ports.apiHttp}/graphql`;
-            const uiUrl = `http://127.0.0.1:${state.ports.ui}`;
-            process.stdout.write(`${renderer.success(`API ready: ${apiUrl}`)}\n`);
-            process.stdout.write(`CompanyHelm CLI: ${versions.cliPackage}\n`);
-            process.stdout.write(`Runner package: ${versions.runnerPackage}\n`);
-            process.stdout.write(`API image: ${versions.images.api}\n`);
-            process.stdout.write(`Frontend image: ${versions.images.frontend}\n`);
-            process.stdout.write(`Postgres image: ${versions.images.postgres}\n`);
-            process.stdout.write(`\n${renderer.success("CompanyHelm started successfully.")}\n`);
-            process.stdout.write(`${renderer.successHighlight("UI URL")}\n`);
-            process.stdout.write(`${renderer.clickableUrl(uiUrl)}\n`);
-            process.stdout.write(`${renderer.successHighlight("Login credentials")}\n`);
-            process.stdout.write(`username: ${state.auth.username}\n`);
-            process.stdout.write(`password: ${state.auth.password}\n`);
+            bootstrapper.writeFrontendConfig(root, state);
+            await stopLocalServicesFromState(stateStore.load(), localServiceProcessManager);
+            try {
+                await dockerStackManager.up(state, {
+                    frontendLogLevel: logLevel,
+                    includeApi: desiredSources.api.source === "docker",
+                    includeFrontend: desiredSources.frontend.source === "docker",
+                    exposePostgresPort: desiredSources.api.source === "local"
+                });
+                const apiUrl = `http://127.0.0.1:${state.ports.apiHttp}/graphql`;
+                const uiUrl = `http://127.0.0.1:${state.ports.ui}`;
+                if (desiredSources.api.source === "local") {
+                    process.stdout.write(`${renderer.progress(`Starting companyhelm-api from ${desiredSources.api.repoPath}...`)}\n`);
+                    state.services.api = await apiLocalService.start({
+                        repoPath: desiredSources.api.repoPath,
+                        configPath: runtimePaths.apiConfigPath(),
+                        graphqlUrl: apiUrl,
+                        logPath: runtimePaths.serviceLogPath("api"),
+                        githubAppConfig,
+                        state,
+                        logLevel
+                    });
+                    startedLocalServices.push("api");
+                }
+                else {
+                    state.services.api = { source: "docker" };
+                }
+                process.stdout.write(`${renderer.progress("Initializing the database...")}\n`);
+                process.stdout.write(`${renderer.progress("Waiting for database migrations...")}\n`);
+                await dockerStackManager.applySeedSql(state.auth.username);
+                if (runnerAlreadyRunning) {
+                    process.stdout.write(`${renderer.progress("Runner already running; skipping startup.")}\n`);
+                }
+                else {
+                    const configureSdkCommand = runnerSupervisor.buildUseHostAuthArgs();
+                    process.stdout.write(`${renderer.progress("Configuring runner authentication...")}\n`);
+                    await commandRunner.run(configureSdkCommand.command, configureSdkCommand.args);
+                    const startCommand = runnerSupervisor.buildStartArgs({
+                        serverUrl: `127.0.0.1:${state.ports.runnerGrpc}`,
+                        agentApiUrl: `127.0.0.1:${state.ports.agentCliGrpc}`,
+                        logPath: runtimePaths.runnerLogPath(),
+                        secret: state.runner.secret,
+                        logLevel,
+                        useHostDockerRuntime
+                    });
+                    process.stdout.write(`${renderer.progress("Starting the runner...")}\n`);
+                    await commandRunner.run(startCommand.command, startCommand.args);
+                    runnerStarted = true;
+                }
+                if (desiredSources.frontend.source === "local") {
+                    process.stdout.write(`${renderer.progress(`Starting companyhelm-web from ${desiredSources.frontend.repoPath}...`)}\n`);
+                    state.services.frontend = await webLocalService.start({
+                        repoPath: desiredSources.frontend.repoPath,
+                        configPath: runtimePaths.frontendConfigPath(),
+                        url: uiUrl,
+                        uiPort: state.ports.ui,
+                        logPath: runtimePaths.serviceLogPath("frontend"),
+                        logLevel
+                    });
+                    startedLocalServices.push("frontend");
+                }
+                else {
+                    state.services.frontend = { source: "docker" };
+                }
+                stateStore.persist(state);
+                process.stdout.write(`${renderer.success(`API ready: ${apiUrl}`)}\n`);
+                process.stdout.write(`CompanyHelm CLI: ${versions.cliPackage}\n`);
+                process.stdout.write(`Runner package: ${versions.runnerPackage}\n`);
+                process.stdout.write(desiredSources.api.source === "local"
+                    ? `API repo: ${desiredSources.api.repoPath}\n`
+                    : `API image: ${versions.images.api}\n`);
+                process.stdout.write(desiredSources.frontend.source === "local"
+                    ? `companyhelm-web repo: ${desiredSources.frontend.repoPath}\n`
+                    : `companyhelm-web image: ${versions.images.frontend}\n`);
+                process.stdout.write(`Postgres image: ${versions.images.postgres}\n`);
+                process.stdout.write(`\n${renderer.success("CompanyHelm started successfully.")}\n`);
+                process.stdout.write(`${renderer.successHighlight("UI URL")}\n`);
+                process.stdout.write(`${renderer.clickableUrl(uiUrl)}\n`);
+                process.stdout.write(`${renderer.successHighlight("Login credentials")}\n`);
+                process.stdout.write(`username: ${state.auth.username}\n`);
+                process.stdout.write(`password: ${state.auth.password}\n`);
+            }
+            catch (error) {
+                if (runnerStarted) {
+                    const stopCommand = runnerSupervisor.buildStopArgs();
+                    try {
+                        await commandRunner.run(stopCommand.command, stopCommand.args);
+                    }
+                    catch {
+                        // Ignore runner stop failures during cleanup.
+                    }
+                }
+                for (const service of startedLocalServices.reverse()) {
+                    const runtime = service === "api" ? state.services.api : state.services.frontend;
+                    if (runtime.source === "local") {
+                        await localServiceProcessManager.stop(runtime);
+                    }
+                }
+                await dockerStackManager.down();
+                throw error;
+            }
         },
         async down() {
-            if (!stateStore.load()) {
-                return;
-            }
             const stopCommand = runnerSupervisor.buildStopArgs();
             try {
                 await commandRunner.run(stopCommand.command, stopCommand.args);
@@ -108,6 +212,11 @@ export function createDefaultDependencies() {
             catch {
                 // Ignore runner stop failures during teardown so container cleanup still happens.
             }
+            const state = stateStore.load();
+            if (!state) {
+                return;
+            }
+            await stopLocalServicesFromState(state, localServiceProcessManager);
             await dockerStackManager.down();
         },
         async status() {
@@ -125,7 +234,8 @@ export function createDefaultDependencies() {
             return logsService.stream(service);
         },
         async reset(options = {}) {
-            if (stateStore.load()) {
+            const state = stateStore.load();
+            if (state) {
                 const stopCommand = runnerSupervisor.buildStopArgs();
                 try {
                     await commandRunner.run(stopCommand.command, stopCommand.args);
@@ -133,6 +243,7 @@ export function createDefaultDependencies() {
                 catch {
                     // Ignore runner stop failures during teardown so docker cleanup still runs.
                 }
+                await stopLocalServicesFromState(state, localServiceProcessManager);
             }
             await dockerStackManager.down({ removeVolumes: true });
             fs.rmSync(projectPaths.apiEnvPath(), { force: true });
@@ -143,3 +254,24 @@ export function createDefaultDependencies() {
         }
     };
 }
+async function stopLocalServicesFromState(state, processManager) {
+    if (!state) {
+        return;
+    }
+    if (state.services.api.source === "local") {
+        await processManager.stop(state.services.api);
+    }
+    if (state.services.frontend.source === "local") {
+        await processManager.stop(state.services.frontend);
+    }
+}
+async function isRunnerRunning(commandRunner, runnerSupervisor) {
+    try {
+        const statusCommand = runnerSupervisor.buildStatusArgs();
+        const output = await commandRunner.capture(statusCommand.command, statusCommand.args);
+        return output.includes("Daemon: running");
+    }
+    catch (error) {
+        return false;
+    }
+}

package/dist/commands/up.js

@@ -3,12 +3,37 @@ export function registerUpCommand(program, dependencies) {
     program
         .command("up")
         .description("Start or reconcile the local deployment.")
-        .option("--log-level <level>", "Set log level for api, frontend, and runner.", "info")
+        .option("--log-level <level>", "Set log level for api, companyhelm-web, and runner.", "info")
+        .option("--use-host-docker-runtime", "Run thread containers against the host Docker runtime instead of DinD sidecars.")
+        .option("--api-repo-path [path]", "Start the API from a local repo path. Defaults to ../companyhelm-api when provided without a value.")
+        .option("--web-repo-path [path]", "Start companyhelm-web from a local repo path. Defaults to ../companyhelm-web when provided without a value.")
         .action(async (options) => {
         const logLevel = String(options.logLevel || "").trim().toLowerCase();
         if (!LOG_LEVELS.has(logLevel)) {
             throw new Error(`Unsupported log level "${options.logLevel}". Expected one of: debug, info, warn, error.`);
         }
-        await dependencies.up({ logLevel: logLevel });
+        const upOptions = {
+            logLevel: logLevel,
+            useHostDockerRuntime: Boolean(options.useHostDockerRuntime)
+        };
+        const apiRepoPath = normalizeLocalRepoOption(options.apiRepoPath);
+        const webRepoPath = normalizeLocalRepoOption(options.webRepoPath);
+        if (apiRepoPath !== undefined) {
+            upOptions.apiRepoPath = apiRepoPath;
+        }
+        if (webRepoPath !== undefined) {
+            upOptions.webRepoPath = webRepoPath;
+        }
+        await dependencies.up(upOptions);
     });
 }
+function normalizeLocalRepoOption(option) {
+    if (option === true) {
+        return true;
+    }
+    if (typeof option === "string") {
+        const trimmed = option.trim();
+        return trimmed.length > 0 ? trimmed : true;
+    }
+    return undefined;
+}

package/dist/core/bootstrap/DeploymentBootstrapper.d.ts

@@ -3,7 +3,12 @@ import type { RuntimeState } from "../runtime/RuntimeState.js";
 export declare class DeploymentBootstrapper {
     private readonly renderer;
     writeSeedSql(root: string, state: RuntimeState, passwordHash: string, passwordSalt: string): string;
-    writeApiConfig(root: string, state: RuntimeState, logLevel?: LogLevel): string;
+    writeApiConfig(root: string, state: RuntimeState, logLevel?: LogLevel, options?: {
+        databaseHost?: string;
+        appPort?: number;
+        runnerGrpcPort?: number;
+        agentGrpcPort?: number;
+    }): string;
     writeFrontendConfig(root: string, state: RuntimeState): string;
     private indentBlock;
 }

package/dist/core/bootstrap/DeploymentBootstrapper.js

@@ -18,28 +18,32 @@ export class DeploymentBootstrapper {
         fs.writeFileSync(outputPath, sql, "utf8");
         return outputPath;
     }
-    writeApiConfig(root, state, logLevel = "info") {
+    writeApiConfig(root, state, logLevel = "info", options = {}) {
         const runtimePaths = new RuntimePaths(root);
         const outputPath = runtimePaths.apiConfigPath();
+        const appPort = options.appPort ?? state.ports.apiHttp;
+        const runnerGrpcPort = options.runnerGrpcPort ?? state.ports.runnerGrpc;
+        const agentGrpcPort = options.agentGrpcPort ?? state.ports.agentCliGrpc;
+        const databaseHost = options.databaseHost ?? "postgres";
         const yaml = [
             "app:",
             '  host: "0.0.0.0"',
-            '  port: 4000',
+            `  port: ${appPort}`,
             '  graphqlEndpoint: "/graphql"',
             "  graphiql: true",
             "  grpc:",
             '    host: "0.0.0.0"',
-            "    port: 50051",
+            `    port: ${runnerGrpcPort}`,
             "    heartbeat:",
             "      intervalMs: 20000",
             "      jitterMs: 10000",
             "agent:",
             "  grpc:",
             '    host: "0.0.0.0"',
-            "    port: 50052",
+            `    port: ${agentGrpcPort}`,
             "database:",
             '  name: "companyhelm"',
-            '  host: "postgres"',
+            `  host: "${databaseHost}"`,
             "  port: 5432",
             "  roles:",
             "    app_runtime:",

package/dist/core/docker/ComposeTemplateRenderer.d.ts

@@ -13,6 +13,9 @@ export interface ComposePaths {
 }
 export interface ComposeRenderOptions {
     frontendLogLevel?: LogLevel;
+    includeApi?: boolean;
+    includeFrontend?: boolean;
+    exposePostgresPort?: boolean;
 }
 export declare class ComposeTemplateRenderer {
     render(ports: ComposePorts, paths: ComposePaths, options?: ComposeRenderOptions): string;

package/dist/core/docker/ComposeTemplateRenderer.js

@@ -10,11 +10,35 @@ export class ComposeTemplateRenderer {
         const template = fs.readFileSync(templatePath, "utf8");
         const images = new ImageCatalog().resolve();
         const frontendLogLevel = options.frontendLogLevel ?? "info";
-        const frontendBlock = [
+        const includeApi = options.includeApi ?? true;
+        const includeFrontend = options.includeFrontend ?? true;
+        const postgresPortsBlock = options.exposePostgresPort ? [
+            "    ports:",
+            '      - "5432:5432"'
+        ].join("\n") : "";
+        const apiBlock = includeApi ? [
+            "  api:",
+            `    image: ${images.api}`,
+            "    platform: linux/amd64",
+            "    depends_on:",
+            "      - postgres",
+            "    env_file:",
+            `      - "${paths.apiEnvPath}"`,
+            "    environment:",
+            "      COMPANYHELM_CONFIG_PATH: /run/companyhelm/config.yaml",
+            "    ports:",
+            `      - "${ports.apiHttpPort}:4000"`,
+            `      - "${ports.runnerGrpcPort}:${ports.runnerGrpcPort}"`,
+            `      - "${ports.agentCliGrpcPort}:${ports.agentCliGrpcPort}"`,
+            "    volumes:",
+            `      - "${paths.apiConfigPath}:/run/companyhelm/config.yaml:ro"`,
+            "    networks:",
+            "      - companyhelm"
+        ].join("\n") : "";
+        const frontendBlock = includeFrontend ? [
             "  frontend:",
             `    image: ${images.frontend}`,
-            "    depends_on:",
-            "      - api",
+            ...(includeApi ? ["    depends_on:", "      - api"] : []),
             "    environment:",
             "      COMPANYHELM_CONFIG_PATH: /run/companyhelm/config.yaml",
             `      COMPANYHELM_LOG_LEVEL: "${frontendLogLevel}"`,
@@ -26,10 +50,11 @@ export class ComposeTemplateRenderer {
             `      - "${paths.frontendConfigPath}:/run/companyhelm/config.yaml:ro"`,
             "    networks:",
             "      - companyhelm"
-        ].join("\n");
+        ].join("\n") : "";
         return template
-            .replaceAll("{{API_IMAGE}}", images.api)
             .replaceAll("{{POSTGRES_IMAGE}}", images.postgres)
+            .replace("{{POSTGRES_PORTS_BLOCK}}", postgresPortsBlock)
+            .replace("{{API_SERVICE_BLOCK}}", apiBlock)
             .replaceAll("{{API_CONFIG_PATH}}", paths.apiConfigPath)
             .replaceAll("{{API_ENV_PATH}}", paths.apiEnvPath)
             .replaceAll("{{SEED_FILE_PATH}}", paths.seedFilePath)

package/dist/core/docker/DockerStackManager.d.ts

@@ -4,6 +4,9 @@ import type { RuntimeState } from "../runtime/RuntimeState.js";
 import { ComposeTemplateRenderer } from "./ComposeTemplateRenderer.js";
 export interface DockerStackUpOptions {
     frontendLogLevel?: LogLevel;
+    includeApi?: boolean;
+    includeFrontend?: boolean;
+    exposePostgresPort?: boolean;
 }
 export interface DockerStackDownOptions {
     removeVolumes?: boolean;

package/dist/core/docker/DockerStackManager.js

@@ -27,7 +27,10 @@ export class DockerStackManager {
             frontendConfigPath: this.runtimePaths.frontendConfigPath(),
             seedFilePath: this.runtimePaths.seedFilePath()
         }, {
-            frontendLogLevel: options.frontendLogLevel
+            frontendLogLevel: options.frontendLogLevel,
+            includeApi: options.includeApi,
+            includeFrontend: options.includeFrontend,
+            exposePostgresPort: options.exposePostgresPort
         }), "utf8");
         await this.commandRunner.run("docker", [
             "compose",

package/dist/core/local/ApiLocalService.d.ts

@@ -0,0 +1,22 @@
+import { LocalServiceProcessManager } from "./LocalServiceProcessManager.js";
+import { CommandRunner } from "../process/CommandRunner.js";
+import type { LogLevel } from "../../commands/dependencies.js";
+import type { GithubAppConfig } from "../config/GithubAppConfig.js";
+import type { LocalManagedServiceRuntime, RuntimeState } from "../runtime/RuntimeState.js";
+export interface ApiLocalServiceStartInput {
+    repoPath: string;
+    configPath: string;
+    graphqlUrl: string;
+    logPath: string;
+    githubAppConfig: GithubAppConfig;
+    state: RuntimeState;
+    logLevel: LogLevel;
+}
+export declare class ApiLocalService {
+    private readonly processManager;
+    private readonly commandRunner;
+    constructor(processManager?: LocalServiceProcessManager, commandRunner?: CommandRunner);
+    start(input: ApiLocalServiceStartInput): Promise<LocalManagedServiceRuntime>;
+    private ensureNodeModules;
+    private waitForReadiness;
+}

package/dist/core/local/ApiLocalService.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import { LocalServiceProcessManager } from "./LocalServiceProcessManager.js";
+import { CommandRunner } from "../process/CommandRunner.js";
+export class ApiLocalService {
+    processManager;
+    commandRunner;
+    constructor(processManager = new LocalServiceProcessManager(), commandRunner = new CommandRunner()) {
+        this.processManager = processManager;
+        this.commandRunner = commandRunner;
+    }
+    async start(input) {
+        await this.ensureNodeModules(input.repoPath);
+        const runtime = this.processManager.start({
+            serviceName: "api",
+            repoPath: input.repoPath,
+            command: process.execPath,
+            args: [
+                "./node_modules/tsx/dist/cli.mjs",
+                "watch",
+                "src/server.ts",
+                "--config-path",
+                input.configPath
+            ],
+            logPath: input.logPath,
+            env: {
+                APP_ENV: "local",
+                GITHUB_APP_CLIENT_ID: input.githubAppConfig.appClientId,
+                GITHUB_APP_URL: input.githubAppConfig.appUrl,
+                GITHUB_APP_PRIVATE_KEY_PEM: input.githubAppConfig.appPrivateKeyPem,
+                COMPANYHELM_JWT_PRIVATE_KEY_PEM: input.state.auth.jwtPrivateKeyPem,
+                COMPANYHELM_JWT_PUBLIC_KEY_PEM: input.state.auth.jwtPublicKeyPem,
+                COMPANYHELM_LOG_LEVEL: input.logLevel
+            }
+        });
+        await this.waitForReadiness(input.graphqlUrl, runtime, "API");
+        return runtime;
+    }
+    async ensureNodeModules(repoPath) {
+        if (fs.existsSync(`${repoPath}/node_modules`)) {
+            return;
+        }
+        await this.commandRunner.run("npm", ["install"], repoPath);
+    }
+    async waitForReadiness(url, runtime, serviceName) {
+        const deadline = Date.now() + 60_000;
+        while (Date.now() < deadline) {
+            if (!this.processManager.isRunning(runtime)) {
+                throw new Error(`${serviceName} exited before becoming ready.`);
+            }
+            try {
+                const response = await fetch(url, { method: "OPTIONS" });
+                if (response.ok) {
+                    return;
+                }
+            }
+            catch {
+                // Retry until the deadline.
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, 1000);
+            });
+        }
+        throw new Error(`${serviceName} did not become ready: ${url}`);
+    }
+}

package/dist/core/local/LocalRepoSourceResolver.d.ts

@@ -0,0 +1,24 @@
+import type { LocalRepoOptionValue } from "../../commands/dependencies.js";
+export interface DockerServiceSource {
+    source: "docker";
+}
+export interface LocalRepoServiceSource {
+    source: "local";
+    repoPath: string;
+}
+export type ResolvedServiceSource = DockerServiceSource | LocalRepoServiceSource;
+export interface ResolvedServiceSources {
+    api: ResolvedServiceSource;
+    frontend: ResolvedServiceSource;
+}
+export interface LocalRepoSourceOptions {
+    apiRepoPath?: LocalRepoOptionValue;
+    webRepoPath?: LocalRepoOptionValue;
+}
+export declare class LocalRepoSourceResolver {
+    private readonly companyhelmRoot;
+    constructor(companyhelmRoot?: string);
+    resolve(options: LocalRepoSourceOptions): ResolvedServiceSources;
+    private resolveService;
+    private assertRepoPathExists;
+}

package/dist/core/local/LocalRepoSourceResolver.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+export class LocalRepoSourceResolver {
+    companyhelmRoot;
+    constructor(companyhelmRoot = process.cwd()) {
+        this.companyhelmRoot = companyhelmRoot;
+    }
+    resolve(options) {
+        return {
+            api: this.resolveService("api", options.apiRepoPath, "../companyhelm-api"),
+            frontend: this.resolveService("frontend", options.webRepoPath, "../companyhelm-web")
+        };
+    }
+    resolveService(service, option, defaultRelativePath) {
+        if (option === undefined) {
+            return {
+                source: "docker"
+            };
+        }
+        const repoPath = path.resolve(this.companyhelmRoot, option === true ? defaultRelativePath : option);
+        this.assertRepoPathExists(service, repoPath);
+        return {
+            source: "local",
+            repoPath
+        };
+    }
+    assertRepoPathExists(service, repoPath) {
+        if (fs.existsSync(repoPath) && fs.statSync(repoPath).isDirectory()) {
+            return;
+        }
+        throw new Error(`Local ${service} repo path does not exist: ${repoPath}`);
+    }
+}

package/dist/core/local/LocalServiceProcessManager.d.ts

@@ -0,0 +1,18 @@
+import type { LocalManagedServiceRuntime } from "../runtime/RuntimeState.js";
+export interface LocalProcessStartInput {
+    serviceName: string;
+    repoPath: string;
+    command: string;
+    args: string[];
+    logPath: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class LocalServiceProcessManager {
+    start(input: LocalProcessStartInput): LocalManagedServiceRuntime;
+    isRunning(runtime: LocalManagedServiceRuntime): boolean;
+    stop(runtime: LocalManagedServiceRuntime): Promise<void>;
+    printLogs(runtime: LocalManagedServiceRuntime): void;
+    private kill;
+    private isPidRunning;
+    private waitForExit;
+}

package/dist/core/local/LocalServiceProcessManager.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
+export class LocalServiceProcessManager {
+    start(input) {
+        fs.mkdirSync(path.dirname(input.logPath), { recursive: true });
+        fs.writeFileSync(input.logPath, `\n[companyhelm] starting ${input.serviceName}: ${input.command} ${input.args.join(" ")}\n`, { flag: "a" });
+        const logFd = fs.openSync(input.logPath, "a");
+        const child = spawn(input.command, input.args, {
+            cwd: input.repoPath,
+            env: {
+                ...process.env,
+                ...input.env
+            },
+            stdio: ["ignore", logFd, logFd],
+            detached: true
+        });
+        child.unref();
+        fs.closeSync(logFd);
+        return {
+            source: "local",
+            repoPath: input.repoPath,
+            logPath: input.logPath,
+            pid: child.pid ?? 0
+        };
+    }
+    isRunning(runtime) {
+        return runtime.pid > 0 && this.isPidRunning(runtime.pid);
+    }
+    async stop(runtime) {
+        if (!this.isRunning(runtime)) {
+            return;
+        }
+        this.kill(runtime.pid, "SIGTERM");
+        const exitedAfterSigTerm = await this.waitForExit(runtime.pid, 5000);
+        if (!exitedAfterSigTerm) {
+            this.kill(runtime.pid, "SIGKILL");
+            await this.waitForExit(runtime.pid, 2000);
+        }
+    }
+    printLogs(runtime) {
+        if (!fs.existsSync(runtime.logPath)) {
+            return;
+        }
+        process.stdout.write(fs.readFileSync(runtime.logPath, "utf8"));
+    }
+    kill(pid, signal) {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // Fall through to direct child kill.
+        }
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Ignore stale pid files.
+        }
+    }
+    isPidRunning(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async waitForExit(pid, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (!this.isPidRunning(pid)) {
+                return true;
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, 100);
+            });
+        }
+        return !this.isPidRunning(pid);
+    }
+}

package/dist/core/local/WebLocalService.d.ts

@@ -0,0 +1,23 @@
+import { LocalServiceProcessManager } from "./LocalServiceProcessManager.js";
+import { CommandRunner } from "../process/CommandRunner.js";
+import type { LogLevel } from "../../commands/dependencies.js";
+import type { LocalManagedServiceRuntime } from "../runtime/RuntimeState.js";
+export interface WebLocalServiceStartInput {
+    repoPath: string;
+    configPath: string;
+    url: string;
+    uiPort: number;
+    logPath: string;
+    logLevel: LogLevel;
+}
+export declare class WebLocalService {
+    private readonly processManager;
+    private readonly commandRunner;
+    private static readonly SERVICE_NAME;
+    constructor(processManager?: LocalServiceProcessManager, commandRunner?: CommandRunner);
+    start(input: WebLocalServiceStartInput): Promise<LocalManagedServiceRuntime>;
+    private ensureNodeModules;
+    private waitForReadiness;
+    private assertUiPortAvailable;
+    private buildStartupFailureMessage;
+}

package/dist/core/local/WebLocalService.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import net from "node:net";
+import { LocalServiceProcessManager } from "./LocalServiceProcessManager.js";
+import { CommandRunner } from "../process/CommandRunner.js";
+export class WebLocalService {
+    processManager;
+    commandRunner;
+    static SERVICE_NAME = "companyhelm-web";
+    constructor(processManager = new LocalServiceProcessManager(), commandRunner = new CommandRunner()) {
+        this.processManager = processManager;
+        this.commandRunner = commandRunner;
+    }
+    async start(input) {
+        await this.assertUiPortAvailable(input.uiPort);
+        await this.ensureNodeModules(input.repoPath);
+        await this.commandRunner.run("npm", ["run", "config:generate", "--", "--config-path", input.configPath], input.repoPath, {
+            APP_ENV: "local"
+        });
+        const runtime = this.processManager.start({
+            serviceName: WebLocalService.SERVICE_NAME,
+            repoPath: input.repoPath,
+            command: process.execPath,
+            args: [
+                "./node_modules/vite/bin/vite.js",
+                "dev",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                String(input.uiPort)
+            ],
+            logPath: input.logPath,
+            env: {
+                APP_ENV: "local",
+                COMPANYHELM_LOG_LEVEL: input.logLevel,
+                npm_config_loglevel: input.logLevel
+            }
+        });
+        await this.waitForReadiness(input.url, runtime);
+        return runtime;
+    }
+    async ensureNodeModules(repoPath) {
+        if (fs.existsSync(`${repoPath}/node_modules`)) {
+            return;
+        }
+        await this.commandRunner.run("npm", ["install"], repoPath);
+    }
+    async waitForReadiness(url, runtime) {
+        const deadline = Date.now() + 60_000;
+        while (Date.now() < deadline) {
+            if (!this.processManager.isRunning(runtime)) {
+                throw new Error(this.buildStartupFailureMessage(runtime, `${WebLocalService.SERVICE_NAME} exited before becoming ready.`));
+            }
+            try {
+                const response = await fetch(url);
+                if (response.ok) {
+                    return;
+                }
+            }
+            catch {
+                // Retry until the deadline.
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, 1000);
+            });
+        }
+        throw new Error(`companyhelm-web did not become ready: ${url}`);
+    }
+    async assertUiPortAvailable(port) {
+        await new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.once("error", (error) => {
+                if (error.code === "EADDRINUSE") {
+                    reject(new Error(`companyhelm-web cannot start because port ${port} is already in use.`));
+                    return;
+                }
+                reject(new Error(`companyhelm-web cannot verify port ${port}: ${error.message}`));
+            });
+            server.once("listening", () => {
+                server.close((closeError) => {
+                    if (closeError) {
+                        reject(closeError);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+            server.listen(port, "0.0.0.0");
+        });
+    }
+    buildStartupFailureMessage(runtime, summary) {
+        if (!fs.existsSync(runtime.logPath)) {
+            return summary;
+        }
+        const startupLog = fs.readFileSync(runtime.logPath, "utf8").trim();
+        if (!startupLog) {
+            return summary;
+        }
+        const tail = startupLog.split(/\r?\n/).slice(-20).join("\n");
+        return `${summary}\nStartup log:\n${tail}`;
+    }
+}

package/dist/core/process/CommandRunner.d.ts

@@ -1,4 +1,4 @@
 export declare class CommandRunner {
-    run(command: string, args: string[], cwd?: string): Promise<void>;
-    capture(command: string, args: string[], cwd?: string): Promise<string>;
+    run(command: string, args: string[], cwd?: string, env?: NodeJS.ProcessEnv): Promise<void>;
+    capture(command: string, args: string[], cwd?: string, env?: NodeJS.ProcessEnv): Promise<string>;
 }

package/dist/core/process/CommandRunner.js

@@ -1,9 +1,13 @@
 import { spawn } from "node:child_process";
 export class CommandRunner {
-    run(command, args, cwd) {
+    run(command, args, cwd, env) {
         return new Promise((resolve, reject) => {
             const child = spawn(command, args, {
                 cwd,
+                env: {
+                    ...process.env,
+                    ...env
+                },
                 stdio: "inherit"
             });
             child.on("error", reject);
@@ -16,10 +20,14 @@ export class CommandRunner {
             });
         });
     }
-    capture(command, args, cwd) {
+    capture(command, args, cwd, env) {
         return new Promise((resolve, reject) => {
             const child = spawn(command, args, {
                 cwd,
+                env: {
+                    ...process.env,
+                    ...env
+                },
                 stdio: ["ignore", "pipe", "pipe"]
             });
             let stdout = "";

package/dist/core/runner/RunnerSupervisor.d.ts

@@ -5,6 +5,7 @@ export interface RunnerStartInput {
     logPath: string;
     secret: string;
     logLevel?: LogLevel;
+    useHostDockerRuntime?: boolean;
 }
 export interface RunnerStartCommand {
     command: string;
@@ -18,4 +19,5 @@ export declare class RunnerSupervisor {
     buildStopArgs(): RunnerStartCommand;
     buildStatusArgs(): RunnerStartCommand;
     private resolveRunnerCliPath;
+    private resolveHostDockerPath;
 }

package/dist/core/runner/RunnerSupervisor.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
+const DEFAULT_HOST_DOCKER_PATH = "unix:///var/run/docker.sock";
 export class RunnerSupervisor {
     configPath;
     constructor(configPath) {
@@ -16,6 +17,9 @@ 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()]
+            : [];
         return {
             command: process.execPath,
             args: [
@@ -30,6 +34,7 @@ export class RunnerSupervisor {
                 input.agentApiUrl,
                 "--log-path",
                 input.logPath,
+                ...hostDockerArgs,
                 "--secret",
                 input.secret,
                 "--log-level",
@@ -58,4 +63,11 @@ export class RunnerSupervisor {
         const packageJsonPath = require.resolve("@companyhelm/runner/package.json");
         return path.resolve(path.dirname(packageJsonPath), "dist/cli.js");
     }
+    resolveHostDockerPath() {
+        const dockerHost = String(process.env.DOCKER_HOST || "").trim();
+        if (dockerHost) {
+            return dockerHost;
+        }
+        return DEFAULT_HOST_DOCKER_PATH;
+    }
 }

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

@@ -9,4 +9,6 @@ export declare class RuntimePaths {
     runnerConfigPath(): string;
     runnerStateDbPath(): string;
     runnerLogPath(): string;
+    serviceRuntimePath(): string;
+    serviceLogPath(service: "api" | "frontend"): string;
 }

package/dist/core/runtime/RuntimePaths.js

@@ -5,7 +5,7 @@ export class RuntimePaths {
         this.root = root;
     }
     stateFilePath() {
-        return path.join(this.root, "state.json");
+        return path.join(this.root, "state.yaml");
     }
     composeFilePath() {
         return path.join(this.root, "docker-compose.yaml");
@@ -28,4 +28,10 @@ export class RuntimePaths {
     runnerLogPath() {
         return path.join(this.runnerConfigPath(), "daemon.log");
     }
+    serviceRuntimePath() {
+        return path.join(this.root, "services");
+    }
+    serviceLogPath(service) {
+        return path.join(this.serviceRuntimePath(), `${service}.log`);
+    }
 }

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

@@ -4,6 +4,16 @@ export interface RuntimePorts {
     runnerGrpc: number;
     agentCliGrpc: number;
 }
+export interface DockerManagedServiceRuntime {
+    source: "docker";
+}
+export interface LocalManagedServiceRuntime {
+    source: "local";
+    repoPath: string;
+    logPath: string;
+    pid: number;
+}
+export type ManagedServiceRuntime = DockerManagedServiceRuntime | LocalManagedServiceRuntime;
 export interface RuntimeState {
     version: 1;
     company: {
@@ -21,4 +31,8 @@ export interface RuntimeState {
         secret: string;
     };
     ports: RuntimePorts;
+    services: {
+        api: ManagedServiceRuntime;
+        frontend: ManagedServiceRuntime;
+    };
 }

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

@@ -6,5 +6,6 @@ export declare class RuntimeStateStore {
     constructor(root: string);
     initialize(): RuntimeState;
     load(): RuntimeState | null;
+    persist(state: RuntimeState): void;
     private save;
 }

package/dist/core/runtime/RuntimeStateStore.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import YAML from "yaml";
 import { PortAllocator } from "./PortAllocator.js";
 import { RuntimePaths } from "./RuntimePaths.js";
 import { createPemKeyPair, randomCompanyId, randomSecret } from "./Secrets.js";
@@ -33,7 +34,15 @@ export class RuntimeStateStore {
                 name: "local-runner",
                 secret: randomSecret()
             },
-            ports: new PortAllocator().allocate()
+            ports: new PortAllocator().allocate(),
+            services: {
+                api: {
+                    source: "docker"
+                },
+                frontend: {
+                    source: "docker"
+                }
+            }
         };
         this.save(state);
         return state;
@@ -42,15 +51,29 @@ export class RuntimeStateStore {
         if (!fs.existsSync(this.runtimePaths.stateFilePath())) {
             return null;
         }
-        const state = JSON.parse(fs.readFileSync(this.runtimePaths.stateFilePath(), "utf8"));
+        const state = YAML.parse(fs.readFileSync(this.runtimePaths.stateFilePath(), "utf8"));
         if (state.auth.username !== RuntimeStateStore.DEFAULT_USERNAME && state.auth.username === "admin") {
             state.auth.username = RuntimeStateStore.DEFAULT_USERNAME;
             this.save(state);
         }
+        if (!state.services) {
+            state.services = {
+                api: {
+                    source: "docker"
+                },
+                frontend: {
+                    source: "docker"
+                }
+            };
+            this.save(state);
+        }
         return state;
     }
+    persist(state) {
+        this.save(state);
+    }
     save(state) {
-        fs.writeFileSync(this.runtimePaths.stateFilePath(), `${JSON.stringify(state, null, 2)}\n`, {
+        fs.writeFileSync(this.runtimePaths.stateFilePath(), YAML.stringify(state), {
             encoding: "utf8",
             mode: 0o600
         });

package/dist/core/status/StatusService.d.ts

@@ -6,11 +6,14 @@ export interface StatusSnapshot {
     runner: ManagedServiceStatus;
 }
 export interface StatusOverrides {
-    runner?: () => Promise<boolean> | boolean;
+    api?: () => Promise<boolean | undefined> | boolean | undefined;
+    frontend?: () => Promise<boolean | undefined> | boolean | undefined;
+    runner?: () => Promise<boolean | undefined> | boolean | undefined;
 }
 export declare class StatusService {
     private readonly listRunningServices;
     private readonly overrides;
     constructor(listRunningServices: () => Promise<string>, overrides?: StatusOverrides);
     read(): Promise<StatusSnapshot>;
+    private resolveServiceRunning;
 }

package/dist/core/status/StatusService.js

@@ -10,12 +10,21 @@ export class StatusService {
             .split("\n")
             .map((service) => service.trim())
             .filter(Boolean));
-        const runnerRunning = this.overrides.runner ? await this.overrides.runner() : running.has("runner");
+        const apiRunning = await this.resolveServiceRunning("api", this.overrides.api, running);
+        const frontendRunning = await this.resolveServiceRunning("frontend", this.overrides.frontend, running);
+        const runnerRunning = await this.resolveServiceRunning("runner", this.overrides.runner, running);
         return {
             postgres: running.has("postgres") ? "running" : "stopped",
-            api: running.has("api") ? "running" : "stopped",
-            frontend: running.has("frontend") ? "running" : "stopped",
+            api: apiRunning ? "running" : "stopped",
+            frontend: frontendRunning ? "running" : "stopped",
             runner: runnerRunning ? "running" : "stopped"
         };
     }
+    async resolveServiceRunning(service, override, running) {
+        if (!override) {
+            return running.has(service);
+        }
+        const result = await override();
+        return typeof result === "boolean" ? result : running.has(service);
+    }
 }

package/dist/core/ui/TerminalRenderer.js

@@ -36,13 +36,13 @@ export class TerminalRenderer {
         const lines = ["Status"];
         lines.push(this.renderServiceLine("Postgres", report.services.postgres));
         lines.push(this.renderServiceLine("API", report.services.api, report.apiUrl));
-        lines.push(this.renderServiceLine("Frontend", report.services.frontend, report.uiUrl));
+        lines.push(this.renderServiceLine("companyhelm-web", report.services.frontend, report.uiUrl));
         lines.push(this.renderServiceLine("Runner", report.services.runner));
         if (report.versions) {
             lines.push(`CompanyHelm CLI: ${report.versions.cliPackage}`);
             lines.push(`Runner package: ${report.versions.runnerPackage}`);
             lines.push(`API image: ${report.versions.images.api}`);
-            lines.push(`Frontend image: ${report.versions.images.frontend}`);
+            lines.push(`companyhelm-web image: ${report.versions.images.frontend}`);
             lines.push(`Postgres image: ${report.versions.images.postgres}`);
         }
         if (report.username) {

package/dist/templates/docker-compose.yaml.tpl

@@ -5,29 +5,14 @@ services:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
       POSTGRES_DB: companyhelm
+{{POSTGRES_PORTS_BLOCK}}
     volumes:
       - companyhelm_postgres_data:/var/lib/postgresql/data
       - "{{SEED_FILE_PATH}}:/run/companyhelm/seed.sql:ro"
     networks:
       - companyhelm
 
-  api:
-    image: {{API_IMAGE}}
-    platform: linux/amd64
-    depends_on:
-      - postgres
-    env_file:
-      - "{{API_ENV_PATH}}"
-    environment:
-      COMPANYHELM_CONFIG_PATH: /run/companyhelm/config.yaml
-    ports:
-      - "{{API_HTTP_PORT}}:4000"
-      - "{{RUNNER_GRPC_PORT}}:{{RUNNER_GRPC_PORT}}"
-      - "{{AGENT_CLI_GRPC_PORT}}:{{AGENT_CLI_GRPC_PORT}}"
-    volumes:
-      - "{{API_CONFIG_PATH}}:/run/companyhelm/config.yaml:ro"
-    networks:
-      - companyhelm
+{{API_SERVICE_BLOCK}}
 
 {{FRONTEND_SERVICE_BLOCK}}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companyhelm/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Bootstrap and manage a local CompanyHelm deployment.",
   "license": "MIT",
   "private": false,

package/src/templates/docker-compose.yaml.tpl

@@ -5,29 +5,14 @@ services:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
       POSTGRES_DB: companyhelm
+{{POSTGRES_PORTS_BLOCK}}
     volumes:
       - companyhelm_postgres_data:/var/lib/postgresql/data
       - "{{SEED_FILE_PATH}}:/run/companyhelm/seed.sql:ro"
     networks:
       - companyhelm
 
-  api:
-    image: {{API_IMAGE}}
-    platform: linux/amd64
-    depends_on:
-      - postgres
-    env_file:
-      - "{{API_ENV_PATH}}"
-    environment:
-      COMPANYHELM_CONFIG_PATH: /run/companyhelm/config.yaml
-    ports:
-      - "{{API_HTTP_PORT}}:4000"
-      - "{{RUNNER_GRPC_PORT}}:{{RUNNER_GRPC_PORT}}"
-      - "{{AGENT_CLI_GRPC_PORT}}:{{AGENT_CLI_GRPC_PORT}}"
-    volumes:
-      - "{{API_CONFIG_PATH}}:/run/companyhelm/config.yaml:ro"
-    networks:
-      - companyhelm
+{{API_SERVICE_BLOCK}}
 
 {{FRONTEND_SERVICE_BLOCK}}