package-manager 0.0.1-preview.1
The Zena package manager's libraries: manifests, version selection, lockfiles, archives and the registry client
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'szena-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'sfilespatterns, 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, orscope:nameto 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 intosources/<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.
20.4 KiB
Raw
/**
* A package's manifest, `zena-package.json`
* (docs/design/package-manifest.md): its name, its DID, its dependencies,
* the scope on a package host it is created in, and at a workspace's root,
* the workspace's other packages, the domains of `scope:name` and whether
* `zena pkg add` gives names their scope.
*
* ```json
* {
* "name": "app",
* "dependencies": {
* "router": {"did": "did:plc:routerrouterrouterrouter", "version": "^1.4.2"},
* "lib": {"path": "./packages/lib"},
* "gfx": {"wit": "./wit"}
* },
* "workspace": {"packages": ["packages/*"]},
* "scopes": {"widgets": "widgets.alt-pkg.org"}
* }
* ```
*
* `writeDependencies` rewrites the dependencies and keeps the rest of the
* file, each key where it was. A WIT dependency, which the compiler reads
* and the package manager has nothing to select or fetch for, is kept as
* it is.
*/
import {HashSet, OrderedHashMap} from 'zena:collections';
import {join} from 'zena:core';
import {globToRegex} from 'zena:glob';
import {JsonArray, JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {isValidDid} from 'atproto/syntax';
import {isValidLocalName, isValidPackageName, isValidScopeName, parsePackageVersion, readRange} from './records.zena';
import {Requirement} from './resolve.zena';
import {Range, Version} from 'zena-lang:semver';
/** A manifest the package manager cannot read or update. */
export class ManifestError extends Error {
new(message: String) : super(message);
}
/** What a package's `zena-package.json` says. */
export final class Manifest {
/** The package's name, or null when the manifest gives none. */
name: String | null;
/** The package's DID, once it has been created on a package host. */
did: String | null;
/**
* The scope on a package host the package is created in, the part of
* `name` before its `:`, or null (package-manifest.md, "name").
*/
var scope: String | null = null;
/** What the package is for, in a sentence: publishing requires it. */
var description: String | null = null;
/** The package's license, an SPDX expression such as `MIT`: publishing requires it. */
var license: String | null = null;
/** The version `zena pkg publish` publishes next, or null. */
version: Version | null;
/** The published packages it depends on, by local name, in file order. */
requirements: OrderedHashMap<String, Requirement>;
/**
* The packages on disk it depends on, by local name: each one's
* directory, relative to the manifest's.
*/
paths: OrderedHashMap<String, String>;
/**
* The range of versions each package on disk is published as a
* dependency with, by local name, for those whose entry gives a
* `version` beside its `path`. Builds use the directory; only
* `zena pkg publish` reads the range (package-manifest.md,
* "dependencies").
*/
var pathRanges = new OrderedHashMap<String, Range>();
/**
* At a workspace's root, the directories of the workspace's other
* packages, or patterns ending in `/*`. Empty elsewhere.
*/
workspacePackages: GrowableArray<String>;
/** At a workspace's root, each scope mapped to its domain. */
scopes: OrderedHashMap<String, String>;
/**
* At a workspace's root, whether `zena pkg add` names a package in a
* scope `<scope>:<name>`, as it does unless `scopedNames` is false
* (docs/design/import-names.md, "Names are still local").
*/
var scopedNames = true;
/**
* At a workspace's root, what `zena pkg add` and `zena pkg update` do when
* selection installs a package at two versions: `allow`, `warn` or
* `error` (docs/design/package-manager.md, "What zena pkg add and zena
* pkg update report").
*/
var duplicates = 'allow';
/**
* The WIT-backed packages it depends on, by local name: each one's `.wit`
* file or directory, relative to the manifest's.
*/
var wits = new OrderedHashMap<String, String>();
/**
* The patterns of the files a published archive holds, relative to the
* manifest's directory, or null for the default (`package-manager/files`).
*/
var files: Array<String> | null = null;
/**
* The directory its libraries are in, relative to the manifest's: its
* `source`, or `src` when it has none (package-manifest.md, "source").
*/
var source = 'src';
/**
* The entry files of the libraries `exports` names, relative to the
* manifest's directory, under `source`: none for an open package, which
* exports every file. A published archive must hold each.
*/
var exportFiles = new GrowableArray<String>();
/**
* The library an import of the package's name alone imports, when the
* manifest names one: `main` when it does not (import-names.md, "The main
* library").
*/
var main: String | null = null;
/**
* The entry file of the library `main` names, relative to the manifest's
* directory, for a package that names a `main` and lists no `exports`:
* one that does has it among `exportFiles`. A published archive must
* hold it.
*/
var mainFile: String | null = null;
new(name: String | null, did: String | null, requirements: OrderedHashMap<String, Requirement>,
paths: OrderedHashMap<String, String>, workspacePackages: GrowableArray<String>,
scopes: OrderedHashMap<String, String>, version: Version | null = null)
: name = name, did = did, requirements = requirements, paths = paths,
workspacePackages = workspacePackages, scopes = scopes, version = version;
}
/**
* The package name and scope a manifest's `name`, `[scope:]name`, gives:
* both null when it has none, and a null scope when the name has none.
*/
function splitName(name: String | null): inline (String | null, String | null) {
if (name == null) {
return (null, null);
}
let colon = name.indexOf(':');
if (let (true, at) = colon) {
let scope = name.slice(name.startIndex, at);
let plain = name.slice(name.indexAfter(at));
if (!isValidLocalName(name) || !isValidPackageName(plain)) {
throw new ManifestError(`zena-package.json: '${name}' is not a valid package name: a name, or scope:name`);
}
return (plain, scope);
}
if (!isValidPackageName(name)) {
throw new ManifestError(`zena-package.json: '${name}' is not a valid package name`);
}
return (name, null);
}
/**
* Reads `zena-package.json` text. A null `text`, for a directory with no
* manifest, reads as an empty manifest. Throws `ManifestError`.
*/
export function readManifest(text: String | null): Manifest {
let root = parse(text);
let (name, nameScope) = splitName(optionalString(root, 'name'));
let did = optionalString(root, 'did');
if (did != null && !isValidDid(did)) {
throw new ManifestError(`zena-package.json: '${did}' is not a DID`);
}
let versionText = optionalString(root, 'version');
var version: Version | null = null;
if (versionText != null) {
try {
version = parsePackageVersion(versionText);
} catch (e) {
throw new ManifestError(`zena-package.json: version: ${e.message}`);
}
}
let requirements = new OrderedHashMap<String, Requirement>();
let paths = new OrderedHashMap<String, String>();
let pathRanges = new OrderedHashMap<String, Range>();
let wits = new OrderedHashMap<String, String>();
let dependencies = member(root, 'dependencies');
if (dependencies != null) {
dependencies.forEach((localName, value) => {
if (!isValidLocalName(localName)) {
throw new ManifestError(`zena-package.json: '${localName}' is not a valid local name`);
}
if (!(value is JsonObject)) {
throw new ManifestError(`zena-package.json: dependency '${localName}' is not an object`);
}
let entry = value;
let wit = entry['wit'];
if (wit != null) {
if (!(wit is String) || entry.has('did') || entry.has('version') || entry.has('path')) {
throw new ManifestError(
`zena-package.json: dependency '${localName}' has a wit and a DID, version or path, or a wit that is not a string`);
}
wits[localName] = wit;
return;
}
let path = entry['path'];
if (path != null) {
if (!(path is String) || entry.has('did')) {
throw new ManifestError(
`zena-package.json: dependency '${localName}' has a path and a DID, or a path that is not a string`);
}
// A version beside a path is the range the dependency is published
// with. The package is still the one in the directory.
if (entry.has('version')) {
let range = entry['version'];
if (!(range is String)) {
throw new ManifestError(`zena-package.json: dependency '${localName}' has a version that is not a string`);
}
pathRanges[localName] = parseRange(range, localName);
}
paths[localName] = path;
return;
}
let did = entry['did'];
let version = entry['version'];
if (!(did is String) || !isValidDid(did)) {
throw new ManifestError(`zena-package.json: dependency '${localName}' has no DID, path or wit`);
}
if (!(version is String)) {
throw new ManifestError(`zena-package.json: dependency '${localName}' has no version`);
}
requirements[localName] = new Requirement(did, parseRange(version, localName));
});
}
let workspacePackages = new GrowableArray<String>();
let workspace = member(root, 'workspace');
if (workspace != null) {
let packages = workspace['packages'];
if (packages != null) {
if (!(packages is JsonArray)) {
throw new ManifestError('zena-package.json: workspace.packages is not a list');
}
let list = packages;
for (var i = 0; i < list.length; i += 1) {
let item = list[i];
if (!(item is String)) {
throw new ManifestError('zena-package.json: workspace.packages lists something other than a directory');
}
workspacePackages.push(item);
}
}
}
let scopes = new OrderedHashMap<String, String>();
let scopeMap = member(root, 'scopes');
if (scopeMap != null) {
scopeMap.forEach((scope, domain) => {
if (!isValidScopeName(scope) || !(domain is String)) {
throw new ManifestError(`zena-package.json: scope '${scope}' is not a scope's name mapped to a domain`);
}
scopes[scope] = domain;
});
}
let manifest = new Manifest(name, did, requirements, paths, workspacePackages, scopes, version);
manifest.wits = wits;
manifest.pathRanges = pathRanges;
manifest.scope = nameScope;
let scopedNames = root['scopedNames'];
if (scopedNames != null) {
if (!(scopedNames is Box<boolean>)) {
throw new ManifestError('zena-package.json: scopedNames is not true or false');
}
manifest.scopedNames = scopedNames.value;
}
let duplicates = optionalString(root, 'duplicates');
if (duplicates != null) {
if (duplicates != 'allow' && duplicates != 'warn' && duplicates != 'error') {
throw new ManifestError(`zena-package.json: duplicates is allow, warn or error, not '${duplicates}'`);
}
manifest.duplicates = duplicates;
}
manifest.description = optionalString(root, 'description');
manifest.license = optionalString(root, 'license');
manifest.files = filePatterns(root);
manifest.source = sourceDirectory(root);
manifest.exportFiles = exportedFiles(root, manifest.source);
let main = mainLibrary(root);
manifest.main = main;
if (main != null && !(root['exports'] is JsonObject)) {
manifest.mainFile = underSource(manifest.source, `${main}.zena`);
}
return manifest;
}
/**
* The manifest's `main`, or null when it has none: a library's name, and
* one of the `exports` when it lists them, as the compiler requires.
*/
function mainLibrary(root: JsonObject): String | null {
let value = root['main'];
if (value == null) {
return null;
}
if (!(value is String)) {
throw new ManifestError('zena-package.json: main is not a string');
}
let main = value;
if (main == '' || main.startsWith('/') || main.endsWith('/') || main.endsWith('.zena')) {
throw new ManifestError(`zena-package.json: main '${main}' is not a library's name`);
}
let exports = root['exports'];
if (exports is JsonObject) {
if (!exports.has(main)) {
throw new ManifestError(`zena-package.json: main '${main}' is not one of its exports`);
}
}
return main;
}
/**
* The `source` directory, normalized, or `src` when there is none. It must
* be a directory inside the package: relative, and without `..`.
*/
function sourceDirectory(root: JsonObject): String {
if (!root.has('source')) {
return 'src';
}
let value = root['source'];
if (!(value is String)) {
throw new ManifestError('zena-package.json: source is not a path');
}
let text = value;
let parts = new GrowableArray<String>();
for (let part in text.split('/')) {
if (part == '..' || (parts.length == 0 && part == '' && text.startsWith('/'))) {
throw new ManifestError(`zena-package.json: source '${text}' is not a directory inside the package`);
}
if (part != '' && part != '.') {
parts.push(part);
}
}
return if (parts.length == 0) '.' else join(parts, '/');
}
/**
* The `files` list: patterns, each perhaps negated with `!`, of paths
* inside the package. Null when there is none.
*/
function filePatterns(root: JsonObject): Array<String> | null {
if (!root.has('files')) {
return null;
}
let value = root['files'];
if (!(value is JsonArray)) {
throw new ManifestError('zena-package.json: files is not a list of paths');
}
let list = value;
let patterns = new GrowableArray<String>();
for (var i = 0; i < list.length; i += 1) {
let item = list[i];
if (!(item is String)) {
throw new ManifestError('zena-package.json: an entry of files is not a string');
}
let pattern = item;
let path = if (pattern.startsWith('!')) pattern.sliceBytes(1, pattern.length) else pattern;
var outside = path == '' || path.startsWith('/');
for (let segment in path.split('/')) {
if (segment == '..') {
outside = true;
}
}
if (outside) {
throw new ManifestError(`zena-package.json: '${pattern}' in files is not a path inside the package`);
}
try {
globToRegex(path);
} catch (e) {
throw new ManifestError(`zena-package.json: '${pattern}' in files is not a pattern: ${e.message}`);
}
patterns.push(pattern);
}
return patterns;
}
/**
* The entry files of the libraries `exports` names, in the `source`
* directory (package-manifest.md, "exports").
*/
function exportedFiles(root: JsonObject, source: String): GrowableArray<String> {
let files = new GrowableArray<String>();
let exports = root['exports'];
if (!(exports is JsonObject)) {
return files;
}
exports.forEach((name, value) => {
if (!(value is JsonObject)) {
return;
}
let entry = value;
let path = entry['path'];
let virtual = entry['virtual'];
if (path is String) {
files.push(underSource(source, path));
} else if (virtual is JsonObject) {
virtual.forEach((target, file) => {
if (file is String) {
files.push(underSource(source, file));
}
});
} else {
files.push(underSource(source, `${name}.zena`));
}
});
return files;
}
/** `file`, a path relative to the `source` directory, relative to the manifest's. */
function underSource(source: String, file: String): String {
let relative = if (file.startsWith('./')) file.sliceBytes(2, file.length) else file;
return if (source == '.') relative else `${source}/${relative}`;
}
/**
* The range a release of `manifest`'s package states for its path
* dependency `localName`, which is at `version` in its directory: the
* range the manifest gives beside the path, or else `^<version>`.
*
* Throws `ManifestError` when the range the manifest gives leaves out
* `version`, since the package was built and tested against that one.
*/
export function publishedRange(manifest: Manifest, localName: String, version: Version): Range {
if (let (true, range) = manifest.pathRanges.get(localName)) {
if (!range.includes(version)) {
throw new ManifestError(
`zena-package.json: dependency '${localName}' is published as ${range.text}, which leaves out ${version.toString()}, the version at its path`);
}
return range;
}
return Range.parse(`^${version.toString()}`);
}
/**
* `zena-package.json` text with its `dependencies` replaced by
* `requirements` and `paths`, or a new manifest holding only them when
* `text` is null. A dependency the file already has keeps its place, new
* ones follow, and every other key stays where it was. A WIT dependency
* stays as the file has it, and a path dependency keeps the `version`
* the file gives beside its path.
*/
export function writeDependencies(text: String | null, requirements: OrderedHashMap<String, Requirement>,
paths: OrderedHashMap<String, String>): String {
let root = parse(text);
let section = new JsonObject();
let written = new HashSet<String>();
let existing = member(root, 'dependencies');
let write = (localName: String) => {
if (written.has(localName)) {
return;
}
if (let (true, requirement) = requirements.get(localName)) {
let entry = new JsonObject();
entry['did'] = requirement.did;
entry['version'] = requirement.range.text;
section[localName] = entry;
written.add(localName);
} else if (let (true, path) = paths.get(localName)) {
let entry = new JsonObject();
entry['path'] = path;
if (existing != null) {
let before = existing[localName];
if (before is JsonObject && before.has('path') && before.has('version')) {
entry['version'] = before['version'];
}
}
section[localName] = entry;
written.add(localName);
}
};
if (existing != null) {
existing.forEach((localName, value) => {
if (value is JsonObject && value.has('wit') && !requirements.has(localName) && !paths.has(localName)) {
section[localName] = value;
written.add(localName);
return;
}
write(localName);
});
}
for (let localName in requirements.keys()) {
write(localName);
}
for (let localName in paths.keys()) {
write(localName);
}
root['dependencies'] = section;
return stringify(root, ' ');
}
/**
* `zena-package.json` text with its `did` set to `did`, and, when a `scope`
* is given, its `name` to `<scope>:<name>`, as `zena pkg publish` writes it
* when it creates the package. A new `did` goes after `name`, and every
* other key stays where it was.
*/
export function writeDid(text: String, did: String, scope: String | null = null): String {
var root = parse(text);
if (root.has('did')) {
root['did'] = did;
} else {
root = insertAfter(root, 'name', 'did', did);
}
if (scope != null) {
let (name, _) = splitName(optionalString(root, 'name'));
if (name == null) {
throw new ManifestError('zena-package.json has no name to give the scope in');
}
root['name'] = `${scope}:${name}`;
}
return stringify(root, ' ');
}
/** `root` with `key` set to `value` just after `after`, or last when it has no `after`. */
function insertAfter(root: JsonObject, after: String, key: String, value: String): JsonObject {
let written = new JsonObject();
root.forEach((existing, existingValue) => {
written[existing] = existingValue;
if (existing == after) {
written[key] = value;
}
});
if (!written.has(key)) {
written[key] = value;
}
return written;
}
function parse(text: String | null): JsonObject {
if (text == null) {
return new JsonObject();
}
var json: JsonValue = null;
try {
json = parseJson(text);
} catch (e) {
throw new ManifestError(`zena-package.json is not JSON: ${e.message}`);
}
if (!(json is JsonObject)) {
throw new ManifestError('zena-package.json is not a JSON object');
}
return json;
}
function member(root: JsonObject, name: String): JsonObject | null {
let value = root[name];
if (value == null) {
return null;
}
if (!(value is JsonObject)) {
throw new ManifestError(`zena-package.json: "${name}" is not an object`);
}
return value;
}
function optionalString(root: JsonObject, name: String): String | null {
let value = root[name];
if (value == null) {
return null;
}
if (!(value is String)) {
throw new ManifestError(`zena-package.json: "${name}" is not a string`);
}
return value;
}
/** A dependency's range, which must have a version in it. */
function parseRange(text: String, localName: String): Range {
try {
return readRange(text, `zena-package.json: dependency '${localName}'`);
} catch (e) {
throw new ManifestError(e.message);
}
}
- 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
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 |
|
|