openpalm 0.10.0 → 0.10.2

package/README.md

@@ -19,6 +19,10 @@ The admin container is optional. Use `--with-admin` to enable the admin addon ov
 | `openpalm install` | Bootstrap `~/.openpalm/`, download assets, run setup wizard, start core services |
 | `openpalm uninstall` | Stop and remove the stack (preserves config and data) |
 | `openpalm update` | Pull latest images and recreate containers |
+| `openpalm upgrade` | Alias for `update` |
+| `openpalm self-update` | Replace the installed CLI binary with the latest release build |
+| `openpalm addon <enable|disable|list>` | Manage registry addons directly from the CLI |
+| `openpalm admin <enable|disable|status>` | Manage the admin addon directly from the CLI |
 | `openpalm start [svc...]` | Start all or named services |
 | `openpalm start --with-admin` | Start all services including admin UI and docker-socket-proxy |
 | `openpalm stop [svc...]` | Stop all or named services |
@@ -31,16 +35,19 @@ The admin container is optional. Use `--with-admin` to enable the admin addon ov
 
 ### Install options
 
-`--force` skip "already installed" check, `--version TAG` install a specific ref (default: current CLI version), `--no-start` prepare files only, `--no-open` skip browser launch.
+`--force` skip "already installed" check and create a backup of the current `OP_HOME`, `--version TAG` install a specific ref (default: current CLI version), `--no-start` prepare files only, `--no-open` skip browser launch.
 
 ### Admin addon
 
 Admin and docker-socket-proxy start only when explicitly requested:
 
 ```bash
-openpalm start --with-admin     # Start core + admin profile
-openpalm start admin            # Start admin service specifically
-openpalm stop admin             # Stop admin service specifically
+openpalm admin enable           # Enable the admin addon and start its services
+openpalm admin disable          # Stop and disable the admin addon
+openpalm admin status           # Show whether the admin addon is enabled
+openpalm addon enable chat      # Enable a registry addon and start its services
+openpalm addon disable chat     # Stop and disable a registry addon
+openpalm addon list             # Show available addons and whether they are enabled
 ```
 
 ## Setup Wizard
