feat: Project maturity improvements, test coverage, cleanups

.cursor/rules/SHADES_COMPONENTS.mdc

@@ -374,7 +374,6 @@ Export pages from an index file:
 // frontend/src/pages/index.ts
 export * from './dashboard.js'
 export * from './login.js'
-export * from './hello-world.js'
 ```
 
 ## Application Entry Point

.cursor/rules/TESTING_GUIDELINES.mdc

@@ -191,6 +191,56 @@ describe('ObservableValue', () => {
 })
 ```
 
+## Backend Service Testing with Test Helpers
+
+### Using `withTestInjector`
+
+For testing backend services and REST actions, use the shared test helpers:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { getRepository } from '@furystack/repository'
+import { ServiceDefinition, ServiceStatus } from 'common'
+
+import { withTestInjector, createMockActionContext } from '../test-helpers.js'
+
+describe('MyAction', () => {
+  it('should return data for valid request', () =>
+    withTestInjector(async ({ injector, elevated }) => {
+      // Seed test data
+      await getRepository(elevated).getDataSetFor(ServiceDefinition, 'id').add(elevated, {
+        id: 'svc-1',
+        stackName: 'test-stack',
+        displayName: 'Test Service',
+        // ... other required fields
+      })
+
+      // Mock external services via setExplicitInstance
+      const mockService = { someMethod: vi.fn().mockResolvedValue('result') }
+      injector.setExplicitInstance(mockService as unknown as MyService, MyService)
+
+      // Create and execute action
+      const ctx = createMockActionContext({
+        injector: elevated,
+        urlParams: { id: 'svc-1' },
+      })
+      const result = await myAction(ctx)
+
+      // Assert
+      expect(result.chunk.status).toBe(200)
+    }),
+  )
+})
+```
+
+### Key patterns
+
+- `withTestInjector` provides an `injector` + `elevated` (system-level) context with all InMemoryStores pre-configured
+- `createMockActionContext` creates a typed request context for REST action testing
+- Use `getRepository(elevated).getDataSetFor(...)` to seed and verify data
+- Use `injector.setExplicitInstance(mock, ServiceClass)` for mocking DI services
+- Both injectors are automatically disposed after each test
+
 ## E2E Testing with Playwright
 
 ### Test File Location
@@ -278,9 +328,8 @@ test.describe('Authentication', () => {
     await page.locator('button', { hasText: 'Login' }).click()
 
     // Verify logged in state
-    const welcomeTitle = page.locator('hello-world div h2')
-    await expect(welcomeTitle).toBeVisible()
-    await expect(welcomeTitle).toHaveText('Hello, testuser !')
+    const dashboard = page.locator('page-dashboard')
+    await expect(dashboard).toBeVisible()
 
     // Logout
     const logoutButton = page.locator('shade-app-bar button >> text="Log Out"')

.env.example

@@ -1 +1,36 @@
+# PostgreSQL connection string (required)
 DATABASE_URL=postgres://stackcraft:stackcraft@localhost:5433/stackcraft
+
+# Backend HTTP server port
+# APP_SERVICE_PORT=9090
+
+# MCP (Model Context Protocol) server port
+# MCP_PORT=9091
+
+# Allowed CORS origins (comma-separated)
+# CORS_ORIGINS=http://localhost:8080
+
+# Base64-encoded 256-bit key for encrypting sensitive values.
+# If unset, a key file is auto-generated in ~/.stack-craft/
+# STACK_CRAFT_ENCRYPTION_KEY=
+
+# Minimum log level: verbose | debug | information | warning | error | fatal
+# LOG_LEVEL=verbose
+
+# Timeout (ms) when stopping a service before sending SIGKILL
+# STOP_TIMEOUT_MS=10000
+
+# Timeout (ms) during shutdown before force-killing child processes
+# SHUTDOWN_KILL_TIMEOUT_MS=5000
+
+# Interval (ms) for flushing buffered process log lines to storage
+# LOG_FLUSH_INTERVAL_MS=100
+
+# MCP session time-to-live (ms) before automatic cleanup
+# MCP_SESSION_TTL_MS=1800000
+
+# Maximum number of concurrent MCP sessions
+# MCP_MAX_SESSIONS=50
+
+# Interval (ms) between MCP stale-session sweeps
+# MCP_SESSION_SWEEP_MS=60000

.yarn/changelogs/common.76693fda.md

@@ -0,0 +1,20 @@
+<!-- version-type: patch -->
+# common
+
+## ♻️ Refactoring
+
+- Normalized service relations — extracted `prerequisiteIds` and `prerequisiteServiceIds` from `ServiceDefinition` into dedicated `ServiceDependencyLink` and `ServicePrerequisiteLink` join entities
+- Added `ServiceRelations` type to `ServiceView`, separating relational data from entity definitions
+- Added `mergeServiceView()` utility for composing a `ServiceView` from separate data-store entities with sensible defaults for missing pieces
+
+## 📚 Documentation
+
+- Added JSDoc to all API endpoint definitions across all API modules (identity, services, stacks, system, prerequisites, tokens, github-repositories, install)
+
+## 🧪 Tests
+
+- Added unit tests for `mergeServiceView()` covering full views, partial data, and missing relations
+
+## 📦 Build
+
+- Regenerated JSON schemas to reflect normalized model structure

.yarn/changelogs/frontend.76693fda.md

@@ -0,0 +1,23 @@
+<!-- version-type: patch -->
+# frontend
+
+## 🐛 Bug Fixes
+
+- Fixed service URL resolution from `.env` file configuration
+- Fixed service selection behavior in the services list
+
+## ♻️ Refactoring
+
+- Restructured layout components into `layout/` module (`sidebar`, `breadcrumbs`, `header`, `body`, `layout`) with barrel export
+- Split monolithic `service-form.tsx` into focused subcomponents: `dependency-selector`, `prerequisite-selector`, and `file-list`
+- Decomposed `service-detail.tsx` into a tabbed interface module with dedicated tabs (overview, configuration, logs, history) and an action bar
+- Refactored dashboard into stack-oriented views (`stack-dashboard`, `stack-list-dashboard`, `service-row`)
+- Split create-service wizard into `index.tsx` and `setup-step.tsx`
+- Moved shared components (`github-logo`, `log-line`, `log-viewer`) into `shared/` module
+- Removed standalone theme-switch component — theme selection moved to the settings page
+- Refactored branch-selector component for positioning and scroll behavior
+
+## 🧪 Tests
+
+- Added unit tests for `session`, `theme-registry`, `install-service`, `environment-variable-service`, and `apply-client-find-options`
+- Added form tests for `github-repo-form`, `prerequisite-form`, `stack-form`, `service-form/validators`, `create-admin-step`, `import-stack`, `api-tokens-section`, and `password-change-form`

.yarn/changelogs/monaco-mfe.76693fda.md

@@ -0,0 +1,15 @@
+<!-- version-type: patch -->
+# monaco-mfe
+
+## ✨ Features
+
+- Added Monaco Editor Micro Frontend — a standalone MFE that the host frontend loads at runtime to render code editors
+- Exposed `create()` / `destroy()` lifecycle API for mounting and unmounting the editor instance
+- Added reactive `props` setter that applies theme, `readOnly`, and `value` changes without remounting the editor
+- Added JSON schema validation support via `registerSchema()` for in-editor diagnostics
+- Added runtime theme support with `applyTheme()`, accepting theme data from the host application
+
+## 📦 Build
+
+- Configured Vite library build outputting a single ES module (`dist/index.js`) with source maps
+- Configured Monaco web workers for JSON language support via dynamic `import()` with Vite worker plugins

.yarn/changelogs/service.76693fda.md

@@ -0,0 +1,31 @@
+<!-- version-type: patch -->
+# service
+
+## ✨ Features
+
+- Added `GET /system/health` endpoint returning database connectivity and overall system health status
+- Added HTTP request logging middleware that logs method, URL, status, and duration with log level based on status code (verbose for 2xx/3xx, warning for 4xx, error for 5xx)
+
+## 🐛 Bug Fixes
+
+- Fixed session state persistence to PostgreSQL
+- Fixed branch checkout behavior when switching service branches
+
+## ♻️ Refactoring
+
+- Normalized data model with `ServiceDependencyLink` and `ServicePrerequisiteLink` join tables, replacing inline arrays on `ServiceDefinition`
+- Split `ProcessManager` into single-responsibility services: `ProcessRunner` (process lifecycle), `ServiceStatusManager` (state transitions), `StaleStateReconciler` (orphan detection), `ServiceGraphResolver` (dependency ordering), `ServiceEnvResolver` (environment variable resolution), and `ProcessIOAttacher` (stdout/stderr handling)
+- Extracted `GitOperationsService` for pull, install, and build operations
+- Added `DomainError` hierarchy (`NotFoundError`, `ConflictError`, `ValidationError`) for structured error handling across REST actions
+- Added `FilteredConsoleLogger` for configurable log level filtering
+- Added `getServiceOrThrow()` utility for consistent service lookup with typed error handling
+- Updated import/export actions to handle normalized service relations (dependency and prerequisite links)
+- Refactored data-store setup into dedicated `init-models`, `models`, and `db-options` modules
+
+## 🧪 Tests
+
+- Added unit tests for new services: `process-runner`, `service-env-resolver`, `service-graph-resolver`, `service-status-manager`, `stale-state-reconciler`, `git-head-watcher`, `git-watcher`, `websocket-service`, `shutdown-handler`
+- Added tests for new utilities: `domain-error`, `filtered-console-logger`, `get-service-or-throw`, `resolve-path`, `resolve-service-cwd`, `encrypt-existing-secrets`
+- Added REST action tests: `health-check`, `service-logs`, `service-history`, `clear-service-logs`, `prerequisite-lifecycle`, `evaluate-prerequisites`, `password-reset`, `validate-repo`, `get-service-status`, `post-install`, `setup-log-store`, `db-options`
+- Added MCP tests: `mcp-server`, `setup-mcp`, `mcp-helpers`, `system-tools`
+- Expanded existing test coverage for `process-manager`, `service-checkout`, `service-lifecycle`, `service-branches`, `check-prerequisite`, `import-export-actions`, `check-env-availability`, `tokens-rest-api`, `log-storage-service`, `git-service`, and `get-cors-options`

.yarn/changelogs/stack-craft.76693fda.md

@@ -0,0 +1,17 @@
+<!-- version-type: patch -->
+# stack-craft
+
+## 📚 Documentation
+
+- Added troubleshooting guide covering database connectivity, port conflicts, and environment configuration issues
+- Added `CONTRIBUTING.md` with development workflow and contribution guidelines
+- Added `CODE_OF_CONDUCT.md` with Contributor Covenant
+- Added `SECURITY.md` with vulnerability reporting procedures
+- Added `.env.example` with documented environment variable defaults
+- Expanded `README.md` with architecture overview and getting-started instructions
+
+## 🧪 Tests
+
+- Expanded E2E dogfooding test suite with prerequisite, repository, and service management flows
+- Split E2E helpers into domain-specific modules (`login`, `notification`, `prerequisite`, `repository`, `service`, `sidebar`, `stack`)
+- Refactored smoke tests for updated routing and layout structure

.yarn/versions/76693fda.yml

@@ -0,0 +1,6 @@
+releases:
+  common: patch
+  frontend: patch
+  monaco-mfe: patch
+  service: patch
+  stack-craft: patch

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue on the
+[GitHub repository](https://github.com/furystack/stack-craft/issues).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations