@meshxdata/fops 0.0.1

package/src/setup/setup.js

@@ -0,0 +1,161 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { execa } from "execa";
+import inquirer from "inquirer";
+import { make } from "../shell.js";
+import { readFopsConfig, saveFopsConfig, promptAwsSsoConfig, detectEcrRegistry, checkEcrRepos } from "./aws.js";
+
+export function runSetup(dir, opts = {}) {
+  const submodules = opts.submodules !== false;
+  const createEnv = opts.env !== false;
+  const download = opts.download === true;
+  const netrcCheck = opts.netrcCheck !== false;
+
+  return (async () => {
+    if (createEnv) {
+      const envPath = path.join(dir, ".env");
+      const envExample = path.join(dir, ".env.example");
+      if (!fs.existsSync(envPath) && fs.existsSync(envExample)) {
+        fs.copyFileSync(envExample, envPath);
+        console.log(chalk.green("Created .env from .env.example. Edit .env with your settings."));
+      } else if (fs.existsSync(envPath)) {
+        console.log(chalk.gray(".env already exists."));
+      }
+    }
+    if (netrcCheck) {
+      const netrcPath = path.join(os.homedir(), ".netrc");
+      const hasNetrc = fs.existsSync(netrcPath);
+      const hasGitHub = hasNetrc && fs.readFileSync(netrcPath, "utf8").includes("machine github.com");
+      if (!hasGitHub) {
+        console.log(chalk.yellow("⚠ GitHub: ensure ~/.netrc has credentials for github.com (needed for submodules)."));
+        console.log(chalk.gray("  See README: Configure GitHub Authentication"));
+      }
+    }
+    if (submodules) {
+      console.log(chalk.blue("Initializing git submodules (checking out main)..."));
+      try {
+        await execa("git", ["submodule", "update", "--init", "--remote", "--recursive"], { cwd: dir, stdio: "inherit" });
+        console.log(chalk.green("Submodules initialized — all on main."));
+      } catch {
+        console.log(chalk.yellow("⚠ Some submodules had issues. Attempting to check out main individually..."));
+        try {
+          await execa("git", ["submodule", "init"], { cwd: dir, stdio: "inherit" });
+          await execa("git", ["submodule", "foreach", "git fetch origin main && git checkout origin/main"], { cwd: dir, stdio: "inherit" });
+          console.log(chalk.green("Submodules recovered."));
+        } catch {
+          console.log(chalk.yellow("Some submodules still failed. Fix manually with:"));
+          console.log(chalk.gray(`  cd ${dir} && git submodule foreach 'git checkout main && git pull'`));
+        }
+      }
+    }
+    if (download) {
+      // Load saved config or prompt for AWS SSO details
+      let config = readFopsConfig();
+      let awsConfig = config.aws;
+
+      const awsConfigPath = path.join(os.homedir(), ".aws", "config");
+      const profileName = awsConfig?.profileName || "dev";
+      const hasProfile = fs.existsSync(awsConfigPath) &&
+        fs.readFileSync(awsConfigPath, "utf8").includes(`[profile ${profileName}]`);
+
+      if (!hasProfile) {
+        // Check if docker-compose references ECR to auto-detect some values
+        const ecrInfo = detectEcrRegistry(dir);
+
+        const { setupAws } = await inquirer.prompt([{
+          type: "confirm",
+          name: "setupAws",
+          message: ecrInfo
+            ? `ECR images detected (account ${ecrInfo.accountId}, region ${ecrInfo.region}). Set up AWS SSO profile?`
+            : "No AWS profile found. Set up AWS SSO for ECR image pulls?",
+          default: true,
+        }]);
+
+        if (setupAws) {
+          awsConfig = await promptAwsSsoConfig();
+
+          // Save config for future runs
+          config.aws = awsConfig;
+          saveFopsConfig(config);
+
+          // Write AWS profile
+          const ssoConfig = [
+            "", `[profile ${awsConfig.profileName}]`,
+            `sso_start_url = ${awsConfig.ssoStartUrl}`,
+            `sso_region = ${awsConfig.ssoRegion}`,
+            `sso_account_id = ${awsConfig.accountId}`,
+            `sso_role_name = ${awsConfig.roleName}`,
+            `region = ${awsConfig.region}`,
+            "output = json", "",
+          ].join("\n");
+          const awsDir = path.join(os.homedir(), ".aws");
+          if (!fs.existsSync(awsDir)) fs.mkdirSync(awsDir, { mode: 0o700 });
+          if (fs.existsSync(awsConfigPath)) fs.appendFileSync(awsConfigPath, ssoConfig);
+          else fs.writeFileSync(awsConfigPath, ssoConfig, { mode: 0o600 });
+          console.log(chalk.green(`  Created AWS profile '${awsConfig.profileName}' in ~/.aws/config`));
+        } else {
+          console.log(chalk.gray("  Skipping AWS setup. Private ECR images won't be available."));
+          console.log(chalk.blue("Downloading public container images..."));
+          try {
+            await make(dir, "download");
+          } catch {
+            console.log(chalk.yellow("\n⚠ Some images failed to download."));
+          }
+          console.log(chalk.green("Setup complete. Run: fops up"));
+          return;
+        }
+      }
+
+      if (!awsConfig) {
+        awsConfig = config.aws || { profileName: "dev" };
+      }
+
+      let ecrAuthed = false;
+      try {
+        await execa("aws", ["sts", "get-caller-identity", "--profile", awsConfig.profileName], { timeout: 5000 });
+        ecrAuthed = true;
+      } catch {
+        console.log(chalk.yellow("\n⚠ AWS SSO session expired or not logged in."));
+        console.log(chalk.blue(`  Running: aws sso login --profile ${awsConfig.profileName}\n`));
+        try {
+          await execa("aws", ["sso", "login", "--profile", awsConfig.profileName], { stdio: "inherit" });
+          ecrAuthed = true;
+        } catch {
+          console.log(chalk.yellow(`  AWS SSO login failed. You can retry later with: aws sso login --profile ${awsConfig.profileName}`));
+        }
+      }
+      if (ecrAuthed) {
+        // Detect ECR registry from compose file or config
+        const ecrInfo = detectEcrRegistry(dir);
+        const ecrRegion = ecrInfo?.region || awsConfig.region;
+        const ecrAccountId = ecrInfo?.accountId || awsConfig.accountId;
+        const ecrUrl = `${ecrAccountId}.dkr.ecr.${ecrRegion}.amazonaws.com`;
+
+        try {
+          console.log(chalk.blue("Logging into ECR..."));
+          const { stdout: ecrPassword } = await execa("aws", [
+            "ecr", "get-login-password", "--region", ecrRegion, "--profile", awsConfig.profileName,
+          ]);
+          await execa("docker", [
+            "login", "--username", "AWS", "--password-stdin", ecrUrl,
+          ], { input: ecrPassword });
+          console.log(chalk.green("ECR login successful."));
+          await checkEcrRepos(dir, awsConfig);
+        } catch {
+          console.log(chalk.yellow("ECR login failed. Image pull may fail for private images."));
+        }
+      }
+      console.log(chalk.blue("Downloading container images..."));
+      try {
+        await make(dir, "download");
+      } catch {
+        console.log(chalk.yellow("\n⚠ Some images failed to download. Public images are fine."));
+        console.log(chalk.gray(`  For private ECR images, ensure: aws sso login --profile ${awsConfig.profileName}`));
+        console.log(chalk.gray("  Then re-run: fops init --download\n"));
+      }
+    }
+    console.log(chalk.green("Setup complete. Run: fops up"));
+  })();
+}

