refactor: write embargo init command myself for clarity

This commit is contained in:
ZTatman 2026-03-31 23:07:26 -04:00
parent 856f422aed
commit f38d3843ac
16 changed files with 443 additions and 223 deletions

View file

@ -0,0 +1,136 @@
# 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?

View file

@ -2,7 +2,7 @@
"name": "embargo",
"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"

View file

@ -1,6 +1,15 @@
{
"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.",
"version": "0.1.0",
"author": {
"name": "Zach Tatman",
"email": "zach.c.tatman@gmail.com"
},
"bugs": {
"url": "https://github.com/ZTatman/embargo/issues"
},
"homepage": "https://github.com/ZTatman/embargo#readme",
"private": true,
"type": "module",
"bin": {
@ -12,6 +21,8 @@
"clean": "rm -rf dist"
},
"dependencies": {
"@embargo/shared": "workspace:*"
"@clack/prompts": "^1.2.0",
"@embargo/shared": "workspace:*",
"yoctocolors": "^2.1.2"
}
}

View file

@ -0,0 +1,72 @@
import path from "node:path";
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";
export async function initCommand(_args: string[]): Promise<void> {
p.intro(c.bold("embargo init"));
const answers = await p.group(
{
domain: () =>
p.text({
message: "What domain will Embargo run on?",
placeholder: "embargo.example.com",
validate: (v) => (v.trim() ? undefined : "Domain is required"),
}),
forgejoAdminUser: () =>
p.text({
message: "Forgejo admin username?",
placeholder: "admin",
validate: (v) => (v.trim() ? undefined : "Username is required"),
}),
},
{
onCancel: () => {
process.stderr.write("\nOperation cancelled.");
process.exit(0);
},
},
);
const s = p.spinner();
s.start("Generating config files");
const forgejoAdminPassword = generatePassword();
const envContent = generateEnvFile({
domain: answers.domain,
forgejoAdminUser: answers.forgejoAdminUser,
forgejoAdminPassword,
forgejoServicePassword: generatePassword(),
jwtSecret: generateSecret(),
dbPassword: generatePassword(),
});
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"),
]);
s.stop("Config files generated");
p.note(
[".env", "docker-compose.yml"].join("\n"),
"Files written to current directory",
);
p.note(
`${answers.forgejoAdminUser} / ${forgejoAdminPassword}`,
"Forgejo admin credentials — save these",
);
p.outro(c.green("Done. Run embargo start to bring up services."));
}
export async function startCommand(...args: any[]): Promise<void> {}
export async function stopCommand(...args: any[]): Promise<void> {}
export async function statusCommand(...args: any[]): Promise<void> {}

View file

@ -1,91 +0,0 @@
import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
import {
generateAppIni,
generateDockerCompose,
generateEnvFile,
generateExampleCaddyfile,
generateExampleNginxConf
} from "../generators/index.js";
import { generateSecret } from "../utils/crypto.js";
import { assertDockerPrerequisites } from "../utils/docker.js";
import { getFlagValue } from "../utils/flags.js";
interface InitOptions {
domain: string;
forgejoAdminPassword: string;
forgejoAdminUser: string;
outputDir: string;
visibilityMode: "allowlist" | "team";
}
function parseInitOptions(argv: string[]): InitOptions {
return {
domain: getFlagValue(argv, "--domain") ?? "localhost",
forgejoAdminPassword: getFlagValue(argv, "--forgejo-admin-password") ?? "change-me",
forgejoAdminUser: getFlagValue(argv, "--forgejo-admin-user") ?? "admin",
outputDir: getFlagValue(argv, "--dir") ?? "embargo",
visibilityMode: (getFlagValue(argv, "--visibility-mode") as InitOptions["visibilityMode"] | undefined) ?? "team"
};
}
export async function initCommand(argv: string[]): Promise<void> {
const options = parseInitOptions(argv);
if (options.visibilityMode !== "team" && options.visibilityMode !== "allowlist") {
throw new Error(`Unsupported visibility mode: ${options.visibilityMode}`);
}
assertDockerPrerequisites();
const outputRoot = path.resolve(process.cwd(), options.outputDir);
const forgejoDir = path.join(outputRoot, "forgejo");
const examplesDir = path.join(outputRoot, "examples");
await mkdir(forgejoDir, { recursive: true });
await mkdir(examplesDir, { recursive: true });
const generatedSecrets = {
dbPassword: generateSecret(),
embargoAdminPassword: generateSecret(),
forgejoServicePassword: generateSecret(),
jwtSecret: generateSecret()
};
await Promise.all([
writeFile(
path.join(outputRoot, "docker-compose.yml"),
generateDockerCompose({ domain: options.domain }),
"utf8"
),
writeFile(
path.join(outputRoot, ".env"),
generateEnvFile({
domain: options.domain,
forgejoAdminPassword: options.forgejoAdminPassword,
forgejoAdminUser: options.forgejoAdminUser,
visibilityMode: options.visibilityMode,
...generatedSecrets
}),
"utf8"
),
writeFile(path.join(forgejoDir, "app.ini"), generateAppIni(), "utf8"),
writeFile(path.join(examplesDir, "Caddyfile"), generateExampleCaddyfile(options.domain), "utf8"),
writeFile(path.join(examplesDir, "nginx.conf"), generateExampleNginxConf(options.domain), "utf8")
]);
process.stdout.write(
[
`Generated Embargo scaffold in ${outputRoot}`,
`Visibility mode: ${options.visibilityMode}`,
"Generated files:",
"- docker-compose.yml",
"- .env",
"- forgejo/app.ini",
"- examples/Caddyfile",
"- examples/nginx.conf"
].join("\n") + "\n"
);
}