@@ -79,4 +86,4 @@ bun run start -- install --no-start
 bun test
 ```
 
-See also: [`scripts/setup.sh`](../../scripts/setup.sh) (shell-based installer).
+See also: [`scripts/setup.sh`](../../scripts/setup.sh) and [`scripts/setup.ps1`](../../scripts/setup.ps1). Both installers support `--cli-only` when you only want to install or refresh the CLI binary without touching the stack or `OP_HOME`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpalm",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "type": "module",
   "license": "MPL-2.0",
   "description": "OpenPalm CLI — install and manage a self-hosted OpenPalm stack",
@@ -26,7 +26,7 @@
     "build:windows-arm64": "bun build src/main.ts --compile --target=bun-windows-arm64 --outfile dist/openpalm-cli-windows-arm64.exe"
   },
   "dependencies": {
-    "@openpalm/lib": ">=0.10.0 <1.0.0",
+    "@openpalm/lib": ">=0.10.1 <1.0.0",
     "citty": "^0.2.1",
     "yaml": "^2.8.0"
   }

package/src/commands/addon.ts

@@ -0,0 +1,130 @@
+import { defineCommand } from 'citty';
+import {
+  getAddonServiceNames,
+  listAvailableAddonIds,
+  listEnabledAddonIds,
+  setAddonEnabled,
+} from '@openpalm/lib';
+import { ensureValidState } from '../lib/cli-state.ts';
+import { fullComposeArgs, runComposeWithPreflight } from '../lib/cli-compose.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+
+function requireKnownAddon(name: string): void {
+  const available = listAvailableAddonIds();
+  const hint = available.length > 0 ? ` Run \`openpalm addon list\` to see the available addons.` : '';
+  if (!available.includes(name)) {
+    throw new Error(`Addon "${name}" is not available. Known addons: ${available.join(', ') || '(none)'}.${hint}`);
+  }
+}
+
+export async function runAddonListAction(): Promise<void> {
+  const state = ensureValidState();
+  const enabled = new Set(listEnabledAddonIds(state.homeDir));
+  const available = listAvailableAddonIds();
+
+  if (available.length === 0) {
+    console.log('No registry addons are available.');
+    return;
+  }
+
+  for (const name of available) {
+    console.log(`${enabled.has(name) ? '[enabled]' : '[disabled]'} ${name}`);
+  }
+}
+
+export async function runAddonEnableAction(name: string): Promise<void> {
+  requireKnownAddon(name);
+  const state = ensureValidState();
+  const mutation = setAddonEnabled(state.homeDir, state.vaultDir, name, true);
+  if (!mutation.ok) throw new Error(mutation.error);
+
+  if (!mutation.changed) {
+    console.log(`Addon "${name}" is already enabled.`);
+    return;
+  }
+
+  console.log(`Enabled addon "${name}".`);
+
+  if (mutation.services.length === 0) return;
+
+  try {
+    const nextState = ensureValidState();
+    await runComposeWithPreflight(nextState, ['up', '-d', ...mutation.services]);
+    console.log(`Started services: ${mutation.services.join(', ')}`);
+  } catch (err) {
+    console.warn(
+      `Warning: addon "${name}" was enabled but its services were not started automatically: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export async function runAddonDisableAction(name: string): Promise<void> {
+  requireKnownAddon(name);
+  const state = ensureValidState();
+  const services = getAddonServiceNames(state.homeDir, name);
+  const wasEnabled = listEnabledAddonIds(state.homeDir).includes(name);
+
+  if (wasEnabled && services.length > 0) {
+    try {
+      await runDockerCompose([...fullComposeArgs(state), 'stop', ...services]);
+      console.log(`Stopped services: ${services.join(', ')}`);
+    } catch (err) {
+      console.warn(
+        `Warning: failed to stop services for addon "${name}" before disabling it: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  const mutation = setAddonEnabled(state.homeDir, state.vaultDir, name, false);
+  if (!mutation.ok) throw new Error(mutation.error);
+
+  if (!mutation.changed) {
+    console.log(`Addon "${name}" is already disabled.`);
+    return;
+  }
+
+  console.log(`Disabled addon "${name}".`);
+}
+
+const enableCmd = defineCommand({
+  meta: { name: 'enable', description: 'Enable a registry addon' },
+  args: {
+    name: { type: 'positional', description: 'Addon name', required: true },
+  },
+  async run({ args }) {
+    const name = String(args._?.[0] ?? '').trim();
+    if (!name) throw new Error('Addon name is required. Run `openpalm addon list` to see the available addons.');
+    await runAddonEnableAction(name);
+  },
+});
+
+const disableCmd = defineCommand({
+  meta: { name: 'disable', description: 'Disable a registry addon' },
+  args: {
+    name: { type: 'positional', description: 'Addon name', required: true },
+  },
+  async run({ args }) {
+    const name = String(args._?.[0] ?? '').trim();
+    if (!name) throw new Error('Addon name is required. Run `openpalm addon list` to see the available addons.');
+    await runAddonDisableAction(name);
+  },
+});
+
+const listCmd = defineCommand({
+  meta: { name: 'list', description: 'List registry addons and whether they are enabled' },
+  async run() {
+    await runAddonListAction();
+  },
+});
+
+export default defineCommand({
+  meta: {
+    name: 'addon',
+    description: 'Enable, disable, or list registry addons',
+  },
+  subCommands: {
+    list: listCmd,
+    enable: enableCmd,
+    disable: disableCmd,
+  },
+});

package/src/commands/admin.ts

@@ -0,0 +1,43 @@
+import { defineCommand } from 'citty';
+import { listEnabledAddonIds } from '@openpalm/lib';
+import { ensureValidState } from '../lib/cli-state.ts';
+import { runAddonDisableAction, runAddonEnableAction } from './addon.ts';
+
+async function runAdminStatusAction(): Promise<void> {
+  const state = ensureValidState();
+  const enabled = listEnabledAddonIds(state.homeDir).includes('admin');
+  console.log(enabled ? 'Admin addon is enabled.' : 'Admin addon is disabled.');
+}
+
+const enableCmd = defineCommand({
+  meta: { name: 'enable', description: 'Enable the admin addon' },
+  async run() {
+    await runAddonEnableAction('admin');
+  },
+});
+
+const disableCmd = defineCommand({
+  meta: { name: 'disable', description: 'Disable the admin addon' },
+  async run() {
+    await runAddonDisableAction('admin');
+  },
+});
+
+const statusCmd = defineCommand({
+  meta: { name: 'status', description: 'Show whether the admin addon is enabled' },
+  async run() {
+    await runAdminStatusAction();
+  },
+});
+
+export default defineCommand({
+  meta: {
+    name: 'admin',
+    description: 'Enable, disable, or inspect the admin addon',
+  },
+  subCommands: {
+    enable: enableCmd,
+    disable: disableCmd,
+    status: statusCmd,
+  },
+});

package/src/commands/install.ts

@@ -7,6 +7,7 @@ import { resolveOpenPalmHome, resolveConfigDir, resolveVaultDir, resolveDataDir
 import { ensureSecrets, ensureStackEnv, resolveRequestedImageTag } from '../lib/env.ts';
 import { ensureDirectoryTree, seedOpenPalmDir, openBrowser, runDockerCompose, runDockerComposeCapture } from '../lib/docker.ts';
 import {
+  backupOpenPalmHome,
   ensureOpenCodeConfig, ensureOpenCodeSystemConfig,
   performSetup,
   applyInstall,
@@ -136,6 +137,13 @@ export async function bootstrapInstall(options: InstallOptions): Promise<void> {
     throw new Error('OpenPalm appears to already be installed. Re-run install with --force to continue.');
   }
 
+  if (alreadyInstalled && options.force) {
+    const backupDir = backupOpenPalmHome(homeDir);
+    if (backupDir) {
+      console.log(`Backed up existing OP_HOME to ${backupDir}`);
+    }
+  }
+
   // ── Bootstrap files ────────────────────────────────────────────────────
   await prepareInstallFiles(homeDir, configDir, vaultDir, dataDir, workDir, options.version);
 

package/src/commands/self-update.ts

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { defineCommand } from 'citty';
+
+const REPO = 'itlackey/openpalm';
+
+function normalizeVersion(version: string): string {
+  return version.startsWith('v') ? version : `v${version}`;
+}
+
+async function resolveLatestVersion(): Promise<string> {
+  try {
+    const res = await fetch(`https://github.com/${REPO}/releases/latest`, {
+      redirect: 'manual',
+      signal: AbortSignal.timeout(10_000),
+    });
+    const match = (res.headers.get('location') ?? '').match(/\/tag\/(v[0-9]+\.[0-9]+\.[0-9]+[^\s]*)$/);
+    if (match?.[1]) return match[1];
+  } catch {
+    // fall through
+  }
+
+  throw new Error('Unable to resolve the latest OpenPalm release.');
+}
+
+export function resolveCliArtifactName(platform = process.platform, arch = process.arch): string {
+  if (platform === 'linux' && arch === 'x64') return 'openpalm-cli-linux-x64';
+  if (platform === 'linux' && arch === 'arm64') return 'openpalm-cli-linux-arm64';
+  if (platform === 'darwin' && arch === 'x64') return 'openpalm-cli-darwin-x64';
+  if (platform === 'darwin' && arch === 'arm64') return 'openpalm-cli-darwin-arm64';
+  if (platform === 'win32' && arch === 'x64') return 'openpalm-cli-windows-x64.exe';
+  if (platform === 'win32' && arch === 'arm64') return 'openpalm-cli-windows-arm64.exe';
+  throw new Error(`Unsupported platform for self-update: ${platform}/${arch}`);
+}
+
+export function canReplaceCurrentExecutable(execPath = process.execPath): boolean {
+  const execName = basename(execPath).toLowerCase();
+  return execName !== 'bun' && execName !== 'bun.exe';
+}
+
+function sha256Hex(content: Uint8Array): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function parseExpectedChecksum(checksums: string, artifact: string): string {
+  const line = checksums
+    .split('\n')
+    .map((entry) => entry.trim())
+    .find((entry) => entry.endsWith(` ${artifact}`) || entry.endsWith(`  ${artifact}`));
+
+  if (!line) throw new Error(`No published checksum found for ${artifact}.`);
+  const checksum = line.split(/\s+/)[0]?.trim();
+  if (!checksum) throw new Error(`Published checksum entry for ${artifact} is invalid.`);
+  return checksum;
+}
+
+function posixShellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+async function downloadVerifiedBinary(version: string, artifact: string): Promise<string> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'openpalm-self-update-'));
+  const artifactPath = join(tempDir, artifact);
+  const binaryUrl = `https://github.com/${REPO}/releases/download/${version}/${artifact}`;
+  const checksumUrl = `https://github.com/${REPO}/releases/download/${version}/checksums-sha256.txt`;
+
+  const [binaryRes, checksumRes] = await Promise.all([
+    fetch(binaryUrl, { signal: AbortSignal.timeout(60_000) }),
+    fetch(checksumUrl, { signal: AbortSignal.timeout(30_000) }),
+  ]);
+
+  if (!binaryRes.ok) throw new Error(`Failed to download ${artifact} (${binaryRes.status}).`);
+  if (!checksumRes.ok) throw new Error(`Failed to download release checksums (${checksumRes.status}).`);
+
+  const binaryBytes = new Uint8Array(await binaryRes.arrayBuffer());
+  const expected = parseExpectedChecksum(await checksumRes.text(), artifact);
+  const actual = sha256Hex(binaryBytes);
+  if (actual !== expected) {
+    throw new Error(`Checksum mismatch for ${artifact}: expected ${expected}, got ${actual}.`);
+  }
+
+  await Bun.write(artifactPath, binaryBytes);
+  await chmod(artifactPath, 0o755);
+  return artifactPath;
+}
+
+async function schedulePosixReplacement(sourcePath: string, targetPath: string): Promise<void> {
+  const scriptDir = await mkdtemp(join(tmpdir(), 'openpalm-self-update-script-'));
+  const scriptPath = join(scriptDir, 'replace.sh');
+  const script = [
+    '#!/usr/bin/env sh',
+    'set -eu',
+    'sleep 1',
+    `tmp=${posixShellQuote(sourcePath)}`,
+    `dest=${posixShellQuote(targetPath)}`,
+    'chmod +x "$tmp"',
+    'mv "$tmp" "$dest"',
+    `rm -rf ${posixShellQuote(scriptDir)}`,
+  ].join('\n') + '\n';
+
+  await Bun.write(scriptPath, script);
+  await chmod(scriptPath, 0o755);
+
+  const proc = Bun.spawn(['sh', scriptPath], {
+    stdout: 'ignore',
+    stderr: 'ignore',
+  });
+  proc.unref();
+}
+
+export default defineCommand({
+  meta: {
+    name: 'self-update',
+    description: 'Replace the installed OpenPalm CLI binary with the latest release build',
+  },
+  args: {
+    version: {
+      type: 'string',
+      description: 'Install a specific release tag instead of the latest release',
+    },
+  },
+  async run({ args }) {
+    if (process.platform === 'win32') {
+      throw new Error('Self-update is not supported on Windows yet because running executables cannot be replaced reliably while they are in use. Download and run setup.ps1 with --cli-only to refresh only the CLI binary.');
+    }
+
+    if (!canReplaceCurrentExecutable()) {
+      throw new Error('Self-update requires the compiled OpenPalm binary. Reinstall with setup.sh --cli-only instead.');
+    }
+
+    const version = args.version ? normalizeVersion(args.version) : await resolveLatestVersion();
+    const artifact = resolveCliArtifactName();
+    const executablePath = process.execPath;
+    const tempBinary = await downloadVerifiedBinary(version, artifact);
+
+    try {
+      await schedulePosixReplacement(tempBinary, executablePath);
+    } catch (err) {
+      await rm(dirname(tempBinary), { recursive: true, force: true }).catch(() => {});
+      throw err;
+    }
+
+    console.log(`Downloaded ${artifact} for ${version}.`);
+    console.log(`The CLI at ${executablePath} will be replaced after this command exits.`);
+  },
+});

package/src/commands/update.ts

@@ -5,17 +5,21 @@ import { ensureValidState } from '../lib/cli-state.ts';
 export default defineCommand({
   meta: {
     name: 'update',
-    description: 'Pull latest images and recreate containers',
+    description: 'Refresh stack assets, pull latest images, and recreate containers',
   },
   async run() {
-    const state = await ensureValidState();
-
-    console.log('Upgrading stack...');
-    const result = await performUpgrade(state);
-    console.log(`Image tag: ${result.namespace}/*:${result.imageTag}`);
-    if (result.assetsUpdated.length > 0) {
-      console.log(`Assets updated: ${result.assetsUpdated.join(', ')}`);
-    }
-    console.log('Update complete.');
+    await runUpgradeAction();
   },
 });
+
+export async function runUpgradeAction(): Promise<void> {
+  const state = await ensureValidState();
+
+  console.log('Upgrading stack...');
+  const result = await performUpgrade(state);
+  console.log(`Image tag: ${result.namespace}/*:${result.imageTag}`);
+  if (result.assetsUpdated.length > 0) {
+    console.log(`Assets updated: ${result.assetsUpdated.join(', ')}`);
+  }
+  console.log('Update complete.');
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,12 @@
+import { defineCommand } from 'citty';
+import { runUpgradeAction } from './update.ts';
+
+export default defineCommand({
+  meta: {
+    name: 'upgrade',
+    description: 'Refresh stack assets, pull latest images, and recreate containers',
+  },
+  async run() {
+    await runUpgradeAction();
+  },
+});

package/src/install-flow.test.ts

@@ -27,6 +27,7 @@ import { readStackSpec } from '@openpalm/lib';
 const REPO_ROOT = resolve(import.meta.dir, '../../..');
 const OPENPALM_SRC = join(REPO_ROOT, '.openpalm');
 const ASSISTANT_SRC = join(REPO_ROOT, 'core/assistant/opencode');
+const SKIP_INSTALL_FLOW_IN_CI = process.env.CI === 'true';
 
 /** Copy a directory tree using cp -a (preserves structure, fast). */
 function cpTree(src: string, dest: string): void {
@@ -182,6 +183,7 @@ describe('install flow — tier 1 (file validation)', () => {
   let homeDir: string;
   const originalHome = process.env.OP_HOME;
   const originalWorkDir = process.env.OP_WORK_DIR;
+  const tier1Test = SKIP_INSTALL_FLOW_IN_CI ? it.skip : it;
 
   afterEach(() => {
     process.env.OP_HOME = originalHome;
@@ -189,7 +191,7 @@ describe('install flow — tier 1 (file validation)', () => {
     if (homeDir) rmSync(homeDir, { recursive: true, force: true });
   });
 
-  it('seed + performSetup produces complete file structure for admin+chat', async () => {
+  tier1Test('seed + performSetup produces complete file structure for admin+chat', async () => {
     homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
     process.env.OP_HOME = homeDir;
     process.env.OP_WORK_DIR = join(homeDir, 'data/workspace');
@@ -303,7 +305,7 @@ describe('install flow — tier 1 (file validation)', () => {
     expect(automations.length).toBe(0);
   }, 30_000);
 
-  it('compose config validates with selected addons', async () => {
+  tier1Test('compose config validates with selected addons', async () => {
     homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
     process.env.OP_HOME = homeDir;
     process.env.OP_WORK_DIR = join(homeDir, 'data/workspace');
@@ -352,7 +354,7 @@ describe('install flow — tier 1 (file validation)', () => {
     expect(proc.exitCode).toBe(0);
   }, 30_000);
 
-  it('performSetup with no addons produces only core services', async () => {
+  tier1Test('performSetup with no addons produces only core services', async () => {
     homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
     process.env.OP_HOME = homeDir;
     process.env.OP_WORK_DIR = join(homeDir, 'data/workspace');

package/src/main.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { detectHostInfo, main, reconcileStackEnvImageTag, resolveRequestedImageTag, upsertEnvValue } from './main.ts';
+import { canReplaceCurrentExecutable, resolveCliArtifactName } from './commands/self-update.ts';
 
 /** Write a minimal SetupSpec YAML file that satisfies validation, allowing --file installs to skip the wizard. */
 function writeMinimalSetupSpec(dir: string): string {
@@ -277,6 +278,117 @@ describe('cli main', () => {
       rmSync(base, { recursive: true, force: true });
     }
   });
+
+  it('backs up the current OP_HOME before install --force rewrites assets', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'openpalm-install-force-'));
+    const workDir = join(base, 'work');
+    const binDir = join(base, 'data', 'bin');
+    const userEnv = join(base, 'vault', 'user', 'user.env');
+    const stackConfig = join(base, 'config', 'stack.yml');
+    const specFile = writeMinimalSetupSpec(base);
+
+    mkdirSync(binDir, { recursive: true });
+    mkdirSync(join(base, 'vault', 'user'), { recursive: true });
+    mkdirSync(join(base, 'config'), { recursive: true });
+    writeFileSync(join(binDir, 'varlock'), '#!/bin/sh\nexit 0\n');
+    chmodSync(join(binDir, 'varlock'), 0o755);
+    writeFileSync(userEnv, 'EXISTING=1\n');
+    writeFileSync(stackConfig, 'llm: old\n');
+
+    process.env.OP_HOME = base;
+    process.env.OP_WORK_DIR = workDir;
+
+    mockDockerCli();
+    globalThis.fetch = mock(async (input: string | URL) => {
+      const url = String(input);
+      if (url.endsWith('/health')) throw new TypeError('fetch failed');
+      if (url.includes('/core.compose.yml') || url.includes('/compose.yml')) {
+        return new Response('services: {}\n', { status: 200 });
+      }
+      if (url.includes('.env.schema')) return new Response('KEY=string\n', { status: 200 });
+      if (url.includes('/AGENTS.md')) return new Response('# Agents\n', { status: 200 });
+      if (url.includes('/opencode.jsonc')) return new Response('{"$schema":"https://opencode.ai/config.json"}\n', { status: 200 });
+      if (url.endsWith('.yml')) return new Response('name: test\nschedule: daily\n', { status: 200 });
+      return new Response('', { status: 503 });
+    }) as unknown as typeof fetch;
+    console.log = mock(() => {}) as typeof console.log;
+    console.warn = mock(() => {}) as typeof console.warn;
+
+    try {
+      await main(['install', '--force', '--no-start', '--file', specFile]);
+
+      const backupsDir = join(base, 'backups');
+      const backups = readdirSync(backupsDir);
+      expect(backups.length).toBeGreaterThan(0);
+      expect(readFileSync(join(backupsDir, backups[0], 'config', 'stack.yml'), 'utf8')).toContain('llm: old');
+      expect(readFileSync(join(backupsDir, backups[0], 'vault', 'user', 'user.env'), 'utf8')).toContain('EXISTING=1');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  it('supports addon and admin commands for enabling and disabling addons', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'openpalm-addon-cli-'));
+    const coreCompose = join(base, 'stack', 'core.compose.yml');
+    const adminAddonDir = join(base, 'registry', 'addons', 'admin');
+    const chatAddonDir = join(base, 'registry', 'addons', 'chat');
+    const guardianEnv = join(base, 'vault', 'stack', 'guardian.env');
+    const logs: string[] = [];
+
+    mkdirSync(join(base, 'stack'), { recursive: true });
+    mkdirSync(join(base, 'vault', 'stack'), { recursive: true });
+    mkdirSync(adminAddonDir, { recursive: true });
+    mkdirSync(chatAddonDir, { recursive: true });
+    writeFileSync(coreCompose, 'services:\n  assistant:\n    image: test\n');
+    writeFileSync(join(adminAddonDir, 'compose.yml'), 'services:\n  docker-socket-proxy:\n    image: proxy\n  admin:\n    image: admin\n');
+    writeFileSync(join(adminAddonDir, '.env.schema'), 'OP_ADMIN_TOKEN=\n');
+    writeFileSync(join(chatAddonDir, 'compose.yml'), 'services:\n  chat:\n    image: chat\n    environment:\n      CHANNEL_NAME: "Chat"\n      CHANNEL_ID: "chat"\n');
+    writeFileSync(join(chatAddonDir, '.env.schema'), 'CHANNEL_CHAT_SECRET=\n');
+    writeFileSync(guardianEnv, '# Guardian channel HMAC secrets — managed by openpalm\n');
+
+    process.env.OP_HOME = base;
+    process.env.OP_SKIP_COMPOSE_PREFLIGHT = '1';
+    mockDockerCli();
+    console.log = mock((message?: unknown) => { logs.push(String(message ?? '')); }) as typeof console.log;
+    console.warn = mock((message?: unknown) => { logs.push(String(message ?? '')); }) as typeof console.warn;
+
+    try {
+      await main(['addon', 'enable', 'chat']);
+      expect(existsSync(join(base, 'stack', 'addons', 'chat', 'compose.yml'))).toBe(true);
+      expect(readFileSync(guardianEnv, 'utf8')).toMatch(/CHANNEL_CHAT_SECRET=/);
+
+      await main(['admin', 'enable']);
+      expect(existsSync(join(base, 'stack', 'addons', 'admin', 'compose.yml'))).toBe(true);
+
+      await main(['admin', 'status']);
+      expect(logs.some((line) => line.includes('Admin addon is enabled.'))).toBe(true);
+
+      await main(['addon', 'disable', 'chat']);
+      expect(existsSync(join(base, 'stack', 'addons', 'chat'))).toBe(false);
+
+      await main(['admin', 'disable']);
+      expect(existsSync(join(base, 'stack', 'addons', 'admin'))).toBe(false);
+    } finally {
+      delete process.env.OP_SKIP_COMPOSE_PREFLIGHT;
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('self-update helpers', () => {
+  it('maps supported platforms to release artifacts', () => {
+    expect(resolveCliArtifactName('linux', 'x64')).toBe('openpalm-cli-linux-x64');
+    expect(resolveCliArtifactName('darwin', 'arm64')).toBe('openpalm-cli-darwin-arm64');
+  });
+
+  it('rejects unsupported platforms', () => {
+    expect(() => resolveCliArtifactName('freebsd', 'mips64')).toThrow('Unsupported platform for self-update');
+  });
+
+  it('only allows replacing standalone executables', () => {
+    expect(canReplaceCurrentExecutable('/usr/local/bin/openpalm')).toBe(true);
+    expect(canReplaceCurrentExecutable('/home/runner/.bun/bin/bun')).toBe(false);
+  });
 });
 
 describe('npm bin launcher', () => {

package/src/main.ts

@@ -18,6 +18,10 @@ export const mainCommand = defineCommand({
     install: () => import('./commands/install.ts').then((m) => m.default),
     uninstall: () => import('./commands/uninstall.ts').then((m) => m.default),
     update: () => import('./commands/update.ts').then((m) => m.default),
+    upgrade: () => import('./commands/upgrade.ts').then((m) => m.default),
+    'self-update': () => import('./commands/self-update.ts').then((m) => m.default),
+    addon: () => import('./commands/addon.ts').then((m) => m.default),
+    admin: () => import('./commands/admin.ts').then((m) => m.default),
     start: () => import('./commands/start.ts').then((m) => m.default),
     stop: () => import('./commands/stop.ts').then((m) => m.default),
     restart: () => import('./commands/restart.ts').then((m) => m.default),