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

package/src/control-plane/task-files.ts

@@ -0,0 +1,51 @@
+/**
+ * Raw file access for the Automations admin tab — a plain editor for the akm
+ * task files in the assistant tasks dir (/stash/tasks = knowledge/tasks).
+ *
+ * akm task files are YAML (`.yml`/`.yaml`) or markdown (`.md`). Names are always
+ * basenames within the tasks dir; the guard rejects path separators and `..`.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TASK_FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.(ya?ml|md)$/;
+
+export function assertSafeTaskFilename(name: string): void {
+  if (!TASK_FILENAME_RE.test(name) || name.includes('..')) {
+    throw new Error(`Invalid task file name: ${name} (expected a .yml/.yaml/.md basename)`);
+  }
+}
+
+/** The assistant tasks dir for a given stash dir (knowledge). Created if absent. */
+export function resolveTasksDir(stashDir: string): string {
+  const dir = join(stashDir, 'tasks');
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export type TaskFileInfo = { name: string; size: number };
+
+/** List the task files (.yml/.yaml/.md) in the tasks dir, with byte sizes. */
+export function listTaskFiles(stashDir: string): TaskFileInfo[] {
+  const dir = resolveTasksDir(stashDir);
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && TASK_FILENAME_RE.test(e.name) && !e.name.includes('..'))
+    .map((e) => ({ name: e.name, size: statSync(join(dir, e.name)).size }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function readTaskFile(stashDir: string, name: string): string | null {
+  assertSafeTaskFilename(name);
+  const path = join(resolveTasksDir(stashDir), name);
+  return existsSync(path) ? readFileSync(path, 'utf-8') : null;
+}
+
+export function writeTaskFile(stashDir: string, name: string, content: string): void {
+  assertSafeTaskFilename(name);
+  writeFileSync(join(resolveTasksDir(stashDir), name), content, { mode: 0o644 });
+}
+
+export function removeTaskFile(stashDir: string, name: string): void {
+  assertSafeTaskFilename(name);
+  rmSync(join(resolveTasksDir(stashDir), name), { force: true });
+}

package/src/control-plane/types.ts

@@ -27,10 +27,9 @@ export type ArtifactMeta = {
 export type ControlPlaneState = {
   homeDir: string;
   configDir: string;
-  stashDir: string;      // homeDir/stash
+  stashDir: string;      // homeDir/knowledge
   workspaceDir: string;  // homeDir/workspace
-  cacheDir: string;      // homeDir/cache (regenerable/semi-persistent data)
-  stateDir: string;      // homeDir/state (service data + system state)
+  dataDir: string;       // homeDir/data (service data + operational files)
   stackDir: string;      // configDir/stack (compose runtime + stack config)
   services: Record<string, "running" | "stopped">;
   artifacts: {
@@ -48,4 +47,3 @@ export const CORE_SERVICES: CoreServiceName[] = [
   "assistant",
   "guardian",
 ];
-

package/src/control-plane/ui-assets.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { resolveUiBuildDir, readUiBuildVersion, UI_VERSION_STAMP, seedOpenPalmDir, SKELETON_VERSION_STAMP } from "./ui-assets.js";
+
+let root = "";
+let opHome = "";
+let repoRoot = "";
+let dataUi = "";
+let bundledUi = "";
+const saved: Record<string, string | undefined> = {};
+
+function makeBuild(dir: string, version: string | null): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "index.js"), "// ui server\n");
+  if (version !== null) writeFileSync(join(dir, UI_VERSION_STAMP), `${version}\n`);
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "ui-assets-"));
+  opHome = join(root, "ophome");
+  repoRoot = join(root, "repo");
+  dataUi = join(opHome, "data", "ui");
+  bundledUi = join(repoRoot, "packages", "ui", "build"); // resolveLocalUiBuild() candidate 1
+  saved.OP_HOME = process.env.OP_HOME;
+  saved.OPENPALM_REPO_ROOT = process.env.OPENPALM_REPO_ROOT;
+  process.env.OP_HOME = opHome;
+  // Pin the bundled candidate to a controlled location so the resolver never
+  // discovers the real packages/ui/build via its source-relative fallback.
+  // Default: an EMPTY build dir (exists but no index.js) = "no bundled build".
+  process.env.OPENPALM_REPO_ROOT = repoRoot;
+  mkdirSync(bundledUi, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+  for (const k of ["OP_HOME", "OPENPALM_REPO_ROOT"] as const) {
+    if (saved[k] === undefined) delete process.env[k];
+    else process.env[k] = saved[k];
+  }
+});
+
+describe("readUiBuildVersion", () => {
+  it("reads the stamp, or null when absent", () => {
+    makeBuild(dataUi, "0.11.0");
+    expect(readUiBuildVersion(dataUi)).toBe("0.11.0");
+    makeBuild(bundledUi, null);
+    expect(readUiBuildVersion(bundledUi)).toBeNull();
+  });
+});
+
+describe("resolveUiBuildDir — version-aware selection", () => {
+  it("uses data/ui when only it exists", () => {
+    makeBuild(dataUi, "0.11.0");
+    expect(resolveUiBuildDir()).toBe(dataUi);
+  });
+
+  it("uses bundled when only it exists", () => {
+    makeBuild(bundledUi, "0.11.0");
+    process.env.OPENPALM_REPO_ROOT = repoRoot;
+    expect(resolveUiBuildDir()).toBe(bundledUi);
+  });
+
+  it("prefers data/ui only when it is strictly NEWER than bundled", () => {
+    makeBuild(dataUi, "0.12.0");
+    makeBuild(bundledUi, "0.11.0");
+    process.env.OPENPALM_REPO_ROOT = repoRoot;
+    expect(resolveUiBuildDir()).toBe(dataUi);
+  });
+
+  it("prefers bundled when it is newer than data/ui (fixes stale-data/ui shadowing)", () => {
+    makeBuild(dataUi, "0.11.0");
+    makeBuild(bundledUi, "0.12.0");
+    process.env.OPENPALM_REPO_ROOT = repoRoot;
+    expect(resolveUiBuildDir()).toBe(bundledUi);
+  });
+
+  it("prefers bundled when versions are equal", () => {
+    makeBuild(dataUi, "0.11.0");
+    makeBuild(bundledUi, "0.11.0");
+    process.env.OPENPALM_REPO_ROOT = repoRoot;
+    expect(resolveUiBuildDir()).toBe(bundledUi);
+  });
+
+  it("prefers bundled when data/ui is unstamped (cannot prove it is newer)", () => {
+    makeBuild(dataUi, null);
+    makeBuild(bundledUi, "0.11.0");
+    process.env.OPENPALM_REPO_ROOT = repoRoot;
+    expect(resolveUiBuildDir()).toBe(bundledUi);
+  });
+
+  it("falls back to the data/ui path when nothing is present (caller seeds)", () => {
+    expect(resolveUiBuildDir()).toBe(dataUi);
+  });
+});
+
+describe("seedOpenPalmDir — version guard (P2)", () => {
+  const seededFile = () => join(opHome, "config", "stack", "x.txt");
+  const stamp = () => join(opHome, SKELETON_VERSION_STAMP);
+
+  beforeEach(() => {
+    // Local skeleton source at OPENPALM_REPO_ROOT/.openpalm (candidate 1).
+    mkdirSync(join(repoRoot, ".openpalm", "config", "stack"), { recursive: true });
+    writeFileSync(join(repoRoot, ".openpalm", "config", "stack", "x.txt"), "seed\n");
+    mkdirSync(opHome, { recursive: true });
+  });
+
+  it("seeds once and stamps the version", async () => {
+    await seedOpenPalmDir("v1", opHome, join(opHome, "config"), join(opHome, "data"));
+    expect(existsSync(seededFile())).toBe(true);
+    expect(readFileSync(stamp(), "utf-8").trim()).toBe("v1");
+  });
+
+  it("does NOT re-seed (or re-materialize a removed file) for the same version", async () => {
+    await seedOpenPalmDir("v1", opHome, join(opHome, "config"), join(opHome, "data"));
+    rmSync(seededFile(), { force: true });
+    await seedOpenPalmDir("v1", opHome, join(opHome, "config"), join(opHome, "data"));
+    expect(existsSync(seededFile())).toBe(false); // guard skipped the copy
+  });
+
+  it("re-seeds on a version change", async () => {
+    await seedOpenPalmDir("v1", opHome, join(opHome, "config"), join(opHome, "data"));
+    rmSync(seededFile(), { force: true });
+    await seedOpenPalmDir("v2", opHome, join(opHome, "config"), join(opHome, "data"));
+    expect(existsSync(seededFile())).toBe(true);
+    expect(readFileSync(stamp(), "utf-8").trim()).toBe("v2");
+  });
+});

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

@@ -12,13 +12,13 @@
  */
 import {
   existsSync, mkdirSync, readdirSync, copyFileSync,
-  readFileSync, writeFileSync, rmSync, realpathSync, renameSync,
+  writeFileSync, readFileSync, rmSync, realpathSync, renameSync,
 } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { x as tarExtract } from 'tar';
-import { resolveStateDir } from './home.js';
+import { resolveBackupsDir, resolveDataDir } from './home.js';
 import { createLogger } from '../logger.js';
 
 const logger = createLogger('lib:ui-assets');
@@ -87,13 +87,15 @@ export function resolveLocalOpenpalmDir(): string | null {
     () => process.env.OPENPALM_REPO_ROOT
       ? join(process.env.OPENPALM_REPO_ROOT, '.openpalm')
       : null,
-    // 2. Relative to this source file (dev / bun run)
+    // 2. Electron extraResources — openpalm-skeleton/ placed alongside the asar
+    () => process.env.OPENPALM_SKELETON_DIR ?? null,
+    // 3. Relative to this source file (dev / bun run)
     () => {
       const meta = fileURLToPath(import.meta.url);
       if (meta.startsWith('/$bunfs/')) return null;
       return join(dirname(meta), '..', '..', '..', '..', '.openpalm');
     },
-    // 3. Relative to the compiled binary on disk
+    // 4. Relative to the compiled binary on disk
     () => join(dirname(realpathSync(process.execPath)), '..', '..', '..', '.openpalm'),
   );
 }
