openpalm 0.2.0

package/README.md

@@ -0,0 +1,63 @@
+# openpalm CLI
+
+CLI tool for installing, managing, and operating an OpenPalm stack. Published to npm as `openpalm`.
+
+## Installation
+
+```bash
+npx openpalm install
+# or
+bunx openpalm install
+```
+
+## 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 |
+| `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
+
+## Building
+
+Cross-platform compiled binaries:
+
+```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
+```
+
+Binaries are output to `dist/`.
+
+## Development
+
+```bash
+# Run directly from source
+bun run src/main.ts install
+
+# Run tests
+cd packages/cli && bun test
+```
+
+## Dependencies
+
+Depends on `@openpalm/lib` (workspace package) for shared utilities like path resolution, runtime detection, and compose generation.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "openpalm",
+  "version": "0.2.0",
+  "description": "CLI tool for installing and managing an OpenPalm stack",
+  "type": "module",
+  "license": "MIT",
+  "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": "./src/main.ts"
+  },
+  "files": [
+    "src/**/*.ts"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "start": "bun run src/main.ts",
+    "test": "bun test",
+    "build": "bun build src/main.ts --compile --outfile dist/openpalm",
+    "build:linux-x64": "bun build src/main.ts --compile --target=bun-linux-x64 --outfile dist/openpalm-linux-x64",
+    "build:linux-arm64": "bun build src/main.ts --compile --target=bun-linux-arm64 --outfile dist/openpalm-linux-arm64",
+    "build:darwin-x64": "bun build src/main.ts --compile --target=bun-darwin-x64 --outfile dist/openpalm-darwin-x64",
+    "build:darwin-arm64": "bun build src/main.ts --compile --target=bun-darwin-arm64 --outfile dist/openpalm-darwin-arm64",
+    "build:windows-x64": "bun build src/main.ts --compile --target=bun-windows-x64 --outfile dist/openpalm-windows-x64.exe",
+    "build:windows-arm64": "bun build src/main.ts --compile --target=bun-windows-arm64 --outfile dist/openpalm-windows-arm64.exe"
+  },
+  "dependencies": {
+    "@openpalm/lib": "workspace:*"
+  }
+}

package/src/commands/create-channel.ts

@@ -0,0 +1,262 @@
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+function usage(): never {
+  throw new Error("Usage: openpalm dev create-channel <channel-name> [--port <number>]");
+}
+
+export function createChannel(args: string[]): void {
+  const nameArg = args.find((arg) => !arg.startsWith("--"));
+  if (!nameArg) usage();
+
+  const name = nameArg.toLowerCase();
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error(`Error: channel name must be lowercase alphanumeric with hyphens, got \"${name}\"`);
+  }
+  if (name.length > 32) throw new Error("Error: channel name must be 32 characters or fewer");
+
+  const reserved = new Set(["chat", "discord", "voice", "telegram", "webhook"]);
+  if (reserved.has(name)) {
+    throw new Error(`Error: \"${name}\" is an existing built-in channel. Choose a different name.`);
+  }
+
+  const portIndex = args.indexOf("--port");
+  const defaultPort = portIndex !== -1 && args[portIndex + 1] ? Number(args[portIndex + 1]) : 8190;
+  if (Number.isNaN(defaultPort) || defaultPort < 1024 || defaultPort > 65535) {
+    throw new Error("Error: --port must be a number between 1024 and 65535");
+  }
+
+  const root = resolve(import.meta.dir, "../../../..");
+  const channelDir = join(root, "channels", name);
+  if (existsSync(channelDir)) throw new Error(`Error: channels/${name}/ already exists.`);
+
+  const envPrefix = name.replace(/-/g, "_").toUpperCase();
+  const secretVar = `CHANNEL_${envPrefix}_SECRET`;
+  const inboundTokenVar = `${envPrefix}_INBOUND_TOKEN`;
+  const serviceName = `channel-${name}`;
+  const camel = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+  const pascal = camel.charAt(0).toUpperCase() + camel.slice(1);
+  const createFn = `create${pascal}Channel`;
+
+  const channelTs = `import type { ChannelAdapter, InboundResult } from "@openpalm/lib/channel.ts";
+
+const INBOUND_TOKEN = Bun.env.${inboundTokenVar} ?? "";
+
+export function ${createFn}(): ChannelAdapter {
+  return {
+    name: "${name}",
+    routes: [
+      {
+        method: "POST",
+        path: "/${name}/inbound",
+        handler: async (req: Request): Promise<InboundResult> => {
+          if (INBOUND_TOKEN && req.headers.get("x-${name}-token") !== INBOUND_TOKEN) {
+            return { ok: false, status: 401, body: { error: "unauthorized" } };
+          }
+
+          const body = (await req.json()) as {
+            userId?: string;
+            text?: string;
+            metadata?: Record<string, unknown>;
+          };
+
+          if (!body.text) {
+            return { ok: false, status: 400, body: { error: "text_required" } };
+          }
+
+          return {
+            ok: true,
+            payload: {
+              userId: body.userId ?? "${name}-user",
+              channel: "${name}",
+              text: body.text,
+              metadata: body.metadata ?? {},
+            },
+          };
+        },
+      },
+    ],
+
+    health: () => ({ ok: true, service: "${serviceName}" }),
+  };
+}
+`;
+
+  const serverTs = `import { createHmac } from "node:crypto";
+import { ${createFn} } from "./channel.ts";
+import type { ChannelAdapter } from "@openpalm/lib/channel.ts";
+
+const PORT = Number(Bun.env.PORT ?? ${defaultPort});
+const GATEWAY_URL = Bun.env.GATEWAY_URL ?? "http://gateway:8080";
+const SHARED_SECRET = Bun.env.${secretVar} ?? "";
+
+export function signPayload(secret: string, body: string) {
+  return createHmac("sha256", secret).update(body).digest("hex");
+}
+
+function json(status: number, data: unknown) {
+  return new Response(JSON.stringify(data, null, 2), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export function createFetch(
+  adapter: ChannelAdapter,
+  gatewayUrl: string,
+  sharedSecret: string,
+  forwardFetch: typeof fetch = fetch,
+) {
+  const routeMap = new Map(adapter.routes.map((route) => [route.method + " " + route.path, route.handler]));
+
+  return async function handle(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    if (url.pathname === "/health") return json(200, adapter.health());
+
+    const handler = routeMap.get(req.method + " " + url.pathname);
+    if (!handler) return json(404, { error: "not_found" });
+
+    const result = await handler(req);
+    if (!result.ok) return json(result.status, result.body);
+
+    const gatewayPayload = {
+      ...result.payload,
+      nonce: crypto.randomUUID(),
+      timestamp: Date.now(),
+    };
+
+    const serialized = JSON.stringify(gatewayPayload);
+    const sig = signPayload(sharedSecret, serialized);
+
+    const resp = await forwardFetch(gatewayUrl + "/channel/inbound", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-channel-signature": sig,
+      },
+      body: serialized,
+    });
+
+    return new Response(await resp.text(), {
+      status: resp.status,
+      headers: { "content-type": "application/json" },
+    });
+  };
+}
+
+if (import.meta.main) {
+  const adapter = ${createFn}();
+  Bun.serve({ port: PORT, fetch: createFetch(adapter, GATEWAY_URL, SHARED_SECRET) });
+  console.log("${name} channel listening on " + PORT);
+}
+`;
+
+  const testTs = `import { describe, expect, it } from "bun:test";
+import { ${createFn} } from "./channel.ts";
+import { createFetch, signPayload } from "./server.ts";
+
+describe("${name} adapter", () => {
+  const adapter = ${createFn}();
+
+  it("returns health status", async () => {
+    const handler = createFetch(adapter, "http://gateway", "secret");
+    const resp = await handler(new Request("http://test/health"));
+    expect(resp.status).toBe(200);
+    const data = (await resp.json()) as { ok: boolean; service: string };
+    expect(data.ok).toBe(true);
+    expect(data.service).toBe("${serviceName}");
+  });
+
+  it("returns 404 for unknown routes", async () => {
+    const handler = createFetch(adapter, "http://gateway", "secret");
+    const resp = await handler(new Request("http://test/unknown"));
+    expect(resp.status).toBe(404);
+  });
+
+  it("returns 400 when text is missing", async () => {
+    const handler = createFetch(adapter, "http://gateway", "secret");
+    const resp = await handler(new Request("http://test/${name}/inbound", {
+      method: "POST",
+      body: JSON.stringify({ userId: "u1" }),
+      headers: { "content-type": "application/json" },
+    }));
+    expect(resp.status).toBe(400);
+  });
+
+  it("normalizes payload and forwards with valid HMAC", async () => {
+    let capturedUrl = "";
+    let capturedSig = "";
+    let capturedBody = "";
+
+    const mockFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      capturedUrl = String(input);
+      capturedSig = String((init?.headers as Record<string, string>)["x-channel-signature"]);
+      capturedBody = String(init?.body);
+      return new Response(JSON.stringify({ ok: true }), { status: 200 });
+    };
+
+    const handler = createFetch(adapter, "http://gateway", "test-secret", mockFetch as typeof fetch);
+
+    const resp = await handler(new Request("http://test/${name}/inbound", {
+      method: "POST",
+      body: JSON.stringify({ userId: "u1", text: "hello" }),
+      headers: { "content-type": "application/json" },
+    }));
+
+    expect(resp.status).toBe(200);
+    expect(capturedUrl).toBe("http://gateway/channel/inbound");
+
+    const parsed = JSON.parse(capturedBody) as Record<string, unknown>;
+    expect(parsed.channel).toBe("${name}");
+    expect(parsed.text).toBe("hello");
+    expect(parsed.userId).toBe("u1");
+    expect(typeof parsed.nonce).toBe("string");
+    expect(typeof parsed.timestamp).toBe("number");
+    expect(capturedSig).toBe(signPayload("test-secret", capturedBody));
+  });
+});
+`;
+
+  const packageJson = `{
+  "name": "@openpalm/channel-${name}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "bun run server.ts",
+    "test": "bun test"
+  }
+}
+`;
+
+  const dockerfile = `FROM oven/bun:1.1.42
+WORKDIR /app
+COPY package.json ./
+COPY server.ts ./server.ts
+COPY channel.ts ./channel.ts
+RUN bun install --production
+CMD ["bun", "run", "server.ts"]
+`;
+
+  const envFile = `# Channel-specific overrides managed by admin UI\n${inboundTokenVar}=\n`;
+
+  mkdirSync(channelDir, { recursive: true });
+
+  const files: Array<[string, string]> = [
+    ["channel.ts", channelTs],
+    ["server.ts", serverTs],
+    ["server.test.ts", testTs],
+    ["package.json", packageJson],
+    ["Dockerfile", dockerfile],
+  ];
+
+  for (const [fileName, content] of files) {
+    writeFileSync(join(channelDir, fileName), content, "utf8");
+  }
+
+  const channelEnvDir = join(root, "assets", "config", "channels");
+  if (existsSync(channelEnvDir)) {
+    writeFileSync(join(channelEnvDir, `${name}.env`), envFile, "utf8");
+  }
+
+  console.log(`✔ Channel scaffolded: channels/${name}/`);
+}