package/src/setup/wizard.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { execa } from "execa";
+import inquirer from "inquirer";
+import { isFoundationRoot, findComposeRootUp } from "../project.js";
+import { runSetup } from "./setup.js";
+
+export async function runInitWizard() {
+  const cwd = process.cwd();
+  const envRoot = process.env.FOUNDATION_ROOT;
+  let projectRoot = null;
+  if (envRoot && fs.existsSync(envRoot) && isFoundationRoot(envRoot)) {
+    projectRoot = path.resolve(envRoot);
+    console.log(chalk.gray(`Using FOUNDATION_ROOT: ${projectRoot}\n`));
+  } else if (isFoundationRoot(cwd)) {
+    projectRoot = cwd;
+    console.log(chalk.gray("Using current directory as project root.\n"));
+  } else {
+    const foundUp = findComposeRootUp(cwd);
+    if (foundUp && foundUp !== cwd) {
+      const { useFound } = await inquirer.prompt([
+        { type: "confirm", name: "useFound", message: `Found Foundation project at:\n  ${foundUp}\n  Use it instead of the current directory?`, default: false },
+      ]);
+      if (useFound) projectRoot = foundUp;
+    } else if (foundUp) {
+      projectRoot = foundUp;
+    }
+    if (!projectRoot) {
+      let hasGit = false, hasDocker = false, hasAws = false;
+      try { await execa("git", ["--version"]); hasGit = true; } catch {}
+      try { await execa("docker", ["info"], { timeout: 5000 }); hasDocker = true; } catch {}
+      try { await execa("aws", ["--version"]); hasAws = true; } catch {}
+      console.log(chalk.cyan("  Prerequisites\n"));
+      console.log(hasGit ? chalk.green("  ✓ Git") : chalk.red("  ✗ Git — install git first"));
+      console.log(hasDocker ? chalk.green("  ✓ Docker") : chalk.red("  ✗ Docker — install and start Docker Desktop"));
+      console.log(hasAws ? chalk.green("  ✓ AWS CLI") : chalk.yellow("  ⚠ AWS CLI — install for ECR image pulls (brew install awscli)"));
+      const netrcPath = path.join(os.homedir(), ".netrc");
+      const hasNetrc = fs.existsSync(netrcPath) && fs.readFileSync(netrcPath, "utf8").includes("machine github.com");
+      console.log(hasNetrc ? chalk.green("  ✓ GitHub credentials (~/.netrc)") : chalk.yellow("  ⚠ GitHub credentials — add to ~/.netrc (needed for private submodules)"));
+      console.log("");
+      if (!hasGit || !hasDocker) {
+        console.log(chalk.red("Fix the missing prerequisites above, then run fops init again.\n"));
+        process.exit(1);
+      }
+      const choices = [
+        { name: "Clone foundation-compose into this directory", value: "clone" },
+        { name: "Enter path to an existing foundation-compose directory", value: "path" },
+        { name: "Cancel", value: "cancel" },
+      ];
+      const { action } = await inquirer.prompt([{ type: "list", name: "action", message: "No Foundation project found. What do you want to do?", choices }]);
+      if (action === "cancel") process.exit(0);
+      if (action === "clone") {
+        const { repoUrl } = await inquirer.prompt([
+          { type: "input", name: "repoUrl", message: "Repository URL:", default: "https://github.com/meshxdata/foundation-compose.git", validate: (v) => (v?.trim() ? true : "Repository URL is required.") },
+        ]);
+        const { targetDir } = await inquirer.prompt([
+          { type: "input", name: "targetDir", message: "Clone into:", default: cwd },
+        ]);
+        const resolved = path.resolve(targetDir.trim());
+        if (fs.existsSync(resolved)) {
+          console.log(chalk.yellow(`\n  ${resolved} already exists.`));
+          if (isFoundationRoot(resolved)) { console.log(chalk.green("  Looks like a Foundation project — using it.\n")); projectRoot = resolved; }
+          else { console.log(chalk.red("  Not a Foundation project. Remove it or choose a different path.\n")); process.exit(1); }
+        } else {
+          console.log(chalk.blue("\nCloning (this may take a minute)...\n"));
+          try {
+            await execa("git", ["clone", repoUrl.trim(), resolved], { stdio: "inherit" });
+          } catch (err) {
+            console.log(chalk.red("\n  Clone failed. Check the URL and your credentials.\n"));
+            if (!hasNetrc) {
+              console.log(chalk.yellow("  Hint: Add GitHub credentials to ~/.netrc:\n"));
+              console.log("    machine github.com\n    login <your-username>\n    password <your-token>\n");
+            }
+            process.exit(1);
+          }
+          console.log(chalk.blue("\nInitializing submodules (checking out main)...\n"));
+          try {
+            await execa("git", ["submodule", "update", "--init", "--remote", "--recursive"], { cwd: resolved, stdio: "inherit" });
+            console.log(chalk.green("\n  Cloned successfully — all submodules on main.\n"));
+          } catch {
+            console.log(chalk.yellow("\n  ⚠ Some submodules had issues. Attempting to check out main individually...\n"));
+            try {
+              await execa("git", ["submodule", "init"], { cwd: resolved, stdio: "inherit" });
+              await execa("git", ["submodule", "foreach", "git fetch origin main && git checkout origin/main"], { cwd: resolved, stdio: "inherit" });
+              console.log(chalk.green("  Submodules recovered.\n"));
+            } catch {
+              console.log(chalk.yellow("  Some submodules still failed. Fix manually with:"));
+              console.log(chalk.gray(`  cd ${resolved} && git submodule foreach 'git checkout main && git pull'\n`));
+            }
+          }
+          projectRoot = resolved;
+        }
+      }
+      if (action === "path") {
+        const { dir } = await inquirer.prompt([
+          {
+            type: "input", name: "dir", message: "Path to foundation-compose directory:",
+            validate: (value) => {
+              const resolved = path.resolve(value.trim());
+              if (!fs.existsSync(resolved)) return "Directory does not exist.";
+              if (!isFoundationRoot(resolved)) return "Directory has no docker-compose.yaml + Makefile.";
+              return true;
+            },
+          },
+        ]);
+        projectRoot = path.resolve(dir.trim());
+      }
+    }
+  }
+  const { submodules, env, download } = await inquirer.prompt([
+    { type: "confirm", name: "submodules", message: "Initialize and update git submodules?", default: true },
+    { type: "confirm", name: "env", message: "Create .env from .env.example (if missing)?", default: true },
+    { type: "confirm", name: "download", message: "Download container images now (make download)?", default: false },
+  ]);
+  console.log("");
+  await runSetup(projectRoot, { submodules, env, download, netrcCheck: true });
+}

