@knolo/cli 5.1.0 → 5.2.1

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,30 @@
+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 (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 === 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,94 @@
+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,
+      redirect: 'follow',
+      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 });
+  }
+
+  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,89 @@
+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 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 },
+  };
+  const tempPath = await writeJsonTemp(targetPath, next);
+  return { path: targetPath, tempPath, 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 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 });
+    return tempPath;
+  } catch (error) {
+    await unlink(tempPath).catch(() => {});
+    throw error;
+  }
+}

package/bin/registry/manifest.mjs

@@ -0,0 +1,47 @@
+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.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.');
+  }
+  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.1",
   "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"