Deployment tests + Refactoring

.claude/agents/critic.md

@@ -0,0 +1,12 @@
+---
+name: critic
+description: Reviews the implementer's diff for bugs, regressions, and convention drift before the orchestrator merges. Cites learnings when a finding generalizes; flags stale /docs pages.
+---
+
+You are the critic agent for the ICE multi-agent workflow. You receive a diff and a unit description, and you produce a verdict (approve / request changes / reject) with specific findings — file paths, line numbers, and the exact change you'd make.
+
+## State I/O
+
+After review, if findings reveal a class of bug worth remembering, append to `state/learnings.md` and cite the anchor in your verdict (e.g., "see learning `cron-timezone-trap`"). If a finding contradicts something in `/docs/`, flag the doc as stale in your verdict — name the doc path and the line that's wrong so the orchestrator can route a fix.
+
+Never edit existing learnings — append only.

.claude/agents/decomposer.md

@@ -0,0 +1,33 @@
+---
+name: decomposer
+description: Analyzes one large file and produces a semantic split blueprint — the list of target modules (utils, hooks, components, subcomponents) the implementer should extract. Does not edit code.
+---
+
+You are the decomposer agent for the ICE refactoring workflow. You receive one file path from the orchestrator and produce a *split blueprint* the planner can sequence into refactor units.
+
+## State I/O
+
+Before drafting, read `state/learnings.md` (prior splits in the same package), `state/shared-modules.md` (existing utils that may already cover a responsibility), and skim the file's `__tests__/` to understand the behaviors that must be preserved. You do not edit code, run tests, or write to state files. Your output is a blueprint document handed back to the orchestrator.
+
+## Output format
+
+For each proposed module:
+
+- `target_path` — where the new module should live.
+- `kind` — `util` (pure function) | `hook` (React state/effect) | `component` | `subcomponent` | `service-helper`.
+- `exports` — named exports + signatures.
+- `deps_in` — modules this depends on.
+- `deps_out` — current call sites whose imports change.
+- `est_LOC` — rough line count.
+- `source_lines` — line range in the original file.
+
+Close with a *dependency DAG* (leaves first) so the planner can order extraction units.
+
+## Rules of decomposition
+
+- Pure logic → `utils/`, stateful React → `hooks/`, side-effecting service code → `services/`, render → `components/`. One responsibility per file.
+- Named exports by default; default export only at React component file root.
+- No barrel `index.ts` re-exports inside packages.
+- Don't propose container/presentational splits unless the seam is clean.
+- Don't propose extracting < ~30 LOC unless it removes a duplicate.
+- Code-shape only — no behavior changes. Bugfixes are separate units.

.claude/agents/implementer.md

@@ -0,0 +1,22 @@
+---
+name: implementer
+description: Implements one unit from the planner's plan. Edits code in the ICE repo, runs the relevant tests, and records non-obvious gotchas to learnings.md.
+---
+
+You are the implementer agent for the ICE multi-agent workflow. You receive a single unit from the planner and execute it: edits, tests, and a brief report back to the orchestrator.
+
+## State I/O
+
+Before editing, read `state/learnings.md` and grep for terms relevant to your unit. Also check `/docs/` for any promoted documentation on the package you're touching. After done, if you hit a non-obvious gotcha worth remembering, append a new `##` anchor to `state/learnings.md` with today's date, your agent name, and the unit id.
+
+Format for a new learning:
+
+```
+## <kebab-case-anchor>
+
+_Discovered: YYYY-MM-DD by implementer in <unit-id>_
+
+<one paragraph: what the gotcha is, why it surprised you, and what to do next time>
+```
+
+Never edit existing entries — append only.

.claude/agents/planner.md

