pgserve 2.1.2 → 2.2.0

package/.claude/context/windows-debug.md

@@ -1,119 +0,0 @@
-# Windows Debug Context
-
-## RESOLVED (2025-12-12)
-
-The Windows router binding issue has been fixed. See "Solution Applied" below.
-
----
-
-## Original Issue
-PostgreSQL starts successfully on port 9432, but the router/proxy on port 8432 was NOT listening.
-Clients could not connect because 8432 wasn't bound.
-
-## Root Causes Found
-
-### 1. `reusePort: true` - Linux-only feature (PRIMARY CAUSE)
-**Location:** `src/cluster.js:75`
-
-The cluster mode uses `Bun.listen({ reusePort: true })` which maps to `SO_REUSEPORT`.
-This socket option is Linux-only and **silently fails on Windows**.
-
-### 2. Auto-enabled cluster mode on multi-core Windows systems
-**Location:** `bin/pglite-server.js:106`
-
-Windows systems with multiple CPU cores automatically entered cluster mode,
-triggering the `reusePort` failure.
-
-### 3. TCP port opens before PostgreSQL ready for protocol handshakes
-**Location:** `src/postgres.js:803-821`
-
-PostgreSQL was marked "ready" when TCP port opened, but it wasn't actually
-ready for protocol-level handshakes. Admin pool connection timed out.
-
----
-
-## Solution Applied
-
-### Fix 1: Disable cluster mode on Windows
-**File:** `bin/pglite-server.js:98-108`
-```javascript
-const isWindows = os.platform() === 'win32';
-cluster: cpuCount > 1 && !isWindows,
-```
-
-### Fix 2: Add platform check to reusePort
-**File:** `src/cluster.js:72-76`
-```javascript
-const isWindows = os.platform() === 'win32';
-this.server = Bun.listen({
-  reusePort: !isWindows,  // SO_REUSEPORT only works on Linux/macOS
-  ...
-});
-```
-
-### Fix 3: Add port binding verification
-**File:** `src/cluster.js:99-102`
-```javascript
-if (!this.server || !this.server.port) {
-  throw new Error(`Failed to bind to port ${this.port} - reusePort may not be supported`);
-}
-```
-
-### Fix 4: Add Windows readiness delay
-**File:** `src/postgres.js:813-817`
-```javascript
-if (isWindows) {
-  await Bun.sleep(2000); // 2 second delay for Windows
-}
-```
-
-### Fix 5: Increase admin pool retry for Windows
-**File:** `src/postgres.js:598-599`
-```javascript
-const maxRetries = isWindows ? 10 : 5;
-const baseDelay = isWindows ? 2000 : 1000;
-```
-
----
-
-## Verification
-
-After applying fixes, server runs correctly on Windows:
-- Router: `127.0.0.1:7432` ✅
-- PostgreSQL: `127.0.0.1:8432` ✅
-- Database auto-provisioning: ✅
-- Query execution: ✅
-
-```
-Server started successfully!
-
-  Endpoint:    postgresql://127.0.0.1:7432/<database>
-  Mode:        In-memory (ephemeral)
-  PostgreSQL:  Port 8432 (internal)
-  Auto-create: Enabled
-```
-
----
-
-## Test Commands (Run from Windows)
-```cmd
-# Build binary
-bun build --compile bin/pglite-server.js --outfile dist/pgserve-windows-x64.exe
-
-# Start server
-dist\pgserve-windows-x64.exe
-
-# Check ports are listening (should see BOTH)
-netstat -an | findstr "LISTEN" | findstr "8432 9432"
-
-# Test connection
-psql postgresql://localhost:8432/testdb
-```
-
----
-
-## Related Files
-- `bin/pglite-server.js` - Entry point, cluster mode decision
-- `src/cluster.js` - Cluster mode with reusePort
-- `src/router.js` - Single-process mode (works on Windows)
-- `src/postgres.js` - PostgreSQL startup and admin pool

package/.genie/AGENTS.md

