@knolo/cli 5.2.0 → 5.2.2

package/bin/registry/commands.mjs

@@ -1,18 +1,60 @@
-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 { isIP } from 'node:net';
 import { homedir } from 'node:os';
 import path from 'node:path';
-import { registryApiUrl, resolveRegistryUrl } from './config.mjs';
-import { downloadBlobToTemp, installCachedArtifact, readArtifact } from './artifacts.mjs';
+import { put as putBlob } from '@vercel/blob';
+import {
+  normalizeRegistryUrl,
+  registryApiUrl,
+  resolveRegistryUrl,
+} from './config.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 } 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';
+import {
+  loadCredentials,
+  promptForToken,
+  removeCredentials,
+  saveCredentials,
+  validateToken,
+} from './credentials.mjs';
 
 const PACK_SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const LOCAL_ONLY_HOSTNAMES = new Set([
+  'localhost',
+  'localhost.localdomain',
+  'ip6-localhost',
+  'ip6-loopback',
+  'broadcasthost',
+  'local',
+  'internal',
+]);
 
-export async function runHubSearch(args, { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}) {
+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'], {
@@ -31,7 +73,10 @@ export async function runHubSearch(args, { env = process.env, fetchImpl = global
   return { registry, url: String(url), body };
 }
 
-export async function runHubInfo(args, { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}) {
+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 });
@@ -45,31 +90,52 @@ export async function runHubInfo(args, { env = process.env, fetchImpl = globalTh
   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,
-} = {}) {
+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.');
+  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]);
+  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 });
+    manifest = validatePackManifest(body, {
+      expectedName: spec.name,
+      requestedVersion: spec.version,
+    });
   } catch (error) {
-    if (error instanceof RegistryError && (error.status === 404 || error.code === 'not_found')) {
+    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 });
+    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;
@@ -77,10 +143,15 @@ export async function runHubAdd(args, {
   }
 
   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 (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');
+  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 });
@@ -91,26 +162,61 @@ 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}`);
+      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.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'}`);
+    if (validation.format === 'V5' && !manifest.stateRoot) {
+      throw new Error('V5 artifact requires manifest stateRoot.');
     }
-    const cache = await installCachedArtifact(download.tempPath, finalCachePath);
-    installed = true;
-    const lock = await upsertLockfile({ cwd, registry, manifest, force: flags.force });
-    let outputPath = cache;
+    if (
+      manifest.stateRoot !== undefined &&
+      manifest.stateRoot !== validation.stateRoot
+    ) {
+      throw new Error(
+        `artifact stateRoot mismatch: expected ${manifest.stateRoot}, got ${validation.stateRoot || 'none'}`
+      );
+    }
+    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,29 +227,44 @@ 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))
+    );
   }
 }
 
