@fyresmith/hive-server 2.3.1 → 2.4.0

package/README.md

@@ -1,6 +1,54 @@
 # Hive Server
 
-Hive server now ships with a first-class `hive` operations CLI for install, setup, tunnel management, env management, and service lifecycle.
+Hive server ships with a first-class `hive` operations CLI for install, setup, tunnel management, env management, and service lifecycle.
+
+## Collaboration protocol v2 additions
+
+Server now supports additive `collab:*` events while retaining backward compatibility for legacy `file-*` and `presence-*` events.
+
+New capabilities include:
+
+- Protocol negotiation (`collab:hello`).
+- Presence heartbeat/jump/list events.
+- Thread/comment/task persistence and realtime events.
+- Activity stream list + subscription.
+- Notification preferences and notify events.
+- Adapter capability negotiation (`markdown`, `canvas`, `metadata`).
+
+## Metadata adapter policy
+
+Selective metadata sync uses a whitelist model only.
+
+Default safe allowlist (override with `HIVE_METADATA_ALLOWLIST_JSON`):
+
+- `.obsidian/appearance.json`
+- `.obsidian/community-plugins.json`
+- `.obsidian/core-plugins.json`
+- `.obsidian/hotkeys.json`
+
+## Discord notifications
+
+Notification webhook env vars:
+
+- `HIVE_DISCORD_WEBHOOK_URL` (default webhook)
+- `HIVE_DISCORD_WEBHOOKS_JSON` (path-prefix mapping)
+
+Example `HIVE_DISCORD_WEBHOOKS_JSON`:
+
+```json
+{
+  "TeamA": "https://discord.com/api/webhooks/...",
+  "Projects/Infra": "https://discord.com/api/webhooks/..."
+}
+```
+
+## Presence stale cleanup
+
+Presence stale eviction is controlled by:
+
+- `HIVE_PRESENCE_STALE_MS` (default `45000`)
+
+Only protocol v2 heartbeat participants are stale-evicted.
 
 ## Install
 
@@ -20,36 +68,12 @@ To build/verify the current local checkout and install it globally:
 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`
+## Tests and verification
 
-### 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`
-- GitHub Actions publish job should run Node 24+ (already configured in workflow)
-
-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
+```bash
+npm test
+npm run verify
+```
 
 ## Fast Path
 
