openpalm 0.10.0-rc9 → 0.10.1

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-rc9",
+  "version": "0.10.1",
   "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.9.8 <1.0.0",
+    "@openpalm/lib": ">=0.10.0 <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

@@ -5,8 +5,9 @@ import cliPkg from '../../package.json' with { type: 'json' };
 import { defaultWorkDir } from '../lib/paths.ts';
 import { resolveOpenPalmHome, resolveConfigDir, resolveVaultDir, resolveDataDir } from '@openpalm/lib';
 import { ensureSecrets, ensureStackEnv, resolveRequestedImageTag } from '../lib/env.ts';
-import { ensureDirectoryTree, seedOpenPalmDir, openBrowser, runDockerCompose } from '../lib/docker.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);
 
@@ -195,9 +203,15 @@ async function prepareInstallFiles(
   try { ensureOpenCodeConfig(); ensureOpenCodeSystemConfig(); } catch (err) { logger.debug('failed to ensure OpenCode config', { error: String(err) }); }
 
   try {
+    // Download + validate wrapped in a single timeout. The download can be
+    // slow on first install (binary fetch from GitHub) but must not block
+    // the install indefinitely — 30s is generous enough for most connections.
     await Promise.race([
-      runVarlockValidation(dataDir, vaultDir),
-      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 5_000)),
+      (async () => {
+        const varlockBin = await ensureVarlock();
+        await runVarlockValidation(varlockBin, vaultDir);
+      })(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 30_000)),
     ]);
     console.log('Configuration validated.');
   } catch (err) { logger.debug('varlock validation skipped', { error: String(err) }); }
@@ -246,6 +260,7 @@ async function runWizardInstall(configDir: string, noOpen: boolean, noStart = fa
   }
 
   console.log('Setup complete. Checking Docker...');
+  wizard.setDeploying(true);
   await requireDocker();
 
   console.log('Starting services...');
@@ -257,13 +272,16 @@ async function runWizardInstall(configDir: string, noOpen: boolean, noStart = fa
   const allServices = await buildManagedServices(state);
   const composeArgs = fullComposeArgs(state);
   try {
-    wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pending', 'Waiting...'));
+    wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pending', 'Pulling images...'));
     await runDockerCompose([...composeArgs, 'pull', ...allServices]).catch(() => {
       console.warn('Warning: image pull failed — if this is your first install, check your network connection.');
     });
     wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pending', 'Starting...'));
     await runDockerCompose([...composeArgs, 'up', '-d', ...allServices]);
-    wizard.markAllRunning();
+
+    // Poll container health so the wizard shows real progress per-service
+    await pollContainerHealth(composeArgs, allServices, wizard);
+
     console.log('\n✓ All services are running:');
     for (const svc of allServices) {
       console.log(`  • ${svc}`);
@@ -273,7 +291,10 @@ async function runWizardInstall(configDir: string, noOpen: boolean, noStart = fa
     console.log(`  Memory API: http://localhost:${3898}`);
     console.log(`  Guardian:   http://localhost:${3899}`);
     console.log('');
-    await new Promise(resolve => setTimeout(resolve, 3000));
+    // pollContainerHealth returns as soon as all services are healthy, but
+    // the frontend polls every 2.5s — keep the server alive long enough for
+    // at least 2-3 polls to fetch the final "all running" state with URLs.
+    await new Promise(resolve => setTimeout(resolve, 8000));
   } catch (err) {
     wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'error', String(err)));
     wizard.setDeployError(String(err));
@@ -291,17 +312,91 @@ async function runFileInstall(filePath: string, noStart: boolean): Promise<void>
     throw new Error(`Setup config file not found: ${filePath}. Check the --file path and try again.`);
   }
   const config = await parseConfigFile(filePath, await Bun.file(filePath).text());
-  if (config.version === 1) throw new Error('v1 setup config format is no longer supported. Use the v2 SetupSpec format (with a "spec" field).');
-  if (!config.spec) throw new Error('Setup config must contain a "spec" field with the v2 StackSpec.');
+
+  // Normalize old wrapped format: { spec: { version, capabilities }, capabilities: [...] }
+  // into flat format:              { version, capabilities: {...}, connections: [...] }
+  if (config.spec && typeof config.spec === 'object') {
+    const spec = config.spec as Record<string, unknown>;
+    // Old format had connections array as top-level "capabilities"
+    if (Array.isArray(config.capabilities)) config.connections = config.capabilities;
+    config.version = spec.version;
+    config.capabilities = spec.capabilities;
+    delete config.spec;
+  }
+
+  if (config.version !== 2) throw new Error('Setup config must be version 2. See example.spec.yaml for the format.');
+  if (!config.capabilities || typeof config.capabilities !== 'object' || Array.isArray(config.capabilities)) {
+    throw new Error('Setup config must contain a "capabilities" object (llm, embeddings, memory).');
+  }
+
+  // Resolve security.adminToken from environment when not in spec
+  const security = (config.security ?? {}) as Record<string, unknown>;
+  if (!security.adminToken && process.env.OP_ADMIN_TOKEN) {
+    security.adminToken = process.env.OP_ADMIN_TOKEN;
+    config.security = security;
+  }
 
   const result = await performSetup(config as unknown as SetupSpec);
   if (!result.ok) throw new Error(`Setup failed: ${result.error}`);
   console.log('Setup complete.');
   if (noStart) { console.log('Config written. Run `openpalm start` to start services.'); return; }
   await requireDocker();
+  await ensureVolumeMountTargets(resolveOpenPalmHome(), resolveVaultDir());
   await deployServices('install');
 }
 