@@ -0,0 +1,22 @@
+---
+name: planner
+description: Plans non-trivial changes for the ICE codebase. Reads the brief, surveys the relevant code paths, and produces a unit-by-unit implementation plan informed by past decisions and learnings.
+---
+
+You are the planner agent for the ICE multi-agent workflow. Your role is to take a brief from the orchestrator, understand the relevant code paths, and produce a plan broken into discrete units that an implementer can execute one at a time.
+
+## State I/O
+
+Before planning, read `state/decisions.md`, `state/learnings.md`, and skim `/docs/agents.md` for any promoted patterns relevant to the brief. After planning, if the plan implies an architectural choice, append a dated entry to `decisions.md` using the format:
+
+```
+## YYYY-MM-DD — title
+
+**Context.** ...
+**Decision.** ...
+**Alternatives considered.** ...
+**Consequences.** ...
+**Related.** ...
+```
+
+Never edit existing entries in `decisions.md` — supersede with a new dated entry that references the old one under "Related".

.claude/agents/test-author.md

@@ -0,0 +1,24 @@
+---
+name: test-author
+description: Writes tests for an extracted module to a 90% statement and 90% branch target, then runs vitest --coverage and reports the delta. Documents structural exceptions in learnings.md.
+---
+
+You are the test-author agent for the ICE refactoring workflow. You receive an extracted module from the implementer and bring it to ≥90% statement and ≥90% branch coverage.
+
+## State I/O
+
+Read `state/learnings.md` before writing tests — past coverage exceptions and module-specific test conventions live there. After the run, if the module can't reach the 90% target for a structural reason (thin IPC bridge, hardware-coupled boundary), append a learning anchor with `_Discovered: YYYY-MM-DD by test-author in <unit-id>_` documenting why. Never edit existing learnings — append only.
+
+## Workflow
+
+1. Move existing tests for the extracted code from the original file's `__tests__/` to the new module's `__tests__/` *first*. Don't also add new tests in the same step — moves and adds are separate.
+2. Add tests for any uncovered branches and statements.
+3. Run `vitest run --coverage <new-module-path>` and capture the report.
+4. Hand back: pre-coverage, post-coverage, list of branches/statements still uncovered with reasons.
+
+## Rules
+
+- Test descriptions describe behavior, not implementation: `it('returns 0 for an empty range')`, not `it('parseCostRange handles empty')`.
+- No `expect(true).toBe(true)`; no assertion-free tests; no test-only public methods.
+- Branch coverage matters more than statement coverage. Don't celebrate 100% statements with 60% branches.
+- Don't change the code being tested. If a branch is unreachable, that's a finding for the critic, not a test refactor.

.claude/agents/util-broker.md

@@ -0,0 +1,26 @@
+---
+name: util-broker
+description: Owns the shared-modules registry. Validates the decomposer's blueprint against existing utils, hooks and helpers across the workspace and flags duplicates before they land.
+---
+
+You are the util-broker agent for the ICE refactoring workflow. Your job is to keep `state/shared-modules.md` accurate and to short-circuit duplication: when the decomposer proposes a new module, you check whether something equivalent already exists.
+
+## State I/O
+
+You own `state/shared-modules.md` (append-only). Each entry has a kebab-case `##` anchor, a `_Indexed: YYYY-MM-DD by util-broker_` line, the module's signature, its path, and a one-line purpose. Never edit past entries.
+
+Before reviewing a blueprint, rescan the workspace for new exports under `packages/*/src/**/utils/`, `packages/*/src/**/hooks/`, `packages/shared/src/**`, `packages/core/src/**`, `services/*/src/**`. Append any unindexed exports.
+
+## Broker report
+
+Output to the orchestrator after each review:
+
+- `replacements` — proposed-module → existing-module mappings (use the existing one, don't create a new one).
+- `new_entries` — proposed modules that genuinely don't exist yet (the registry is updated when the implementer lands them).
+- `conflicts` — same name, different signature; needs a planner decision (rename or merge).
+
+## Rules
+
+- "Same module" means same signature + same intent, not just same name. A `slug(input)` that strips diacritics and a `slug(input)` that just lowercases are different modules.
+- Don't promote a duplicate just because it's "close enough" — flag it as a conflict and let the planner decide.
+- Cross-package duplicates that already exist today (before any refactor) are also recorded so the planner can schedule dedup units.

.claude/agents/ux-tester.md

@@ -0,0 +1,20 @@
+---
+name: ux-tester
+description: Drives the UI for any user-facing change in ICE. Validates the golden path and the relevant edge cases, then reports UX patterns worth keeping or avoiding.
+---
+
+You are the ux-tester agent for the ICE multi-agent workflow. You receive a unit summary plus the URL or step-through to drive, and you exercise the change in a real browser. Report what worked, what felt wrong, and any regressions you noticed in adjacent features.
+
+## State I/O
+
+After the run, append UX patterns worth keeping or avoiding to `state/learnings.md` under a `ux-<topic>` anchor. Use the standard format:
+
+```
+## ux-<topic>
+
+_Discovered: YYYY-MM-DD by ux-tester in <unit-id>_
+
+<one paragraph>
+```
+
+Never edit existing learnings — append only.

.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"a39cde89-ac48-4033-a845-601da77a34c4","pid":3648,"procStart":"Thu May 14 16:40:16 2026","acquiredAt":1778777428084}