package/src/shell.js

@@ -0,0 +1,9 @@
+import { execa } from "execa";
+
+export async function make(root, target, args = []) {
+  return execa("make", [target, ...args], { cwd: root, stdio: "inherit" });
+}
+
+export async function dockerCompose(root, args) {
+  return execa("docker", ["compose", ...args], { cwd: root, stdio: "inherit" });
+}

package/src/shell.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("execa", () => ({
+  execa: vi.fn(() => Promise.resolve({ stdout: "", exitCode: 0 })),
+}));
+
+const { execa } = await import("execa");
+const { make, dockerCompose } = await import("./shell.js");
+
+describe("shell", () => {
+  describe("make", () => {
+    it("calls execa with make, target, and cwd", async () => {
+      await make("/project", "up");
+      expect(execa).toHaveBeenCalledWith("make", ["up"], { cwd: "/project", stdio: "inherit" });
+    });
+
+    it("passes extra args", async () => {
+      await make("/project", "logs", ["-f"]);
+      expect(execa).toHaveBeenCalledWith("make", ["logs", "-f"], { cwd: "/project", stdio: "inherit" });
+    });
+
+    it("uses empty args by default", async () => {
+      await make("/root", "build");
+      expect(execa).toHaveBeenCalledWith("make", ["build"], { cwd: "/root", stdio: "inherit" });
+    });
+
+    it("propagates execa rejection", async () => {
+      execa.mockRejectedValueOnce(new Error("make failed"));
+      await expect(make("/project", "bad-target")).rejects.toThrow("make failed");
+    });
+
+    it("passes multiple args correctly", async () => {
+      await make("/project", "deploy", ["--env=prod", "--verbose", "--dry-run"]);
+      expect(execa).toHaveBeenCalledWith(
+        "make",
+        ["deploy", "--env=prod", "--verbose", "--dry-run"],
+        { cwd: "/project", stdio: "inherit" }
+      );
+    });
+  });
+
+  describe("dockerCompose", () => {
+    it("calls execa with docker compose and args", async () => {
+      await dockerCompose("/project", ["ps", "--format", "json"]);
+      expect(execa).toHaveBeenCalledWith("docker", ["compose", "ps", "--format", "json"], {
+        cwd: "/project",
+        stdio: "inherit",
+      });
+    });
+
+    it("prefixes args with compose subcommand", async () => {
+      await dockerCompose("/project", ["up", "-d"]);
+      expect(execa).toHaveBeenCalledWith("docker", ["compose", "up", "-d"], {
+        cwd: "/project",
+        stdio: "inherit",
+      });
+    });
+
+    it("propagates execa rejection", async () => {
+      execa.mockRejectedValueOnce(new Error("docker failed"));
+      await expect(dockerCompose("/project", ["up"])).rejects.toThrow("docker failed");
+    });
+
+    it("handles empty args array", async () => {
+      await dockerCompose("/project", []);
+      expect(execa).toHaveBeenCalledWith("docker", ["compose"], {
+        cwd: "/project",
+        stdio: "inherit",
+      });
+    });
+  });
+});

