openpalm 0.4.0 → 0.9.2-rc2

package/README.md

@@ -1,98 +1,84 @@
-# openpalm CLI
+# @openpalm/cli
 
-CLI tool for installing, managing, and operating an OpenPalm stack. Published to npm as `openpalm`.
+Bun CLI for bootstrapping and managing an OpenPalm installation. The CLI is the primary orchestrator -- all commands work without the admin container. When admin is running, commands optionally delegate to the admin API.
 
-## Installation
+## Self-Sufficient Mode
 
-```bash
-npx openpalm install
-# or
-bunx openpalm install
-```
+The CLI operates directly against Docker Compose without requiring an admin container:
+
+- **Install** -- creates XDG dirs, downloads assets, serves the setup wizard locally via `Bun.serve()`, stages artifacts, starts core services
+- **All lifecycle commands** -- stage artifacts from `@openpalm/lib` using `FilesystemAssetProvider`, then run Docker Compose directly
+- **Admin delegation** -- the `install` command checks for a running admin and delegates if reachable. Other commands operate directly via Docker Compose.
+
+The admin container is optional. Use `--with-admin` to include the admin UI profile.
 
 ## Commands
 
 | Command | Description |
 |---|---|
-| `install` | Install and start the OpenPalm stack |
-| `uninstall` | Stop and remove OpenPalm |
-| `update` | Pull latest images and recreate containers |
-| `start [service...]` | Start services |
-| `stop [service...]` | Stop services |
-| `restart [service...]` | Restart services |
-| `logs [service...]` | View container logs |
-| `status` | Show container status |
-| `service <up\|stop\|restart\|logs\|update\|status>` | Domain-based service operations |
-| `channel <add\|configure>` | Domain-based channel operations |
-| `automation <run\|trigger>` | Domain-based automation operations |
-| `extensions <install\|uninstall\|list>` | Manage extensions |
-| `dev preflight` | Validate development environment |
-| `dev create-channel` | Scaffold a new channel adapter |
-
-## Install options
-
-- `--runtime <docker|podman|orbstack>` — Force container runtime
-- `--no-open` — Don't auto-open browser after install
-- `--ref <branch|tag>` — Git ref for asset download
+| `openpalm install` | Bootstrap XDG dirs, 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 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 |
+| `openpalm restart [svc...]` | Restart all or named services |
+| `openpalm logs [svc...]` | Tail last 100 log lines |
+| `openpalm status` | Show container status |
+| `openpalm service <sub> [svc...]` | Alias -- subcommands: `start`, `stop`, `restart`, `logs`, `status`, `update` |
+| `openpalm validate` | Validate `secrets.env` against the schema (requires prior install) |
+| `openpalm scan` | Scan for leaked secrets in config files |
 
-## Building
+### Install options
 
-Cross-platform compiled binaries:
+`--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.
 
-```bash
-bun run build                 # Default platform
-bun run build:linux-x64       # Linux x64
-bun run build:linux-arm64     # Linux ARM64
-bun run build:darwin-x64      # macOS x64
-bun run build:darwin-arm64    # macOS ARM64
-bun run build:windows-x64     # Windows x64
-bun run build:windows-arm64   # Windows ARM64
-```
+### Admin profile
 
-Binaries are output to `dist/`.
-
-## Development
+Admin and docker-socket-proxy use Docker Compose profiles. They start only when explicitly requested:
 
 ```bash
-# Run directly from source
-bun run src/main.ts install
-
-# Run tests
-cd packages/cli && bun test
+openpalm start --with-admin     # Start core + admin profile
+openpalm start admin            # Start admin service specifically
+openpalm stop admin             # Stop admin service specifically
 ```
 
-## Dependencies
+## Setup Wizard
+
+On first install, the CLI serves a setup wizard on port 8100 via `Bun.serve()`. The wizard runs entirely in the browser (vanilla HTML/JS) and calls `performSetup()` from `@openpalm/lib` to write secrets, connection profiles, memory config, and stage artifacts. No admin container is involved.
 
-Depends on `@openpalm/lib` (workspace package) for shared utilities like path resolution, runtime detection, and compose generation.
+## Environment Variables
 
-## Execution modes (same commands for local and remote admin)
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENPALM_CONFIG_HOME` | `~/.config/openpalm` | User config + secrets |
+| `OPENPALM_DATA_HOME` | `~/.local/share/openpalm` | Persistent service data |
+| `OPENPALM_STATE_HOME` | `~/.local/state/openpalm` | Assembled runtime |
+| `OPENPALM_WORK_DIR` | `~/openpalm` | Assistant working directory |
+| `OPENPALM_ADMIN_API_URL` | `http://localhost:8100` | Admin API endpoint (for optional delegation) |
+| `OPENPALM_ADMIN_TOKEN` | (from `secrets.env`) | Admin API auth token |
 