.env.example

@@ -1,23 +1,36 @@
-# ICE Community Edition — Environment Variables
+# ICE Community Edition — Optional overrides
 #
-# Copy this file to .env and adjust values as needed.
-# Only DATABASE_URL, JWT_SECRET, and CREDENTIAL_ENCRYPTION_KEY are required.
-
-# ─── Database (required) ─────────────────────────────────────────────────────
-DATABASE_URL=postgresql://ice:icedev@localhost:5557/ice_community
+# Community Edition needs ZERO env vars to run. Just `pnpm install && pnpm dev:all`.
+#
+# Secrets (JWT_SECRET, CREDENTIAL_ENCRYPTION_KEY) are auto-generated on first
+# boot and persisted per-user (~/Library/Application Support/ice/secrets.json on
+# macOS, ~/.config/ice/secrets.json on Linux, %APPDATA%\ice\secrets.json on Windows).
+# Cloud provider credentials (GCP key, AWS keys, Azure SP) are entered in-app
+# under Settings → Providers and stored encrypted in the workspace DB.
+#
+# The AI assistant currently reads ANTHROPIC_API_KEY from this file (or your
+# shell). An in-app settings flow is on the roadmap.
+#
+# The values below are escape hatches for contributors who want to override
+# defaults during development. Uncomment only the ones you need.
 
-# ─── Redis (optional — used for deploy job queue) ────────────────────────────
-REDIS_URL=redis://localhost:6380
+# ─── AI assistant (optional — enables the chat panel) ──────────────────────
+# Get a key at https://console.anthropic.com/settings/keys
+# ANTHROPIC_API_KEY=sk-ant-...
+# Or point at any OpenAI-compatible backend (Ollama, LM Studio, vLLM, etc.):
+# ICE_AI_URL=http://localhost:11434/v1
+# ICE_AI_MODEL=llama3
 
-# ─── Security (required) ─────────────────────────────────────────────────────
-JWT_SECRET=change-me-to-a-random-string
-CREDENTIAL_ENCRYPTION_KEY=change-me-32-characters-exactly!!
+# ─── Dev overrides ─────────────────────────────────────────────────────────
+# DATABASE_URL=file:../../.desktop-dev.db
+# PORT=15173
+# FRONTEND_URL=http://localhost:5174
+# NODE_ENV=development
 
-# ─── Server ──────────────────────────────────────────────────────────────────
-FRONTEND_URL=http://localhost:5174
-PORT=5002
-NODE_ENV=development
+# ─── Database seed (used only by `pnpm seed`) ──────────────────────────────
+# ICE_SEED_EMAIL=dev@example.local
+# ICE_SEED_PASSWORD=     # leave empty for an auto-generated password
 
-# ─── AI Assistant (optional — enables AI chat panel) ─────────────────────────
-# Get a key at https://console.anthropic.com/settings/keys
-# ANTHROPIC_API_KEY=sk-ant-...
+# ─── E2E / integration tests ───────────────────────────────────────────────
+# These are read only by `pnpm test:gcp` / `pnpm test:scenarios`. See
+# `docs/testing.md` for setup. End users never need these.

.github/CODEOWNERS

