@companyhelm/cli 0.1.2 → 0.1.5

package/dist/commands/set-image-version.js

@@ -0,0 +1,87 @@
+import * as clack from "@clack/prompts";
+import { LocalConfigStore } from "../core/runtime/LocalConfigStore.js";
+import { MANAGED_IMAGE_SERVICES, requireManagedImageService } from "../core/runtime/ManagedImages.js";
+import { PublicImageTagRegistry } from "../core/runtime/PublicImageTagRegistry.js";
+import { requireInteractiveTerminal, unwrapPromptResult } from "./interactive.js";
+function parsePositiveInteger(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`Expected a positive integer, received: ${value}`);
+    }
+    return parsed;
+}
+async function promptForSelection(message, options, input, output, defaultValue) {
+    requireInteractiveTerminal(input, output, "set-image-version requires a TTY so you can choose an image interactively.");
+    if (options.length === 0) {
+        throw new Error("No selectable options were provided.");
+    }
+    const selected = await clack.select({
+        message,
+        options: options.map((option, index) => ({
+            ...option,
+            hint: option.value === defaultValue ? "current" : undefined
+        })),
+        initialValue: defaultValue,
+        input,
+        output
+    });
+    return unwrapPromptResult(selected, "Image selection cancelled.", output);
+}
+async function loadAvailableTags(registry, service, limit, output) {
+    const spinner = clack.spinner({ output });
+    spinner.start(`Loading the latest ${limit} image tags for ${service}`);
+    let tags;
+    try {
+        tags = await registry.listAvailableTags(service, limit);
+    }
+    catch (error) {
+        spinner.stop("Unable to load image tags");
+        throw error;
+    }
+    if (tags.length === 0) {
+        spinner.stop("No image tags found");
+        throw new Error(`No image tags found for ${service}.`);
+    }
+    spinner.stop(`Loaded ${tags.length} image tag${tags.length === 1 ? "" : "s"}`);
+    return tags;
+}
+function formatTagTimestamp(createdAt) {
+    if (!createdAt) {
+        return "timestamp unavailable";
+    }
+    const timestamp = new Date(createdAt);
+    if (Number.isNaN(timestamp.valueOf())) {
+        return "timestamp unavailable";
+    }
+    return timestamp.toISOString().slice(0, 16).replace("T", " ") + " UTC";
+}
+export async function runSetImageVersion(options, dependencies = {}) {
+    const input = dependencies.input ?? process.stdin;
+    const output = dependencies.output ?? process.stdout;
+    const registry = dependencies.registry ?? new PublicImageTagRegistry();
+    const configStore = dependencies.configStore ?? new LocalConfigStore();
+    clack.intro("CompanyHelm image selection", { output });
+    const selectedService = options.service
+        ? requireManagedImageService(options.service)
+        : await promptForSelection("Which image do you want to pin?", MANAGED_IMAGE_SERVICES.map((service) => ({ value: service, label: service })), input, output).then((value) => requireManagedImageService(value));
+    const currentImage = configStore.load().images[selectedService];
+    clack.log.info(`Current configured image for ${selectedService}: ${currentImage ?? "default (latest)"}`, { output });
+    const tags = await loadAvailableTags(registry, selectedService, options.limit, output);
+    const currentTag = currentImage ? currentImage.slice(currentImage.lastIndexOf(":") + 1) : undefined;
+    const selectedTag = await promptForSelection(`Choose the ${selectedService} image tag`, tags.map((tag) => ({
+        value: tag.tag,
+        label: `${tag.tag} (${formatTagTimestamp(tag.createdAt)})`
+    })), input, output, currentTag);
+    const result = configStore.setImage(selectedService, registry.buildImageReference(selectedService, selectedTag));
+    clack.outro(`Updated ${result.configPath} to ${result.image}`, { output });
+}
+export function registerSetImageVersionCommand(program) {
+    program
+        .command("set-image-version")
+        .description("Interactively choose an API or frontend image tag and store it in local config.yaml.")
+        .option("-s, --service <service>", "Prefill the service to update (api or frontend)")
+        .option("-l, --limit <count>", "How many image tags to show", parsePositiveInteger, 20)
+        .action(async (options) => {
+        await runSetImageVersion(options);
+    });
+}

