From b5595b4e856470ccbfb2827ebf82a429b513e99a Mon Sep 17 00:00:00 2001 From: ZTatman Date: Wed, 1 Apr 2026 14:12:56 -0400 Subject: [PATCH] refactor: rename Myst and narrow CLI setup flow --- README.md | 45 +++- docs/plans/2026-03-30-phase-1-design.md | 76 +++++- ...-31-embargit-auth-and-deployment-design.md | 136 ----------- ...6-03-31-myst-auth-and-deployment-design.md | 219 ++++++++++++++++++ package.json | 2 +- packages/cli/package.json | 12 +- packages/cli/src/commands/index.ts | 191 ++++++++++++--- packages/cli/src/docker-compose.yml | 4 +- packages/cli/src/generators/docker-compose.ts | 6 +- packages/cli/src/generators/env.ts | 36 +-- packages/cli/src/generators/examples.ts | 5 +- packages/cli/src/index.ts | 10 +- packages/cli/src/myst.config.json | 7 + packages/service/package.json | 4 +- packages/service/src/index.ts | 4 +- packages/shared/package.json | 2 +- packages/shared/src/constants.ts | 7 +- pnpm-lock.yaml | 4 +- tsconfig.base.json | 2 +- 19 files changed, 546 insertions(+), 226 deletions(-) delete mode 100644 docs/plans/2026-03-31-embargit-auth-and-deployment-design.md create mode 100644 docs/plans/2026-03-31-myst-auth-and-deployment-design.md create mode 100644 packages/cli/src/myst.config.json diff --git a/README.md b/README.md index 62f3d35..56b6a3c 100644 --- a/README.md +++ b/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. diff --git a/docs/plans/2026-03-30-phase-1-design.md b/docs/plans/2026-03-30-phase-1-design.md index acf5eeb..aed247a 100644 --- a/docs/plans/2026-03-30-phase-1-design.md +++ b/docs/plans/2026-03-30-phase-1-design.md @@ -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 diff --git a/docs/plans/2026-03-31-embargit-auth-and-deployment-design.md b/docs/plans/2026-03-31-embargit-auth-and-deployment-design.md deleted file mode 100644 index 98884f6..0000000 --- a/docs/plans/2026-03-31-embargit-auth-and-deployment-design.md +++ /dev/null @@ -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? diff --git a/docs/plans/2026-03-31-myst-auth-and-deployment-design.md b/docs/plans/2026-03-31-myst-auth-and-deployment-design.md new file mode 100644 index 0000000..8a3f824 --- /dev/null +++ b/docs/plans/2026-03-31-myst-auth-and-deployment-design.md @@ -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? diff --git a/package.json b/package.json index dae8402..440aabe 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "embargo", + "name": "myst", "private": true, "version": "0.1.0", "packageManager": "pnpm@10.33.0", diff --git a/packages/cli/package.json b/packages/cli/package.json index f2183b6..5eff730 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -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" } } diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index 97dd14a..0b5959b 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -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 { - 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 { 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 {} export async function stopCommand(...args: any[]): Promise {} diff --git a/packages/cli/src/docker-compose.yml b/packages/cli/src/docker-compose.yml index eb7c193..5b9c556 100644 --- a/packages/cli/src/docker-compose.yml +++ b/packages/cli/src/docker-compose.yml @@ -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 diff --git a/packages/cli/src/generators/docker-compose.ts b/packages/cli/src/generators/docker-compose.ts index f4f7f91..86b6759 100644 --- a/packages/cli/src/generators/docker-compose.ts +++ b/packages/cli/src/generators/docker-compose.ts @@ -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 diff --git a/packages/cli/src/generators/env.ts b/packages/cli/src/generators/env.ts index 7d1c5c3..9b237b4 100644 --- a/packages/cli/src/generators/env.ts +++ b/packages/cli/src/generators/env.ts @@ -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} `; } diff --git a/packages/cli/src/generators/examples.ts b/packages/cli/src/generators/examples.ts index b2d9304..5db02fb 100644 --- a/packages/cli/src/generators/examples.ts +++ b/packages/cli/src/generators/examples.ts @@ -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 { } `; } - diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index f415e9d..86cdb57 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -11,7 +11,7 @@ import { const PADDING = 4; const INDENT = " "; -const USAGE = "embargo [options/flags] [arguments]"; +const USAGE = "myst [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" }, diff --git a/packages/cli/src/myst.config.json b/packages/cli/src/myst.config.json new file mode 100644 index 0000000..c048b1f --- /dev/null +++ b/packages/cli/src/myst.config.json @@ -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" +} diff --git a/packages/service/package.json b/packages/service/package.json index a846861..4479140 100644 --- a/packages/service/package.json +++ b/packages/service/package.json @@ -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:*" } } diff --git a/packages/service/src/index.ts b/packages/service/src/index.ts index 721b79a..71d14e2 100644 --- a/packages/service/src/index.ts +++ b/packages/service/src/index.ts @@ -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`); diff --git a/packages/shared/package.json b/packages/shared/package.json index d06a67b..ecf9864 100644 --- a/packages/shared/package.json +++ b/packages/shared/package.json @@ -1,5 +1,5 @@ { - "name": "@embargo/shared", + "name": "@myst/shared", "version": "0.1.0", "private": true, "type": "module", diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts index f791b0b..93592ca 100644 --- a/packages/shared/src/constants.ts +++ b/packages/shared/src/constants.ts @@ -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; - diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9988c66..9c9ab0e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -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 diff --git a/tsconfig.base.json b/tsconfig.base.json index d99371a..70e6674 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -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,