@openpalm/lib 0.11.0-beta.9 → 0.11.0-rc.1

package/src/control-plane/config-persistence.ts

@@ -3,58 +3,53 @@
  *
  * Writes and derives live runtime files (compose, env, schemas).
  * Files are validated in-place before writing; rollback is handled by
- * the rollback module (snapshot to ~/.cache/openpalm/rollback/).
+ * the rollback module (snapshot to OP_HOME/data/rollback/).
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
-import { dirname } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
 import { parse as yamlParse } from "yaml";
-import { parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
+import { parseEnvContent, parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
+import { assertNoSecretLikeStackEnvKeys, isSecretLikeStackEnvKey } from './secrets.js';
+import { ensureSecret } from './secrets-files.js';
 import type { ControlPlaneState, ArtifactMeta } from "./types.js";
-import { isChannelAddon } from "./channels.js";
 import { listEnabledAddonIds } from "./registry.js";
 import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
+import { SPEC_DEFAULTS } from "./stack-spec.js";
 
 import {
   readCoreCompose,
+  readBundledStackAsset,
 } from "./core-assets.js";
 export { sha256, randomHex } from "./crypto.js";
 import { sha256, randomHex } from "./crypto.js";
 
-const DEFAULT_IMAGE_TAG = process.env.OP_IMAGE_TAG ?? "latest";
+const DEFAULT_IMAGE_TAG = "latest";
 
 // ── Env File Management ──────────────────────────────────────────────
 
 /**
  * Return the env files used for docker compose --env-file args.
- * These are the live vault env files.
  *
- * Order: stack.env -> guardian.env
- *
- * Note: `vault/user/user.env` is no longer a
- * compose env_file. User-managed env secrets live in the akm
- * `vault:user` store and are sourced by the assistant entrypoint at
- * container startup. The legacy file is migrated into akm and deleted
- * on upgrade; subsequent `docker compose` invocations must not reference
- * it (compose interpolates `${VAR}` against the merged --env-file
- * contents, and a stale user.env would shadow the akm-sourced values).
+ * Only `knowledge/env/stack.env` (non-secret system config). Secret values
+ * live in `knowledge/secrets/<ENV_KEY>` and are granted to services as Compose
+ * file secrets. The user env (`knowledge/env/user.env`) is NOT a compose
+ * env_file — it is sourced by the assistant entrypoint at container startup.
  */
 export function buildEnvFiles(state: ControlPlaneState): string[] {
   return [
-    `${state.stackDir}/stack.env`,
-    `${state.stackDir}/guardian.env`,
+    `${state.stashDir}/env/stack.env`,
   ].filter(existsSync);
 }
 
 /**
- * Write system-managed values to config/stack/stack.env.
+ * Write system-managed values to knowledge/env/stack.env.
  *
- * Channel HMAC secrets are NOT written here — they belong in guardian.env.
- * Use writeChannelSecrets() for channel secrets.
+ * Secret-like keys are NOT written here — they belong in knowledge/secrets/.
+ * Use ensureChannelSecret() for channel secrets.
  */
 export function writeSystemEnv(state: ControlPlaneState): void {
-  mkdirSync(state.stackDir, { recursive: true });
-
-  const systemEnvPath = `${state.stackDir}/stack.env`;
+  const systemEnvPath = `${state.stashDir}/env/stack.env`;
+  mkdirSync(`${state.stashDir}/env`, { recursive: true, mode: 0o700 });
 
   let base = "";
   if (existsSync(systemEnvPath)) {
@@ -63,11 +58,12 @@ export function writeSystemEnv(state: ControlPlaneState): void {
     base = generateFallbackSystemEnv(state);
   }
 
-  // Preserve existing OP_SETUP_COMPLETE=true
-  const alreadyComplete = /^OP_SETUP_COMPLETE=true$/mi.test(base);
-
+  // Preserve the existing OP_SETUP_COMPLETE flag as-is.
+  // Only the wizard completion path (buildSystemSecretsFromSetup) writes "true".
+  // Defaulting to "false" here ensures a fresh install always shows the wizard.
+  const parsed = parseEnvFile(systemEnvPath);
   const adminManaged: Record<string, string> = {
-    OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
+    OP_SETUP_COMPLETE: parsed.OP_SETUP_COMPLETE === "true" ? "true" : "false",
   };
 
   // Backfill OP_UID/OP_GID when the existing stack.env was written by an
@@ -76,13 +72,20 @@ export function writeSystemEnv(state: ControlPlaneState): void {
   // missing or zero — an operator who manually set OP_UID=2000 (e.g.
   // because they're running on a host with a non-1000 service account)
   // must not be silently changed.
-  const parsed = parseEnvFile(systemEnvPath);
   const ids = resolveOperatorIds(state.homeDir);
   if (ids) {
     if (!hasUsableOperatorId(parsed, "OP_UID")) adminManaged.OP_UID = String(ids.uid);
     if (!hasUsableOperatorId(parsed, "OP_GID")) adminManaged.OP_GID = String(ids.gid);
   }
 
+  // Backfill OP_HOME when missing — compose files reference ${OP_HOME}
+  // for all volume mounts. Without this, Docker Compose defaults to blank.
+  if (!parsed.OP_HOME) adminManaged.OP_HOME = state.homeDir;
+
+  base = stripSecretLikeEnvKeys(base);
+  assertNoSecretLikeStackEnvKeys(parseEnvContent(base));
+  assertNoSecretLikeStackEnvKeys(adminManaged);
+
   const content = mergeEnvContent(base, adminManaged, {
     sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
   });
@@ -91,6 +94,19 @@ export function writeSystemEnv(state: ControlPlaneState): void {
   chmodSync(systemEnvPath, 0o600);
 }
 
+function stripSecretLikeEnvKeys(content: string): string {
+  return content
+    .split('\n')
+    .filter((line) => {
+      let trimmed = line.trim();
+      if (trimmed.startsWith('export ')) trimmed = trimmed.slice(7).trimStart();
+      const eq = trimmed.indexOf('=');
+      if (eq <= 0) return true;
+      return !isSecretLikeStackEnvKey(trimmed.slice(0, eq).trim());
+    })
+    .join('\n');
+}
+
 function generateFallbackSystemEnv(state: ControlPlaneState): string {
   // Operator UID/GID — auto-detect from OP_HOME owner (or process UID).
   // Skipped on Windows where containers run in WSL2 and OP_UID has no
@@ -104,12 +120,6 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     "# OpenPalm — System Configuration (managed by CLI/admin)",
     "# Auto-generated fallback.",
     "",
-    "# ── Authentication ──────────────────────────────────────────────────",
-    `OP_UI_LOGIN_PASSWORD=\${OP_UI_LOGIN_PASSWORD}`,
-    "",
-    "# ── Service Auth ─────────────────────────────────────────────────────",
-    "OP_OPENCODE_PASSWORD=",
-    "",
     "# ── Paths ──────────────────────────────────────────────────────────",
     `OP_HOME=${state.homeDir}`,
     ...idLines,
@@ -121,9 +131,8 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     "# ── Ports (38XX range) ──────────────────────────────────────────────",
     "# Guardian is network-only (no host port) — channels reach it via",
     "# http://guardian:8080 over the channel_lan Docker network.",
-    `OP_ASSISTANT_PORT=3800`,
-    `OP_ADMIN_PORT=3880`,
-    `OP_ADMIN_OPENCODE_PORT=3881`,
+    `OP_ASSISTANT_PORT=${SPEC_DEFAULTS.ports.assistant}`,
+    `OP_HOST_UI_PORT=${SPEC_DEFAULTS.ports.hostUi}`,
     ""
   ].join("\n");
 }
@@ -131,37 +140,25 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
 // ── Stack Overlay Discovery ────────────────────────────────────────────
 
 /**
- * Discover compose overlays from the stack directory.
- * Returns full paths: [stack/core.compose.yml, stack/addons/{name}/compose.yml].
+ * Discover active compose overlays.
+ * Returns the fixed compose stack: core, services, channels, and custom.
+ * First-party services are profile-gated inside services.compose.yml and
+ * channels.compose.yml.
+ *
+ * Host AKM sharing is NOT a compose overlay: the assistant always mounts
+ * `/host-stash` (core.compose.yml, with an empty-dir fallback), and "sharing"
+ * is purely a writable secondary source entry in config/akm/config.json. No
+ * conditional overlay file is involved.
  */
-export function discoverStackOverlays(stackDir: string): string[] {
+export function discoverStackOverlays(stackDir: string, _homeDir?: string): string[] {
   const files: string[] = [];
 
   const coreYml = `${stackDir}/core.compose.yml`;
   if (existsSync(coreYml)) files.push(coreYml);
 
-  const addonsDir = `${stackDir}/addons`;
-  if (existsSync(addonsDir)) {
-    const entries = readdirSync(addonsDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      const dir = `${addonsDir}/${entry.name}`;
-      // Pick up compose.yml plus any compose.<variant>.yml sibling
-      // overlays (e.g. compose.cdi.yml generated by /admin/voice on
-      // CDI hosts). Stable sort: compose.yml first, then siblings
-      // alphabetically, so the base file's keys are the defaults and
-      // overlays merge on top in deterministic order.
-      const overlays = readdirSync(dir, { withFileTypes: true })
-        .filter((e) => e.isFile() && /^compose(\.[A-Za-z0-9_-]+)?\.ya?ml$/.test(e.name))
-        .map((e) => e.name)
-        .sort((a, b) => {
-          if (a === "compose.yml" || a === "compose.yaml") return -1;
-          if (b === "compose.yml" || b === "compose.yaml") return 1;
-          return a.localeCompare(b);
-        });
-      for (const name of overlays) files.push(`${dir}/${name}`);
-    }
+  for (const name of ['services.compose.yml', 'channels.compose.yml', 'custom.compose.yml']) {
+    const composePath = `${stackDir}/${name}`;
+    if (existsSync(composePath)) files.push(composePath);
   }
 
   return files;
@@ -192,79 +189,38 @@ export function buildRuntimeFileMeta(artifacts: {
 }
 
 // ── Channel Secrets ────────────────────────────────────────────────────
-// Channel HMAC secrets live exclusively in vault/stack/guardian.env.
-
-const CHANNEL_SECRET_RE = /^CHANNEL_([A-Z0-9_]+)_SECRET$/;
-
-/** Extract channel secrets from parsed env entries. */
-function extractChannelSecrets(parsed: Record<string, string>): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [key, value] of Object.entries(parsed)) {
-    const match = key.match(CHANNEL_SECRET_RE);
-    if (match?.[1] && value) result[match[1].toLowerCase()] = value;
-  }
-  return result;
-}
 
-/**
- * Read channel HMAC secrets from config/stack/guardian.env.
- */
-export function readChannelSecrets(stackDir: string): Record<string, string> {
-  return extractChannelSecrets(parseEnvFile(`${stackDir}/guardian.env`));
+export function channelSecretName(addon: string): string {
+  return `channel_${addon.replace(/-/g, '_')}_secret`;
 }
 
-/**
- * Write channel HMAC secrets to state/guardian.env.
- * Merges with existing content; does not overwrite unrelated entries.
- */
-export function writeChannelSecrets(stackDir: string, secrets: Record<string, string>): void {
-  const guardianPath = `${stackDir}/guardian.env`;
-  mkdirSync(stackDir, { recursive: true });
-
-  let base = "";
-  if (existsSync(guardianPath)) {
-    base = readFileSync(guardianPath, "utf-8");
-  } else {
-    base = "# Guardian channel HMAC secrets — managed by openpalm\n";
-  }
-
-  const updates: Record<string, string> = {};
-  for (const [ch, secret] of Object.entries(secrets)) {
-    updates[`CHANNEL_${ch.toUpperCase()}_SECRET`] = secret;
-  }
-
-  const content = mergeEnvContent(base, updates);
-  writeFileSync(guardianPath, content, { mode: 0o600 });
-  // Ensure correct permissions even if file already existed with wrong mode
-  chmodSync(guardianPath, 0o600);
+export function ensureChannelSecret(stackDir: string, addon: string): string {
+  return ensureSecret(stackDir, channelSecretName(addon), () => randomHex(16));
 }
 
 // ── Volume Mount Targets ───────────────────────────────────────────────
 
 /**
- * Parse all enabled compose files and pre-create every host-side volume
- * mount target as the current user. This prevents Docker from creating
- * them as root-owned, which causes EACCES inside non-root containers.
- *
- * For file mounts (basename contains a `.`), creates an empty file.
- * For directory mounts (basename has no `.`), creates the directory.
- *
- * Heuristic: a basename containing a `.` is treated as a file. This
- * intentionally includes leading-dot files (e.g. `.env`) because Docker
- * bind mounts to them must be regular files. Bare directory names like
- * `stack` or `addons` lack extensions and are created as directories.
+ * Parse enabled compose files and pre-create host-side volume mount
+ * targets under OP_HOME as the current user. This prevents Docker from
+ * creating them as root-owned, which causes EACCES inside non-root
+ * containers.
  *
  * Only mount sources under `state.homeDir` are touched; external paths
  * (e.g. `/var/run/docker.sock`) are left alone.
+ *
+ * The file-vs-directory distinction is best-effort and only applies to
+ * explicit OP_HOME paths.
  */
 export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
-  const composeFiles = discoverStackOverlays(state.stackDir);
+  const composeFiles = discoverStackOverlays(state.stackDir, state.homeDir);
   if (composeFiles.length === 0) return;
 
   const envVars: Record<string, string> = {
     ...(process.env as Record<string, string>),
-    ...parseEnvFile(`${state.stackDir}/stack.env`),
+    ...parseEnvFile(`${state.stashDir}/env/stack.env`),
   };
+  const homeRoot = resolvePath(state.homeDir);
 
   for (const file of composeFiles) {
     let doc: Record<string, unknown>;
@@ -291,18 +247,20 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
 
         const hostPath = expandEnvVars(rawSource, envVars);
         if (!hostPath || !hostPath.startsWith('/')) continue;
-        if (existsSync(hostPath)) continue;
+        const resolvedHostPath = resolvePath(hostPath);
+        if (!resolvedHostPath.startsWith(`${homeRoot}/`) && resolvedHostPath !== homeRoot) continue;
+        if (existsSync(resolvedHostPath)) continue;
 
-        // A basename containing a `.` (anywhere, including leading) is a file.
-        // Bare names like `stack` or `data` are directories.
-        const basename = hostPath.split('/').pop() ?? '';
+        // Only create mounts under OP_HOME. For now, treat existing explicit
+        // file paths as files and directory paths as directories.
+        const basename = resolvedHostPath.split('/').pop() ?? '';
         const isFile = basename.includes('.');
 
         if (isFile) {
-          mkdirSync(dirname(hostPath), { recursive: true });
-          writeFileSync(hostPath, '');
+          mkdirSync(dirname(resolvedHostPath), { recursive: true });
+          writeFileSync(resolvedHostPath, '');
         } else {
-          mkdirSync(hostPath, { recursive: true });
+          mkdirSync(resolvedHostPath, { recursive: true });
         }
       }
     }
@@ -322,24 +280,25 @@ export function writeRuntimeFiles(
     writeFileSync(composePath, state.artifacts.compose);
   }
 
-  // Load persisted channel HMAC secrets from guardian.env,
-  // then generate new ones for new channel addons.
-  const channelSecrets = readChannelSecrets(state.stackDir);
+  for (const name of ['services.compose.yml', 'channels.compose.yml', 'custom.compose.yml']) {
+    const path = `${state.stackDir}/${name}`;
+    if (!existsSync(path)) writeFileSync(path, readBundledStackAsset(name));
+  }
+
   for (const addon of listEnabledAddonIds(state.homeDir)) {
-    const composePath = `${state.stackDir}/addons/${addon}/compose.yml`;
-    if (isChannelAddon(composePath) && !channelSecrets[addon]) {
-      channelSecrets[addon] = randomHex(16);
+    if (['api', 'chat', 'discord', 'slack'].includes(addon)) {
+      for (const channel of ['api', 'chat', 'discord', 'slack']) {
+        ensureChannelSecret(state.stackDir, channel);
+      }
+      break;
     }
   }
 
-  // Write channel secrets to guardian.env (the canonical source)
-  writeChannelSecrets(state.stackDir, channelSecrets);
-
-  // Write system.env (no channel secrets — those live in guardian.env)
+  // Write stack.env (no secrets — those live in knowledge/secrets/)
   writeSystemEnv(state);
 
   // Ensure state directory exists
-  mkdirSync(state.stateDir, { recursive: true });
+  mkdirSync(state.dataDir, { recursive: true });
 
   state.artifactMeta = buildRuntimeFileMeta(state.artifacts);
 }

package/src/control-plane/core-assets.ts

@@ -5,19 +5,24 @@
  *   stack/              — compose runtime assets (core.compose.yml)
  *
  * This module manages runtime-owned core files only.
- * Registry catalog refresh is handled separately in registry.ts.
+ * Addon compose bundle generation and registry catalog refresh are handled
+ * separately in registry.ts.
  * Env validation has moved to `akm vault` + the in-house redactor — the
  * historical `.env.schema` files (varlock format) were retired in #391.
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveStateDir, resolveOpenPalmHome, resolveBackupsDir, resolveStashDir } from "./home.js";
+import { resolveDataDir, resolveOpenPalmHome, resolveBackupsDir } from "./home.js";
 import { createLogger } from "../logger.js";
 import { sha256 } from "./crypto.js";
 
 const logger = createLogger("core-assets");
 
+function bundledAssetPath(relPath: string): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '../../../../.openpalm', relPath);
+}
+
 // ── Core Compose (stack/) ─────────────────────────────────────────────
 
 export function ensureCoreCompose(): string {
@@ -27,57 +32,26 @@ export function ensureCoreCompose(): string {
 }
 
 export function readCoreCompose(): string {
-  return readFileSync(`${resolveOpenPalmHome()}/config/stack/core.compose.yml`, "utf-8");
+  const livePath = `${resolveOpenPalmHome()}/config/stack/core.compose.yml`;
+  if (existsSync(livePath)) {
+    return readFileSync(livePath, 'utf-8');
+  }
+  return readFileSync(bundledAssetPath('config/stack/core.compose.yml'), 'utf-8');
+}
+
+export function readBundledStackAsset(name: string): string {
+  return readFileSync(bundledAssetPath(`config/stack/${name}`), 'utf-8');
 }
 
 // ── OpenCode System Config ──────────────────────────────────────────
 
 export function ensureOpenCodeSystemConfig(): void {
-  const dir = `${resolveStateDir()}/assistant`;
+  const dir = `${resolveDataDir()}/assistant`;
   mkdirSync(dir, { recursive: true });
 }
 
 // ── Shared akm stash (skills / commands / agents) ────────────────────
 
-/**
- * Seed the shared akm stash with built-in skills / commands / agents.
- *
- * Idempotent: **never overwrites** an existing file — user edits to a
- * seeded asset always win, which preserves the same "config doesn't
- * overwrite user edits" contract that governs the rest of OP_HOME.
- *
- * Returns the list of stash-relative paths that were actually written
- * (empty on re-run when every seed already exists on disk).
- *
- * `seeds` is a map of stash-relative path → file content. Keys MUST be
- * forward-slash relative paths that stay inside `data/stash/`; any key
- * that escapes the stash directory after canonicalization throws,
- * preventing a malicious caller from writing arbitrary files. Source of
- * truth for the seeded files lives at `.openpalm/stash/` in the
- * repo; the CLI embeds them at build time and passes the embedded
- * record directly.
- */
-export function seedStashAssets(seeds: Record<string, string>): string[] {
-  const stashDir = resolveStashDir();
-  const normalizedStash = resolve(stashDir);
-  const written: string[] = [];
-  for (const [relPath, content] of Object.entries(seeds)) {
-    const targetPath = join(stashDir, relPath);
-    const normalizedTarget = resolve(targetPath);
-    if (
-      normalizedTarget !== normalizedStash &&
-      !normalizedTarget.startsWith(normalizedStash + sep)
-    ) {
-      throw new Error(`Seed path escapes stash dir: ${relPath}`);
-    }
-    if (existsSync(targetPath)) continue;
-    mkdirSync(dirname(targetPath), { recursive: true });
-    writeFileSync(targetPath, content);
-    written.push(relPath);
-  }
-  return written;
-}
-
 // ── Asset Refresh (GitHub download) ──────────────────────────────────
 
 const REPO = "itlackey/openpalm";
@@ -100,12 +74,15 @@ const VERSION = resolveAssetVersion();
 // overwritten) via seedOpenPalmDir (skipExisting) or SEEDED_ASSETS below.
 const MANAGED_ASSETS: { relPath: string; githubFilename: string }[] = [
   { relPath: "config/stack/core.compose.yml", githubFilename: ".openpalm/config/stack/core.compose.yml" },
+  { relPath: "config/stack/services.compose.yml", githubFilename: ".openpalm/config/stack/services.compose.yml" },
+  { relPath: "config/stack/channels.compose.yml", githubFilename: ".openpalm/config/stack/channels.compose.yml" },
 ];
 
 // Seeded once — written only when the file does not exist yet.
 // User edits always win; upgrade never touches these files.
 const SEEDED_ASSETS: { relPath: string; githubFilename: string }[] = [
   { relPath: "config/assistant/opencode.jsonc", githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
+  { relPath: "config/stack/custom.compose.yml", githubFilename: ".openpalm/config/stack/custom.compose.yml" },
 ];
 
 async function downloadAsset(filename: string): Promise<string> {

package/src/control-plane/docker.ts

@@ -39,10 +39,12 @@ function run(
 
 /**
  * Resolve the Docker Compose project name.
- * Honors COMPOSE_PROJECT_NAME (Docker standard) and OP_PROJECT_NAME (legacy).
+ * Honors OP_PROJECT_NAME first for OpenPalm stacks, then COMPOSE_PROJECT_NAME.
  */
-export function resolveComposeProjectName(): string {
+export function resolveComposeProjectName(envOverrides: Record<string, string> = {}): string {
   return (
+    envOverrides.OP_PROJECT_NAME?.trim() ||
+    envOverrides.COMPOSE_PROJECT_NAME?.trim() ||
     process.env.OP_PROJECT_NAME?.trim() ||
     process.env.COMPOSE_PROJECT_NAME?.trim() ||
     "openpalm"
@@ -87,12 +89,14 @@ export async function checkDockerCompose(): Promise<DockerResult> {
   });
 }
 
-/** Build common prefix: compose -f ... --project-name ... --env-file ... */
-function buildComposeArgs(options: { files: string[]; envFiles?: string[] }): string[] {
-  const args = ["compose", ...options.files.flatMap((f) => ["-f", f]), "--project-name", resolveComposeProjectName()];
+/** Build common prefix: compose -f ... --project-name ... --env-file ... --profile ... */
+function buildComposeArgs(options: { files: string[]; envFiles?: string[]; profiles?: string[] }): string[] {
+  const envOverrides = collectEnvOverrides(options.envFiles);
+  const args = ["compose", ...options.files.flatMap((f) => ["-f", f]), "--project-name", resolveComposeProjectName(envOverrides)];
   for (const ef of options.envFiles ?? []) {
     if (existsSync(ef)) args.push("--env-file", ef);
   }
+  for (const p of options.profiles ?? []) args.push("--profile", p);
   return args;
 }
 
@@ -108,7 +112,7 @@ function collectEnvOverrides(envFiles?: string[]): Record<string, string> {
  * Must be called before any lifecycle mutation (install/apply/update).
  */
 export async function composePreflight(
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<DockerResult> {
   const args = buildComposeArgs(options);
   args.push("config", "--quiet");
@@ -119,22 +123,23 @@ export async function composePreflight(
  * Run compose config preflight validation before any mutation.
  * Skipped when OP_SKIP_COMPOSE_PREFLIGHT is set (tests, CI).
  */
-async function runPreflight(options: { files: string[]; envFiles?: string[] }): Promise<void> {
+async function runPreflight(options: { files: string[]; envFiles?: string[]; profiles?: string[] }): Promise<void> {
   if (options.files.length === 0 || process.env.OP_SKIP_COMPOSE_PREFLIGHT) return;
   const result = await composePreflight(options);
   if (!result.ok) {
-    const project = resolveComposeProjectName();
+    const project = resolveComposeProjectName(collectEnvOverrides(options.envFiles));
     const fileArgs = options.files.map((f) => `-f ${f}`).join(" ");
     const envArgs = (options.envFiles ?? []).map((f) => `--env-file ${f}`).join(" ");
+    const profileArgs = (options.profiles ?? []).map((p) => `--profile ${p}`).join(" ");
     throw new Error(
       `Compose preflight failed: ${result.stderr}\n` +
-      `Resolved command: docker compose ${fileArgs} --project-name ${project} ${envArgs} config --quiet`
+      `Resolved command: docker compose ${fileArgs} --project-name ${project} ${envArgs} ${profileArgs} config --quiet`
     );
   }
 }
 
 export async function composeConfigServices(
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<{ ok: boolean; services: string[] }> {
   const args = buildComposeArgs(options);
   args.push("config", "--services");
@@ -163,7 +168,6 @@ export async function composeUp(
     return { ok: false, stdout: "", stderr: "Compose file not found", code: 1 };
   }
   const args = buildComposeArgs(options);
-  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("up", "-d");
   if (options.forceRecreate) args.push("--force-recreate");
   if (options.removeOrphans) args.push("--remove-orphans");
@@ -187,7 +191,6 @@ export async function composeDown(
     return { ok: false, stdout: "", stderr: "Compose file not found", code: 1 };
   }
   const args = buildComposeArgs(options);
-  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("down");
   if (options.removeVolumes) args.push("-v");
   return run(args, undefined);
@@ -313,7 +316,6 @@ export async function composePullService(
 ): Promise<DockerResult> {
   await runPreflight(options);
   const args = buildComposeArgs(options);
-  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("pull", service);
   return run(args, undefined, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }
@@ -323,7 +325,6 @@ export async function composePull(
 ): Promise<DockerResult> {
   await runPreflight(options);
   const args = buildComposeArgs(options);
-  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("pull");
   return run(args, undefined, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }

package/src/control-plane/env.test.ts

@@ -86,25 +86,25 @@ describe("quoteEnvValue quoting strategy (via mergeEnvContent)", () => {
 
 describe("mergeEnvContent updates existing keys with special char values", () => {
   it("updates an existing key to a value with =", () => {
-    const input = "export ADMIN_TOKEN=old_value\n";
-    const result = mergeEnvContent(input, { ADMIN_TOKEN: "new=value=here" });
+    const input = "export TEST_VALUE=old_value\n";
+    const result = mergeEnvContent(input, { TEST_VALUE: "new=value=here" });
     const parsed = parseEnvContent(result);
-    expect(parsed.ADMIN_TOKEN).toBe("new=value=here");
+    expect(parsed.TEST_VALUE).toBe("new=value=here");
   });
 
   it("updates an existing key to a value with $", () => {
-    const input = "export ADMIN_TOKEN=old_value\n";
-    const result = mergeEnvContent(input, { ADMIN_TOKEN: "tok$en" });
+    const input = "export TEST_VALUE=old_value\n";
+    const result = mergeEnvContent(input, { TEST_VALUE: "tok$en" });
     const parsed = parseEnvContent(result);
-    expect(parsed.ADMIN_TOKEN).toBe("tok$en");
+    expect(parsed.TEST_VALUE).toBe("tok$en");
   });
 
   it("preserves export prefix when updating with special chars", () => {
-    const input = "export ADMIN_TOKEN=old_value\n";
-    const result = mergeEnvContent(input, { ADMIN_TOKEN: "new#value" });
-    expect(result).toMatch(/^export ADMIN_TOKEN=/m);
+    const input = "export TEST_VALUE=old_value\n";
+    const result = mergeEnvContent(input, { TEST_VALUE: "new#value" });
+    expect(result).toMatch(/^export TEST_VALUE=/m);
     const parsed = parseEnvContent(result);
-    expect(parsed.ADMIN_TOKEN).toBe("new#value");
+    expect(parsed.TEST_VALUE).toBe("new#value");
   });
 });
 

package/src/control-plane/env.ts

@@ -26,7 +26,7 @@ export function expandEnvVars(input: string, vars: Record<string, string>): stri
   return input.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (_, name, def) => vars[name] ?? def ?? '');
 }
 
-function quoteEnvValue(value: string): string {
+export function quoteEnvValue(value: string): string {
   if (value.length === 0) return '';
   const needsQuoting = /[#"'\\\n\r$]/.test(value) || value !== value.trim();
   if (!needsQuoting) return value;