package/dist/commands/setup-github-app.d.ts

@@ -0,0 +1,10 @@
+import { Writable, type Readable } from "node:stream";
+import type { Command } from "commander";
+import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
+import { type GithubAppConfig } from "../core/config/GithubAppConfig.js";
+type BrowserUrlOpener = (url: string) => Promise<void>;
+export declare function readPemFromTerminal(input?: Readable, output?: Writable): Promise<string>;
+export declare function promptGithubAppConfig(input?: Readable, output?: Writable, openBrowser?: BrowserUrlOpener): Promise<GithubAppConfig>;
+export declare function ensureGithubAppConfig(store?: GithubAppConfigStore, input?: Readable, output?: Writable): Promise<GithubAppConfig>;
+export declare function registerSetupGithubAppCommand(program: Command, store?: GithubAppConfigStore): void;
+export {};

package/dist/commands/setup-github-app.js

@@ -0,0 +1,211 @@
+import * as clack from "@clack/prompts";
+import chalk from "chalk";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { unwrapPromptResult, requireInteractiveTerminal, InteractiveCommandCancelledError } from "./interactive.js";
+import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
+import { normalizeGithubAppConfig } from "../core/config/GithubAppConfig.js";
+const GITHUB_NEW_APP_URL = "https://github.com/settings/apps/new";
+function createHiddenTerminalOutput() {
+    return new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+}
+function getBrowserOpenCommand(url) {
+    if (process.platform === "darwin") {
+        return { command: "open", args: [url] };
+    }
+    if (process.platform === "win32") {
+        return { command: "cmd", args: ["/c", "start", "", url] };
+    }
+    return { command: "xdg-open", args: [url] };
+}
+async function openUrlInBrowser(url) {
+    const { command, args } = getBrowserOpenCommand(url);
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+function writeGithubAppCreationGuide(output) {
+    const divider = chalk.dim("=".repeat(68));
+    const label = (text) => chalk.bold(chalk.cyan(text));
+    const value = (text) => chalk.white(text);
+    output.write([
+        divider,
+        chalk.bold("Create a GitHub App before continuing"),
+        chalk.dim("CompanyHelm needs a local GitHub App before startup can continue."),
+        chalk.dim("Agents use that app to access and work on your repositories from isolated container workspaces."),
+        chalk.dim("That lets each agent clone repos and operate safely without reusing your host checkout."),
+        "",
+        `${label("New app page")} ${chalk.underline(chalk.green(GITHUB_NEW_APP_URL))}`,
+        "",
+        chalk.bold("Required form values"),
+        `${label("GitHub App name:")} ${value("Any name you like, e.g. companyhelm <your deployment name>")}`,
+        `${label("Public link:")} ${value("Paste your public link here")}`,
+        `${label("Setup URL:")} ${value("http://localhost:4173/github/install")}`,
+        `${label("Redirect on update:")} ${value("Checked")}`,
+        `${label("Webhook:")} ${value("Leave it inactive and uncheck the webhook option")}`,
+        `${label("Permissions:")} ${value("Grant at least Contents so CompanyHelm can download repositories; add any additional permissions your agents need")}`,
+        `${label("Where can this GitHub App be installed?")} ${value("Select Any account")}`,
+        "",
+        chalk.bold("Bring back after creation"),
+        value("App URL, Client ID, and private key PEM"),
+        "",
+        divider,
+        "",
+    ].join("\n"));
+}
+async function promptTextValue(message, input, output, validate) {
+    const value = await clack.text({
+        message,
+        input,
+        output,
+        validate,
+    });
+    return String(unwrapPromptResult(value, "GitHub App setup cancelled.", output)).trim();
+}
+export async function readPemFromTerminal(input = process.stdin, output = process.stdout) {
+    requireInteractiveTerminal(input, output, "setup-github-app requires an interactive terminal.");
+    output.write([
+        "Generate a private key.",
+        "Once downloaded copy the contents (e.g. cat ~/Downloads/{your-app-name}{date}.pem | pbcopy) and paste it here.",
+        "",
+    ].join("\n"));
+    const readline = createInterface({
+        input,
+        output: createHiddenTerminalOutput(),
+        terminal: false,
+    });
+    return await new Promise((resolve, reject) => {
+        const lines = [];
+        let settled = false;
+        const finish = (callback) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            readline.close();
+            callback();
+        };
+        readline.on("line", (line) => {
+            lines.push(line);
+            if (/^-----END [A-Z0-9 ]+-----$/.test(line.trim())) {
+                finish(() => {
+                    try {
+                        const normalized = normalizeGithubAppConfig({
+                            appUrl: "https://github.com/apps/placeholder",
+                            appClientId: "placeholder",
+                            appPrivateKeyPem: `${lines.join("\n")}\n`,
+                        });
+                        resolve(normalized.appPrivateKeyPem);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                });
+            }
+        });
+        readline.on("close", () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            reject(new Error("GitHub App PEM input ended before a PEM end marker was received."));
+        });
+        readline.on("SIGINT", () => {
+            finish(() => {
+                reject(new InteractiveCommandCancelledError("GitHub App setup cancelled."));
+            });
+        });
+        readline.on("error", (error) => {
+            finish(() => {
+                reject(error);
+            });
+        });
+    });
+}
+export async function promptGithubAppConfig(input = process.stdin, output = process.stdout, openBrowser = openUrlInBrowser) {
+    requireInteractiveTerminal(input, output, "setup-github-app requires an interactive terminal.");
+    writeGithubAppCreationGuide(output);
+    const shouldOpenBrowser = unwrapPromptResult(await clack.confirm({
+        message: `Open ${GITHUB_NEW_APP_URL} in your browser now?`,
+        active: "Yes",
+        inactive: "No",
+        initialValue: true,
+        input,
+        output,
+    }), "GitHub App setup cancelled.", output);
+    if (shouldOpenBrowser) {
+        try {
+            await openBrowser(GITHUB_NEW_APP_URL);
+            output.write(`Opened ${GITHUB_NEW_APP_URL} in your browser.\n\n`);
+        }
+        catch {
+            output.write([
+                "Could not open a browser automatically.",
+                `Open this URL manually: ${GITHUB_NEW_APP_URL}`,
+                "",
+            ].join("\n"));
+        }
+    }
+    const appUrl = await promptTextValue("GitHub App URL", input, output, (value) => {
+        try {
+            new URL(String(value || "").trim());
+            return undefined;
+        }
+        catch {
+            return "Enter a valid GitHub App URL.";
+        }
+    });
+    const appClientId = await promptTextValue("GitHub App Client ID (not the App ID)", input, output, (value) => (String(value || "").trim() ? undefined : "Client ID is required."));
+    const appPrivateKeyPem = await readPemFromTerminal(input, output);
+    return normalizeGithubAppConfig({
+        appUrl,
+        appClientId,
+        appPrivateKeyPem,
+    });
+}
+export async function ensureGithubAppConfig(store = new GithubAppConfigStore(), input = process.stdin, output = process.stdout) {
+    const existingConfig = store.load();
+    if (existingConfig) {
+        return existingConfig;
+    }
+    requireInteractiveTerminal(input, output, `GitHub App config is not set up. Run \`companyhelm setup-github-app\` or rerun \`companyhelm up\` in a TTY.`);
+    clack.intro("CompanyHelm GitHub App setup", { output });
+    clack.note([
+        "No machine GitHub App config was found.",
+        "CompanyHelm will collect it now and then continue startup.",
+    ].join("\n"), "Setup required", { output });
+    const config = await promptGithubAppConfig(input, output);
+    const spinner = clack.spinner({ output });
+    spinner.start("Saving machine GitHub App config");
+    const configPath = store.save(config);
+    spinner.stop(`Saved GitHub App config to ${configPath}`);
+    clack.outro("GitHub App setup complete. Continuing startup.", { output });
+    return config;
+}
+export function registerSetupGithubAppCommand(program, store = new GithubAppConfigStore()) {
+    program
+        .command("setup-github-app")
+        .description("Save machine-wide GitHub App config for local deploys.")
+        .action(async () => {
+        clack.intro("CompanyHelm GitHub App setup");
+        const config = await promptGithubAppConfig();
+        const spinner = clack.spinner();
+        spinner.start("Saving machine GitHub App config");
+        const configPath = store.save(config);
+        spinner.stop(`Saved GitHub App config to ${configPath}`);
+        clack.outro(`Saved GitHub App config to ${configPath}.`);
+    });
+}

