@argus-vrt/web 0.1.1 → 0.2.1

package/README.md

@@ -22,6 +22,20 @@ The `init` wizard generates a `docker-compose.yml`, `.env`, and optionally `ngin
 
 - [Docker](https://docs.docker.com/get-docker/) installed and running
 - Node.js >= 20 (for running the CLI via npx)
+- A [GitHub OAuth App](https://github.com/settings/developers) for authentication
+
+## Authentication
+
+Argus requires GitHub OAuth for login. All browser routes are protected — unauthenticated users are redirected to GitHub to sign in.
+
+The `/api/upload` endpoint used by CI/CD is authenticated separately via API key (`Authorization: Bearer <key>` header), so pipelines don't need GitHub credentials.
+
+### Setting Up GitHub OAuth
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers) → **New OAuth App**
+2. Set the **Authorization callback URL** to `https://your-domain.com/auth/github/callback` (or `http://localhost:3000/auth/github/callback` for local development)
+3. Save the **Client ID** and generate a **Client Secret**
+4. Provide these values when running `npx @argus-vrt/web init`
 
 ## Commands
 
@@ -35,6 +49,11 @@ Interactive setup wizard. Prompts for:
 - **HTTPS** — Let's Encrypt, custom certificate, or none
 - **Reverse proxy** — include an Nginx container or manage yourself
 - **Screenshots path** — where uploaded screenshots are stored
+- **GitHub Client ID** — from your GitHub OAuth App
+- **GitHub Client Secret** — from your GitHub OAuth App
+- **API key** — for CI/CD uploads (auto-generated by default)
+
+A **session secret** is auto-generated and does not require input.
 
 Generates configuration files into `./argus/` (or `--dir <path>`).
 
@@ -63,13 +82,17 @@ Show container status and run a health check on the web dashboard.
 
 Pull the latest Docker images and restart containers.
 
+### `npx @argus-vrt/web setup-ssl <domain>`
+
+Obtain a Let's Encrypt SSL certificate for your domain. Requires the Nginx and Certbot containers (select Let's Encrypt during `init`).
+
 ```bash
-npx @argus-vrt/web upgrade
+npx @argus-vrt/web setup-ssl argus.yourcompany.com
 ```
 
 ## Options
 
-All management commands (`start`, `stop`, `logs`, `status`, `upgrade`) accept:
+All management commands (`start`, `stop`, `logs`, `status`, `upgrade`, `setup-ssl`) accept:
 
 | Flag | Description |
 |------|-------------|
@@ -77,11 +100,12 @@ All management commands (`start`, `stop`, `logs`, `status`, `upgrade`) accept:
 
 ## Connecting the CLI
 
-Once the dashboard is running, point the testing CLI at it by adding `apiUrl` to your project's `.argus.json`:
+Once the dashboard is running, point the testing CLI at it by adding `apiUrl` and `apiKey` to your project's `.argus.json`:
 
 ```json
 {
-  "apiUrl": "http://localhost:3000"
+  "apiUrl": "http://localhost:3000",
+  "apiKey": "your-api-key-from-init"
 }
 ```
 
