wip: alpha

Author: czxtm

.envrc

@@ -3,6 +3,8 @@
 export DIRENV_WARN_TIMEOUT=20s
 export NIX_CONFIG='pure-eval = false'
 
+echo "$PWD" > .stackpanel-root
+
 # Use flake-based devenv (via nix develop)
 # This dogfoods our own flake-parts + devenv integration
 use flake . --no-pure-eval --impure

.github/workflows/devenv-cache.yml

@@ -41,7 +41,7 @@ jobs:
         with:
           extra_nix_config: |
             accept-flake-config = true
-            extra-substituters = https://devenv.cachix.org https://stackpanel.cachix.org
+            extra-substituters = https://devenv.cachix.org https://darkmatter.cachix.org
             extra-trusted-public-keys = devenv.cachix.org-1:w1cLUi8dv3hnoSPGAuibQv+f9TZLr6cv/Hm9XgU50cw= darkmatter.cachix.org-1:FM0VM+D2fvMt8R899nyKsAxkcwERzDVYaeJEZ9oKejQ=
 
       - name: Setup Cachix

.gitignore

@@ -13,7 +13,6 @@ build
 .env*.local
 
 # IDEs and editors
-.vscode/*
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
@@ -98,3 +97,6 @@ devenv.local.yaml
 /bts.jsonc
 
 /result
+
+# Stackpanel root marker (machine-specific)
+.stackpanel-root

.ruler/todo.md

@@ -0,0 +1,80 @@
+## Nix refactor plan: shared core + thin adapters
+
+### Goal
+- **Same functionality** in both entrypoints:
+  - `nix develop --impure --no-eval-cache`
+  - `devenv shell`
+- Make it **obvious** what is:
+  - **core logic** (reusable)
+  - **module adapter** (options + wiring)
+- Remove duplication between `nix/modules/*` and `nix/lib/*`.
+
+### Target layout (north star)
+- **`nix/lib/core/`**: shared behavior (pure-ish functions returning `{ packages, env, shellHook/enterShell, files?, warnings? }`)
+- **`nix/modules/*`**: thin adapters that:
+  - define options
+  - map `config.stackpanel.*` → `nix/lib/core/*`
+  - merge returned attrs into devenv/Nix module outputs
+- **Entrypoints**
+  - `nix/stackpanel.nix`: devenv module aggregator
+  - `nix/modules/devenv/devenv.nix`: devenv directory import entrypoint (obvious import path)
+  - `nix/modules/devenv.nix`: compatibility shim (only if needed)
+  - `flake.nix`: exports `flake.lib.*`, `flake.devenvModules.*` (and any module paths)
+
+### Principles
+- **Single source of truth**: implement behavior once (core), call it from both adapters.
+- **Adapters stay tiny**: avoid duplicating computation in modules.
+- **Purity by default**: impure reads must be explicit and optional.
+- **Compatibility**: prefer shims/deprecations over breaking moves.
+
+---
+
+## Todo list
+
+### Completed (already done)
+- [x] Create shared core for global services: `nix/lib/core/global-services.nix`
+- [x] Refactor `nix/lib/devshell.nix` to use shared core
+- [x] Refactor `nix/modules/global-services.nix` to use shared core
+- [x] Add obvious devenv import path: `nix/modules/devenv/devenv.nix`
+- [x] Add compatibility shim: `nix/modules/devenv.nix`
+- [x] Eval sanity checks:
+  - [x] `nix eval '.#devenvModules.default'`
+  - [x] `nix eval '.#lib'`
+  - [x] `nix eval '.#nixosModules.default'`
+
+### Next (core parity module-by-module) - COMPLETED
+- [x] **Ports**: moved deterministic port computation into `nix/lib/core/ports.nix`; `nix/modules/ports.nix` now uses shared core.
+- [x] **Caddy**: module already uses `nix/lib/caddy.nix` as the single source of truth; no duplicated behavior.
+- [x] **Network / Step CA**: module already uses `nix/lib/network.nix` as the single source of truth.
+- [x] **AWS**: module already uses `nix/lib/aws.nix` as the single source of truth.
+- [x] **Theme / starship**: module already uses `nix/lib/theme.nix` as the single source of truth.
+- [x] **IDE integration**:
+  - [x] Already separates "pure generation" vs "impure merge existing settings" as explicit options (`existing-settings-path`)
+  - [x] Module only wires + writes files; `nix/lib/integrations/ide.nix` generates content
+
+### Optional (high-leverage)
+- [ ] Centralize shared option types/defaults in `nix/lib/modules/options.nix` (or `nix/modules/options/`) so both adapters share one schema.
+- [ ] Update docs to recommend `stackpanel/nix/modules/devenv` import path everywhere.
+
+---
+
+## Summary of Changes (2024-12-23)
+
+### Files Created
+- `nix/lib/core/ports.nix`: Pure port computation library with functions:
+  - `computeBasePort`: Deterministic port from project name
+  - `computeServicePort`: Port for a service by index
+  - `computeServicesWithPorts`: Compute ports for a list of services
+  - `mkServicesByKey`: Create lookup attrset by service key
+  - `mkServiceEnvVars`: Generate environment variables for services
+  - `mkPortsConfig`: Convenience function for full port configuration
+
+### Files Modified
+- `nix/modules/ports.nix`: Now imports and uses `nix/lib/core/ports.nix` for all computation
+- `nix/lib/default.nix`: Added `ports` export for port computation utilities
+- `nix/lib/devshell.nix`: Added `ports` export for mkShell users
+
+### Architecture
+The codebase now follows a consistent pattern where:
+1. **Core libraries** (`nix/lib/core/*.nix`, `nix/lib/*.nix`): Pure functions that implement behavior
+2. **Modules** (`nix/modules/*.nix`): Thin adapters that define options and call core libraries

.rules

@@ -1,17 +1,3 @@
-# Ultracite Code Standards
-
-This project uses **Ultracite**, a zero-config Biome preset that enforces strict code quality standards through automated formatting and linting.
-
-## Quick Reference
-
-- **Format code**: `npx ultracite fix`
-- **Check for issues**: `npx ultracite check`
-- **Diagnose setup**: `npx ultracite doctor`
-
-Biome (the underlying engine) provides extremely fast Rust-based linting and formatting. Most issues are automatically fixable.
-
----
-
 ## Core Principles
 
 Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
@@ -107,17 +93,4 @@ Write code that is **accessible, performant, type-safe, and maintainable**. Focu
 - Don't use `.only` or `.skip` in committed code
 - Keep test suites reasonably flat - avoid excessive `describe` nesting
 
-## When Biome Can't Help
-
-Biome's linter will catch most issues automatically. Focus your attention on:
-
-1. **Business logic correctness** - Biome can't validate your algorithms
-2. **Meaningful naming** - Use descriptive names for functions, variables, and types
-3. **Architecture decisions** - Component structure, data flow, and API design
-4. **Edge cases** - Handle boundary conditions and error states
-5. **User experience** - Accessibility, performance, and usability considerations
-6. **Documentation** - Add comments for complex logic, but prefer self-documenting code
-
 ---
-
-Most formatting and common issues are automatically fixed by Biome. Run `npx ultracite fix` before committing to ensure compliance.

.stackpanel/gen/schemas/secrets/app-config.schema.json

@@ -1 +1,33 @@
-"{\"$id\":\"https://stackpanel.dev/schemas/secrets/app-config.json\",\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"additionalProperties\":false,\"description\":\"Per-app configuration for codegen and settings\",\"examples\":[{\"codegen\":{\"language\":\"typescript\",\"path\":\"packages/api/src/env.ts\"}}],\"properties\":{\"codegen\":{\"additionalProperties\":false,\"description\":\"Code generation settings for typed env access\",\"properties\":{\"language\":{\"description\":\"Target language for generated code (null to disable)\",\"enum\":[\"typescript\",\"python\",\"go\",null],\"type\":[\"string\",\"null\"]},\"path\":{\"description\":\"Output path for generated code (relative to repo root)\",\"examples\":[\"packages/api/src/env.ts\",\"apps/server/env.py\",\"internal/env/env.go\"],\"type\":\"string\"}},\"required\":[\"language\",\"path\"],\"type\":\"object\"}},\"title\":\"Stackpanel App Secrets Config\",\"type\":\"object\"}"
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "description": "Per-app secrets and codegen config (.stackpanel/secrets/apps/*/config.yaml)",
+  "properties": {
+    "codegen": {
+      "additionalProperties": false,
+      "description": "Code generation settings for type-safe env access",
+      "properties": {
+        "language": {
+          "description": "Target language for generated code",
+          "enum": [
+            "typescript",
+            "python",
+            "go"
+          ],
+          "type": "string"
+        },
+        "path": {
+          "description": "Output path relative to project root (e.g., packages/api/src/env.ts)",
+          "type": "string"
+        }
+      },
+      "required": [
+        "language",
+        "path"
+      ],
+      "type": "object"
+    }
+  },
+  "title": "App Secrets Configuration",
+  "type": "object"
+}

