mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-20 12:03:30 +00:00
refactor: rename Myst and narrow CLI setup flow
This commit is contained in:
parent
f38d3843ac
commit
b5595b4e85
19 changed files with 546 additions and 226 deletions
45
README.md
45
README.md
|
|
@ -1,8 +1,8 @@
|
|||
# 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 private code snapshots.
|
||||
|
||||
## Phase 1 PR Breakdown
|
||||
|
||||
|
|
@ -17,20 +17,41 @@ Phase 1 is split into these reviewable branches:
|
|||
|
||||
## Core Principles
|
||||
|
||||
- Embargo runs beside Forgejo and talks to it only through the Forgejo API.
|
||||
- Myst 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.
|
||||
- Myst keeps the admin surface private through operator-managed network or reverse-proxy protection.
|
||||
- Myst does not provide built-in admin authentication in Phase 1; VPN, Tailscale, Cloudflare Access, or reverse-proxy auth is required for the admin surface.
|
||||
- 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.
|
||||
- A repo is shareable only if the service account can see it and Myst has sharing enabled for it.
|
||||
|
||||
## Current CLI Surface
|
||||
## Forgejo Integration Requirements
|
||||
|
||||
- A Forgejo "service account" for Myst is a normal Forgejo user created by the operator, such as `myst-bot`.
|
||||
- The operator creates the PAT for that user and grants repo access explicitly.
|
||||
- Recommended PAT scopes are `read:user` and `read:repository`.
|
||||
- Some organization or team-based setups may also require `read:organization`.
|
||||
- Myst validates the account and token; it does not create Forgejo users, PATs, or repo permissions.
|
||||
|
||||
Helpful Forgejo docs:
|
||||
|
||||
- API usage: `https://forgejo.org/docs/latest/user/api-usage/`
|
||||
- Token scopes: `https://forgejo.org/docs/latest/user/token-scope/`
|
||||
- Repo permissions: `https://forgejo.org/docs/latest/user/repo-permissions/`
|
||||
- Admin CLI: `https://forgejo.org/docs/latest/admin/command-line/`
|
||||
|
||||
## Planned CLI Surface
|
||||
|
||||
```bash
|
||||
pnpm --filter @embargo/cli build
|
||||
node packages/cli/dist/index.js init --dir ./embargo
|
||||
node packages/cli/dist/index.js status --dir ./embargo
|
||||
node packages/cli/dist/index.js start --dir ./embargo
|
||||
node packages/cli/dist/index.js stop --dir ./embargo
|
||||
pnpm --filter @myst/cli build
|
||||
node packages/cli/dist/index.js init
|
||||
node packages/cli/dist/index.js forgejo bootstrap
|
||||
node packages/cli/dist/index.js doctor
|
||||
node packages/cli/dist/index.js config print
|
||||
```
|
||||
|
||||
The CLI is intended to wire Myst into an existing Forgejo deployment. It should not provision Forgejo, Postgres, TLS, or reverse proxies for operators.
|
||||
|
||||
- `myst init` generates the Myst-owned configuration files needed for deployment, including `.env` and `myst.config.json`.
|
||||
- `myst forgejo bootstrap` verifies Forgejo reachability, service-account identity, token scopes, and read access to the repo data Myst needs.
|
||||
|
||||
The Phase 1 pull requests are intentionally stacked so each review focuses on one layer of the system at a time.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,24 @@
|
|||
# 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
|
||||
|
||||
Phase 1 does not deliver:
|
||||
|
||||
- Forgejo provisioning
|
||||
- Forgejo database provisioning
|
||||
- reverse proxy or DNS automation
|
||||
- platform-specific hosting orchestration beyond optional templates and docs
|
||||
|
||||
## Reviewable Branches
|
||||
|
||||
1. `codex/phase1-bootstrap-monorepo`
|
||||
|
|
@ -24,6 +31,65 @@ 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
|
||||
|
||||
## 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
|
||||
|
||||
## 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
|
||||
- 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
|
||||
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -1,136 +0,0 @@
|
|||
# EmbarGit Auth and Deployment Design
|
||||
|
||||
This document captures current decisions about deployment topology and CLI scope for Phase 1.
|
||||
|
||||
## Goals
|
||||
|
||||
- Keep EmbarGit self-hosted and private by default.
|
||||
- Expose only the read-only share-link viewer to the public internet.
|
||||
- Make the CLI responsible for generating deployment files and setup scaffolding.
|
||||
- Keep Phase 1 scope minimal and shippable.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Any admin authentication layer (no Tailscale, no Pocket ID, no login screen).
|
||||
- Reverse proxy generation or examples.
|
||||
- Cloudflare integration or documentation.
|
||||
- Replacing Forgejo.
|
||||
- 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 deployment scaffolding exist.
|
||||
|
||||
## Core Architecture
|
||||
|
||||
EmbarGit has two distinct surfaces:
|
||||
|
||||
- Public viewer surface for read-only share links.
|
||||
- Private admin and operational surface for owners/operators.
|
||||
|
||||
The security boundary is the public/private split, not an auth layer.
|
||||
|
||||
```ascii
|
||||
Public internet
|
||||
|
|
||||
v
|
||||
Read-only viewer endpoint
|
||||
|
|
||||
+--> Embargo/EmbarGit app
|
||||
|
|
||||
+--> Private Forgejo API
|
||||
|
|
||||
+--> Private database
|
||||
|
||||
Admin/operator access
|
||||
|
|
||||
v
|
||||
Direct host or VPN (operator's responsibility)
|
||||
|
|
||||
v
|
||||
Private admin panel
|
||||
|
|
||||
+--> Forgejo admin
|
||||
+--> Postgres
|
||||
+--> Logs / backups / host access
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
Single deployment mode: Docker Compose.
|
||||
|
||||
- EmbarGit service
|
||||
- Forgejo service
|
||||
- PostgreSQL service
|
||||
- Network definitions for private/public separation
|
||||
|
||||
Admin access security is the operator's responsibility (VPN, firewall rules, etc). EmbarGit does not enforce or scaffold this in Phase 1.
|
||||
|
||||
## Public Viewer Rules
|
||||
|
||||
- Share links are public resources by design.
|
||||
- Public access must be read-only.
|
||||
- Public access must not expose admin routes, database ports, or Forgejo admin surfaces.
|
||||
- Viewer requests must validate:
|
||||
- link token
|
||||
- expiration
|
||||
- revoked state
|
||||
- snapshot binding
|
||||
|
||||
The viewer should be the only public application surface that emits code content.
|
||||
|
||||
## CLI Responsibilities
|
||||
|
||||
The CLI is the primary way to scaffold a deployment.
|
||||
|
||||
### `init`
|
||||
|
||||
`init` should:
|
||||
|
||||
- prompt for domain / hostnames
|
||||
- generate `.env`
|
||||
- generate `docker-compose.yml`
|
||||
- generate Forgejo and Embargo service defaults
|
||||
|
||||
### `start`, `stop`, `status`
|
||||
|
||||
Thin wrappers around Docker Compose.
|
||||
|
||||
### CLI UX
|
||||
|
||||
- Use spinners for long-running steps.
|
||||
- Use prompts for interactive configuration.
|
||||
- Keep output terse and actionable.
|
||||
- Present generated files clearly after initialization.
|
||||
|
||||
## Configuration Outputs
|
||||
|
||||
Expected outputs from `init`:
|
||||
|
||||
- `.env`
|
||||
- `docker-compose.yml`
|
||||
|
||||
## Data and Auth Model
|
||||
|
||||
- Share links are tied to immutable snapshots.
|
||||
- Grants must resolve to a specific `commit_sha`.
|
||||
- Viewer endpoints must never accept arbitrary repo/ref selection.
|
||||
|
||||
## 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`
|
||||
|
||||
Next implementation work:
|
||||
|
||||
1. Make `init` generate configs via interactive prompts
|
||||
2. Add a CLI prompt/spinner library
|
||||
3. Expand shared types for deployment config
|
||||
4. Wire the service to use the generated config
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should the public viewer be mounted at a fixed path like `/share/*` or a dedicated hostname?
|
||||
219
docs/plans/2026-03-31-myst-auth-and-deployment-design.md
Normal file
219
docs/plans/2026-03-31-myst-auth-and-deployment-design.md
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
# Myst Auth and Deployment Design
|
||||
|
||||
This document captures current decisions about deployment topology 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.
|
||||
|
||||
## 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 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: myst.example.com
|
||||
|
|
||||
v
|
||||
Reverse Proxy / Platform Router
|
||||
(Coolify, Caddy, Nginx, etc.)
|
||||
|
|
||||
v
|
||||
Myst App (UI + API)
|
||||
|
|
||||
-------------------
|
||||
| |
|
||||
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 authenticates to Forgejo with an operator-created service account token.
|
||||
- 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.
|
||||
|
||||
## 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
|
||||
2. Same Coolify project or private network as Forgejo
|
||||
3. Separate host on the same trusted network as Forgejo
|
||||
|
||||
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
|
||||
|
||||
## Public Viewer Rules
|
||||
|
||||
- Share links are public resources by design.
|
||||
- Public access must be read-only.
|
||||
- Public access must not expose database ports or Forgejo admin surfaces.
|
||||
- Viewer requests must validate:
|
||||
- link token
|
||||
- expiration
|
||||
- revoked state
|
||||
- snapshot binding
|
||||
|
||||
The viewer should be the only public application surface that emits code content.
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
- 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
|
||||
|
||||
## Data and Auth Model
|
||||
|
||||
- Share links are tied to immutable snapshots.
|
||||
- Grants must resolve to a specific `commit_sha`.
|
||||
- Viewer endpoints must never accept arbitrary repo/ref selection.
|
||||
- Myst stores its metadata in its own Postgres database.
|
||||
- Minimum v1 data model is `repos` and `grants`.
|
||||
- Operators create the Forgejo service account and PAT themselves.
|
||||
- Myst does not maintain a separate in-app admin user database in Phase 1.
|
||||
- Admin access is delegated to operator-managed network or reverse-proxy controls.
|
||||
|
||||
## 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`
|
||||
|
||||
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, and database settings
|
||||
3. Implement `forgejo bootstrap` and `doctor`
|
||||
4. Add Postgres-backed service foundation using the minimum `repos` and `grants` schema
|
||||
5. Wire the service to load generated config and validate required env at startup
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should the public viewer be mounted at a fixed path like `/share/*` or a dedicated hostname?
|
||||
- Should the admin UI and viewer share a single Myst origin in v1, or should the docs recommend separate admin and public origins?
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"name": "embargo",
|
||||
"name": "myst",
|
||||
"private": true,
|
||||
"version": "0.1.0",
|
||||
"packageManager": "pnpm@10.33.0",
|
||||
|
|
|
|||
|
|
@ -1,19 +1,19 @@
|
|||
{
|
||||
"name": "@embargo/cli",
|
||||
"description": "A cli tool that helps you setup a private forgejo instance with link expiry grant access controls on repositories you choose to share.",
|
||||
"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/embargo/issues"
|
||||
"url": "https://github.com/ZTatman/myst/issues"
|
||||
},
|
||||
"homepage": "https://github.com/ZTatman/embargo#readme",
|
||||
"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",
|
||||
|
|
@ -22,7 +22,7 @@
|
|||
},
|
||||
"dependencies": {
|
||||
"@clack/prompts": "^1.2.0",
|
||||
"@embargo/shared": "workspace:*",
|
||||
"@myst/shared": "workspace:*",
|
||||
"yoctocolors": "^2.1.2"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -3,25 +3,139 @@ import fs from "node:fs/promises";
|
|||
import * as p from "@clack/prompts";
|
||||
import * as c from "yoctocolors";
|
||||
import { generateEnvFile } from "../generators/env.js";
|
||||
import { generateDockerCompose } from "../generators/docker-compose.js";
|
||||
import { generateSecret, generatePassword } from "../utils/crypto.js";
|
||||
import { generateSecret } from "../utils/crypto.js";
|
||||
|
||||
interface MystConfig {
|
||||
adminUrl: string;
|
||||
databaseUrl: string;
|
||||
forgejoBaseUrl: string;
|
||||
forgejoServiceAccountUsername: string;
|
||||
publicUrl: string;
|
||||
}
|
||||
|
||||
function normalizeHttpUrl(value: string): string {
|
||||
const trimmed = value.trim();
|
||||
if (/^https?:\/\//i.test(trimmed)) {
|
||||
return trimmed;
|
||||
}
|
||||
|
||||
return `https://${trimmed}`;
|
||||
}
|
||||
|
||||
function validateHttpUrlOrHost(
|
||||
value: string | undefined,
|
||||
label: string,
|
||||
): string | undefined {
|
||||
if (!value?.trim()) {
|
||||
return `${label} is required`;
|
||||
}
|
||||
|
||||
try {
|
||||
const url = new URL(normalizeHttpUrl(value));
|
||||
if (url.protocol !== "http:" && url.protocol !== "https:") {
|
||||
return `${label} must start with http:// or https://`;
|
||||
}
|
||||
|
||||
if (!url.hostname) {
|
||||
return `${label} must include a domain or hostname`;
|
||||
}
|
||||
} catch {
|
||||
return `${label} must be a valid URL or hostname`;
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
function generateConfigFile(config: MystConfig): string {
|
||||
return `${JSON.stringify(config, null, 2)}\n`;
|
||||
}
|
||||
|
||||
export async function initCommand(_args: string[]): Promise<void> {
|
||||
p.intro(c.bold("embargo init"));
|
||||
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(
|
||||
{
|
||||
domain: () =>
|
||||
publicUrl: () =>
|
||||
p.text({
|
||||
message: "What domain will Embargo run on?",
|
||||
placeholder: "embargo.example.com",
|
||||
validate: (v) => (v.trim() ? undefined : "Domain is required"),
|
||||
message: "Domain name or URL for the public viewer",
|
||||
placeholder: "share.example.com",
|
||||
validate: (v) => validateHttpUrlOrHost(v, "Public viewer URL"),
|
||||
}),
|
||||
forgejoAdminUser: () =>
|
||||
adminUrl: () =>
|
||||
p.text({
|
||||
message: "Forgejo admin username?",
|
||||
placeholder: "admin",
|
||||
validate: (v) => (v.trim() ? undefined : "Username is required"),
|
||||
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,
|
||||
}),
|
||||
},
|
||||
{
|
||||
|
|
@ -35,37 +149,62 @@ export async function initCommand(_args: string[]): Promise<void> {
|
|||
const s = p.spinner();
|
||||
s.start("Generating config files");
|
||||
|
||||
const forgejoAdminPassword = generatePassword();
|
||||
const publicUrl = normalizeHttpUrl(answers.publicUrl);
|
||||
const adminUrl = normalizeHttpUrl(answers.adminUrl);
|
||||
const forgejoBaseUrl = normalizeHttpUrl(answers.forgejoBaseUrl);
|
||||
const grantTokenSecret = answers.grantTokenSecret?.trim() || generateSecret();
|
||||
const envContent = generateEnvFile({
|
||||
domain: answers.domain,
|
||||
forgejoAdminUser: answers.forgejoAdminUser,
|
||||
forgejoAdminPassword,
|
||||
forgejoServicePassword: generatePassword(),
|
||||
jwtSecret: generateSecret(),
|
||||
dbPassword: generatePassword(),
|
||||
adminUrl,
|
||||
databaseUrl: answers.databaseUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoPat: answers.forgejoPat,
|
||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
||||
grantTokenSecret,
|
||||
publicUrl,
|
||||
});
|
||||
const configContent = generateConfigFile({
|
||||
adminUrl,
|
||||
databaseUrl: answers.databaseUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
||||
publicUrl,
|
||||
});
|
||||
|
||||
const composeContent = generateDockerCompose({ domain: answers.domain });
|
||||
|
||||
const outDir = process.cwd();
|
||||
await Promise.all([
|
||||
fs.writeFile(path.join(outDir, ".env"), envContent, "utf8"),
|
||||
fs.writeFile(path.join(outDir, "docker-compose.yml"), composeContent, "utf8"),
|
||||
fs.writeFile(
|
||||
path.join(outDir, "myst.config.json"),
|
||||
configContent,
|
||||
"utf8",
|
||||
),
|
||||
]);
|
||||
|
||||
s.stop("Config files generated");
|
||||
|
||||
p.note(
|
||||
[".env", "docker-compose.yml"].join("\n"),
|
||||
"Files written to current directory",
|
||||
[c.green(".env"), c.green("myst.config.json")].join("\n"),
|
||||
c.yellow("Files written to current directory"),
|
||||
);
|
||||
|
||||
p.note(
|
||||
`${answers.forgejoAdminUser} / ${forgejoAdminPassword}`,
|
||||
"Forgejo admin credentials — save these",
|
||||
[
|
||||
`${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("Tip:")} entering a bare hostname defaults to ${c.bold("https://")}.`,
|
||||
`${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`,
|
||||
`${c.bold("PAT setup docs:")} ${c.cyan("https://forgejo.org/docs/latest/user/api-usage/")}`,
|
||||
`${c.bold("PAT scope docs:")} ${c.cyan("https://forgejo.org/docs/latest/user/token-scope/")}`,
|
||||
`${c.bold("Next commands:")} ${c.green("myst forgejo bootstrap")} then ${c.green("myst doctor")}`,
|
||||
].join("\n"),
|
||||
c.yellow("Next steps"),
|
||||
);
|
||||
|
||||
p.outro(c.green("Done. Run embargo start to bring up services."));
|
||||
p.outro(
|
||||
c.green("Done. Deploy Myst, then run forgejo bootstrap and doctor."),
|
||||
);
|
||||
}
|
||||
export async function startCommand(...args: any[]): Promise<void> {}
|
||||
export async function stopCommand(...args: any[]): Promise<void> {}
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ services:
|
|||
networks:
|
||||
- private
|
||||
|
||||
embargo:
|
||||
myst:
|
||||
image: node:22-alpine
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
|
|
@ -34,7 +34,7 @@ services:
|
|||
ports:
|
||||
- "4000:4000"
|
||||
environment:
|
||||
EMBARGO_DOMAIN: fuck.llms.org
|
||||
MYST_DOMAIN: myst.example.com
|
||||
networks:
|
||||
- private
|
||||
- public
|
||||
|
|
|
|||
|
|
@ -27,8 +27,8 @@ export function generateDockerCompose({ domain }: { domain: string }): string {
|
|||
networks:
|
||||
- private
|
||||
|
||||
embargo:
|
||||
container_name: embargo
|
||||
myst:
|
||||
container_name: myst
|
||||
image: node:22-alpine
|
||||
restart: always
|
||||
env_file:
|
||||
|
|
@ -38,7 +38,7 @@ export function generateDockerCompose({ domain }: { domain: string }): string {
|
|||
ports:
|
||||
- "4000:4000"
|
||||
environment:
|
||||
EMBARGO_DOMAIN: ${domain}
|
||||
MYST_DOMAIN: ${domain}
|
||||
networks:
|
||||
- private
|
||||
- public
|
||||
|
|
|
|||
|
|
@ -1,23 +1,29 @@
|
|||
interface EnvOptions {
|
||||
dbPassword: string;
|
||||
domain: string;
|
||||
forgejoAdminPassword: string;
|
||||
forgejoAdminUser: string;
|
||||
forgejoServicePassword: string;
|
||||
jwtSecret: string;
|
||||
adminUrl: string;
|
||||
databaseUrl: string;
|
||||
forgejoBaseUrl: string;
|
||||
forgejoPat: string;
|
||||
forgejoServiceAccountUsername: string;
|
||||
grantTokenSecret: string;
|
||||
publicUrl: string;
|
||||
}
|
||||
|
||||
export function generateEnvFile(options: EnvOptions): string {
|
||||
return `EMBARGO_DOMAIN=${options.domain}
|
||||
JWT_SECRET=${options.jwtSecret}
|
||||
return `# Public URL used for share links.
|
||||
MYST_PUBLIC_URL=${options.publicUrl}
|
||||
|
||||
FORGEJO_ADMIN_USERNAME=${options.forgejoAdminUser}
|
||||
FORGEJO_ADMIN_PASSWORD=${options.forgejoAdminPassword}
|
||||
FORGEJO_SERVICE_ACCOUNT=embargo-bot
|
||||
FORGEJO_SERVICE_ACCOUNT_PASSWORD=${options.forgejoServicePassword}
|
||||
# Private operator URL for the admin UI. Protect this upstream.
|
||||
MYST_ADMIN_URL=${options.adminUrl}
|
||||
|
||||
POSTGRES_DB=forgejo
|
||||
POSTGRES_USER=forgejo
|
||||
POSTGRES_PASSWORD=${options.dbPassword}
|
||||
# Myst's own Postgres database.
|
||||
DATABASE_URL=${options.databaseUrl}
|
||||
|
||||
# Existing Forgejo instance and operator-created service account token.
|
||||
FORGEJO_BASE_URL=${options.forgejoBaseUrl}
|
||||
FORGEJO_SERVICE_ACCOUNT_USERNAME=${options.forgejoServiceAccountUsername}
|
||||
FORGEJO_PAT=${options.forgejoPat}
|
||||
|
||||
# Secret used to sign or derive grant tokens.
|
||||
GRANT_TOKEN_SECRET=${options.grantTokenSecret}
|
||||
`;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
export function generateExampleCaddyfile(domain: string): string {
|
||||
return `${domain} {
|
||||
reverse_proxy /_embargo/* localhost:4000
|
||||
reverse_proxy /_myst/* localhost:4000
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
`;
|
||||
|
|
@ -10,7 +10,7 @@ export function generateExampleNginxConf(domain: string): string {
|
|||
return `server {
|
||||
server_name ${domain};
|
||||
|
||||
location /_embargo/ {
|
||||
location /_myst/ {
|
||||
proxy_pass http://127.0.0.1:4000/;
|
||||
}
|
||||
|
||||
|
|
@ -20,4 +20,3 @@ export function generateExampleNginxConf(domain: string): string {
|
|||
}
|
||||
`;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ import {
|
|||
|
||||
const PADDING = 4;
|
||||
const INDENT = " ";
|
||||
const USAGE = "embargo <command> [options/flags] [arguments]";
|
||||
const USAGE = "myst <command> [options/flags] [arguments]";
|
||||
|
||||
type CommandName = "init" | "start" | "status" | "stop";
|
||||
|
||||
|
|
@ -27,10 +27,10 @@ interface CLIConfig {
|
|||
|
||||
const config: CLIConfig = {
|
||||
commands: [
|
||||
{ name: "init", desc: "Bootstrap embargo and generate config/env files" },
|
||||
{ name: "start", desc: "Start embargo grant access control services" },
|
||||
{ name: "stop", desc: "Stop embargo grant access control services" },
|
||||
{ name: "status", desc: "List the health of running embargo services" },
|
||||
{ name: "init", desc: "Bootstrap Myst and generate config/env files" },
|
||||
{ name: "start", desc: "Start Myst grant access control services" },
|
||||
{ name: "stop", desc: "Stop Myst grant access control services" },
|
||||
{ name: "status", desc: "List the health of running Myst services" },
|
||||
],
|
||||
globalFlags: [
|
||||
{ name: ["-h", "--help"], desc: "Display help information" },
|
||||
|
|
|
|||
7
packages/cli/src/myst.config.json
Normal file
7
packages/cli/src/myst.config.json
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"adminUrl": "https://admin.myshit.com",
|
||||
"databaseUrl": "postgresql://myst:password@postgres.myshit.com:5432/myst",
|
||||
"forgejoBaseUrl": "https://git.myshit.com",
|
||||
"forgejoServiceAccountUsername": "myshit-bot",
|
||||
"publicUrl": "https://werwr.werwer.werwre"
|
||||
}
|
||||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
4
pnpm-lock.yaml
generated
4
pnpm-lock.yaml
generated
|
|
@ -20,7 +20,7 @@ importers:
|
|||
'@clack/prompts':
|
||||
specifier: ^1.2.0
|
||||
version: 1.2.0
|
||||
'@embargo/shared':
|
||||
'@myst/shared':
|
||||
specifier: workspace:*
|
||||
version: link:../shared
|
||||
yoctocolors:
|
||||
|
|
@ -29,7 +29,7 @@ importers:
|
|||
|
||||
packages/service:
|
||||
dependencies:
|
||||
'@embargo/shared':
|
||||
'@myst/shared':
|
||||
specifier: workspace:*
|
||||
version: link:../shared
|
||||
|
||||
|
|
|
|||
|
|
@ -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