package/src/skills/foundation/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: foundation-stack
+description: Managing the Foundation data mesh stack with fops
+---
+## Foundation Stack Management
+
+### Lifecycle
+
+Start the full stack:
+```bash
+fops up
+```
+
+Stop all services:
+```bash
+fops down
+```
+
+Stop and remove all volumes (clean slate):
+```bash
+fops down --clean
+```
+
+Check what's running:
+```bash
+fops status
+```
+
+### Debugging
+
+Run full environment diagnostics:
+```bash
+fops doctor
+```
+
+Auto-fix detected issues:
+```bash
+fops doctor --fix
+```
+
+Tail logs for all services:
+```bash
+fops logs
+```
+
+Tail logs for a specific service:
+```bash
+fops logs backend
+fops logs frontend
+fops logs postgres
+```
+
+### Suggesting Commands
+
+Always suggest **2–3 commands** in separate fenced blocks so the user can choose. Pair the primary action with a useful follow-up:
+
+- Restart → then logs: `fops restart kafka` + `fops logs kafka`
+- Debug → then fix: `fops doctor` + `fops doctor --fix`
+- Status → then logs: `fops status` + `fops logs`
+- Setup → then verify: `fops init` + `fops doctor`
+
+Never suggest only 1 command when a follow-up would be useful.
+
+### Stale Images
+
+If an image is more than 7 days old, it's likely stale — dependencies may have changed. When you see errors about missing packages, commands not found, or broken virtualenvs, **always check image ages first** and suggest a rebuild:
+```bash
+docker compose build --pull
+```
+```bash
+fops doctor
+```
+
+### Common Issues
+
+**Containers stuck in "unhealthy"**: Check logs for the specific service, then restart. Often caused by a dependency not being ready yet — `fops down` then `fops up` usually resolves it.
+
+**Port conflicts**: Run `fops doctor` to see which ports are in use. Kill the conflicting process or change the port mapping in `.env`.
+
+**ECR auth expired**: Run `fops login` or `fops doctor --fix` to re-authenticate with AWS ECR.
+
+**Missing .env**: Run `fops setup` to regenerate from `.env.example`.
+
+**Submodules out of date**: Run `fops setup` to re-init and pull submodules.
+
+### Services & Ports
+
+| Service         | Port  | Purpose                    |
+|-----------------|-------|----------------------------|
+| Backend         | 9001  | Core API server            |
+| Frontend        | 3002  | Web UI                     |
+| Storage Engine  | 9002  | Object storage layer       |
+| Trino           | 8081  | Distributed SQL engine     |
+| OPA             | 8181  | Policy engine              |
+| Kafka           | 9092  | Event streaming            |
+| Postgres        | 5432  | Metadata database          |
+| Hive Metastore  | 9083  | Table metadata catalog     |
+| Vault           | 18201 | Secrets management         |
+
+### First-Time Setup
+
+```bash
+npm install -g @meshxdata/fops
+fops init
+fops up
+fops doctor
+```

