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.
3.6 KiB
Raw
/**
* The package cache, where `zena pkg fetch` stores packages and the compiler
* reads them. Each source archive is unpacked into `sources/<CID>`, the
* directory `compiler/package-manifest` roots a pinned package at.
*
* A source directory is written under `tmp/` and renamed into `sources/`
* when it is complete, so the compiler never reads half a package. The
* contents of `sources/<CID>` are fixed by the CID, so when two fetches
* store the same archive, whichever renames first wins and the other's
* copy is dropped.
*/
import {exists, mkdir, rename, rmdir, unlink, writeFileBytes} from 'zena:fs';
import {monotonic} from 'zena:time';
import {Cid} from 'atproto/cid';
import {SourceFile} from './archive.zena';
/** A package cache rooted at a directory. */
export final class PackageCache {
/** The cache directory, such as `~/.cache/zena/packages`. */
root: String;
new(root: String) : root = root;
/** Where the source archive `cid` is unpacked. */
sourceDir(cid: Cid): String {
return `${this.root}/sources/${cid.toString()}`;
}
/** Whether the source archive `cid` is unpacked in the cache. */
async hasSource(cid: Cid): Future<boolean> {
return await exists(this.sourceDir(cid));
}
/** Writes `files`, the contents of the source archive `cid`, into the cache. */
async storeSource(cid: Cid, files: FixedArray<SourceFile>): Future<void> {
let target = this.sourceDir(cid);
if (await exists(target)) {
return;
}
await makeDirectories(`${this.root}/sources`);
await makeDirectories(`${this.root}/tmp`);
let staging = `${this.root}/tmp/${cid.toString()}.${monotonic() as i64}`;
await mkdir(staging);
let made = new GrowableArray<String>();
try {
for (let file in files) {
await makeParents(staging, file.path, made);
await writeFileBytes(`${staging}/${file.path}`, file.contents);
}
await rename(staging, target);
} catch (e) {
await removeStaging(staging, files, made);
// Another fetch may have stored the same archive first.
if (!(await exists(target))) {
throw e;
}
}
}
}
/** Creates `path` and any of its parents that are missing. */
async function makeDirectories(path: String): Future<void> {
let missing = new GrowableArray<String>();
var current = path;
while (current != '' && current != '/' && !(await exists(current))) {
missing.push(current);
current = parentOf(current);
}
for (var i = missing.length - 1; i >= 0; i -= 1) {
await mkdir(missing[i]);
}
}
/**
* Creates the directories between `root` and the file `path` under it,
* recording each one it creates in `made`.
*/
async function makeParents(root: String, path: String, made: GrowableArray<String>): Future<void> {
for (var i = 0; i < path.length; i += 1) {
if (path.getByteAt(i) == 47) { // '/'
let dir = `${root}/${path.sliceBytes(0, i)}`;
if (!(await exists(dir))) {
await mkdir(dir);
made.push(dir);
}
}
}
}
/** Removes a staging directory that was not renamed into place. */
async function removeStaging(staging: String, files: FixedArray<SourceFile>,
made: GrowableArray<String>): Future<void> {
if (!(await exists(staging))) {
return;
}
for (let file in files) {
let path = `${staging}/${file.path}`;
if (await exists(path)) {
await unlink(path);
}
}
for (var i = made.length - 1; i >= 0; i -= 1) {
await rmdir(made[i]);
}
await rmdir(staging);
}
function parentOf(path: String): String {
for (var i = path.length - 1; i > 0; i -= 1) {
if (path.getByteAt(i) == 47) {
return path.sliceBytes(0, i);
}
}
return if (path.startsWith('/')) '/' else '';
}
- 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 |
|
|