Skip to content

Commit 27c7d52

Browse files
gallaylgallayl
committed
SOLID refactors, documentation updates
1 parent 6f393f5 commit 27c7d52

38 files changed

+1526
-525
lines changed

‎CONTRIBUTING.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Contributing to Stack Craft
2+
3+
## Development Setup
4+
5+
1. Clone the repository and install dependencies:
6+
7+
```bash
8+
git clone https://github.com/furystack/stack-craft.git
9+
cd stack-craft
10+
yarn
11+
```
12+
13+
2. Start PostgreSQL:
14+
15+
```bash
16+
docker compose up -d
17+
```
18+
19+
3. Create your environment file:
20+
21+
```bash
22+
cp .env.example .env
23+
```
24+
25+
4. Start the backend and frontend in separate terminals:
26+
27+
```bash
28+
yarn start:service # Terminal 1
29+
yarn start:frontend # Terminal 2
30+
```
31+
32+
## Project Structure
33+
34+
```
35+
stack-craft/
36+
├── common/ # Shared API type definitions, models, and generated schemas
37+
├── frontend/ # Shades-based SPA (Vite dev server on :8080)
38+
├── service/ # FuryStack REST backend (Node.js on :9090)
39+
├── e2e/ # Playwright end-to-end tests
40+
└── docs/ # Documentation
41+
```
42+
43+
## Code Style
44+
45+
The project uses **ESLint** and **Prettier** for code quality and formatting. Both run automatically on staged files via Husky pre-commit hooks.
46+
47+
```bash
48+
yarn lint # Run ESLint
49+
yarn format # Format all files with Prettier
50+
yarn format:check # Check formatting without modifying files
51+
```
52+
53+
Key conventions:
54+
55+
- **File names:** kebab-case (e.g. `service-pipeline.ts`)
56+
- **Components:** PascalCase exports in kebab-case files
57+
- **Types:** Prefer `type` over `interface`
58+
- **No `any`:** Use `unknown`, generics, or union types instead
59+
60+
See `.cursor/rules/` for detailed coding guidelines.
61+
62+
## Testing
63+
64+
```bash
65+
yarn test # Run Vitest unit tests with coverage
66+
yarn test:e2e # Run Playwright E2E tests (requires running DB)
67+
```
68+
69+
- Unit tests are co-located with source files (`*.spec.ts`)
70+
- Coverage thresholds are enforced in `vitest.config.mts`
71+
- Add tests for new functionality before submitting a PR
72+
73+
## Schema Generation
74+
75+
When you modify API types in `common/src/apis/` or models in `common/src/models/`, regenerate the JSON schemas:
76+
77+
```bash
78+
yarn build # Must build common first
79+
yarn create-schemas # Regenerate schemas
80+
```
81+
82+
## Versioning and Changelogs
83+
84+
This project uses [Yarn's release workflow](https://yarnpkg.com/features/release-workflow) for version management and changelogs. Both are required before opening a PR.
85+
86+
### 1. Bump versions
87+
88+
Decide which packages need a version bump and at what level (patch/minor/major):
89+
90+
```bash
91+
yarn bumpVersions # Interactive prompt to select packages and bump type
92+
```
93+
94+
This creates version manifest files that Yarn tracks. You can verify the state with:
95+
96+
```bash
97+
yarn version check # Validates that version bumps are configured
98+
```
99+
100+
### 2. Create changelog drafts
101+
102+
Generate changelog draft files for each bumped package:
103+
104+
```bash
105+
yarn changelog create # Creates .yarn/changelogs/{package}.{id}.md files
106+
yarn changelog create -f # Force-recreate (useful if drafts are stale)
107+
```
108+
109+
### 3. Fill the changelog entries
110+
111+
Edit the generated `.yarn/changelogs/*.md` files. Each file has section placeholders -- fill in the relevant ones describing what changed and why. Write for end users, not as a git log.
112+
113+
### 4. Validate
114+
115+
```bash
116+
yarn changelog check # Validates entries are filled and match the version type
117+
```
118+
119+
### Applying releases (maintainers only)
120+
121+
When merging to a release branch, the release pipeline runs:
122+
123+
```bash
124+
yarn applyReleaseChanges # Applies version bumps, merges changelogs, and formats
125+
```
126+
127+
## Pull Request Process
128+
129+
1. Create a feature branch from the latest `develop`
130+
2. Make your changes with tests
131+
3. Ensure `yarn build`, `yarn lint`, and `yarn test` all pass
132+
4. Bump versions (`yarn bumpVersions`) and fill changelog entries (`yarn changelog create`, then edit the drafts)
133+
5. Verify with `yarn changelog check`
134+
6. Open a PR against `develop`
135+
7. PRs must pass CI checks (build, lint, test, E2E, changelog check, version check)

‎README.md‎

Lines changed: 96 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,108 @@
11
# Stack Craft
22

3-
Example web app with common type API definitions, a FuryStack-based backend service and a Shades-based single page application.
3+
A web application for managing development stacks, services, prerequisites, and repositories. Built with a [FuryStack](https://github.com/furystack/furystack) backend and a [Shades](https://github.com/furystack/furystack/tree/develop/packages/shades)-based single page application.
44

5-
# Usage
5+
## Features
66

7-
1. Clone the repository
8-
1. Install the dependencies with `yarn`
9-
1. Start PostgreSQL (e.g. `docker compose up -d`)
10-
1. Copy `.env.example` to `.env` and adjust if needed
11-
1. Start the frontend and the backend service with `yarn start` (you can stop / start them individually, check the NPM scripts for further details)
7+
- **Stack management** -- group related services, repositories, and prerequisites into stacks
8+
- **Service lifecycle** -- start, stop, restart, build, and install services with real-time log streaming
9+
- **Prerequisite checks** -- define and evaluate system prerequisites before running services
10+
- **Repository integration** -- clone and manage GitHub repositories with branch switching
11+
- **Environment variables** -- manage per-stack and per-service environment configuration with encrypted secrets
12+
- **Import / Export** -- share stack configurations across environments
13+
- **MCP server** -- interact with Stack Craft via [Model Context Protocol](https://modelcontextprotocol.io/) for AI assistant integration
14+
15+
## Prerequisites
16+
17+
- [Node.js](https://nodejs.org/) >= 22
18+
- [Yarn](https://yarnpkg.com/) 4 (included via `packageManager` in `package.json`)
19+
- [Docker](https://www.docker.com/) (for PostgreSQL, or provide your own instance)
20+
21+
## Getting Started
22+
23+
```bash
24+
# Clone and install
25+
git clone https://github.com/furystack/stack-craft.git
26+
cd stack-craft
27+
yarn
28+
29+
# Start PostgreSQL
30+
docker compose up -d
31+
32+
# Create your environment file
33+
cp .env.example .env
34+
35+
# Start the backend and frontend
36+
yarn start:service # Backend on http://localhost:9090
37+
yarn start:frontend # Frontend on http://localhost:8080
38+
```
39+
40+
Open http://localhost:8080 in your browser. On first launch, the installer wizard will guide you through creating an admin account.
41+
42+
## Configuration
43+
44+
Environment variables can be set in the `.env` file at the project root.
45+
46+
| Variable | Default | Description |
47+
| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
48+
| `DATABASE_URL` | `postgres://stackcraft:stackcraft@localhost:5433/stackcraft` | PostgreSQL connection string |
49+
| `APP_SERVICE_PORT` | `9090` | Backend HTTP server port |
50+
| `MCP_PORT` | `9091` | MCP server port |
51+
| `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/` |
1252

1353
## Docker
1454

15-
When running the Docker image, pass the `DATABASE_URL` environment variable:
55+
Build and run the Docker image:
1656

1757
```bash
18-
docker run -e DATABASE_URL=postgres://user:password@host:5433/stackcraft furystack/stack-craft
58+
docker build -t stack-craft .
59+
60+
docker run -p 9090:9090 \
61+
-e DATABASE_URL=postgres://user:password@host:5432/stackcraft \
62+
stack-craft
1963
```
2064

21-
# Testing
65+
The pre-built image is also available on Docker Hub:
66+
67+
```bash
68+
docker run -p 9090:9090 \
69+
-e DATABASE_URL=postgres://user:password@host:5432/stackcraft \
70+
furystack/stack-craft
71+
```
72+
73+
## Project Structure
74+
75+
```
76+
stack-craft/
77+
├── common/ # Shared API type definitions and models
78+
├── frontend/ # Shades-based SPA (Vite)
79+
├── service/ # FuryStack REST backend (Node.js)
80+
└── e2e/ # Playwright end-to-end tests
81+
```
82+
83+
## Testing
84+
85+
```bash
86+
# Unit tests (Vitest)
87+
yarn test
88+
89+
# End-to-end tests (requires running PostgreSQL + DATABASE_URL)
90+
yarn test:e2e
91+
```
92+
93+
## Available Scripts
94+
95+
| Script | Description |
96+
| --------------------- | --------------------------------------------- |
97+
| `yarn start:service` | Start the backend service |
98+
| `yarn start:frontend` | Start the Vite dev server for the frontend |
99+
| `yarn build` | Build all packages |
100+
| `yarn test` | Run Vitest unit tests |
101+
| `yarn test:e2e` | Run Playwright E2E tests |
102+
| `yarn lint` | Run ESLint |
103+
| `yarn format` | Format code with Prettier |
104+
| `yarn create-schemas` | Regenerate JSON schemas from TypeScript types |
105+
106+
## License
22107

23-
- You can execute the example Vitest tests with `yarn test`
24-
- You can execute E2E tests with `yarn test:e2e` (requires a running PostgreSQL instance and `DATABASE_URL` set)
108+
[GPL-2.0-only](LICENSE)

‎common/schemas/identity-api.json‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@
1616
}
1717
},
1818
"required": ["result"],
19-
"additionalProperties": false
19+
"additionalProperties": false,
20+
"description": "Checks whether the current session is authenticated"
2021
},
2122
"GetCurrentUserAction": {
2223
"type": "object",
@@ -26,7 +27,8 @@
2627
}
2728
},
2829
"required": ["result"],
29-
"additionalProperties": false
30+
"additionalProperties": false,
31+
"description": "Returns the currently authenticated user's profile"
3032
},
3133
"User": {
3234
"type": "object",
@@ -65,15 +67,17 @@
6567
}
6668
},
6769
"required": ["result", "body"],
68-
"additionalProperties": false
70+
"additionalProperties": false,
71+
"description": "Authenticates with username/password and returns the user profile"
6972
},
7073
"LogoutAction": {
7174
"type": "object",
7275
"properties": {
7376
"result": {}
7477
},
7578
"required": ["result"],
76-
"additionalProperties": false
79+
"additionalProperties": false,
80+
"description": "Ends the current session"
7781
},
7882
"PasswordResetAction": {
7983
"type": "object",
@@ -103,7 +107,8 @@
103107
}
104108
},
105109
"required": ["result", "body"],
106-
"additionalProperties": false
110+
"additionalProperties": false,
111+
"description": "Changes the current user's password"
107112
},
108113
"IdentityApi": {
109114
"type": "object",

‎common/schemas/install-api.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
}
2424
},
2525
"required": ["result"],
26-
"additionalProperties": false
26+
"additionalProperties": false,
27+
"description": "Returns whether the application needs initial setup or is already installed"
2728
},
2829
"InstallAction": {
2930
"type": "object",
@@ -53,7 +54,8 @@
5354
}
5455
},
5556
"required": ["result", "body"],
56-
"additionalProperties": false
57+
"additionalProperties": false,
58+
"description": "Performs initial application setup and creates the first admin user"
5759
},
5860
"InstallApi": {
5961
"type": "object",

0 commit comments

Comments
 (0)