@knolo/cli 5.2.0 → 5.2.1

package/README.md

@@ -47,10 +47,49 @@ 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:
+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
@@ -60,6 +99,7 @@ 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,7 +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';
+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);
@@ -34,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', 'search', 'info', 'login', 'whoami', 'logout', 'publish', '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'),
@@ -86,7 +86,8 @@ Commands:
   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
+  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
@@ -111,10 +112,11 @@ function printCommandHelp(command) {
     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>]',
+    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>  (not available until Hub write APIs support CLI tokens)',
+    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>',
@@ -1195,7 +1197,8 @@ async function main() {
       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);
+      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

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { createWriteStream } from 'node:fs';
-import { chmod, mkdir, readFile, rename, unlink } from 'node:fs/promises';
+import { chmod, copyFile, mkdir, readFile, rename, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import { Readable } from 'node:stream';
 
@@ -86,11 +86,27 @@ export async function readArtifact(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 });
-  await chmod(tempPath, 0o644);
-  await rename(tempPath, cachePath);
-  await chmod(cachePath, 0o644);
-  return cachePath;
+  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) {

package/bin/registry/commands.mjs

@@ -1,11 +1,12 @@
-import { copyFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { chmod, copyFile, lstat, mkdir, readFile, rename, unlink } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { registryApiUrl, resolveRegistryUrl } from './config.mjs';
-import { downloadBlobToTemp, installCachedArtifact, readArtifact } from './artifacts.mjs';
+import { downloadBlobToTemp, MAX_ARTIFACT_BYTES, readArtifact, stageCachedArtifact } from './artifacts.mjs';
 import { RegistryError } from './errors.mjs';
-import { getJson } from './http.mjs';
-import { cachePath, upsertLockfile, validateLockfileUpdate } from './lockfile.mjs';
+import { getJson, postJson, putBytes } from './http.mjs';
+import { cachePath, stageLockfileUpdate, validateLockfileUpdate } from './lockfile.mjs';
 import { validatePackManifest } from './manifest.mjs';
 import { parsePackName, parsePackSpec } from './specs.mjs';
 import { loadCredentials, promptForToken, removeCredentials, saveCredentials, validateToken } from './credentials.mjs';
@@ -91,7 +92,7 @@ export async function runHubAdd(args, {
     expectedSize: manifest.sizeBytes,
     fetchImpl,
   });
-  let installed = false;
+  const stagedFiles = [];
   try {
     if (download.sha256 !== manifest.sha256) {
       throw new Error(`artifact sha256 mismatch: expected ${manifest.sha256}, got ${download.sha256}`);
@@ -101,16 +102,24 @@ export async function runHubAdd(args, {
     if (manifest.format && String(manifest.format).toUpperCase() !== validation.format) {
       throw new Error(`artifact format mismatch: manifest=${manifest.format}, bytes=${validation.format}`);
     }
+    if (validation.format === 'V5' && !manifest.stateRoot) {
+      throw new Error('V5 artifact requires manifest stateRoot.');
+    }
     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;
+    const stagedCachePath = await stageCachedArtifact(download.tempPath, finalCachePath);
+    stagedFiles.push({ targetPath: finalCachePath, tempPath: stagedCachePath });
+    let outputPath = finalCachePath;
     if (flags.out) {
-      outputPath = await copyArtifact(cache, flags.out, cwd);
+      const stagedOutput = await stageArtifactCopy(download.tempPath, flags.out, cwd);
+      stagedFiles.push(stagedOutput);
+      outputPath = stagedOutput.targetPath;
     }
+    const stagedLock = await stageLockfileUpdate({ cwd, registry, manifest, force: flags.force });
+    stagedFiles.push({ targetPath: stagedLock.path, tempPath: stagedLock.tempPath });
+    await commitStagedFiles(stagedFiles);
+    const lock = { path: stagedLock.path, entry: stagedLock.entry };
     const result = { ...manifest, path: outputPath, lockfile: lock.path };
     if (flags.json) print(JSON.stringify(result, null, 2));
     else {
@@ -121,7 +130,8 @@ export async function runHubAdd(args, {
     }
     return result;
   } finally {
-    if (!installed) await unlinkIfPresent(download.tempPath);
+    await unlinkIfPresent(download.tempPath);
+    await Promise.all(stagedFiles.map(({ tempPath }) => unlinkIfPresent(tempPath)));
   }
 }
 
@@ -140,6 +150,7 @@ export async function runHubLogin(args, {
   const saved = await saveCredentials({ registry, token, env, homeDir });
   print(`logged in to ${saved.registry}`);
   print(`token ${saved.prefix}`);
+  print('Authorization: Bearer kno_…');
   return saved;
 }
 
@@ -158,8 +169,323 @@ export async function runHubLogout(args, { env = process.env, homeDir, print = c
   return result;
 }
 
-export function runHubPublishStub() {
-  throw new Error('Hub write APIs do not accept CLI tokens yet');
+export async function runHubPublish(args, {
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  cwd = process.cwd(),
+  homeDir,
+  print = console.log,
+  sleep = wait,
+  pollIntervalMs = 1000,
+  maxPollAttempts = 120,
+} = {}) {
+  const { packPath, flags } = parsePublishArgs(args);
+  const credentials = await loadCredentials({ env, homeDir });
+  const registry = resolveRegistryUrl({ value: flags.registry || credentials.registry, env });
+  const authHeaders = authorizationHeaders(credentials.token);
+
+  // This request is deliberately first: it proves the stored dashboard token
+  // is a Hub Bearer credential before any upload or publish mutation starts.
+  const account = await getJson(registryApiUrl(registry, ['account']), { fetchImpl, headers: authHeaders });
+  const accountPublisher = extractPublisherHandle(account);
+  if (flags.publisher && accountPublisher && flags.publisher !== accountPublisher) {
+    throw new Error(`Token is scoped to publisher ${accountPublisher}, not ${flags.publisher}.`);
+  }
+  const publisher = flags.publisher || accountPublisher;
+
+  const packFile = path.resolve(cwd, packPath);
+  const bytes = await readFile(packFile);
+  if (bytes.length > MAX_ARTIFACT_BYTES) throw new Error('Artifact exceeds Hub’s 250 MB limit.');
+  const sha256 = createSha256(bytes);
+
+  const uploadToken = await postJson(hubApiUrl(registry, ['upload', 'token']), {
+    sha256,
+    contentLength: bytes.length,
+  }, { fetchImpl, headers: authHeaders });
+  const upload = validateUploadTokenResponse(uploadToken, sha256);
+  assertPublicBlobUrl(upload.url, 'upload');
+  const uploaded = await putBytes(upload.url, bytes, {
+    fetchImpl,
+    headers: { 'content-length': String(bytes.length) },
+  });
+  assertPublicBlobUrl(uploaded.url, 'uploaded artifact');
+
+  const completed = await postJson(hubApiUrl(registry, ['upload', 'complete']), {
+    sha256,
+    url: upload.url,
+    sizeBytes: bytes.length,
+    pathname: upload.pathname,
+  }, { fetchImpl, headers: authHeaders });
+  const blobUrl = extractBlobUrl(completed) || upload.url;
+  assertPublicBlobUrl(blobUrl, 'completed upload');
+
+  const verifyResponse = await postJson(registryApiUrl(registry, ['publish', 'verify']), { sha256 }, {
+    fetchImpl,
+    headers: authHeaders,
+  });
+  const jobId = extractId(verifyResponse, ['jobId', 'id', 'job']);
+  if (!jobId) throw new Error('Hub verify response did not include a publish job id.');
+  const job = await waitForPublishJob(registry, jobId, {
+    fetchImpl,
+    headers: authHeaders,
+    sleep,
+    pollIntervalMs,
+    maxPollAttempts,
+  });
+
+  const draftPayload = {
+    sha256,
+    slug: flags.slug,
+    version: flags.version,
+    license: flags.license,
+    attested: true,
+    ...(flags.readme !== undefined ? { readme: flags.readme } : {}),
+    ...(flags.sources !== undefined ? { sources: flags.sources } : {}),
+    ...(flags.intendedUse !== undefined ? { intendedUse: flags.intendedUse } : {}),
+  };
+  const draftResponse = await postJson(registryApiUrl(registry, ['publish', 'drafts']), draftPayload, {
+    fetchImpl,
+    headers: authHeaders,
+  });
+  const draftId = extractId(draftResponse, ['draftId', 'id', 'draft']);
+  if (!draftId) throw new Error('Hub draft response did not include a draft id.');
+
+  const releaseResponse = await postJson(registryApiUrl(registry, ['publish', 'drafts', draftId, 'release']), undefined, {
+    fetchImpl,
+    headers: authHeaders,
+  });
+  const name = `${publisher ? `${publisher}/` : ''}${flags.slug}`;
+  const result = {
+    registry,
+    ...(publisher ? { publisher } : {}),
+    name,
+    slug: flags.slug,
+    version: flags.version,
+    sha256,
+    sizeBytes: bytes.length,
+    pathname: upload.pathname,
+    url: blobUrl,
+    jobId: String(jobId),
+    draftId: String(draftId),
+    verification: job,
+    release: releaseResponse,
+  };
+
+  if (flags.json) print(JSON.stringify(result, null, 2));
+  else {
+    print(`published ${name}@${flags.version}`);
+    print(`sha256    ${sha256}`);
+    print(`url       ${blobUrl}`);
+    print(`job       ${jobId}`);
+  }
+  return result;
+}
+
+export async function runHubYank(args, {
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  homeDir,
+  print = console.log,
+} = {}) {
+  const { spec, flags } = parseYankArgs(args);
+  const credentials = await loadCredentials({ env, homeDir });
+  const registry = resolveRegistryUrl({ value: flags.registry || credentials.registry, env });
+  const response = await postJson(registryApiUrl(registry, ['packs', spec.publisher, spec.slug, spec.version, 'yank']), undefined, {
+    fetchImpl,
+    headers: authorizationHeaders(credentials.token),
+  });
+  const result = {
+    registry,
+    name: spec.name,
+    version: spec.version,
+    response,
+  };
+  if (flags.json) print(JSON.stringify(result, null, 2));
+  else print(`yanked ${spec.name}@${spec.version}`);
+  return result;
+}
+
+export function parsePublishArgs(args) {
+  const positional = [];
+  const flags = {};
+  const valueFlags = new Map([
+    ['--slug', 'slug'],
+    ['--version', 'version'],
+    ['--license', 'license'],
+    ['--publisher', 'publisher'],
+    ['--readme', 'readme'],
+    ['--sources', 'sources'],
+    ['--intended-use', 'intendedUse'],
+    ['--registry', 'registry'],
+  ]);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      flags.json = true;
+      continue;
+    }
+    if (valueFlags.has(arg)) {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      flags[valueFlags.get(arg)] = value;
+      continue;
+    }
+    if (arg.startsWith('--')) throw new Error(`Unknown flag for publish: ${arg}`);
+    positional.push(arg);
+  }
+
+  if (positional.length !== 1 || !flags.slug || !flags.version || !flags.license) {
+    throw new Error('Usage: knolo publish <pack.knolo> --slug <slug> --version <version> --license <SPDX> [--publisher <handle>] [--readme <text>] [--sources <text>] [--intended-use <text>] [--json] [--registry <url>]');
+  }
+  if (!/^[a-z0-9-]+$/.test(flags.slug)) throw new Error('Publish slug must contain lowercase letters, numbers, and hyphens.');
+  if (!flags.version.trim() || flags.version.includes('@')) throw new Error('Publish version must be a non-empty version without @.');
+  if (!flags.license.trim()) throw new Error('Publish license is required.');
+  if (flags.publisher && !/^[a-z0-9-]+$/.test(flags.publisher)) throw new Error('Publish publisher must contain lowercase letters, numbers, and hyphens.');
+  return { packPath: positional[0], flags };
+}
+
+export function parseYankArgs(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 yank: ${arg}`);
+    positional.push(arg);
+  }
+  if (positional.length !== 1) throw new Error('Usage: knolo yank <publisher>/<slug>@<version> [--json] [--registry <url>]');
+  const spec = parsePackSpec(positional[0]);
+  if (spec.version === 'latest') throw new Error('Yank requires an exact version: <publisher>/<slug>@<version>.');
+  return { spec, flags };
+}
+
+function authorizationHeaders(token) {
+  return { Authorization: `Bearer ${token}` };
+}
+
+function hubApiUrl(registry, segments) {
+  const url = new URL(registry);
+  url.pathname = `/api/${segments.map((segment) => encodeURIComponent(String(segment))).join('/')}`;
+  return url;
+}
+
+function createSha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function extractPublisherHandle(account) {
+  const candidates = [
+    account?.publisherHandle,
+    account?.publisher?.handle,
+    account?.publisher?.slug,
+    account?.handle,
+    account?.account?.publisherHandle,
+    account?.account?.publisher?.handle,
+    account?.user?.publisherHandle,
+    account?.publishers?.[0]?.handle,
+    account?.publishers?.[0]?.slug,
+    typeof account?.publisher === 'string' ? account.publisher : undefined,
+  ];
+  return candidates.find((value) => typeof value === 'string' && value.trim())?.trim();
+}
+
+function validateUploadTokenResponse(body, sha256) {
+  const upload = body?.upload && typeof body.upload === 'object' ? body.upload : body;
+  if (!upload || typeof upload !== 'object' || typeof upload.url !== 'string' || !upload.url) {
+    if (upload?.clientToken || body?.clientToken) {
+      throw new Error('Hub returned a Blob client token; this CLI requires an upload.url for direct public-Blob PUT.');
+    }
+    throw new Error('Hub upload token response is missing upload.url.');
+  }
+  const pathname = upload.pathname || body?.pathname;
+  if (typeof pathname !== 'string' || !pathname) throw new Error('Hub upload token response is missing upload.pathname.');
+  const expectedPathname = `sha256/${sha256}.knolo`;
+  if (pathname !== expectedPathname) {
+    throw new Error(`Hub upload pathname is not locked to ${expectedPathname}.`);
+  }
+  return { url: upload.url, pathname };
+}
+
+function extractBlobUrl(body) {
+  const candidates = [
+    body?.url,
+    body?.publicUrl,
+    body?.blobUrl,
+    body?.artifact?.url,
+    body?.artifact?.publicUrl,
+    body?.upload?.url,
+    body?.upload?.publicUrl,
+    body?.pack?.url,
+  ];
+  return candidates.find((value) => typeof value === 'string' && value.trim())?.trim();
+}
+
+function assertPublicBlobUrl(value, label) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Hub ${label} URL is invalid.`);
+  }
+  const hostname = url.hostname.toLowerCase();
+  if (url.protocol !== 'https:') throw new Error(`Hub ${label} URL must use HTTPS.`);
+  if (hostname.includes('.private.') || hostname.startsWith('private.')) {
+    throw new Error(`Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`);
+  }
+  return url;
+}
+
+function extractId(body, keys) {
+  for (const key of keys) {
+    const value = body?.[key];
+    if (typeof value === 'string' && value) return value;
+    if (typeof value === 'number' && Number.isSafeInteger(value)) return value;
+    if (value && typeof value === 'object') {
+      if (typeof value.id === 'string' && value.id) return value.id;
+      if (typeof value.id === 'number' && Number.isSafeInteger(value.id)) return value.id;
+      if (typeof value.jobId === 'string' && value.jobId) return value.jobId;
+      if (typeof value.draftId === 'string' && value.draftId) return value.draftId;
+    }
+  }
+  return undefined;
+}
+
+async function waitForPublishJob(registry, jobId, {
+  fetchImpl,
+  headers,
+  sleep: sleepImpl = wait,
+  pollIntervalMs = 1000,
+  maxPollAttempts = 120,
+} = {}) {
+  if (!Number.isSafeInteger(maxPollAttempts) || maxPollAttempts < 1) throw new Error('maxPollAttempts must be a positive integer.');
+  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) throw new Error('pollIntervalMs must be a non-negative number.');
+
+  for (let attempt = 0; attempt < maxPollAttempts; attempt++) {
+    if (attempt > 0 && pollIntervalMs > 0) await sleepImpl(pollIntervalMs);
+    const body = await getJson(registryApiUrl(registry, ['publish', 'jobs', jobId]), { fetchImpl, headers });
+    const job = body?.job && typeof body.job === 'object' ? body.job : body;
+    const status = String(job?.status || job?.state || '').toLowerCase();
+    if (['passed', 'pass', 'complete', 'completed', 'succeeded', 'success'].includes(status)) return job;
+    if (['failed', 'failure', 'error', 'rejected'].includes(status)) {
+      const detail = job?.error || job?.message || body?.error;
+      throw new Error(`Hub publish verification failed${detail ? `: ${detail}` : '.'}`);
+    }
+  }
+
+  throw new Error(`Timed out waiting for Hub publish verification job ${jobId}.`);
+}
+
+function wait(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
 export function parseAddArgs(args) {
@@ -310,17 +636,75 @@ async function validateKnowledgeImage(core, bytes) {
   throw new Error('not a Knowledge Image');
 }
 
-async function copyArtifact(sourcePath, outputPath, cwd) {
+async function stageArtifactCopy(sourcePath, outputPath, cwd) {
   const targetPath = path.resolve(cwd, outputPath);
-  const tempPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
   await mkdir(path.dirname(targetPath), { recursive: true });
+  const tempPath = `${targetPath}.tmp-${process.pid}-${randomUUID()}`;
   try {
     await copyFile(sourcePath, tempPath);
-    await rename(tempPath, targetPath);
-  } finally {
+    await chmod(tempPath, 0o644);
+    return { targetPath, tempPath };
+  } catch (error) {
     await unlinkIfPresent(tempPath);
+    throw error;
+  }
+}
+
+async function commitStagedFiles(entries) {
+  const targets = new Set();
+  const records = entries.map((entry) => {
+    if (targets.has(entry.targetPath)) throw new Error(`Install paths must be unique: ${entry.targetPath}`);
+    targets.add(entry.targetPath);
+    return {
+      ...entry,
+      backupPath: `${entry.targetPath}.backup-${process.pid}-${randomUUID()}`,
+      hadOriginal: false,
+      committed: false,
+    };
+  });
+
+  try {
+    for (const record of records) {
+      const existing = await statIfPresent(record.targetPath);
+      if (existing?.isDirectory()) throw new Error(`Cannot replace directory at ${record.targetPath}.`);
+    }
+
+    for (const record of records) {
+      if (await pathExists(record.targetPath)) {
+        record.hadOriginal = true;
+        await rename(record.targetPath, record.backupPath);
+      }
+      await rename(record.tempPath, record.targetPath);
+      record.committed = true;
+    }
+
+  } catch (error) {
+    for (const record of [...records].reverse()) {
+      if (record.committed) await unlinkIfPresent(record.targetPath);
+      if (record.hadOriginal && await pathExists(record.backupPath)) {
+        await unlinkIfPresent(record.targetPath);
+        await rename(record.backupPath, record.targetPath);
+      }
+    }
+    throw error;
+  }
+
+  for (const record of records) {
+    if (record.hadOriginal) await unlinkIfPresent(record.backupPath).catch(() => {});
+  }
+}
+
+async function statIfPresent(filePath) {
+  try {
+    return await lstat(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw error;
   }
-  return targetPath;
+}
+
+async function pathExists(filePath) {
+  return Boolean(await statIfPresent(filePath));
 }
 
 async function unlinkIfPresent(filePath) {

package/bin/registry/errors.mjs

@@ -18,8 +18,10 @@ export class RegistryNetworkError extends Error {
 }
 
 export function registryErrorMessage({ status, code, body, url }) {
+  if (status === 401 || code === 'unauthenticated') {
+    return 'Hub authentication failed. Use Authorization: Bearer kno_…; a revoked token can also return 401. GitHub sign-in is only required to mint tokens.';
+  }
   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.';

package/bin/registry/http.mjs

@@ -1,14 +1,50 @@
 import { RegistryError, RegistryNetworkError, registryErrorMessage } from './errors.mjs';
 
 export async function getJson(url, { fetchImpl = globalThis.fetch, headers = {} } = {}) {
+  return requestJson(url, { fetchImpl, headers, method: 'GET' });
+}
+
+export async function postJson(url, body, { fetchImpl = globalThis.fetch, headers = {} } = {}) {
+  return requestJson(url, { fetchImpl, headers, method: 'POST', body });
+}
+
+export async function putBytes(url, bytes, { 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: 'PUT',
+      redirect: 'follow',
+      headers: { 'content-type': 'application/octet-stream', ...headers },
+      body: bytes,
+    });
+  } catch (error) {
+    throw new RegistryNetworkError(`Could not upload artifact to ${new URL(url).origin}.`, { url: String(url), cause: error });
+  }
+
+  if (!response.ok) {
+    const detail = await readResponseText(response, url);
+    throw new RegistryError(`Blob upload failed with HTTP ${response.status}${detail ? `: ${detail}` : '.'}`, {
+      status: response.status,
+      url: String(url),
+      body: detail,
+    });
+  }
+
+  return { status: response.status, url: response.url || String(url) };
+}
+
+async function requestJson(url, { fetchImpl = globalThis.fetch, headers = {}, method = 'GET', body: requestBody } = {}) {
   if (typeof fetchImpl !== 'function') throw new Error('This Node runtime does not provide fetch.');
 
   let response;
   try {
     response = await fetchImpl(url, {
-      method: 'GET',
+      method,
       redirect: 'follow',
-      headers: { accept: 'application/json', ...headers },
+      headers: { accept: 'application/json', ...(requestBody !== undefined ? { 'content-type': 'application/json' } : {}), ...headers },
+      ...(requestBody !== undefined ? { body: JSON.stringify(requestBody) } : {}),
     });
   } catch (error) {
     throw new RegistryNetworkError(`Could not reach registry at ${new URL(url).origin}.`, { url: String(url), cause: error });

package/bin/registry/lockfile.mjs

@@ -37,13 +37,23 @@ export async function validateLockfileUpdate({ cwd = process.cwd(), registry, ma
 }
 
 export async function upsertLockfile({ cwd = process.cwd(), registry, manifest, force = false } = {}) {
+  const staged = await stageLockfileUpdate({ cwd, registry, manifest, force });
+  try {
+    await rename(staged.tempPath, staged.path);
+  } finally {
+    await unlink(staged.tempPath).catch(() => {});
+  }
+  return { path: staged.path, entry: staged.entry };
+}
+
+export async function stageLockfileUpdate({ 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 };
+  const tempPath = await writeJsonTemp(targetPath, next);
+  return { path: targetPath, tempPath, entry };
 }
 
 async function readLockfile(filePath) {
@@ -66,13 +76,14 @@ async function readLockfile(filePath) {
   return value;
 }
 
-async function atomicWriteJson(filePath, value) {
+async function writeJsonTemp(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 {
+    return tempPath;
+  } catch (error) {
     await unlink(tempPath).catch(() => {});
+    throw error;
   }
 }

package/bin/registry/manifest.mjs

@@ -20,6 +20,12 @@ export function validatePackManifest(value, { expectedName, requestedVersion } =
   if (value.stateRoot !== undefined && typeof value.stateRoot !== 'string') {
     throw new Error('Registry manifest stateRoot must be a string when present.');
   }
+  if (value.format !== undefined && !['V4', 'V5'].includes(value.format)) {
+    throw new Error('Registry manifest format must be V4 or V5 when present.');
+  }
+  if (value.format === 'V5' && (!value.stateRoot || typeof value.stateRoot !== 'string')) {
+    throw new Error('Registry manifest stateRoot is required for V5 manifests.');
+  }
   if (value.license !== undefined && typeof value.license !== 'string') {
     throw new Error('Registry manifest license must be a string when present.');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/cli",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"