package-manager 0.0.1-preview.1

The Zena package manager's libraries: manifests, version selection, lockfiles, archives and the registry client

Readme Files Dependencies Versions

package-manager#

Client libraries for Zena packages published on AT Protocol: package manifests (zena-package.json), lockfiles (zena-lock.json), deterministic CAR source archives, dependency resolution, and registry queries. Versions and ranges are the package zena-lang:semver (packages/semver).

Usage#

import {readManifest} from 'package-manager/manifest';
import {Range} from 'zena-lang:semver';

let manifest = readManifest('{"name": "hello", "version": "1.0.0"}');
let version = manifest.version;
let matches = version != null && Range.parse('^1.0.0').includes(version);

Libraries#

  • package-manager/manifest: reading a package's zena-package.json, and rewriting its dependencies while keeping the rest of the file.
  • package-manager/workspace: a workspace's packages, read from disk: the root's manifest, the packages it lists, and the ones they depend on by path.
  • package-manager/files: which files a package publishes: its manifest's files patterns, or by default every file but tests, and always the manifest, README, and license, never hidden files, node_modules, or the lockfile.
  • package-manager/archive: source archives, the CAR files that hold a release's source. Packing is deterministic, so the same files always have the same CID, and unpacking accepts only what packing writes.
  • package-manager/records: the profile, release, retraction, and maintainers records, an organization's members record, and the private membership entries it commits to, read from the atproto data model with the checks their lexicons describe, and written back. Also the rules for package names.
  • package-manager/registry-methods: the NSIDs of the App View's XRPC methods.
  • package-manager/registry: finding packages: resolving a DID, a handle, or scope:name to a DID, a package's versions and retractions, its profile, and its releases with their proofs.
  • package-manager/resolve: version selection, from the ranges in all of a workspace's manifests to what its lockfile pins, installing as few versions of each package as the ranges allow.
  • package-manager/resolution: the packages a workspace's lockfile, zena-lock.json, pins, writing it, and what writing it changes in the pins already there (diffPins), including releases changed in place.
  • package-manager/cache: the package cache, where each source archive is unpacked into sources/<CID> for the compiler to read.
  • package-manager/fetch: fetching pinned packages into the cache. The release record's proof is checked against the account's signing key, the record and the source archive against the CIDs the lockfile pins, and the release's dependencies against the names it maps.
  • package-manager/validate: checking a package directory and its manifest before publishing.
  • package-manager/testing/fake-pds: an in-process PLC directory, DNS-over-HTTPS resolver, and PDS for package accounts, for testing code that finds and fetches packages.
8.3 KiB Raw
/**
 * Source archives: the CAR files that hold a release's `source` artifact
 * (docs/design/package-manager.md, "Source archives").
 *
 * The archive's one root is a DAG-CBOR map,
 * `{$type: "dev.zena-lang.package.tree", files: {path: cid}}`, and each
 * file's contents are a raw block. Packing is deterministic: the same
 * files give the same bytes, and so the same CID, in whatever order they
 * are given. The root comes first, then the files' blocks in the order the
 * root lists them, and contents two files share are stored once.
 *
 * Unpacking accepts only what packing produces, apart from keys the root
 * map may gain later: one root, every file's block present and raw, valid
 * paths, and no block the root does not name.
 */

import {HashMap, HashSet} from 'zena:collections';
import {BlockMap, Car, readCar, writeCar} from 'atproto/car';
import {decodeCbor, sortedKeys} from 'atproto/cbor';
import {CODEC_DAG_CBOR, CODEC_RAW, Cid} from 'atproto/cid';
import {LinkValue, MapValue, StringValue, Value, field, newMap} from 'atproto/data';

export let TREE_TYPE = 'dev.zena-lang.package.tree';

/** The most files a source archive may hold. */
export let MAX_ARCHIVE_FILES = 10000;

/**
 * The most bytes a source archive's files may take together, counting a
 * file once for each path that names it. Contents two paths share are
 * stored once, so without this an archive of a few megabytes could name
 * one block from every path and take gigabytes to write out.
 */