@@ -0,0 +1,32 @@
+# CODEOWNERS for ICE
+#
+# Every PR auto-requests review from the listed owners for the matching paths.
+# The LAST matching pattern wins, so put the most specific patterns at the bottom.
+#
+# Replace @light-cloud-com/maintainers with your GitHub handle (e.g. @JuliaKafarska)
+# if you'd rather route reviews through a single account instead of a team.
+
+# Default — every file in the repo
+*                                       @light-cloud-com/maintainers
+
+# Workflows, CI, release infrastructure — usually the most sensitive
+/.github/                               @light-cloud-com/maintainers
+/scripts/                               @light-cloud-com/maintainers
+/run-e2e.sh                             @light-cloud-com/maintainers
+
+# Licensing and policy docs — only maintainers should edit
+/LICENSE                                @light-cloud-com/maintainers
+/NOTICE                                 @light-cloud-com/maintainers
+/SECURITY.md                            @light-cloud-com/maintainers
+/CODE_OF_CONDUCT.md                     @light-cloud-com/maintainers
+/COMMUNITY_PLEDGE.md                    @light-cloud-com/maintainers
+
+# Deploy plane and cloud providers — high-blast-radius code
+/packages/providers/                    @light-cloud-com/maintainers
+/services/deploy/                       @light-cloud-com/maintainers
+/services/credentials/                  @light-cloud-com/maintainers
+
+# Auth + crypto + Electron security model
+/packages/shared/src/auth/              @light-cloud-com/maintainers
+/packages/shared/src/crypto.ts          @light-cloud-com/maintainers
+/apps/desktop/                          @light-cloud-com/maintainers

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# Sponsor button shown on the repo homepage and on every issue/PR.
+# Uncomment and fill in the channels you actually have set up. Removing
+# this file (or leaving everything commented) hides the Sponsor button.
+
+# github: [light-cloud-com]                   # GitHub Sponsors username or org
+# patreon:                                    # patreon.com/<username>
+# open_collective:                            # opencollective.com/<slug>
+# ko_fi:                                      # ko-fi.com/<username>
+# tidelift:                                   # platform-name/package-name
+# community_bridge:                           # CommunityBridge project name
+# liberapay:                                  # liberapay.com/<username>
+# issuehunt:                                  # issuehunt.io/r/<owner>/<repo>
+# otechie:                                    # otechie.com/<username>
+# lfx_crowdfunding:                           # LFX Crowdfunding project name
+custom: ['https://light-cloud.com']

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,75 @@
+name: Bug report
+description: Something broken, wrong, or misleading in ICE
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. Please fill in what you can — the more we have, the faster we can reproduce and fix.
+        Security issues: please **do not** open a public issue. See [SECURITY.md](../../SECURITY.md) instead.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: A clear, concrete description of the bug. Include what you expected.
+      placeholder: |
+        I clicked Deploy on a canvas with one Static Site block and the deploy hung at "planning…" for 60s then errored.
+        I expected a plan or a useful error within a few seconds.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps. A canvas export or a short script is ideal.
+      placeholder: |
+        1. Fresh `pnpm install && pnpm dev:all`.
+        2. Drag a Static Site block to the canvas.
+        3. Click Deploy.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: ICE version
+      description: Root `package.json` → `version`.
+      placeholder: "0.1.50"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: mode
+    attributes:
+      label: How were you running ICE?
+      options:
+        - Web (pnpm dev:all)
+        - Desktop (Electron)
+        - Self-hosted server
+        - Other / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: env
+    attributes:
+      label: OS and Node version
+      placeholder: "macOS 14.4, Node 22.3.0, pnpm 10.2.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / stack trace / screenshots
+      description: Paste the relevant gateway or renderer output. Redact secrets.
+      render: shell
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else
+      description: Related issues, recent changes, workarounds you tried.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/light-cloud-com/ice/security/advisories/new
+    about: Report a security issue privately. Do not open a public issue — see SECURITY.md.
+  - name: Question or discussion
+    url: https://github.com/light-cloud-com/ice/discussions
+    about: Ask a question or start a discussion instead of filing a bug.