@fyresmith/hive-server 1.0.1-3

package/README.md

@@ -0,0 +1,143 @@
+# Hive Server
+
+Hive server now ships with a first-class `hive` operations CLI for install, setup, tunnel management, env management, and service lifecycle.
+
+## Install
+
+```bash
+npm i -g hive-server
+```
+
+The global install exposes:
+
+```bash
+hive --help
+```
+
+To build/verify the current local checkout and install it globally:
+
+```bash
+npm run install-hive
+```
+
+## Release System (GitHub Actions + npm)
+
+This repo now includes a release pipeline for `hive-server`:
+
+- CI: `.github/workflows/hive-server-ci.yml`
+- Release tag workflow: `.github/workflows/hive-server-release-tag.yml`
+- npm publish workflow: `.github/workflows/hive-server-publish.yml`
+
+### One-time repo setup
+
+Configure npm Trusted Publisher for this repo/workflow:
+
+- Package: `hive-server`
+- Provider: GitHub Actions
+- Repository: this repository
+- Workflow file: `.github/workflows/hive-server-publish.yml`
+
+No `NPM_TOKEN` secret is required when Trusted Publishing is configured.
+
+### How releases work
+
+1. Run workflow `hive-server-release-tag` from the default branch.
+2. Choose release type (`patch|minor|major|prerelease|custom`).
+3. Workflow bumps `package.json`, commits, and pushes tag `hive-server-vX.Y.Z`.
+4. Tag push triggers `hive-server-publish`, which:
+    - verifies the package
+    - checks tag version matches `package.json`
+    - publishes to npm with provenance
+    - creates a GitHub Release with generated notes
+
+## Fast Path
+
+Run the guided setup:
+
+```bash
+hive setup
+```
+
+Non-interactive defaults:
+
+```bash
+hive setup --yes
+```
+
+`hive setup` can:
+
+- initialize and validate `.env`
+- configure Cloudflare Tunnel
+- sync `DISCORD_REDIRECT_URI`
+- install Hive as a launchd/systemd service
+- run post-setup checks
+
+## Config and Env
+
+Operator config:
+
+- `~/.hive/config.json`
+
+Default env location:
+
+- `~/.hive/server/.env`
+
+Env commands:
+
+```bash
+hive env init
+hive env edit
+hive env check
+hive env print
+```
+
+## Tunnel Operations
+
+```bash
+hive tunnel setup
+hive tunnel status
+hive tunnel run
+hive tunnel service-install
+hive tunnel service-status
+```
+
+## Server Service Operations
+
+```bash
+hive service install
+hive service start
+hive service stop
+hive service restart
+hive service status
+hive service logs
+hive service uninstall
+```
+
+## Runtime and Diagnostics
+
+Run directly in foreground:
+
+```bash
+hive run
+```
+
+Diagnostics:
+
+```bash
+hive doctor
+hive status
+```
+
+## Migration Notes
+
+On first `hive setup`, if legacy `server/.env` exists and no `~/.hive/config.json` exists, setup will offer to import legacy env values.
+
+## Legacy Scripts (Deprecated)
+
+Legacy operational files are still present for one release cycle:
+
+- `/setup-tunnel.sh`
+- `/infra/cloudflare-tunnel.yml`
+- `/infra/collab-server.service`
+
+Use `hive` commands instead of editing legacy templates manually.

package/bin/hive.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCliOrExit } from '../cli/main.js';
+
+runCliOrExit(process.argv);

package/cli/checks.js

