no-crd GEMINI.md

Gemini CLI Mandate: nogoo9 / no-crd

This repository is a platform for agent-driven, on-demand pod orchestration in Kubernetes (k8s/k3s) without Custom Resource Definitions. It provides dynamic pod lifecycle management similar to JupyterHub or cloud IDE services, but agnostic to actual use cases.

Project Overview

• Purpose: Let AI agents (and APIs) dynamically spin up, route to, and manage ephemeral pods on Kubernetes — without requiring CRDs or cluster-level operators.
• Architecture:
  • MCP Server (src/): Model Context Protocol server exposing pod lifecycle tools — spawn, stop, list, templates — to AI agents.
• Technology Stack: Bun, Deno, Node.js, TypeScript, Moon (task runner), Biome (linting/formatting), Docker, k3d (local k8s), Kubernetes client-node.

Architecture Map

graph TD
    Agent["AI Agent / Client"] --> MCP["MCP Server: src/"]
    MCP --> K8s["Kubernetes API"]
    K8s --> Pod["Spawned Pod"]

Repository Structure

nogoo9/
├── src/                 # MCP server for pod lifecycle tools (cross-runtime)
│   ├── server/          # Fastify HTTP server, SSE manager, OIDC singleflight & proxies
│   ├── mcp/             # MCP tool implementations & schema definitions
│   └── polyfill.ts      # Global environment polyfills for Deno/Node compatibility
├── infra/
│   └── k3d/             # Local k3d cluster setup + manifests
├── .agents/             # AI agent rules & workflows
├── .moon/               # Moon workspace + toolchain config
├── .github/             # CI workflows
├── deno.json            # Deno import maps for Node module compatibility
└── package.json         # Package configuration & conditional exports

Development Conventions

• Toolchain: Supports Bun, Deno, and Node.js runtimes. Pinned via .prototools and .moon/toolchain.yml.
• Path Alias Invariant: Never use relative parent paths (../) in src/ modules. Always use the project path alias (~/) (e.g. import { foo } from "~/server/helpers.js").
• Linting & Formatting: Strictly adhere to Biome and import checks. Run bun run format (Biome lint + auto-fix) and bun run lint (scripts/check-imports.ts). Do NOT use ESLint or Prettier.
• Testing (Mandatory):
  • TDD: Write unit tests before implementing features or fixes.
  • Unit Tests: Located in src/**/*.test.ts.
  • Run all tests: bun run test or moon run mcp:test.
• Error Handling: Use clear descriptive messages. MCP tools must return structured error responses.