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.
11.0 KiB Raw
/**
 * What makes a release one to publish or to use
 * (docs/design/package-manager.md, "Validating releases"). The same rules
 * are checked by `zena pkg publish` before it uploads anything, by a package
 * host before it records a release, since it trusts no client, and by
 * `zena pkg fetch`, since a package can be kept on any PDS, where nothing
 * checked what was written.
 *
 * `checkSource` checks a release against its source archive: that the
 * archive is the artifact the release names and unpacks, and that the
 * manifest in it agrees with the release. `checkDependencies` checks that
 * each dependency is a release that exists and is not retracted, which a
 * fetch need not repeat, since resolving fails on a missing one.
 * `validateRelease` is both, for publishing, and also requires the
 * manifest's `description` and `license`, which releases published before
 * that rule may lack. Each returns every problem it finds, so one attempt
 * reports them all.
 */

import {Future} from 'zena:async';
import {HashSet} from 'zena:collections';
import {Cid} from 'atproto/cid';
import {IdentityResolver} from 'atproto/identity';
import {SourceFile, unpackSource} from './archive.zena';
import {PublishedFiles} from './files.zena';
import {Manifest, readManifest} from './manifest.zena';
import {Dependency, Release, SOURCE, isValidLicenseExpression} from './records.zena';
import {Version} from 'zena-lang:semver';
import {listVersions} from './registry.zena';
import {Versions} from './resolve.zena';
import {MANIFEST} from './workspace.zena';

/** The MIME type of a source archive, a CAR file. */
export let SOURCE_MIME_TYPE = 'application/vnd.ipld.car';

/**
 * The MIME types an artifact's blobs have: a source archive, a component
 * or core module, a component's WIT, and the parts of a large artifact
 * (package-manager.md, "Large artifacts").
 */
export let ARTIFACT_MIME_TYPES: Array<String> = [SOURCE_MIME_TYPE, 'application/wasm', 'text/plain',
    'application/octet-stream'];

/**
 * The artifact MIME type a `Content-Type` names, without its parameters
 * and in lowercase; null when it is not one of `ARTIFACT_MIME_TYPES`.
 */
export function artifactMimeType(contentType: String): String | null {
  let type = contentType.split(';')[0].trim().asciiLowerCase();
  for (let allowed in ARTIFACT_MIME_TYPES) {
    if (type == allowed) {
      return type;
    }
  }
  return null;
}

/**
 * The problems with `release`, a release of the package `did`, and
 * `source`, the bytes of its source artifact: empty when there are none.
 * `profileName`, given when publishing, is the name the package's profile
 * gives, which its manifest must have too. A fetch leaves it out, since a
 * package renamed later keeps its older releases. `publishing` also
 * requires the manifest's `description` and an SPDX `license`.
 */
export function checkSource(release: Release, did: String, source: FixedArray<u8>,
    profileName: String | null = null, publishing: boolean = false): GrowableArray<String> {
  let problems = new GrowableArray<String>();
  let version = release.version.toString();
  let artifact = release.artifact(SOURCE);
  if (artifact == null) {
    problems.push(`release ${version} has no source artifact`);
    return problems;
  }
  if (artifact.size != source.length as i64) {
    problems.push(`the source artifact is ${artifact.size} bytes, but the archive is ${source.length}`);
  }
  if (!Cid.forBlob(source).equals(artifact.cid)) {
    problems.push(`the archive is not the source artifact ${artifact.cid.toString()}`);
  }
  let blob = artifact.blob;
  if (blob != null && blob.mimeType != SOURCE_MIME_TYPE) {
    problems.push(`the source artifact is ${blob.mimeType}, not ${SOURCE_MIME_TYPE}`);
  }

  let files = unpacked(source, problems);
  if (files == null) {
    return problems;
  }
  var text: String | null = null;
  for (let file in files) {
    if (file.path == MANIFEST) {
      text = String.fromBytes(file.contents as ByteArray);
    }
  }
  if (text == null) {
    problems.push(`the archive has no ${MANIFEST}`);
    return problems;
  }
  let manifest = try {
    readManifest(text)
  } catch (e) {
    problems.push(`the archive's ${MANIFEST} cannot be read: ${e.message}`);
    null
  };
  if (manifest == null) {
    return problems;
  }

  let manifestVersion = manifest.version;
  if (manifestVersion == null) {
    problems.push(`the archive's ${MANIFEST} has no version`);
  } else if (manifestVersion.compareTo(release.version) != 0) {
    problems.push(`the archive's ${MANIFEST} is version ${manifestVersion.toString()}, not ${version}`);
  }
  let manifestDid = manifest.did;
  if (manifestDid != null && manifestDid != did) {
    problems.push(`the archive's ${MANIFEST} is the package ${manifestDid}, not ${did}`);
  }
  if (profileName != null && (manifest.name == null || manifest.name as String != profileName)) {
    problems.push(`the archive's ${MANIFEST} names ${manifest.name ?? 'no package'}, not ${profileName}`);
  }
  manifest.wits.forEach((name, wit) => {
    problems.push(`the archive depends on the WIT in ${wit}, as ${name}, which a published package cannot`);
  });
  // A new release says what the package is and on what terms it may be
  // used. Releases published before this rule are fetched all the same.
  if (publishing) {
    for (let problem in checkMetadata(manifest, `the archive's ${MANIFEST}`)) {
      problems.push(problem);
    }
    // The archive holds what its manifest publishes, the file of every
    // library it exports among them (package-manifest.md, "files").
    let published = PublishedFiles.of(manifest);
    let held = new HashSet<String>();
    for (let file in files) {
      held.add(file.path);
      if (!published.includes(file.path)) {
        problems.push(`the archive holds ${file.path}, which its ${MANIFEST} does not publish`);
      }
    }
    for (let path in manifest.exportFiles) {
      let relative = if (path.startsWith('./')) path.sliceBytes(2, path.length) else path;
      if (!held.has(relative)) {
        problems.push(`the archive has no ${relative}, which its ${MANIFEST} exports`);
      }
    }
    // A package that lists no exports has its main library in its source
    // directory too, or no import of its name works.
    let mainFile = manifest.mainFile;
    if (mainFile != null && !held.has(mainFile)) {
      problems.push(`the archive has no ${mainFile}, the library its ${MANIFEST}'s main names`);
    }
  }

  // The release's dependencies are the manifest's, each by its local name:
  // a path dependency appears in the release as the DID it has.
  let declared = new HashSet<String>();
  for (let name in manifest.requirements.keys()) {
    declared.add(name);
  }
  for (let name in manifest.paths.keys()) {
    declared.add(name);
  }
  let listed = new HashSet<String>();
  for (let dependency in release.dependencies) {
    listed.add(dependency.name);
    if (!declared.has(dependency.name)) {
      problems.push(`the release depends on ${dependency.name}, which the archive's ${MANIFEST} does not`);
    }
  }
  for (let name in declared) {
    if (!listed.has(name)) {
      problems.push(`the archive's ${MANIFEST} depends on ${name}, which the release does not list`);
    }
  }
  return problems;
}