@@ -0,0 +1,28 @@
+import { createServer } from 'net';
+import { access } from 'fs/promises';
+
+export async function isPortAvailable(port) {
+  return await new Promise((resolve) => {
+    const server = createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+export async function pathExists(pathValue) {
+  if (!pathValue) return false;
+  try {
+    await access(pathValue);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function validateDomain(domain) {
+  if (!domain) return false;
+  return /^[a-zA-Z0-9.-]+$/.test(domain) && domain.includes('.');
+}

package/cli/config.js

@@ -0,0 +1,33 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { dirname } from 'path';
+import { DEFAULT_CONFIG, HIVE_CONFIG_FILE } from './constants.js';
+
+export function getConfigPath() {
+  return HIVE_CONFIG_FILE;
+}
+
+export async function ensureConfigDir() {
+  await mkdir(dirname(HIVE_CONFIG_FILE), { recursive: true });
+}
+
+export async function loadHiveConfig() {
+  if (!existsSync(HIVE_CONFIG_FILE)) {
+    return { ...DEFAULT_CONFIG };
+  }
+  const raw = await readFile(HIVE_CONFIG_FILE, 'utf-8');
+  const parsed = JSON.parse(raw);
+  return { ...DEFAULT_CONFIG, ...parsed };
+}
+
+export async function saveHiveConfig(config) {
+  await ensureConfigDir();
+  await writeFile(HIVE_CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+}
+
+export async function updateHiveConfig(patch) {
+  const current = await loadHiveConfig();
+  const next = { ...current, ...patch };
+  await saveHiveConfig(next);
+  return next;
+}

package/cli/constants.js

@@ -0,0 +1,45 @@
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const SERVER_ROOT = join(__dirname, '..');
+export const HIVE_HOME = join(homedir(), '.hive');
+export const HIVE_CONFIG_FILE = join(HIVE_HOME, 'config.json');
+export const DEFAULT_ENV_FILE = join(HIVE_HOME, 'server', '.env');
+export const LEGACY_ENV_FILE = join(SERVER_ROOT, '.env');
+export const DEFAULT_DOMAIN = 'collab.example.com';
+export const DEFAULT_TUNNEL_NAME = 'hive';
+export const DEFAULT_CLOUDFLARED_CONFIG = join(homedir(), '.cloudflared', 'config.yml');
+export const DEFAULT_CLOUDFLARED_CERT = join(homedir(), '.cloudflared', 'cert.pem');
+
+export const REQUIRED_ENV_KEYS = [
+  'DISCORD_CLIENT_ID',
+  'DISCORD_CLIENT_SECRET',
+  'DISCORD_REDIRECT_URI',
+  'DISCORD_GUILD_ID',
+  'JWT_SECRET',
+  'VAULT_PATH',
+  'PORT',
+  'YJS_PORT',
+];
+
+export const DEFAULT_ENV_VALUES = {
+  PORT: '3000',
+  YJS_PORT: '3001',
+};
+
+export const DEFAULT_CONFIG = {
+  version: 1,
+  envFile: DEFAULT_ENV_FILE,
+  domain: DEFAULT_DOMAIN,
+  tunnelName: DEFAULT_TUNNEL_NAME,
+  cloudflaredConfigFile: DEFAULT_CLOUDFLARED_CONFIG,
+};
+
+export const EXIT = {
+  OK: 0,
+  FAIL: 1,
+  PREREQ: 2,
+};

package/cli/env-file.js

@@ -0,0 +1,141 @@
+import dotenv from 'dotenv';
+import prompts from 'prompts';
+import { access, mkdir, readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { dirname } from 'path';
+import { DEFAULT_ENV_VALUES, REQUIRED_ENV_KEYS } from './constants.js';
+import { CliError } from './errors.js';
+
+const SECRET_RE = /(SECRET|TOKEN|JWT|PASSWORD|KEY)/i;
+
+function envSortKey(a, b) {
+  const ai = REQUIRED_ENV_KEYS.indexOf(a);
+  const bi = REQUIRED_ENV_KEYS.indexOf(b);
+  if (ai >= 0 && bi >= 0) return ai - bi;
+  if (ai >= 0) return -1;
+  if (bi >= 0) return 1;
+  return a.localeCompare(b);
+}
+
+export async function loadEnvFile(envFile) {
+  if (!existsSync(envFile)) return {};
+  const raw = await readFile(envFile, 'utf-8');
+  return dotenv.parse(raw);
+}
+
+export function redactEnv(values) {
+  const out = {};
+  for (const [k, v] of Object.entries(values)) {
+    if (SECRET_RE.test(k)) {
+      if (!v) out[k] = '';
+      else if (v.length <= 6) out[k] = '******';
+      else out[k] = `${v.slice(0, 2)}***${v.slice(-2)}`;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export function normalizeEnv(values) {
+  const merged = { ...DEFAULT_ENV_VALUES, ...values };
+  for (const key of REQUIRED_ENV_KEYS) {
+    if (merged[key] === undefined || merged[key] === null) {
+      merged[key] = '';
+    }
+  }
+  return merged;
+}
+
+export function serializeEnv(values) {
+  const keys = Object.keys(values).sort(envSortKey);
+  return `${keys.map((k) => `${k}=${values[k] ?? ''}`).join('\n')}\n`;
+}
+
+export async function writeEnvFile(envFile, values) {
+  await mkdir(dirname(envFile), { recursive: true });
+  await writeFile(envFile, serializeEnv(normalizeEnv(values)), 'utf-8');
+}
+
+export function inferDomainFromRedirect(redirectUri) {
+  if (!redirectUri) return null;
+  try {
+    const u = new URL(redirectUri);
+    return u.host;
+  } catch {
+    return null;
+  }
+}
+
+export function validateEnvValues(values) {
+  const issues = [];
+  for (const key of REQUIRED_ENV_KEYS) {
+    if (!String(values[key] ?? '').trim()) {
+      issues.push(`Missing ${key}`);
+    }
+  }
+
+  const port = parseInt(values.PORT ?? '', 10);
+  const yjsPort = parseInt(values.YJS_PORT ?? '', 10);
+  if (!Number.isInteger(port) || port <= 0) issues.push('PORT must be a positive integer');
+  if (!Number.isInteger(yjsPort) || yjsPort <= 0) issues.push('YJS_PORT must be a positive integer');
+
+  try {
+    const uri = new URL(values.DISCORD_REDIRECT_URI ?? '');
+    if (!/^https?:$/.test(uri.protocol)) {
+      issues.push('DISCORD_REDIRECT_URI must use http or https');
+    }
+  } catch {
+    issues.push('DISCORD_REDIRECT_URI must be a valid URL');
+  }
+
+  return issues;
+}
+
+export async function ensureVaultPathReadable(pathValue) {
+  if (!pathValue) return false;
+  try {
+    await access(pathValue);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function promptForEnv({ envFile, existing, yes = false, preset = {} }) {
+  const current = normalizeEnv({ ...existing, ...preset });
+
+  if (yes) {
+    await writeEnvFile(envFile, current);
+    return current;
+  }
+
+  const questions = [
+    { name: 'DISCORD_CLIENT_ID', message: 'Discord Client ID' },
+    { name: 'DISCORD_CLIENT_SECRET', message: 'Discord Client Secret', secret: true },
+    { name: 'DISCORD_GUILD_ID', message: 'Discord Guild ID' },
+    { name: 'JWT_SECRET', message: 'JWT secret', secret: true },
+    { name: 'VAULT_PATH', message: 'Vault absolute path' },
+    { name: 'PORT', message: 'HTTP port' },
+    { name: 'YJS_PORT', message: 'Yjs WS port' },
+    { name: 'DISCORD_REDIRECT_URI', message: 'Discord redirect URI' },
+  ];
+
+  const answers = {};
+  for (const q of questions) {
+    const response = await prompts({
+      type: q.secret ? 'password' : 'text',
+      name: 'value',
+      message: q.message,
+      initial: current[q.name] ?? '',
+    });
+    if (response.value === undefined) {
+      throw new CliError('Cancelled by user');
+    }
+    answers[q.name] = String(response.value ?? '').trim();
+  }
+
+  const merged = normalizeEnv({ ...current, ...answers });
+  await writeEnvFile(envFile, merged);
+  return merged;
+}

package/cli/errors.js

@@ -0,0 +1,11 @@
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} exitCode
+   */
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}

package/cli/exec.js

@@ -0,0 +1,12 @@
+import { execa } from 'execa';
+
+export async function run(cmd, args = [], options = {}) {
+  return execa(cmd, args, {
+    stdio: options.stdio ?? 'pipe',
+    ...options,
+  });
+}
+
+export async function runInherit(cmd, args = [], options = {}) {
+  return run(cmd, args, { ...options, stdio: 'inherit' });
+}