.stackpanel/gen/schemas/secrets/config.schema.json

@@ -1 +1,30 @@
-"{\"$id\":\"https://stackpanel.dev/schemas/secrets/config.json\",\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"additionalProperties\":false,\"description\":\"Global configuration for the stackpanel secrets module\",\"properties\":{\"backend\":{\"default\":\"vals\",\"description\":\"Backend for secret resolution.\\n- vals: Multi-backend resolver (SOPS, AWS, 1Password, Vault, Doppler)\\n- sops: Direct SOPS usage only\",\"enum\":[\"vals\",\"sops\"],\"type\":\"string\"},\"defaultEnvironments\":{\"default\":[\"dev\",\"staging\",\"prod\"],\"description\":\"Default environments for all apps\",\"items\":{\"type\":\"string\"},\"type\":\"array\"},\"generatePlaceholders\":{\"default\":true,\"description\":\"Generate placeholder .yaml files for each app/environment\",\"type\":\"boolean\"},\"secretsDir\":{\"default\":\"secrets\",\"description\":\"Directory for encrypted secrets files (relative to repo root)\",\"type\":\"string\"}},\"title\":\"Stackpanel Secrets Config\",\"type\":\"object\"}"
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "description": "Global secrets configuration (.stackpanel/secrets/config.yaml)",
+  "properties": {
+    "backend": {
+      "default": "sops",
+      "description": "Secrets backend to use (sops or vals)",
+      "enum": [
+        "sops",
+        "vals"
+      ],
+      "type": "string"
+    },
+    "default-environments": {
+      "default": [
+        "dev",
+        "staging",
+        "prod"
+      ],
+      "description": "Default environments created for new apps",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "title": "Stackpanel Secrets Configuration",
+  "type": "object"
+}

.stackpanel/gen/schemas/secrets/env.schema.json

@@ -1 +1,38 @@
-"{\"$id\":\"https://stackpanel.dev/schemas/secrets/env.json\",\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"additionalProperties\":false,\"definitions\":{\"SecretEntry\":{\"additionalProperties\":false,\"properties\":{\"default\":{\"description\":\"Default value (only for non-required secrets)\",\"type\":\"string\"},\"description\":{\"description\":\"Description of what this secret is for\",\"type\":\"string\"},\"required\":{\"default\":true,\"description\":\"Whether this secret is required\",\"type\":\"boolean\"},\"sensitive\":{\"default\":true,\"description\":\"Whether this secret is sensitive (masked in logs)\",\"type\":\"boolean\"}},\"type\":\"object\"}},\"description\":\"Per-environment configuration (dev.yaml, staging.yaml, prod.yaml)\",\"examples\":[{\"extraKeys\":[],\"schema\":{\"DEBUG\":{\"required\":false,\"sensitive\":false},\"LOG_LEVEL\":{\"default\":\"debug\"}},\"users\":[\"alice\",\"bob\",\"charlie\"]},{\"extraKeys\":[\"age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p\"],\"schema\":{\"SENTRY_DSN\":{\"required\":true,\"sensitive\":true}},\"users\":[\"alice\"]}],\"properties\":{\"extraKeys\":{\"description\":\"Additional AGE keys for CI systems, servers, etc.\",\"items\":{\"pattern\":\"^age1[a-z0-9]{58}$\",\"type\":\"string\"},\"type\":\"array\"},\"schema\":{\"additionalProperties\":{\"$ref\":\"#/definitions/SecretEntry\"},\"description\":\"Environment-specific schema additions/overrides\",\"type\":\"object\"},\"users\":{\"description\":\"User names (from users.yaml) who can access this environment's secrets\",\"items\":{\"type\":\"string\"},\"type\":\"array\"}},\"title\":\"Stackpanel Environment Config\",\"type\":\"object\"}"
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "description": "Environment-specific secrets (.stackpanel/secrets/apps/*/{dev,staging,prod}.yaml)",
+  "properties": {
+    "schema": {
+      "additionalProperties": {
+        "additionalProperties": false,
+        "properties": {
+          "default": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "sensitive": {
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
+      "description": "Environment-specific schema overrides (merged with common.yaml)",
+      "type": "object"
+    },
+    "users": {
+      "description": "Usernames (from users.yaml) who can access this environment",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "title": "Environment Secrets",
+  "type": "object"
+}

.stackpanel/gen/schemas/secrets/schema.schema.json

@@ -1 +1,31 @@
-"{\"$id\":\"https://stackpanel.dev/schemas/secrets/schema.json\",\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"additionalProperties\":{\"$ref\":\"#/definitions/SecretEntry\"},\"definitions\":{\"SecretEntry\":{\"additionalProperties\":false,\"properties\":{\"default\":{\"description\":\"Default value (only for non-required secrets)\",\"type\":\"string\"},\"description\":{\"description\":\"Description of what this secret is for\",\"type\":\"string\"},\"required\":{\"default\":true,\"description\":\"Whether this secret is required\",\"type\":\"boolean\"},\"sensitive\":{\"default\":true,\"description\":\"Whether this secret is sensitive (masked in logs)\",\"type\":\"boolean\"}},\"type\":\"object\"}},\"description\":\"Schema for secrets entries (common.yaml)\",\"examples\":[{\"DATABASE_URL\":{\"description\":\"PostgreSQL connection string\",\"required\":true,\"sensitive\":true},\"LOG_LEVEL\":{\"default\":\"info\",\"required\":false,\"sensitive\":false}}],\"title\":\"Stackpanel Secrets Schema\",\"type\":\"object\"}"
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {
+    "additionalProperties": false,
+    "description": "Secret variable definition",
+    "properties": {
+      "default": {
+        "description": "Default value (only for non-sensitive secrets)",
+        "type": "string"
+      },
+      "description": {
+        "description": "Human-readable description of this secret",
+        "type": "string"
+      },
+      "required": {
+        "default": false,
+        "description": "Whether this secret must be set",
+        "type": "boolean"
+      },
+      "sensitive": {
+        "default": true,
+        "description": "Whether to mask value in logs and output",
+        "type": "boolean"
+      }
+    },
+    "type": "object"
+  },
+  "description": "Schema for secret variables (.stackpanel/secrets/apps/*/common.yaml)",
+  "title": "Secret Schema",
+  "type": "object"
+}

.stackpanel/gen/schemas/secrets/users.schema.json

@@ -1 +1,29 @@
-"{\"$id\":\"https://stackpanel.dev/schemas/secrets/users.json\",\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"additionalProperties\":{\"$ref\":\"#/definitions/User\"},\"definitions\":{\"User\":{\"additionalProperties\":false,\"properties\":{\"admin\":{\"default\":false,\"description\":\"Admins can decrypt all secrets across all environments\",\"type\":\"boolean\"},\"github\":{\"description\":\"GitHub username (for display/lookup)\",\"type\":\"string\"},\"pubkey\":{\"description\":\"AGE public key (starts with age1...)\",\"pattern\":\"^age1[a-z0-9]{58}$\",\"type\":\"string\"}},\"required\":[\"pubkey\"],\"type\":\"object\"}},\"description\":\"Team members and their AGE public keys for secrets access\",\"examples\":[{\"alice\":{\"admin\":true,\"github\":\"alice\",\"pubkey\":\"age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p\"},\"bob\":{\"github\":\"bobdev\",\"pubkey\":\"age1tpqft77pxl5qm7d7u0j5gsyvxzrxdg4krqjr3uvps7y0vfsueyeqg5ztsa\"}}],\"title\":\"Stackpanel Secrets Users\",\"type\":\"object\"}"
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {
+    "additionalProperties": false,
+    "properties": {
+      "admin": {
+        "default": false,
+        "description": "Admins can decrypt secrets for all environments",
+        "type": "boolean"
+      },
+      "github": {
+        "description": "GitHub username (for key lookup)",
+        "type": "string"
+      },
+      "pubkey": {
+        "description": "AGE public key (starts with age1...)",
+        "pattern": "^age1[a-z0-9]{58}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "pubkey"
+    ],
+    "type": "object"
+  },
+  "description": "Team members with access to secrets (.stackpanel/secrets/users.yaml)",
+  "title": "Stackpanel Users",
+  "type": "object"
+}