mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-20 20:07:59 +00:00
Phase 1: add CLI scaffold and config generators (#2)
* Add CLI scaffold and config generators * Add PR stacking note to README * refactor: write embargo init command myself for clarity * refactor: rename Myst and narrow CLI setup flow * Update Phase 1 plans with finalized design decisions Major updates: - Add authentication model (Forgejo sessions for identity, PAT for data access) - Add link types (private email-verified, public time-expired) - Add link creation rules (owner-only) - Add Docker/deployment guidance (Dockerfile only, Dokploy handles orchestration) - Add database model (separate DBs on same PostgreSQL instance) - Add viewer baseline and user dashboard sections - Add SMTP configuration via post-login setup page Key architectural decisions: - Users log in via Forgejo session, no separate Myst login - Service account PAT used for API calls, not user identity - Private links require email verification code - Public links are time-expired for job applications - Myst provides Dockerfile, operators use Dokploy for deployment * Complete CLI init skeleton with CodeRabbit review fixes CLI changes: - Narrow init to Myst-only config generation (no Forgejo provisioning) - Add yoctocolors styling to CLI output - Simplify URL validation logic (remove dead code) - Fix typo in env.ts comment - Remove docker-compose generator (out of scope) - Move example config from src/ to packages/cli/examples/ - Fix CommandName type to match implemented commands only Config changes: - Remove databaseUrl from myst.config.json (DB is .env-only) - Update example config with current fields - Reject non-HTTP schemes before auto-prepending https:// - Use localhost -> 127.0.0.1 in Caddy/Nginx examples - Add file existence checks and 0o600 permissions Build passes after all changes. * docs: rewrite README with Myst branding and architecture - Add Mermaid architecture diagram - Document two link types (private/public) - Explain authentication model - Provide setup steps - Add example configuration - Include Phase 1 completion checklist * fix: correct Mermaid diagram syntax * refactor: streamline README per create-readme skill guidelines - Use blockquote for tagline - Simplify architecture diagram labels - Remove redundant sections (Setup, Example Config, License) - Keep checklist as primary tracking mechanism - Use tables for features and auth - Reduce verbosity throughout * cli: add preflight check and version flag - Add preflightWriteTargets to check file existence before writing - Remove stub commands (start, stop, status) from help text - Add --version flag support - Sequential file writes with preflight check * cleanup: remove empty command stubs and test config - Remove start.ts, stop.ts, status.ts (not implemented yet) - Remove myst.config.json (generated during testing) * cleanup: remove app-ini generator (Forgejo provisioning out of scope) * cleanup: remove empty unused utility files (docker.ts, flags.ts, init.ts) * cleanup: remove examples.ts (examples belong in docs, not deployed code)
This commit is contained in:
parent
b22d46ff84
commit
eeddcd9c8b
17 changed files with 1208 additions and 49 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -1,5 +1,6 @@
|
|||
node_modules/
|
||||
.DS_Store
|
||||
.tmp/
|
||||
dist/
|
||||
coverage/
|
||||
.env
|
||||
|
|
|
|||
140
README.md
140
README.md
|
|
@ -1,25 +1,131 @@
|
|||
# Embargo
|
||||
# Myst
|
||||
|
||||
Your code, under embargo.
|
||||
> My stuff, kept private.
|
||||
|
||||
Embargo is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for private code snapshots.
|
||||
Myst is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots.
|
||||
|
||||
## Phase 1 PR Breakdown
|
||||
## Architecture
|
||||
|
||||
Phase 1 is split into these reviewable branches:
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph VPS["VPS / Self-Hosted"]
|
||||
subgraph Docker["Docker Network"]
|
||||
Forgejo["Forgejo (Git Server)"]
|
||||
Postgres["PostgreSQL (2 Databases)"]
|
||||
Myst["Myst (This Service)"]
|
||||
Traefik["Traefik (Reverse Proxy)"]
|
||||
end
|
||||
Tailscale["Tailscale (Admin Access)"]
|
||||
end
|
||||
|
||||
1. `codex/phase1-bootstrap-monorepo`
|
||||
2. `codex/phase1-cli-init-skeleton`
|
||||
3. `codex/phase1-service-foundation`
|
||||
4. `codex/phase1-forgejo-integration`
|
||||
5. `codex/phase1-grants-viewer`
|
||||
6. `codex/phase1-dashboard-logs-settings`
|
||||
subgraph External["External"]
|
||||
Owner["Repo Owner"]
|
||||
Viewer["Link Recipient"]
|
||||
end
|
||||
|
||||
## Core Principles
|
||||
Owner -->|"Login via Forgejo Session"| Myst
|
||||
Owner -->|"Create View Link (PAT)"| Forgejo
|
||||
Myst -->|"Read-only API (PAT)"| Forgejo
|
||||
Myst -->|"Store Grants"| Postgres
|
||||
Forgejo -->|"Sessions"| Postgres
|
||||
Myst -->|"Public Viewer"| Viewer
|
||||
Myst -->|"Admin UI (Protected)"| Owner
|
||||
Tailscale -->|"Private Admin Access"| Myst
|
||||
Traefik -->|"Route HTTPS Traffic"| Myst
|
||||
```
|
||||
|
||||
- Embargo runs beside Forgejo and talks to it only through the Forgejo API.
|
||||
- Share links pin to an immutable `commit_sha`, not a moving branch.
|
||||
- Embargo uses its own owner auth for MVP.
|
||||
- Forgejo access is performed by a constrained service account with minimum PAT scopes.
|
||||
- A repo is shareable only if the service account can see it and Embargo has sharing enabled for it.
|
||||
## Features
|
||||
|
||||
### Two Link Types
|
||||
|
||||
| Type | Verification | Use Case |
|
||||
|------|--------------|----------|
|
||||
| **Private** | Email verification code required | Share with specific individuals |
|
||||
| **Public** | No verification, time-expired | Job applications, portfolios |
|
||||
|
||||
### Security
|
||||
|
||||
- Links pinned to immutable `commit_sha` — not moving branches
|
||||
- Email verification prevents unauthorized access
|
||||
- Time-expiration and revocation give owners control
|
||||
- No public repo listing — anti-scraping by design
|
||||
- Admin access protected upstream (Tailscale, VPN, Cloudflare Access)
|
||||
|
||||
### Authentication
|
||||
|
||||
| Purpose | Method |
|
||||
|---------|--------|
|
||||
| User Identity | Forgejo Sessions |
|
||||
| Data Access | Service Account PAT |
|
||||
|
||||
### Tech Stack
|
||||
|
||||
- **Backend**: Python + FastAPI
|
||||
- **Frontend**: Jinja2 templates + HTMX (no build step)
|
||||
- **Database**: PostgreSQL
|
||||
|
||||
HTMX provides interactivity (filtering, form submissions) with minimal JavaScript. Jinja2 handles server-side rendering for fast page loads.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Run `myst init`
|
||||
|
||||
```bash
|
||||
myst init
|
||||
```
|
||||
|
||||
Prompts for:
|
||||
|
||||
- Public viewer URL (`share.example.com`)
|
||||
- Private admin URL (`admin.example.com`)
|
||||
- Forgejo base URL (`git.example.com`)
|
||||
- PostgreSQL connection string
|
||||
- Forgejo service account username and PAT
|
||||
- Grant token secret
|
||||
|
||||
### 2. Configure Service Account
|
||||
|
||||
Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT:
|
||||
|
||||
- `read:user`
|
||||
- `read:repository`
|
||||
|
||||
### 3. Deploy
|
||||
|
||||
Deploy via Dokploy, Coolify, or your preferred platform.
|
||||
|
||||
## Example Configuration
|
||||
|
||||
```env
|
||||
MYST_PUBLIC_URL="https://share.example.com"
|
||||
MYST_ADMIN_URL="https://admin.example.com"
|
||||
DATABASE_URL="postgresql://myst:secret@localhost:5432/myst"
|
||||
FORGEJO_BASE_URL="https://git.example.com"
|
||||
FORGEJO_SERVICE_ACCOUNT_USERNAME="myst-bot"
|
||||
FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx"
|
||||
GRANT_TOKEN_SECRET="your-secret-here"
|
||||
```
|
||||
|
||||
## Phase 1 Progress
|
||||
|
||||
- [x] Project renamed from Embargo to Myst
|
||||
- [x] CLI scaffold (`myst init`)
|
||||
- [x] Config generation (`.env`, `myst.config.json`)
|
||||
- [ ] Service foundation (FastAPI + PostgreSQL)
|
||||
- [ ] `myst forgejo bootstrap` — verify Forgejo connectivity
|
||||
- [ ] `myst doctor` — validate configuration
|
||||
- [ ] `myst config print` — show current config
|
||||
- [ ] Forgejo session authentication
|
||||
- [ ] Repo ownership verification
|
||||
- [ ] Private link creation (email-verified)
|
||||
- [ ] Public link creation (time-expired)
|
||||
- [ ] Web-based code viewer (Jinja2 + HTMX)
|
||||
- [ ] User dashboard
|
||||
- [ ] SMTP configuration UI
|
||||
- [ ] Access logs
|
||||
|
||||
## Resources
|
||||
|
||||
- [Forgejo Docs](https://forgejo.org/docs/)
|
||||
- [API Usage](https://forgejo.org/docs/latest/user/api-usage/)
|
||||
- [Token Scopes](https://forgejo.org/docs/latest/user/token-scope/)
|
||||
|
|
|
|||
|
|
@ -1,16 +1,40 @@
|
|||
# Embargo Phase 1 Design
|
||||
# Myst Phase 1 Design
|
||||
|
||||
This document captures the approved Phase 1 plan for Embargo.
|
||||
This document captures the approved Phase 1 plan for Myst.
|
||||
|
||||
## Scope
|
||||
|
||||
Phase 1 delivers:
|
||||
|
||||
- CLI bootstrap for Forgejo + Embargo deployment
|
||||
- Embargo service foundation
|
||||
- CLI setup for attaching Myst to an existing Forgejo deployment
|
||||
- Myst service foundation
|
||||
- constrained Forgejo service-account integration
|
||||
- immutable snapshot grants pinned to `commit_sha`
|
||||
- owner dashboard and viewer flow
|
||||
- two link types: private (email-verified) and public (time-expired)
|
||||
- web-based code viewer (not git clone URLs)
|
||||
|
||||
Phase 1 does not deliver:
|
||||
|
||||
- Forgejo provisioning
|
||||
- Forgejo database provisioning
|
||||
- reverse proxy or DNS automation
|
||||
- platform-specific hosting orchestration beyond optional templates and docs
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Backend**: Python 3.11+ with FastAPI
|
||||
- **Frontend**: Jinja2 templates with HTMX for interactivity
|
||||
- **Database**: PostgreSQL
|
||||
- **Async**: Uses `async/await` with asyncpg for database access
|
||||
|
||||
### Why This Stack?
|
||||
|
||||
**FastAPI**: Lightweight async framework, automatic OpenAPI docs, Pydantic for validation.
|
||||
|
||||
**Jinja2 + HTMX**: Server-side rendering with minimal JavaScript. HTMX handles dynamic updates (filtering, form submissions) without a build step or heavy SPA framework.
|
||||
|
||||
**PostgreSQL**: Reliable, well-supported by async libraries (asyncpg, SQLModel).
|
||||
|
||||
## Reviewable Branches
|
||||
|
||||
|
|
@ -24,6 +48,176 @@ Phase 1 delivers:
|
|||
## Security Baseline
|
||||
|
||||
- service account access is restricted to approved repos
|
||||
- Embargo grant checks are enforced on every Forgejo read
|
||||
- Myst grant checks are enforced on every Forgejo read
|
||||
- grants store `repo_id` and pinned `commit_sha`
|
||||
- viewer requests never choose repo or ref directly
|
||||
- operators create the Forgejo service account and PAT themselves
|
||||
- Myst stores only its own app config and metadata in its own database
|
||||
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls
|
||||
- Myst does not ship built-in admin auth in Phase 1
|
||||
|
||||
## Authentication Model
|
||||
|
||||
Myst uses two authentication mechanisms:
|
||||
|
||||
**User Identity (Forgejo Sessions)**
|
||||
- Users log in via Forgejo's session system
|
||||
- Myst redirects to Forgejo login and validates the session
|
||||
- Users use their existing Forgejo accounts — no separate Myst login
|
||||
- All Forgejo users with an account are trusted Myst users
|
||||
|
||||
**Data Access (Service Account PAT)**
|
||||
- Myst uses an operator-created service account PAT to call the Forgejo API
|
||||
- PAT is used to verify repo ownership and fetch code for viewers
|
||||
- PAT is never used for user identity (that's handled by sessions)
|
||||
|
||||
**Why both?**
|
||||
- Sessions identify who the user is (zach@me.com logged in)
|
||||
- PAT allows Myst to verify repo ownership (can zach@me.com create view links for this repo?)
|
||||
- PAT allows Myst to fetch code content for the viewer (get the pinned commit's files)
|
||||
|
||||
## Forgejo Service Account Baseline
|
||||
|
||||
- the Forgejo service account is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
|
||||
- the operator creates this user in Forgejo and grants repo access explicitly
|
||||
- the operator creates the PAT for this user through the Forgejo UI or admin CLI
|
||||
- recommended PAT scopes are `read:user` and `read:repository`
|
||||
- `read:organization` may also be required when repo visibility depends on org or team APIs
|
||||
- Myst must not create Forgejo users, PATs, or repo permissions in Phase 1
|
||||
|
||||
## Link Types
|
||||
|
||||
Myst supports two types of view links:
|
||||
|
||||
### Private Links (Email-Verified)
|
||||
|
||||
- Time expired (configurable duration)
|
||||
- Revocable by the owner
|
||||
- Requires email verification code to view
|
||||
- Tied to a specific email address
|
||||
- Owner specifies the recipient's email when creating the link
|
||||
- Myst sends an email with a verification code
|
||||
- Viewer enters the code to access the snapshot
|
||||
|
||||
### Public Links (Time-Expired)
|
||||
|
||||
- Time expired (configurable duration)
|
||||
- Revocable by the owner
|
||||
- No verification required
|
||||
- Anyone with the link can view
|
||||
- Suitable for job application portfolio fields
|
||||
- Owner copies the link and shares it directly
|
||||
|
||||
## Link Creation Rules
|
||||
|
||||
Only repo owners can create view links for their repos.
|
||||
|
||||
- Myst verifies ownership via the Forgejo API using the service account PAT
|
||||
- Collaborators or read-access users cannot create view links
|
||||
- Site admins are treated as regular users for this purpose (details to be finalized)
|
||||
|
||||
## CLI Init Baseline
|
||||
|
||||
`myst init` should ask only for:
|
||||
|
||||
- public viewer URL, for example `https://share.example.com`
|
||||
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net`
|
||||
- Forgejo base URL, for example `https://git.example.com`
|
||||
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst`
|
||||
- Forgejo service account username, for example `myst-bot`
|
||||
- Forgejo PAT for that service account
|
||||
- grant token secret, with secure auto-generation as the default
|
||||
|
||||
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
|
||||
|
||||
- `.env`
|
||||
- `myst.config.json`
|
||||
- any future Myst-only deployment templates, but never Forgejo provisioning files
|
||||
|
||||
`myst init` should provide inline guidance that:
|
||||
|
||||
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
||||
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1
|
||||
- the database URL must point to Myst's own Postgres database, not Forgejo's tables
|
||||
- the PAT should be created for the dedicated service account user
|
||||
- the operator can consult Forgejo docs for token creation and scopes if needed
|
||||
- bare hostnames such as `share.example.com` are accepted and should default to `https://`
|
||||
|
||||
## Deployment Baseline
|
||||
|
||||
- Forgejo is already deployed and operator-managed
|
||||
- Myst is deployed independently as its own app
|
||||
- Myst uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables)
|
||||
- Myst reaches Forgejo via API using a least-privilege service account token
|
||||
- the CLI validates configuration and connectivity rather than provisioning infrastructure
|
||||
- the Myst admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
|
||||
|
||||
### Docker and Deployment
|
||||
|
||||
Myst provides a Dockerfile for containerized deployment:
|
||||
|
||||
- Myst includes a `Dockerfile` in its repository for building the container image
|
||||
- Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Myst container
|
||||
- Myst does not generate Docker Compose files for Forgejo or other infrastructure
|
||||
- Myst does not provision containers, images, or hosting resources
|
||||
- Operators manage their own container orchestration (Dokploy handles this for most users)
|
||||
|
||||
For Dokploy users, deploying Myst is similar to deploying any other containerized application:
|
||||
|
||||
1. Build or import the Myst image using Dokploy's Docker Compose support
|
||||
2. Configure environment variables from `.env` generated by `myst init`
|
||||
3. Set up the public and admin domains in Dokploy's domain configuration
|
||||
4. Dokploy handles Traefik routing, TLS, and container restarts
|
||||
|
||||
## Database Model
|
||||
|
||||
Myst uses its own Postgres database on the same DB server as Forgejo:
|
||||
|
||||
- separate databases (not shared tables with Forgejo)
|
||||
- recommended: same PostgreSQL instance with `forgejo` and `myst` databases
|
||||
- clean schema separation prevents coupling to Forgejo's database schema
|
||||
- independent backups and migrations
|
||||
- operators can run both databases on a small VPS efficiently
|
||||
|
||||
Minimum v1 data model:
|
||||
|
||||
- `grants`: view link metadata (repo, commit_sha, type, expiration, email, revoked)
|
||||
- `verification_codes`: email verification codes for private links
|
||||
- `sessions`: user sessions (validated against Forgejo)
|
||||
- `smtp_config`: SMTP settings (encrypted)
|
||||
|
||||
## Forgejo Bootstrap Baseline
|
||||
|
||||
`myst forgejo bootstrap` should verify, not provision:
|
||||
|
||||
- Forgejo base URL reachability
|
||||
- service account token validity
|
||||
- authenticated user matches the configured service account username
|
||||
- minimum token scopes are sufficient for Myst's read-only API usage
|
||||
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve
|
||||
- Myst can verify repo ownership for the operator's user account
|
||||
|
||||
## Viewer Baseline
|
||||
|
||||
The web-based viewer is the public-facing code display surface:
|
||||
|
||||
- displays code with syntax highlighting
|
||||
- read-only, no raw git access
|
||||
- validates link token, expiration, and revoked state
|
||||
- for private links: requires valid email verification code
|
||||
- for public links: accessible immediately with the link
|
||||
- never exposes Forgejo admin surfaces or database ports
|
||||
- pinned to immutable commit_sha (not moving branches)
|
||||
|
||||
## User Dashboard
|
||||
|
||||
The owner dashboard allows repo owners to manage their view links:
|
||||
|
||||
- list of created links (public and private)
|
||||
- link status (active, expired, revoked)
|
||||
- view count and access logs (details to be finalized)
|
||||
- create new link flow
|
||||
- revoke/delete existing links
|
||||
- SMTP configuration page
|
||||
|
||||
First-time users see a quick setup page to configure SMTP credentials before accessing the full dashboard.
|
||||
|
|
|
|||
366
docs/plans/2026-03-31-myst-auth-and-deployment-design.md
Normal file
366
docs/plans/2026-03-31-myst-auth-and-deployment-design.md
Normal file
|
|
@ -0,0 +1,366 @@
|
|||
# Myst Auth and Deployment Design
|
||||
|
||||
This document captures current decisions about deployment topology, authentication, and CLI scope for Phase 1.
|
||||
|
||||
## Goals
|
||||
|
||||
- Keep Myst self-hosted and private by default.
|
||||
- Let operators attach Myst to an existing Forgejo deployment.
|
||||
- Expose only the read-only share-link viewer and Myst UI routes the operator chooses to publish.
|
||||
- Make the CLI responsible for Myst-specific configuration, validation, and Forgejo integration checks.
|
||||
- Keep Phase 1 scope minimal and shippable.
|
||||
- Prevent code theft and scraping by controlling who can view shared links and how.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Built-in admin authentication in Myst for Phase 1.
|
||||
- Provisioning Forgejo for operators.
|
||||
- Provisioning PostgreSQL for Forgejo or Myst.
|
||||
- Owning reverse proxy, DNS, TLS, backup, or firewall setup.
|
||||
- Replacing Dokploy, Coolify, or any other hosting platform.
|
||||
- Adding a SaaS control plane.
|
||||
- Requiring end users to join Tailscale in order to view shared code.
|
||||
- Designing a browser-based admin UX before the backend and integration flow exist.
|
||||
|
||||
## Core Architecture
|
||||
|
||||
Myst is a companion service deployed beside an existing Forgejo instance. It owns its own UI/API app and its own database, and it integrates with Forgejo only through the Forgejo API.
|
||||
|
||||
```ascii
|
||||
Public Internet
|
||||
|
|
||||
v
|
||||
DNS: share.example.com (viewer)
|
||||
DNS: admin.example.com (dashboard, protected)
|
||||
|
|
||||
v
|
||||
Reverse Proxy / Platform Router
|
||||
(Dokploy, Caddy, Nginx, etc.)
|
||||
|
|
||||
v
|
||||
Myst App (Viewer + Dashboard)
|
||||
|
|
||||
-------------------
|
||||
| |
|
||||
v v
|
||||
Myst Database Forgejo API
|
||||
(Postgres) (existing instance)
|
||||
```
|
||||
|
||||
Deployment boundaries:
|
||||
|
||||
- Forgejo is already running and is managed by the operator.
|
||||
- Myst is deployed independently from Forgejo.
|
||||
- Myst never reads or writes Forgejo's database directly.
|
||||
- Myst uses a service account PAT to call the Forgejo API.
|
||||
- Myst uses Forgejo sessions to identify logged-in users.
|
||||
- Myst admin access is protected upstream rather than by an in-app login system in Phase 1.
|
||||
- VPN, Tailscale, Cloudflare Access, or reverse-proxy auth is required for the admin surface in Phase 1.
|
||||
|
||||
## Authentication
|
||||
|
||||
Myst uses two authentication mechanisms for different purposes:
|
||||
|
||||
### User Identity: Forgejo Sessions
|
||||
|
||||
Users log in via Forgejo's existing session system:
|
||||
|
||||
1. User visits Myst dashboard
|
||||
2. Myst redirects to Forgejo login page
|
||||
3. User authenticates with Forgejo credentials
|
||||
4. Forgejo sets a session cookie
|
||||
5. Myst validates the session via Forgejo API
|
||||
6. Myst knows the user's identity without maintaining its own user database
|
||||
|
||||
**Benefits:**
|
||||
- No separate Myst login — users use their existing Forgejo account
|
||||
- All Forgejo users with an account are trusted Myst users
|
||||
- No separate user management in Myst
|
||||
|
||||
### Data Access: Service Account PAT
|
||||
|
||||
Myst uses an operator-created PAT to call the Forgejo API:
|
||||
|
||||
1. Verify repo ownership when owner creates a view link
|
||||
2. Fetch code content when serving view links to viewers
|
||||
|
||||
**Why both mechanisms?**
|
||||
- Sessions identify the user (zach@me.com is logged in)
|
||||
- PAT authorizes Myst's server-to-server API calls (fetch repo data, verify ownership)
|
||||
- PAT is not used for user identity — that's the session's job
|
||||
|
||||
## Link Types
|
||||
|
||||
### Private Links (Email-Verified)
|
||||
|
||||
Intended for sharing with specific individuals via email.
|
||||
|
||||
**Creation:**
|
||||
- Owner selects repo and commit_sha
|
||||
- Owner enters recipient's email address
|
||||
- Owner sets expiration time
|
||||
- Myst generates a unique link token
|
||||
|
||||
**Viewer flow:**
|
||||
1. Owner shares the link with the recipient (via email or copy)
|
||||
2. Recipient clicks the link
|
||||
3. Recipient enters email verification code from Myst's email
|
||||
4. On successful verification, recipient can view the code snapshot
|
||||
|
||||
**Protections:**
|
||||
- Link is useless to anyone without the verification code
|
||||
- Cannot scrape or index the content
|
||||
- Owner can revoke access at any time
|
||||
|
||||
### Public Links (Time-Expired)
|
||||
|
||||
Intended for job applications, portfolios, and public sharing.
|
||||
|
||||
**Creation:**
|
||||
- Owner selects repo and commit_sha
|
||||
- Owner sets expiration time (e.g., 7 days)
|
||||
- No email required
|
||||
|
||||
**Viewer flow:**
|
||||
1. Owner copies the link
|
||||
2. Pastes into a job application field or shares publicly
|
||||
3. Anyone with the link can view immediately (no verification)
|
||||
|
||||
**Protections:**
|
||||
- Link expires automatically
|
||||
- Owner can revoke at any time
|
||||
- No public listing of repos or profiles
|
||||
|
||||
## Anti-Scraping Protections
|
||||
|
||||
Myst is designed to prevent code theft and scraping:
|
||||
|
||||
- No public listing of repositories
|
||||
- No profile exposure
|
||||
- Private links require email verification
|
||||
- Public links are time-limited and revocable
|
||||
- Links are tied to immutable commit snapshots
|
||||
- Cannot dig through repo list or browse content without a valid link
|
||||
|
||||
## Deployment
|
||||
|
||||
Myst should be deployable anywhere an operator can run a normal web app and Postgres database.
|
||||
|
||||
Recommended v1 deployment environments:
|
||||
|
||||
1. Same VPS or host as Forgejo (via Dokploy)
|
||||
2. Same Dokploy project or private network as Forgejo
|
||||
3. Separate host on the same trusted network as Forgejo
|
||||
|
||||
### Docker and Deployment
|
||||
|
||||
Myst provides a Dockerfile for containerized deployment:
|
||||
|
||||
- Myst includes a `Dockerfile` in its repository for building the container image
|
||||
- Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Myst container
|
||||
- Myst does not generate Docker Compose files for Forgejo or other infrastructure
|
||||
- Myst does not provision containers, images, or hosting resources
|
||||
- Operators manage their own container orchestration
|
||||
|
||||
For Dokploy users, deploying Myst is similar to deploying any other containerized application:
|
||||
|
||||
1. Build or import the Myst image using Dokploy's Docker Compose support
|
||||
2. Configure environment variables from `.env` generated by `myst init`
|
||||
3. Set up the public and admin domains in Dokploy's domain configuration
|
||||
4. Dokploy handles Traefik routing, TLS, and container restarts
|
||||
|
||||
### Database Configuration
|
||||
|
||||
Myst uses its own Postgres database on the same DB server as Forgejo:
|
||||
|
||||
- Separate databases (e.g., `forgejo` and `myst`)
|
||||
- NOT shared tables or schemas
|
||||
- Operators can run both on a small VPS efficiently
|
||||
- Independent backups and migrations
|
||||
|
||||
Admin access security is the operator's responsibility (VPN, firewall rules, SSO, host access, etc). Myst does not enforce or scaffold this in Phase 1.
|
||||
|
||||
Recommended admin protection modes:
|
||||
|
||||
1. Tailscale or another private network
|
||||
2. Cloudflare Access or similar identity-aware proxy
|
||||
3. Reverse-proxy basic auth or IP allowlisting when the operator accepts the trade-offs
|
||||
|
||||
Recommended hostname split:
|
||||
|
||||
- `https://share.example.com` for the public viewer
|
||||
- `https://admin.example.com` for the private admin UI
|
||||
|
||||
## CLI Responsibilities
|
||||
|
||||
The CLI is the primary way to configure and validate Myst against an existing Forgejo deployment.
|
||||
|
||||
### `init`
|
||||
|
||||
`init` should:
|
||||
|
||||
- prompt for the public viewer URL, for example `https://share.example.com`
|
||||
- prompt for the private admin URL, for example `https://admin.example.com`
|
||||
- prompt for the Forgejo base URL, for example `https://git.example.com`
|
||||
- collect the Forgejo service account username, for example `myst-bot`
|
||||
- collect a user-created Forgejo PAT for that service account
|
||||
- collect Myst Postgres connection details, for example `postgresql://myst:password@db.example.com:5432/myst`
|
||||
- generate a grant token secret by default unless the operator pastes one
|
||||
- generate all Myst-owned config files needed for deployment in Phase 1
|
||||
- write `.env`
|
||||
- write `myst.config.json`
|
||||
- print manual follow-up actions for admin URL protection, app deployment, and Forgejo validation
|
||||
- show links to Forgejo docs for API usage, token scopes, repo permissions, and the admin CLI
|
||||
- remind operators to run `myst init` in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
||||
|
||||
**Setup is manual** — operators enter all values directly. No auto-detection of Forgejo configuration.
|
||||
|
||||
Suggested `init` prompt guidance:
|
||||
|
||||
- Public viewer URL: "What public URL should viewers use for shared links?" Example: `https://share.example.com`
|
||||
- Private admin URL: "What private URL should operators use for the Myst admin UI?" Example: `https://admin.example.com`
|
||||
- Forgejo base URL: "What is the base URL of your existing Forgejo instance?" Example: `https://git.example.com`
|
||||
- Myst database URL: "What Postgres connection string should Myst use?" Example: `postgresql://myst:password@db.example.com:5432/myst`
|
||||
- Forgejo service account username: "What Forgejo username should Myst use for API access?" Example: `myst-bot`
|
||||
- Forgejo PAT: "Paste the Forgejo personal access token for that service account" Example: `fgp_...`
|
||||
- Grant token secret: "Paste a grant token secret, or press enter to generate one automatically"
|
||||
|
||||
Suggested `init` prompt notes:
|
||||
|
||||
- "Protect the admin URL upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth. Myst does not provide admin auth in Phase 1."
|
||||
- "Use a dedicated Forgejo user for Myst and create the PAT as that user."
|
||||
- "Recommended PAT scopes: `read:user`, `read:repository`; add `read:organization` only if your org or team setup requires it."
|
||||
- "Do not point Myst at Forgejo's database tables."
|
||||
- "Bare hostnames such as `share.example.com` are accepted and default to `https://`. Enter the full URL only if you need `http://` or a custom path."
|
||||
- "Run `myst init` in the directory where you plan to deploy Myst so the generated files are already in place on the target host."
|
||||
|
||||
Forgejo docs to link directly from CLI output:
|
||||
|
||||
- `https://forgejo.org/docs/latest/user/api-usage/`
|
||||
- `https://forgejo.org/docs/latest/user/token-scope/`
|
||||
- `https://forgejo.org/docs/latest/user/repo-permissions/`
|
||||
- `https://forgejo.org/docs/latest/admin/command-line/`
|
||||
|
||||
### `forgejo bootstrap`
|
||||
|
||||
`forgejo bootstrap` should:
|
||||
|
||||
- validate Forgejo connectivity
|
||||
- validate the provided service account token
|
||||
- verify minimum required scopes and permissions
|
||||
- confirm Myst can resolve the repos it needs
|
||||
- confirm the authenticated user matches the configured service account username
|
||||
- confirm Myst can resolve a branch or ref to a pinned `commit_sha`
|
||||
- confirm Myst can read tree and file data for a pinned commit
|
||||
- verify Myst can confirm repo ownership for the operator's user account
|
||||
- never create Forgejo users, PATs, or repo permissions
|
||||
|
||||
### `doctor`
|
||||
|
||||
`doctor` should:
|
||||
|
||||
- validate the local Myst config
|
||||
- validate database connectivity
|
||||
- validate Forgejo API reachability
|
||||
- validate token/scopes/permissions
|
||||
- validate the public base URL and key route assumptions
|
||||
|
||||
### `config print`
|
||||
|
||||
`config print` should:
|
||||
|
||||
- show resolved Myst configuration
|
||||
- redact secrets by default
|
||||
- help operators debug misconfiguration without touching infrastructure
|
||||
|
||||
### CLI UX
|
||||
|
||||
- Use spinners for long-running steps.
|
||||
- Use prompts for interactive configuration.
|
||||
- Keep output terse and actionable.
|
||||
- Present required manual follow-up actions clearly after initialization.
|
||||
|
||||
## Configuration Outputs
|
||||
|
||||
Expected outputs from `init`:
|
||||
|
||||
- `.env`
|
||||
- `myst.config.json`
|
||||
- optional platform templates for Myst only (e.g., Docker Compose for Dokploy)
|
||||
|
||||
## Data Model
|
||||
|
||||
Myst stores its metadata in its own Postgres database (separate from Forgejo's database).
|
||||
|
||||
Minimum v1 data model:
|
||||
|
||||
- `grants`: view link metadata (repo_id, commit_sha, type, expiration, email, revoked, created_by)
|
||||
- `verification_codes`: email verification codes for private links (code, email, grant_id, expires_at)
|
||||
- `sessions`: user sessions (session_token, forgejo_user_id, created_at, expires_at)
|
||||
- `smtp_config`: SMTP settings (encrypted, configured via dashboard)
|
||||
|
||||
Key constraints:
|
||||
|
||||
- grants are tied to immutable commit snapshots
|
||||
- viewer endpoints never accept arbitrary repo/ref selection
|
||||
- link tokens are unique and unguessable
|
||||
- verification codes expire quickly (e.g., 15 minutes)
|
||||
|
||||
## User Dashboard
|
||||
|
||||
The owner dashboard provides:
|
||||
|
||||
- List of created links (public and private)
|
||||
- Link status (active, expired, revoked)
|
||||
- View count and access logs (details to be finalized)
|
||||
- Create new link flow:
|
||||
- Select repo (fetched via service account PAT, filtered to owned repos)
|
||||
- Select commit (branch/tag to SHA resolution)
|
||||
- Choose link type (public or private)
|
||||
- Set expiration
|
||||
- For private: enter recipient email
|
||||
- Revoke/delete existing links
|
||||
- SMTP configuration page
|
||||
|
||||
**First-time setup:**
|
||||
- After logging in via Forgejo, users see a quick setup page to configure SMTP credentials
|
||||
- Once configured, full dashboard access is granted
|
||||
|
||||
## Viewer Rules
|
||||
|
||||
The viewer is the only public application surface that emits code content.
|
||||
|
||||
- Share links are tied to immutable snapshots (commit_sha)
|
||||
- Viewer requests must validate:
|
||||
- link token
|
||||
- expiration
|
||||
- revoked state
|
||||
- snapshot binding
|
||||
- for private links: valid email verification code
|
||||
- Public access must be read-only
|
||||
- Public access must not expose database ports or Forgejo admin surfaces
|
||||
|
||||
## Repo Implementation Impact
|
||||
|
||||
Active surfaces:
|
||||
|
||||
- CLI entrypoint: `packages/cli/src/index.ts`
|
||||
- Command stubs: `packages/cli/src/commands/*`
|
||||
- Config generators: `packages/cli/src/generators/*`
|
||||
- Shared constants/types: `packages/shared/src/*`
|
||||
- Service entrypoint: `packages/service/src/index.ts`
|
||||
- Viewer routes: `packages/service/src/viewer/*`
|
||||
- Dashboard routes: `packages/service/src/dashboard/*`
|
||||
|
||||
Next implementation work:
|
||||
|
||||
1. Narrow `init` to Myst-only config generation for an existing Forgejo deployment
|
||||
2. Add config types for Forgejo connection details, Myst base URL, database, and SMTP settings
|
||||
3. Implement `forgejo bootstrap` and `doctor`
|
||||
4. Add Postgres-backed service foundation using the data model
|
||||
5. Wire the service to load generated config and validate required env at startup
|
||||
6. Implement Forgejo session authentication for the dashboard
|
||||
7. Build the link creation flow with repo ownership verification
|
||||
8. Implement the web-based code viewer
|
||||
9. Build the user dashboard with access logs
|
||||
10. Implement email sending for private link verification codes
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
{
|
||||
"name": "embargo",
|
||||
"name": "myst",
|
||||
"private": true,
|
||||
"version": "0.1.0",
|
||||
"packageManager": "pnpm@10.11.0",
|
||||
"packageManager": "pnpm@10.33.0",
|
||||
"devDependencies": {
|
||||
"@types/node": "^24.0.0",
|
||||
"typescript": "^5.8.3"
|
||||
|
|
|
|||
6
packages/cli/examples/myst.config.example.json
Normal file
6
packages/cli/examples/myst.config.example.json
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
{
|
||||
"adminUrl": "https://admin.example.com",
|
||||
"forgejoBaseUrl": "https://git.example.com",
|
||||
"forgejoServiceAccountUsername": "myst-bot",
|
||||
"publicUrl": "https://share.example.com"
|
||||
}
|
||||
|
|
@ -1,10 +1,19 @@
|
|||
{
|
||||
"name": "@embargo/cli",
|
||||
"name": "@myst/cli",
|
||||
"description": "A CLI tool that helps you wire Myst into an existing Forgejo instance with expiring grant access controls for repos you choose to share.",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "Zach Tatman",
|
||||
"email": "zach.c.tatman@gmail.com"
|
||||
},
|
||||
"bugs": {
|
||||
"url": "https://github.com/ZTatman/myst/issues"
|
||||
},
|
||||
"homepage": "https://github.com/ZTatman/myst#readme",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"embargo": "./dist/index.js"
|
||||
"myst": "./dist/index.js"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc -p tsconfig.json",
|
||||
|
|
@ -12,6 +21,8 @@
|
|||
"clean": "rm -rf dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"@embargo/shared": "workspace:*"
|
||||
"@clack/prompts": "^1.2.0",
|
||||
"@myst/shared": "workspace:*",
|
||||
"yoctocolors": "^2.1.2"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
273
packages/cli/src/commands/init.ts
Normal file
273
packages/cli/src/commands/init.ts
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
import fs from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import * as c from "yoctocolors";
|
||||
import * as p from "@clack/prompts";
|
||||
|
||||
import { generateSecret } from "../utils/crypto.js";
|
||||
import { generateEnvFile } from "../utils/env.js";
|
||||
|
||||
/**
|
||||
* Normalizes a URL to use https:// if no protocol is specified.
|
||||
* @param value - The URL to normalize.
|
||||
* @returns {string} The normalized URL.
|
||||
*/
|
||||
function normalizeHttpUrl(value: string): string {
|
||||
const trimmed = value.trim();
|
||||
const hasProtocol = /^[a-z]+:\/\//i.test(trimmed);
|
||||
const isNotHttp = !/^https?:\/\//i.test(trimmed);
|
||||
|
||||
if (hasProtocol && isNotHttp) {
|
||||
throw new Error("URLs must use http:// or https://");
|
||||
}
|
||||
|
||||
return hasProtocol ? trimmed : `https://${trimmed}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a URL or host, returning the normalized URL or undefined if valid.
|
||||
* @param value - The URL or host to validate.
|
||||
* @param label - The label to use in error messages.
|
||||
* @returns {string | undefined} The normalized URL or undefined if valid.
|
||||
*/
|
||||
function validateHttpUrlOrHost(
|
||||
value: string | undefined,
|
||||
label: string,
|
||||
): string | undefined {
|
||||
if (!value?.trim()) return `${label} is required`;
|
||||
|
||||
try {
|
||||
const normalized = normalizeHttpUrl(value);
|
||||
const url = new URL(normalized);
|
||||
|
||||
if (!url.hostname) {
|
||||
return `${label} must include a domain or hostname`;
|
||||
}
|
||||
} catch {
|
||||
return `${label} must be a valid URL or hostname`;
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a Postgres URL, returning undefined if valid.
|
||||
* @param value - The Postgres URL to validate.
|
||||
* @returns {string | undefined} The error message or undefined if valid.
|
||||
*/
|
||||
function validatePostgresUrl(value: string | undefined): string | undefined {
|
||||
if (!value?.trim()) {
|
||||
return "Database URL is required";
|
||||
}
|
||||
|
||||
try {
|
||||
const url = new URL(value);
|
||||
if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
|
||||
return "Database URL must start with postgres:// or postgresql://";
|
||||
}
|
||||
} catch {
|
||||
return "Database URL must be a valid Postgres connection string";
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Writes a private file to disk, throwing an error if the file already exists.
|
||||
* @param filePath - The path to the file to write.
|
||||
* @param content - The content to write to the file.
|
||||
* @returns {Promise<void>} A promise that resolves when the file is written.
|
||||
*/
|
||||
async function writePrivateFile(
|
||||
filePath: string,
|
||||
content: string,
|
||||
): Promise<void> {
|
||||
try {
|
||||
await fs.writeFile(filePath, content, {
|
||||
encoding: "utf8",
|
||||
flag: "wx",
|
||||
mode: 0o600,
|
||||
});
|
||||
} catch (e) {
|
||||
const error = e as NodeJS.ErrnoException;
|
||||
if (error.code === "EEXIST") {
|
||||
throw new Error(
|
||||
`Error: the file '${c.underline(path.basename(filePath))}' already exists in directory ${c.underline(path.dirname(filePath))}`,
|
||||
);
|
||||
}
|
||||
throw error; // throw any other errors back if not EEXIST code
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Preflight check for write targets, throwing an error if any target file already exists.
|
||||
* @param filePaths - The paths of the files to write.
|
||||
* @returns {Promise<void>} A promise that resolves when all targets are checked.
|
||||
*/
|
||||
async function preflightWriteTargets(filePaths: string[]): Promise<void> {
|
||||
for (const filePath of filePaths) {
|
||||
try {
|
||||
await fs.access(filePath);
|
||||
throw new Error(
|
||||
`Error: the file '${c.underline(path.basename(filePath))}' already exists in directory ${c.underline(path.dirname(filePath))}`,
|
||||
);
|
||||
} catch (error) {
|
||||
const err = error as NodeJS.ErrnoException;
|
||||
if (err.code !== "ENOENT") {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Initializes a Myst project by creating the necessary configuration files.
|
||||
* @param _args - The command arguments.
|
||||
* @returns {Promise<void>} A promise that resolves when the initialization is complete.
|
||||
*/
|
||||
export async function initCommand(_args: string[]): Promise<void> {
|
||||
p.intro(c.bold("myst init"));
|
||||
p.note(
|
||||
[
|
||||
`${c.bold("Run this in the directory where you plan to deploy Myst.")}`,
|
||||
"",
|
||||
c.bold("Forgejo docs:"),
|
||||
"",
|
||||
`- API usage: ${c.cyan("https://forgejo.org/docs/latest/user/api-usage/")}`,
|
||||
`- Token scopes: ${c.cyan("https://forgejo.org/docs/latest/user/token-scope/")}`,
|
||||
`- Repo permissions: ${c.cyan("https://forgejo.org/docs/latest/user/repo-permissions/")}`,
|
||||
`- Admin CLI: ${c.cyan("https://forgejo.org/docs/latest/admin/command-line/")}`,
|
||||
"",
|
||||
`1. Create a dedicated Forgejo user such as ${c.bold("myst-bot")} and generate its PAT in Forgejo ${c.bold("Settings -> Applications")}.`,
|
||||
`2. Generate a PAT with the appropriate scopes for your Forgejo setup.`,
|
||||
"",
|
||||
`Recommended PAT scopes:\n - ${c.bold("read:user")}\n - ${c.bold("read:repository")}\n - ${c.bold("read:organization")} (optional)`,
|
||||
].join("\n"),
|
||||
c.yellow("Before you start:"),
|
||||
);
|
||||
|
||||
const answers = await p.group(
|
||||
{
|
||||
publicUrl: () =>
|
||||
p.text({
|
||||
message: "Domain name or URL for the public viewer",
|
||||
placeholder: "share.example.com",
|
||||
validate: (v) => validateHttpUrlOrHost(v, "Public viewer URL"),
|
||||
}),
|
||||
adminUrl: () =>
|
||||
p.text({
|
||||
message: "Domain name or URL for the Myst admin UI",
|
||||
placeholder: "admin.example.com",
|
||||
validate: (v) => validateHttpUrlOrHost(v, "Private admin URL"),
|
||||
}),
|
||||
forgejoBaseUrl: () =>
|
||||
p.text({
|
||||
message: "Domain name or URL for your existing Forgejo instance?",
|
||||
placeholder: "git.example.com",
|
||||
validate: (v) => validateHttpUrlOrHost(v, "Forgejo base URL"),
|
||||
}),
|
||||
databaseUrl: () =>
|
||||
p.text({
|
||||
message: "What Postgres connection string should Myst use?",
|
||||
placeholder: "postgresql://myst:password@db.example.com:5432/myst",
|
||||
validate: validatePostgresUrl,
|
||||
}),
|
||||
forgejoServiceAccountUsername: () =>
|
||||
p.text({
|
||||
message:
|
||||
"What Forgejo service account username should Myst use for API access?",
|
||||
placeholder: "myst-bot",
|
||||
validate: (v) =>
|
||||
v?.trim()
|
||||
? undefined
|
||||
: "Forgejo service account username is required",
|
||||
}),
|
||||
forgejoPat: () =>
|
||||
p.password({
|
||||
message:
|
||||
"Paste the Forgejo personal access token for that service account",
|
||||
validate: (v) => (v?.trim() ? undefined : "Forgejo PAT is required"),
|
||||
}),
|
||||
grantTokenSecret: () =>
|
||||
p.password({
|
||||
message:
|
||||
"Paste a grant token secret, or press enter to generate one automatically",
|
||||
validate: () => undefined,
|
||||
}),
|
||||
},
|
||||
{
|
||||
onCancel: () => {
|
||||
p.cancel("\nOperation cancelled.");
|
||||
process.exit(0);
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
const s = p.spinner();
|
||||
s.start("Generating config files");
|
||||
const publicUrl = normalizeHttpUrl(answers.publicUrl);
|
||||
const adminUrl = normalizeHttpUrl(answers.adminUrl);
|
||||
const forgejoBaseUrl = normalizeHttpUrl(answers.forgejoBaseUrl);
|
||||
const grantTokenSecret = answers.grantTokenSecret?.trim() || generateSecret();
|
||||
const envContent = generateEnvFile({
|
||||
adminUrl,
|
||||
databaseUrl: answers.databaseUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoPat: answers.forgejoPat,
|
||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
||||
grantTokenSecret,
|
||||
publicUrl,
|
||||
});
|
||||
const configContent = JSON.stringify(
|
||||
{
|
||||
adminUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
||||
publicUrl,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
);
|
||||
|
||||
const outDir = process.cwd();
|
||||
const envPath = path.join(outDir, ".env");
|
||||
const configPath = path.join(outDir, "myst.config.json");
|
||||
|
||||
try {
|
||||
await preflightWriteTargets([envPath, configPath]);
|
||||
await writePrivateFile(envPath, envContent);
|
||||
await writePrivateFile(configPath, configContent);
|
||||
} catch (e) {
|
||||
s.stop();
|
||||
p.cancel(
|
||||
e instanceof Error
|
||||
? e.message
|
||||
: `Failed to write config files to ${outDir}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
s.stop("Config files generated");
|
||||
|
||||
p.note(
|
||||
[c.green(".env"), c.green("myst.config.json")].join("\n"),
|
||||
c.yellow("Files written to current directory"),
|
||||
);
|
||||
|
||||
p.note(
|
||||
[
|
||||
`${c.bold("Public viewer URL:")} ${c.cyan(publicUrl)}`,
|
||||
`${c.bold("Private admin URL:")} ${c.cyan(adminUrl)}`,
|
||||
`${c.bold("Forgejo base URL:")} ${c.cyan(forgejoBaseUrl)}`,
|
||||
`${c.bold("Forgejo service account:")} ${c.green(answers.forgejoServiceAccountUsername)}`,
|
||||
"",
|
||||
`${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`,
|
||||
].join("\n"),
|
||||
c.yellow("Next steps"),
|
||||
);
|
||||
p.outro(
|
||||
c.green(
|
||||
"Done. Deploy Myst, then run forgejo bootstrap and doctor commands to verify setup.",
|
||||
),
|
||||
);
|
||||
}
|
||||
|
|
@ -1,14 +1,113 @@
|
|||
import { EMBARGO_DEFAULT_FORGEJO_PORT, EMBARGO_DEFAULT_SERVICE_PORT } from "@embargo/shared";
|
||||
#!/usr/bin/env node
|
||||
import * as c from "yoctocolors";
|
||||
import pkg from "../package.json" with { type: "json" };
|
||||
|
||||
function main(): void {
|
||||
process.stdout.write(
|
||||
[
|
||||
"Embargo CLI bootstrap",
|
||||
`Forgejo default port: ${EMBARGO_DEFAULT_FORGEJO_PORT}`,
|
||||
`Service default port: ${EMBARGO_DEFAULT_SERVICE_PORT}`
|
||||
].join("\n") + "\n"
|
||||
);
|
||||
import { initCommand } from "./commands/init.js";
|
||||
|
||||
const PADDING = 4;
|
||||
const INDENT = " ";
|
||||
const USAGE = "myst <command> [options/flags] [arguments]";
|
||||
|
||||
type CommandName = "init";
|
||||
|
||||
interface Option {
|
||||
name: CommandName | string | string[];
|
||||
desc: string;
|
||||
}
|
||||
|
||||
main();
|
||||
interface CLIConfig {
|
||||
commands: Option[];
|
||||
globalFlags: Option[];
|
||||
}
|
||||
|
||||
const config: CLIConfig = {
|
||||
commands: [
|
||||
{ name: "init", desc: "Bootstrap Myst and generate config/env files" },
|
||||
],
|
||||
globalFlags: [
|
||||
{ name: ["-h", "--help"], desc: "Display help information" },
|
||||
{ name: ["-v", "--version"], desc: "Display package version number" },
|
||||
],
|
||||
};
|
||||
|
||||
const splitCamelCaseWords = (text: string): string =>
|
||||
text.replace(/([a-z])([A-Z])/g, "$1 $2");
|
||||
|
||||
const toTitleCase = (text: string): string =>
|
||||
text.replace(/\b\w/g, (c) => c.toUpperCase());
|
||||
|
||||
function formatSection(
|
||||
header: string,
|
||||
options: Option[],
|
||||
colWidth: number,
|
||||
): string {
|
||||
const rows = options.map((o) => {
|
||||
const name = Array.isArray(o.name) ? o.name.join(", ") : o.name;
|
||||
return `${INDENT}${name.padEnd(colWidth)}${o.desc}`;
|
||||
});
|
||||
const title = toTitleCase(splitCamelCaseWords(header));
|
||||
return [c.bold(title + ":"), ...rows].join("\n");
|
||||
}
|
||||
|
||||
const allOptions = Object.values(config).flat();
|
||||
const COL_WIDTH =
|
||||
Math.max(
|
||||
...allOptions.map((o) =>
|
||||
Array.isArray(o.name) ? o.name.join(", ").length : o.name.length,
|
||||
),
|
||||
) + PADDING;
|
||||
|
||||
const HELP_TEXT = `
|
||||
${c.yellow(pkg.name)}
|
||||
|
||||
|
||||
${INDENT}${USAGE}
|
||||
|
||||
|
||||
${Object.entries(config)
|
||||
.map(([header, options]) =>
|
||||
formatSection(header, options as Option[], COL_WIDTH),
|
||||
)
|
||||
.join("\n\n")}
|
||||
`;
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const [command, ...options] = process.argv.slice(2);
|
||||
const flags = options.filter((o) => o.startsWith("-"));
|
||||
|
||||
if (flags.includes("-v") || flags.includes("--version")) {
|
||||
process.stdout.write(`${pkg.version}\n`);
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
|
||||
if (!command || flags.includes("-h") || flags.includes("--help")) {
|
||||
process.stdout.write(`${HELP_TEXT}`);
|
||||
process.exitCode = 0;
|
||||
return;
|
||||
}
|
||||
|
||||
const knownCommands: Record<CommandName, (args: string[]) => Promise<void>> =
|
||||
{
|
||||
init: initCommand,
|
||||
};
|
||||
|
||||
const isKnownCommand = (cmd: string): cmd is CommandName =>
|
||||
cmd in knownCommands;
|
||||
|
||||
if (!isKnownCommand(command)) {
|
||||
process.stderr.write(`Unknown command: ${command}\n`);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
await knownCommands[command](options);
|
||||
} catch (error) {
|
||||
const message = error instanceof Error ? error.message : "Unknown error";
|
||||
process.stderr.write(`${c.red("Error:")} ${message}\n`);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
}
|
||||
|
||||
await main();
|
||||
|
|
|
|||
9
packages/cli/src/utils/crypto.ts
Normal file
9
packages/cli/src/utils/crypto.ts
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
import { randomBytes } from "node:crypto";
|
||||
|
||||
export function generateSecret(bytes = 32): string {
|
||||
return randomBytes(bytes).toString("hex");
|
||||
}
|
||||
|
||||
export function generatePassword(bytes = 16): string {
|
||||
return randomBytes(bytes).toString("base64url");
|
||||
}
|
||||
41
packages/cli/src/utils/env.ts
Normal file
41
packages/cli/src/utils/env.ts
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
interface EnvOptions {
|
||||
adminUrl: string;
|
||||
databaseUrl: string;
|
||||
forgejoBaseUrl: string;
|
||||
forgejoPat: string;
|
||||
forgejoServiceAccountUsername: string;
|
||||
grantTokenSecret: string;
|
||||
publicUrl: string;
|
||||
}
|
||||
|
||||
function escapeEnvValue(value: string): string {
|
||||
return `"${value
|
||||
.replace(/\\/g, "\\\\") // Escape backslashes
|
||||
.replace(/"/g, '\\"') // Escape double quotes
|
||||
.replace(/\r?\n/g, "\\n")}"`; // Escape newlines
|
||||
}
|
||||
|
||||
/**
|
||||
* Generates an .env file for Myst with the given options.
|
||||
* @param options - The options for generating the .env file.
|
||||
* @returns {string} The .env file formatted as a string.
|
||||
*/
|
||||
export function generateEnvFile(options: EnvOptions): string {
|
||||
return `# Public URL used for share links.
|
||||
MYST_PUBLIC_URL=${escapeEnvValue(options.publicUrl)}
|
||||
|
||||
# Private operator URL for the admin UI. Protect this upstream.
|
||||
MYST_ADMIN_URL=${escapeEnvValue(options.adminUrl)}
|
||||
|
||||
# Myst's own Postgres database.
|
||||
DATABASE_URL=${escapeEnvValue(options.databaseUrl)}
|
||||
|
||||
# Existing Forgejo instance and operator-created service account token.
|
||||
FORGEJO_BASE_URL=${escapeEnvValue(options.forgejoBaseUrl)}
|
||||
FORGEJO_SERVICE_ACCOUNT_USERNAME=${escapeEnvValue(options.forgejoServiceAccountUsername)}
|
||||
FORGEJO_PAT=${escapeEnvValue(options.forgejoPat)}
|
||||
|
||||
# Secret used to sign or derive grant tokens.
|
||||
GRANT_TOKEN_SECRET=${escapeEnvValue(options.grantTokenSecret)}
|
||||
`;
|
||||
}
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"name": "@embargo/service",
|
||||
"name": "@myst/service",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
|
|
@ -9,6 +9,6 @@
|
|||
"clean": "rm -rf dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"@embargo/shared": "workspace:*"
|
||||
"@myst/shared": "workspace:*"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
import { EMBARGO_DEFAULT_SERVICE_PORT } from "@embargo/shared";
|
||||
import { MYST_DEFAULT_SERVICE_PORT } from "@myst/shared";
|
||||
|
||||
process.stdout.write(`Embargo service bootstrap on port ${EMBARGO_DEFAULT_SERVICE_PORT}\n`);
|
||||
process.stdout.write(`Myst service bootstrap on port ${MYST_DEFAULT_SERVICE_PORT}\n`);
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"name": "@embargo/shared",
|
||||
"name": "@myst/shared",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
export const EMBARGO_DEFAULT_FORGEJO_PORT = 3000;
|
||||
export const EMBARGO_DEFAULT_SERVICE_PORT = 4000;
|
||||
export const MYST_DEFAULT_FORGEJO_PORT = 3000;
|
||||
export const MYST_DEFAULT_SERVICE_PORT = 4000;
|
||||
|
||||
export const EMBARGO_VISIBILITY_MODES = {
|
||||
export const MYST_VISIBILITY_MODES = {
|
||||
TEAM: "team",
|
||||
ALLOWLIST: "allowlist"
|
||||
} as const;
|
||||
|
||||
|
|
|
|||
58
pnpm-lock.yaml
generated
58
pnpm-lock.yaml
generated
|
|
@ -17,13 +17,19 @@ importers:
|
|||
|
||||
packages/cli:
|
||||
dependencies:
|
||||
'@embargo/shared':
|
||||
'@clack/prompts':
|
||||
specifier: ^1.2.0
|
||||
version: 1.2.0
|
||||
'@myst/shared':
|
||||
specifier: workspace:*
|
||||
version: link:../shared
|
||||
yoctocolors:
|
||||
specifier: ^2.1.2
|
||||
version: 2.1.2
|
||||
|
||||
packages/service:
|
||||
dependencies:
|
||||
'@embargo/shared':
|
||||
'@myst/shared':
|
||||
specifier: workspace:*
|
||||
version: link:../shared
|
||||
|
||||
|
|
@ -31,9 +37,27 @@ importers:
|
|||
|
||||
packages:
|
||||
|
||||
'@clack/core@1.2.0':
|
||||
resolution: {integrity: sha512-qfxof/3T3t9DPU/Rj3OmcFyZInceqj/NVtO9rwIuJqCUgh32gwPjpFQQp/ben07qKlhpwq7GzfWpST4qdJ5Drg==}
|
||||
|
||||
'@clack/prompts@1.2.0':
|
||||
resolution: {integrity: sha512-4jmztR9fMqPMjz6H/UZXj0zEmE43ha1euENwkckKKel4XpSfokExPo5AiVStdHSAlHekz4d0CA/r45Ok1E4D3w==}
|
||||
|
||||
'@types/node@24.12.0':
|
||||
resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
|
||||
|
||||
fast-string-truncated-width@1.2.1:
|
||||
resolution: {integrity: sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==}
|
||||
|
||||
fast-string-width@1.1.0:
|
||||
resolution: {integrity: sha512-O3fwIVIH5gKB38QNbdg+3760ZmGz0SZMgvwJbA1b2TGXceKE6A2cOlfogh1iw8lr049zPyd7YADHy+B7U4W9bQ==}
|
||||
|
||||
fast-wrap-ansi@0.1.6:
|
||||
resolution: {integrity: sha512-HlUwET7a5gqjURj70D5jl7aC3Zmy4weA1SHUfM0JFI0Ptq987NH2TwbBFLoERhfwk+E+eaq4EK3jXoT+R3yp3w==}
|
||||
|
||||
sisteransi@1.0.5:
|
||||
resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
|
||||
|
||||
typescript@5.9.3:
|
||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
||||
engines: {node: '>=14.17'}
|
||||
|
|
@ -42,12 +66,42 @@ packages:
|
|||
undici-types@7.16.0:
|
||||
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
|
||||
|
||||
yoctocolors@2.1.2:
|
||||
resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
|
||||
engines: {node: '>=18'}
|
||||
|
||||
snapshots:
|
||||
|
||||
'@clack/core@1.2.0':
|
||||
dependencies:
|
||||
fast-wrap-ansi: 0.1.6
|
||||
sisteransi: 1.0.5
|
||||
|
||||
'@clack/prompts@1.2.0':
|
||||
dependencies:
|
||||
'@clack/core': 1.2.0
|
||||
fast-string-width: 1.1.0
|
||||
fast-wrap-ansi: 0.1.6
|
||||
sisteransi: 1.0.5
|
||||
|
||||
'@types/node@24.12.0':
|
||||
dependencies:
|
||||
undici-types: 7.16.0
|
||||
|
||||
fast-string-truncated-width@1.2.1: {}
|
||||
|
||||
fast-string-width@1.1.0:
|
||||
dependencies:
|
||||
fast-string-truncated-width: 1.2.1
|
||||
|
||||
fast-wrap-ansi@0.1.6:
|
||||
dependencies:
|
||||
fast-string-width: 1.1.0
|
||||
|
||||
sisteransi@1.0.5: {}
|
||||
|
||||
typescript@5.9.3: {}
|
||||
|
||||
undici-types@7.16.0: {}
|
||||
|
||||
yoctocolors@2.1.2: {}
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
"lib": ["ES2022"],
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@embargo/shared": ["packages/shared/src/index.ts"]
|
||||
"@myst/shared": ["packages/shared/src/index.ts"]
|
||||
},
|
||||
"strict": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue