@greenpandastudios/aug-cli 0.19.0

package/src/ownership.js

@@ -0,0 +1,232 @@
+export const unionOrigins = (...sets) => new Set(sets.flatMap(set => [...set]));
+export const overlap = (left, right) => [...left].some(origin => right.has(origin));
+export const allocationOrigin = (span) => new Set([`new:${span.file}:${span.start}`]);
+/** Stable object origins survive rebinding; loans and branch joins stay private. */
+export class OwnershipFlow {
+    places = new Map();
+    loans = new Map();
+    borrowedInputs = new Set();
+    heap = new Map();
+    regions = [];
+    frozenOrigins = new Set();
+    taskLoans = new Map();
+    tasks = new Map();
+    clone() {
+        const copy = new OwnershipFlow();
+        copy.places = new Map([...this.places].map(([name, place]) => [name, { ...place }]));
+        copy.loans = new Map(this.loans);
+        copy.borrowedInputs = new Set(this.borrowedInputs);
+        copy.heap = new Map([...this.heap].map(([origin, fields]) => [origin, new Map(fields)]));
+        copy.regions = [...this.regions];
+        copy.frozenOrigins = new Set(this.frozenOrigins);
+        copy.taskLoans = new Map(this.taskLoans);
+        copy.tasks = new Map(this.tasks);
+        return copy;
+    }
+    origins(name) { return this.places.get(name)?.origins ?? new Set(); }
+    frozen(origins) { return overlap(origins, this.frozenOrigins); }
+    freeze(origins, span, report) {
+        const reachable = this.reachable(origins);
+        if ([...this.loans.values()].some(loan => overlap(loan.origins, reachable)))
+            report(span, 'Cannot freeze an active mutable borrow');
+        for (const origin of reachable)
+            this.frozenOrigins.add(origin);
+        for (const place of this.places.values())
+            if (overlap(this.reachable(place.origins), reachable))
+                place.readonly = true;
+    }
+    external(name) { return this.places.get(name)?.external; }
+    region(origins) { this.regions.push({ origins, outerNames: new Set(this.places.keys()) }); }
+    captureTask(task, scope, origins, exclusive, repeated, span, report) {
+        const reachable = this.reachable(origins);
+        for (const loan of this.taskLoans.values())
+            if ((exclusive || loan.exclusive) && overlap(reachable, loan.origins))
+                report(span, 'Task captures overlap an active task with mutable access');
+        const previous = this.taskLoans.get(task);
+        this.taskLoans.set(task, { scope, origins: unionOrigins(previous?.origins ?? new Set(), reachable),
+            exclusive: exclusive || !!previous?.exclusive, repeated: repeated || !!previous?.repeated });
+    }
+    waitTasks(origins, all) {
+        const reachable = this.reachable(origins);
+        const matches = [...this.tasks.keys()].filter(task => reachable.has(task));
+        // A Task<T> read from an indexed collection or branch may have several
+        // possible origins. Only a List<Task<T>> wait joins every matching child.
+        if (!all && matches.length !== 1)
+            return;
+        // A static start site in a loop can represent several live children. Waiting for
+        // one result cannot prove that earlier children from that site have finished.
+        for (const task of matches) {
+            if (!this.taskLoans.get(task)?.repeated)
+                this.taskLoans.delete(task);
+            const value = this.tasks.get(task);
+            this.tasks.set(task, { ...value, observed: true });
+        }
+    }
+    registerTask(task, scope, errors) {
+        this.tasks.set(task, { scope, errors, observed: false });
+    }
+    taskErrors(origins) {
+        const found = [...this.reachable(origins)].flatMap(origin => this.tasks.has(origin) ? [this.tasks.get(origin)] : []);
+        const scopes = new Set(found.map(task => task.scope));
+        return found.length ? [...found, ...[...this.tasks.values()].filter(task => !task.observed && scopes.has(task.scope))].flatMap(task => task.errors) : undefined;
+    }
+    hasTaskCapture(origins) {
+        const reachable = this.reachable(origins);
+        return [...this.taskLoans.values()].some(loan => overlap(loan.origins, reachable));
+    }
+    pendingTaskErrors(scope) {
+        return [...this.tasks.values()].filter(task => !task.observed && (!scope || task.scope === scope)).flatMap(task => task.errors);
+    }
+    joinTasks(scope) {
+        for (const [task, loan] of this.taskLoans)
+            if (loan.scope === scope)
+                this.taskLoans.delete(task);
+        for (const [task, value] of this.tasks)
+            if (value.scope === scope)
+                this.tasks.delete(task);
+    }
+    object(origins, fields) {
+        for (const origin of origins) {
+            const stored = this.heap.get(origin) ?? new Map();
+            for (const field of fields)
+                stored.set(field.name, { origins: unionOrigins(stored.get(field.name)?.origins ?? new Set(), field.origins),
+                    mutable: field.mutable || !!stored.get(field.name)?.mutable });
+            this.heap.set(origin, stored);
+        }
+    }
+    field(origins, name) {
+        return unionOrigins(...[...origins].map(origin => {
+            const fields = this.heap.get(origin);
+            if (!fields)
+                return new Set([origin]);
+            return name === undefined ? unionOrigins(...[...fields.values()].map(field => field.origins)) : fields.get(name)?.origins ?? new Set([origin]);
+        }));
+    }
+    reachable(origins, mutableOnly = false) {
+        const output = new Set(origins);
+        for (const origin of output)
+            for (const field of this.heap.get(origin)?.values() ?? [])
+                if (!mutableOnly || field.mutable)
+                    for (const child of field.origins)
+                        output.add(child);
+        return output;
+    }
+    declare(name, origins, readonly, options = {}) {
+        const source = options.source ? this.places.get(options.source) : undefined;
+        const grant = options.source ? this.activeGrant(options.source) : undefined;
+        this.places.set(name, { origins, readonly: readonly || !!source?.readonly || this.frozen(origins),
+            parent: options.parent, grant, external: options.external ?? source?.external });
+        if (options.borrowedInput)
+            for (const origin of origins)
+                this.borrowedInputs.add(origin);
+    }
+    rebind(name, origins, readonly, span, report, source) {
+        const place = this.places.get(name);
+        if (place && !place.parent && [...this.loans.values()].some(loan => overlap(loan.origins, this.reachable(place.origins, true))))
+            report(span, `Cannot rebind ${name} while its object is borrowed`);
+        if ([...this.loans.values()].some(loan => loan.outerNames.has(name) && overlap(loan.origins, this.reachable(origins))))
+            report(span, `A borrowed reference cannot escape into outer variable ${name}`);
+        if (this.regions.some(region => region.outerNames.has(name) && overlap(region.origins, this.reachable(origins))))
+            report(span, `A scoped reference cannot escape into outer variable ${name}`);
+        this.declare(name, origins, readonly, { source, external: place?.parent ? place.external : undefined, parent: place?.parent });
+    }
+    read(name, span, report) {
+        const place = this.places.get(name);
+        if (!place)
+            return;
+        if (![...place.origins].some(origin => this.taskLoans.has(origin)) &&
+            [...this.taskLoans.values()].some(loan => loan.exclusive && overlap(loan.origins, this.reachable(place.origins))))
+            report(span, `Cannot read ${name} while a task has mutable access; wait for the task first`);
+        for (const [borrower, loan] of this.loans) {
+            if (overlap(loan.origins, this.reachable(place.origins)) && name !== borrower && place.grant !== borrower && place.parent !== borrower)
+                report(span, `Cannot read ${name} while alias ${borrower} is mutably borrowed`);
+        }
+    }
+    borrow(name, span, report, implicit = false) {
+        const place = this.places.get(name);
+        if (!place)
+            return;
+        if (place.readonly)
+            report(span, `Cannot mutably borrow read-only ${name}`);
+        const reachable = this.reachable(place.origins, true);
+        if ([...this.taskLoans.values()].some(loan => overlap(loan.origins, reachable)))
+            report(span, `Cannot borrow ${name} while a task uses it; wait for the task first`);
+        for (const [other, loan] of this.loans)
+            if (overlap(loan.origins, reachable) &&
+                !(loan.implicit && (other === name || place.parent === other || place.grant === other)))
+                report(span, `${name} aliases active exclusive borrow ${other}`);
+        this.loans.set(name, { origins: reachable, implicit, outerNames: new Set(this.places.keys()) });
+    }
+    activeGrant(name) {
+        const place = this.places.get(name);
+        if (this.loans.has(name))
+            return name;
+        if (place?.grant && this.loans.has(place.grant))
+            return place.grant;
+        if (place?.parent && this.loans.has(place.parent))
+            return place.parent;
+        return undefined;
+    }
+    assertMove(name, span, report) {
+        const place = this.places.get(name);
+        if (place && [...this.loans.values()].some(loan => overlap(loan.origins, this.reachable(place.origins, true))))
+            report(span, `Cannot move ${name} while it is borrowed`);
+        if (place && this.hasTaskCapture(place.origins))
+            report(span, `Cannot move ${name} while a task uses it; wait for the task first`);
+    }
+    escape(origins, span, report, scoped = true, immutable = false) {
+        if (immutable)
+            return;
+        const reachable = this.reachable(origins);
+        if ([...reachable].some(origin => this.borrowedInputs.has(origin)) ||
+            [...this.loans.values()].some(loan => overlap(loan.origins, reachable)))
+            report(span, 'A borrowed reference cannot escape into storage or a return value');
+        if (scoped && this.regions.some(region => overlap(region.origins, reachable)))
+            report(span, 'A scoped reference cannot escape its composition scope');
+    }
+    assertDistinct(arguments_, report) {
+        arguments_.forEach((argument, index) => {
+            for (const other of arguments_.slice(0, index))
+                if ((argument.exclusive || other.exclusive) &&
+                    overlap(this.reachable(argument.origins, argument.exclusive), this.reachable(other.origins, other.exclusive)))
+                    report(argument.span, 'An exclusive argument aliases another argument in this call');
+        });
+    }
+    join(branches) {
+        this.taskLoans = new Map(branches.flatMap(branch => [...branch.taskLoans]));
+        this.tasks = new Map([...new Set(branches.flatMap(branch => [...branch.tasks.keys()]))].map(task => {
+            const values = branches.flatMap(branch => branch.tasks.has(task) ? [branch.tasks.get(task)] : []);
+            return [task, { ...values[0], errors: values.flatMap(value => value.errors), observed: values.every(value => value.observed) }];
+        }));
+        for (const branch of branches)
+            for (const origin of branch.frozenOrigins)
+                this.frozenOrigins.add(origin);
+        for (const branch of branches)
+            for (const [origin, fields] of branch.heap) {
+                const current = this.heap.get(origin) ?? new Map();
+                for (const [name, field] of fields)
+                    current.set(name, {
+                        origins: unionOrigins(current.get(name)?.origins ?? new Set(), field.origins),
+                        mutable: field.mutable || !!current.get(name)?.mutable,
+                    });
+                this.heap.set(origin, current);
+            }
+        for (const [name, place] of this.places) {
+            const versions = branches.map(branch => branch.places.get(name)).filter((value) => !!value);
+            place.origins = unionOrigins(place.origins, ...versions.map(value => value.origins));
+            place.readonly ||= versions.some(value => value.readonly);
+            if (versions.some(value => value.external !== place.external))
+                place.external = undefined;
+        }
+    }
+    signature() {
+        return JSON.stringify({ places: [...this.places].map(([name, place]) => [name, [...place.origins].sort(), place.readonly, place.external]),
+            tasks: [...this.tasks].map(([task, value]) => [task, value.observed]),
+            heap: [...this.heap].map(([origin, fields]) => [origin, [...fields].map(([name, field]) => [name, [...field.origins].sort(), field.mutable])]) });
+    }
+}
+export function sourceName(expression) {
+    if (expression.kind === 'call' && expression.callee.kind === 'member')
+        return sourceName(expression.callee.object);
+    return expression.kind === 'name' ? expression.name : expression.kind === 'member' ? sourceName(expression.object) : undefined;
+}