package/dist/commands/status.js

@@ -1,5 +1,7 @@
+import { TerminalRenderer } from "../core/ui/TerminalRenderer.js";
 export function registerStatusCommand(program, dependencies) {
     program.command("status").description("Show deployment status.").action(async () => {
-        process.stdout.write(`${JSON.stringify(await dependencies.status())}\n`);
+        const renderer = new TerminalRenderer(process.stdout.isTTY);
+        process.stdout.write(`${renderer.renderStatus(await dependencies.status())}\n`);
     });
 }

package/dist/commands/up.js

@@ -1,5 +1,39 @@
+const LOG_LEVELS = new Set(["debug", "info", "warn", "error"]);
 export function registerUpCommand(program, dependencies) {
-    program.command("up").description("Start or reconcile the local deployment.").action(async () => {
-        await dependencies.up();
+    program
+        .command("up")
+        .description("Start or reconcile the local deployment.")
+        .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.`);
+        }
+        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

@@ -1,9 +1,14 @@
+import type { LogLevel } from "../../commands/dependencies.js";
 import type { RuntimeState } from "../runtime/RuntimeState.js";
 export declare class DeploymentBootstrapper {
     private readonly renderer;
-    private readonly githubAppClientId;
     writeSeedSql(root: string, state: RuntimeState, passwordHash: string, passwordSalt: string): string;
-    writeApiConfig(root: string, state: RuntimeState): 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

@@ -3,7 +3,6 @@ import { RuntimePaths } from "../runtime/RuntimePaths.js";
 import { SeedSqlRenderer } from "./SeedSqlRenderer.js";
 export class DeploymentBootstrapper {
     renderer = new SeedSqlRenderer();
-    githubAppClientId = "Iv23lirb9vZAi67f5bSQ";
     writeSeedSql(root, state, passwordHash, passwordSalt) {
         const runtimePaths = new RuntimePaths(root);
         const outputPath = runtimePaths.seedFilePath();
@@ -19,28 +18,32 @@ export class DeploymentBootstrapper {
         fs.writeFileSync(outputPath, sql, "utf8");
         return outputPath;
     }
-    writeApiConfig(root, state) {
+    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:",
@@ -50,10 +53,9 @@ export class DeploymentBootstrapper {
             '      username: "postgres"',
             '      password: "postgres"',
             "github:",
-            `  app_client_id: "${this.githubAppClientId}"`,
-            "  app_private_key_pem: |-",
-            this.indentBlock(state.auth.jwtPrivateKeyPem, 4),
-            '  app_link: "https://github.com/apps/companyhelm-local"',
+            '  app_client_id: "${GITHUB_APP_CLIENT_ID}"',
+            '  app_private_key_pem: "${GITHUB_APP_PRIVATE_KEY_PEM}"',
+            '  app_link: "${GITHUB_APP_URL}"',
             'authProvider: "companyhelm"',
             "auth:",
             "  companyhelm:",
@@ -67,7 +69,7 @@ export class DeploymentBootstrapper {
             "security:",
             "  encryption:",
             '    key: "companyhelm-local-encryption-key"',
-            'log_level: "info"',
+            `log_level: "${logLevel}"`,
             "log_pretty: false",
             ""
         ].join("\n");

package/dist/core/bootstrap/SeedSqlRenderer.js

@@ -8,19 +8,37 @@ export class SeedSqlRenderer {
     render(input) {
         const templatePath = path.resolve(__dirname, "../../templates/seed.sql.tpl");
         const template = fs.readFileSync(templatePath, "utf8");
-        const email = `${input.username}@local.companyhelm`;
+        const email = input.username.trim();
+        const firstName = email.split("@")[0] || email;
         const runnerSecretHash = createHash("sha256").update(input.runnerSecret).digest("hex");
+        const userId = deriveUuid(input.companyId, "user");
+        const userAuthId = deriveUuid(input.companyId, "user-auth");
+        const runnerId = deriveUuid(input.companyId, "runner");
         return template
             .replaceAll("{{COMPANY_ID}}", input.companyId)
             .replaceAll("{{COMPANY_NAME}}", input.companyName)
-            .replaceAll("{{USER_ID}}", `${input.companyId}-admin`)
-            .replaceAll("{{USER_AUTH_ID}}", `${input.companyId}-auth`)
-            .replaceAll("{{USER_FIRST_NAME}}", input.username)
+            .replaceAll("{{USER_ID}}", userId)
+            .replaceAll("{{USER_AUTH_ID}}", userAuthId)
+            .replaceAll("{{USER_FIRST_NAME}}", firstName)
             .replaceAll("{{USER_EMAIL}}", email)
             .replaceAll("{{PASSWORD_SALT}}", input.passwordSalt ?? "password-salt")
             .replaceAll("{{PASSWORD_HASH}}", input.passwordHash)
-            .replaceAll("{{RUNNER_ID}}", `${input.companyId}-runner`)
+            .replaceAll("{{RUNNER_ID}}", runnerId)
             .replaceAll("{{RUNNER_NAME}}", input.runnerName)
             .replaceAll("{{RUNNER_SECRET_HASH}}", runnerSecretHash);
     }
 }
+function deriveUuid(companyId, scope) {
+    const hex = createHash("sha256").update(`${companyId}:${scope}`).digest("hex");
+    const chars = hex.slice(0, 32).split("");
+    chars[12] = "4";
+    chars[16] = ((Number.parseInt(chars[16] ?? "0", 16) & 0x3) | 0x8).toString(16);
+    const normalized = chars.join("");
+    return [
+        normalized.slice(0, 8),
+        normalized.slice(8, 12),
+        normalized.slice(12, 16),
+        normalized.slice(16, 20),
+        normalized.slice(20, 32)
+    ].join("-");
+}

package/dist/core/config/ApiEnvFileWriter.d.ts

@@ -0,0 +1,6 @@
+import type { GithubAppConfig } from "./GithubAppConfig.js";
+export declare class ApiEnvFileWriter {
+    private readonly projectPaths;
+    constructor(projectRoot?: string);
+    write(config: GithubAppConfig): string;
+}

package/dist/core/config/ApiEnvFileWriter.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import { ProjectPaths } from "../runtime/ProjectPaths.js";
+function escapeEnvValue(value) {
+    return String(value || "")
+        .replace(/\\/g, "\\\\")
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .replace(/\n/g, "\\n");
+}
+export class ApiEnvFileWriter {
+    projectPaths;
+    constructor(projectRoot = process.cwd()) {
+        this.projectPaths = new ProjectPaths(projectRoot);
+    }
+    write(config) {
+        fs.mkdirSync(this.projectPaths.apiDirectoryPath(), { recursive: true });
+        const contents = [
+            `GITHUB_APP_URL=${escapeEnvValue(config.appUrl)}`,
+            `GITHUB_APP_CLIENT_ID=${escapeEnvValue(config.appClientId)}`,
+            `GITHUB_APP_PRIVATE_KEY_PEM=${escapeEnvValue(config.appPrivateKeyPem)}`,
+            "",
+        ].join("\n");
+        fs.writeFileSync(this.projectPaths.apiEnvPath(), contents, "utf8");
+        return this.projectPaths.apiEnvPath();
+    }
+}

package/dist/core/config/GithubAppConfig.d.ts

@@ -0,0 +1,6 @@
+export interface GithubAppConfig {
+    appUrl: string;
+    appClientId: string;
+    appPrivateKeyPem: string;
+}
+export declare function normalizeGithubAppConfig(config: GithubAppConfig): GithubAppConfig;

package/dist/core/config/GithubAppConfig.js

@@ -0,0 +1,26 @@
+function normalizeRequiredValue(value, fieldName) {
+    const normalized = String(value || "").trim();
+    if (!normalized) {
+        throw new Error(`GitHub App config field "${fieldName}" is required.`);
+    }
+    return normalized;
+}
+export function normalizeGithubAppConfig(config) {
+    const appUrl = normalizeRequiredValue(config.appUrl, "appUrl");
+    try {
+        new URL(appUrl);
+    }
+    catch {
+        throw new Error(`GitHub App config field "appUrl" must be a valid URL.`);
+    }
+    const appClientId = normalizeRequiredValue(config.appClientId, "appClientId");
+    const rawPem = String(config.appPrivateKeyPem || "").replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+    if (!rawPem) {
+        throw new Error('GitHub App config field "appPrivateKeyPem" is required.');
+    }
+    return {
+        appUrl,
+        appClientId,
+        appPrivateKeyPem: `${rawPem}\n`,
+    };
+}

package/dist/core/config/GithubAppConfigStore.d.ts

@@ -0,0 +1,11 @@
+import { type GithubAppConfig } from "./GithubAppConfig.js";
+export declare class GithubAppConfigStore {
+    private readonly configRoot;
+    constructor(configRoot?: string);
+    configPath(): string;
+    hasConfig(): boolean;
+    save(config: GithubAppConfig): string;
+    load(): GithubAppConfig | null;
+    loadOrThrow(): GithubAppConfig;
+    delete(): void;
+}

package/dist/core/config/GithubAppConfigStore.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { normalizeGithubAppConfig } from "./GithubAppConfig.js";
+function defaultConfigRoot() {
+    const explicitRoot = String(process.env.COMPANYHELM_CONFIG_HOME || "").trim();
+    if (explicitRoot) {
+        return path.resolve(explicitRoot);
+    }
+    const xdgRoot = String(process.env.XDG_CONFIG_HOME || "").trim();
+    if (xdgRoot) {
+        return path.resolve(xdgRoot, "companyhelm");
+    }
+    return path.join(os.homedir(), ".config", "companyhelm");
+}
+export class GithubAppConfigStore {
+    configRoot;
+    constructor(configRoot = defaultConfigRoot()) {
+        this.configRoot = configRoot;
+    }
+    configPath() {
+        return path.join(this.configRoot, "github-app.yaml");
+    }
+    hasConfig() {
+        return fs.existsSync(this.configPath());
+    }
+    save(config) {
+        const normalized = normalizeGithubAppConfig(config);
+        fs.mkdirSync(this.configRoot, { recursive: true });
+        const tempPath = `${this.configPath()}.tmp`;
+        const yaml = stringify({
+            app_url: normalized.appUrl,
+            app_client_id: normalized.appClientId,
+            app_private_key_pem: normalized.appPrivateKeyPem,
+        });
+        fs.writeFileSync(tempPath, yaml, { encoding: "utf8", mode: 0o600 });
+        fs.renameSync(tempPath, this.configPath());
+        return this.configPath();
+    }
+    load() {
+        if (!this.hasConfig()) {
+            return null;
+        }
+        const parsed = parse(fs.readFileSync(this.configPath(), "utf8"));
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`Machine GitHub App config at ${this.configPath()} is invalid.`);
+        }
+        return normalizeGithubAppConfig({
+            appUrl: String(parsed.app_url || ""),
+            appClientId: String(parsed.app_client_id || ""),
+            appPrivateKeyPem: String(parsed.app_private_key_pem || ""),
+        });
+    }
+    loadOrThrow() {
+        const config = this.load();
+        if (!config) {
+            throw new Error(`GitHub App config is not set up. Run \`companyhelm setup-github-app\` to create ${this.configPath()}.`);
+        }
+        return config;
+    }
+    delete() {
+        fs.rmSync(this.configPath(), { force: true });
+    }
+}

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

@@ -1,3 +1,4 @@
+import type { LogLevel } from "../../commands/dependencies.js";
 export interface ComposePorts {
     apiHttpPort: number;
     uiPort: number;
@@ -6,9 +7,16 @@ export interface ComposePorts {
 }
 export interface ComposePaths {
     apiConfigPath: string;
+    apiEnvPath: string;
     frontendConfigPath: string;
     seedFilePath: string;
 }
+export interface ComposeRenderOptions {
+    frontendLogLevel?: LogLevel;
+    includeApi?: boolean;
+    includeFrontend?: boolean;
+    exposePostgresPort?: boolean;
+}
 export declare class ComposeTemplateRenderer {
-    render(ports: ComposePorts, paths: ComposePaths): string;
+    render(ports: ComposePorts, paths: ComposePaths, options?: ComposeRenderOptions): string;
 }