export let MAX_UNPACKED_BYTES = 64 * 1024 * 1024;

/** An archive that cannot be packed or unpacked. */
export class ArchiveError extends Error {
  new(message: String) : super(message);
}

/** A file in a source archive. */
export final class SourceFile {
  /** The path from the package root, with `/` between directories. */
  path: String;
  /** The raw CID of the contents. */
  cid: Cid;
  contents: FixedArray<u8>;
  /** Where the contents start in the archive's bytes. */
  offset: i32;

  new(this.path, this.cid, this.contents, this.offset);
}

/**
 * Whether `path` can name a file in a source archive: at most 1,024 bytes
 * of ASCII letters, digits, `.`, `_`, `-` and `/`, where `/` separates
 * non-empty names that are not `.` or `..`. Every such path is also a
 * valid relative path on Windows, macOS and Linux.
 */
export function isValidSourcePath(path: String): boolean {
  if (path.length == 0 || path.length > 1024) {
    return false;
  }
  var segmentStart = 0;
  for (var i = 0; i <= path.length; i += 1) {
    if (i == path.length || path.getByteAt(i) == 47) { // '/'
      let segment = path.sliceBytes(segmentStart, i);
      if (segment.length == 0 || segment == '.' || segment == '..') {
        return false;
      }
      segmentStart = i + 1;
    } else {
      let b = path.getByteAt(i);
      let allowed = (b >= 48 && b <= 57) || (b >= 65 && b <= 90) || (b >= 97 && b <= 122) ||
          b == 46 || b == 95 || b == 45;
      if (!allowed) {
        return false;
      }
    }
  }
  return true;
}

/**
 * Packs `files`, from path to contents, into a source archive. Throws
 * `ArchiveError` for an invalid path, for two paths that differ only in
 * case, for a path that is also another's directory, and for more files
 * or bytes than an archive may hold.
 */
export function packSource(files: HashMap<String, FixedArray<u8>>): FixedArray<u8> {
  checkFileCount(files.size);
  let paths = new GrowableArray<String>();
  var unpacked = 0;
  for (let path in files.keys()) {
    paths.push(path);
    unpacked = addUnpacked(unpacked, files[path].length);
  }
  checkPaths(paths);

  let blocks = new BlockMap();
  let tree = newMap();
  files.forEach((path, contents) => {
    let cid = Cid.forBlob(contents);
    blocks.set(cid, contents);
    tree.entries[path] = new LinkValue(cid);
  });
  let root = newMap();
  root.entries['$type'] = new StringValue(TREE_TYPE);
  root.entries['files'] = tree;
  let rootCid = blocks.add(root);

  let order = new FixedArray<Cid>(blocks.size, rootCid);
  let written = new HashSet<String>();
  var n = 1;
  for (let path in sortedKeys(tree.entries)) {
    let cid = (tree.entries[path] as LinkValue).cid;
    if (!written.has(cid.toString())) {
      written.add(cid.toString());
      order[n] = cid;
      n += 1;
    }
  }
  return writeCar(fixedOf(rootCid), blocks, order);
}

/**
 * Unpacks a source archive into its files, in the order its root lists
 * them. Throws `ArchiveError` for anything `packSource` would not have
 * written.
 */
