@knolo/cli 5.1.0 → 5.2.1

package/README.md

@@ -25,6 +25,81 @@ 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`.
+
+Hub writes use a dashboard token as an HTTP Bearer credential. GitHub sign-in
+is needed only to mint that token at
+`https://hub.knolo.dev/dashboard/tokens`; `knolo login` is local-only and does
+not call a Hub login or token-minting endpoint:
+
+```bash
+knolo login --token kno_…
+# write requests use: Authorization: Bearer kno_…
+```
+
+`knolo publish` uploads bytes directly to the public Blob URL returned by Hub,
+waits for verification, creates an attested draft, and releases it. The
+`--slug`, `--version`, and SPDX `--license` are required:
+
+```bash
+knolo publish ./dist/knowledge.knolo \
+  --slug refund-policy --version 1.2.0 --license Apache-2.0
+knolo yank acme/refund-policy@1.2.0
+```
+
+Only public Blob URLs are accepted because Hub verification fetches the
+artifact itself. The CLI never sends the `kno_…` token to Blob, in a query
+string, cookie, or pack bytes. A 401 usually means the `Bearer` word is
+missing or the token was revoked; it does not mean the Hub write API requires
+a GitHub browser session.
+
+The older `@knolo/cli@5.2.0` publish/yank command was an unimplemented stub;
+current versions use the live Hub HTTP sequence. For a direct smoke test of a
+stored credential, request the account endpoint with the same header:
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer kno_…" \
+  -H "Accept: application/json" \
+  https://hub.knolo.dev/api/v1/account
+```
+
+Do not use `POST /api/v1/tokens` as a CLI login endpoint; it is for the
+dashboard/GitHub session that mints tokens.
+
+Hub pack installation remains available without credentials and only happens
+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, runHubPublish, runHubSearch, runHubWhoami, runHubYank } 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', 'yank', '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,14 @@ 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 a pack with a Hub Bearer token
+  yank <pack>@<version>   Yank a released pack with a Hub Bearer token
   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 +109,14 @@ 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>]\n\nStores the raw token locally. Hub write calls send Authorization: Bearer kno_….\nMint tokens at https://hub.knolo.dev/dashboard/tokens; login does not call POST /api/v1/tokens.',
+    whoami: 'Usage: knolo whoami',
+    logout: 'Usage: knolo logout',
+    publish: 'Usage: knolo publish <pack.knolo> --slug <slug> --version <version> --license <SPDX> [--publisher <handle>] [--readme <text>] [--sources <text>] [--intended-use <text>] [--json] [--registry <url>]\n\nUses the stored token as Authorization: Bearer kno_…. Uploads go directly to a public Blob URL; Hub verifies before release.\nOlder @knolo/cli 5.2.0 builds were unimplemented; Hub has always accepted Bearer CLI tokens.',
+    yank: 'Usage: knolo yank <publisher>/<slug>@<version> [--json] [--registry <url>]\n\nUses the stored token as Authorization: Bearer kno_…. Yank is owner-only and leaves the public Blob in place.',
     build: 'Usage: knolo build',
     query: 'Usage: knolo query <question> [--pack <path>] [--k <number>] [--receipt <file>] [--json]',
     inspect: 'Usage: knolo inspect <pack.knolo>',
@@ -272,6 +287,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 +1192,13 @@ 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 runHubPublish(commandArgs);
+      if (command === 'yank') return runHubYank(commandArgs);
 
       const core = await loadCore();
       if (command === 'build') return await cmdBuild(core);

package/bin/registry/artifacts.mjs

@@ -0,0 +1,159 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { chmod, copyFile, 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) {
+  const stagedPath = await stageCachedArtifact(tempPath, cachePath);
+  try {
+    await rename(stagedPath, cachePath);
+    await chmod(cachePath, 0o644);
+    return cachePath;
+  } finally {
+    await unlink(stagedPath).catch(() => {});
+  }
+}
+
+export async function stageCachedArtifact(sourcePath, cachePath) {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  const stagedPath = `${cachePath}.tmp-${process.pid}-${randomUUID()}`;
+  try {
+    await copyFile(sourcePath, stagedPath);
+    await chmod(stagedPath, 0o644);
+    return stagedPath;
+  } catch (error) {
+    await unlink(stagedPath).catch(() => {});
+    throw error;
+  }
+}
+
+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 '';
+  }
+}