View file

@ -1,12 +0,0 @@
import path from "node:path";
import { assertDockerPrerequisites, getComposeCommand } from "../utils/docker.js";
import { getFlagValue } from "../utils/flags.js";
export async function startCommand(argv: string[]): Promise<void> {
assertDockerPrerequisites();
const outputDir = path.resolve(process.cwd(), getFlagValue(argv, "--dir") ?? "embargo");
process.stdout.write(`${getComposeCommand(outputDir)} up -d\n`);
}

View file

@ -1,34 +0,0 @@
import { access } from "node:fs/promises";
import path from "node:path";
import { assertDockerPrerequisites } from "../utils/docker.js";
import { getFlagValue } from "../utils/flags.js";
const REQUIRED_FILES = [
"docker-compose.yml",
".env",
"forgejo/app.ini",
"examples/Caddyfile",
"examples/nginx.conf"
] as const;
export async function statusCommand(argv: string[]): Promise<void> {
assertDockerPrerequisites();
const outputDir = path.resolve(process.cwd(), getFlagValue(argv, "--dir") ?? "embargo");
const results = await Promise.all(
REQUIRED_FILES.map(async (file) => {
const filePath = path.join(outputDir, file);
try {
await access(filePath);
return `OK ${file}`;
} catch {
return `MISS ${file}`;
}
})
);
process.stdout.write([`Scaffold directory: ${outputDir}`, ...results].join("\n") + "\n");
}

View file

@ -1,12 +0,0 @@
import path from "node:path";
import { assertDockerPrerequisites, getComposeCommand } from "../utils/docker.js";
import { getFlagValue } from "../utils/flags.js";
export async function stopCommand(argv: string[]): Promise<void> {
assertDockerPrerequisites();
const outputDir = path.resolve(process.cwd(), getFlagValue(argv, "--dir") ?? "embargo");
process.stdout.write(`${getComposeCommand(outputDir)} down\n`);
}

View file

@ -0,0 +1,49 @@
services:
postgres:
image: postgres:16
restart: unless-stopped
env_file:
- .env
volumes:
- postgres-data:/var/lib/postgresql/data
networks:
- private
forgejo:
image: codeberg.org/forgejo/forgejo:11.0.11
restart: unless-stopped
env_file:
- .env
depends_on:
- postgres
ports:
- "3000:3000"
- "2222:22"
volumes:
- forgejo-data:/data
networks:
- private
embargo:
image: node:22-alpine
restart: unless-stopped
env_file:
- .env
depends_on:
- forgejo
ports:
- "4000:4000"
environment:
EMBARGO_DOMAIN: fuck.llms.org
networks:
- private
- public
networks:
private:
internal: true
public:
volumes:
postgres-data:
forgejo-data:

View file

@ -1,16 +1,20 @@
export function generateDockerCompose({ domain }: { domain: string }): string {
return `services:
postgres:
container_name: postgres
image: postgres:16
restart: unless-stopped
restart: always
env_file:
- .env
volumes:
- postgres-data:/var/lib/postgresql/data
- postgres:/var/lib/postgresql/data
networks:
- private
forgejo:
image: codeberg.org/forgejo/forgejo:11.0.11
restart: unless-stopped
container_name: forgejo
image: codeberg.org/forgejo/forgejo:14
restart: always
env_file:
- .env
depends_on:
@ -19,11 +23,14 @@ export function generateDockerCompose({ domain }: { domain: string }): string {
- "3000:3000"
- "2222:22"
volumes:
- ./forgejo/app.ini:/data/gitea/conf/app.ini
- forgejo:/data
networks:
- private
embargo-service:
embargo:
container_name: embargo
image: node:22-alpine
restart: unless-stopped
restart: always
env_file:
- .env
depends_on:
@ -32,12 +39,17 @@ export function generateDockerCompose({ domain }: { domain: string }): string {
- "4000:4000"
environment:
EMBARGO_DOMAIN: ${domain}
volumes:
- embargo-data:/data
networks:
- private
- public
networks:
private:
internal: true
public:
volumes:
postgres-data:
embargo-data:
postgres:
forgejo:
`;
}

View file