/** The files in `source`, or null, with why added to `problems`. */
function unpacked(source: FixedArray<u8>, problems: GrowableArray<String>): FixedArray<SourceFile> | null {
  try {
    return unpackSource(source);
  } catch (e) {
    problems.push(`the archive does not unpack: ${e.message}`);
    return null;
  }
}

/**
 * The problems with `dependencies`: each range must have a version in it
 * that its package has published and not retracted, or the release that
 * names it could never be resolved. Empty when there are none. With `explain`, a dependency that
 * cannot be found says why in full; without, only whether its DID or its
 * PDS failed, as a host answers.
 */
export async function checkDependencies(dependencies: Array<Dependency>, resolver: IdentityResolver,
    explain: boolean = true): Future<GrowableArray<String>> {
  let problems = new GrowableArray<String>();
  for (let dependency in dependencies) {
    let named = `${dependency.name} ${dependency.range.text} (${dependency.did})`;
    let found = await versionsOf(dependency, resolver, explain);
    if (found is String) {
      problems.push(`${named} cannot be found: ${found}`);
    } else {
      var published = false;
      var usable = false;
      for (let version in found.releases) {
        if (dependency.range.includes(version)) {
          published = true;
          if (!found.retracted.has(version.toString())) {
            usable = true;
          }
        }
      }
      if (!published) {
        problems.push(`${named} is not published: no version in the range is; publish one first, or depend on a range that has one`);
      } else if (!usable) {
        problems.push(`${named} is retracted: every published version in the range is; depend on another range`);
      }
    }
  }
  return problems;
}

/**
 * The versions `dependency`'s package lists, or why they could not be
 * read: whether its DID does not resolve or its PDS cannot be read, and
 * with `explain`, the error. A host leaves the error out, since its
 * answer would tell a refused connection from a timeout from a status,
 * on whatever network a DID document points it at.
 */
async function versionsOf(dependency: Dependency, resolver: IdentityResolver, explain: boolean)
    : Future<Versions | String> {
  let document = try {
    await resolver.resolveDid(dependency.did)
  } catch (e) {
    return if (explain) `its DID does not resolve: ${e.message}` else 'its DID does not resolve';
  };
  try {
    return await listVersions(document);
  } catch (e) {
    return if (explain) `its PDS cannot be read: ${e.message}` else 'its PDS cannot be read';
  }
}

/**
 * What publishing requires of `manifest`, called `where` in the problems:
 * a description, and a license as an SPDX expression.
 */
export function checkMetadata(manifest: Manifest, where: String): GrowableArray<String> {
  let problems = new GrowableArray<String>();
  let description = manifest.description;
  if (description == null || description.trim() == '') {
    problems.push(`${where} has no description`);
  }
  let license = manifest.license;
  if (license == null) {
    problems.push(`${where} has no license: give an SPDX expression, such as "MIT"`);
  } else if (!isValidLicenseExpression(license)) {
    problems.push(`${where} license '${license}' is not an SPDX expression`);
  }
  return problems;
}

/**
 * Every problem with publishing `release` of the package `did`, with
 * `source` as its source archive and `profileName` as its profile's name:
 * `checkSource`'s and `checkDependencies`', the errors behind a dependency
 * that cannot be found included unless `explain` is false.
 */
export async function validateRelease(release: Release, did: String, source: FixedArray<u8>,
    profileName: String, resolver: IdentityResolver, explain: boolean = true): Future<GrowableArray<String>> {
  let problems = checkSource(release, did, source, profileName, true);
  for (let problem in await checkDependencies(release.dependencies, resolver, explain)) {
    problems.push(problem);
  }
  return problems;
}
  • 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