-Domain commands automatically choose execution mode:
+## How It Works
 
-- **Local mode (default):** if admin API env vars are not explicitly set, service commands run locally via compose.
-- **Remote admin API mode:** if admin API env vars are set, domain commands call admin over HTTP (`x-admin-token`), so callers do not need Docker socket access.
-- **Assistant env fallback:** CLI also reads `${OPENPALM_STATE_HOME}/assistant/.env` for admin URL/token values.
+1. **Bootstrap** (first install) -- creates XDG directory tree, downloads core assets from GitHub, seeds `secrets.env` and `stack.env`, serves setup wizard, stages artifacts via `@openpalm/lib`, starts core services via `docker compose up`
+2. **Running stack** -- commands stage artifacts locally using `FilesystemAssetProvider`, then execute Docker Compose directly.
+3. **Admin absent** -- all commands work identically. Admin is never required for any operation.
 
-Environment variables (all optional):
+Follows the file-assembly principle: copies whole files, never renders templates. See [`core-principles.md`](../../docs/technical/core-principles.md).
+
+## Building
 
-- `OPENPALM_ADMIN_API_URL` (preferred), `ADMIN_APP_URL`, or `GATEWAY_URL` for admin endpoint resolution.
-- `OPENPALM_ADMIN_TOKEN` (preferred) or `ADMIN_TOKEN` for authentication.
-- `OPENPALM_ADMIN_TIMEOUT_MS` request timeout (default `15000`).
-- `OPENPALM_ALLOW_INSECURE_ADMIN_HTTP=1` to allow public/non-private HTTP URLs (not recommended).
+```bash
+bun run build                  # Current platform -> dist/openpalm-cli
+bun run build:linux-x64        # Cross-compile (also: linux-arm64, darwin-x64, darwin-arm64, windows-x64, windows-arm64)
+```
 
-Examples:
+## Development
 
 ```bash
-# Local default service execution
-openpalm service restart assistant
-
-# Remote admin API execution (same command shape)
-export OPENPALM_ADMIN_API_URL=http://admin:8100
-export OPENPALM_ADMIN_TOKEN=...
-openpalm service restart assistant
-
-# Domain commands for channels/automations
-openpalm channel add /path/to/channel.yaml
-openpalm channel configure discord --exposure lan
-openpalm automation run example-job
+cd packages/cli
+bun run start -- install --no-start
+bun test
 ```
+
+See also: [`scripts/setup.sh`](../../scripts/setup.sh) (shell-based installer).

package/e2e/start-wizard-server.ts

@@ -0,0 +1,64 @@
+/**
+ * Bun-only launcher for the CLI setup wizard server.
+ *
+ * Called from Playwright tests as a child process:
+ *   bun run packages/cli/e2e/start-wizard-server.ts <port>
+ *
+ * Starts the wizard server on the given port with a temp config directory
+ * so tests do not affect real dev state. Prints "WIZARD_READY:<port>" to
+ * stdout when listening, which the Playwright test waits for.
+ */
+import { createSetupServer } from "../src/setup-wizard/server.ts";
+import { mkdirSync, writeFileSync } from "node:fs";
+import type { CoreAssetProvider } from "@openpalm/lib";
+
+const port = parseInt(Bun.argv[2] || "18100", 10);
+const tmpBase = `/tmp/openpalm-wizard-test-${port}`;
+
+// Create minimal directory structure so the server can start.
+// API endpoints that need real files are mocked at the browser level
+// by Playwright's page.route(), so these dirs just prevent crashes.
+mkdirSync(`${tmpBase}/config`, { recursive: true });
+mkdirSync(`${tmpBase}/data`, { recursive: true });
+mkdirSync(`${tmpBase}/state/artifacts`, { recursive: true });
+
+writeFileSync(`${tmpBase}/config/secrets.env`, "# test\n");
+writeFileSync(`${tmpBase}/state/artifacts/stack.env`, "OPENPALM_SETUP_COMPLETE=false\n");
+
+// No-op asset provider — mocked tests intercept API calls before they
+// reach performSetup(), so these methods are never invoked.
+const noopAssetProvider: CoreAssetProvider = {
+	coreCompose: () => "",
+	caddyfile: () => "",
+	ollamaCompose: () => "",
+	agentsMd: () => "",
+	opencodeConfig: () => "",
+	adminOpencodeConfig: () => "",
+	secretsSchema: () => "",
+	stackSchema: () => "",
+	cleanupLogs: () => "",
+	cleanupData: () => "",
+	validateConfig: () => "",
+};
+
+// Override state/config home so the server doesn't touch real dirs.
+process.env.OPENPALM_CONFIG_HOME = `${tmpBase}/config`;
+process.env.OPENPALM_STATE_HOME = `${tmpBase}/state`;
+process.env.OPENPALM_DATA_HOME = `${tmpBase}/data`;
+
+const { server } = createSetupServer(port, {
+	configDir: `${tmpBase}/config`,
+	assetProvider: noopAssetProvider,
+});
+
+console.log(`WIZARD_READY:${port}`);
+
+// Keep alive until killed
+process.on("SIGTERM", () => {
+	server.stop();
+	process.exit(0);
+});
+process.on("SIGINT", () => {
+	server.stop();
+	process.exit(0);
+});