@ -1,28 +1,23 @@
interface EnvOptions {
dbPassword: string;
domain: string;
embargoAdminPassword: string;
forgejoAdminPassword: string;
forgejoAdminUser: string;
forgejoServicePassword: string;
jwtSecret: string;
visibilityMode: "allowlist" | "team";
}
export function generateEnvFile(options: EnvOptions): string {
return `EMBARGO_DOMAIN=${options.domain}
EMBARGO_ADMIN_PASSWORD=${options.embargoAdminPassword}
JWT_SECRET=${options.jwtSecret}
FORGEJO_ADMIN_USERNAME=${options.forgejoAdminUser}
FORGEJO_ADMIN_PASSWORD=${options.forgejoAdminPassword}
FORGEJO_SERVICE_ACCOUNT=embargo-bot
FORGEJO_SERVICE_ACCOUNT_PASSWORD=${options.forgejoServicePassword}
FORGEJO_VISIBILITY_MODE=${options.visibilityMode}
POSTGRES_DB=forgejo
POSTGRES_USER=forgejo
POSTGRES_PASSWORD=${options.dbPassword}
`;
}

View file

@ -1,47 +1,112 @@
#!/usr/bin/env node
import * as c from "yoctocolors";
import pkg from "../package.json" with { type: "json" };
import { initCommand } from "./commands/init.js";
import { startCommand } from "./commands/start.js";
import { statusCommand } from "./commands/status.js";
import { stopCommand } from "./commands/stop.js";
import {
initCommand,
startCommand,
statusCommand,
stopCommand,
} from "./commands/index.js";
const PADDING = 4;
const INDENT = " ";
const USAGE = "embargo <command> [options/flags] [arguments]";
type CommandName = "init" | "start" | "status" | "stop";
const HELP_TEXT = `Embargo CLI
interface Option {
name: CommandName | string | string[];
desc: string;
}
Usage:
embargo <command> [options]
interface CLIConfig {
commands: Option[];
globalFlags: Option[];
}
Commands:
init Generate the local Embargo stack scaffold
start Print the docker compose command used to start the stack
stop Print the docker compose command used to stop the stack
status Validate docker tooling and generated files
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" },
],
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, ...args] = process.argv.slice(2);
const [command, ...options] = process.argv.slice(2);
const flags = options.filter((o) => o.startsWith("-"));
if (!command || command === "--help" || command === "-h") {
process.stdout.write(`${HELP_TEXT}\n`);
if (!command || flags.includes("-h") || flags.includes("--help")) {
process.stdout.write(`${HELP_TEXT}`);
process.exitCode = 0;
return;
}
const knownCommands: Record<CommandName, (argv: string[]) => Promise<void>> = {
init: initCommand,
start: startCommand,
status: statusCommand,
stop: stopCommand
};
const knownCommands: Record<CommandName, (args: string[]) => Promise<void>> =
{
init: initCommand,
start: startCommand,
status: statusCommand,
stop: stopCommand,
};
if (!(command in knownCommands)) {
process.stderr.write(`Unknown command: ${command}\n\n${HELP_TEXT}\n`);
const isKnownCommand = (cmd: string): cmd is CommandName =>
cmd in knownCommands;
if (!isKnownCommand(command)) {
process.stderr.write(`Unknown command: ${command}\n`);
process.exitCode = 1;
return;
}
await knownCommands[command as CommandName](args);
await knownCommands[command](options);
}
void main();
await main();

View file

@ -1,6 +1,9 @@
import { randomBytes } from "node:crypto";
export function generateSecret(bytes = 24): string {
export function generateSecret(bytes = 32): string {
return randomBytes(bytes).toString("hex");
}
export function generatePassword(bytes = 16): string {
return randomBytes(bytes).toString("base64url");
}

View file

@ -1,19 +0,0 @@
import { spawnSync } from "node:child_process";
function assertCommand(command: string, args: string[] = []): void {
const result = spawnSync(command, args, { stdio: "ignore" });
if (result.status !== 0) {
throw new Error(`Required command not available: ${[command, ...args].join(" ")}`);
}
}
export function assertDockerPrerequisites(): void {
assertCommand("docker", ["--version"]);
assertCommand("docker", ["compose", "version"]);
}
export function getComposeCommand(outputDir: string): string {
return `docker compose --project-directory ${outputDir}`;
}

View file

@ -1,9 +0,0 @@
export function getFlagValue(argv: string[], flag: string): string | undefined {
const index = argv.indexOf(flag);
if (index === -1) {
return undefined;
}
return argv[index + 1];
}

54
pnpm-lock.yaml generated
View file

@ -17,9 +17,15 @@ importers:
packages/cli:
dependencies:
'@clack/prompts':
specifier: ^1.2.0
version: 1.2.0
'@embargo/shared':
specifier: workspace:*
version: link:../shared
yoctocolors:
specifier: ^2.1.2
version: 2.1.2
packages/service:
dependencies:
@ -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: {}