@@ -91,9 +115,18 @@ Then upload results after running tests:
 npx argus test
 ```
 
+Or upload manually with a header:
+
+```bash
+curl -X POST https://your-domain.com/api/upload \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"branch":"main","commitHash":"abc123","stories":[...]}'
+```
+
 ## Environment Variables
 
-The generated `.env` file supports:
+The generated `.env` file includes:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -101,6 +134,10 @@ The generated `.env` file supports:
 | `DATABASE_URL` | (auto) | PostgreSQL connection string (external DB only) |
 | `DB_PASSWORD` | `argus` | Database password (container DB only) |
 | `SCREENSHOTS_PATH` | `./argus-data/images` | Path to screenshots directory |
+| `GITHUB_CLIENT_ID` | — | GitHub OAuth App client ID |
+| `GITHUB_CLIENT_SECRET` | — | GitHub OAuth App client secret |
+| `SESSION_SECRET` | (auto-generated) | Encryption key for session cookies |
+| `ARGUS_API_KEY` | (auto-generated) | API key for CI/CD upload authentication |
 
 ## Docker Image
 

package/dist-cli/index.js

@@ -5,11 +5,13 @@ import { Command } from "commander";
 
 // cli/commands/init.ts
 import * as p from "@clack/prompts";
-import chalk from "chalk";
+import chalk3 from "chalk";
+import { randomBytes } from "crypto";
 import { existsSync as existsSync2, mkdirSync, writeFileSync } from "fs";
 import { resolve as resolve2 } from "path";
 
 // cli/utils/config.ts
+import chalk from "chalk";
 import { existsSync } from "fs";
 import { resolve } from "path";
 var DOCKER_IMAGE = "ghcr.io/maxcwolf/argus-web";
@@ -20,10 +22,11 @@ var DEFAULT_SCREENSHOTS_PATH = "./argus-data/images";
 function findArgusDir(dir) {
   const target = dir ? resolve(dir) : resolve(process.cwd(), DEFAULT_DIR);
   if (!existsSync(resolve(target, "docker-compose.yml"))) {
-    throw new Error(
-      `No docker-compose.yml found in ${target}.
-Run 'argus-web init' first to set up Argus.`
+    console.error(
+      `${chalk.red("Error:")} No docker-compose.yml found in ${target}
+Run ${chalk.cyan("argus-web init")} first to set up Argus.`
     );
+    process.exit(1);
   }
   return target;
 }
@@ -51,6 +54,10 @@ function generateDockerCompose(options) {
     lines.push("      - DATABASE_URL=${DATABASE_URL}");
   }
   lines.push("      - NODE_ENV=production");
+  lines.push("      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}");
+  lines.push("      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}");
+  lines.push("      - SESSION_SECRET=${SESSION_SECRET}");
+  lines.push("      - ARGUS_API_KEY=${ARGUS_API_KEY}");
   if (options.includeDb) {
     lines.push("    depends_on:");
     lines.push("      db:");
@@ -147,6 +154,16 @@ function generateEnv(options) {
   lines.push("# Path to screenshots directory (mounted read-only into the container)");
   lines.push(`SCREENSHOTS_PATH=${options.screenshotsPath}`);
   lines.push("");
+  lines.push("# GitHub OAuth (create app at https://github.com/settings/developers)");
+  lines.push(`GITHUB_CLIENT_ID=${options.githubClientId}`);
+  lines.push(`GITHUB_CLIENT_SECRET=${options.githubClientSecret}`);
+  lines.push("");
+  lines.push("# Session encryption key (auto-generated)");
+  lines.push(`SESSION_SECRET=${options.sessionSecret}`);
+  lines.push("");
+  lines.push("# API key for CI/CD uploads (Authorization: Bearer <key>)");
+  lines.push(`ARGUS_API_KEY=${options.apiKey}`);
+  lines.push("");
   return lines.join("\n");
 }
 
@@ -209,6 +226,7 @@ function generateNginxConf(options) {
 }
 
 // cli/utils/docker.ts
+import chalk2 from "chalk";
 import { execa } from "execa";
 async function isDockerInstalled() {
   try {
@@ -227,28 +245,41 @@ async function isDockerRunning() {
   }
 }
 async function dockerCompose(args, cwd, options) {
-  return execa("docker", ["compose", ...args], {
-    cwd,
-    stdio: "inherit",
-    ...options
-  });
+  try {
+    return await execa("docker", ["compose", ...args], {
+      cwd,
+      stdio: "inherit",
+      ...options
+    });
+  } catch (error) {
+    const cmd = `docker compose ${args.join(" ")}`;
+    const exitCode = error && typeof error === "object" && "exitCode" in error ? error.exitCode : 1;
+    console.error(
+      `
+${chalk2.red("Error:")} ${chalk2.dim(cmd)} exited with code ${exitCode}`
+    );
+    process.exit(exitCode);
+  }
 }
 async function ensureDocker() {
   if (!await isDockerInstalled()) {
-    throw new Error(
-      "Docker is not installed. Please install Docker first:\nhttps://docs.docker.com/get-docker/"
+    console.error(
+      `${chalk2.red("Error:")} Docker is not installed.
+Install it from: https://docs.docker.com/get-docker/`
     );
