@hivemagnus/hive-skills 1.1.0 → 1.2.0

package/README.md

@@ -19,17 +19,18 @@ 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.1.0
+npm install --prefix /opt/hive-skills/runtime @hivemagnus/hive-skills@1.2.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`, `check`, `env-schema`, `--help` and `--version`. `check` validates TLS,
+(the default), `seed`, `check`, `env-schema`, `migrate`, `upgrade`, `rollback`, `--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.
+catalog; startup never seeds or replaces existing records. Run `hive-skills migrate`
+explicitly before first startup, or enable `HIVE_AUTO_MIGRATE=true` with backup access.
 
 Configure these values in a private environment file (mode 0600):
 
@@ -155,3 +156,13 @@ version in `package.json`. CI also checks the package allowlist and npm 12 insta
 The package publishes from `.github/workflows/publish.yml` alongside the other packages;
 configure its npm trusted publisher for that workflow and the `npm-publish` environment after
 the initial authenticated publication.
+
+## Managed upgrades
+
+Use `hive upgrade --dry-run`, then `hive upgrade` for the enrolled release bundle. This server's
+`upgrade` and `rollback` commands delegate to the same owner-run launcher. `migrate --plan --json`
+is read-only; migration requires a verified backup. Set `HIVE_AUTO_MIGRATE=true` explicitly for
+startup migrations outside a managed install. Slow or one-way automatic migrations are refused.
+`check --json` reports configuration without initializing state. No upgrade rotates signing keys
+or reseeds existing accounts. See [UPGRADING.md](https://github.com/ChefTaco/hive/blob/main/UPGRADING.md)
+for adoption, compatibility, recovery, update notices and container controls.

package/dist/app.js

@@ -1,3 +1,7 @@
+import { maintenanceActive } from './release/runtime.js';
+import { metadata } from './release/runtime.js';
+import { packageRoot as releasePackageRoot } from './paths.js';
+import { home as upgradeHome, updateStatus } from './release/runtime.js';
 import { bodyLimit } from 'hono/body-limit';
 import { existsSync, readFileSync } from 'node:fs';
 import { Hono } from 'hono';
@@ -50,6 +54,8 @@ const archiveUrl = (skillSlug, release, channel) => {
     const base = `${config.publicUrl}/v1/skills/${skillSlug}/releases/${release.version}/archive`;
     return channel === 'stable' ? base : `${base}?channel=${channel}`;
 };
+app.use('*', async (c, next) => { if (maintenanceActive(new URL(c.req.url).pathname))
+    return c.json({ error: 'Hive is undergoing maintenance' }, 503); await next(); });
 app.use('*', bodyLimit({ maxSize: 70 * 1024 * 1024 }));
 for (const target of config.targets)
     store.seedTarget(target);
@@ -60,11 +66,11 @@ app.use('*', async (c, next) => {
     await next();
 });
 app.get('/', (c) => c.html(page));
-app.get('/health/live', (c) => c.json({ status: 'ok', service: 'hive-skills' }));
+app.get('/health/live', (c) => c.json({ ...metadata(releasePackageRoot), status: 'ok', service: 'hive-skills' }));
 app.get('/healthz', (c) => {
     try {
         const health = store.readiness();
-        return c.json({ status: health.ready ? 'ok' : 'degraded', service: 'hive-skills', ...health }, health.ready ? 200 : 503);
+        return c.json({ ...metadata(releasePackageRoot), status: health.ready ? 'ok' : 'degraded', service: 'hive-skills', ...health }, health.ready ? 200 : 503);
     }
     catch {
         return c.json({ status: 'degraded', service: 'hive-skills', reason: 'database_unavailable' }, 503);
@@ -179,6 +185,7 @@ app.post('/auth/logout', (c) => {
 });
 app.get('/auth/me', requireAuth(), (c) => c.json(c.get('auth')));
 app.get('/admin/skills', requireAuth(true), (c) => c.json(store.listAllSkills()));
+app.get('/admin/updates', requireAuth(true), async (c) => c.json(await updateStatus(metadata(releasePackageRoot).release, upgradeHome())));
 app.post('/admin/skills', requireAuth(true), async (c) => {
     const body = await requestJson(c);
     const skill = store.createSkill({

package/dist/cli.js

@@ -4,11 +4,15 @@ 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|check|env-schema] [--env-file FILE]
+Usage: hive-skills [start|seed|check|env-schema|migrate|upgrade|rollback] [--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.
+              --json prints a JSON report.
+migrate       --plan [--json] inspects; otherwise back up and migrate (--backup-dir DIR).
+upgrade       Delegate a complete managed bundle upgrade to the Hive launcher.
+rollback      Delegate managed code rollback or explicitly confirmed data restore.
 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.
@@ -18,6 +22,27 @@ HIVE_SKILLS_ADMIN_USERS, HIVE_SKILLS_TLS_KEY_FILE and HIVE_SKILLS_TLS_CERT_FILE.
 See the package README for the complete configuration and migration guide.`;
 export async function main(args) {
     try {
+        const special = args.find(arg => ['upgrade', 'rollback', 'migrate'].includes(arg));
+        if (special) {
+            const rest = [...args];
+            rest.splice(rest.indexOf(special), 1);
+            for (let i = 0; i < rest.length; i++) {
+                if (rest[i] === '--env-file' || rest[i]?.startsWith('--env-file=')) {
+                    const inline = rest[i].startsWith('--env-file=');
+                    const file = inline ? rest[i].slice(11) : rest[i + 1];
+                    if (!file)
+                        throw new Error('--env-file requires a file');
+                    process.loadEnvFile(resolve(file));
+                    rest.splice(i, inline ? 1 : 2);
+                    i--;
+                }
+            }
+            if (special === 'migrate') {
+                await (await import('./upgrade.js')).skillsMigration(rest);
+                return 0;
+            }
+            return (await import('./release/runtime.js')).delegate([special, ...rest]);
+        }
         if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
             console.log(usage);
             return 0;
@@ -44,6 +69,8 @@ export async function main(args) {
             }
             else if (!command && (arg === 'start' || arg === 'seed' || arg === 'check'))
                 command = arg;
+            else if (arg === '--json' && command === 'check')
+                continue;
             else
                 throw new Error('Invalid arguments. Run hive-skills --help.');
         }
@@ -57,10 +84,16 @@ export async function main(args) {
                 if (existsSync('.env'))
                     process.loadEnvFile('.env');
             }
-            return checkConfiguration(process.env);
+            if (args.includes('--json'))
+                return (await import('./release/runtime.js')).captureCheck(() => checkConfiguration(process.env));
+            const code = checkConfiguration(process.env);
+            await (await import('./release/runtime.js')).printUpdateNotice(JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8')).version);
+            return code;
         }
-        if (command === 'seed')
+        if (command === 'seed') {
+            await (await import('./upgrade.js')).skillsMigration([]);
             await import('./seed.js');
+        }
         else
             await import('./server.js');
         return 0;

package/dist/db.js

@@ -3,59 +3,9 @@ import { existsSync } from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
 import { config } from './config.js';
 import { compatibleVersion } from './compatibility.js';
+if (!existsSync(config.databasePath))
+    throw new Error('Skills database is missing; run hive-skills migrate before opening storage');
 const db = new DatabaseSync(config.databasePath, { enableForeignKeyConstraints: true });
-db.exec(`
-  PRAGMA journal_mode = WAL;
-  CREATE TABLE IF NOT EXISTS skills (
-    slug TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT NOT NULL, homepage TEXT,
-    enabled INTEGER NOT NULL DEFAULT 1 CHECK(enabled IN (0, 1)), created_at TEXT NOT NULL, updated_at TEXT NOT NULL
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS releases (
-    skill_slug TEXT NOT NULL REFERENCES skills(slug) ON DELETE CASCADE, version TEXT NOT NULL,
-    sha256 TEXT NOT NULL, archive_path TEXT NOT NULL, notes TEXT, created_at TEXT NOT NULL,
-    min_hermes_version TEXT, max_hermes_version TEXT,
-    PRIMARY KEY(skill_slug, version)
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS sessions (
-    id TEXT PRIMARY KEY, username TEXT NOT NULL, expires_at TEXT NOT NULL, created_at TEXT NOT NULL
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS deployment_targets (
-    name TEXT PRIMARY KEY, host TEXT NOT NULL, username TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 1 CHECK(enabled IN (0, 1))
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS channel_releases (
-    channel TEXT NOT NULL CHECK(channel IN ('stable','canary')), skill_slug TEXT NOT NULL REFERENCES skills(slug) ON DELETE CASCADE,
-    version TEXT NOT NULL, PRIMARY KEY(channel,skill_slug), FOREIGN KEY(skill_slug,version) REFERENCES releases(skill_slug,version)
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS target_policies (
-    target TEXT PRIMARY KEY REFERENCES deployment_targets(name), channel TEXT NOT NULL CHECK(channel IN ('stable','canary')),
-    token_hash TEXT NOT NULL, skills_json TEXT, receipt_json TEXT, updated_at TEXT NOT NULL
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS registry_migrations (id TEXT PRIMARY KEY) STRICT;
-  CREATE TABLE IF NOT EXISTS deployment_jobs (
-    id TEXT PRIMARY KEY, target TEXT NOT NULL, actor TEXT NOT NULL, status TEXT NOT NULL,
-    result TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
-  ) STRICT;
-  CREATE TABLE IF NOT EXISTS audit_log (
-    id INTEGER PRIMARY KEY, actor TEXT NOT NULL, action TEXT NOT NULL, subject TEXT NOT NULL, details TEXT NOT NULL, created_at TEXT NOT NULL
-  ) STRICT;
-`);
-const releaseColumns = new Set(db.prepare('PRAGMA table_info(releases)').all().map((column) => column.name));
-if (!releaseColumns.has('min_hermes_version'))
-    db.exec('ALTER TABLE releases ADD COLUMN min_hermes_version TEXT');
-if (!releaseColumns.has('max_hermes_version'))
-    db.exec('ALTER TABLE releases ADD COLUMN max_hermes_version TEXT');
-// Preserve the currently published version during the first channel migration.
-if (!db.prepare("SELECT id FROM registry_migrations WHERE id='release-channels'").get()) {
-    db.exec("BEGIN IMMEDIATE");
-    try {
-        db.exec("INSERT OR IGNORE INTO channel_releases SELECT 'stable', skill_slug, version FROM releases r WHERE created_at=(SELECT MAX(created_at) FROM releases WHERE skill_slug=r.skill_slug)");
-        db.exec("INSERT INTO registry_migrations VALUES ('release-channels'); COMMIT");
-    }
-    catch (error) {
-        db.exec('ROLLBACK');
-        throw error;
-    }
-}
 const tokenHash = (token) => createHash('sha256').update(token).digest('hex');
 const now = () => new Date().toISOString();
 const mapSkill = (row) => ({ slug: row.slug, name: row.name, description: row.description, homepage: row.homepage, enabled: row.enabled === 1, createdAt: row.created_at, updatedAt: row.updated_at });

package/dist/deployment-worker.js

@@ -1,12 +1,14 @@
 import { spawn } from 'node:child_process';
 import { config } from './config.js';
 import { store } from './db.js';
+import { maintenanceActive } from './release/runtime.js';
 /** One local deployment at a time. Output may contain credentials: retain only exit codes. */
 export function startDeploymentWorker() {
     let busy = false;
+    let active = Promise.resolve();
     store.recoverDeployments();
     const timer = setInterval(() => {
-        if (busy)
+        if (busy || maintenanceActive('/worker'))
             return;
         const job = store.claimDeployment();
         if (!job)
@@ -26,8 +28,10 @@ export function startDeploymentWorker() {
                     HIVE_SKILLS_TARGET_USER: target.username, HIVE_SKILLS_KEY_ONLY: 'true' },
             });
             let finished = false;
+            let complete = () => { };
+            active = new Promise((done) => { complete = done; });
             const finish = (ok, code) => { if (finished)
-                return; finished = true; store.finishDeployment(job.id, ok, code); busy = false; };
+                return; finished = true; store.finishDeployment(job.id, ok, code); busy = false; complete(); };
             child.once('error', () => finish(false, 'launch_failed'));
             child.once('close', (code) => finish(code === 0, code === 0 ? 'timer_installed' : `exit_${code ?? 'signal'}`));
         }
@@ -37,5 +41,5 @@ export function startDeploymentWorker() {
         }
     }, 1000);
     timer.unref();
-    return () => clearInterval(timer);
+    return async () => { clearInterval(timer); await active; };
 }

package/dist/env-schema.js

@@ -1,3 +1,4 @@
+import { commonEnv } from './release/runtime.js';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { packageRoot } from './paths.js';
@@ -7,7 +8,7 @@ export function envSchemaDocument() {
     return {
         service: 'skills', package: '@hivemagnus/hive-skills', version, defaultPort: 4030,
         healthPath: '/healthz', consolePath: '/', dependencies: [],
-        env: [
+        env: [...commonEnv(),
             { 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.' },

package/dist/migrations/managed-format-1.js

@@ -0,0 +1,54 @@
+export function initializeSchema(db) {
+    db.exec(`
+  PRAGMA journal_mode = WAL;
+  CREATE TABLE IF NOT EXISTS skills (
+    slug TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT NOT NULL, homepage TEXT,
+    enabled INTEGER NOT NULL DEFAULT 1 CHECK(enabled IN (0, 1)), created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS releases (
+    skill_slug TEXT NOT NULL REFERENCES skills(slug) ON DELETE CASCADE, version TEXT NOT NULL,
+    sha256 TEXT NOT NULL, archive_path TEXT NOT NULL, notes TEXT, created_at TEXT NOT NULL,
+    min_hermes_version TEXT, max_hermes_version TEXT,
+    PRIMARY KEY(skill_slug, version)
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY, username TEXT NOT NULL, expires_at TEXT NOT NULL, created_at TEXT NOT NULL
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS deployment_targets (
+    name TEXT PRIMARY KEY, host TEXT NOT NULL, username TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 1 CHECK(enabled IN (0, 1))
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS channel_releases (
+    channel TEXT NOT NULL CHECK(channel IN ('stable','canary')), skill_slug TEXT NOT NULL REFERENCES skills(slug) ON DELETE CASCADE,
+    version TEXT NOT NULL, PRIMARY KEY(channel,skill_slug), FOREIGN KEY(skill_slug,version) REFERENCES releases(skill_slug,version)
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS target_policies (
+    target TEXT PRIMARY KEY REFERENCES deployment_targets(name), channel TEXT NOT NULL CHECK(channel IN ('stable','canary')),
+    token_hash TEXT NOT NULL, skills_json TEXT, receipt_json TEXT, updated_at TEXT NOT NULL
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS registry_migrations (id TEXT PRIMARY KEY) STRICT;
+  CREATE TABLE IF NOT EXISTS deployment_jobs (
+    id TEXT PRIMARY KEY, target TEXT NOT NULL, actor TEXT NOT NULL, status TEXT NOT NULL,
+    result TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+  ) STRICT;
+  CREATE TABLE IF NOT EXISTS audit_log (
+    id INTEGER PRIMARY KEY, actor TEXT NOT NULL, action TEXT NOT NULL, subject TEXT NOT NULL, details TEXT NOT NULL, created_at TEXT NOT NULL
+  ) STRICT;
+`);
+    const releaseColumns = new Set(db.prepare('PRAGMA table_info(releases)').all().map((column) => column.name));
+    if (!releaseColumns.has('min_hermes_version'))
+        db.exec('ALTER TABLE releases ADD COLUMN min_hermes_version TEXT');
+    if (!releaseColumns.has('max_hermes_version'))
+        db.exec('ALTER TABLE releases ADD COLUMN max_hermes_version TEXT');
+    // Preserve the currently published version during the first channel migration.
+    if (!db.prepare("SELECT id FROM registry_migrations WHERE id='release-channels'").get()) {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            db.exec("INSERT OR IGNORE INTO channel_releases SELECT 'stable', skill_slug, version FROM releases r WHERE created_at=(SELECT MAX(created_at) FROM releases WHERE skill_slug=r.skill_slug)");
+            db.exec("INSERT INTO registry_migrations VALUES ('release-channels'); COMMIT");
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}

package/dist/release/ZOD_LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.