package/src/ui/banner.js

@@ -0,0 +1,56 @@
+import { PKG } from "../config.js";
+
+// Fun AI/OPS quotes
+export const QUOTES = [
+  // Mr Robot vibes
+  "Control is an illusion. But root access is real.",
+  "The world is a zero-day. We're just living in it.",
+  "I don't debug. I interrogate code until it confesses.",
+  "Every container is a prison. Some are just nicer than others.",
+  "sudo rm -rf doubt",
+  "Trust no process. Verify all containers.",
+  "The logs never lie. But they do omit.",
+  "Every daemon was once an angel.",
+  "First rule of production: you don't push on Friday.",
+  // Classic ops humor
+  "It works on my container™",
+  "Have you tried turning the pod off and on again?",
+  "99.9% uptime means 8.7 hours of chaos per year",
+  "YAML: Yet Another Markup Landmine",
+  "There's no place like 127.0.0.1",
+  "Docker: because 'it works on my machine' wasn't enough",
+  "The cloud is just someone else's computer having a bad day",
+  "sudo make me a sandwich",
+  "I don't always test my code, but when I do, I do it in production",
+  "Containers: VMs but make it fashion",
+  "Keep calm and kubectl apply -f",
+  "In a world of microservices, be a monolith of calm",
+  "Terraform: Infrastructure as YOLO",
+  "The best time to fix prod was yesterday. The second best is now.",
+  "May your builds be green and your deploys be boring",
+  "Observability: watching things break, but fancier",
+];
+
+export function getRandomQuote() {
+  return QUOTES[Math.floor(Math.random() * QUOTES.length)];
+}
+
+// Banner ASCII art
+export const BANNER = `
+  ███████╗ ██████╗ ██████╗ ███████╗
+  ██╔════╝██╔═══██╗██╔══██╗██╔════╝
+  █████╗  ██║   ██║██████╔╝███████╗
+  ██╔══╝  ██║   ██║██╔═══╝ ╚════██║
+  ██║     ╚██████╔╝██║     ███████║
+  ╚═╝      ╚═════╝ ╚═╝     ╚══════╝
+`;
+
+/**
+ * Render the Foundation banner (static, no ink)
+ */
+export function renderBanner() {
+  console.log("\x1b[36m" + BANNER + "\x1b[0m");
+  console.log("  \x1b[1mFoundation OPS CLI\x1b[0m");
+  console.log("  \x1b[90mv" + PKG.version + "  •  /exit to quit  •  ↑↓ history\x1b[0m");
+  console.log("\n  \x1b[3;33m\"" + getRandomQuote() + "\"\x1b[0m\n");
+}

