@knolo/cli 5.1.0 → 5.2.0

package/README.md

@@ -25,6 +25,41 @@ Or use via npx:
 npx knolo build
 ```
 
+## Hub Registry Discovery (V5.2)
+
+The CLI can search the public Knolo Hub and inspect a published pack without
+changing the local pack workflow:
+
+```bash
+knolo search "refund policy"
+knolo info acme/refund-policy
+```
+
+The production registry is `https://hub.knolo.dev`. Use `--registry` for a
+one-off override, or set `KNOLO_HUB_URL` for the current environment:
+
+```bash
+knolo search docs --registry https://hub.knolo.dev
+KNOLO_HUB_URL=http://localhost:3000 knolo search docs
+```
+
+An explicit `--registry` value takes precedence over `KNOLO_HUB_URL`. In
+development mode (`NODE_ENV=development`), the default is
+`http://localhost:3000`; otherwise the default is `https://hub.knolo.dev`.
+
+The current Hub surface is read-only discovery and verified installation. Local
+`knolo add <name> <path>` continues to update a project’s local source
+configuration. A Hub pack is installed only after its manifest, Blob bytes,
+digest, size, and local Knowledge Image structure have all been verified:
+
+```bash
+knolo add acme/refund-policy@1.2.0
+```
+
+Successful installs are cached by SHA-256 and recorded in
+`knolo.lock.json`. A yanked version or an existing conflicting pin requires
+`--force`; digest and artifact validation cannot be bypassed.
+
 ---
 
 ## 🚀 Commands

package/bin/knolo.mjs

@@ -20,6 +20,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
+import { isHubAddInvocation, runHubAdd, runHubInfo, runHubLogin, runHubLogout, runHubPublishStub, runHubSearch, runHubWhoami } from './registry/commands.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -33,7 +34,7 @@ const DEFAULT_CONFIG = {
 };
 const SUPPORTED_EXTENSIONS = new Set(['.md', '.txt', '.json']);
 const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', '.dfx', '.cargo-target']);
