@hivemagnus/hive-skills 1.0.3 → 1.1.0

package/README.md

@@ -4,6 +4,14 @@
 
 The registry is intentionally small and local-first. SQLite records skills, releases, sessions, audit events, and deployment targets; archives live under the configured data directory. The initial catalog entry is **HiveMem**, based on the existing HiveMem Hermes plugin/skill source supplied at seed time.
 
+## Install with the Hive launcher
+
+Run `npx @hivemagnus/hive@^1.1.0 init --services all` to configure all four services,
+or select `--services skills` for this registry alone. The launcher generates private
+configuration, a strong session secret and TLS, and wires the Router's Skills panel.
+Skills OS/PAM administration remains separate from IAM sign-in. See the
+[launcher guide](../../packages/hive/README.md#include-hive-skills).
+
 ## Install from npm
 
 Requires Linux, Node.js 24.22.1+ or 26.13.0+, TLS certificates, and `pamtester` for
@@ -11,12 +19,14 @@ OS-backed sign-in. SQLite is provided by Node; there are no native npm add-ons.
 Agent deployment also needs Bash, OpenSSH, and permission to enable the target's user timer.
 
 ```bash
-npm install --prefix /opt/hive-skills/runtime @hivemagnus/hive-skills@1.0.3
+npm install --prefix /opt/hive-skills/runtime @hivemagnus/hive-skills@1.1.0
 /opt/hive-skills/runtime/node_modules/.bin/hive-skills --env-file /opt/hive-skills/skills.env
 ```
 
 Or run `npx @hivemagnus/hive-skills --env-file skills.env`. The CLI accepts `start`
-(the default), `seed`, `--help` and `--version`. Environment-file paths may be absolute;
+(the default), `seed`, `check`, `env-schema`, `--help` and `--version`. `check` validates TLS,
+configuration and an existing database without creating or migrating state. `env-schema` prints
+configuration metadata without loading runtime configuration. Environment-file paths may be absolute;
 existing environment variables win. Without `--env-file`, the historical `./.env` lookup
 is retained. Help/version do not initialize storage. A fresh install starts with an empty
 catalog; startup never seeds or replaces existing records.

package/dist/check.js

@@ -0,0 +1,67 @@
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
+import { X509Certificate, createPrivateKey } from 'node:crypto';
+import { isIP } from 'node:net';
+import { dirname, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+/** Read-only preflight: never imports config/app/db, seeds, or creates state. */
+export function checkConfiguration(env) {
+    let failures = 0;
+    const check = (ok, message) => { console.log(`  ${ok ? 'ok  ' : 'FAIL'}  ${message}`); if (!ok)
+        failures++; };
+    const port = Number(env.HIVE_SKILLS_PORT ?? '4030');
+    check(Number.isInteger(port) && port > 0 && port <= 65535, 'HIVE_SKILLS_PORT is valid');
+    check((env.HIVE_SKILLS_SESSION_SECRET?.trim().length ?? 0) >= 32, 'HIVE_SKILLS_SESSION_SECRET has at least 32 characters');
+    let hostname;
+    try {
+        const url = new URL(env.HIVE_SKILLS_PUBLIC_URL ?? `https://localhost:${port}`);
+        hostname = url.hostname.replace(/^\[|\]$/g, '');
+        check(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash, 'HIVE_SKILLS_PUBLIC_URL is an HTTPS URL without credentials');
+    }
+    catch {
+        check(false, 'HIVE_SKILLS_PUBLIC_URL must be a valid HTTPS URL');
+    }
+    try {
+        const cert = new X509Certificate(readFileSync(env.HIVE_SKILLS_TLS_CERT_FILE ?? ''));
+        const key = createPrivateKey(readFileSync(env.HIVE_SKILLS_TLS_KEY_FILE ?? ''));
+        check(cert.checkPrivateKey(key), 'TLS certificate and key match');
+        check(Date.parse(cert.validTo) > Date.now() && Date.parse(cert.validFrom) <= Date.now(), 'TLS certificate is currently valid');
+        if (hostname)
+            check(Boolean(isIP(hostname) ? cert.checkIP(hostname) : cert.checkHost(hostname)), 'TLS certificate covers the public URL hostname');
+    }
+    catch {
+        check(false, 'HIVE_SKILLS_TLS_CERT_FILE and HIVE_SKILLS_TLS_KEY_FILE must be readable valid PEM files');
+    }
+    const data = resolve(env.HIVE_SKILLS_DATA_DIR ?? './data');
+    try {
+        let ancestor = data;
+        while (!existsSync(ancestor) && dirname(ancestor) !== ancestor)
+            ancestor = dirname(ancestor);
+        accessSync(ancestor, constants.W_OK | constants.X_OK);
+        check(statSync(ancestor).isDirectory(), 'Skills data directory exists and is writable, or can be created');
+    }
+    catch {
+        check(false, 'Skills data directory must be writable');
+    }
+    const database = resolve(data, 'registry.sqlite');
+    if (existsSync(database)) {
+        let db;
+        try {
+            db = new DatabaseSync(database, { readOnly: true });
+            check(db.prepare('PRAGMA quick_check').get()?.quick_check === 'ok', 'SQLite integrity');
+            check(db.prepare('PRAGMA foreign_key_check').all().length === 0, 'SQLite foreign keys');
+            db.prepare('SELECT slug FROM skills LIMIT 1').get();
+        }
+        catch {
+            check(false, 'Existing database must be a readable Skills registry');
+        }
+        finally {
+            db?.close();
+        }
+    }
+    else
+        console.log('  info  Registry database will be created on first start; catalog starts empty');
+    if (!env.HIVE_SKILLS_ADMIN_USERS?.trim())
+        console.log('  !     HIVE_SKILLS_ADMIN_USERS is empty; OS administration is disabled');
+    console.log(failures ? `Result: ${failures} problem(s)` : 'Result: ready to start');
+    return failures ? 1 : 0;
+}

package/dist/cli.js

@@ -4,10 +4,12 @@ import { resolve } from 'node:path';
 import { packageRoot } from './paths.js';
 const usage = `Hive Skills: HTTPS skill registry and Hermes distribution bridge.
 
-Usage: hive-skills [start|seed] [--env-file FILE]
+Usage: hive-skills [start|seed|check|env-schema] [--env-file FILE]
        hive-skills --help | --version
 
 start         Start the registry (default); requires TLS key and certificate.
+check         Validate configuration, TLS and existing storage without writing.
+env-schema    Print configuration metadata as JSON without loading configuration.
 seed          Explicitly seed the bundled HiveMem skill; never runs on start.
 --env-file    Load a dotenv file; existing environment values win.
 
@@ -25,6 +27,11 @@ export async function main(args) {
             console.log(manifest.version);
             return 0;
         }
+        if (args.length === 1 && args[0] === 'env-schema') {
+            const { envSchemaDocument } = await import('./env-schema.js');
+            console.log(JSON.stringify(envSchemaDocument()));
+            return 0;
+        }
         let command;
         const files = [];
         for (let index = 0; index < args.length; index++) {
@@ -35,13 +42,23 @@ export async function main(args) {
                     throw new Error('--env-file requires a file path');
                 files.push(file);
             }
-            else if (!command && (arg === 'start' || arg === 'seed'))
+            else if (!command && (arg === 'start' || arg === 'seed' || arg === 'check'))
                 command = arg;
             else
                 throw new Error('Invalid arguments. Run hive-skills --help.');
         }
         for (const file of files)
             process.loadEnvFile(resolve(file));
+        if (command === 'check') {
+            const { checkConfiguration } = await import('./check.js');
+            // Preserve the historical cwd env lookup without importing the writable config module.
+            if (files.length === 0) {
+                const { existsSync } = await import('node:fs');
+                if (existsSync('.env'))
+                    process.loadEnvFile('.env');
+            }
+            return checkConfiguration(process.env);
+        }
         if (command === 'seed')
             await import('./seed.js');
         else

package/dist/env-schema.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { packageRoot } from './paths.js';
+/** Safe to call before configuration is loaded; contains no runtime values. */
+export function envSchemaDocument() {
+    const { version } = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8'));
+    return {
+        service: 'skills', package: '@hivemagnus/hive-skills', version, defaultPort: 4030,
+        healthPath: '/healthz', consolePath: '/', dependencies: [],
+        env: [
+            { name: 'NODE_ENV', default: 'production', description: 'Runtime environment.' },
+            { name: 'HIVE_SKILLS_HOST', default: '127.0.0.1', description: 'Listener bind address.' },
+            { name: 'HIVE_SKILLS_PORT', default: '4030', description: 'HTTPS listener port.' },
+            { name: 'HIVE_SKILLS_PUBLIC_URL', default: 'https://localhost:4030', description: 'Public HTTPS registry URL used in archive links.' },
+            { name: 'HIVE_SKILLS_DATA_DIR', default: './data', description: 'SQLite database and immutable skill archives.' },
+            { name: 'HIVE_SKILLS_SESSION_SECRET', required: true, secret: true, generate: 'hex32', description: 'Session signing secret; at least 32 characters.' },
+            { name: 'HIVE_SKILLS_ADMIN_USERS', description: 'Comma-separated OS accounts allowed to administer the registry; independent of IAM.' },
+            { name: 'HIVE_SKILLS_PAM_SERVICE', default: 'hive-skills', description: 'Installed PAM policy for OS authentication; use login for a standard Linux policy.' },
+            { name: 'HIVE_SKILLS_TLS_KEY_FILE', required: true, description: 'TLS private-key PEM file.' },
+            { name: 'HIVE_SKILLS_TLS_CERT_FILE', required: true, description: 'TLS certificate PEM file.' },
+            { name: 'HIVE_SKILLS_DEPLOY_SCRIPT', description: 'Optional override for the bundled agent deployment helper.' },
+            { name: 'HIVE_SKILLS_TARGETS', description: 'Optional initial deployment targets: name=user@host, comma-separated.' },
+        ].map((entry) => ({ required: false, secret: false, ...entry })),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/hive-skills",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "type": "module",
   "engines": {
     "node": "^24.22.1 || ^26.13.0"