package/src/commands/extensions.ts

@@ -0,0 +1,122 @@
+import { join } from "node:path";
+import { readEnvFile } from "@openpalm/lib/env.ts";
+import { resolveXDGPaths } from "@openpalm/lib/paths.ts";
+import { error, info } from "@openpalm/lib/ui.ts";
+
+/**
+ * Implements the extensions command for managing OpenPalm extensions.
+ * @param subcommand - The subcommand to execute: "install", "uninstall", or "list"
+ * @param args - Remaining CLI arguments (may contain --plugin <id>)
+ */
+export async function extensions(
+  subcommand: string,
+  args: string[]
+): Promise<void> {
+  // Helper function to find argument value
+  function getArg(name: string): string | undefined {
+    const index = args.indexOf(`--${name}`);
+    return index >= 0 && index + 1 < args.length ? args[index + 1] : undefined;
+  }
+
+  // Get admin token from environment or state .env file
+  let adminToken = Bun.env.ADMIN_TOKEN;
+  if (!adminToken) {
+    try {
+      const stateEnvPath = join(resolveXDGPaths().state, ".env");
+      const envVars = await readEnvFile(stateEnvPath);
+      adminToken = envVars.ADMIN_TOKEN;
+    } catch {
+      // Ignore errors reading env file
+    }
+  }
+
+  if (!adminToken) {
+    error("ADMIN_TOKEN not found in environment or state .env file");
+    process.exit(1);
+  }
+
+  // Determine base URL
+  const base =
+    Bun.env.ADMIN_APP_URL ??
+    Bun.env.GATEWAY_URL ??
+    "http://localhost/admin";
+
+  // Build headers
+  const headers = {
+    "content-type": "application/json",
+    "x-admin-token": adminToken,
+  };
+
+  /** Check HTTP response status and throw on failure. */
+  function checkResponse(response: Response, action: string): void {
+    if (!response.ok) {
+      throw new Error(
+        `${action} failed: HTTP ${response.status} ${response.statusText}`
+      );
+    }
+  }
+
+  try {
+    switch (subcommand) {
+      case "install": {
+        const pluginId = getArg("plugin");
+        if (!pluginId) {
+          error("--plugin <id> is required for install");
+          info("Usage: openpalm extensions install --plugin <id>");
+          process.exit(1);
+        }
+
+        const response = await fetch(`${base}/admin/plugins/install`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ pluginId }),
+        });
+
+        checkResponse(response, "Extension install");
+        const text = await response.text();
+        info(text);
+        break;
+      }
+
+      case "uninstall": {
+        const pluginId = getArg("plugin");
+        if (!pluginId) {
+          error("--plugin <id> is required for uninstall");
+          info("Usage: openpalm extensions uninstall --plugin <id>");
+          process.exit(1);
+        }
+
+        const response = await fetch(`${base}/admin/plugins/uninstall`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ pluginId }),
+        });
+
+        checkResponse(response, "Extension uninstall");
+        const text = await response.text();
+        info(text);
+        break;
+      }
+
+      case "list": {
+        const response = await fetch(`${base}/admin/installed`, {
+          method: "GET",
+          headers,
+        });
+
+        checkResponse(response, "Extension list");
+        const text = await response.text();
+        info(text);
+        break;
+      }
+
+      default:
+        error(`Unknown subcommand: ${subcommand}`);
+        info("Usage: openpalm extensions <install|uninstall|list> [--plugin <id>]");
+        process.exit(1);
+    }
+  } catch (err) {
+    error(`Failed to execute extensions command: ${err}`);
+    process.exit(1);
+  }
+}