@@ -91,62 +115,3 @@ 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 up
-hive down
-hive logs
-hive doctor
-hive status
-hive update
-```
-
-`hive up` / `hive down` start or stop installed Hive and cloudflared services together.
-`hive logs` streams service logs (`--component hive|tunnel|both`).
-`hive update` installs the latest npm release for the current package and then restarts the Hive OS service and cloudflared service when they are installed.
-
-## 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/cli/commands/env.js

@@ -0,0 +1,80 @@
+import { section, success, fail } from '../output.js';
+import { EXIT } from '../constants.js';
+import { CliError } from '../errors.js';
+import { inferDomainFromRedirect, loadEnvFile, normalizeEnv, promptForEnv, redactEnv, validateEnvValues } from '../env-file.js';
+import { updateHiveConfig } from '../config.js';
+import { assertEnvFileExists, loadValidatedEnv, resolveContext } from '../core/context.js';
+
+export function registerEnvCommands(program) {
+  const env = program.command('env').description('Manage Hive .env configuration');
+
+  env
+    .command('init')
+    .description('Create or update env file from prompts')
+    .option('--env-file <path>', 'env file path')
+    .option('--yes', 'accept defaults where possible', false)
+    .action(async (options) => {
+      section('Env Init');
+      const { config, envFile } = await resolveContext(options);
+      const existing = await loadEnvFile(envFile);
+      const values = await promptForEnv({ envFile, existing, yes: options.yes });
+      const issues = validateEnvValues(values);
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Env file has validation issues', EXIT.FAIL);
+      }
+
+      const domain = inferDomainFromRedirect(values.DISCORD_REDIRECT_URI) || config.domain;
+      await updateHiveConfig({ envFile, domain });
+      success(`Env file ready at ${envFile}`);
+    });
+
+  env
+    .command('edit')
+    .description('Edit env values interactively')
+    .option('--env-file <path>', 'env file path')
+    .option('--yes', 'accept defaults where possible', false)
+    .action(async (options) => {
+      section('Env Edit');
+      const { envFile } = await resolveContext(options);
+      assertEnvFileExists(envFile);
+
+      const existing = await loadEnvFile(envFile);
+      const values = await promptForEnv({ envFile, existing, yes: options.yes });
+      const issues = validateEnvValues(values);
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Env file has validation issues', EXIT.FAIL);
+      }
+      success(`Env file updated: ${envFile}`);
+    });
+
+  env
+    .command('check')
+    .description('Validate env file')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      section('Env Check');
+      const { envFile } = await resolveContext(options);
+      const { issues } = await loadValidatedEnv(envFile, { requireFile: true });
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Env validation failed', EXIT.FAIL);
+      }
+      success('Env validation passed');
+    });
+
+  env
+    .command('print')
+    .description('Print redacted env values')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { envFile } = await resolveContext(options);
+      const values = normalizeEnv(await loadEnvFile(envFile));
+      const redacted = redactEnv(values);
+      section(`Env (${envFile})`);
+      for (const [key, value] of Object.entries(redacted)) {
+        console.log(`${key}=${value}`);
+      }
+    });
+}

package/cli/commands/root.js

@@ -0,0 +1,91 @@
+import { existsSync } from 'fs';
+import { HIVE_CONFIG_FILE, EXIT } from '../constants.js';
+import { CliError } from '../errors.js';
+import { loadHiveConfig } from '../config.js';
+import { section, info } from '../output.js';
+import { cloudflaredServiceStatus } from '../tunnel.js';
+import { getHiveServiceStatus } from '../service.js';
+import { resolveContext, resolveServiceConfig } from '../core/context.js';
+import { runDoctorChecks } from '../flows/doctor.js';
+import { runSetupWizard } from '../flows/setup.js';
+import { runDownFlow, runLogsFlow, runUpFlow, runUpdateFlow } from '../flows/system.js';
+import { startHiveServer } from '../../index.js';
+
+export function registerRootCommands(program) {
+  program
+    .command('setup')
+    .description('Run guided setup for env, tunnel, and service')
+    .option('--env-file <path>', 'env file path')
+    .option('--domain <domain>', 'public domain')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .option('--cloudflared-config-file <path>', 'cloudflared config file')
+    .option('--yes', 'non-interactive mode', false)
+    .action(runSetupWizard);
+
+  program
+    .command('update')
+    .description('Update Hive from npm and restart installed services')
+    .option('--package <name>', 'npm package override')
+    .action(runUpdateFlow);
+
+  program
+    .command('up')
+    .description('Start installed Hive + cloudflared services')
+    .action(runUpFlow);
+
+  program
+    .command('down')
+    .description('Stop installed Hive + cloudflared services')
+    .action(runDownFlow);
+
+  program
+    .command('logs')
+    .description('Stream logs for Hive and/or cloudflared services')
+    .option('-c, --component <name>', 'hive|tunnel|both', 'hive')
+    .option('-n, --lines <n>', 'lines to show', '80')
+    .option('--no-follow', 'do not follow logs')
+    .action(runLogsFlow);
+
+  program
+    .command('doctor')
+    .description('Run prerequisite and configuration checks')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { envFile } = await resolveContext(options);
+      await runDoctorChecks({ envFile, includeCloudflared: true });
+    });
+
+  program
+    .command('run')
+    .description('Start Hive server immediately')
+    .option('--env-file <path>', 'env file path')
+    .option('--quiet', 'reduce startup logs', false)
+    .action(async (options) => {
+      const { envFile } = await resolveContext(options);
+      if (!existsSync(envFile)) {
+        throw new CliError(`Env file not found: ${envFile}. Run: hive env init`, EXIT.FAIL);
+      }
+      await startHiveServer({ envFile, quiet: Boolean(options.quiet) });
+      info(`Hive server started using env: ${envFile}`);
+    });
+
+  program
+    .command('status')
+    .description('Quick status summary (service + tunnel + doctor-lite)')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { config, envFile } = await resolveContext(options);
+      section('Hive Status');
+      console.log(`Config: ${HIVE_CONFIG_FILE}`);
+      console.log(`Env: ${envFile} ${existsSync(envFile) ? '' : '(missing)'}`);
+      if (config.domain) console.log(`Domain: ${config.domain}`);
+      if (config.tunnelName) console.log(`Tunnel: ${config.tunnelName}`);
+
+      const svc = resolveServiceConfig(config);
+      const serviceStatus = await getHiveServiceStatus(svc).catch(() => ({ active: false, detail: 'not installed' }));
+      console.log(`Service ${svc.serviceName}: ${serviceStatus.active ? 'active' : 'inactive'}`);
+
+      const tunnelSvc = await cloudflaredServiceStatus().catch(() => false);
+      console.log(`cloudflared service: ${tunnelSvc ? 'active' : 'inactive or unknown'}`);
+    });
+}

package/cli/commands/service.js

@@ -0,0 +1,112 @@
+import { loadHiveConfig, updateHiveConfig } from '../config.js';
+import { parseInteger, resolveServiceConfig, resolveContext } from '../core/context.js';
+import {
+  getHiveServiceStatus,
+  installHiveService,
+  restartHiveService,
+  startHiveService,
+  stopHiveService,
+  streamHiveServiceLogs,
+  uninstallHiveService,
+} from '../service.js';
+import { section, success } from '../output.js';
+
+export function registerServiceCommands(program) {
+  const service = program.command('service').description('Manage Hive OS service');
+
+  service
+    .command('install')
+    .description('Install Hive as launchd/systemd service')
+    .option('--env-file <path>', 'env file path')
+    .option('--yes', 'non-interactive mode', false)
+    .action(async (options) => {
+      const { config, envFile } = await resolveContext(options);
+      const infoOut = await installHiveService({
+        envFile,
+        yes: Boolean(options.yes),
+        serviceName: config.serviceName,
+      });
+      await updateHiveConfig({
+        envFile,
+        servicePlatform: infoOut.servicePlatform,
+        serviceName: infoOut.serviceName,
+      });
+      success(`Service installed: ${infoOut.serviceName}`);
+    });
+
+  service
+    .command('start')
+    .description('Start Hive service')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await startHiveService(svc);
+      success('Hive service started');
+    });
+
+  service
+    .command('stop')
+    .description('Stop Hive service')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await stopHiveService(svc);
+      success('Hive service stopped');
+    });
+
+  service
+    .command('restart')
+    .description('Restart Hive service')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await restartHiveService(svc);
+      success('Hive service restarted');
+    });
+
+  service
+    .command('status')
+    .description('Show Hive service status')
+    .action(async () => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      const status = await getHiveServiceStatus(svc);
+      section('Hive Service Status');
+      console.log(`Service: ${svc.serviceName} (${svc.servicePlatform})`);
+      console.log(`Active: ${status.active ? 'yes' : 'no'}`);
+      if (status.detail) {
+        console.log('');
+        console.log(status.detail);
+      }
+    });
+
+  service
+    .command('logs')
+    .description('Stream service logs')
+    .option('-n, --lines <n>', 'lines to show', '80')
+    .option('--no-follow', 'do not follow logs')
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      const lines = parseInteger(options.lines, 'lines');
+      await streamHiveServiceLogs({
+        ...svc,
+        follow: Boolean(options.follow),
+        lines,
+      });
+    });
+
+  service
+    .command('uninstall')
+    .description('Uninstall Hive service')
+    .option('--yes', 'skip confirmation', false)
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const svc = resolveServiceConfig(config);
+      await uninstallHiveService({
+        ...svc,
+        yes: Boolean(options.yes),
+      });
+      success(`Service removed: ${svc.serviceName}`);
+    });
+}

package/cli/commands/tunnel.js

@@ -0,0 +1,165 @@
+import process from 'process';
+import {
+  DEFAULT_CLOUDFLARED_CERT,
+  DEFAULT_CLOUDFLARED_CONFIG,
+  DEFAULT_TUNNEL_NAME,
+  EXIT,
+} from '../constants.js';
+import { CliError } from '../errors.js';
+import { inferDomainFromRedirect } from '../env-file.js';
+import { loadHiveConfig, updateHiveConfig } from '../config.js';
+import { validateDomain } from '../checks.js';
+import { run } from '../exec.js';
+import {
+  cloudflaredServiceStatus,
+  installCloudflaredService,
+  runTunnelForeground,
+  setupTunnel,
+  tunnelStatus,
+} from '../tunnel.js';
+import { section, success, fail } from '../output.js';
+import {
+  loadValidatedEnv,
+  parseInteger,
+  requiredOrFallback,
+  resolveContext,
+  setRedirectUriForDomain,
+} from '../core/context.js';
+
+export function registerTunnelCommands(program) {
+  const tunnel = program.command('tunnel').description('Manage Cloudflare tunnel');
+
+  tunnel
+    .command('setup')
+    .description('Run full tunnel lifecycle setup')
+    .option('--env-file <path>', 'env file path')
+    .option('--domain <domain>', 'public domain')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .option('--cloudflared-config-file <path>', 'cloudflared config file')
+    .option('--install-service', 'install cloudflared service', false)
+    .option('--yes', 'non-interactive mode', false)
+    .action(async (options) => {
+      section('Tunnel Setup');
+      const { config, envFile } = await resolveContext(options);
+      const { env, issues } = await loadValidatedEnv(envFile, { requireFile: true });
+      if (issues.length > 0) {
+        for (const issue of issues) fail(issue);
+        throw new CliError('Fix env file first (hive env check)', EXIT.FAIL);
+      }
+
+      const domain = requiredOrFallback(
+        options.domain,
+        inferDomainFromRedirect(env.DISCORD_REDIRECT_URI) || config.domain
+      );
+      if (!validateDomain(domain)) {
+        throw new CliError(`Invalid domain: ${domain}`);
+      }
+
+      const tunnelName = requiredOrFallback(options.tunnelName, config.tunnelName || DEFAULT_TUNNEL_NAME);
+      const cloudflaredConfigFile = requiredOrFallback(
+        options.cloudflaredConfigFile,
+        config.cloudflaredConfigFile || DEFAULT_CLOUDFLARED_CONFIG
+      );
+
+      const tunnelResult = await setupTunnel({
+        tunnelName,
+        domain,
+        configFile: cloudflaredConfigFile,
+        certPath: DEFAULT_CLOUDFLARED_CERT,
+        port: parseInteger(env.PORT, 'PORT'),
+        yjsPort: parseInteger(env.YJS_PORT, 'YJS_PORT'),
+        yes: Boolean(options.yes),
+        installService: Boolean(options.installService),
+      });
+
+      const nextEnv = await setRedirectUriForDomain({
+        envFile,
+        env,
+        domain,
+        yes: Boolean(options.yes),
+      });
+
+      await updateHiveConfig({
+        envFile,
+        domain,
+        tunnelName,
+        tunnelId: tunnelResult.tunnelId,
+        tunnelCredentialsFile: tunnelResult.credentialsFile,
+        cloudflaredConfigFile,
+      });
+
+      if (nextEnv.DISCORD_REDIRECT_URI !== env.DISCORD_REDIRECT_URI) {
+        success('Redirect URI synced for tunnel domain');
+      }
+      success('Tunnel setup complete');
+    });
+
+  tunnel
+    .command('status')
+    .description('Show tunnel status and config')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .option('--cloudflared-config-file <path>', 'cloudflared config path')
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const tunnelName = requiredOrFallback(options.tunnelName, config.tunnelName || DEFAULT_TUNNEL_NAME);
+      const cloudflaredConfigFile = requiredOrFallback(
+        options.cloudflaredConfigFile,
+        config.cloudflaredConfigFile || DEFAULT_CLOUDFLARED_CONFIG
+      );
+      const status = await tunnelStatus({ tunnelName, configFile: cloudflaredConfigFile });
+      section('Tunnel Status');
+      console.log(`Name: ${tunnelName}`);
+      console.log(`Tunnel ID: ${status.tunnel?.id || '(not found)'}`);
+      console.log(`Config file: ${status.configFile} ${status.configExists ? '' : '(missing)'}`);
+      if (config.domain) {
+        console.log(`Domain: ${config.domain}`);
+      }
+      const svc = await cloudflaredServiceStatus().catch(() => false);
+      console.log(`cloudflared service: ${svc ? 'active' : 'inactive or unknown'}`);
+    });
+
+  tunnel
+    .command('run')
+    .description('Run tunnel in foreground')
+    .option('--tunnel-name <name>', 'tunnel name')
+    .action(async (options) => {
+      const config = await loadHiveConfig();
+      const tunnelName = requiredOrFallback(options.tunnelName, config.tunnelName || DEFAULT_TUNNEL_NAME);
+      await runTunnelForeground({ tunnelName });
+    });
+
+  tunnel
+    .command('service-install')
+    .description('Install cloudflared as a system service')
+    .action(async () => {
+      section('Tunnel Service Install');
+      await installCloudflaredService();
+      success('cloudflared service installed');
+    });
+
+  tunnel
+    .command('service-status')
+    .description('Show cloudflared service status')
+    .action(async () => {
+      const active = await cloudflaredServiceStatus();
+      section('Tunnel Service Status');
+      console.log(active ? 'active' : 'inactive');
+      if (process.platform === 'darwin') {
+        const listing = await run('launchctl', ['list']).catch(() => ({ stdout: '' }));
+        const row = listing.stdout
+          .split('\n')
+          .find((line) => line.toLowerCase().includes('cloudflared'));
+        if (row) {
+          console.log('');
+          console.log(row.trim());
+        }
+      } else if (process.platform === 'linux') {
+        const status = await run('sudo', ['systemctl', 'status', 'cloudflared', '--no-pager', '--lines', '20'])
+          .catch(() => ({ stdout: '' }));
+        if (status.stdout) {
+          console.log('');
+          console.log(status.stdout);
+        }
+      }
+    });
+}

package/cli/core/app.js

@@ -0,0 +1,57 @@
+import process from 'process';
+import { Command, CommanderError } from 'commander';
+import { EXIT } from '../constants.js';
+import { CliError } from '../errors.js';
+import { registerEnvCommands } from '../commands/env.js';
+import { registerRootCommands } from '../commands/root.js';
+import { registerServiceCommands } from '../commands/service.js';
+import { registerTunnelCommands } from '../commands/tunnel.js';
+
+export class HiveCliApp {
+  constructor() {
+    this.program = this.createProgram();
+  }
+
+  createProgram() {
+    const program = new Command();
+
+    program
+      .name('hive')
+      .description('Hive server operations CLI')
+      .showHelpAfterError()
+      .version('1.0.0');
+
+    registerRootCommands(program);
+    registerEnvCommands(program);
+    registerTunnelCommands(program);
+    registerServiceCommands(program);
+
+    return program;
+  }
+
+  async run(argv = process.argv) {
+    if ((argv?.length ?? 0) <= 2) {
+      this.program.outputHelp();
+      return EXIT.OK;
+    }
+
+    this.program.exitOverride();
+
+    try {
+      await this.program.parseAsync(argv);
+      return EXIT.OK;
+    } catch (err) {
+      if (err instanceof CommanderError) {
+        if (
+          err.code === 'commander.helpDisplayed'
+          || err.code === 'commander.help'
+          || err.message === '(outputHelp)'
+        ) {
+          return EXIT.OK;
+        }
+        throw new CliError(err.message, err.exitCode ?? EXIT.FAIL);
+      }
+      throw err;
+    }
+  }
+}