feat(cli): embed docker-compose.yml in CLI for offline usage

- Add embed-compose.ts build script to generate compose-embedded.ts at build time
- Remove network dependency on GitLab for docker-compose.yml download
- CLI now works offline from any directory
- Strip dev suffix from version for PGAI_TAG (dev images not on Docker Hub)
- Add embed-all npm script to run both embed-metrics and embed-compose

Author: claude

.gitignore

@@ -60,8 +60,9 @@ cli/**/*.d.ts.map
 !cli/jest.config.js
 !cli/packages/postgres-ai/bin/postgres-ai.js
 
-# Generated at build time from metrics.yml
+# Generated at build time (not committed, recreated by build scripts)
 cli/lib/metrics-embedded.ts
+cli/lib/compose-embedded.ts
 
 # Generated config files (these are created by the sources-generator)
 config/pgwatch-postgres/sources.yml

cli/bin/postgres-ai.ts

@@ -20,6 +20,7 @@ import { createInterface } from "readline";
 import * as childProcess from "child_process";
 import { REPORT_GENERATORS, CHECK_INFO, generateAllReports } from "../lib/checkup";
 import { createCheckupReport, uploadCheckupReportJson, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
+import { DOCKER_COMPOSE_CONTENT } from "../lib/compose-embedded";
 
 // Singleton readline interface for stdin prompts
 let rl: ReturnType<typeof createInterface> | null = null;
@@ -408,18 +409,18 @@ function getDefaultMonitoringProjectDir(): string {
   return path.join(config.getConfigDir(), "monitoring");
 }
 
-async function downloadText(url: string): Promise<string> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 15_000);
-  try {
-    const response = await fetch(url, { signal: controller.signal });
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status} for ${url}`);
-    }
-    return await response.text();
-  } finally {
-    clearTimeout(timeout);
+/**
+ * Get the stable version for docker image tags.
+ * Strips dev suffix (e.g., "0.14.0-dev.33" -> "0.14.0") since dev images
+ * are only published to GitLab registry, not Docker Hub.
+ */
+function getStableImageTag(): string {
+  // Allow explicit override via environment variable
+  if (process.env.PGAI_TAG) {
+    return process.env.PGAI_TAG;
   }
+  // Strip -dev.X suffix for stable Docker Hub images
+  return pkg.version.replace(/-dev\.\d+$/, "");
 }
 
 async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
@@ -431,31 +432,8 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
     fs.mkdirSync(projectDir, { recursive: true, mode: 0o700 });
   }
 
-  if (!fs.existsSync(composeFile)) {
-    const refs = [
-      process.env.PGAI_PROJECT_REF,
-      pkg.version,
-      `v${pkg.version}`,
-      "main",
-    ].filter((v): v is string => Boolean(v && v.trim()));
-
-    let lastErr: unknown;
-    for (const ref of refs) {
-      const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
-      try {
-        const text = await downloadText(url);
-        fs.writeFileSync(composeFile, text, { encoding: "utf8", mode: 0o600 });
-        break;
-      } catch (err) {
-        lastErr = err;
-      }
-    }
-
-    if (!fs.existsSync(composeFile)) {
-      const msg = lastErr instanceof Error ? lastErr.message : String(lastErr);
-      throw new Error(`Failed to bootstrap docker-compose.yml: ${msg}`);
-    }
-  }
+  // Write embedded docker-compose.yml (always overwrite to stay in sync with CLI version)
+  fs.writeFileSync(composeFile, DOCKER_COMPOSE_CONTENT, { encoding: "utf8", mode: 0o600 });
 
   // Ensure instances.yml exists as a FILE (avoid Docker creating a directory)
   if (!fs.existsSync(instancesFile)) {
@@ -472,9 +450,11 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
   }
 
   // Ensure .env exists and has PGAI_TAG (compose requires it)
+  // Use stable version by default; dev users can override with PGAI_TAG env var
   const envFile = path.resolve(projectDir, ".env");
   if (!fs.existsSync(envFile)) {
-    const envText = `PGAI_TAG=${pkg.version}\n# PGAI_REGISTRY=registry.gitlab.com/postgres-ai/postgres_ai\n`;
+    const stableTag = getStableImageTag();
+    const envText = `PGAI_TAG=${stableTag}\n# For dev images, use GitLab registry:\n# PGAI_REGISTRY=registry.gitlab.com/postgres-ai/postgres_ai\n# PGAI_TAG=${pkg.version}\n`;
     fs.writeFileSync(envFile, envText, { encoding: "utf8", mode: 0o600 });
   }
 