-export async function runHubLogin(args, {
-  env = process.env,
-  homeDir,
-  input = process.stdin,
-  output = process.stderr,
-  print = console.log,
-} = {}) {
+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();
+  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}`);
+  print('Authorization: Bearer kno_…');
   return saved;
 }
 
-export async function runHubWhoami(args, { env = process.env, homeDir, print = console.log } = {}) {
+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}`);
@@ -151,15 +272,553 @@ export async function runHubWhoami(args, { env = process.env, homeDir, print = c
   return { registry: credentials.registry, prefix: credentials.prefix };
 }
 
-export async function runHubLogout(args, { env = process.env, homeDir, print = console.log } = {}) {
+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 async function runHubPublish(
+  args,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    cwd = process.cwd(),
+    homeDir,
+    print = console.log,
+    sleep = wait,
+    putImpl = putBlob,
+    pollIntervalMs = 1000,
+    maxPollAttempts = 120,
+  } = {}
+) {
+  const { packPath, flags } = parsePublishArgs(args);
+  const credentials = await loadCredentials({ env, homeDir });
+  const registry = resolveCredentialRegistry(
+    flags.registry,
+    credentials.registry
+  );
+  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 pathname = `sha256/${sha256}.knolo`;
+
+  const uploaded = await putImpl(pathname, bytes, {
+    access: 'public',
+    addRandomSuffix: false,
+    // The pathname is content-addressed by the already-computed SHA-256.
+    // Allowing overwrite makes a retry safe after a partial Hub publish.
+    allowOverwrite: true,
+    contentType: 'application/octet-stream',
+    cacheControlMaxAge: 31536000,
+    token: packsReadWriteToken(env),
+  });
+  if (!uploaded || typeof uploaded.url !== 'string' || !uploaded.url) {
+    throw new Error('Public Blob upload did not return a URL.');
+  }
+  if (uploaded.pathname !== undefined && uploaded.pathname !== pathname) {
+    throw new Error(
+      `Public Blob upload pathname is not locked to ${pathname}.`
+    );
+  }
+  const blobUrl = assertPublicBlobUrl(
+    uploaded.url,
+    'uploaded artifact'
+  ).toString();
+
+  await postJson(
+    hubApiUrl(registry, ['upload', 'complete']),
+    {
+      sha256,
+      url: blobUrl,
+      sizeBytes: bytes.length,
+      pathname,
+    },
+    { fetchImpl, headers: authHeaders }
+  );
+
+  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,
+    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 = resolveCredentialRegistry(
+    flags.registry,
+    credentials.registry
+  );
+  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 resolveCredentialRegistry(requestedRegistry, storedRegistry) {
+  const stored = normalizeRegistryUrl(storedRegistry);
+  if (!requestedRegistry) return stored;
+  const requested = normalizeRegistryUrl(requestedRegistry);
+  if (requested !== stored) {
+    throw new Error(
+      `Stored credentials belong to ${stored}; refusing to send them to ${requested}. Log in to the requested registry first.`
+    );
+  }
+  return requested;
+}
+
+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 packsReadWriteToken(env) {
+  const token =
+    typeof env?.PACKS_READ_WRITE_TOKEN === 'string'
+      ? env.PACKS_READ_WRITE_TOKEN.trim()
+      : '';
+  if (!token)
+    throw new Error(
+      'PACKS_READ_WRITE_TOKEN is required for public Blob uploads.'
+    );
+  return token;
+}
+
+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 assertPublicBlobUrl(value, label) {
+  if (typeof value !== 'string' || value.includes('.private.')) {
+    throw new Error(
+      `Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
+  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.') ||
+    isPrivateOrLocalIp(hostname)
+  ) {
+    throw new Error(
+      `Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
+  if (isLocalOnlyHostname(hostname)) {
+    throw new Error(
+      `Refusing local-only Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
+  return url;
+}
+
+function isLocalOnlyHostname(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  return (
+    LOCAL_ONLY_HOSTNAMES.has(normalized) ||
+    normalized.endsWith('.localhost') ||
+    normalized.endsWith('.local') ||
+    normalized.endsWith('.internal') ||
+    normalized.endsWith('.home.arpa')
+  );
+}
+
+function isPrivateOrLocalIp(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, '');
+  const version = isIP(normalized);
+  if (version === 4) return isPrivateIpv4(normalized);
+  if (version !== 6) return false;
+
+  const words = parseIpv6Words(normalized);
+  if (!words) return false;
+  const first = words[0];
+  const allZero = words.every((word) => word === 0);
+  const loopback =
+    words.slice(0, 7).every((word) => word === 0) && words[7] === 1;
+  const uniqueLocal = (first & 0xfe00) === 0xfc00;
+  const linkLocal = (first & 0xffc0) === 0xfe80;
+  const mappedIpv4 =
+    words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff;
+  const mappedAddress = mappedIpv4
+    ? `${words[6] >> 8}.${words[6] & 0xff}.${words[7] >> 8}.${words[7] & 0xff}`
+    : undefined;
+  return (
+    allZero ||
+    loopback ||
+    uniqueLocal ||
+    linkLocal ||
+    (mappedAddress ? isPrivateIpv4(mappedAddress) : false)
+  );
+}
+
+function isPrivateIpv4(value) {
+  const octets = value.split('.').map(Number);
+  if (
+    octets.length !== 4 ||
+    octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)
+  )
+    return false;
+  const [first, second] = octets;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && (second === 0 || second === 168)) ||
+    (first === 198 && (second === 18 || second === 19)) ||
+    first >= 224
+  );
+}
+
+function parseIpv6Words(value) {
+  const sections = value.toLowerCase().split('::');
+  if (sections.length > 2) return undefined;
+  const left = parseIpv6Section(sections[0]);
+  const right = sections.length === 2 ? parseIpv6Section(sections[1]) : [];
+  if (!left || !right) return undefined;
+  const zeroCount = sections.length === 2 ? 8 - left.length - right.length : 0;
+  if (
+    zeroCount < (sections.length === 2 ? 1 : 0) ||
+    left.length + right.length + zeroCount !== 8
+  )
+    return undefined;
+  return [...left, ...new Array(zeroCount).fill(0), ...right];
+}
+
+function parseIpv6Section(section) {
+  if (!section) return [];
+  const words = [];
+  for (const part of section.split(':')) {
+    if (part.includes('.')) {
+      const octets = part.split('.').map(Number);
+      if (
+        octets.length !== 4 ||
+        octets.some(
+          (octet) => !Number.isInteger(octet) || octet < 0 || octet > 255
+        )
+      )
+        return undefined;
+      words.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+    } else {
+      if (!/^[0-9a-f]{1,4}$/.test(part)) return undefined;
+      words.push(Number.parseInt(part, 16));
+    }
+  }
+  return words;
+}
+
+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) {
@@ -173,14 +832,18 @@ export function parseAddArgs(args) {
     }
     if (['--out', '--registry'].includes(arg)) {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      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>]');
+  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 };
 }
 
@@ -194,12 +857,15 @@ export function parseLoginArgs(args) {
     }
     if (arg === '--token' || arg === '--registry') {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      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>]');
+    throw new Error(
+      'Usage: knolo login [--token kno_…] [--stdin] [--registry <url>]'
+    );
   }
   return { flags };
 }
@@ -237,17 +903,25 @@ export function parseSearchArgs(args) {
     }
     if (['--format', '--license', '--registry'].includes(arg)) {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      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}`);
+    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())) {
+  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();
@@ -265,14 +939,18 @@ export function parseInfoArgs(args) {
     }
     if (arg === '--registry') {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error('Missing value for --registry');
+      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>]');
+  if (positional.length !== 1)
+    throw new Error(
+      'Usage: knolo info <publisher>/<slug> [--json] [--registry <url>]'
+    );
   return { positional, flags };
 }
 
@@ -283,7 +961,13 @@ function validatePacksResponse(body) {
 }
 
 function validatePackInfoResponse(body) {
-  if (!body || typeof body !== 'object' || typeof body.name !== 'string' || !body.pack || typeof body.pack !== 'object') {
+  if (
+    !body ||
+    typeof body !== 'object' ||
+    typeof body.name !== 'string' ||
+    !body.pack ||
+    typeof body.pack !== 'object'
+  ) {
     throw new Error('Registry returned an invalid pack response.');
   }
 }
@@ -294,33 +978,100 @@ async function validateKnowledgeImage(core, bytes) {
       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)}`);
+      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);
+  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(
+        `invalid V4 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
   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(() => {});
   }
-  return targetPath;
+}
+
+async function statIfPresent(filePath) {
+  try {
+    return await lstat(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+async function pathExists(filePath) {
+  return Boolean(await statIfPresent(filePath));
 }
 
 async function unlinkIfPresent(filePath) {
@@ -334,24 +1085,36 @@ async function unlinkIfPresent(filePath) {
 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 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();
+  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');
 }