package/src/commands/install.ts

@@ -0,0 +1,326 @@
+import { join } from "node:path";
+import { chmod, writeFile, rm } from "node:fs/promises";
+import type { InstallOptions } from "../types.ts";
+import type { ComposeConfig } from "@openpalm/lib/types.ts";
+import { detectOS, detectArch, detectRuntime, resolveSocketPath, resolveComposeBin, validateRuntime } from "@openpalm/lib/runtime.ts";
+import { resolveXDGPaths, createDirectoryTree } from "@openpalm/lib/paths.ts";
+import { upsertEnvVars } from "@openpalm/lib/env.ts";
+import { generateToken } from "@openpalm/lib/tokens.ts";
+import { composePull, composeUp } from "@openpalm/lib/compose.ts";
+import { seedConfigFiles } from "@openpalm/lib/assets.ts";
+import { runPreflightChecks, noRuntimeGuidance, noComposeGuidance } from "@openpalm/lib/preflight.ts";
+import { log, info, warn, error, bold, green, cyan, yellow, dim, spinner } from "@openpalm/lib/ui.ts";
+
+export async function install(options: InstallOptions): Promise<void> {
+  // ============================================================================
+  // Phase 1: Setup infrastructure
+  // ============================================================================
+
+  log(bold("\nOpenPalm Installation\n"));
+
+  // 1. Detect OS
+  const os = detectOS();
+  if (os === "unknown") {
+    error("Unable to detect operating system. Installation aborted.");
+    process.exit(1);
+  }
+
+  // 2. Detect arch
+  const arch = detectArch();
+
+  // 3. Detect or use overridden container runtime
+  const platform = options.runtime ?? await detectRuntime(os);
+  if (!platform) {
+    error(noRuntimeGuidance(os));
+    process.exit(1);
+  }
+
+  // 4. Resolve compose bin/subcommand
+  const { bin, subcommand } = resolveComposeBin(platform);
+
+  // 5. Run pre-flight checks (daemon running, disk space, port 80)
+  const preflightWarnings = await runPreflightChecks(bin, platform);
+  for (const w of preflightWarnings) {
+    warn(w.message);
+    if (w.detail) {
+      for (const line of w.detail.split("\n")) {
+        info(`  ${line}`);
+      }
+    }
+    log("");
+  }
+
+  // Daemon not running is fatal — we can't proceed
+  const daemonWarning = preflightWarnings.find((w) =>
+    w.message.includes("daemon is not running")
+  );
+  if (daemonWarning) {
+    process.exit(1);
+  }
+
+  // 6. Validate compose works
+  const isValid = await validateRuntime(bin, subcommand);
+  if (!isValid) {
+    error(noComposeGuidance(platform));
+    process.exit(1);
+  }
+
+  // 7. Print detected info
+  log(bold("Detected environment:"));
+  info(`  OS: ${cyan(os)}`);
+  info(`  Architecture: ${cyan(arch)}`);
+  info(`  Container runtime: ${cyan(platform)}`);
+  info(`  Compose command: ${cyan(`${bin} ${subcommand}`)}\n`);
+
+  // 8. Resolve XDG paths, print them
+  const xdg = resolveXDGPaths();
+  log(bold("\nXDG paths:"));
+  info(`  Data: ${dim(xdg.data)}`);
+  info(`  Config: ${dim(xdg.config)}`);
+  info(`  State: ${dim(xdg.state)}\n`);
+
+  // 9. Check if .env exists in CWD, generate if not
+  const envPath = join(process.cwd(), ".env");
+  const envExists = await Bun.file(envPath).exists();
+
+  let generatedAdminToken = "";
+  if (!envExists) {
+    const spin2 = spinner("Generating .env file...");
+    generatedAdminToken = generateToken();
+    const overrides: Record<string, string> = {
+      ADMIN_TOKEN: generatedAdminToken,
+      POSTGRES_PASSWORD: generateToken(),
+      CHANNEL_CHAT_SECRET: generateToken(),
+      CHANNEL_DISCORD_SECRET: generateToken(),
+      CHANNEL_VOICE_SECRET: generateToken(),
+      CHANNEL_TELEGRAM_SECRET: generateToken(),
+    };
+    const envSeed = Object.entries(overrides).map(([key, value]) => `${key}=${value}`).join("\n") + "\n";
+    await writeFile(envPath, envSeed, "utf8");
+    spin2.stop(green(".env file created"));
+
+    // Display admin token prominently
+    log("");
+    log(bold(green("  YOUR ADMIN PASSWORD (save this!)")));
+    log("");
+    log(`  ${yellow(generatedAdminToken)}`);
+    log("");
+    info("  You will need this password to log in to the admin dashboard.");
+    info(`  It is also saved in: ${dim(envPath)}`);
+    log("");
+  } else {
+    info("Using existing .env file");
+  }
+
+  // 10. Upsert runtime config vars into .env (single read-write cycle)
+  const socketPath = resolveSocketPath(platform, os);
+  await upsertEnvVars(envPath, [
+    ["OPENPALM_DATA_HOME", xdg.data],
+    ["OPENPALM_CONFIG_HOME", xdg.config],
+    ["OPENPALM_STATE_HOME", xdg.state],
+    ["OPENPALM_CONTAINER_PLATFORM", platform],
+    ["OPENPALM_COMPOSE_BIN", bin],
+    ["OPENPALM_COMPOSE_SUBCOMMAND", subcommand],
+    ["OPENPALM_CONTAINER_SOCKET_PATH", socketPath],
+    ["OPENPALM_CONTAINER_SOCKET_IN_CONTAINER", "/var/run/docker.sock"],
+    ["OPENPALM_CONTAINER_SOCKET_URI", "unix:///var/run/docker.sock"],
+    ["OPENPALM_IMAGE_TAG", `latest-${arch}`],
+    ["OPENPALM_ENABLED_CHANNELS", ""],
+  ]);
+
+  // 11. Create XDG directory tree
+  const spin3 = spinner("Creating directory structure...");
+  await createDirectoryTree(xdg);
+  spin3.stop(green("Directory structure created"));
+
+  // 12. Copy .env to state home
+  const stateEnvFile = join(xdg.state, ".env");
+  await Bun.write(stateEnvFile, Bun.file(envPath));
+
+  // 13. Seed config files (embedded templates — no network needed)
+  const spin4 = spinner("Seeding configuration files...");
+  await seedConfigFiles(xdg.config);
+  spin4.stop(green("Configuration files seeded"));
+
+  // 14. Reset setup wizard state so every install/reinstall starts from first boot
+  await rm(join(xdg.data, "admin", "setup-state.json"), { force: true });
+
+  // 15. Write uninstall script to state home
+  const uninstallDst = join(xdg.state, "uninstall.sh");
+  await writeFile(uninstallDst, "#!/usr/bin/env bash\nopenpalm uninstall\n", "utf8");
+  try {
+    await chmod(uninstallDst, 0o755);
+  } catch {
+    // chmod may fail on Windows — non-critical
+  }
+
+  // 16. Write minimal setup-only Caddy JSON config (admin routes only)
+  const minimalCaddyJson = JSON.stringify({
+    admin: { disabled: true },
+    apps: {
+      http: {
+        servers: {
+          main: {
+            listen: [":80"],
+            routes: [
+              {
+                match: [{ path: ["/admin*"] }],
+                handle: [{
+                  handler: "subroute",
+                  routes: [
+                    {
+                      match: [{ path: ["/admin/api*"] }],
+                      handle: [
+                        { handler: "rewrite", uri_substring: [{ find: "/admin/api", replace: "/admin" }] },
+                        { handler: "reverse_proxy", upstreams: [{ dial: "admin:8100" }] },
+                      ],
+                      terminal: true,
+                    },
+                    {
+                      handle: [
+                        { handler: "rewrite", strip_path_prefix: "/admin" },
+                        { handler: "reverse_proxy", upstreams: [{ dial: "admin:8100" }] },
+                      ],
+                    },
+                  ],
+                }],
+                terminal: true,
+              },
+              {
+                handle: [{
+                  handler: "static_response",
+                  body: "OpenPalm is starting... Please visit /admin/ to complete setup.",
+                  status_code: "503",
+                }],
+              },
+            ],
+          },
+        },
+      },
+    },
+  }, null, 2) + "\n";
+  const caddyJsonPath = join(xdg.state, "rendered", "caddy", "caddy.json");
+  await writeFile(caddyJsonPath, minimalCaddyJson, "utf8");
+
+  // ============================================================================
+  // Phase 2: Early UI access
+  // ============================================================================
+
+  log(bold("\nDownloading OpenPalm services (this may take a few minutes on first install)...\n"));
+
+  // The compose file is generated by the admin on first stack apply.
+  // For initial install, we need a minimal compose file to start core services.
+  // The admin server will generate the full compose file when the stack is applied.
+  const stateComposeFile = join(xdg.state, "docker-compose.yml");
+
+  const composeConfig: ComposeConfig = {
+    bin,
+    subcommand,
+    composeFile: stateComposeFile,
+    envFile: stateEnvFile,
+  };
+
+  const coreServices = ["caddy", "admin"];
+
+  const spin6 = spinner("Pulling core service images...");
+  await composePull(composeConfig, coreServices);
+  spin6.stop(green("Core images pulled"));
+
+  const spin7 = spinner("Starting core services...");
+  await composeUp(composeConfig, coreServices, { detach: true });
+  spin7.stop(green("Core services started"));
+
+  // Wait for admin health check
+  const adminUrl = "http://localhost/admin";
+  const healthUrl = `${adminUrl}/api/setup/status`;
+  const spin8 = spinner("Waiting for admin interface...");
+
+  let healthy = false;
+  for (let i = 0; i < 90; i++) {
+    try {
+      const response = await fetch(healthUrl, { signal: AbortSignal.timeout(3000) });
+      if (response.ok) {
+        healthy = true;
+        break;
+      }
+    } catch {
+      // Service not ready yet
+    }
+    await Bun.sleep(2000);
+  }
+
+  if (!healthy) {
+    spin8.stop(yellow("Admin interface did not become healthy in time"));
+  } else {
+    spin8.stop(green("Admin interface ready"));
+  }
+
+  // Open browser
+  if (!options.noOpen && healthy) {
+    try {
+      if (os === "macos") {
+        Bun.spawn(["open", adminUrl]);
+      } else if (os === "linux") {
+        Bun.spawn(["xdg-open", adminUrl]);
+      } else {
+        // Windows — use cmd /c start
+        Bun.spawn(["cmd", "/c", "start", adminUrl]);
+      }
+    } catch {
+      // Ignore — we print the URL below
+    }
+  }
+
+  // ============================================================================
+  // Final output
+  // ============================================================================
+
+  if (healthy) {
+    log("");
+    log(bold(green("  OpenPalm setup wizard is ready!")));
+    log("");
+    info(`  Setup wizard: ${cyan(adminUrl)}`);
+    log("");
+    if (generatedAdminToken) {
+      info(`  Admin password: ${yellow(generatedAdminToken)}`);
+      log("");
+    }
+    log(bold("  What happens next:"));
+    info("    1. The setup wizard opens in your browser");
+    info("    2. Enter your AI provider API key (e.g. from console.anthropic.com)");
+    info("    3. The wizard will download and start remaining services automatically");
+    info("    4. Pick which channels to enable (chat, Discord, etc.)");
+    info("    5. Done! Start chatting with your assistant");
+    log("");
+    if (!options.noOpen) {
+      info("  Opening setup wizard in your browser...");
+    } else {
+      info(`  Open this URL in your browser to continue: ${adminUrl}`);
+    }
+  } else {
+    log("");
+    log(bold(yellow("  Setup did not come online within 90 seconds")));
+    log("");
+    info("  This usually means containers are still starting. Try these steps:");
+    log("");
+    info(`  1. Wait a minute, then open: ${adminUrl}`);
+    log("");
+    info("  2. Check if containers are running:");
+    info("     openpalm status");
+    log("");
+    info("  3. Check logs for errors:");
+    info("     openpalm logs");
+    log("");
+    info("  4. Common fixes:");
+    info("     - Make sure port 80 is not used by another service");
+    info("     - Restart Docker/Podman and try again");
+    info("     - Check that you have internet access (images need to download)");
+  }
+
+  log("");
+  log(bold("  Useful commands:"));
+  info("    View logs:  openpalm logs");
+  info("    Stop:       openpalm stop");
+  info("    Uninstall:  openpalm uninstall");
+  log("");
+}