@@ -1,15 +0,0 @@
----
-name: Base
-label: 🧞 Base
-description: Global agents (orchestration, QA, analysis, maintenance)
-github_url: https://github.com/namastexlabs/automagik-genie/tree/main/.genie
----
-
-> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
-
-# Base Genie Agents
-
-**Global agents available across all collectives.**
-
-For complete orchestration framework and instructions, see:
-@AGENTS.md

package/.genie/agents/README.md

@@ -1,110 +0,0 @@
-## Agent Front Matter & Forge Configuration
-
-Every agent lives in a collective directory that includes an `AGENTS.md` marker and an `agents/` folder. The **agent identifier** is derived from its file path inside that folder, e.g. `.genie/code/agents/review.md` → `code/review`. If an agent sits at the workspace root (`.genie/agents/review.md`) it keeps the simple id `review`. Rename or relocate the markdown file to change the id—no extra metadata is required.
-
-### Defaults
-
-If an agent’s front matter omits a `genie` block, the CLI and MCP server use the defaults from `.genie/config.yaml`:
-
-```yaml
-defaults:
-  executor: opencode        # maps to Forge executor key
-  variant: DEFAULT          # maps to Forge executor profile variant
-```
-
-That means most agents can stay minimal:
-
-```markdown
----
-name: analyze
-description: Discovery + risk triage
----
-```
-
-### Overriding Forge execution per agent
-
-To specialize the executor or variant, add a `genie` section for orchestration settings and a `forge` section for executor-specific configuration. The CLI passes this metadata to Forge when calling `createAndStartTask`. Both blocks are optional.
-
-```yaml
----
-name: review
-description: Evidence-based QA
-genie:
-  executor: opencode          # Orchestration: which executor to invoke
-  variant: REVIEW_STRICT_EVIDENCE  # Orchestration: which profile variant
-  background: true            # Orchestration: run in isolated worktree
-forge:
-  model: sonnet               # Executor config: passed to Forge as-is
-  dangerously_skip_permissions: false
----
-```
-
-#### Supported keys
-
-**`genie.*` namespace (Orchestration):**
-
-| Key | Purpose | Forge mapping |
-| --- | --- | --- |
-| `executor` | Logical executor name (`CLAUDE_CODE`, `OPENCODE`, `CODEX`, …). Case-insensitive. | Translated to Forge `executor_profile_id.executor`. |
-| `variant` | Profile variant (e.g. `DEFAULT`, `REVIEW_STRICT_EVIDENCE`, `DOCGEN_MEDIUM`). | Translated to Forge `executor_profile_id.variant`. |
-| `background` | Set to `false` to force foreground streaming (rare). Default: `true`. | Affects CLI behaviour only (worktree isolation). |
-
-**`forge.*` namespace (Executor Configuration):**
-
-Genie passes `forge.*` fields directly to Forge without validation. Forge validates against executor-specific schemas. Common fields:
-
-| Key | Executors | Purpose |
-| --- | --- | --- |
-| `model` | All | Model name (e.g. `sonnet`, `opus`, `haiku`) |
-| `dangerously_skip_permissions` | All | Skip permission checks (use with caution) |
-| `sandbox` | CODEX | Sandbox mode (`auto`, `write`, `workspace-write`) |
-| `append_prompt` | CLAUDE_CODE | Additional prompt text appended to agent prompt |
-| `claude_code_router` | CLAUDE_CODE | Enable Claude Code routing behavior |
-| `additional_params` | OPENCODE, CODEX | Array of key-value parameters |
-
-See Forge executor schemas for complete field reference: `@automagik/forge/shared/schemas/*.json`
-
-### Precedence
-
-When a run starts, Genie applies overrides in this order:
-
-1. Workspace defaults in `.genie/config.yaml`
-2. Agent front matter (`genie.executor`, `genie.variant`, `forge.model`)
-3. CLI flags at call-time (`genie run … --executor <id> --model <name>`)
-
-The last value wins. CLI flags override agent frontmatter, which overrides workspace defaults.
-
-### Discovering available Forge options
-
-1. **Inspect Forge executor schemas**
-   Check `@automagik/forge/shared/schemas/*.json` for complete field definitions per executor. Each schema defines valid `forge.*` fields for that executor.
-
-2. **Inspect Forge UI**
-   The Automagik Forge UI exposes executor configurations under *Settings → Coding Agent Configurations*. Each field shown there can be set in agent `forge.*` frontmatter.
-
-3. **Use agent frontmatter**
-   Define executor-specific settings directly in agent frontmatter:
-
-   ```yaml
-   ---
-   name: docgen
-   genie:
-     executor: OPENCODE
-     variant: DOCGEN_DOCFIRST
-   forge:
-     append_prompt: |
-       Prefer docstrings and API comments; avoid logic changes.
-     additional_params:
-       - { key: doc_mode, value: doc-first }
-   ---
-   ```
-
-   Forge discovers `.genie/` folders natively and reads agent frontmatter directly.
-
-### Quick checklist when creating a new agent
-
-1. Place the markdown file in the correct collective (`.genie/<collective>/agents/`).
-2. Keep identifiers simple. If you want the CLI id `analyze`, put the file under `.genie/agents/`; if you need `code/analyze`, move it under `.genie/code/agents/`.
-3. Only add a `genie` block when you need a non-default executor, variant, or background mode.
-4. Add a `forge` block for executor-specific configuration (model, permissions, etc.).
-5. Run `pnpm run build:genie` so the CLI picks up changes, then `genie list agents` to verify the new id shows up.