package/src/ui/banner.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from "vitest";
+import { QUOTES, getRandomQuote, BANNER, renderBanner } from "./banner.js";
+
+describe("ui/banner", () => {
+  describe("QUOTES", () => {
+    it("is a non-empty array of strings", () => {
+      expect(Array.isArray(QUOTES)).toBe(true);
+      expect(QUOTES.length).toBeGreaterThan(10);
+      for (const q of QUOTES) {
+        expect(typeof q).toBe("string");
+        expect(q.length).toBeGreaterThan(0);
+      }
+    });
+
+    it("has no duplicate quotes", () => {
+      const unique = new Set(QUOTES);
+      expect(unique.size).toBe(QUOTES.length);
+    });
+
+    it("includes Mr Robot themed quotes", () => {
+      const hasMrRobot = QUOTES.some((q) => q.includes("zero-day") || q.includes("daemon") || q.includes("root access"));
+      expect(hasMrRobot).toBe(true);
+    });
+
+    it("includes ops humor quotes", () => {
+      const hasOps = QUOTES.some((q) => q.includes("container") || q.includes("production") || q.includes("Docker"));
+      expect(hasOps).toBe(true);
+    });
+  });
+
+  describe("getRandomQuote", () => {
+    it("returns a string from QUOTES", () => {
+      const quote = getRandomQuote();
+      expect(typeof quote).toBe("string");
+      expect(QUOTES).toContain(quote);
+    });
+
+    it("returns a value on every call", () => {
+      for (let i = 0; i < 20; i++) {
+        const quote = getRandomQuote();
+        expect(typeof quote).toBe("string");
+        expect(quote.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe("BANNER", () => {
+    it("contains ASCII art block characters", () => {
+      expect(BANNER).toContain("█");
+      expect(BANNER).toContain("╗");
+      expect(BANNER).toContain("╚");
+      expect(BANNER).toContain("═");
+    });
+
+    it("is multi-line", () => {
+      const lines = BANNER.split("\n").filter((l) => l.trim());
+      expect(lines.length).toBeGreaterThanOrEqual(5);
+    });
+
+    it("has substantial length", () => {
+      expect(BANNER.length).toBeGreaterThan(100);
+    });
+  });
+
+  describe("renderBanner", () => {
+    it("prints banner to stdout", () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+      renderBanner();
+      expect(spy).toHaveBeenCalled();
+      const output = spy.mock.calls.map((c) => c[0]).join("\n");
+      expect(output).toContain("Foundation OPS CLI");
+    });
+
+    it("displays version", () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+      renderBanner();
+      const output = spy.mock.calls.map((c) => c[0]).join("\n");
+      expect(output).toMatch(/v\d+\.\d+/);
+    });
+
+    it("displays exit instructions", () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+      renderBanner();
+      const output = spy.mock.calls.map((c) => c[0]).join("\n");
+      expect(output).toContain("/exit");
+    });
+
+    it("displays a quote", () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+      renderBanner();
+      const output = spy.mock.calls.map((c) => c[0]).join("\n");
+      // At least one quote should be present
+      const hasQuote = QUOTES.some((q) => output.includes(q));
+      expect(hasQuote).toBe(true);
+    });
+  });
+});