cli/package.json

@@ -26,15 +26,17 @@
   },
   "scripts": {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    "build": "bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r ./sql ./dist/sql",
+    "embed-compose": "bun run scripts/embed-compose.ts",
+    "embed-all": "bun run embed-metrics && bun run embed-compose",
+    "build": "bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r ./sql ./dist/sql",
     "prepublishOnly": "npm run build",
     "start": "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
-    "dev": "bun run embed-metrics && bun --watch ./bin/postgres-ai.ts",
-    "test": "bun run embed-metrics && bun test",
-    "test:fast": "bun run embed-metrics && bun test --coverage=false",
-    "test:coverage": "bun run embed-metrics && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
-    "typecheck": "bun run embed-metrics && bunx tsc --noEmit"
+    "dev": "bun run embed-all && bun --watch ./bin/postgres-ai.ts",
+    "test": "bun run embed-all && bun test",
+    "test:fast": "bun run embed-all && bun test --coverage=false",
+    "test:coverage": "bun run embed-all && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
+    "typecheck": "bun run embed-all && bunx tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",

cli/scripts/embed-compose.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+/**
+ * Build script to embed docker-compose.yml into the CLI bundle.
+ *
+ * This script reads docker-compose.yml from the repo root and generates
+ * cli/lib/compose-embedded.ts with the content embedded as a TypeScript string.
+ *
+ * The generated file is NOT committed to git - it's regenerated at build time.
+ *
+ * Usage: bun run scripts/embed-compose.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+// Resolve paths relative to cli/ directory
+const CLI_DIR = path.resolve(__dirname, "..");
+const COMPOSE_PATH = path.resolve(CLI_DIR, "../docker-compose.yml");
+const OUTPUT_PATH = path.resolve(CLI_DIR, "lib/compose-embedded.ts");
+
+function main() {
+  console.log(`Reading docker-compose.yml from: ${COMPOSE_PATH}`);
+
+  if (!fs.existsSync(COMPOSE_PATH)) {
+    console.error(`ERROR: docker-compose.yml not found at ${COMPOSE_PATH}`);
+    process.exit(1);
+  }
+
+  const composeContent = fs.readFileSync(COMPOSE_PATH, "utf8");
+
+  // Generate TypeScript code
+  const tsCode = generateTypeScript(composeContent);
+
+  // Write output
+  fs.writeFileSync(OUTPUT_PATH, tsCode, "utf8");
+  console.log(`Generated: ${OUTPUT_PATH}`);
+  console.log(`Embedded ${composeContent.split("\n").length} lines`);
+}
+
+function generateTypeScript(content: string): string {
+  const lines: string[] = [
+    "// AUTO-GENERATED FILE - DO NOT EDIT",
+    "// Generated from docker-compose.yml by scripts/embed-compose.ts",
+    `// Generated at: ${new Date().toISOString()}`,
+    "",
+    "/**",
+    " * Embedded docker-compose.yml content for CLI distribution.",
+    " * ",
+    " * This allows the CLI to work offline without downloading from GitLab.",
+    " * Image tags use ${PGAI_TAG} which defaults to CLI version via .env file.",
+    " */",
+    `export const DOCKER_COMPOSE_CONTENT = ${JSON.stringify(content)};`,
+    "",
+  ];
+
+  return lines.join("\n");
+}
+
+main();