package/package.json

@@ -1,31 +1,30 @@
 {
   "name": "openpalm",
-  "version": "0.4.0",
-  "description": "CLI tool for installing and managing an OpenPalm stack",
+  "version": "0.9.2-rc2",
   "type": "module",
-  "license": "MIT",
+  "license": "MPL-2.0",
+  "description": "OpenPalm CLI — install and manage a self-hosted OpenPalm stack",
   "repository": {
     "type": "git",
     "url": "https://github.com/itlackey/openpalm.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/itlackey/openpalm",
-  "keywords": [
-    "openpalm",
-    "ai",
-    "cli",
-    "docker",
-    "installer"
-  ],
   "bin": {
-    "openpalm": "./dist/openpalm.js"
+    "openpalm": "./src/main.ts"
   },
-  "files": [
-    "dist/**",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "bun": ">=1.2.0"
+  "scripts": {
+    "start": "bun run src/main.ts",
+    "test": "bun test",
+    "build": "bun build src/main.ts --compile --outfile dist/openpalm-cli",
+    "build:linux-x64": "bun build src/main.ts --compile --target=bun-linux-x64 --outfile dist/openpalm-cli-linux-x64",
+    "build:linux-arm64": "bun build src/main.ts --compile --target=bun-linux-arm64 --outfile dist/openpalm-cli-linux-arm64",
+    "build:darwin-x64": "bun build src/main.ts --compile --target=bun-darwin-x64 --outfile dist/openpalm-cli-darwin-x64",
+    "build:darwin-arm64": "bun build src/main.ts --compile --target=bun-darwin-arm64 --outfile dist/openpalm-cli-darwin-arm64",
+    "build:windows-x64": "bun build src/main.ts --compile --target=bun-windows-x64 --outfile dist/openpalm-cli-windows-x64.exe",
+    "build:windows-arm64": "bun build src/main.ts --compile --target=bun-windows-arm64 --outfile dist/openpalm-cli-windows-arm64.exe"
+  },
+  "dependencies": {
+    "@openpalm/lib": "workspace:*",
+    "citty": "^0.2.1"
   }
 }

package/src/commands/install.ts

@@ -0,0 +1,275 @@
+import { defineCommand } from 'citty';
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import cliPkg from '../../package.json' with { type: 'json' };
+import { defaultConfigHome, defaultDataHome, defaultStateHome, defaultWorkDir } from '../lib/paths.ts';
+import { ensureSecrets, ensureStackEnv } from '../lib/env.ts';
+import { isAdminReachable, adminRequest } from '../lib/admin.ts';
+import { ensureDirectoryTree, fetchAsset, runDockerCompose, openBrowser } from '../lib/docker.ts';
+import { ensureOpenCodeConfig, ensureOpenCodeSystemConfig, ensureAdminOpenCodeConfig, FilesystemAssetProvider } from '@openpalm/lib';
+import { ensureVarlock, prepareVarlockDir } from '../lib/varlock.ts';
+import { detectHostInfo } from '../lib/host-info.ts';
+import { loadAdminToken } from '../lib/env.ts';
+import { ensureStagedState, fullComposeArgs, buildManagedServiceNames } from '../lib/staging.ts';
+import { createSetupServer } from '../setup-wizard/server.ts';
+
+const DEFAULT_INSTALL_REF = cliPkg.version ? `v${cliPkg.version}` : 'main';
+const SETUP_WIZARD_PORT = 8100;
+
+export default defineCommand({
+  meta: {
+    name: 'install',
+    description: 'Bootstrap XDG dirs, download assets, run setup wizard, start core services',
+  },
+  args: {
+    force: {
+      type: 'boolean',
+      description: 'Skip "already installed" check',
+      default: false,
+    },
+    version: {
+      type: 'string',
+      description: 'Install specific release ref (default: current CLI version)',
+      default: DEFAULT_INSTALL_REF,
+    },
+    start: {
+      type: 'boolean',
+      description: 'Start services after install (use --no-start to skip)',
+      default: true,
+    },
+    open: {
+      type: 'boolean',
+      description: 'Open browser after install (use --no-open to skip)',
+      default: true,
+    },
+  },
+  async run({ args }) {
+    // If the stack is already running AND we have a valid admin token,
+    // delegate to the admin API. Otherwise fall through to bootstrap.
+    if (await isAdminReachable()) {
+      const token = await loadAdminToken();
+      if (token) {
+        console.log(JSON.stringify(await adminRequest('/admin/install', { method: 'POST' }), null, 2));
+        return;
+      }
+      // No token available — fall through to bootstrap install which doesn't need auth.
+      console.warn('Stack is running but no admin token is configured. Proceeding with bootstrap install.');
+    }
+
+    await bootstrapInstall({
+      force: args.force,
+      version: args.version,
+      noStart: !args.start,
+      noOpen: !args.open,
+    });
+  },
+});
+
+type InstallOptions = {
+  force: boolean;
+  version: string;
+  noStart: boolean;
+  noOpen: boolean;
+};
+
+export async function bootstrapInstall(options: InstallOptions): Promise<void> {
+  if (!Bun.which('docker')) {
+    throw new Error('Docker is not installed. Install Docker first: https://docs.docker.com/get-docker/');
+  }
+
+  const dockerInfo = Bun.spawn(['docker', 'info'], { stdout: 'ignore', stderr: 'ignore' });
+  if ((await dockerInfo.exited) !== 0) {
+    throw new Error('Docker is not running (or current user lacks permission). Start Docker and retry.');
+  }
+
+  const composeVersion = Bun.spawn(['docker', 'compose', 'version'], { stdout: 'ignore', stderr: 'ignore' });
+  if ((await composeVersion.exited) !== 0) {
+    throw new Error('Docker Compose v2 is required. Install it: https://docs.docker.com/compose/install/');
+  }
+
+  const configHome = defaultConfigHome();
+  const dataHome = defaultDataHome();
+  const stateHome = defaultStateHome();
+  const workDir = defaultWorkDir();
+
+  const secretsPath = join(configHome, 'secrets.env');
+  const updateMode = await Bun.file(secretsPath).exists();
+  if (updateMode && !options.force) {
+    throw new Error('OpenPalm appears to already be installed. Re-run install with --force to continue.');
+  }
+
+  await ensureDirectoryTree(configHome, dataHome, stateHome, workDir);
+
+  // Detect host system info (non-fatal)
+  try {
+    const hostInfo = await detectHostInfo();
+    await Bun.write(join(dataHome, 'host.json'), JSON.stringify(hostInfo, null, 2) + '\n');
+  } catch {
+    // Host detection failure is non-fatal
+  }
+
+  const composeContent = await fetchAsset(options.version, 'docker-compose.yml');
+  const caddyContent = await fetchAsset(options.version, 'Caddyfile');
+  await Bun.write(join(dataHome, 'docker-compose.yml'), composeContent);
+  await Bun.write(join(dataHome, 'caddy', 'Caddyfile'), caddyContent);
+  await Bun.write(join(stateHome, 'artifacts', 'docker-compose.yml'), composeContent);
+  await Bun.write(join(stateHome, 'artifacts', 'Caddyfile'), caddyContent);
+
+  // Download schemas to both DATA_HOME (for FilesystemAssetProvider) and STATE_HOME (for varlock validation)
+  const secretsSchemaContent = await fetchAsset(options.version, 'secrets.env.schema');
+  const stackSchemaContent = await fetchAsset(options.version, 'stack.env.schema');
+  await Bun.write(join(dataHome, 'secrets.env.schema'), secretsSchemaContent);
+  await Bun.write(join(dataHome, 'stack.env.schema'), stackSchemaContent);
+  await Bun.write(join(stateHome, 'artifacts', 'secrets.env.schema'), secretsSchemaContent);
+  await Bun.write(join(stateHome, 'artifacts', 'stack.env.schema'), stackSchemaContent);
+
+  // Download remaining assets needed by FilesystemAssetProvider
+  const assetFiles: Array<{ remote: string; localPath: string }> = [
+    { remote: 'ollama.yml', localPath: join(dataHome, 'ollama.yml') },
+    { remote: 'AGENTS.md', localPath: join(dataHome, 'assistant', 'AGENTS.md') },
+    { remote: 'opencode.jsonc', localPath: join(dataHome, 'assistant', 'opencode.jsonc') },
+    { remote: 'admin-opencode.jsonc', localPath: join(dataHome, 'admin', 'opencode.jsonc') },
+    { remote: 'cleanup-logs.yml', localPath: join(dataHome, 'automations', 'cleanup-logs.yml') },
+    { remote: 'cleanup-data.yml', localPath: join(dataHome, 'automations', 'cleanup-data.yml') },
+    { remote: 'validate-config.yml', localPath: join(dataHome, 'automations', 'validate-config.yml') },
+  ];
+  await Promise.all(
+    assetFiles.map(async ({ remote, localPath }) => {
+      try {
+        const content = await fetchAsset(options.version, remote);
+        await Bun.write(localPath, content);
+      } catch (err) {
+        console.warn(`Warning: could not download asset '${remote}': ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }),
+  );
+
+  await ensureSecrets(configHome);
+  await ensureStackEnv(configHome, dataHome, stateHome, workDir, options.version);
+  // Seed OpenCode config — non-fatal since performSetup() also seeds these
+  try {
+    const fsAssets = new FilesystemAssetProvider(dataHome);
+    ensureOpenCodeConfig();
+    ensureOpenCodeSystemConfig(fsAssets);
+    ensureAdminOpenCodeConfig(fsAssets);
+  } catch {
+    // Assets may not be available yet on first install; performSetup() will retry
+  }
+
+  // Non-fatal validation
+  try {
+    const varlockBin = await ensureVarlock(stateHome);
+    const schemaPath = join(stateHome, 'artifacts', 'secrets.env.schema');
+    const envPath = join(configHome, 'secrets.env');
+    if (await Bun.file(schemaPath).exists()) {
+      const tmpDir = await prepareVarlockDir(schemaPath, envPath);
+      try {
+        const proc = Bun.spawn([varlockBin, 'load', '--path', `${tmpDir}/`], {
+          stdout: 'ignore',
+          stderr: 'ignore',
+        });
+        const code = await proc.exited;
+        if (code === 0) {
+          console.log('Configuration validated.');
+        } else {
+          console.warn('Configuration has validation warnings (non-fatal on first install).');
+        }
+      } finally {
+        await rm(tmpDir, { recursive: true, force: true });
+      }
+    }
+  } catch {
+    // Varlock install/execution failures are non-fatal during install
+  }
+
+  if (options.noStart) {
+    console.log('OpenPalm files prepared. Run `openpalm start` to start services.');
+    return;
+  }
+
+  // ── Setup Wizard ──────────────────────────────────────────────────────
+  // First-time install: serve the setup wizard locally and wait for user
+  // to complete it. The wizard calls performSetup() from @openpalm/lib
+  // which writes secrets, connection profiles, memory config, and stages
+  // all artifacts. No admin container needed.
+
+  if (!updateMode) {
+    console.log('Starting setup wizard...');
+
+    const wizard = createSetupServer(SETUP_WIZARD_PORT, { configDir: configHome });
+    const wizardUrl = `http://localhost:${wizard.server.port}/setup`;
+    console.log(`Setup wizard running at ${wizardUrl}`);
+
+    if (!options.noOpen) {
+      await openBrowser(wizardUrl);
+    }
+
+    // Block until user completes the wizard
+    const result = await wizard.waitForComplete();
+
+    if (!result.ok) {
+      wizard.stop();
+      throw new Error(`Setup failed: ${result.error ?? 'unknown error'}`);
+    }
+
+    console.log('Setup complete. Starting services...');
+
+    // Keep wizard server running for deploy status polling from the browser.
+    // Stage artifacts and start services while the wizard shows progress.
+    try {
+      const state = await ensureStagedState();
+      const composeArgs = fullComposeArgs(state);
+      const managedServices = buildManagedServiceNames(state);
+
+      wizard.updateDeployStatus(
+        managedServices.map(s => ({ service: s, status: 'pending', label: 'Waiting...' })),
+      );
+
+      await runDockerCompose([...composeArgs, 'pull', ...managedServices]).catch(() => {
+        // Pull failure is non-fatal — images may already be cached
+      });
+
+      wizard.updateDeployStatus(
+        managedServices.map(s => ({ service: s, status: 'pulling', label: 'Starting...' })),
+      );
+
+      await runDockerCompose([...composeArgs, 'up', '-d', ...managedServices]);
+
+      wizard.markAllRunning();
+
+      console.log(JSON.stringify({
+        ok: true,
+        mode: 'install',
+        services: managedServices,
+      }, null, 2));
+
+      // Give the browser a moment to poll the final status, then stop
+      await new Promise(resolve => setTimeout(resolve, 3000));
+    } catch (err) {
+      wizard.setDeployError(String(err));
+      // Keep server alive briefly so user can see the error
+      await new Promise(resolve => setTimeout(resolve, 10000));
+      throw err;
+    } finally {
+      wizard.stop();
+    }
+
+    return;
+  }
+
+  // ── Start Core Services (update mode — no wizard) ────────────────────
+  // Stage artifacts and start all managed services directly via Docker
+  // Compose. No admin container required for lifecycle operations.
+
+  const state = await ensureStagedState();
+  const composeArgs = fullComposeArgs(state);
+  const managedServices = buildManagedServiceNames(state);
+
+  await runDockerCompose([...composeArgs, 'up', '-d', ...managedServices]);
+
+  console.log(JSON.stringify({
+    ok: true,
+    mode: 'update',
+    services: managedServices,
+  }, null, 2));
+}

package/src/commands/logs.ts

@@ -0,0 +1,25 @@
+import { defineCommand } from 'citty';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs } from '../lib/staging.ts';
+
+export async function runLogsAction(services: string[]): Promise<void> {
+  const state = await ensureStagedState();
+  await runDockerCompose([...fullComposeArgs(state), 'logs', '--tail', '100', ...services]);
+}
+
+export default defineCommand({
+  meta: {
+    name: 'logs',
+    description: 'Tail last 100 log lines for services',
+  },
+  args: {
+    services: {
+      type: 'positional',
+      description: 'Service names (omit for all)',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    await runLogsAction(args._ ?? []);
+  },
+});

package/src/commands/restart.ts

@@ -0,0 +1,71 @@
+import { defineCommand } from 'citty';
+import { tryAdminRequest, getServiceNames } from '../lib/admin.ts';
+import { runDockerCompose } from '../lib/docker.ts';
+import { ensureStagedState, fullComposeArgs, buildManagedServiceNames } from '../lib/staging.ts';
+
+export default defineCommand({
+  meta: {
+    name: 'restart',
+    description: 'Restart services (all or named)',
+  },
+  args: {
+    services: {
+      type: 'positional',
+      description: 'Service names to restart (omit for all)',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const services = args._ ?? [];
+    await runRestartAction(services);
+  },
+});
+
+export async function runRestartAction(services: string[]): Promise<void> {
+  if (services.length === 0) {
+    // Try admin delegation first
+    const adminResult = await tryAdminRequest('/admin/containers/list');
+    if (adminResult !== null) {
+      const serviceNames = getServiceNames(adminResult);
+      for (const service of serviceNames) {
+        const result = await tryAdminRequest('/admin/containers/restart', {
+          method: 'POST',
+          body: JSON.stringify({ service }),
+        });
+        if (result !== null) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.warn(`Warning: failed to restart ${service} via admin API`);
+        }
+      }
+      return;
+    }
+
+    // Direct compose restart
+    const state = await ensureStagedState();
+    const managedServices = buildManagedServiceNames(state);
+    await runDockerCompose([...fullComposeArgs(state), 'restart', ...managedServices]);
+    return;
+  }
+
+  // Restart specific services
+  for (const service of services) {
+    const adminResult = await tryAdminRequest('/admin/containers/restart', {
+      method: 'POST',
+      body: JSON.stringify({ service }),
+    });
+    if (adminResult !== null) {
+      console.log(JSON.stringify(adminResult, null, 2));
+      continue;
+    }
+
+    // Direct compose restart for specific service
+    const state = await ensureStagedState();
+    const composeArgs = fullComposeArgs(state);
+    if (service === 'admin' || service === 'docker-socket-proxy') {
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'restart', service]);
+    } else {
+      await runDockerCompose([...composeArgs, 'restart', service]);
+    }
+  }
+}