From bfe48f1b9e53a36028f65d206e28c74ca572dc88 Mon Sep 17 00:00:00 2001 From: bnz183 Date: Tue, 9 Jun 2026 12:19:01 +0200 Subject: [PATCH] Open-source launch docs and acceptance test --- .github/ISSUE_TEMPLATE/bug_report.md | 52 ++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 35 +++++++++ CHANGELOG.md | 36 ++++++++++ CONTRIBUTING.md | 86 ++++++++++++++++++----- README.md | 19 ++++- docs/architecture.md | 2 +- docs/assets/README.md | 35 +++++++++ docs/configuration.md | 2 + docs/getting-started.md | 6 +- docs/manual-acceptance-test.md | 59 ++++++++++++++++ docs/media.md | 8 +-- docs/non-technical-overview.md | 7 +- docs/project-status.md | 4 +- docs/screenshots.md | 34 +++++++++ docs/security.md | 4 +- 15 files changed, 356 insertions(+), 33 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 CHANGELOG.md create mode 100644 docs/assets/README.md create mode 100644 docs/manual-acceptance-test.md create mode 100644 docs/screenshots.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..7bed4fe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,52 @@ +--- +name: Bug report +about: Report a problem with SourceDraft Studio, publishing, or configuration +title: "" +labels: bug +assignees: "" +--- + +## SourceDraft version / commit + + + +## Environment + +- **OS:** +- **Node version:** (`node -v`) +- **pnpm version:** (`pnpm -v`) +- **Browser:** + +## Configuration + +- **Adapter:** (`astro-mdx` or `markdown`) +- **contentDir:** +- **mediaDir:** +- **publicMediaPath:** (if set) +- **GitHub target:** owner/repo and branch (do not paste tokens) + +## What happened + +### Error message / logs + +``` +Paste relevant server or browser console output. Redact tokens and secrets. +``` + +### Expected behavior + + + +### Actual behavior + + + +## Steps to reproduce + +1. +2. +3. + +## Additional context + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..15b480c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,35 @@ +--- +name: Feature request +about: Suggest an improvement for SourceDraft core or adapters +title: "" +labels: enhancement +assignees: "" +--- + +## Problem + + + +## Proposed feature + + + +## Target user + + + +## Adapter / publisher affected + + + +## Core vs plugin / future adapter + + + +## Alternatives considered + + + +## Additional context + + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..991defe --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,36 @@ +# Changelog + +All notable changes to SourceDraft are documented here. The project uses [Semantic Versioning](https://semver.org/) where practical. + +## v0.1.0 + +First public open-source MVP for local/private Git-backed publishing. + +### Added + +- **Studio editor** for Markdown and MDX posts with universal article fields (title, slug, dates, category, tags, draft, body) +- **Markdown and MDX publishing** via adapters (`astro-mdx`, `markdown`) +- **GitHub publishing** through the Contents API (`@sourcedraft/github-publisher`) +- **Existing post listing and editing** from configured `contentDir` +- **Image uploads** to `mediaDir` (PNG, JPEG, GIF, WebP; 5 MB max) +- **Configurable `publicMediaPath`** — separate repo write path from URL path inserted into posts +- **Universal article validation** (`@sourcedraft/core`) +- **Project configuration** via `sourcedraft.config.json` and `.env` overrides +- **CI baseline** — build and unit tests on push/PR + +### Security (MVP) + +- Local/private **password auth** with server-side session cookies +- GitHub token and admin password stay on the server only +- Lightweight same-site protection on state-changing API routes + +**Warning:** MVP password auth is intended for local or private use. Do not expose Studio publicly without HTTPS, stronger auth, and deployment hardening. + +### Known limitations + +- GitHub Contents API only (no Git Trees API or content indexer yet) +- In-memory sessions (lost when the API restarts) +- No OAuth, user accounts, or hosted multi-tenant product +- Large content folders may hit GitHub listing or file-size limits + +See [docs/project-status.md](docs/project-status.md) for current scope. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4784aba..70c1b8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,29 +1,79 @@ -# Contributing +# Contributing to SourceDraft -SourceDraft is early-stage. Prefer small, typed changes over large refactors. +Thank you for helping improve SourceDraft. This project is an early open-source MVP for Git-backed Markdown and MDX publishing — not a hosted SaaS product. -## Principles +## Local setup -- Universal article schema in `@sourcedraft/core` -- Site-specific values in config files, not hardcoded in packages -- No generic SaaS UI patterns, fake metrics, or placeholder screens -- Secrets only in server code and `.env` +Requirements: -## Docs +- Node.js 22+ +- pnpm 11+ -Update user-facing docs when behavior changes: +```bash +git clone https://github.com/bnz183/SourceDraft.git +cd SourceDraft +pnpm install + +cp sourcedraft.config.example.json sourcedraft.config.json +cp .env.example .env +``` + +Edit `.env` with local values for development. **Do not commit `.env` or `.env.local`.** + +`GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO`, and `SOURCEDRAFT_ADMIN_PASSWORD` are read only by the Studio server (`apps/studio/server`). They must never be added to client code, issue reports, or screenshots. -- [README.md](README.md) -- [docs/getting-started.md](docs/getting-started.md) -- [docs/github-publishing.md](docs/github-publishing.md) -- [docs/configuration.md](docs/configuration.md) -- [docs/project-status.md](docs/project-status.md) +## Branch workflow -## Development +1. Fork the repository (or create a branch if you have write access). +2. Branch from `main` with a short descriptive name, for example `fix/post-list-error` or `docs/contributing`. +3. Keep changes focused — avoid unrelated refactors. +4. Open a pull request against `main` with a clear summary and test notes. + +## Commands + +From the repository root: ```bash -pnpm install -pnpm dev +pnpm install # install workspace dependencies +pnpm build # build all packages and Studio (including server TypeScript) +pnpm test # run unit tests +pnpm dev # start Studio UI + publish API locally +``` + +Optional: + +```bash +pnpm lint # lint workspace packages where configured +pnpm check # TypeScript check without emit ``` -Runs Studio and the publish API from the repo root. +CI runs `pnpm install --frozen-lockfile`, `pnpm build`, and `pnpm test` on push and pull requests. + +## What to contribute + +Good first contributions: + +- Documentation fixes and clarity +- Tests for pure helpers in `packages/*` +- Clearer error messages (server-side) +- Bug fixes with a small, focused diff + +Please avoid: + +- Hardcoding site-specific logic (QuBrite or any single publication) +- Exposing secrets or tokens in browser code +- Large refactors without an issue discussion first +- Fake features, metrics, or placeholder UI + +## Reporting issues + +Use the GitHub issue templates: + +- [Bug report](.github/ISSUE_TEMPLATE/bug_report.md) +- [Feature request](.github/ISSUE_TEMPLATE/feature_request.md) + +Do not paste live tokens, passwords, or private repository details in public issues. + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/README.md b/README.md index 71e9523..5af49c3 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,16 @@ SourceDraft is a free, open-source editor for Markdown and MDX blogs backed by GitHub. You write in the browser, upload images, check your metadata, preview the generated file, and publish into your site repository. +**Project status:** SourceDraft is an early local/private MVP for Git-backed Markdown and MDX publishing. It is usable for solo writing and GitHub commits, but it is not a hosted CMS, multi-user product, or finished SaaS. See [docs/project-status.md](docs/project-status.md) and [CHANGELOG.md](CHANGELOG.md). + SourceDraft began as an internal tool for [QuBrite.com](https://qubrite.com) and is published here for anyone running a similar static-site workflow. QuBrite is the origin story, not a dependency — you point SourceDraft at your own repository and config. +## Screenshots + +Screenshots are not included in the repository yet. Expected images and capture instructions: [docs/screenshots.md](docs/screenshots.md). + +When added, they will live in `docs/assets/` (overview, editor preview, media upload, publish success). + ## What is SourceDraft? SourceDraft is not WordPress and not a hosted website builder. It is a local **Studio** (editor) plus a small **publish API** that commits content and media files to GitHub. @@ -80,7 +88,7 @@ Start Studio (UI + publish API): pnpm dev ``` -Sign in, open **New Article**, preview the output, publish. The file lands at `contentDir/.mdx` or `.md` depending on your adapter (default: `src/content/blog/`). +Sign in, open **Write**, preview the output, publish. The file lands at `contentDir/.mdx` or `.md` depending on your adapter (default: `src/content/blog/`). Full walkthrough: [docs/getting-started.md](docs/getting-started.md) @@ -92,7 +100,7 @@ If someone technical already installed SourceDraft and pointed it at your blog r 2. The admin password they set in `.env` 3. Your site’s category list (from `sourcedraft.config.json`) -Then: sign in → **Overview** to open an existing post, or **New Article** → fill in title, description, date, category, tags, and body → upload images if needed → check the preview → **Publish to GitHub**. Your post appears as a file in the blog repo; the normal site build deploys it. +Then: sign in → **Posts** to open an existing post, or **Write** → fill in title, description, date, category, tags, and body → upload images if needed → check the preview → **Publish to GitHub**. Your post appears as a file in the blog repo; the normal site build deploys it. You do not edit GitHub by hand or run terminal commands for each post. If publish is disabled, ask your technical contact to check `.env` (GitHub token and repo) and that Studio is running with `pnpm dev`. @@ -122,6 +130,10 @@ Reference: [docs/configuration.md](docs/configuration.md) [examples/astro-blog/](examples/astro-blog/) is a **folder layout example** — not a runnable Astro site. It shows where files go, a sample published `.mdx`, and matching config. Read its README before copying paths into your own blog repo. +## Contributing + +Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, commands, and security reminders. + ## Documentation - [Getting started](docs/getting-started.md) @@ -133,7 +145,10 @@ Reference: [docs/configuration.md](docs/configuration.md) - [Architecture](docs/architecture.md) - [Adapters](docs/adapters.md) - [Project status](docs/project-status.md) +- [Manual acceptance test](docs/manual-acceptance-test.md) - [Security](docs/security.md) +- [Screenshots guide](docs/screenshots.md) +- [Changelog](CHANGELOG.md) ## License diff --git a/docs/architecture.md b/docs/architecture.md index 6e02b2b..27545d7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -40,7 +40,7 @@ Studio (browser) Publish API (server) → listFiles / readFile (@sourcedraft/github-publisher) → parse frontmatter, validate (@sourcedraft/core) - → JSON for Overview and edit flow + → JSON for Posts list and edit flow ``` ## Packages diff --git a/docs/assets/README.md b/docs/assets/README.md new file mode 100644 index 0000000..e17166e --- /dev/null +++ b/docs/assets/README.md @@ -0,0 +1,35 @@ +# docs/assets + +Static images for SourceDraft documentation (primarily README screenshots). + +## Naming + +Use lowercase kebab-case PNG files: + +- `studio-overview.png` +- `editor-preview.png` +- `media-upload.png` +- `publish-success.png` + +Add new screenshots only when they reflect the current Studio UI. + +## Privacy and security + +Before committing an image, confirm it does **not** show: + +- GitHub tokens or personal access tokens +- `.env` contents or `SOURCEDRAFT_ADMIN_PASSWORD` +- Private repository names you do not want public (use a test repo or blur) +- Personal email addresses, internal URLs, or unrelated proprietary content + +Studio Settings fields are read-only, but screenshots can still expose owner/repo names and folder paths. Use a dedicated test GitHub repository when possible. + +## Usage + +Reference images from the root README or docs with relative paths, for example: + +```markdown +![Studio overview](docs/assets/studio-overview.png) +``` + +See [screenshots.md](../screenshots.md) for capture instructions. diff --git a/docs/configuration.md b/docs/configuration.md index 78d9fb0..f629a4f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -128,3 +128,5 @@ Secrets: ``` .env only (never in sourcedraft.config.json) ``` + +For local development and contributions, see [CONTRIBUTING.md](../CONTRIBUTING.md). Release history: [CHANGELOG.md](../CHANGELOG.md). diff --git a/docs/getting-started.md b/docs/getting-started.md index fe26d7e..3d6d5b5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -36,7 +36,7 @@ GITHUB_BRANCH=main | File | Holds | |------|--------| -| `sourcedraft.config.json` | `contentDir`, `mediaDir`, categories, adapter | +| `sourcedraft.config.json` | `contentDir`, `mediaDir`, `publicMediaPath`, categories, adapter | | `.env` | Password, GitHub token, repo owner/name | See [configuration.md](configuration.md) for the full split. @@ -59,8 +59,8 @@ Sign in with `SOURCEDRAFT_ADMIN_PASSWORD`. ## 5. Write and publish -1. **Overview** — see existing posts from GitHub; click **Edit**, or use **New Article** -2. Fill in the form; upload images under **Hero image** if needed ([media.md](media.md)) +1. **Posts** — see existing posts from GitHub; click **Edit**, or open **Write** for a new post +2. Fill in post details; upload a cover image if needed ([media.md](media.md)) 3. Check the Markdown or MDX preview and output path 4. **Publish to GitHub** diff --git a/docs/manual-acceptance-test.md b/docs/manual-acceptance-test.md new file mode 100644 index 0000000..b1ccf2d --- /dev/null +++ b/docs/manual-acceptance-test.md @@ -0,0 +1,59 @@ +# Manual acceptance test + +Run this checklist before promoting SourceDraft v0.1. Requires a configured `.env`, `sourcedraft.config.json`, and a test GitHub repository you can write to. + +## Setup + +- [ ] `pnpm install` +- [ ] Copy `sourcedraft.config.example.json` → `sourcedraft.config.json` and adjust paths +- [ ] Copy `.env.example` → `.env` with `CMS_ADMIN_PASSWORD`, `GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO` + +## Start Studio + +- [ ] `pnpm dev` +- [ ] Open `http://localhost:5173` (or the URL shown in the terminal) +- [ ] Log in with the admin password + +## Navigation and settings + +- [ ] **Posts** loads (post list or empty state) +- [ ] Open **Settings** and confirm adapter, `contentDir`, `mediaDir`, and `publicMediaPath` match your config + +## Create and preview + +- [ ] Open **Write** (new article) +- [ ] Fill title, description, category, tags, and body +- [ ] Upload an image (drag or **Choose image**) +- [ ] Set uploaded image as **Cover image** +- [ ] Insert uploaded image into the body +- [ ] Preview shows the expected output file content + +## Publish new post + +- [ ] Publish succeeds (no validation or API errors) +- [ ] New file appears in GitHub under `contentDir` +- [ ] Uploaded image appears in GitHub under `mediaDir` +- [ ] Cover and inline image paths in the committed file match `publicMediaPath` + +## Edit existing post + +- [ ] From **Posts**, open an existing post +- [ ] Edit title or body +- [ ] Publish update succeeds +- [ ] Same file path updates in GitHub (no duplicate slug file) + +## Error smoke checks (optional) + +- [ ] Wrong `GITHUB_OWNER` or `GITHUB_REPO` shows a clear error on publish or post list +- [ ] Missing or invalid token shows a clear error (not a blank screen) +- [ ] Upload over 5 MB or wrong file type is rejected with a clear message + +## Automated checks (CI parity) + +```bash +pnpm install --lockfile-only +pnpm build +pnpm test +``` + +All three commands should exit 0. diff --git a/docs/media.md b/docs/media.md index e13774a..62d8b5a 100644 --- a/docs/media.md +++ b/docs/media.md @@ -1,17 +1,17 @@ # Media uploads -SourceDraft can upload hero and inline images to your GitHub repository through the publish API. Uploads are server-side only — the browser never sees your GitHub token. +SourceDraft can upload cover and inline images to your GitHub repository through the publish API. Uploads are server-side only — the browser never sees your GitHub token. See also: [Configuration](configuration.md) · [Security](security.md) · [Getting started](getting-started.md) ## Upload flow -1. In Studio, open **New Article** or edit an existing post. -2. Under **Hero image**, use the upload area: drag an image in or click **Choose image**. +1. In Studio, open **Write** or edit an existing post from **Posts**. +2. Under **Cover image**, use the upload area: drag an image in or click **Choose image**. 3. The browser sends the file to `POST /api/media/upload` (multipart field name: `file`). 4. The server validates type, size, and file signature, sanitizes the filename, and commits the image to `mediaDir` via the GitHub Contents API. 5. On success, Studio shows the public path (for example `/images/my-photo-a1b2c3d4.png`). -6. Click **Use as hero image** to fill the hero field, or **Insert into body** to add a Markdown image line. +6. Click **Use as cover image** to fill the cover field (`heroImage` in frontmatter), or **Insert into body** to add a Markdown image line. Your static site must serve files from the path your site expects — SourceDraft only writes into the repo. diff --git a/docs/non-technical-overview.md b/docs/non-technical-overview.md index db17d4b..18fdaa4 100644 --- a/docs/non-technical-overview.md +++ b/docs/non-technical-overview.md @@ -16,8 +16,9 @@ SourceDraft keeps the writing and publish steps in one interface. 1. Sign in with the admin password (set once by whoever installed SourceDraft) 2. Write your post — title, description, category, tags, body -3. Preview the exact MDX file SourceDraft will commit -4. Publish to GitHub when validation passes +3. Upload cover and inline images to your repo (optional) +4. Preview the exact output file SourceDraft will commit (MDX or Markdown) +5. Publish to GitHub when validation passes There are no traffic charts, billing screens, or account tiers. @@ -25,7 +26,7 @@ There are no traffic charts, billing screens, or account tiers. - Host or serve your public website - Replace Astro or your current site builder -- Upload images (you type a path such as `/images/photo.jpg`) +- Host images on external CDNs (uploads go to your GitHub repo's media folder) - Manage comments, email lists, or analytics After publish, your normal site build and deploy process runs unchanged. diff --git a/docs/project-status.md b/docs/project-status.md index 97db7bb..2c55a8e 100644 --- a/docs/project-status.md +++ b/docs/project-status.md @@ -10,7 +10,7 @@ Early open-source MVP — usable for single-editor writing and GitHub publishing - Live preview for `astro-mdx` and `markdown` adapters - GitHub file create/update for posts and media (`@sourcedraft/github-publisher`) - Clearer GitHub API error messages for token, repo, path, and Contents API limits -- Image upload from Studio (PNG, JPEG, GIF, WebP; 5 MB max) +- Image upload from Studio (PNG, JPEG, GIF, WebP; 5 MB max) with configurable `publicMediaPath` - `sourcedraft.config.json` + `.env` configuration - Server-side password auth for Studio and API - CI: build and unit tests on push/PR @@ -43,3 +43,5 @@ Open-source tool for developers and technical bloggers who accept these limits. Built first for [QuBrite.com](https://qubrite.com). Core code stays generic; each site uses its own config and GitHub target. Publishing flow: [github-publishing.md](github-publishing.md) · Media: [media.md](media.md) + +Contributing: [../CONTRIBUTING.md](../CONTRIBUTING.md) · Releases: [../CHANGELOG.md](../CHANGELOG.md) diff --git a/docs/screenshots.md b/docs/screenshots.md new file mode 100644 index 0000000..e7da7b7 --- /dev/null +++ b/docs/screenshots.md @@ -0,0 +1,34 @@ +# Screenshots + +Screenshots help first-time visitors understand SourceDraft without running the project locally. They are optional for development but useful for the README and release notes. + +## Expected screenshots + +Maintainers can add these under `docs/assets/` when captured from a real local session: + +| File | What to show | +|------|----------------| +| `studio-overview.png` | **Posts** view — post list or empty state with publishing setup visible | +| `editor-preview.png` | **Write** view — body editor, post details panel, and MDX/Markdown preview | +| `media-upload.png` | Cover image upload area with accepted formats noted | +| `publish-success.png` | Publish confirmation after a successful commit | + +Do not commit placeholder or generated fake screenshots. + +## How to capture locally + +1. Start Studio: `pnpm dev` from the repository root. +2. Sign in with your local admin password. +3. Use a **test repository** or sanitized config — not production secrets. +4. Open the view you want (Posts, Write, Settings). +5. Capture the browser window at a readable width (about 1280px works well). +6. Save as PNG with the filenames above into `docs/assets/`. +7. Review the image: crop out tokens, private repo names, personal paths, or email addresses if needed. + +On Linux, many desktops support **Print Screen** or a region capture tool. Browser dev tools device toolbar is optional; full-window captures are fine. + +## Before committing + +Read [assets/README.md](assets/README.md) for naming and privacy rules. + +If screenshots are not ready yet, the root README links here instead of showing broken images. diff --git a/docs/security.md b/docs/security.md index 36a92d5..d4ecc00 100644 --- a/docs/security.md +++ b/docs/security.md @@ -74,4 +74,6 @@ Single shared password, in-memory sessions. This is not a multi-tenant production auth system yet. -Report security concerns privately; do not include live tokens in reports. +Report security concerns privately; do not include live tokens in reports or public issue templates. + +When filing bugs, redact tokens, passwords, and private repository details. See [CONTRIBUTING.md](../CONTRIBUTING.md).