@openpalm/lib 0.10.2 → 0.11.0-beta.2

package/src/control-plane/registry.ts

@@ -1,7 +1,7 @@
 /**
  * Registry catalog discovery and refresh.
  *
- * `OP_HOME/registry` is the only persistent catalog location.
+ * `OP_HOME/state/registry` is the only persistent catalog location.
  * Install seeds it once; refresh replaces it explicitly.
  */
 import { cpSync, existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -46,10 +46,10 @@ export function isValidComponentName(name: string): boolean {
 
 const DEFAULT_REPO = 'itlackey/openpalm';
 
-export interface RegistryConfig {
+export type RegistryConfig = {
   repoUrl: string;
   branch: string;
-}
+};
 
 export function getRegistryConfig(): RegistryConfig {
   return {
@@ -63,7 +63,7 @@ export type RegistryAutomationEntry = {
   type: 'automation';
   description: string;
   schedule: string;
-  ymlContent: string;
+  content: string;
 };
 
 export type RegistryComponentEntry = {
@@ -95,7 +95,10 @@ function countValidAddons(rootDir: string): number {
   return readdirSync(addonsDir, { withFileTypes: true }).filter((entry) => {
     if (!entry.isDirectory() || !isValidComponentName(entry.name)) return false;
     const addonDir = join(addonsDir, entry.name);
-    return existsSync(join(addonDir, 'compose.yml')) && existsSync(join(addonDir, '.env.schema'));
+    // An addon is valid if it has a compose.yml. Overlay-only addons that only
+    // patch existing services (ports, env, volumes) do not need an .env.schema;
+    // full addons that introduce services and env vars do.
+    return existsSync(join(addonDir, 'compose.yml'));
   }).length;
 }
 
@@ -103,8 +106,8 @@ function countValidAutomations(rootDir: string): number {
   const automationsDir = join(rootDir, 'automations');
   if (!existsSync(automationsDir)) return 0;
   return readdirSync(automationsDir).filter((file) => {
-    if (!file.endsWith('.yml')) return false;
-    return isValidComponentName(file.replace(/\.yml$/, ''));
+    if (!file.endsWith('.md')) return false;
+    return isValidComponentName(file.replace(/\.md$/, ''));
   }).length;
 }
 
@@ -123,8 +126,8 @@ export function verifyRegistryCatalog(rootDir = resolveRegistryDir()): RegistryC
 }
 
 export function materializeRegistryCatalog(sourceRoot: string): string {
-  const sourceAddonsDir = join(sourceRoot, '.openpalm', 'registry', 'addons');
-  const sourceAutomationsDir = join(sourceRoot, '.openpalm', 'registry', 'automations');
+  const sourceAddonsDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'addons');
+  const sourceAutomationsDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'automations');
   const tempRoot = mkdtempSync(join(tmpdir(), 'openpalm-registry-materialize-'));
 
   try {
@@ -184,37 +187,46 @@ export function discoverRegistryComponents(): Record<string, RegistryComponentEn
     if (!entry.isDirectory() || !VALID_NAME_RE.test(entry.name)) continue;
     const addonDir = join(addonsDir, entry.name);
     const composeFile = join(addonDir, 'compose.yml');
+    if (!existsSync(composeFile)) continue;
+
+    // .env.schema is optional: overlay-only addons (e.g. a port toggle) do
+    // not introduce new env vars, so they ship just compose.yml.
     const schemaFile = join(addonDir, '.env.schema');
-    if (!existsSync(composeFile) || !existsSync(schemaFile)) continue;
+    const schema = existsSync(schemaFile) ? readFileSync(schemaFile, 'utf-8') : '';
 
     result[entry.name] = {
       compose: readFileSync(composeFile, 'utf-8'),
-      schema: readFileSync(schemaFile, 'utf-8'),
+      schema,
     };
   }
 
   return result;
 }
 
-export function discoverRegistryAutomations(): RegistryAutomationEntry[] {
+export function discoverRegistryAutomations(stashDir: string): RegistryAutomationEntry[] {
   const automationsDir = resolveRegistryAutomationsDir();
   if (!existsSync(automationsDir)) return [];
 
   return readdirSync(automationsDir)
-    .filter((file) => file.endsWith('.yml'))
+    .filter((file) => file.endsWith('.md'))
     .map((file) => {
-      const name = file.replace(/\.yml$/, '');
+      const name = file.replace(/\.md$/, '');
       if (!VALID_NAME_RE.test(name)) return null;
 
-      const ymlContent = readFileSync(join(automationsDir, file), 'utf-8');
+      const content = readFileSync(join(automationsDir, file), 'utf-8');
       let description = '';
       let schedule = '';
 
+      // Extract frontmatter metadata (between --- delimiters)
       try {
-        const parsed = parseYaml(ymlContent);
-        if (parsed && typeof parsed === 'object') {
-          description = parsed.description ?? '';
-          schedule = parsed.schedule ?? '';
+        const after = content.startsWith('---') ? content.slice(3) : '';
+        const end = after.indexOf('\n---');
+        if (end !== -1) {
+          const parsed = parseYaml(after.slice(0, end));
+          if (parsed && typeof parsed === 'object') {
+            description = (parsed as Record<string, unknown>).description as string ?? '';
+            schedule = (parsed as Record<string, unknown>).schedule as string ?? '';
+          }
         }
       } catch {
         // best-effort metadata extraction
@@ -225,7 +237,7 @@ export function discoverRegistryAutomations(): RegistryAutomationEntry[] {
         type: 'automation' as const,
         description,
         schedule,
-        ymlContent,
+        content,
       };
     })
     .filter((entry): entry is RegistryAutomationEntry => entry !== null);
@@ -233,9 +245,9 @@ export function discoverRegistryAutomations(): RegistryAutomationEntry[] {
 
 export function getRegistryAutomation(name: string): string | null {
   if (!VALID_NAME_RE.test(name)) return null;
-  const ymlPath = join(resolveRegistryAutomationsDir(), `${name}.yml`);
-  if (!existsSync(ymlPath)) return null;
-  return readFileSync(ymlPath, 'utf-8');
+  const mdPath = join(resolveRegistryAutomationsDir(), `${name}.md`);
+  if (!existsSync(mdPath)) return null;
+  return readFileSync(mdPath, 'utf-8');
 }
 
 export function getRegistryAddonConfig(homeDir: string, name: string): RegistryAddonConfig {
@@ -243,11 +255,14 @@ export function getRegistryAddonConfig(homeDir: string, name: string): RegistryA
     throw new Error(`Invalid addon name: ${name}`);
   }
 
-  const schemaPath = `registry/addons/${name}/.env.schema`;
+  // Overlay-only addons (compose.yml only, no .env.schema) have no env vars
+  // to render, so the schema reads as an empty string.
+  const schemaPath = `state/registry/addons/${name}/.env.schema`;
+  const schemaFile = join(homeDir, schemaPath);
   return {
     schemaPath,
-    userEnvPath: 'vault/user/user.env',
-    envSchema: readFileSync(join(homeDir, schemaPath), 'utf-8'),
+    userEnvPath: 'config/stack/stack.env',
+    envSchema: existsSync(schemaFile) ? readFileSync(schemaFile, 'utf-8') : '',
   };
 }
 
@@ -261,7 +276,7 @@ export function listAvailableAddonIds(): string[] {
 }
 
 export function listEnabledAddonIds(homeDir: string): string[] {
-  const addonsDir = join(homeDir, 'stack', 'addons');
+  const addonsDir = join(homeDir, 'config', 'stack', 'addons');
   if (!existsSync(addonsDir)) return [];
 
   return readdirSync(addonsDir, { withFileTypes: true })
@@ -274,19 +289,21 @@ function copyAddonFromRegistry(homeDir: string, name: string): void {
   if (!VALID_NAME_RE.test(name)) throw new Error(`Invalid addon name: ${name}`);
 
   const sourceDir = join(resolveRegistryAddonsDir(), name);
-  if (!existsSync(join(sourceDir, 'compose.yml')) || !existsSync(join(sourceDir, '.env.schema'))) {
+  // compose.yml is the only required file. Overlay-only addons may omit
+  // .env.schema entirely.
+  if (!existsSync(join(sourceDir, 'compose.yml'))) {
     throw new Error(`Addon "${name}" not found in registry`);
   }
 
-  const targetDir = join(homeDir, 'stack', 'addons', name);
+  const targetDir = join(homeDir, 'config', 'stack', 'addons', name);
   rmSync(targetDir, { recursive: true, force: true });
-  mkdirSync(join(homeDir, 'stack', 'addons'), { recursive: true });
+  mkdirSync(join(homeDir, 'config', 'stack', 'addons'), { recursive: true });
   cpSync(sourceDir, targetDir, { recursive: true });
 }
 
 function removeEnabledAddon(homeDir: string, name: string): void {
   if (!VALID_NAME_RE.test(name)) throw new Error(`Invalid addon name: ${name}`);
-  rmSync(join(homeDir, 'stack', 'addons', name), { recursive: true, force: true });
+  rmSync(join(homeDir, 'config', 'stack', 'addons', name), { recursive: true, force: true });
 }
 
 function readAddonServiceNames(composePath: string): string[] {
@@ -310,8 +327,8 @@ export function getAddonServiceNames(homeDir: string, name: string): string[] {
   if (!VALID_NAME_RE.test(name)) throw new Error(`Invalid addon name: ${name}`);
 
   const composeCandidates = [
-    join(homeDir, "stack", "addons", name, "compose.yml"),
-    join(homeDir, "registry", "addons", name, "compose.yml"),
+    join(homeDir, "config", "stack", "addons", name, "compose.yml"),
+    join(homeDir, "state", "registry", "addons", name, "compose.yml"),
   ];
 
   for (const composePath of composeCandidates) {
@@ -325,8 +342,8 @@ export function getAddonServiceNames(homeDir: string, name: string): string[] {
 export function enableAddon(homeDir: string, name: string): MutationResult {
   try {
     copyAddonFromRegistry(homeDir, name);
-    // Pre-create the addon data directory so Docker doesn't create it as root
-    mkdirSync(join(homeDir, 'data', name), { recursive: true });
+    // Pre-create the addon services directory so Docker doesn't create it as root
+    mkdirSync(join(homeDir, 'services', name), { recursive: true });
     return { ok: true };
   } catch (error) {
     return { ok: false, error: error instanceof Error ? error.message : String(error) };
@@ -342,7 +359,7 @@ export function disableAddonByName(homeDir: string, name: string): MutationResul
   }
 }
 
-export function setAddonEnabled(homeDir: string, vaultDir: string, name: string, enabled: boolean): AddonMutationResult {
+export function setAddonEnabled(homeDir: string, stackDir: string, name: string, enabled: boolean): AddonMutationResult {
   if (!VALID_NAME_RE.test(name)) {
     return { ok: false, error: `Invalid addon name: ${name}` };
   }
@@ -367,9 +384,9 @@ export function setAddonEnabled(homeDir: string, vaultDir: string, name: string,
   if (!mutation.ok) return mutation;
 
   if (enabled) {
-    const composePath = join(homeDir, "stack", "addons", name, "compose.yml");
+    const composePath = join(homeDir, "config", "stack", "addons", name, "compose.yml");
     if (isChannelAddon(composePath)) {
-      writeChannelSecrets(vaultDir, { [name]: randomHex(16) });
+      writeChannelSecrets(stackDir, { [name]: randomHex(16) });
     }
   }
 
@@ -381,38 +398,42 @@ export function setAddonEnabled(homeDir: string, vaultDir: string, name: string,
   };
 }
 
-export function installAutomationFromRegistry(name: string, configDir: string): MutationResult {
+export function installAutomationFromRegistry(name: string, stashDir: string): MutationResult {
   if (!VALID_NAME_RE.test(name)) {
     return { ok: false, error: `Invalid automation name: ${name}` };
   }
 
-  const automationYml = getRegistryAutomation(name);
-  if (!automationYml) {
+  const markdownContent = getRegistryAutomation(name);
+  if (!markdownContent) {
     return { ok: false, error: `Automation "${name}" not found in registry` };
   }
 
-  const automationsDir = join(configDir, 'automations');
-  mkdirSync(automationsDir, { recursive: true });
+  const tasksDir = join(stashDir, 'tasks');
+  mkdirSync(tasksDir, { recursive: true });
 
-  const ymlPath = join(automationsDir, `${name}.yml`);
-  if (existsSync(ymlPath)) {
+  const mdPath = join(tasksDir, `${name}.md`);
+  if (existsSync(mdPath)) {
     return { ok: false, error: `Automation "${name}" is already installed` };
   }
 
-  writeFileSync(ymlPath, automationYml);
+  writeFileSync(mdPath, markdownContent);
+  // The assistant container's 60-second akm tasks sync loop picks up the new
+  // file from the shared stash mount and registers it with OS cron.
   return { ok: true };
 }
 
-export function uninstallAutomation(name: string, configDir: string): MutationResult {
+export function uninstallAutomation(name: string, stashDir: string): MutationResult {
   if (!VALID_NAME_RE.test(name)) {
     return { ok: false, error: `Invalid automation name: ${name}` };
   }
 
-  const ymlPath = join(configDir, 'automations', `${name}.yml`);
-  if (!existsSync(ymlPath)) {
+  const mdPath = join(stashDir, 'tasks', `${name}.md`);
+  if (!existsSync(mdPath)) {
     return { ok: false, error: `Automation "${name}" is not installed` };
   }
 
-  rmSync(ymlPath, { force: true });
+  rmSync(mdPath, { force: true });
+  // The assistant container's 60-second akm tasks sync will notice the file
+  // is gone and deregister it from OS cron on next sync.
   return { ok: true };
 }

package/src/control-plane/rollback.ts

@@ -11,11 +11,12 @@ import type { ControlPlaneState } from "./types.js";
 import { resolveRollbackDir } from "./home.js";
 
 /** Files that are tracked for rollback (relative to homeDir).
- *  Only vault/stack/ files are included — vault/user/ and config/ are
- *  user-owned and never overwritten by lifecycle operations. */
+ *  Only config/ system files are included — user-editable config files
+ *  are never overwritten by lifecycle operations. */
 const SNAPSHOT_FILES = [
-  "vault/stack/stack.env",
-  "vault/stack/guardian.env",
+  "config/stack/stack.env",
+  "config/stack/guardian.env",
+  "config/auth.json",
 ];
 
 /**
@@ -43,12 +44,12 @@ export function snapshotCurrentState(state: ControlPlaneState): void {
     safeCopy(src, dest);
   }
 
-  // Snapshot stack/core.compose.yml
-  const coreCompose = join(state.homeDir, "stack/core.compose.yml");
-  safeCopy(coreCompose, join(rollbackDir, "stack/core.compose.yml"));
+  // Snapshot config/stack/core.compose.yml
+  const coreCompose = join(state.homeDir, "config/stack/core.compose.yml");
+  safeCopy(coreCompose, join(rollbackDir, "config/stack/core.compose.yml"));
 
-  // Snapshot stack/addons/*/compose.yml
-  const addonsDir = join(state.homeDir, "stack/addons");
+  // Snapshot config/stack/addons/*/compose.yml
+  const addonsDir = join(state.homeDir, "config/stack/addons");
   if (existsSync(addonsDir)) {
     for (const entry of readdirSync(addonsDir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
@@ -56,7 +57,7 @@ export function snapshotCurrentState(state: ControlPlaneState): void {
         if (existsSync(addonCompose)) {
           safeCopy(
             addonCompose,
-            join(rollbackDir, "stack/addons", entry.name, "compose.yml"),
+            join(rollbackDir, "config/stack/addons", entry.name, "compose.yml"),
           );
         }
       }
@@ -87,14 +88,14 @@ export function restoreSnapshot(state: ControlPlaneState): void {
     safeCopy(src, dest);
   }
 
-  // Restore stack/core.compose.yml
-  const srcCoreCompose = join(rollbackDir, "stack/core.compose.yml");
+  // Restore config/stack/core.compose.yml
+  const srcCoreCompose = join(rollbackDir, "config/stack/core.compose.yml");
   if (existsSync(srcCoreCompose)) {
-    safeCopy(srcCoreCompose, join(state.homeDir, "stack/core.compose.yml"));
+    safeCopy(srcCoreCompose, join(state.homeDir, "config/stack/core.compose.yml"));
   }
 
-  // Restore stack/addons/*/compose.yml
-  const srcAddons = join(rollbackDir, "stack/addons");
+  // Restore config/stack/addons/*/compose.yml
+  const srcAddons = join(rollbackDir, "config/stack/addons");
   if (existsSync(srcAddons)) {
     for (const entry of readdirSync(srcAddons, { withFileTypes: true })) {
       if (entry.isDirectory()) {
@@ -102,7 +103,7 @@ export function restoreSnapshot(state: ControlPlaneState): void {
         if (existsSync(srcAddonCompose)) {
           safeCopy(
             srcAddonCompose,
-            join(state.homeDir, "stack/addons", entry.name, "compose.yml"),
+            join(state.homeDir, "config/stack/addons", entry.name, "compose.yml"),
           );
         }
       }