-const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'inspect', 'migrate', 'verify', 'explain', 'diff', 'dev', 'v5', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
+const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'inspect', 'migrate', 'verify', 'explain', 'diff', 'dev', 'v5', 'search', 'info', 'login', 'whoami', 'logout', 'publish', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
 const ICP_SUBCOMMANDS = new Set(['init', 'build-pack', 'upload', 'query', 'health', 'info', 'clear']);
 const ICP_TEMPLATE_CANDIDATES = [
   path.resolve(__dirname, '../templates/icp-knowledge-canister'),
@@ -79,7 +80,13 @@ Usage:
 
 Commands:
   init                    Initialize knolo.config.json and starter docs
-  add <name> <path>       Add or update a source entry in config
+  add <name> <path>       Add or update a local source entry, or install a Hub pack
+  search <query>          Search the Knolo Hub registry
+  info <publisher>/<slug> Show a Hub registry pack
+  login                   Store a Hub token locally
+  whoami                  Show the stored Hub token prefix
+  logout                  Remove the stored Hub token
+  publish                 Publish support is waiting for Hub write APIs
   build                   Build a .knolo pack from configured sources
   query <question>        Query a built pack and print top hits
   inspect <pack>          Inspect pack format, sections, and manifest
@@ -101,7 +108,13 @@ Run "knolo <command> --help" for command details.`);
 function printCommandHelp(command) {
   const help = {
     init: 'Usage: knolo init',
-    add: 'Usage: knolo add <name> <path>',
+    add: 'Usage: knolo add <name> <path> | <publisher>/<slug>[@<version>] [--out <path>] [--force] [--json] [--registry <url>]',
+    search: 'Usage: knolo search <query> [--format V4|V5] [--license <id>] [--official] [--agents] [--json] [--registry <url>]',
+    info: 'Usage: knolo info <publisher>/<slug> [--json] [--registry <url>]',
+    login: 'Usage: knolo login [--token kno_…] [--stdin] [--registry <url>]',
+    whoami: 'Usage: knolo whoami',
+    logout: 'Usage: knolo logout',
+    publish: 'Usage: knolo publish <pack.knolo>  (not available until Hub write APIs support CLI tokens)',
     build: 'Usage: knolo build',
     query: 'Usage: knolo query <question> [--pack <path>] [--k <number>] [--receipt <file>] [--json]',
     inspect: 'Usage: knolo inspect <pack.knolo>',
@@ -272,6 +285,14 @@ async function cmdInit() {
 }
 
 async function cmdAdd(args) {
+  if (isHubAddInvocation(args)) {
+    const core = await loadCore();
+    return await runHubAdd(args, { core });
+  }
+  return await cmdAddLocal(args);
+}
+
+async function cmdAddLocal(args) {
   const [name, sourcePath] = args;
   if (!name || !sourcePath) throw createError('Usage: knolo add <name> <path>');
 
@@ -1169,6 +1190,12 @@ async function main() {
       if (commandArgs.includes('--help') || commandArgs.includes('-h')) return printCommandHelp(command);
       if (command === 'init') return await cmdInit();
       if (command === 'add') return await cmdAdd(commandArgs);
+      if (command === 'search') return await runHubSearch(commandArgs);
+      if (command === 'info') return await runHubInfo(commandArgs);
+      if (command === 'login') return await runHubLogin(commandArgs);
+      if (command === 'whoami') return await runHubWhoami(commandArgs);
+      if (command === 'logout') return await runHubLogout(commandArgs);
+      if (command === 'publish') return runHubPublishStub(commandArgs);
 
       const core = await loadCore();
       if (command === 'build') return await cmdBuild(core);

package/bin/registry/artifacts.mjs

@@ -0,0 +1,143 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { chmod, mkdir, readFile, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+
+export const MAX_ARTIFACT_BYTES = 250 * 1024 * 1024;
+
+export async function downloadBlobToTemp(url, {
+  tempDir,
+  expectedSize = 0,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const blobUrl = new URL(url);
+  if (blobUrl.protocol !== 'https:') throw new Error('Blob URL must use HTTPS.');
+  if (typeof fetchImpl !== 'function') throw new Error('This Node runtime does not provide fetch.');
+  if (!Number.isSafeInteger(expectedSize) || expectedSize < 0) throw new Error('Manifest sizeBytes is invalid.');
+  if (expectedSize > MAX_ARTIFACT_BYTES) throw new Error('Artifact exceeds Hub’s 250 MB limit.');
+
+  let response;
+  try {
+    response = await fetchImpl(blobUrl, { method: 'GET', redirect: 'follow' });
+  } catch (error) {
+    throw new Error(`Could not download artifact from ${blobUrl.origin}.`, { cause: error });
+  }
+
+  if (!response.ok) {
+    const detail = await safeResponseText(response);
+    throw new Error(`Artifact download failed with HTTP ${response.status}${detail ? `: ${detail}` : '.'}`);
+  }
+  if (response.url) {
+    const finalUrl = new URL(response.url);
+    if (finalUrl.protocol !== 'https:') throw new Error('Blob redirect must remain HTTPS.');
+  }
+
+  const contentLength = readContentLength(response);
+  if (contentLength !== undefined && contentLength > MAX_ARTIFACT_BYTES) {
+    throw new Error('Artifact exceeds Hub’s 250 MB limit.');
+  }
+  if (expectedSize > 0 && contentLength !== undefined && contentLength !== expectedSize) {
+    throw new Error(`Artifact Content-Length ${contentLength} does not match manifest sizeBytes ${expectedSize}.`);
+  }
+
+  await mkdir(tempDir, { recursive: true });
+  const tempPath = path.join(tempDir, `.download-${randomUUID()}.tmp`);
+  const output = createWriteStream(tempPath, { flags: 'wx', mode: 0o600 });
+  const hash = createHash('sha256');
+  let sizeBytes = 0;
+
+  try {
+    if (response.body && typeof response.body.getReader === 'function') {
+      for await (const chunk of Readable.fromWeb(response.body)) {
+        const bytes = Buffer.from(chunk);
+        sizeBytes += bytes.length;
+        if (sizeBytes > MAX_ARTIFACT_BYTES) throw new Error('Artifact exceeds Hub’s 250 MB limit.');
+        hash.update(bytes);
+        await writeChunk(output, bytes);
+      }
+    } else if (typeof response.arrayBuffer === 'function') {
+      const bytes = Buffer.from(await response.arrayBuffer());
+      sizeBytes = bytes.length;
+      if (sizeBytes > MAX_ARTIFACT_BYTES) throw new Error('Artifact exceeds Hub’s 250 MB limit.');
+      hash.update(bytes);
+      await writeChunk(output, bytes);
+    } else {
+      throw new Error('Artifact response did not provide a readable body.');
+    }
+    await endStream(output);
+  } catch (error) {
+    output.destroy();
+    await unlink(tempPath).catch(() => {});
+    throw error;
+  }
+
+  if (expectedSize > 0 && sizeBytes !== expectedSize) {
+    await unlink(tempPath).catch(() => {});
+    throw new Error(`Artifact body length ${sizeBytes} does not match manifest sizeBytes ${expectedSize}.`);
+  }
+
+  await chmod(tempPath, 0o600);
+  return { tempPath, sizeBytes, sha256: hash.digest('hex'), contentLength };
+}
+
+export async function readArtifact(tempPath) {
+  return new Uint8Array(await readFile(tempPath));
+}
+
+export async function installCachedArtifact(tempPath, cachePath) {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  await chmod(tempPath, 0o644);
+  await rename(tempPath, cachePath);
+  await chmod(cachePath, 0o644);
+  return cachePath;
+}
+
+async function writeChunk(stream, chunk) {
+  if (stream.write(chunk)) return;
+  await new Promise((resolve, reject) => {
+    const onDrain = () => {
+      stream.off('error', onError);
+      resolve();
+    };
+    const onError = (error) => {
+      stream.off('drain', onDrain);
+      reject(error);
+    };
+    stream.once('drain', onDrain);
+    stream.once('error', onError);
+  });
+}
+
+async function endStream(stream) {
+  await new Promise((resolve, reject) => {
+    const onClose = () => {
+      stream.off('error', onError);
+      resolve();
+    };
+    const onError = (error) => {
+      stream.off('close', onClose);
+      reject(error);
+    };
+    stream.once('close', onClose);
+    stream.once('error', onError);
+    stream.end();
+  });
+}
+
+function readContentLength(response) {
+  const raw = response.headers?.get?.('content-length') ?? response.headers?.['content-length'] ?? response.headers?.['Content-Length'];
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error('Artifact Content-Length is invalid.');
+  return value;
+}
+
+async function safeResponseText(response) {
+  try {
+    const text = await response.text();
+    return String(text || '').replace(/\s+/g, ' ').slice(0, 240);
+  } catch {
+    return '';
+  }
+}

package/bin/registry/commands.mjs

@@ -0,0 +1,392 @@
+import { copyFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { registryApiUrl, resolveRegistryUrl } from './config.mjs';
+import { downloadBlobToTemp, installCachedArtifact, readArtifact } from './artifacts.mjs';
+import { RegistryError } from './errors.mjs';
+import { getJson } from './http.mjs';
+import { cachePath, upsertLockfile, validateLockfileUpdate } from './lockfile.mjs';
+import { validatePackManifest } from './manifest.mjs';
+import { parsePackName, parsePackSpec } from './specs.mjs';
+import { loadCredentials, promptForToken, removeCredentials, saveCredentials, validateToken } from './credentials.mjs';
+
+const PACK_SHA256_PATTERN = /^[0-9a-f]{64}$/;
+
+export async function runHubSearch(args, { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}) {
+  const { query, flags } = parseSearchArgs(args);
+  const registry = resolveRegistryUrl({ value: flags.registry, env });
+  const url = registryApiUrl(registry, ['packs'], {
+    q: query,
+    format: flags.format,
+    license: flags.license,
+    official: flags.official ? 'true' : undefined,
+    agents: flags.agents ? 'true' : undefined,
+  });
+  const body = await getJson(url, { fetchImpl });
+  validatePacksResponse(body);
+
+  if (flags.json) print(JSON.stringify(body, null, 2));
+  else print(renderSearchTable(body.packs));
+
+  return { registry, url: String(url), body };
+}
+
+export async function runHubInfo(args, { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}) {
+  const { positional, flags } = parseInfoArgs(args);
+  const pack = parsePackName(positional[0]);
+  const registry = resolveRegistryUrl({ value: flags.registry, env });
+  const url = registryApiUrl(registry, ['packs', pack.publisher, pack.slug]);
+  const body = await getJson(url, { fetchImpl });
+  validatePackInfoResponse(body);
+
+  if (flags.json) print(JSON.stringify(body, null, 2));
+  else print(renderPackInfo(body));
+
+  return { registry, url: String(url), body };
+}
+
+export async function runHubAdd(args, {
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  core,
+  cwd = process.cwd(),
+  homeDir,
+  print = console.log,
+  warn = console.error,
+} = {}) {
+  const { spec, flags } = parseAddArgs(args);
+  if (!core) throw new Error('Could not load @knolo/core for Hub artifact validation.');
+  const registry = resolveRegistryUrl({ value: flags.registry, env });
+  const manifestUrl = registryApiUrl(registry, ['packs', spec.publisher, spec.slug, spec.version]);
+
+  let manifest;
+  let yanked = false;
+  try {
+    const body = await getJson(manifestUrl, { fetchImpl });
+    manifest = validatePackManifest(body, { expectedName: spec.name, requestedVersion: spec.version });
+  } catch (error) {
+    if (error instanceof RegistryError && (error.status === 404 || error.code === 'not_found')) {
+      throw new Error('pack version not found');
+    }
+    if (error instanceof RegistryError && (error.status === 410 || error.code === 'yanked')) {
+      manifest = validatePackManifest(error.body, { expectedName: spec.name, requestedVersion: spec.version });
+      yanked = true;
+    } else {
+      throw error;
+    }
+  }
+
+  if (manifest.yanked) yanked = true;
+  if (yanked && !flags.force) throw new Error('version yanked; use --force to download yanked bytes');
+  if (yanked) warn(`warning: downloading yanked version ${manifest.name}@${manifest.version}`);
+  if (!manifest.url) throw new Error('artifact bytes are not stored yet');
+  if (!PACK_SHA256_PATTERN.test(manifest.sha256)) throw new Error('manifest sha256 is invalid');
+
+  const artifactHome = homeDir || homedir();
+  await validateLockfileUpdate({ cwd, registry, manifest, force: flags.force });
+  const finalCachePath = cachePath(artifactHome, manifest.sha256);
+  const tempDir = path.dirname(finalCachePath);
+  const download = await downloadBlobToTemp(manifest.url, {
+    tempDir,
+    expectedSize: manifest.sizeBytes,
+    fetchImpl,
+  });
+  let installed = false;
+  try {
+    if (download.sha256 !== manifest.sha256) {
+      throw new Error(`artifact sha256 mismatch: expected ${manifest.sha256}, got ${download.sha256}`);
+    }
+    const bytes = await readArtifact(download.tempPath);
+    const validation = await validateKnowledgeImage(core, bytes);
+    if (manifest.format && String(manifest.format).toUpperCase() !== validation.format) {
+      throw new Error(`artifact format mismatch: manifest=${manifest.format}, bytes=${validation.format}`);
+    }
+    if (manifest.stateRoot !== undefined && manifest.stateRoot !== validation.stateRoot) {
+      throw new Error(`artifact stateRoot mismatch: expected ${manifest.stateRoot}, got ${validation.stateRoot || 'none'}`);
+    }
+    const cache = await installCachedArtifact(download.tempPath, finalCachePath);
+    installed = true;
+    const lock = await upsertLockfile({ cwd, registry, manifest, force: flags.force });
+    let outputPath = cache;
+    if (flags.out) {
+      outputPath = await copyArtifact(cache, flags.out, cwd);
+    }
+    const result = { ...manifest, path: outputPath, lockfile: lock.path };
+    if (flags.json) print(JSON.stringify(result, null, 2));
+    else {
+      print(`added ${manifest.name}@${manifest.version}`);
+      print(`sha256 ${manifest.sha256}`);
+      print(`url    ${manifest.url}`);
+      print(`path   ${outputPath}`);
+    }
+    return result;
+  } finally {
+    if (!installed) await unlinkIfPresent(download.tempPath);
+  }
+}
+
+export async function runHubLogin(args, {
+  env = process.env,
+  homeDir,
+  input = process.stdin,
+  output = process.stderr,
+  print = console.log,
+} = {}) {
+  const { flags } = parseLoginArgs(args);
+  const registry = resolveRegistryUrl({ value: flags.registry, env });
+  print(`Create a token at ${registry}/dashboard/tokens (Sign in with GitHub).`);
+  const token = (flags.token ?? await promptForToken({ input, output, forceStdin: flags.stdin })).trim();
+  validateToken(token);
+  const saved = await saveCredentials({ registry, token, env, homeDir });
+  print(`logged in to ${saved.registry}`);
+  print(`token ${saved.prefix}`);
+  return saved;
+}
+
+export async function runHubWhoami(args, { env = process.env, homeDir, print = console.log } = {}) {
+  if (args.length) throw new Error('Usage: knolo whoami');
+  const credentials = await loadCredentials({ env, homeDir });
+  print(`registry ${credentials.registry}`);
+  print(`token    ${credentials.prefix}`);
+  return { registry: credentials.registry, prefix: credentials.prefix };
+}
+
+export async function runHubLogout(args, { env = process.env, homeDir, print = console.log } = {}) {
+  if (args.length) throw new Error('Usage: knolo logout');
+  const result = await removeCredentials({ env, homeDir });
+  print(result.removed ? 'logged out' : 'not logged in');
+  return result;
+}
+
+export function runHubPublishStub() {
+  throw new Error('Hub write APIs do not accept CLI tokens yet');
+}
+
+export function parseAddArgs(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--force' || arg === '--json') {
+      flags[arg.slice(2)] = true;
+      continue;
+    }
+    if (['--out', '--registry'].includes(arg)) {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      flags[arg.slice(2)] = value;
+      continue;
+    }
+    if (arg.startsWith('--')) throw new Error(`Unknown flag for add: ${arg}`);
+    positional.push(arg);
+  }
+  if (positional.length !== 1) throw new Error('Usage: knolo add <publisher>/<slug>[@<version>] [--out <path>] [--force] [--json] [--registry <url>]');
+  return { spec: parsePackSpec(positional[0]), flags };
+}
+
+export function parseLoginArgs(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--stdin') {
+      flags.stdin = true;
+      continue;
+    }
+    if (arg === '--token' || arg === '--registry') {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      flags[arg.slice(2)] = value;
+      continue;
+    }
+    if (arg.startsWith('--')) throw new Error(`Unknown flag for login: ${arg}`);
+    throw new Error('Usage: knolo login [--token kno_…] [--stdin] [--registry <url>]');
+  }
+  return { flags };
+}
+
+export function isHubAddInvocation(args) {
+  if (!args[0] || args[0].startsWith('--')) return false;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (['--out', '--registry'].includes(arg)) {
+      i += 1;
+      continue;
+    }
+    if (arg === '--force' || arg === '--json') continue;
+    if (arg.startsWith('--')) return false;
+    positional.push(arg);
+  }
+  if (positional.length !== 1) return false;
+  try {
+    parsePackSpec(positional[0]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function parseSearchArgs(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json' || arg === '--official' || arg === '--agents') {
+      flags[arg.slice(2)] = true;
+      continue;
+    }
+    if (['--format', '--license', '--registry'].includes(arg)) {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      flags[arg.slice(2)] = value;
+      continue;
+    }
+    if (arg.startsWith('--')) throw new Error(`Unknown flag for search: ${arg}`);
+    positional.push(arg);
+  }
+
+  const query = positional.join(' ').trim();
+  if (!query) throw new Error('Usage: knolo search <query> [--format V4|V5] [--license <id>] [--official] [--agents] [--json] [--registry <url>]');
+  if (flags.format && !['V4', 'V5'].includes(String(flags.format).toUpperCase())) {
+    throw new Error('--format must be V4 or V5.');
+  }
+  if (flags.format) flags.format = String(flags.format).toUpperCase();
+  return { query, flags };
+}
+
+export function parseInfoArgs(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      flags.json = true;
+      continue;
+    }
+    if (arg === '--registry') {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error('Missing value for --registry');
+      flags.registry = value;
+      continue;
+    }
+    if (arg.startsWith('--')) throw new Error(`Unknown flag for info: ${arg}`);
+    positional.push(arg);
+  }
+  if (positional.length !== 1) throw new Error('Usage: knolo info <publisher>/<slug> [--json] [--registry <url>]');
+  return { positional, flags };
+}
+
+function validatePacksResponse(body) {
+  if (!body || typeof body !== 'object' || !Array.isArray(body.packs)) {
+    throw new Error('Registry returned an invalid packs response.');
+  }
+}
+
+function validatePackInfoResponse(body) {
+  if (!body || typeof body !== 'object' || typeof body.name !== 'string' || !body.pack || typeof body.pack !== 'object') {
+    throw new Error('Registry returned an invalid pack response.');
+  }
+}
+
+async function validateKnowledgeImage(core, bytes) {
+  if (core.isKnowledgeImageV5?.(bytes)) {
+    try {
+      const verification = core.verifyKnowledgeImageV5(bytes);
+      return { format: 'V5', stateRoot: verification.stateRoot };
+    } catch (error) {
+      throw new Error(`invalid V5 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  if (core.isPackV4?.(buffer)) {
+    try {
+      await core.mountPack({ src: bytes });
+      return { format: 'V4' };
+    } catch (error) {
+      throw new Error(`invalid V4 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  throw new Error('not a Knowledge Image');
+}
+
+async function copyArtifact(sourcePath, outputPath, cwd) {
+  const targetPath = path.resolve(cwd, outputPath);
+  const tempPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  try {
+    await copyFile(sourcePath, tempPath);
+    await rename(tempPath, targetPath);
+  } finally {
+    await unlinkIfPresent(tempPath);
+  }
+  return targetPath;
+}
+
+async function unlinkIfPresent(filePath) {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+export function renderSearchTable(packs) {
+  if (!packs.length) return 'No packs found.';
+
+  const rows = packs.map((pack) => [
+    pack.id || pack.name || `${pack.publisher || ''}/${pack.slug || ''}`,
+    pack.version ?? '',
+    pack.format ?? '',
+    pack.license ?? '',
+    pack.pulls ?? 0,
+    pack.description ?? '',
+  ].map((value) => String(value)));
+  const widths = [24, 9, 6, 11, 8];
+  const header = ['NAME', 'VERSION', 'FORMAT', 'LICENSE', 'PULLS', 'DESCRIPTION'];
+  const formatRow = (row) => [
+    pad(truncate(row[0], widths[0]), widths[0]),
+    pad(truncate(row[1], widths[1]), widths[1]),
+    pad(truncate(row[2], widths[2]), widths[2]),
+    pad(truncate(row[3], widths[3]), widths[3]),
+    pad(truncate(row[4], widths[4]), widths[4]),
+    truncate(row[5], 72),
+  ].join('  ').trimEnd();
+
+  return [formatRow(header), ...rows.map(formatRow)].join('\n');
+}
+
+export function renderPackInfo(body) {
+  const pack = body.pack || {};
+  const latest = body.latest || {};
+  const lines = [
+    `name        ${body.name}`,
+    `description ${body.description || pack.description || ''}`,
+    `publisher   ${body.publisher || pack.publisher || ''}`,
+    `slug        ${body.slug || pack.slug || ''}`,
+    `format      ${pack.format || ''}`,
+    `version     ${pack.version || latest.version || ''}`,
+    `license     ${pack.license || latest.license || ''}`,
+    `sizeBytes   ${pack.sizeBytes ?? latest.sizeBytes ?? 0}`,
+    `docs        ${pack.docs ?? 0}`,
+    `blocks      ${pack.blocks ?? 0}`,
+    `namespaces  ${Array.isArray(pack.namespaces) ? pack.namespaces.join(', ') : ''}`,
+    `pulls       ${pack.pulls ?? 0}`,
+    `stars       ${pack.stars ?? 0}`,
+    `topics      ${Array.isArray(pack.topics) ? pack.topics.join(', ') : ''}`,
+    `latest      ${latest.version || ''}`,
+    `sha256      ${latest.sha256 || pack.sha256 || ''}`,
+    `url         ${latest.url || pack.blobUrl || ''}`,
+  ];
+  return lines.join('\n');
+}
+
+function truncate(value, width) {
+  if (value.length <= width) return value;
+  if (width <= 1) return '…'.slice(0, width);
+  return `${value.slice(0, width - 1)}…`;
+}
+
+function pad(value, width) {
+  return value.padEnd(width, ' ');
+}

package/bin/registry/config.mjs

@@ -0,0 +1,46 @@
+export const DEFAULT_PRODUCTION_REGISTRY = 'https://hub.knolo.dev';
+export const DEFAULT_DEVELOPMENT_REGISTRY = 'http://localhost:3000';
+
+export function resolveRegistryUrl({ value, env = process.env } = {}) {
+  const configured = value || env.KNOLO_HUB_URL;
+  if (configured) return normalizeRegistryUrl(configured);
+
+  const development = env.NODE_ENV === 'development' || env.KNOLO_ENV === 'development';
+  return normalizeRegistryUrl(development ? DEFAULT_DEVELOPMENT_REGISTRY : DEFAULT_PRODUCTION_REGISTRY);
+}
+
+export function normalizeRegistryUrl(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error('Registry URL must be a non-empty HTTP(S) URL.');
+  }
+
+  let url;
+  try {
+    url = new URL(value.trim());
+  } catch {
+    throw new Error(`Invalid registry URL: ${value}`);
+  }
+
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error(`Registry URL must use http or https: ${value}`);
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error('Registry URL must be an origin without credentials, query parameters, or fragments.');
+  }
+  if (url.pathname !== '/' && url.pathname !== '') {
+    throw new Error('Registry URL must be an origin without a path.');
+  }
+
+  return url.origin;
+}
+
+export function registryApiUrl(registry, segments, searchParams) {
+  const url = new URL(normalizeRegistryUrl(registry));
+  url.pathname = `/api/v1/${segments.map((segment) => encodeURIComponent(String(segment))).join('/')}`;
+  if (searchParams) {
+    for (const [key, value] of Object.entries(searchParams)) {
+      if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value));
+    }
+  }
+  return url;
+}

package/bin/registry/credentials.mjs

@@ -0,0 +1,93 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+const TOKEN_PATTERN = /^kno_[A-Za-z0-9_-]+$/;
+
+export function credentialsPath({ env = process.env, homeDir = homedir() } = {}) {
+  const configHome = env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(homeDir, '.config');
+  return path.join(configHome, 'knolo', 'credentials.json');
+}
+
+export async function saveCredentials({ registry, token, env = process.env, homeDir = homedir() } = {}) {
+  const normalizedToken = typeof token === 'string' ? token.trim() : token;
+  validateToken(normalizedToken);
+  if (typeof registry !== 'string' || !registry) throw new Error('Credential registry is required.');
+  const targetPath = credentialsPath({ env, homeDir });
+  const directory = path.dirname(targetPath);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+
+  const value = {
+    registry,
+    token: normalizedToken,
+    prefix: normalizedToken.slice(0, 12),
+  };
+  const tempPath = `${targetPath}.tmp-${process.pid}-${randomUUID()}`;
+  try {
+    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    await chmod(tempPath, 0o600);
+    await rename(tempPath, targetPath);
+    await chmod(targetPath, 0o600);
+  } finally {
+    await unlink(tempPath).catch(() => {});
+  }
+  return { path: targetPath, registry, prefix: value.prefix };
+}
+
+export async function loadCredentials({ env = process.env, homeDir = homedir() } = {}) {
+  const filePath = credentialsPath({ env, homeDir });
+  let text;
+  try {
+    text = await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error('Not logged in. Run "knolo login" first.');
+    throw error;
+  }
+
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error('Invalid JSON in knolo credentials.');
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Knolo credentials must be a JSON object.');
+  if (typeof value.registry !== 'string' || !value.registry) throw new Error('Knolo credentials are missing registry.');
+  validateToken(value.token);
+  if (typeof value.prefix !== 'string' || value.prefix !== value.token.slice(0, 12)) throw new Error('Knolo credentials have an invalid token prefix.');
+  return { path: filePath, registry: value.registry, token: value.token, prefix: value.prefix };
+}
+
+export async function removeCredentials({ env = process.env, homeDir = homedir() } = {}) {
+  const filePath = credentialsPath({ env, homeDir });
+  try {
+    await unlink(filePath);
+    return { path: filePath, removed: true };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { path: filePath, removed: false };
+    throw error;
+  }
+}
+
+export async function promptForToken({ input = process.stdin, output = process.stderr, forceStdin = false } = {}) {
+  if (forceStdin || !input.isTTY) {
+    const chunks = [];
+    for await (const chunk of input) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8').trim();
+  }
+
+  const readline = createInterface({ input, output });
+  try {
+    return (await readline.question('Hub token (kno_…): ')).trim();
+  } finally {
+    readline.close();
+  }
+}
+
+export function validateToken(token) {
+  if (typeof token !== 'string' || !TOKEN_PATTERN.test(token.trim())) {
+    throw new Error('Token must start with kno_ and contain only base64url characters.');
+  }
+}

package/bin/registry/errors.mjs

@@ -0,0 +1,28 @@
+export class RegistryError extends Error {
+  constructor(message, { status, code, url, body, cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'RegistryError';
+    this.status = status;
+    this.code = code;
+    this.url = url;
+    this.body = body;
+  }
+}
+
+export class RegistryNetworkError extends Error {
+  constructor(message, { url, cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'RegistryNetworkError';
+    this.url = url;
+  }
+}
+
+export function registryErrorMessage({ status, code, body, url }) {
+  if (typeof body?.error === 'string' && body.error.trim()) return body.error.trim();
+  if (status === 401 || code === 'unauthenticated') return 'Registry authentication is required.';
+  if (status === 404 || code === 'not_found') return 'Registry resource not found.';
+  if (status === 410 || code === 'yanked') return 'Registry version is yanked.';
+  if (status === 413 || code === 'too_large') return 'Registry artifact is too large.';
+  if (status === 503 || code === 'unconfigured') return 'Registry is not configured.';
+  return `Registry request failed${status ? ` with HTTP ${status}` : ''}${url ? `: ${url}` : '.'}`;
+}

package/bin/registry/http.mjs

@@ -0,0 +1,58 @@
+import { RegistryError, RegistryNetworkError, registryErrorMessage } from './errors.mjs';
+
+export async function getJson(url, { fetchImpl = globalThis.fetch, headers = {} } = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('This Node runtime does not provide fetch.');
+
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'GET',
+      redirect: 'follow',
+      headers: { accept: 'application/json', ...headers },
+    });
+  } catch (error) {
+    throw new RegistryNetworkError(`Could not reach registry at ${new URL(url).origin}.`, { url: String(url), cause: error });
+  }
+
+  const text = await readResponseText(response, url);
+  let body;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      if (!response.ok) {
+        throw new RegistryError(`Registry returned HTTP ${response.status} with a non-JSON response.`, {
+          status: response.status,
+          url: String(url),
+          body: text.slice(0, 240),
+        });
+      }
+      throw new RegistryError('Registry returned invalid JSON.', {
+        status: response.status,
+        code: 'invalid_response',
+        url: String(url),
+        body: text.slice(0, 240),
+      });
+    }
+  }
+
+  if (!response.ok) {
+    const code = typeof body?.code === 'string' ? body.code : undefined;
+    throw new RegistryError(registryErrorMessage({ status: response.status, code, body, url: String(url) }), {
+      status: response.status,
+      code,
+      url: String(url),
+      body,
+    });
+  }
+
+  return body;
+}
+
+async function readResponseText(response, url) {
+  try {
+    return await response.text();
+  } catch (error) {
+    throw new RegistryNetworkError(`Could not read registry response from ${new URL(url).origin}.`, { url: String(url), cause: error });
+  }
+}

package/bin/registry/lockfile.mjs

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const LOCKFILE_NAME = 'knolo.lock.json';
+
+export function lockfilePath(cwd = process.cwd()) {
+  return path.resolve(cwd, LOCKFILE_NAME);
+}
+
+export function cachePath(homeDir, sha256) {
+  return path.join(homeDir, '.knolo', 'cache', 'sha256', `${sha256}.knolo`);
+}
+
+export async function validateLockfileUpdate({ cwd = process.cwd(), registry, manifest, force = false } = {}) {
+  const targetPath = lockfilePath(cwd);
+  const current = await readLockfile(targetPath);
+  if (current.registry && current.registry !== registry && !force) {
+    throw new Error(`Lockfile registry is ${current.registry}; refusing to mix registries without --force.`);
+  }
+
+  const packs = current.packs && typeof current.packs === 'object' && !Array.isArray(current.packs)
+    ? current.packs
+    : {};
+  const existing = packs[manifest.name];
+  if (existing?.sha256 && existing.sha256 !== manifest.sha256 && !force) {
+    throw new Error(`Lockfile already pins ${manifest.name} to a different digest; use --force to replace it.`);
+  }
+
+  const entry = {
+    version: manifest.version,
+    sha256: manifest.sha256,
+    ...(manifest.stateRoot !== undefined ? { stateRoot: manifest.stateRoot } : {}),
+    ...(manifest.license !== undefined ? { license: manifest.license } : {}),
+  };
+  return { targetPath, current, entry, packs };
+}
+
+export async function upsertLockfile({ cwd = process.cwd(), registry, manifest, force = false } = {}) {
+  const { targetPath, entry, packs } = await validateLockfileUpdate({ cwd, registry, manifest, force });
+  const next = {
+    registry,
+    packs: { ...packs, [manifest.name]: entry },
+  };
+  await atomicWriteJson(targetPath, next);
+  return { path: targetPath, entry };
+}
+
+async function readLockfile(filePath) {
+  let text;
+  try {
+    text = await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { packs: {} };
+    throw error;
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error(`Invalid JSON in ${LOCKFILE_NAME}.`);
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${LOCKFILE_NAME} must be a JSON object.`);
+  if (value.registry !== undefined && typeof value.registry !== 'string') throw new Error(`${LOCKFILE_NAME}.registry must be a string.`);
+  if (value.packs !== undefined && (typeof value.packs !== 'object' || Array.isArray(value.packs))) throw new Error(`${LOCKFILE_NAME}.packs must be an object.`);
+  return value;
+}
+
+async function atomicWriteJson(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${randomUUID()}`;
+  try {
+    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o644 });
+    await rename(tempPath, filePath);
+  } finally {
+    await unlink(tempPath).catch(() => {});
+  }
+}

package/bin/registry/manifest.mjs

@@ -0,0 +1,41 @@
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+
+export function validatePackManifest(value, { expectedName, requestedVersion } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Registry returned an invalid pack manifest.');
+  }
+  if (typeof value.name !== 'string' || !value.name) throw new Error('Registry manifest is missing name.');
+  if (expectedName && value.name !== expectedName) throw new Error(`Registry manifest name mismatch: expected ${expectedName}, got ${value.name}.`);
+  if (typeof value.version !== 'string' || !value.version) throw new Error('Registry manifest is missing version.');
+  if (requestedVersion && requestedVersion !== 'latest' && value.version !== requestedVersion) {
+    throw new Error(`Registry manifest version mismatch: expected ${requestedVersion}, got ${value.version}.`);
+  }
+  if (typeof value.sha256 !== 'string' || !SHA256_PATTERN.test(value.sha256)) {
+    throw new Error('Registry manifest sha256 must be 64 lowercase hexadecimal characters.');
+  }
+  if (typeof value.url !== 'string') throw new Error('Registry manifest is missing url.');
+  if (!Number.isSafeInteger(value.sizeBytes) || value.sizeBytes < 0) {
+    throw new Error('Registry manifest sizeBytes must be a non-negative integer.');
+  }
+  if (value.stateRoot !== undefined && typeof value.stateRoot !== 'string') {
+    throw new Error('Registry manifest stateRoot must be a string when present.');
+  }
+  if (value.license !== undefined && typeof value.license !== 'string') {
+    throw new Error('Registry manifest license must be a string when present.');
+  }
+  if (value.yanked !== undefined && typeof value.yanked !== 'boolean') {
+    throw new Error('Registry manifest yanked must be a boolean when present.');
+  }
+
+  return {
+    name: value.name,
+    version: value.version,
+    sha256: value.sha256,
+    ...(value.stateRoot !== undefined ? { stateRoot: value.stateRoot } : {}),
+    url: value.url,
+    ...(value.license !== undefined ? { license: value.license } : {}),
+    sizeBytes: value.sizeBytes,
+    yanked: value.yanked === true,
+    ...(value.format !== undefined ? { format: value.format } : {}),
+  };
+}

package/bin/registry/specs.mjs

@@ -0,0 +1,20 @@
+const PACK_SPEC_PATTERN = /^(?<publisher>[a-z0-9-]+)\/(?<slug>[a-z0-9-]+)(?:@(?<version>[^@]+))?$/;
+
+export function parsePackSpec(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('Pack spec must be publisher/slug[@version].');
+  const match = PACK_SPEC_PATTERN.exec(value.trim());
+  if (!match) throw new Error(`Invalid pack spec: ${value}. Expected publisher/slug[@version].`);
+
+  return {
+    publisher: match.groups.publisher,
+    slug: match.groups.slug,
+    version: match.groups.version || 'latest',
+    name: `${match.groups.publisher}/${match.groups.slug}`,
+  };
+}
+
+export function parsePackName(value) {
+  const parsed = parsePackSpec(value);
+  if (value.includes('@')) throw new Error(`Pack name must not include a version: ${value}`);
+  return parsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/cli",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
@@ -28,7 +28,8 @@
   },
   "scripts": {
     "build": "node -e \"console.log('cli is executable via bin/knolo.mjs')\"",
-    "test": "npm run build --prefix ../core && node --test test/cli.test.mjs"
+    "test": "npm run build --prefix ../core && node --test test/cli.test.mjs test/hub.integration.test.mjs",
+    "test:hub": "node --test test/hub.integration.test.mjs"
   },
   "dependencies": {
     "@knolo/core": "^5.1.0"