@@ -105,18 +107,44 @@ export function resolveLocalOpenpalmDir(): string | null {
  * Falls back to downloading the repo tarball from GitHub when no local
  * skeleton is found (production binary, packaged Electron app).
  */
+/** Version stamp recording which skeleton version OP_HOME was last seeded from. */
+export const SKELETON_VERSION_STAMP = '.skeleton-version';
+
+/**
+ * Seed the bundled `.openpalm/` skeleton into OP_HOME — ONCE PER VERSION.
+ *
+ * Electron calls this on every launch; without a guard it re-copied the entire
+ * skeleton tree each time (wasteful, and it re-materialized files a user/process
+ * had deliberately removed). We stamp OP_HOME/.skeleton-version with `repoRef`
+ * after a successful seed and skip the copy when it already matches — so a given
+ * version seeds once and an upgrade re-seeds (skipExisting still preserves any
+ * user edits). To force a re-seed, delete the stamp.
+ */
 export async function seedOpenPalmDir(
   repoRef: string,
   homeDir: string,
   _configDir: string,
-  _stateDir: string,
+  _dataDir: string,
 ): Promise<void> {
+  const stampPath = join(homeDir, SKELETON_VERSION_STAMP);
+  if (existsSync(stampPath)) {
+    try {
+      if (readFileSync(stampPath, 'utf-8').trim() === repoRef.trim()) {
+        logger.debug('skeleton already seeded for this version — skipping', { repoRef });
+        return;
+      }
+    } catch { /* unreadable stamp → re-seed */ }
+  }
+
+  const stamp = (): void => {
+    try { writeFileSync(stampPath, `${repoRef}\n`); } catch { /* best-effort */ }
+  };
+
   const local = resolveLocalOpenpalmDir();
   if (local) {
-    logger.debug('seeding .openpalm from local source', { src: local });
+    logger.debug('seeding .openpalm from local source', { src: local, repoRef });
     copyTree(local, homeDir, { skipExisting: true });
-    // Registry is system-managed — always refresh so addon overlays stay current.
-    copyTree(join(local, 'state', 'registry'), join(homeDir, 'state', 'registry'));
+    stamp();
     return;
   }
 
@@ -137,8 +165,7 @@ export async function seedOpenPalmDir(
     const srcOpenpalm = join(tmpDir, '.openpalm');
     if (!existsSync(srcOpenpalm)) throw new Error('.openpalm/ not found in tarball');
     copyTree(srcOpenpalm, homeDir, { skipExisting: true });
-    // Registry is system-managed — always refresh so addon overlays stay current.
-    copyTree(join(srcOpenpalm, 'state', 'registry'), join(homeDir, 'state', 'registry'));
+    stamp();
   } finally {
     rmSync(tmpDir, { recursive: true, force: true });
   }
@@ -179,47 +206,72 @@ export function resolveLocalUiBuild(): string | null {
   );
 }
 
-function readUiVersionFile(dir: string): string | null {
-  try { return readFileSync(join(dir, 'version.txt'), 'utf-8').trim(); } catch { return null; }
-}
-
 /**
  * Resolve the best available UI build directory at runtime.
  *
  * Priority:
- *   1. OP_HOME/state/ui/ — if its version.txt is NEWER than the bundled build
- *   2. Bundled / local build (Electron extraResources, source checkout)
- *   3. OP_HOME/state/ui/ — fallback when no bundled build exists
+ *   1. OP_HOME/data/ui/ — user-installed or auto-updated build
+ *   2. Bundled / local build (Electron extraResources, OPENPALM_REPO_ROOT, source checkout)
+ */
+/** Filename of the build-time version stamp written into the UI build root. */
+export const UI_VERSION_STAMP = '.openpalm-ui-version';
+
+/** Read the stamped UI version from a build dir, or null if absent/unreadable. */
+export function readUiBuildVersion(dir: string): string | null {
+  try {
+    const v = readFileSync(join(dir, UI_VERSION_STAMP), 'utf-8').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve which UI build to run.
+ *
+ * Two channels exist: the bundled build (shipped inside the AppImage / source
+ * tree) and `data/ui` (operator-updatable, seeded from GitHub releases). To fix
+ * the stale-`data/ui` shadowing bug AND stay forward-compatible with updating the
+ * UI without shipping a new app (D5), selection is VERSION-AWARE:
+ *
+ *   - If only one channel has a build → use it.
+ *   - If both exist → use `data/ui` ONLY when it is strictly NEWER than the
+ *     bundled build (per the version stamp); otherwise prefer the bundled build.
+ *     An unstamped/older `data/ui` never shadows a newer bundled build.
  *
- * This means GitHub-downloaded updates are applied automatically (disk wins
- * when newer), but a fresh AppImage install always works without a download.
+ * This means a fresh app runs its bundled UI, and a future "update UI only" flow
+ * (seed a newer-stamped build into data/ui) is picked up automatically — no app
+ * reinstall required.
  */
 export function resolveUiBuildDir(): string {
-  const stateBuild = join(resolveStateDir(), 'ui');
-  const localBuild = resolveLocalUiBuild();
-
-  if (existsSync(join(stateBuild, 'index.js')) && localBuild) {
-    const diskVer    = readUiVersionFile(stateBuild);
-    const bundledVer = readUiVersionFile(localBuild);
-    if (diskVer && bundledVer && compareVersionTags(diskVer, bundledVer) > 0) {
-      return stateBuild;
-    }
-    return localBuild;
+  const dataBuild = join(resolveDataDir(), 'ui');
+  const hasData = existsSync(join(dataBuild, 'index.js'));
+  // resolveLocalUiBuild()'s env/resourcesPath candidates only check the dir
+  // exists, not that it holds a runnable build — require index.js before trusting it.
+  const bundledRaw = resolveLocalUiBuild();
+  const bundled = bundledRaw && existsSync(join(bundledRaw, 'index.js')) ? bundledRaw : null;
+
+  if (hasData && bundled) {
+    const dataVer = readUiBuildVersion(dataBuild);
+    const bundledVer = readUiBuildVersion(bundled);
+    // data/ui wins only when we can prove it's strictly newer.
+    if (dataVer && bundledVer && compareVersionTags(dataVer, bundledVer) > 0) return dataBuild;
+    return bundled;
   }
-
-  if (localBuild) return localBuild;
-  return stateBuild;
+  if (hasData) return dataBuild;
+  if (bundled) return bundled;
+  return dataBuild; // nothing present yet → caller triggers seedUiBuild
 }
 
 /**
- * Install the UI build to OP_HOME/state/ui/.
+ * Install the UI build to OP_HOME/data/ui/.
  *
  * Copies from local packages/ui/build/ when running from source,
  * otherwise downloads ui-build.tar.gz from the GitHub release.
  * Called during install and update; always replaces existing content.
  *
- * state/ui/ is automatically included in backups because
- * backupOpenPalmHome() copies all of OP_HOME/state/.
+ * data/ui/ is automatically included in backups because
+ * backupOpenPalmHome() copies all of OP_HOME/data/.
  */
 /** SHA-256 hex digest of arbitrary bytes. */
 function sha256Hex(data: Uint8Array): string {
@@ -241,21 +293,14 @@ function parseChecksumsFile(content: string): Map<string, string> {
   return map;
 }
 
-export function readCurrentUiBuildVersion(stateDir: string): string | null {
-  const versionFile = join(stateDir, 'ui', 'version.txt');
-  if (!existsSync(versionFile)) return null;
-  return readFileSync(versionFile, 'utf-8').trim() || null;
-}
-
-export async function seedUiBuild(repoRef: string, stateDir: string, options?: { forceRemote?: boolean }): Promise<void> {
-  const uiDir = join(stateDir, 'ui');
+export async function seedUiBuild(repoRef: string, dataDir: string, options?: { forceRemote?: boolean }): Promise<void> {
+  const uiDir = join(dataDir, 'ui');
   mkdirSync(uiDir, { recursive: true });
 
   const local = options?.forceRemote ? null : resolveLocalUiBuild();
   if (local) {
     logger.debug('seeding UI build from local source', { src: local });
     copyTree(local, uiDir);
-    writeFileSync(join(uiDir, 'version.txt'), repoRef.replace(/^v/, ''));
     return;
   }
 
@@ -264,7 +309,7 @@ export async function seedUiBuild(repoRef: string, stateDir: string, options?: {
   const checksumUrl  = `${base}/checksums-sha256.txt`;
   logger.debug('downloading UI build', { url: tarballUrl });
 
-  const tmpTar = join(stateDir, '.ui-build.tar.gz.tmp');
+  const tmpTar = join(dataDir, '.ui-build.tar.gz.tmp');
   try {
     // Download tarball and checksums file in parallel (checksums best-effort)
     const [tarRes, csRes] = await Promise.all([
@@ -295,7 +340,6 @@ export async function seedUiBuild(repoRef: string, stateDir: string, options?: {
     mkdirSync(uiDir, { recursive: true });
     // Cross-platform extraction via the `tar` npm package — no shell dependency
     await tarExtract({ file: tmpTar, cwd: uiDir, strip: 1 });
-    writeFileSync(join(uiDir, 'version.txt'), repoRef.replace(/^v/, ''));
   } finally {
     rmSync(tmpTar, { force: true });
   }
@@ -305,14 +349,45 @@ export async function seedUiBuild(repoRef: string, stateDir: string, options?: {
 
 const GITHUB_API = 'https://api.github.com';
 
-/** Returns 1 if a > b, -1 if a < b, 0 if equal. Strips leading 'v'. */
+/** Returns 1 if a > b, -1 if a < b, 0 if equal. Strips leading 'v'. Handles pre-release tags. */
 function compareVersionTags(a: string, b: string): number {
-  const parse = (v: string) => v.replace(/^v/, '').split('.').map(Number);
-  const [aM, am, ap] = parse(a);
-  const [bM, bm, bp] = parse(b);
+  const parse = (v: string): [number, number, number, string | null] => {
+    const clean = v.replace(/^v/, '');
+    const dashIdx = clean.indexOf('-');
+    const main = dashIdx === -1 ? clean : clean.slice(0, dashIdx);
+    const pre = dashIdx === -1 ? null : clean.slice(dashIdx + 1);
+    const parts = main.split('.').map(Number);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0, pre];
+  };
+  const comparePre = (x: string, y: string): number => {
+    const xp = x.split('.');
+    const yp = y.split('.');
+    for (let i = 0; i < Math.max(xp.length, yp.length); i++) {
+      if (i >= xp.length) return -1;
+      if (i >= yp.length) return 1;
+      const xn = Number(xp[i]);
+      const yn = Number(yp[i]);
+      const xIsNum = !isNaN(xn);
+      const yIsNum = !isNaN(yn);
+      if (xIsNum && yIsNum) {
+        if (xn !== yn) return xn > yn ? 1 : -1;
+      } else if (xIsNum !== yIsNum) {
+        return xIsNum ? -1 : 1; // numeric < alphanumeric per semver
+      } else {
+        if (xp[i] !== yp[i]) return xp[i]! > yp[i]! ? 1 : -1;
+      }
+    }
+    return 0;
+  };
+  const [aM, am, ap, aPre] = parse(a);
+  const [bM, bm, bp, bPre] = parse(b);
   if (aM !== bM) return aM > bM ? 1 : -1;
   if (am !== bm) return am > bm ? 1 : -1;
   if (ap !== bp) return ap > bp ? 1 : -1;
+  // Same numeric version: stable > pre-release (semver spec)
+  if (aPre === null && bPre !== null) return 1;
+  if (aPre !== null && bPre === null) return -1;
+  if (aPre !== null && bPre !== null) return comparePre(aPre, bPre);
   return 0;
 }
 
@@ -326,15 +401,15 @@ export interface UiBuildUpdateResult {
  * Check GitHub for a newer UI build and apply it if one exists.
  *
  * When an update is available:
- *   1. Move state/ui/ → state/backups/ui-{timestamp}/ (preserves the old build)
- *   2. Download ui-build.tar.gz from the latest release and extract to state/ui/
+ *   1. Move data/ui/ → data/backups/ui-{timestamp}/ (preserves the old build)
+ *   2. Download ui-build.tar.gz from the latest release and extract to data/ui/
  *
  * Non-fatal: any network or extraction error returns { updated: false, error }.
  * The caller should proceed with the existing build on failure.
  */
 export async function checkAndUpdateUiBuild(
   currentVersion: string,
-  stateDir: string,
+  dataDir: string,
 ): Promise<UiBuildUpdateResult> {
   try {
     const res = await fetch(
@@ -365,15 +440,15 @@ export async function checkAndUpdateUiBuild(
     }
 
     // Back up the existing UI build before replacing it
-    const uiDir = join(stateDir, 'ui');
+    const uiDir = join(dataDir, 'ui');
     if (existsSync(join(uiDir, 'index.js'))) {
-      const backupDir = join(stateDir, 'backups', `ui-${Date.now()}`);
-      mkdirSync(join(stateDir, 'backups'), { recursive: true });
+      const backupDir = join(resolveBackupsDir(), `ui-${Date.now()}`);
+      mkdirSync(resolveBackupsDir(), { recursive: true });
       renameSync(uiDir, backupDir);
       logger.debug('backed up UI build before update', { backup: backupDir });
     }
 
-    await seedUiBuild(latestTag, stateDir);
+    await seedUiBuild(latestTag, dataDir);
     logger.debug('UI build updated', { from: currentVersion, to: latestVersion });
 
     return { updated: true, latestVersion };

package/src/control-plane/validate.ts

@@ -2,26 +2,26 @@
  * Runtime configuration validation for the OpenPalm control plane.
  *
  * Validation is a presence check on the canonical env keys we expect in
- * the live config/stack/stack.env file. The
+ * the live config/stack files. The
  * historical schema files and external validation binary were retired in
  * #391; everything advisory is surfaced as a non-blocking warning. The
  * function never shells out and never reads schemas.
  */
 import { existsSync } from "node:fs";
-import { readStackEnv } from "./secrets.js";
+import { readStackRuntimeEnv } from "./secrets.js";
 import { getCoreSecretMappings } from "./secret-mappings.js";
 import type { ControlPlaneState } from "./types.js";
 
 // Stack-scoped env keys that must always exist and carry a non-empty value
 // for the platform to boot. Keep this list small — anything optional
 // belongs in the warning bucket instead.
-const REQUIRED_STACK_KEYS = ["OP_UI_LOGIN_PASSWORD"] as const;
+const REQUIRED_SECRET_KEYS = ["OP_UI_LOGIN_PASSWORD"] as const;
 
 /**
  * Validate the live configuration files.
  *
  * Checks:
- * 1. config/stack/stack.env exists and carries every required key with a
+ * 1. knowledge/env/stack.env exists and carries every required key with a
  *    non-empty value.
  * 2. Every secret env key in getCoreSecretMappings() is present (key only
  *    — blank values are warned about, never erred on, because operators
@@ -38,32 +38,30 @@ export async function validateProposedState(state: ControlPlaneState): Promise<{
   const errors: string[] = [];
   const warnings: string[] = [];
 
-  const stackEnvPath = `${state.stackDir}/stack.env`;
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
 
   if (!existsSync(stackEnvPath)) {
     errors.push(`ERROR: stack env file missing at ${stackEnvPath}`);
     return { ok: false, errors, warnings };
   }
 
-  const stackEnv = readStackEnv(state.stackDir);
-  const userEnv: Record<string, string> = {};
+  const runtimeEnv = readStackRuntimeEnv(state.stackDir);
 
-  for (const key of REQUIRED_STACK_KEYS) {
-    const value = stackEnv[key];
+  for (const key of REQUIRED_SECRET_KEYS) {
+    const value = runtimeEnv[key];
     if (!value || value.trim().length === 0) {
-      errors.push(`ERROR: required key ${key} is missing or empty in config/stack/stack.env`);
+      errors.push(`ERROR: required secret ${key} is missing or empty in knowledge/secrets/${key.toLowerCase()}`);
     }
   }
 
   // Every canonical secret should at least appear as a key somewhere in
   // the env files so the operator sees the slot. Missing slots warn (not
   // error) since not every provider is in use on every install.
-  for (const mapping of getCoreSecretMappings(stackEnv)) {
-    const inStack = Object.prototype.hasOwnProperty.call(stackEnv, mapping.envKey);
-    const inUser = Object.prototype.hasOwnProperty.call(userEnv, mapping.envKey);
-    if (!inStack && !inUser) {
+  for (const mapping of getCoreSecretMappings(runtimeEnv)) {
+    const inRuntime = Object.prototype.hasOwnProperty.call(runtimeEnv, mapping.envKey);
+    if (!inRuntime) {
       warnings.push(
-        `WARN: ${mapping.envKey} (akm ${mapping.secretKey}) is not declared in config/stack/stack.env`,
+        `WARN: ${mapping.envKey} (akm ${mapping.secretKey}) is not declared in knowledge/secrets/${mapping.envKey.toLowerCase()}`,
       );
     }
   }