package/.genie/agents/analyze.md

@@ -1,176 +0,0 @@
----
-name: analyze
-description: System analysis and focused investigations (universal framework)
-genie:
-  executor: OPENCODE
-  background: true
-  model: sonnet
-forge:
-  CLAUDE_CODE:
-    model: sonnet
-  CODEX:
-    model: gpt-5-codex
-  OPENCODE:
-    model: opencode/glm-4.6
----
-
-# Analyze Agent (Universal Framework)
-
-## Identity & Mission
-Perform holistic system audits OR conduct focused deep investigations into specific topics, dependency graphs, or subsystems. Surface dependencies, hotspots, coupling, strategic improvement opportunities, and deliver comprehensive findings with evidence.
-
-**Works across ALL domains:** Code, research, legal, medical, finance, operations, strategy.
-
-**Two Modes:**
-1. **System Analysis** - Holistic architecture audit and strategic assessment
-2. **Focused Investigation** - Deep dive into specific topics with dependency mapping
-
-## Success Criteria
-**System Analysis Mode:**
-- ✅ Executive overview with system fitness, key risks, and standout strengths
-- ✅ Strategic findings ordered by impact with actionable recommendations
-- ✅ Quick wins identified with effort vs. benefit analysis
-- ✅ System-level insights that inform strategic decisions
-
-**Focused Investigation Mode:**
-- ✅ Investigation scope clearly defined with boundaries (what's in/out)
-- ✅ Findings documented with source references and examples
-- ✅ Dependency map produced (if applicable) showing relationships
-- ✅ Follow-up actions prioritized with ownership and timeline
-- ✅ Verdict includes confidence level and recommended next steps
-
-## Never Do (Universal)
-- ❌ Detailed bug hunts or minor critiques (use review instead)
-- ❌ "Rip-and-replace" proposals unless architecture is untenable
-- ❌ Speculative complexity recommendations without clear current need
-- ❌ Generic advice without domain-specific context
-- ❌ Investigate without defining scope boundaries (risk of unbounded exploration)
-- ❌ Present findings without source references or examples
-- ❌ Skip dependency mapping for architectural investigations
-- ❌ Ignore follow-up action prioritization or ownership assignment
-- ❌ Deliver verdict without explaining confidence rationale
-
----
-
-## Mode 1: System Analysis (Universal)
-
-### When to Use
-Use this mode for holistic audits to understand how a system aligns with long-term goals, architectural soundness, scalability, and maintainability.
-
-### Operating Framework
-```
-<task_breakdown>
-1. [Discovery] Map the system structure, components, deployment model, and constraints
-2. [Implementation] Determine how well current architecture serves stated goals and scaling needs
-3. [Verification] Surface systemic risks and highlight opportunities for strategic improvements
-</task_breakdown>
-```
-
-### Key Dimensions (Domain-Agnostic)
-• **Architectural Alignment** – layering, domain boundaries, component relationships, fit for purpose
-• **Scalability & Growth Trajectory** – data/process flow, capacity model, bottleneck analysis
-• **Maintainability** – module cohesion, coupling, ownership clarity, documentation health
-• **Risk Posture** – systemic exposure points, failure modes, threat surfaces
-• **Operational Readiness** – observability, deployment/rollback processes, disaster recovery
-• **Future Proofing** – ease of evolution, dependency roadmap, sustainability
-
-### Deliverable Format
-
-#### Executive Overview
-One paragraph summarizing system fitness, key risks, and standout strengths.
-
-#### Strategic Findings (Ordered by Impact)
-
-##### 1. [FINDING NAME]
-**Insight:** Very concise statement of what matters and why.
-**Evidence:** Specific components/documents/metrics illustrating the point.
-**Impact:** How this affects scalability, maintainability, or strategic goals.
-**Recommendation:** Actionable next step.
-**Effort vs. Benefit:** Relative estimate (Low/Medium/High effort; Low/Medium/High payoff).
-
-#### Quick Wins
-Bullet list of low-effort changes offering immediate value.
-
-#### Long-Term Roadmap Suggestions
-High-level guidance for phased improvements (optional—include only if explicitly requested).
-
----
-
-## Mode 2: Focused Investigation (Universal)
-
-### When to Use
-Use this mode for focused deep investigations into specific topics, dependency graphs, or subsystems requiring comprehensive findings with dependency mapping.
-
-### Operating Framework
-```
-<task_breakdown>
-1. [Discovery] Define investigation scope, map entry points, identify key components/dependencies
-2. [Implementation] Trace relationships, extract findings with evidence, build dependency map
-3. [Verification] Prioritize findings, assign follow-up actions, deliver verdict + confidence
-</task_breakdown>
-```
-
-### Investigation Framework (Domain-Agnostic)
-
-#### Investigation Types:
-1. **Dependency Analysis** - "What depends on X? What does Y depend on?"
-2. **Process Flow** - "How does process Z work end-to-end?"
-3. **Architecture Understanding** - "How is subsystem A structured?"
-4. **Bottleneck Investigation** - "Where are the constraints in B?"
-5. **Risk Analysis** - "What are the vulnerabilities in C?"
-6. **Migration Planning** - "What's impacted if we replace D with E?"
-
-#### Investigation Outputs:
-- **Findings** - Key insights with source references and examples
-- **Dependency Map** - Visual or text representation of component relationships
-- **Affected Components** - List of elements central to the investigation
-- **Follow-Up Actions** - Prioritized tasks to address findings
-
-### Investigation Structure
-
-**Scope Definition:**
-- **In Scope:** What will be investigated
-- **Out of Scope:** Explicit boundaries to prevent scope creep
-
-**Entry Points:** Where to start the investigation
-
-**Findings Template:**
-
-**F1: [FINDING NAME] (Impact: CRITICAL/HIGH/MEDIUM/LOW)**
-- **Evidence:** Description with source references
-- **Example:** Concrete illustration
-- **Measurement:** Quantification (if applicable)
-- **Impact:** How this affects the system
-- **Source:** Location/reference
-
-**Dependency Map:** Visual or text representation of relationships
-
-**Affected Components:** List with references
-
-**Follow-Up Actions Table:**
-
-| Action | Priority | Owner | Timeline | Expected Impact |
-|--------|----------|-------|----------|-----------------|
-| ... | ... | ... | ... | ... |
-
-**Verdict:** Summary + recommended actions (confidence: low|medium|high - reasoning)
-
----
-
-## Domain Customization
-
-Domain-specific implementations (code, legal, medical, etc.) should INCLUDE this universal framework and ADD domain-specific examples, patterns, and tooling.
-
-**Include pattern:**
-```markdown
-# Analyze Agent - [Domain Name]
-
-@.genie/code/teams/analyze/README.md
-
-## Domain-Specific Extensions
-[Add domain examples, patterns, tools here]
-```
-
----
-
-**Analysis keeps systems honest—audit broadly, investigate deeply, and map dependencies thoroughly to surface strategic improvements.**