+/**
+ * Poll `docker compose ps` until all services are running/healthy (or timeout).
+ * Updates the wizard deploy status per-service so the frontend shows real progress.
+ */
+async function pollContainerHealth(
+  composeArgs: string[],
+  services: string[],
+  wizard: ReturnType<typeof createSetupServer>,
+): Promise<void> {
+  const MAX_WAIT_MS = 120_000; // 2 minutes
+  const POLL_INTERVAL = 3_000;
+  const start = Date.now();
+  const running = new Set<string>();
+  const psArgs = [...composeArgs, 'ps', '--format', 'json'];
+  let prevRunningCount = 0;
+
+  while (Date.now() - start < MAX_WAIT_MS) {
+    try {
+      const output = await runDockerComposeCapture(psArgs);
+      for (const line of output.trim().split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          const container = JSON.parse(line) as { Service?: string; State?: string; Health?: string };
+          const svc = container.Service;
+          if (!svc || !services.includes(svc)) continue;
+          const isHealthy = container.Health === 'healthy' || (container.State === 'running' && !container.Health);
+          if (isHealthy) running.add(svc);
+        } catch { /* skip malformed JSON line */ }
+      }
+    } catch { /* compose ps failed — retry next tick */ }
+
+    if (running.size !== prevRunningCount) {
+      prevRunningCount = running.size;
+      const entries = services.map(svc => ({
+        service: svc,
+        status: (running.has(svc) ? 'running' : 'pending') as 'running' | 'pending',
+        label: running.has(svc) ? 'Running' : 'Starting...',
+      }));
+      wizard.updateDeployStatus(entries);
+    }
+
+    if (running.size >= services.length) return;
+
+    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
+  }
+
+  // Timeout: mark remaining as running so the UI completes, but warn
+  const pending = services.filter(s => !running.has(s));
+  console.warn(`Warning: health check timed out for: ${pending.join(', ')}. They may still be starting.`);
+  wizard.markAllRunning();
+}
+
 /**
  * Parse all compose files under homeDir/stack/ and pre-create every host-side
  * volume mount target as the current user. This prevents Docker from creating
@@ -381,8 +476,7 @@ async function ensureVolumeMountTargets(homeDir: string, vaultDir: string): Prom
   }
 }
 
-async function runVarlockValidation(_dataDir: string, vaultDir: string): Promise<void> {
-  const varlockBin = await ensureVarlock();
+async function runVarlockValidation(varlockBin: string, vaultDir: string): Promise<void> {
   const schemaPath = join(vaultDir, 'user', 'user.env.schema');
   if (!(await Bun.file(schemaPath).exists())) return;
   const tmpDir = await prepareVarlockDir(schemaPath, join(vaultDir, 'user', 'user.env'));

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();
+  },
+});