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.
13.2 KiB Raw
/**
 * The packages a workspace pins: the `resolved` section of its lockfile
 * (docs/design/package-manifest.md, "zena-lock.json"), keyed by DID and
 * version. `zena pkg fetch` fetches them, and the compiler reads them from
 * the package cache. The `workspace` section gives the pin each workspace
 * package's names stand for, by the package's directory.
 *
 * `writeLockfile` writes a `Resolution` as `zena-lock.json`, and
 * `diffPins` sorts what writing it changes in the pins already there.
 *
 * ```json
 * {
 *   "lockfileVersion": 1,
 *   "workspace": {".": {"router": "did:plc:...@1.4.2"}},
 *   "resolved": {
 *     "did:plc:...@1.4.2": {
 *       "release": "bafyrei...",
 *       "source": "bafkrei...",
 *       "dependencies": {"json": "did:web:json.example.com@2.1.0"}
 *     }
 *   }
 * }
 * ```
 */

import {HashMap, HashSet, OrderedHashMap} from 'zena:collections';
import {JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {CODEC_DAG_CBOR, CODEC_RAW, Cid} from 'atproto/cid';
import {isValidCidSyntax, isValidDid} from 'atproto/syntax';
import {Range, Version} from 'zena-lang:semver';
import {parsePackageVersion} from './records.zena';

/**
 * The version of the lockfile's format, which `writeLockfile` writes as
 * `lockfileVersion` and `readPins` requires. It is the format's own
 * number, unrelated to any package's version. The compiler reads
 * lockfiles too (`LOCKFILE_VERSION` in `compiler/package-manifest`),
 * so a change to the format raises both, and
 * `packages/cli/tests/lockfile-version_test.zena` checks they agree.
 */
export let LOCKFILE_VERSION = 1;

/** A lockfile whose pins cannot be read. */
export class ResolutionError extends Error {
  new(message: String) : super(message);
}

/** How a lockfile names a version of a package: `did:plc:...@1.4.2`. */
export function packageKey(did: String, version: Version): String {
  return `${did}@${version.toString()}`;
}

/** A package a lockfile pins. */
export final class Pin {
  /** The package's DID and version, `did:plc:...@1.4.2`. */
  key: String;
  did: String;
  version: Version;
  /** The CID of the release record. */
  release: Cid;
  /** The raw CID of the release's source archive. */
  source: Cid;
  /** The local names the package's own imports use, each mapped to a pinned package's key. */
  dependencies: HashMap<String, String>;

  new(key: String, did: String, version: Version, release: Cid, source: Cid,
      dependencies: HashMap<String, String>)
      : key = key, did = did, version = version, release = release, source = source,
        dependencies = dependencies;
}

/**
 * The packages the lockfile `text` pins, in the order it lists
 * them; none when it has no `resolved` section. Throws `ResolutionError`
 * for a lockfile of another `lockfileVersion`, or none, and for a pin that
 * cannot be fetched as written.
 */
export function readPins(text: String): GrowableArray<Pin> {
  var json: JsonValue = null;
  try {
    json = parseJson(text);
  } catch (e) {
    throw new ResolutionError(`zena-lock.json is not JSON: ${e.message}`);
  }
  if (!(json is JsonObject)) {
    throw new ResolutionError('zena-lock.json is not an object');
  }
  let root = json;
  checkVersion(root['lockfileVersion']);
  let pins = new GrowableArray<Pin>();
  let resolved = root['resolved'];
  if (resolved == null) {
    return pins;
  }
  if (!(resolved is JsonObject)) {
    throw new ResolutionError('the "resolved" section of zena-lock.json is not an object');
  }
  resolved.forEach((key, value) => {
    pins.push(readPin(key, value));
  });
  return pins;
}

/**
 * Throws `ResolutionError` unless `value`, a lockfile's `lockfileVersion`,
 * is `LOCKFILE_VERSION`: a newer one asks for a newer `zena`, and an older
 * one, or none, for the lockfile to be written again.
 */
function checkVersion(value: JsonValue): void {
  let again = 'delete it and run zena pkg update to write it again';
  if (value == null) {
    throw new ResolutionError(`zena-lock.json has no "lockfileVersion": ${again}`);
  }
  if (!(value is Box<f64>) || value.value != ((value.value as i32) as f64) || value.value < 1.0) {
    throw new ResolutionError('the "lockfileVersion" of zena-lock.json is not a whole number of at least 1');
  }
  let version = value.value as i32;
  if (version > LOCKFILE_VERSION) {
    throw new ResolutionError(
        `zena-lock.json is lockfile version ${version}, newer than the ${LOCKFILE_VERSION} this zena reads: upgrade zena`);
  }
  if (version < LOCKFILE_VERSION) {
    throw new ResolutionError(
        `zena-lock.json is lockfile version ${version}, older than the ${LOCKFILE_VERSION} this zena reads: ${again}`);
  }
}

function readPin(key: String, value: JsonValue): Pin {
  var at = -1;
  for (var i = 0; i < key.length; i += 1) {
    if (key.getByteAt(i) == 64) { // '@'
      at = i;
    }
  }
  let did = if (at < 0) key else key.sliceBytes(0, at);
  if (at < 0 || !isValidDid(did)) {
    throw new ResolutionError(`'${key}' is not a DID and version, such as did:plc:example@1.4.2`);
  }
  if (!(value is JsonObject)) {
    throw new ResolutionError(`${key} is not an object`);
  }
  let entry = value;
  let version = parseVersion(key.sliceBytes(at + 1, key.length), key);
  let release = cidMember(entry, 'release', key);
  if (release.codec != CODEC_DAG_CBOR) {
    throw new ResolutionError(`${key}: release ${release.toString()} is not the CID of a record`);
  }
  let source = cidMember(entry, 'source', key);
  if (source.codec != CODEC_RAW) {
    throw new ResolutionError(`${key}: source ${source.toString()} is not the raw CID of a blob`);
  }

  let dependencies = new HashMap<String, String>();
  let names = entry['dependencies'];
  if (names != null) {
    if (!(names is JsonObject)) {
      throw new ResolutionError(`${key}: dependencies is not an object`);
    }
    names.forEach((name, target) => {
      if (!(target is String)) {
        throw new ResolutionError(`${key}: dependency '${name}' is not a string`);
      }
      dependencies[name] = target;
    });
  }
  return new Pin(key, did, version, release, source, dependencies);
}

function member(entry: JsonObject, name: String, key: String): String {
  let value = entry[name];
  if (!(value is String)) {
    throw new ResolutionError(`${key} has no "${name}" string`);
  }
  return value;
}

function cidMember(entry: JsonObject, name: String, key: String): Cid {
  let text = member(entry, name, key);
  if (!isValidCidSyntax(text)) {
    throw new ResolutionError(`${key}: ${name} '${text}' is not a CID`);
  }
  return Cid.parse(text);
}

function parseVersion(text: String, key: String): Version {
  try {
    return parsePackageVersion(text);
  } catch (e) {
    throw new ResolutionError(`${key}: ${e.message}`);
  }
}

/** A published package as the lockfile pins it. */
export final class ResolvedPackage {
  /** The package's DID and version, `did:plc:...@1.4.2`. */
  key: String;
  did: String;
  version: Version;
  /** The CID of the release record. */
  release: Cid;
  /** The raw CID of the source archive. */
  source: Cid;
  /** The release's names for its dependencies, each mapped to a package's key. */
  dependencies: OrderedHashMap<String, String>;

  new(key: String, did: String, version: Version, release: Cid, source: Cid,
      dependencies: OrderedHashMap<String, String>)
      : key = key, did = did, version = version, release = release, source = source,
        dependencies = dependencies;
}

/** What selection chose for a workspace. */
export final class Resolution {
  /** The selected packages, by key. */
  packages: OrderedHashMap<String, ResolvedPackage>;

  new(packages: OrderedHashMap<String, ResolvedPackage>) : packages = packages;

  /**
   * The key of the version selected for a dependency on `did` with
   * `range`: the highest selected version of `did` in the range, or null
   * when none is.
   */
  keyOf(did: String, range: Range): String | null {
    var found: ResolvedPackage | null = null;
    for (let key in this.packages.keys()) {
      let pkg = this.packages[key];
      if (pkg.did == did && range.includes(pkg.version)) {
        let current = found;
        if (current == null || pkg.version.compareTo(current.version) > 0) {
          found = pkg;
        }
      }
    }
    return found?.key;
  }

  /** Each package selected at more than one version, with its versions in order. */
  duplicates(): OrderedHashMap<String, GrowableArray<Version>> {
    let byPackage = new OrderedHashMap<String, GrowableArray<Version>>();
    for (let key in this.packages.keys()) {
      let pkg = this.packages[key];
      if (let (true, versions) = byPackage.get(pkg.did)) {
        versions.push(pkg.version);
      } else {
        let versions = new GrowableArray<Version>();
        versions.push(pkg.version);
        byPackage[pkg.did] = versions;
      }
    }
    let out = new OrderedHashMap<String, GrowableArray<Version>>();
    byPackage.forEach((did, versions) => {
      if (versions.length > 1) {
        out[did] = versions;
      }
    });
    return out;
  }
}

/**
 * `zena-lock.json` text pinning `resolution`'s packages, with `workspace`,
 * each workspace package's names by its directory, each mapped to a key
 * of `resolution`, after `lockfileVersion`. The lockfile holds nothing
 * else, so it is written whole.
 */
export function writeLockfile(resolution: Resolution,
    workspace: OrderedHashMap<String, OrderedHashMap<String, String>>): String {
  let root = new JsonObject();
  root['lockfileVersion'] = new Box<f64>(LOCKFILE_VERSION as f64);
  let names = new JsonObject();
  workspace.forEach((dir, pins) => {
    if (pins.size > 0) {
      let entry = new JsonObject();
      pins.forEach((name, key) => {
        entry[name] = key;
      });
      names[dir] = entry;
    }
  });
  if (names.size > 0) {
    root['workspace'] = names;
  }
  let resolved = new JsonObject();
  resolution.packages.forEach((key, pkg) => {
    let entry = new JsonObject();
    entry['release'] = pkg.release.toString();
    entry['source'] = pkg.source.toString();
    if (pkg.dependencies.size > 0) {
      let dependencies = new JsonObject();
      pkg.dependencies.forEach((name, target) => {
        dependencies[name] = target;
      });
      entry['dependencies'] = dependencies;
    }
    resolved[key] = entry;
  });
  root['resolved'] = resolved;
  return stringify(root, '  ');
}

/**
 * How a package's pin changes when a lockfile is written for a new
 * resolution (`diffPins`).
 */
export sealed class PinChange {
  /** A package the lockfile did not pin. */
  case PinAdded(now: ResolvedPackage)
  /** A package the lockfile pinned, and no longer does. */
  case PinRemoved(pin: Pin)
  /**
   * A package pinned at another version on the same compatible line
   * (`Version.compatibleLine`), higher or lower: the one version on that
   * line the lockfile pinned and the one the resolution selects instead.
   */
  case PinVersionChanged(pin: Pin, now: ResolvedPackage)
  /**
   * A package at the version it was pinned at, with another release
   * record or source archive: the release was changed in place, which a
   * published version never is (docs/design/package-manager.md,
   * "Immutability").
   */
  case PinChangedInPlace(pin: Pin, now: ResolvedPackage)
}

/**
 * What writing `after` changes in the pins `before`, in `after`'s order
 * and then `before`'s: a version both have with other CIDs was changed in
 * place; a package and compatible line with one version before and
 * another after changed version; any other version only one of them has
 * was added or removed. A pin that stays the same has no change.
 */
export function diffPins(before: GrowableArray<Pin>, after: Resolution): GrowableArray<PinChange> {
  let pinned = new HashMap<String, Pin>();
  // The versions only `before` or only `after` has, by package and compatible line.
  let gone = new HashMap<String, GrowableArray<Pin>>();
  let fresh = new HashMap<String, GrowableArray<ResolvedPackage>>();
  for (let pin in before) {
    pinned[pin.key] = pin;
    if (!after.packages.has(pin.key)) {
      append(gone, slotOf(pin.did, pin.version), pin);
    }
  }
  after.packages.forEach((key, now) => {
    if (!pinned.has(key)) {
      append(fresh, slotOf(now.did, now.version), now);
    }
  });
  let changes = new GrowableArray<PinChange>();
  let paired = new HashSet<String>();
  after.packages.forEach((key, now) => {
    if (let (true, pin) = pinned.get(key)) {
      if (!pin.release.equals(now.release) || !pin.source.equals(now.source)) {
        changes.push(new PinChangedInPlace(pin, now));
      }
      return;
    }
    let slot = slotOf(now.did, now.version);
    if (let (true, pins) = gone.get(slot)) {
      if (pins.length == 1 && fresh[slot].length == 1) {
        changes.push(new PinVersionChanged(pins[0], now));
        paired.add(pins[0].key);
        return;
      }
    }
    changes.push(new PinAdded(now));
  });
  for (let pin in before) {
    if (!after.packages.has(pin.key) && !paired.has(pin.key)) {
      changes.push(new PinRemoved(pin));
    }
  }
  return changes;
}

/** The package `did`'s compatible line that `version` is on. */
function slotOf(did: String, version: Version): String {
  return `${did}@${version.compatibleLine()}`;
}

function append<T>(map: HashMap<String, GrowableArray<T>>, key: String, value: T): void {
  if (let (true, values) = map.get(key)) {
    values.push(value);
  } else {
    let values = new GrowableArray<T>();
    values.push(value);
    map[key] = values;
  }
}
  • 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