package/src/package-manager.js

@@ -0,0 +1,299 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadConfig } from "./config.js";
+export const compilerVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export const packageAlias = (name) => /^[a-z][a-z0-9_]*$/.test(name) && name !== 'august';
+const version = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/;
+const npmName = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const json = (file) => JSON.parse(readFileSync(file, 'utf8'));
+const writeJson = (file, data) => writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+const inside = (root, file) => file === root || file.startsWith(root + sep);
+const ordered = (values) => Object.fromEntries(Object.entries(values).sort(([a], [b]) => a.localeCompare(b)));
+const sameSpecifications = (left, right) => JSON.stringify(ordered(left)) === JSON.stringify(ordered(right));
+function verifyReference(spec, target) {
+    if (spec.startsWith('npm:') && spec !== `npm:${target.name}@${target.version}`)
+        throw new Error(`Package lock resolves ${spec} to incompatible ${target.name}@${target.version}`);
+}
+function verifyIdentities(packages) {
+    const entries = [...packages], paths = new Map(entries.map(entry => [entry.path, entry]));
+    const identities = new Map();
+    for (const entry of entries) {
+        const dependencies = Object.entries(entry.dependencies).sort(([a], [b]) => a.localeCompare(b)).map(([alias, path]) => {
+            const target = paths.get(path);
+            if (!target)
+                throw new Error('Package lock is missing a transitive dependency');
+            return [alias, `${target.name}@${target.version}`, target.digest];
+        });
+        const key = `${entry.name}@${entry.version}`, fingerprint = JSON.stringify([entry.digest, dependencies]);
+        if (identities.has(key) && identities.get(key) !== fingerprint)
+            throw new Error(`Conflicting contents or dependencies for ${key}; publish a new version for changed source`);
+        identities.set(key, fingerprint);
+    }
+}
+export function sourcePaths(root) {
+    const result = [];
+    for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith('.') || ['node_modules', 'dist'].includes(entry.name))
+            continue;
+        const file = join(root, entry.name);
+        if (entry.isSymbolicLink())
+            throw new Error(`Package source cannot contain a symlink: ${file}`);
+        if (entry.isDirectory())
+            result.push(...sourcePaths(file));
+        else if (entry.isFile() && entry.name.endsWith('.aug'))
+            result.push(file);
+    }
+    return result;
+}
+export function readPackage(directory) {
+    const manifest = json(join(directory, 'aug-package.json'));
+    if (manifest.format !== 1 || !npmName.test(manifest.name ?? '') || !version.test(manifest.version ?? '') ||
+        manifest.compiler !== compilerVersion())
+        throw new Error(`Invalid August package or compiler mismatch in ${directory}; expected compiler ${compilerVersion()}`);
+    if (typeof manifest.source !== 'string' || !manifest.source || isAbsolute(manifest.source))
+        throw new Error('Package source must be a relative folder');
+    const sourceRoot = realpathSync(resolve(directory, manifest.source));
+    if (!inside(realpathSync(directory), sourceRoot))
+        throw new Error('Package source cannot escape its package directory');
+    if (!existsSync(join(sourceRoot, 'export.aug')))
+        throw new Error(`${manifest.name} requires export.aug in its source folder`);
+    for (const [alias, spec] of Object.entries(manifest.dependencies ?? {})) {
+        if (!packageAlias(alias) || typeof spec !== 'string')
+            throw new Error(`Invalid package dependency ${alias}`);
+        normalizeSpecifier(spec, directory, false);
+    }
+    const published = json(join(directory, 'package.json'));
+    if (published.name !== manifest.name || published.version !== manifest.version)
+        throw new Error('package.json and aug-package.json names/versions must match');
+    const declared = manifest.dependencies ?? {}, actual = published.dependencies ?? {};
+    if (Object.keys(actual).length !== Object.keys(declared).length || Object.entries(declared).some(([alias, spec]) => actual[alias] !== spec))
+        throw new Error('package.json dependencies must match the August dependency aliases; aug package pack synchronizes them');
+    for (const alias of Object.keys(declared))
+        assertAlias(sourceRoot, alias);
+    return { manifest, sourceRoot };
+}
+function assertAlias(root, alias) {
+    if (!packageAlias(alias))
+        throw new Error(`Package alias ${alias} must be lowercase and cannot be august or private`);
+    if (existsSync(join(root, alias)) || existsSync(join(root, alias + '.aug')))
+        throw new Error(`Package alias ${alias} conflicts with a local module`);
+}
+function normalizeSpecifier(spec, root, requirePath = true) {
+    if (spec.startsWith('npm:')) {
+        const match = /^npm:((?:@[^/]+\/)?[^@]+)@(.+)$/.exec(spec);
+        if (!match || !npmName.test(match[1]) || !version.test(match[2]))
+            throw new Error(`Use an exact registry version: npm:@owner/package@1.2.3 (${spec})`);
+        return spec;
+    }
+    const path = spec.startsWith('file:') ? spec.slice(5) : spec;
+    if (!path.startsWith('.') && !isAbsolute(path))
+        throw new Error(`Use a local path or npm:name@version: ${spec}`);
+    const absolute = resolve(root, path);
+    if (!requirePath)
+        return 'file:' + absolute;
+    if (!existsSync(absolute))
+        throw new Error(`Package path does not exist: ${path}`);
+    if (!lstatSync(absolute).isDirectory() && !absolute.endsWith('.tgz'))
+        throw new Error('Local packages must be folders or .tgz archives');
+    return 'file:' + realpathSync(absolute);
+}
+function packageDigest(directory, sourceRoot) {
+    const hash = createHash('sha256');
+    for (const file of [join(directory, 'aug-package.json'), join(directory, 'package.json'), ...sourcePaths(sourceRoot)].sort()) {
+        hash.update(relative(directory, file).replaceAll('\\', '/'));
+        hash.update('\0');
+        hash.update(readFileSync(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+/** Compilation reads only a verified installed snapshot. It never fetches dependencies. */
+export function projectPackages(root, specifications, sourceFolder = root) {
+    const result = { roots: new Map(), scopes: new Map(), diagnostics: [] };
+    if (!Object.keys(specifications).length)
+        return result;
+    try {
+        const lock = json(join(root, 'aug.lock.json'));
+        if (lock.format !== 1 || lock.compiler !== compilerVersion() || !sameSpecifications(lock.specifications, specifications))
+            throw new Error('Package lock does not match this project/compiler; run aug install');
+        const cache = realpathSync(join(root, '.aug-packages'));
+        const manifests = new Map();
+        for (const entry of lock.packages) {
+            if (isAbsolute(entry.path))
+                throw new Error('Invalid absolute package lock path');
+            const directory = realpathSync(resolve(cache, entry.path));
+            if (!inside(cache, directory))
+                throw new Error('Package lock path escapes the installed snapshot');
+            const { manifest, sourceRoot } = readPackage(directory);
+            if (manifest.name !== entry.name || manifest.version !== entry.version || manifest.source !== entry.source ||
+                packageDigest(directory, sourceRoot) !== entry.digest)
+                throw new Error(`Installed ${entry.name} changed; run aug install`);
+            if (result.scopes.has(entry.path))
+                throw new Error('Duplicate package lock path');
+            manifests.set(entry.path, manifest);
+            result.scopes.set(entry.path, { ...entry, directory, sourceRoot });
+        }
+        verifyIdentities(lock.packages);
+        for (const scope of result.scopes.values()) {
+            const declared = manifests.get(scope.path).dependencies ?? {};
+            if (!sameSpecifications(Object.fromEntries(Object.keys(declared).map(alias => [alias, ''])), Object.fromEntries(Object.keys(scope.dependencies).map(alias => [alias, '']))))
+                throw new Error('Package lock dependency aliases changed');
+            for (const [alias, path] of Object.entries(scope.dependencies))
+                verifyReference(declared[alias], result.scopes.get(path));
+        }
+        // One package identity has one set of declarations, even when npm installs duplicate copies.
+        const canonical = new Map();
+        for (const [path, scope] of result.scopes) {
+            const identity = `${scope.name}@${scope.version}`;
+            if (canonical.has(identity))
+                result.scopes.set(path, canonical.get(identity));
+            else
+                canonical.set(identity, scope);
+        }
+        for (const [alias, path] of Object.entries(lock.roots)) {
+            assertAlias(sourceFolder, alias);
+            if (!(alias in specifications))
+                throw new Error('Package lock contains an undeclared root dependency');
+            const scope = result.scopes.get(path);
+            if (!scope)
+                throw new Error(`Missing package ${alias}`);
+            verifyReference(specifications[alias], scope);
+            result.roots.set(alias, scope);
+        }
+        if (Object.keys(specifications).some(alias => !result.roots.has(alias)))
+            throw new Error('Package lock is missing a requested dependency');
+        for (const scope of result.scopes.values())
+            for (const path of Object.values(scope.dependencies))
+                if (!result.scopes.has(path))
+                    throw new Error('Package lock is missing a transitive dependency');
+    }
+    catch (error) {
+        result.roots.clear();
+        result.scopes.clear();
+        result.diagnostics.push({ file: join(root, 'main.yaml'), line: 1, column: 1, code: 'PACKAGE',
+            message: `${error.message}. Install dependencies with aug install ${root}` });
+    }
+    return result;
+}
+function npm(args, cwd) {
+    const process = spawnSync('npm', args, { cwd, encoding: 'utf8', timeout: 120000 });
+    if (process.error || process.status !== 0)
+        throw new Error(process.error?.message ?? process.stderr ?? 'npm failed');
+    return process.stdout;
+}
+export function installPackages(root, frozen = false, offline = false) {
+    const loaded = loadConfig(root);
+    if (loaded.diagnostics.length)
+        throw new Error(loaded.diagnostics.map(issue => issue.message).join('\n'));
+    const library = existsSync(join(root, 'aug-package.json')) ? json(join(root, 'aug-package.json')) : undefined;
+    if (library)
+        preparePackage(root);
+    const specifications = ordered(library?.dependencies ?? loaded.config.packages);
+    for (const alias of Object.keys(specifications))
+        assertAlias(library ? resolve(root, library.source) : root, alias);
+    const lockPath = join(root, 'aug.lock.json');
+    const previous = existsSync(lockPath) ? json(lockPath) : undefined;
+    const same = previous?.compiler === compilerVersion() && sameSpecifications(previous.specifications, specifications);
+    if (frozen && !same)
+        throw new Error('Frozen installation requires a matching aug.lock.json');
+    const stage = realpathSync(mkdtempSync(join(root, '.aug-install-')));
+    try {
+        const dependencies = Object.fromEntries(Object.entries(specifications).map(([alias, spec]) => {
+            const normalized = normalizeSpecifier(spec, root);
+            return [alias, normalized.startsWith('file:') ? 'file:' + relative(stage, normalized.slice(5)).replaceAll('\\', '/') : normalized];
+        }));
+        writeJson(join(stage, 'package.json'), { name: 'august-project-dependencies', version: '0.0.0', private: true, dependencies });
+        if (same && previous?.npm)
+            writeJson(join(stage, 'package-lock.json'), previous.npm);
+        npm([frozen ? 'ci' : 'install', '--ignore-scripts', '--install-links', '--bin-links=false', '--no-audit', '--no-fund',
+            ...(offline ? ['--offline'] : [])], stage);
+        const packages = new Map();
+        const visit = (directory) => {
+            const actual = realpathSync(directory);
+            if (!inside(stage, actual))
+                throw new Error('Package installer did not create a self-contained snapshot');
+            const path = relative(stage, actual).replaceAll('\\', '/');
+            if (packages.has(path))
+                return path;
+            const { manifest, sourceRoot } = readPackage(actual);
+            const entry = { path, name: manifest.name, version: manifest.version, source: manifest.source,
+                digest: packageDigest(actual, sourceRoot), dependencies: {} };
+            packages.set(path, entry);
+            for (const alias of Object.keys(manifest.dependencies ?? {})) {
+                let owner = actual;
+                while (inside(stage, owner) && !existsSync(join(owner, 'node_modules', alias, 'aug-package.json')))
+                    owner = dirname(owner);
+                if (!inside(stage, owner))
+                    throw new Error(`${manifest.name} is missing dependency ${alias}`);
+                entry.dependencies[alias] = visit(join(owner, 'node_modules', alias));
+                verifyReference(manifest.dependencies[alias], packages.get(entry.dependencies[alias]));
+            }
+            return path;
+        };
+        const roots = Object.fromEntries(Object.keys(specifications).map(alias => [alias, visit(join(stage, 'node_modules', alias))]));
+        const lock = { format: 1, compiler: compilerVersion(), specifications, roots,
+            packages: [...packages.values()].sort((a, b) => a.path.localeCompare(b.path)), npm: json(join(stage, 'package-lock.json')) };
+        verifyIdentities(lock.packages);
+        for (const [alias, path] of Object.entries(roots))
+            verifyReference(specifications[alias], packages.get(path));
+        if (frozen && JSON.stringify(lock.packages) !== JSON.stringify(previous.packages))
+            throw new Error('Frozen package contents changed; update the lock explicitly with aug install');
+        const cache = join(root, '.aug-packages'), backup = join(root, '.aug-packages-old');
+        if (existsSync(backup))
+            throw new Error('Previous package install backup exists; inspect .aug-packages-old before installing');
+        if (existsSync(cache))
+            renameSync(cache, backup);
+        try {
+            renameSync(stage, cache);
+            writeJson(lockPath + '.tmp', lock);
+            renameSync(lockPath + '.tmp', lockPath);
+        }
+        catch (error) {
+            rmSync(cache, { recursive: true, force: true });
+            if (existsSync(backup))
+                renameSync(backup, cache);
+            throw error;
+        }
+        rmSync(backup, { recursive: true, force: true });
+        return lock;
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+    }
+}
+export function initPackage(directory, name) {
+    if (!npmName.test(name))
+        throw new Error('Package name must be an npm name, for example @owner/aug-math');
+    if (existsSync(directory) && readdirSync(directory).length)
+        throw new Error('Package init requires a new or empty directory');
+    mkdirSync(join(directory, 'src'), { recursive: true });
+    const manifest = { format: 1, name, version: '0.1.0', compiler: compilerVersion(), source: 'src', dependencies: {} };
+    writeJson(join(directory, 'aug-package.json'), manifest);
+    writeJson(join(directory, 'package.json'), { name, version: manifest.version, description: 'An August source library',
+        files: ['src', '.aug-spec', 'aug-package.json', 'README.md', 'LICENSE'], exports: { './aug-package.json': './aug-package.json' }, dependencies: {} });
+    writeFileSync(join(directory, 'src/export.aug'), 'export add from arithmetic\n');
+    writeFileSync(join(directory, 'src/arithmetic.aug'), '/** Add two integers. @param left First value. @param right Second value. @return Their sum. */\nadd(int left, int right) returns int {\n    return left + right\n}\n\ntest add {\n    when addition {\n        it adds_two_integers {\n            assert(add(left=2, right=3) == 5)\n        }\n    }\n}\n');
+    writeFileSync(join(directory, 'README.md'), `# ${name}\n\nAugust ${compilerVersion()} source library. Public exports live in src/export.aug.\n`);
+    writeFileSync(join(directory, '.gitignore'), '.aug-build/\n.aug-packages/\n.aug-install-*/\nnode_modules/\n*.tgz\n');
+}
+/** Synchronize transport metadata; August's manifest owns dependency aliases. */
+export function preparePackage(root) {
+    const manifest = json(join(root, 'aug-package.json'));
+    const transport = json(join(root, 'package.json'));
+    transport.name = manifest.name;
+    transport.version = manifest.version;
+    transport.dependencies = manifest.dependencies ?? {};
+    transport.files = [...new Set([...(Array.isArray(transport.files) ? transport.files : ['README.md', 'LICENSE']), manifest.source, '.aug-spec', 'aug-package.json'])];
+    writeJson(join(root, 'package.json'), transport);
+    readPackage(root);
+}
+export function packPackage(root) {
+    const destination = join(root, '.aug-build/packages');
+    mkdirSync(destination, { recursive: true });
+    const result = JSON.parse(npm(['pack', '--ignore-scripts', '--json', '--pack-destination', destination], root))[0];
+    if (!result?.filename)
+        throw new Error('npm pack returned no archive');
+    return join(destination, basename(result.filename));
+}