refactors, cleanups, docs

Author: gallayl

.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

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

README.md

@@ -43,12 +43,12 @@ Open http://localhost:8080 in your browser. On first launch, the installer wizar
 
 Environment variables can be set in the `.env` file at the project root.
 
-| Variable                     | Default                                                      | Description                                                                                           |
-| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| `DATABASE_URL`               | `postgres://stackcraft:stackcraft@localhost:5433/stackcraft` | PostgreSQL connection string                                                                          |
-| `APP_SERVICE_PORT`           | `9090`                                                       | Backend HTTP server port                                                                              |
-| `MCP_PORT`                   | `9091`                                                       | MCP server port                                                                                       |
-| `STACK_CRAFT_ENCRYPTION_KEY` | *(auto-generated)*                                           | Base64-encoded 256-bit key for encrypting sensitive values. If unset, a key file is created in `~/.stack-craft/` |
+| Variable                     | Default                                                      | Description                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`               | `postgres://stackcraft:stackcraft@localhost:5433/stackcraft` | PostgreSQL connection string                                                                                     |
+| `APP_SERVICE_PORT`           | `9090`                                                       | Backend HTTP server port                                                                                         |
+| `MCP_PORT`                   | `9091`                                                       | MCP server port                                                                                                  |
+| `STACK_CRAFT_ENCRYPTION_KEY` | _(auto-generated)_                                           | Base64-encoded 256-bit key for encrypting sensitive values. If unset, a key file is created in `~/.stack-craft/` |
 
 ## Docker
 
@@ -70,16 +70,37 @@ docker run -p 9090:9090 \
   furystack/stack-craft
 ```
 
+## Architecture
+
+```
+                          ┌──────────────────────────┐
+                          │  Browser (Shades SPA)    │
+                          └────────┬─────────────────┘
+                                   │ REST + WebSocket
+                          ┌────────▼─────────────────┐
+  MCP Clients ──HTTP+SSE──▶  Node.js Service :9090   │
+        :9091              │  (FuryStack REST)        │
+                          └──┬──────────────┬────────┘
+                             │              │
+                    ┌────────▼──┐    ┌──────▼──────┐
+                    │ PostgreSQL│    │ File System  │
+                    │           │    │ (git, procs) │
+                    └───────────┘    └─────────────┘
+```
+
 ## Project Structure
 
 ```
 stack-craft/
 ├── common/     # Shared API type definitions and models
 ├── frontend/   # Shades-based SPA (Vite)
 ├── service/    # FuryStack REST backend (Node.js)
+├── docs/       # Documentation (troubleshooting, etc.)
 └── e2e/        # Playwright end-to-end tests
 ```
 
+See also: [frontend/README.md](frontend/README.md) for frontend-specific documentation.
+
 ## Testing
 
 ```bash
@@ -103,6 +124,20 @@ yarn test:e2e
 | `yarn format`         | Format code with Prettier                     |
 | `yarn create-schemas` | Regenerate JSON schemas from TypeScript types |
 
+## MCP Server
+
+Stack Craft includes a [Model Context Protocol](https://modelcontextprotocol.io/) server for AI assistant integration. It runs on a separate port (default `9091`) and provides tools for managing stacks, services, repositories, prerequisites, and environment variables.
+
+**Connecting:** Point your MCP client to `http://localhost:9091/mcp` using Streamable HTTP transport with a Bearer token for authentication. Create API tokens via the UI under User Settings.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the release workflow.
+
+## Troubleshooting
+
+See [docs/troubleshooting.md](docs/troubleshooting.md) for common issues and their resolutions.
+
 ## License
 
 [GPL-2.0-only](LICENSE)

SECURITY.md

@@ -0,0 +1,51 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest release published to Docker Hub is actively supported with security updates:
+
+| Version                        | Supported |
+| ------------------------------ | --------- |
+| `furystack/stack-craft:latest` | Yes       |
+| Older versions                 | No        |
+
+We recommend always running the latest image to benefit from the most recent security patches.
+
+## Reporting a Vulnerability
+
+**Please do NOT open a public GitHub issue for security vulnerabilities.**
+
+Instead, report vulnerabilities privately by filing a security advisory:
+
+> [https://github.com/furystack/stack-craft/security/advisories/new](https://github.com/furystack/stack-craft/security/advisories/new)
+
+When reporting, please include:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof-of-concept
+- Affected component(s) and version(s)
+- Any suggested mitigation or fix
+
+## Response Timeline
+
+- **Acknowledgement**: within 72 hours of the report
+- **Fix timeline**: within 2 weeks of confirmation, we will provide either a patch or a mitigation plan
+
+## Scope
+
+### In scope
+
+- Backend service (`service/`)
+- Frontend application (`frontend/`)
+- MCP server (`service/src/mcp/`)
+- Authentication and session handling
+- Encryption and secrets management
+
+### Out of scope
+
+- Third-party dependencies: please report vulnerabilities in upstream packages directly to their respective maintainers
+- Issues in infrastructure or hosting environments not maintained by this project
+
+## Disclosure
+
+We follow coordinated disclosure. We ask that reporters allow us a reasonable window to address the issue before any public disclosure.

common/src/apis/github-repositories.ts

@@ -1,16 +1,23 @@
+/**
+ * REST API type definitions for GitHub repository management.
+ * Repositories are linked to services and used for cloning, fetching, and branch tracking.
+ */
+
 import type { WithOptionalId } from '@furystack/core'
 import type { DeleteEndpoint, GetCollectionEndpoint, GetEntityEndpoint, PatchEndpoint, RestApi } from '@furystack/rest'
 import type { GitHubRepository } from '../models/github-repository.js'
 
 export type GitHubRepoWritableFields = Omit<GitHubRepository, 'createdAt' | 'updatedAt'>
 
+/** Registers a new GitHub repository */
 export type PostGitHubRepoEndpoint = {
   result: GitHubRepository
   body: WithOptionalId<GitHubRepoWritableFields, 'id'>
 }
 
 export type PatchGitHubRepoEndpoint = PatchEndpoint<GitHubRepoWritableFields, 'id'>
 
+/** Checks whether the repository is accessible (e.g. URL is valid and reachable) */
 export type ValidateRepoEndpoint = {
   url: { id: string }
   result: { accessible: boolean; message?: string }

common/src/apis/prerequisites.ts

@@ -1,16 +1,23 @@
+/**
+ * REST API type definitions for prerequisite management.
+ * Prerequisites represent system-level dependencies (e.g. Node.js, Docker) that services require.
+ */
+
 import type { WithOptionalId } from '@furystack/core'
 import type { DeleteEndpoint, GetCollectionEndpoint, GetEntityEndpoint, PatchEndpoint, RestApi } from '@furystack/rest'
 import type { Prerequisite } from '../models/prerequisite.js'
 
 export type PrerequisiteWritableFields = Omit<Prerequisite, 'createdAt' | 'updatedAt'>
 
+/** Creates a new prerequisite definition */
 export type PostPrerequisiteEndpoint = {
   result: Prerequisite
   body: WithOptionalId<PrerequisiteWritableFields, 'id'>
 }
 
 export type PatchPrerequisiteEndpoint = PatchEndpoint<PrerequisiteWritableFields, 'id'>
 
+/** Executes the prerequisite's check command and returns whether it is satisfied */
 export type CheckPrerequisiteEndpoint = {
   url: { id: string }
   result: { satisfied: boolean; output: string }