+    process.exit(1);
   }
   if (!await isDockerRunning()) {
-    throw new Error(
-      "Docker is not running. Please start Docker Desktop or the Docker daemon."
+    console.error(
+      `${chalk2.red("Error:")} Docker is not running. Please start Docker Desktop or the Docker daemon.`
     );
+    process.exit(1);
   }
 }
 
 // cli/commands/init.ts
 async function initCommand(options) {
-  p.intro(chalk.bold("Argus Web Dashboard Setup"));
+  p.intro(chalk3.bold("Argus Web Dashboard Setup"));
   const outputDir = resolve2(options.dir || DEFAULT_DIR);
   if (existsSync2(resolve2(outputDir, "docker-compose.yml"))) {
     const overwrite = await p.confirm({
@@ -341,6 +372,23 @@ async function initCommand(options) {
         message: "Screenshots storage path",
         defaultValue: DEFAULT_SCREENSHOTS_PATH,
         placeholder: DEFAULT_SCREENSHOTS_PATH
+      }),
+      githubClientId: () => p.text({
+        message: "GitHub OAuth Client ID",
+        validate: (value) => {
+          if (!value) return "Client ID is required for authentication";
+        }
+      }),
+      githubClientSecret: () => p.password({
+        message: "GitHub OAuth Client Secret",
+        validate: (value) => {
+          if (!value) return "Client Secret is required for authentication";
+        }
+      }),
+      apiKey: () => p.text({
+        message: "API key for CI/CD uploads",
+        defaultValue: randomBytes(32).toString("hex"),
+        placeholder: "auto-generated"
       })
     },
     {
@@ -350,6 +398,18 @@ async function initCommand(options) {
       }
     }
   );
+  const sessionSecret = randomBytes(32).toString("hex");
+  const callbackUrl = answers.domain ? `https://${answers.domain}/auth/github/callback` : `http://localhost:${parseInt(answers.port, 10) || DEFAULT_PORT}/auth/github/callback`;
+  p.note(
+    [
+      `Create a GitHub OAuth App at:`,
+      `  ${chalk3.cyan("https://github.com/settings/developers")}`,
+      ``,
+      `Set the callback URL to:`,
+      `  ${chalk3.cyan(callbackUrl)}`
+    ].join("\n"),
+    "GitHub OAuth Setup"
+  );
   const s = p.spinner();
   s.start("Generating configuration files");
   mkdirSync(outputDir, { recursive: true });
@@ -373,7 +433,11 @@ async function initCommand(options) {
     includeDb: answers.includeDb,
     dbConnectionString: answers.dbConnectionString,
     dbPassword: answers.dbPassword || DEFAULT_DB_PASSWORD,
-    screenshotsPath: answers.screenshotsPath || DEFAULT_SCREENSHOTS_PATH
+    screenshotsPath: answers.screenshotsPath || DEFAULT_SCREENSHOTS_PATH,
+    githubClientId: answers.githubClientId,
+    githubClientSecret: answers.githubClientSecret,
+    sessionSecret,
+    apiKey: answers.apiKey
   };
   writeFileSync(resolve2(outputDir, ".env"), generateEnv(envOptions));
   if (answers.includeNginx && answers.domain) {
@@ -386,44 +450,40 @@ async function initCommand(options) {
     );
   }
   s.stop("Configuration files generated");
-  p.note(
-    [
-      `${chalk.dim("Directory:")}  ${outputDir}`,
-      `${chalk.dim("Files:")}      docker-compose.yml, .env${answers.includeNginx ? ", nginx.conf" : ""}`,
-      "",
-      `${chalk.dim("Next steps:")}`,
-      `  cd ${options.dir || DEFAULT_DIR}`,
-      "  argus-web start"
-    ].join("\n"),
-    "Setup complete"
-  );
+  const dir = options.dir || DEFAULT_DIR;
+  const nextSteps = [
+    `${chalk3.dim("Directory:")}  ${outputDir}`,
+    `${chalk3.dim("Files:")}      docker-compose.yml, .env${answers.includeNginx ? ", nginx.conf" : ""}`,
+    "",
+    `${chalk3.dim("Next steps:")}`,
+    `  cd ${dir}`
+  ];
+  nextSteps.push("  argus-web start");
   if (answers.https === "letsencrypt" && answers.domain) {
-    p.log.info(
-      `Run this to obtain your initial SSL certificate:
-  docker compose run --rm certbot certonly --webroot -w /var/www/certbot -d ${answers.domain}`
-    );
+    nextSteps.push(`  argus-web setup-ssl ${answers.domain}`);
   }
-  p.outro(chalk.green("Happy testing!"));
+  p.note(nextSteps.join("\n"), "Setup complete");
+  p.outro(chalk3.green("Happy testing!"));
 }
 
 // cli/commands/start.ts