export function unpackSource(bytes: FixedArray<u8>): FixedArray<SourceFile> {
  let car = readCarOrThrow(bytes);
  if (car.roots.length != 1) {
    throw new ArchiveError(`the archive has ${car.roots.length} roots, not one`);
  }
  let rootCid = car.roots[0];
  if (rootCid.codec != CODEC_DAG_CBOR) {
    throw new ArchiveError('the root is not a DAG-CBOR block');
  }
  let rootBytes = car.blocks.get(rootCid);
  if (rootBytes == null) {
    throw new ArchiveError('the archive has no root block');
  }
  let root = decodeOrThrow(rootBytes);
  if (!(root is MapValue)) {
    throw new ArchiveError('the root is not a map');
  }
  let type = field(root, '$type');
  if (!(type is StringValue) || type.value != TREE_TYPE) {
    throw new ArchiveError(`the root's $type is not '${TREE_TYPE}'`);
  }
  let tree = field(root, 'files');
  if (!(tree is MapValue)) {
    throw new ArchiveError('the root has no map of files');
  }
  checkFileCount(tree.entries.size);

  let paths = sortedKeys(tree.entries);
  checkPaths(paths);
  let used = new HashSet<String>();
  used.add(rootCid.toString());
  let files = new FixedArray<SourceFile>(paths.length, new SourceFile('', rootCid, rootBytes, 0));
  var unpacked = 0;
  for (var i = 0; i < paths.length; i += 1) {
    let path = paths[i];
    let link = tree.entries[path];
    if (!(link is LinkValue)) {
      throw new ArchiveError(`'${path}' is not a link`);
    }
    if (link.cid.codec != CODEC_RAW) {
      throw new ArchiveError(`'${path}' is not a link to a raw block`);
    }
    let contents = car.blocks.get(link.cid);
    if (contents == null) {
      throw new ArchiveError(`the archive has no block for '${path}'`);
    }
    unpacked = addUnpacked(unpacked, contents.length);
    used.add(link.cid.toString());
    files[i] = new SourceFile(path, link.cid, contents, car.offsetOf(link.cid));
  }
  if (used.size != car.blocks.size) {
    throw new ArchiveError(`the archive has ${car.blocks.size - used.size} blocks its root does not name`);
  }
  return files;
}

/**
 * Checks that each path is valid, that no two differ only in case, and
 * that none is also a directory of another. An archive that broke these
 * could not be written out on every file system.
 */
function checkPaths(paths: Array<String>): void {
  let folded = new HashSet<String>();
  for (let path in paths) {
    if (!isValidSourcePath(path)) {
      throw new ArchiveError(`'${path}' is not a valid source path`);
    }
    let key = path.asciiLowerCase();
    if (folded.has(key)) {
      throw new ArchiveError(`'${path}' is a second file with that name, ignoring case`);
    }
    folded.add(key);
  }
  for (let path in paths) {
    let key = path.asciiLowerCase();
    for (var i = 0; i < key.length; i += 1) {
      if (key.getByteAt(i) == 47 && folded.has(key.sliceBytes(0, i))) {
        throw new ArchiveError(`'${path}' is inside '${path.sliceBytes(0, i)}', which is a file`);
      }
    }
  }
}

function checkFileCount(count: i32): void {
  if (count > MAX_ARCHIVE_FILES) {
    throw new ArchiveError(`${count} files are more than the ${MAX_ARCHIVE_FILES} an archive may hold`);
  }
}

/**
 * `total + length`, or `ArchiveError` when the sum would be more than
 * `MAX_UNPACKED_BYTES`. `total` never is, so the subtraction cannot
 * overflow where the sum could.
 */
function addUnpacked(total: i32, length: i32): i32 {
  if (length > MAX_UNPACKED_BYTES - total) {
    throw new ArchiveError(`the files take more than the ${MAX_UNPACKED_BYTES} bytes an archive may unpack to`);
  }
  return total + length;
}

function readCarOrThrow(bytes: FixedArray<u8>): Car {
  try {
    return readCar(bytes);
  } catch (e) {
    throw new ArchiveError(`the archive is not a valid CAR file: ${e.message}`);
  }
}

function decodeOrThrow(bytes: FixedArray<u8>): Value {
  try {
    return decodeCbor(bytes);
  } catch (e) {
    throw new ArchiveError(`the root is not valid DAG-CBOR: ${e.message}`);
  }
}

function fixedOf(cid: Cid): FixedArray<Cid> {
  return new FixedArray<Cid>(1, cid);
}
  • atproto atproto.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
  • zena-lang:semver semver.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19
  • atproto atproto.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
  • zena-lang:semver semver.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1