package/src/commands/logs.ts

@@ -0,0 +1,7 @@
+import { composeLogs } from "@openpalm/lib/compose.ts";
+import { loadComposeConfig } from "@openpalm/lib/config.ts";
+
+export async function logs(services?: string[]): Promise<void> {
+  const config = await loadComposeConfig();
+  await composeLogs(config, services?.length ? services : undefined, { follow: true, tail: 50 });
+}

package/src/commands/preflight.ts

@@ -0,0 +1,49 @@
+import { statSync } from "node:fs";
+import { info } from "@openpalm/lib/ui.ts";
+
+const devDir = ".dev";
+const envFile = ".env";
+
+const requiredDirs = [
+  "config",
+  "data/postgres",
+  "data/qdrant",
+  "data/openmemory",
+  "data/assistant",
+  "state/gateway",
+  "state/caddy",
+  "state/rendered/caddy",
+];
+
+export function preflight(): void {
+  const issues: string[] = [];
+
+  try {
+    statSync(envFile);
+  } catch {
+    issues.push(`Missing ${envFile}. Run: bun run dev:setup`);
+  }
+
+  try {
+    statSync(devDir);
+  } catch {
+    issues.push(`Missing ${devDir}/ directory. Run: bun run dev:setup`);
+  }
+
+  if (issues.length === 0) {
+    for (const dir of requiredDirs) {
+      try {
+        statSync(`${devDir}/${dir}`);
+      } catch {
+        issues.push(`Missing ${devDir}/${dir}. Run: bun run dev:setup`);
+        break;
+      }
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new Error(`Pre-flight check failed:\n\n${issues.map((issue) => `  - ${issue}`).join("\n")}\n\nRun 'bun run dev:setup' first, then try again.`);
+  }
+
+  info("Pre-flight check passed.");
+}

package/src/commands/restart.ts

@@ -0,0 +1,10 @@
+import { composeRestart } from "@openpalm/lib/compose.ts";
+import { loadComposeConfig } from "@openpalm/lib/config.ts";
+import { info, green } from "@openpalm/lib/ui.ts";
+
+export async function restart(services?: string[]): Promise<void> {
+  const config = await loadComposeConfig();
+  info("Restarting services...");
+  await composeRestart(config, services);
+  info(green("Services restarted."));
+}

package/src/commands/start.ts

@@ -0,0 +1,10 @@
+import { composeUp } from "@openpalm/lib/compose.ts";
+import { loadComposeConfig } from "@openpalm/lib/config.ts";
+import { info, green } from "@openpalm/lib/ui.ts";
+
+export async function start(services?: string[]): Promise<void> {
+  const config = await loadComposeConfig();
+  info("Starting services...");
+  await composeUp(config, services);
+  info(green("Services started."));
+}

package/src/commands/status.ts

@@ -0,0 +1,9 @@
+import { composePs } from "@openpalm/lib/compose.ts";
+import { loadComposeConfig } from "@openpalm/lib/config.ts";
+import { log } from "@openpalm/lib/ui.ts";
+
+export async function status(): Promise<void> {
+  const config = await loadComposeConfig();
+  const output = await composePs(config);
+  log(output);
+}

package/src/commands/stop.ts

@@ -0,0 +1,10 @@
+import { composeStop } from "@openpalm/lib/compose.ts";
+import { loadComposeConfig } from "@openpalm/lib/config.ts";
+import { info, green } from "@openpalm/lib/ui.ts";
+
+export async function stop(services?: string[]): Promise<void> {
+  const config = await loadComposeConfig();
+  info("Stopping services...");
+  await composeStop(config, services);
+  info(green("Services stopped."));
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,124 @@
+import { rm, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import type { UninstallOptions, ContainerPlatform } from "../types.ts";
+import type { ComposeConfig } from "@openpalm/lib/types.ts";
+import { composeDown } from "@openpalm/lib/compose.ts";
+import { readEnvFile } from "@openpalm/lib/env.ts";
+import { resolveXDGPaths } from "@openpalm/lib/paths.ts";
+import { resolveComposeBin, detectRuntime, detectOS } from "@openpalm/lib/runtime.ts";
+import { log, info, warn, error, bold, green, red, yellow, confirm } from "@openpalm/lib/ui.ts";
+
+export async function uninstall(options: UninstallOptions): Promise<void> {
+  // 1. Resolve XDG paths
+  const xdg = resolveXDGPaths();
+
+  // 2. Try to read .env from state home, falling back to CWD .env
+  let env: Record<string, string> = {};
+  const stateEnvPath = join(xdg.state, ".env");
+  try {
+    env = await readEnvFile(stateEnvPath);
+  } catch {
+    try {
+      env = await readEnvFile(".env");
+    } catch {
+      // No env file found, continue with empty env
+    }
+  }
+
+  // 3. Determine container platform
+  let platform: ContainerPlatform | null = null;
+  if (options.runtime) {
+    platform = options.runtime;
+  } else if (env.OPENPALM_CONTAINER_PLATFORM) {
+    platform = env.OPENPALM_CONTAINER_PLATFORM as ContainerPlatform;
+  } else {
+    platform = await detectRuntime(detectOS());
+  }
+
+  // 4. Resolve compose bin/subcommand if platform found
+  let composeBin: { bin: string; subcommand: string } | null = null;
+  if (platform) {
+    composeBin = resolveComposeBin(platform);
+  }
+
+  // 5. Print planned actions summary
+  log("");
+  log(bold("Uninstall Summary:"));
+  log(`Runtime platform: ${platform || "not detected"}`);
+  log("Stop/remove containers: yes");
+  log(`Remove images: ${options.removeImages ? "yes" : "no"}`);
+  log(`Remove all data/config/state: ${options.removeAll ? "yes" : "no"}`);
+  log("");
+  log(`Data directory: ${xdg.data}`);
+  log(`Config directory: ${xdg.config}`);
+  log(`State directory: ${xdg.state}`);
+  log("");
+
+  // 6. Prompt for confirmation if not --yes
+  if (!options.yes) {
+    const shouldContinue = await confirm("Continue?");
+    if (!shouldContinue) {
+      log("Aborted.");
+      return;
+    }
+  }
+
+  // 7. Stop and remove containers if compose is available
+  const composeFilePath = join(xdg.state, "docker-compose.yml");
+  if (composeBin && platform) {
+    try {
+      // Check if compose file exists by attempting to read env (simple existence check)
+      await Bun.file(composeFilePath).text();
+
+      const config: ComposeConfig = {
+        bin: composeBin.bin,
+        subcommand: composeBin.subcommand,
+        envFile: stateEnvPath,
+        composeFile: composeFilePath,
+      };
+
+      await composeDown(config, {
+        removeOrphans: true,
+        removeImages: options.removeImages,
+      });
+    } catch {
+      // 8. Compose file not found or other error
+      warn("Compose runtime or file not found; skipping container shutdown.");
+    }
+  } else {
+    // 8. No platform/compose bin detected
+    warn("Compose runtime or file not found; skipping container shutdown.");
+  }
+
+  // 9. Remove all data/config/state if requested
+  if (options.removeAll) {
+    try {
+      await rm(xdg.data, { recursive: true, force: true });
+    } catch {
+      // Directory may not exist, continue
+    }
+
+    try {
+      await rm(xdg.config, { recursive: true, force: true });
+    } catch {
+      // Directory may not exist, continue
+    }
+
+    try {
+      await rm(xdg.state, { recursive: true, force: true });
+    } catch {
+      // Directory may not exist, continue
+    }
+
+    try {
+      await unlink(".env");
+    } catch {
+      // .env may not exist in CWD, continue
+    }
+
+    info("Removed OpenPalm data/config/state and local .env.");
+  }
+
+  // 10. Success message
+  info(green("Uninstall complete."));
+}

package/src/commands/update.ts

@@ -0,0 +1,12 @@
+import { composePull, composeUp } from "@openpalm/lib/compose.ts";
+import { loadComposeConfig } from "@openpalm/lib/config.ts";
+import { info, green } from "@openpalm/lib/ui.ts";
+
+export async function update(): Promise<void> {
+  const config = await loadComposeConfig();
+  info("Pulling latest images...");
+  await composePull(config);
+  info("Recreating containers with updated images...");
+  await composeUp(config, undefined, { pull: "always" });
+  info(green("Update complete."));
+}

package/src/main.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+import type { ContainerPlatform, InstallOptions, UninstallOptions } from "./types.ts";
+import { install } from "./commands/install.ts";
+import { uninstall } from "./commands/uninstall.ts";
+import { update } from "./commands/update.ts";
+import { start } from "./commands/start.ts";
+import { stop } from "./commands/stop.ts";
+import { restart } from "./commands/restart.ts";
+import { logs } from "./commands/logs.ts";
+import { status } from "./commands/status.ts";
+import { extensions } from "./commands/extensions.ts";
+import { preflight } from "./commands/preflight.ts";
+import { createChannel } from "./commands/create-channel.ts";
+import { log, error, bold, dim } from "@openpalm/lib/ui.ts";
+import pkg from "../package.json";
+
+const VERSION = pkg.version;
+
+function printHelp(): void {
+  log(bold("openpalm") + dim(` v${VERSION}`));
+  log("");
+  log(bold("Usage:"));
+  log("  openpalm <command> [options]");
+  log("");
+  log(bold("Commands:"));
+  log("  install        Install and start OpenPalm");
+  log("  uninstall      Stop and remove OpenPalm");
+  log("  update         Pull latest images and recreate containers");
+  log("  start          Start services");
+  log("  stop           Stop services");
+  log("  restart        Restart services");
+  log("  logs           View container logs");
+  log("  status         Show container status");
+  log("  extensions     Manage extensions (install, uninstall, list)");
+  log("  dev            Development helpers (preflight, create-channel)");
+  log("  version        Print version");
+  log("  help           Show this help");
+  log("");
+  log(bold("Install options:"));
+  log("  --runtime <docker|podman|orbstack>  Force container runtime");
+  log("  --no-open                           Don't auto-open browser");
+  log("  --ref <branch|tag>                  Git ref for asset download");
+  log("");
+  log(bold("Uninstall options:"));
+  log("  --runtime <docker|podman|orbstack>  Force container runtime");
+  log("  --remove-all                        Remove all data/config/state");
+  log("  --remove-images                     Remove container images");
+  log("  --yes                               Skip confirmation prompts");
+  log("");
+  log(bold("Management commands accept optional service names:"));
+  log("  openpalm start [service...]");
+  log("  openpalm stop [service...]");
+  log("  openpalm restart [service...]");
+  log("  openpalm logs [service...]");
+  log("");
+  log(bold("Extensions:"));
+  log("  openpalm extensions install --plugin <id>");
+  log("  openpalm extensions uninstall --plugin <id>");
+  log("  openpalm extensions list");
+}
+
+function parseArg(args: string[], name: string): string | undefined {
+  const index = args.indexOf(`--${name}`);
+  if (index >= 0 && index + 1 < args.length) {
+    return args[index + 1];
+  }
+  return undefined;
+}
+
+function hasFlag(args: string[], name: string): boolean {
+  return args.includes(`--${name}`);
+}
+
+function getPositionalArgs(args: string[]): string[] {
+  const result: string[] = [];
+  let i = 0;
+  while (i < args.length) {
+    if (args[i].startsWith("--")) {
+      // Skip flag and its value if it has one
+      const flagName = args[i].slice(2);
+      if (["runtime", "ref", "plugin"].includes(flagName)) {
+        i += 2; // skip flag + value
+      } else {
+        i += 1; // skip boolean flag
+      }
+    } else {
+      result.push(args[i]);
+      i += 1;
+    }
+  }
+  return result;
+}
+
+async function main(): Promise<void> {
+  const [command, ...args] = process.argv.slice(2);
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    log(`openpalm v${VERSION}`);
+    return;
+  }
+
+  try {
+    switch (command) {
+      case "install": {
+        const options: InstallOptions = {
+          runtime: parseArg(args, "runtime") as ContainerPlatform | undefined,
+          noOpen: hasFlag(args, "no-open"),
+          ref: parseArg(args, "ref"),
+        };
+        await install(options);
+        break;
+      }
+
+      case "uninstall": {
+        const options: UninstallOptions = {
+          runtime: parseArg(args, "runtime") as ContainerPlatform | undefined,
+          removeAll: hasFlag(args, "remove-all"),
+          removeImages: hasFlag(args, "remove-images"),
+          yes: hasFlag(args, "yes"),
+        };
+        await uninstall(options);
+        break;
+      }
+
+      case "update": {
+        await update();
+        break;
+      }
+
+      case "start": {
+        const services = getPositionalArgs(args);
+        await start(services.length > 0 ? services : undefined);
+        break;
+      }
+
+      case "stop": {
+        const services = getPositionalArgs(args);
+        await stop(services.length > 0 ? services : undefined);
+        break;
+      }
+
+      case "restart": {
+        const services = getPositionalArgs(args);
+        await restart(services.length > 0 ? services : undefined);
+        break;
+      }
+
+      case "logs": {
+        const services = getPositionalArgs(args);
+        await logs(services.length > 0 ? services : undefined);
+        break;
+      }
+
+      case "status":
+      case "ps": {
+        await status();
+        break;
+      }
+
+      case "extensions":
+      case "ext": {
+        const [subcommand, ...extArgs] = args;
+        if (!subcommand) {
+          error("Missing subcommand. Usage: openpalm extensions <install|uninstall|list>");
+          process.exit(1);
+        }
+        await extensions(subcommand, extArgs);
+        break;
+      }
+
+      case "dev": {
+        const [subcommand, ...devArgs] = args;
+        if (!subcommand) {
+          error("Missing subcommand. Usage: openpalm dev <preflight|create-channel>");
+          process.exit(1);
+        }
+        if (subcommand === "preflight") {
+          preflight();
+          break;
+        }
+        if (subcommand === "create-channel") {
+          createChannel(devArgs);
+          break;
+        }
+        error(`Unknown dev subcommand: ${subcommand}`);
+        process.exit(1);
+      }
+
+      default: {
+        error(`Unknown command: ${command}`);
+        log("Run 'openpalm help' for usage information.");
+        process.exit(1);
+      }
+    }
+  } catch (err) {
+    if (err instanceof Error) {
+      error(err.message);
+    } else {
+      error(String(err));
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/src/types.ts

@@ -0,0 +1,18 @@
+import type { ContainerPlatform } from "@openpalm/lib/types.ts";
+
+/** Options for the install command. */
+export type InstallOptions = {
+  runtime?: ContainerPlatform;
+  noOpen?: boolean;
+  ref?: string;
+};
+
+/** Options for the uninstall command. */
+export type UninstallOptions = {
+  runtime?: ContainerPlatform;
+  removeAll?: boolean;
+  removeImages?: boolean;
+  yes?: boolean;
+};
+
+export type { ContainerPlatform };