-import chalk2 from "chalk";
+import chalk4 from "chalk";
 async function startCommand(options) {
   const cwd = findArgusDir(options.dir);
   await ensureDocker();
-  console.log(chalk2.blue("Starting Argus..."));
+  console.log(chalk4.blue("Starting Argus..."));
   await dockerCompose(["up", "-d"], cwd);
-  console.log(chalk2.green("Argus is running."));
+  console.log(chalk4.green("Argus is running."));
 }
 
 // cli/commands/stop.ts
-import chalk3 from "chalk";
+import chalk5 from "chalk";
 async function stopCommand(options) {
   const cwd = findArgusDir(options.dir);
   await ensureDocker();
-  console.log(chalk3.blue("Stopping Argus..."));
+  console.log(chalk5.blue("Stopping Argus..."));
   await dockerCompose(["down"], cwd);
-  console.log(chalk3.green("Argus stopped."));
+  console.log(chalk5.green("Argus stopped."));
 }
 
 // cli/commands/logs.ts
@@ -438,11 +498,11 @@ async function logsCommand(options) {
 }
 
 // cli/commands/status.ts
-import chalk4 from "chalk";
+import chalk6 from "chalk";
 async function statusCommand(options) {
   const cwd = findArgusDir(options.dir);
   await ensureDocker();
-  console.log(chalk4.blue("Argus status:\n"));
+  console.log(chalk6.blue("Argus status:\n"));
   await dockerCompose(["ps"], cwd);
   try {
     const result = await dockerCompose(
@@ -451,23 +511,48 @@ async function statusCommand(options) {
       { stdio: "pipe" }
     );
     if (result.exitCode === 0) {
-      console.log(chalk4.green("\nWeb dashboard is healthy."));
+      console.log(chalk6.green("\nWeb dashboard is healthy."));
     }
   } catch {
-    console.log(chalk4.yellow("\nWeb dashboard health check failed \u2014 container may still be starting."));
+    console.log(chalk6.yellow("\nWeb dashboard health check failed \u2014 container may still be starting."));
   }
 }
 
 // cli/commands/upgrade.ts
-import chalk5 from "chalk";
+import chalk7 from "chalk";
 async function upgradeCommand(options) {
   const cwd = findArgusDir(options.dir);
   await ensureDocker();
-  console.log(chalk5.blue("Pulling latest images..."));
+  console.log(chalk7.blue("Pulling latest images..."));
   await dockerCompose(["pull"], cwd);
-  console.log(chalk5.blue("Restarting with new images..."));
+  console.log(chalk7.blue("Restarting with new images..."));
   await dockerCompose(["up", "-d"], cwd);
-  console.log(chalk5.green("Argus upgraded successfully."));
+  console.log(chalk7.green("Argus upgraded successfully."));
+}
+
+// cli/commands/setup-ssl.ts
+import chalk8 from "chalk";
+async function setupSslCommand(domain, options) {
+  const cwd = findArgusDir(options.dir);
+  await ensureDocker();
+  console.log(chalk8.blue(`Obtaining SSL certificate for ${domain}...`));
+  await dockerCompose(
+    [
+      "run",
+      "--rm",
+      "certbot",
+      "certonly",
+      "--webroot",
+      "-w",
+      "/var/www/certbot",
+      "-d",
+      domain
+    ],
+    cwd
+  );
+  console.log(chalk8.blue("Restarting nginx..."));
+  await dockerCompose(["restart", "nginx"], cwd);
+  console.log(chalk8.green("SSL certificate installed successfully."));
 }
 
 // cli/index.ts
@@ -479,4 +564,5 @@ program.command("stop").description("Stop Argus (docker compose down)").option("
 program.command("logs").description("View logs (docker compose logs -f)").option("-d, --dir <path>", "Argus directory").option("-s, --service <name>", "Service name (web, db, nginx)").action(logsCommand);
 program.command("status").description("Check container status and health").option("-d, --dir <path>", "Argus directory").action(statusCommand);
 program.command("upgrade").description("Pull latest images and restart").option("-d, --dir <path>", "Argus directory").action(upgradeCommand);
+program.command("setup-ssl").description("Obtain a Let's Encrypt SSL certificate").argument("<domain>", "Domain to obtain certificate for").option("-d, --dir <path>", "Argus directory").action(setupSslCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@argus-vrt/web",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -55,6 +55,7 @@
     "clsx": "^2.1.1",
     "drizzle-kit": "^0.31.8",
     "drizzle-orm": "^0.45.1",
+    "iron-session": "^8.0.4",
     "jsdom": "^27.0.0",
     "lucide-react": "^0.561.0",
     "postgres": "^3.4.8",