openpalm 0.9.1 → 0.9.2-rc3

package/README.md

@@ -1,26 +1,53 @@
 # @openpalm/cli
 
-Bun CLI for bootstrapping and managing an OpenPalm installation. Handles the initial install (directory creation, asset download, secret seeding) and delegates to the Admin API once the stack is running.
+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.
+
+## Self-Sufficient Mode
+
+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 |
 |---|---|
-| `openpalm install` | Bootstrap XDG dirs, download assets, start admin + docker-socket-proxy, open setup wizard |
+| `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 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 |
 
 ### Install options
 
-`--force` skip "already installed" check, `--version TAG` install a specific ref (default `main`), `--no-start` prepare files only, `--no-open` skip browser launch.
+`--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.
+
+### Admin profile
+
+Admin and docker-socket-proxy use Docker Compose profiles. They 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
+```
+
+## 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.
 
-## Environment variables
+## Environment Variables
 
 | Variable | Default | Purpose |
 |---|---|---|
@@ -28,20 +55,21 @@ Bun CLI for bootstrapping and managing an OpenPalm installation. Handles the ini
 | `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 |
+| `OPENPALM_ADMIN_API_URL` | `http://localhost:8100` | Admin API endpoint (for optional delegation) |
 | `OPENPALM_ADMIN_TOKEN` | (from `secrets.env`) | Admin API auth token |
 
-## How it works
+## How It Works
 
-1. **Bootstrap** (no stack running) — creates XDG directory tree, downloads `docker-compose.yml` + `Caddyfile` from GitHub, seeds `secrets.env` and `stack.env`, starts core services via `docker compose`
-2. **Running stack** — all commands delegate to the Admin API (`/admin/install`, `/admin/containers/*`, etc.) using `x-admin-token` auth
+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.
 
-Follows the file-assembly principle: copies whole files, never renders templates. See [`docs/core-principles.md`](../../docs/technical/core-principles.md).
+Follows the file-assembly principle: copies whole files, never renders templates. See [`core-principles.md`](../../docs/technical/core-principles.md).
 
 ## Building
 
 ```bash
-bun run build                  # Current platform → dist/openpalm-cli
+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)
 ```
 
@@ -53,4 +81,4 @@ bun run start -- install --no-start
 bun test
 ```
 
-See also: [`scripts/install.sh`](../../scripts/install.sh) (binary installer), [`scripts/setup.sh`](../../scripts/setup.sh) (shell-based installer).
+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,10 +1,10 @@
 {
   "name": "openpalm",
-  "version": "0.9.1",
+  "version": "0.9.2-rc3",
   "type": "module",
   "license": "MPL-2.0",
   "description": "OpenPalm CLI — install and manage a self-hosted OpenPalm stack",
-    "repository": {
+  "repository": {
     "type": "git",
     "url": "https://github.com/itlackey/openpalm.git",
     "directory": "packages/cli"
@@ -22,5 +22,9 @@
     "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": "0.9.4",
+    "citty": "^0.2.1"
   }
 }

package/src/commands/install-services.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import { buildDeployStatusEntries, buildInstallServiceNames } from './install-services.ts';
+
+describe('install service helpers', () => {
+  it('appends admin services to managed services', () => {
+    expect(buildInstallServiceNames(['caddy', 'memory'])).toEqual([
+      'caddy',
+      'memory',
+      'admin',
+      'docker-socket-proxy',
+    ]);
+  });
+
+  it('builds deploy status entries for the full install service list', () => {
+    const services = buildInstallServiceNames(['caddy', 'memory']);
+
+    expect(buildDeployStatusEntries(services, 'pending', 'Waiting...')).toEqual([
+      { service: 'caddy', status: 'pending', label: 'Waiting...' },
+      { service: 'memory', status: 'pending', label: 'Waiting...' },
+      { service: 'admin', status: 'pending', label: 'Waiting...' },
+      { service: 'docker-socket-proxy', status: 'pending', label: 'Waiting...' },
+    ]);
+  });
+});

package/src/commands/install-services.ts

@@ -0,0 +1,13 @@
+export type DeployStatusState = 'pending' | 'pulling';
+
+export function buildInstallServiceNames(managedServices: string[]): string[] {
+  return [...managedServices, 'admin', 'docker-socket-proxy'];
+}
+
+export function buildDeployStatusEntries(
+  services: string[],
+  status: DeployStatusState,
+  label: string,
+): Array<{ service: string; status: DeployStatusState; label: string }> {
+  return services.map(service => ({ service, status, label }));
+}

package/src/commands/install.ts

@@ -0,0 +1,274 @@
+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';
+import { buildInstallServiceNames, buildDeployStatusEntries } from './install-services.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);
+      const allServices = buildInstallServiceNames(managedServices);
+
+      wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pending', 'Waiting...'));
+
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'pull', ...allServices]).catch(() => {
+        // Pull failure is non-fatal — images may already be cached
+      });
+
+      wizard.updateDeployStatus(buildDeployStatusEntries(allServices, 'pulling', 'Starting...'));
+
+      await runDockerCompose([...composeArgs, '--profile', 'admin', 'up', '-d', ...allServices]);
+
+      wizard.markAllRunning();
+
+      console.log(JSON.stringify({
+        ok: true,
+        mode: 'install',
+        services: allServices,
+      }, 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);
+  const allServices = buildInstallServiceNames(managedServices);
+
+  await runDockerCompose([...composeArgs, '--profile', 'admin', 'up', '-d', ...allServices]);
+
+  console.log(JSON.stringify({
+    ok: true,
+    mode: 'update',
+    services: allServices,
+  }, 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]);
+    }
+  }
+}

package/src/commands/scan.ts

@@ -0,0 +1,48 @@
+import { defineCommand } from 'citty';
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { defaultConfigHome, defaultStateHome } from '../lib/paths.ts';
+import { ensureVarlock, prepareVarlockDir } from '../lib/varlock.ts';
+
+export default defineCommand({
+  meta: {
+    name: 'scan',
+    description: 'Scan codebase for leaked secrets (requires local secrets.env)',
+  },
+  async run() {
+    const stateHome = defaultStateHome();
+    const configHome = defaultConfigHome();
+
+    const schemaPath = join(stateHome, 'artifacts', 'secrets.env.schema');
+    const envPath = join(configHome, 'secrets.env');
+
+    if (!(await Bun.file(schemaPath).exists())) {
+      console.error(
+        `Error: secrets.env.schema not found at ${schemaPath}.\nRun 'openpalm install' first to stage schema files.`,
+      );
+      process.exit(1);
+    }
+
+    if (!(await Bun.file(envPath).exists())) {
+      console.error(
+        `Error: secrets.env not found at ${envPath}.\nRun 'openpalm install' first.`,
+      );
+      process.exit(1);
+    }
+
+    const varlockBin = await ensureVarlock(stateHome);
+
+    const tmpDir = await prepareVarlockDir(schemaPath, envPath);
+    let exitCode = 1;
+    try {
+      const proc = Bun.spawn([varlockBin, 'scan', '--path', `${tmpDir}/`], {
+        stdout: 'inherit',
+        stderr: 'inherit',
+      });
+      exitCode = await proc.exited;
+    } finally {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+    process.exit(exitCode);
+  },
+});