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.
6.1 KiB
Raw
/**
* Finding packages on the network, for `zena pkg add` and `zena pkg update`
* (docs/design/package-manager.md, "Names and scopes"): turning what a
* person typed into a DID, listing a package's versions, and reading its
* profile and releases with their proofs.
*/
import {HashMap, HashSet, OrderedHashMap} from 'zena:collections';
import {DidDocument} from 'atproto/did';
import {IdentityResolver} from 'atproto/identity';
import {getVerifiedRecord, listRecords} from 'atproto/sync';
import {isValidDid, isValidHandle} from 'atproto/syntax';
import {
PROFILE_KEY, PROFILE_TYPE, Profile, RELEASE_TYPE, Release, RETRACTION_TYPE, isValidLocalName
} from './records.zena';
import {CheckedRelease, PackageSource, Versions} from './resolve.zena';
import {Version} from 'zena-lang:semver';
/** The domain `scope:name` is looked up in when no `scopes` entry names one. */
export let DEFAULT_DOMAIN = 'pkg.zena-lang.dev';
/** A package that cannot be found as asked. */
export class RegistryError extends Error {
new(message: String) : super(message);
}
/** Whether `identifier`, a package as `zena pkg add` is given one, is `scope:name`: one `:`, and not a DID. */
export function isScopedIdentifier(identifier: String): boolean {
return !identifier.startsWith('did:') && identifier.contains(':');
}
/**
* The handle `scope:name` stands for: `name.<domain>`, where the domain
* is the one `scopes` maps `scope` to, or `scope.<defaultDomain>`.
*/
export function scopedHandle(identifier: String, scopes: OrderedHashMap<String, String>,
defaultDomain: String = DEFAULT_DOMAIN): String {
let parts = identifier.split(':');
if (parts.length != 2 || parts[0] == '' || parts[1] == '') {
throw new RegistryError(`'${identifier}' is not scope:name`);
}
let scope = parts[0];
let name = parts[1];
if (let (true, domain) = scopes.get(scope)) {
return `${name}.${domain}`;
}
return `${name}.${scope}.${defaultDomain}`;
}
/**
* The local name `zena pkg add` gives the package whose handle is
* `handle` when it is not told one, the inverse of `scopedHandle`:
* `<scope>:<name>` for a name in a scope on the domain `scopes` maps
* `<scope>` to (`<name>.<domain>`) or on `defaultDomain`
* (`<name>.<scope>.<defaultDomain>`); null for any other handle
* (docs/design/import-names.md, "Names are still local").
*/
export function scopedName(handle: String, scopes: OrderedHashMap<String, String>,
defaultDomain: String = DEFAULT_DOMAIN): String | null {
let lower = handle.asciiLowerCase();
var found: String | null = null;
for (let scope in scopes.keys()) {
let suffix = `.${scopes[scope].asciiLowerCase()}`;
if (found == null && lower.endsWith(suffix)) {
found = `${scope}:${lower.sliceBytes(0, lower.length - suffix.length)}`;
}
}
if (found == null) {
let suffix = `.${defaultDomain.asciiLowerCase()}`;
if (lower.endsWith(suffix)) {
let labels = lower.sliceBytes(0, lower.length - suffix.length).split('.');
if (labels.length == 2) {
found = `${labels[1]}:${labels[0]}`;
}
}
}
return if (found != null && isValidLocalName(found)) found else null;
}
/**
* The DID that `identifier` names: a DID as it is, `scope:name` by the
* handle it stands for, and a handle by resolving it and checking that the
* DID's document claims it back.
*/
export async function resolveIdentifier(identifier: String, scopes: OrderedHashMap<String, String>,
resolver: IdentityResolver, defaultDomain: String = DEFAULT_DOMAIN): Future<String> {
if (identifier.startsWith('did:')) {
if (!isValidDid(identifier)) {
throw new RegistryError(`'${identifier}' is not a DID`);
}
return identifier;
}
let handle = if (isScopedIdentifier(identifier)) scopedHandle(identifier, scopes, defaultDomain) else identifier;
if (!isValidHandle(handle)) {
throw new RegistryError(`'${identifier}' is not a DID, a handle or scope:name`);
}
let identity = await resolver.resolve(handle);
return identity.did;
}
/**
* The versions the package `document` describes lists. The list is its
* PDS's word: whatever is chosen from it is fetched again with its proof.
* Record keys that are not versions are skipped.
*/
export async function listVersions(document: DidDocument): Future<Versions> {
let releases = new GrowableArray<Version>();
for (let record in await listRecords(document, RELEASE_TYPE)) {
try {
releases.push(Version.parse(record.rkey));
} catch (e) {
// Not a version: no client publishes such a record.
}
}
let retracted = new HashSet<String>();
for (let record in await listRecords(document, RETRACTION_TYPE)) {
retracted.add(record.rkey);
}
return new Versions(releases, retracted);
}
/** The package's profile, with its proof, or null when it has none. */
export async function fetchProfile(document: DidDocument): Future<Profile | null> {
let proof = await getVerifiedRecord(document, PROFILE_TYPE, PROFILE_KEY);
let record = proof.record;
if (record == null) {
return null;
}
return Profile.fromValue(record);
}
/**
* A `PackageSource` that reads each package's versions and releases from
* its PDS, releases with their proofs, resolving each DID once.
*/
export final class NetworkSource implements PackageSource {
#resolver: IdentityResolver;
#documents = new HashMap<String, DidDocument>();
new(resolver: IdentityResolver) : #resolver = resolver;
async versions(did: String): Future<Versions> {
return await listVersions(await this.#document(did));
}
async release(did: String, version: Version): Future<CheckedRelease> {
let document = await this.#document(did);
let text = version.toString();
let proof = await getVerifiedRecord(document, RELEASE_TYPE, text);
let record = proof.record;
let cid = proof.cid;
if (record == null || cid == null) {
throw new RegistryError(`${did} has no release ${text}`);
}
return new CheckedRelease(Release.fromValue(record, text), cid);
}
async #document(did: String): Future<DidDocument> {
if (let (true, known) = this.#documents.get(did)) {
return known;
}
let resolved = await this.#resolver.resolveDid(did);
this.#documents[did] = resolved;
return resolved;
}
}
- 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 |
|
|