@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/src/package-locking.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Serialize writers while allowing independent projects to share immutable cached Git objects. */
+export function withPackageLock(path, action) {
+    const deadline = Date.now() + 30000;
+    while (true) {
+        try {
+            mkdirSync(path);
+            break;
+        }
+        catch (error) {
+            if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+                throw error;
+            let stale = false;
+            try {
+                const pid = Number(readFileSync(join(path, 'pid'), 'utf8'));
+                if (!Number.isSafeInteger(pid) || pid < 1)
+                    throw new Error('Invalid lock owner');
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (error) {
+                    stale = !!error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH';
+                }
+            }
+            catch {
+                stale = existsSync(path) && Date.now() - statSync(path).mtimeMs > 180000;
+            }
+            if (stale) {
+                rmSync(path, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error('Another August package installation is still running. Let it finish, then retry. Lock: ' + path);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        }
+    }
+    try {
+        writeFileSync(join(path, 'pid'), String(process.pid));
+        return action();
+    }
+    finally {
+        rmSync(path, { recursive: true, force: true });
+    }
+}
+/** Network-backed installs keep the writer lock until the asynchronous action completes. */
+export async function withPackageLockAsync(path, action) {
+    const deadline = Date.now() + 30000;
+    while (true) {
+        try {
+            mkdirSync(path);
+            break;
+        }
+        catch (error) {
+            if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+                throw error;
+            let stale = false;
+            try {
+                const pid = Number(readFileSync(join(path, 'pid'), 'utf8'));
+                if (!Number.isSafeInteger(pid) || pid < 1)
+                    throw new Error('Invalid lock owner');
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (e) {
+                    stale = !!e && typeof e === 'object' && 'code' in e && e.code === 'ESRCH';
+                }
+            }
+            catch {
+                stale = existsSync(path) && Date.now() - statSync(path).mtimeMs > 180000;
+            }
+            if (stale) {
+                rmSync(path, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error('Another August installation is still running. Lock: ' + path);
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    try {
+        writeFileSync(join(path, 'pid'), String(process.pid));
+        return await action();
+    }
+    finally {
+        rmSync(path, { recursive: true, force: true });
+    }
+}

package/src/package-manager.js

@@ -2,9 +2,26 @@ 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 { x as extractArchive } from 'tar';
 import { loadConfig } from "./config.js";
+import { parse } from "./parser.js";
+import { isGitSource, materializeGit, sourceAlias } from "./git-packages.js";
+import { agentInstructions } from "./project-init.js";
+import { withPackageLock } from "./package-locking.js";
+import { validateNativeManifest, readNativeDescriptor } from "./native-contracts.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';
+/** Repository imports declare their dependencies beside the code that uses them. */
+export function packageSpecifications(sourceRoot, declared, overrides = new Map()) {
+    const specifications = { ...declared };
+    for (const path of sourcePaths(sourceRoot)) {
+        const file = parse(path, overrides.get(path) ?? readFileSync(path, 'utf8')).file;
+        for (const item of file.items)
+            if (item.kind === 'import' && isGitSource(item.from[0]))
+                specifications[sourceAlias(item.from[0])] = item.from[0];
+    }
+    return ordered(specifications);
+}
 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'));
@@ -38,8 +55,11 @@ export function sourcePaths(root) {
         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.isSymbolicLink()) {
+            if (entry.name.endsWith('.aug'))
+                throw new Error(`Package source cannot contain a symbolic link: ${file}`);
+            continue;
+        }
         if (entry.isDirectory())
             result.push(...sourcePaths(file));
         else if (entry.isFile() && entry.name.endsWith('.aug'))
@@ -48,10 +68,19 @@ export function sourcePaths(root) {
     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 ?? '') ||
+    const manifest = existsSync(join(directory, 'aug-package.json')) ? json(join(directory, 'aug-package.json')) : {
+        format: 1, name: 'aug-' + sourceAlias(realpathSync(directory)), version: '0.0.0', compiler: compilerVersion(),
+        source: existsSync(join(directory, 'export.aug')) ? '.' : 'src', dependencies: {}
+    };
+    if (![1, 2].includes(manifest.format) || !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 (manifest.format === 1 && manifest.native !== undefined)
+        throw new Error('Native packages require manifest format 2');
+    if (manifest.format === 2) {
+        manifest.native = validateNativeManifest(manifest.native);
+        readNativeDescriptor(directory, manifest.native);
+    }
     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));
@@ -64,12 +93,14 @@ export function readPackage(directory) {
             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)
+    const published = existsSync(join(directory, 'package.json')) ? json(join(directory, 'package.json')) : undefined;
+    if (published && (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');
+    const configuration = loadConfig(directory);
+    if (configuration.diagnostics.length)
+        throw new Error(`Invalid package configuration in ${directory}: ${configuration.diagnostics.map(issue => issue.message).join('; ')}`);
+    manifest.dependencies = { ...configuration.config.packages, ...manifest.dependencies };
+    const declared = manifest.dependencies ?? {};
     for (const alias of Object.keys(declared))
         assertAlias(sourceRoot, alias);
     return { manifest, sourceRoot };
@@ -81,6 +112,8 @@ function assertAlias(root, alias) {
         throw new Error(`Package alias ${alias} conflicts with a local module`);
 }
 function normalizeSpecifier(spec, root, requirePath = true) {
+    if (isGitSource(spec))
+        return spec;
     if (spec.startsWith('npm:')) {
         const match = /^npm:((?:@[^/]+\/)?[^@]+)@(.+)$/.exec(spec);
         if (!match || !npmName.test(match[1]) || !version.test(match[2]))
@@ -101,7 +134,7 @@ function normalizeSpecifier(spec, root, requirePath = true) {
 }
 function packageDigest(directory, sourceRoot) {
     const hash = createHash('sha256');
-    for (const file of [join(directory, 'aug-package.json'), join(directory, 'package.json'), ...sourcePaths(sourceRoot)].sort()) {
+    for (const file of [join(directory, 'aug-package.json'), join(directory, 'package.json'), join(directory, 'native.abi.json'), join(directory, 'THIRD_PARTY_NOTICES.md'), ...sourcePaths(sourceRoot)].filter(existsSync).sort()) {
         hash.update(relative(directory, file).replaceAll('\\', '/'));
         hash.update('\0');
         hash.update(readFileSync(file));
@@ -111,7 +144,7 @@ function packageDigest(directory, sourceRoot) {
 }
 /** 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: [] };
+    const result = { roots: new Map(), scopes: new Map(), diagnostics: [], specifications };
     if (!Object.keys(specifications).length)
         return result;
     try {
@@ -130,10 +163,12 @@ export function projectPackages(root, specifications, sourceFolder = root) {
             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 (JSON.stringify(entry.native) !== JSON.stringify(manifest.native))
+                throw new Error(`NATIVE_LOCK: Native metadata for ${entry.name} differs from its verified source manifest; 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 });
+            result.scopes.set(entry.path, { ...entry, native: manifest.native, directory, sourceRoot, specifications: manifest.dependencies ?? {} });
         }
         verifyIdentities(lock.packages);
         for (const scope of result.scopes.values()) {
@@ -179,76 +214,212 @@ export function projectPackages(root, specifications, sourceFolder = root) {
 }
 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');
+    if (process.error)
+        throw new Error(`Cannot install August packages: ${'code' in process.error && process.error.code === 'ENOENT' ? 'npm is missing from PATH. Install Node.js 24 or newer, which includes npm.' : process.error.message}\nRetry aug run after fixing the package installer.`);
+    if (process.status !== 0)
+        throw new Error(`August package installation failed.\n${(process.stderr || process.stdout || `npm exited ${process.status}`).trim()}\nCheck the package versions and paths in main.yaml, your network connection, and npm registry configuration. Retry aug run; use aug install for an explicit installation.`);
     return process.stdout;
 }
-export function installPackages(root, frozen = false, offline = false) {
+/** Running an application prepares its declared packages; checking remains read-only. */
+export function prepareRunPackages(root, offline = false, frozen = false) {
+    const loaded = loadConfig(root);
+    if (loaded.diagnostics.length)
+        return; // The checker renders the configuration's source diagnostics.
+    const library = isLibrary(root) ? readPackage(root) : undefined;
+    const specifications = packageSpecifications(library?.sourceRoot ?? root, library?.manifest.dependencies ?? loaded.config.packages);
+    const lockPath = join(root, 'aug.lock.json');
+    let lock;
+    if (existsSync(lockPath)) {
+        try {
+            lock = json(lockPath);
+        }
+        catch {
+            throw new Error('aug.lock.json is unreadable. Restore it from version control or run aug install to recreate it.');
+        }
+        if (lock?.format !== 1 || !Array.isArray(lock.packages) || !lock.specifications || typeof lock.specifications !== 'object')
+            throw new Error('aug.lock.json has an unsupported structure. Run aug install to recreate it.');
+    }
+    const matching = lock?.compiler === compilerVersion() && sameSpecifications(lock.specifications, specifications);
+    if (!matching) {
+        if (!lock && !Object.keys(specifications).length)
+            return;
+        if (frozen)
+            throw new Error('PACKAGE_LOCK: Frozen run requires a matching aug.lock.json for the current imports, configuration and compiler. Run aug install before retrying.');
+        process.stderr.write('Installing August packages declared by imports and main.yaml…\n');
+        installPackages(root, false, offline);
+        return;
+    }
+    const snapshot = resolve(root, '.aug-packages');
+    const missing = lock.packages.some(entry => {
+        if (typeof entry.path !== 'string' || isAbsolute(entry.path) || !inside(snapshot, resolve(snapshot, entry.path)))
+            throw new Error('Package lock contains a path outside its snapshot. Run aug install to recreate it.');
+        return !existsSync(resolve(snapshot, entry.path));
+    });
+    if (missing) {
+        process.stderr.write('Restoring August packages from aug.lock.json…\n');
+        installPackages(root, true, offline);
+    }
+    // projectPackages checks contents and integrity before compilation. Changed installed sources are never silently replaced.
+}
+export function installPackages(root, frozen = false, offline = false, update = false) {
+    return withPackageLock(join(root, '.aug-install.lock'), () => installLocked(root, frozen, offline, update));
+}
+function installLocked(root, frozen, offline, update) {
+    if (frozen && update)
+        throw new Error('--frozen and --update cannot be used together.');
     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);
+    const library = isLibrary(root) ? readPackage(root) : undefined;
+    const specifications = packageSpecifications(library?.sourceRoot ?? root, library?.manifest.dependencies ?? loaded.config.packages);
     for (const alias of Object.keys(specifications))
-        assertAlias(library ? resolve(root, library.source) : root, alias);
+        assertAlias(library?.sourceRoot ?? 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);
+    const same = !update && previous?.compiler === compilerVersion() && sameSpecifications(previous.specifications, specifications);
     if (frozen && !same)
         throw new Error('Frozen installation requires a matching aug.lock.json');
+    return installSourceGraph(root, specifications, frozen, offline, same ? previous : undefined);
+}
+const isLibrary = (root) => existsSync(join(root, 'aug-package.json')) ||
+    !existsSync(join(root, 'main.aug')) && (existsSync(join(root, 'export.aug')) || existsSync(join(root, 'src/export.aug')));
+const selectedSource = (file) => file.endsWith('.aug') || ['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE', 'native.abi.json', 'THIRD_PARTY_NOTICES.md'].includes(file);
+function copySource(origin, destination) {
+    let bytes = 0, count = 0;
+    const copy = (folder) => {
+        for (const entry of readdirSync(folder, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || ['node_modules', 'dist'].includes(entry.name))
+                continue;
+            const file = join(folder, entry.name), name = relative(origin, file);
+            if (entry.isDirectory())
+                copy(file);
+            else if (selectedSource(name)) {
+                if (!entry.isFile())
+                    throw new Error('Package source must contain regular files: ' + name);
+                const data = readFileSync(file);
+                bytes += data.length;
+                if (++count > 10000 || bytes > 32 * 1024 * 1024)
+                    throw new Error('Source package exceeds 10,000 files or 32 MiB.');
+                mkdirSync(dirname(join(destination, name)), { recursive: true });
+                writeFileSync(join(destination, name), data);
+            }
+        }
+    };
+    copy(origin);
+}
+function unpackSource(archive, destination) {
+    let bytes = 0, count = 0;
+    const paths = new Set();
+    extractArchive({ file: archive, cwd: destination, strip: 1, sync: true, strict: true, filter: (path, entry) => {
+            if (!('type' in entry))
+                throw new Error('Expected an archive entry.');
+            const parts = path.split('/');
+            if (isAbsolute(path) || path.includes('\\') || parts.some(part => part === '..'))
+                throw new Error('Package archive contains a path outside its folder.');
+            const name = parts.slice(1).join('/');
+            if (entry.type === 'Directory')
+                return false;
+            if (!selectedSource(name))
+                return false;
+            if (entry.type !== 'File' || !name || parts[0] !== 'package' || parts.slice(1).some(part => !part || part.startsWith('.')))
+                throw new Error('Package archive source must be regular files inside package/.');
+            if (paths.has(name))
+                throw new Error('Package archive repeats a source file: ' + name);
+            paths.add(name);
+            bytes += entry.size;
+            if (++count > 10000 || bytes > 32 * 1024 * 1024)
+                throw new Error('Source package exceeds 10,000 files or 32 MiB.');
+            return true;
+        } });
+}
+/** Git libraries use the same checked source graph as registry libraries. No remote program is executed. */
+function installSourceGraph(root, specifications, frozen, offline, previous) {
     const stage = realpathSync(mkdtempSync(join(root, '.aug-install-')));
+    const packages = new Map(), visited = new Map();
+    const gitSources = new Map();
+    const registry = {};
+    const locked = new Map((previous?.git ?? []).map(source => [source.request, source]));
+    const visit = (spec, owner) => {
+        const normalized = normalizeSpecifier(spec, owner);
+        if (visited.has(normalized))
+            return visited.get(normalized);
+        if (visited.size >= 1000)
+            throw new Error('Package graph exceeds 1,000 source packages.');
+        const identity = normalized.startsWith('file:') ? 'file:' + relative(root, normalized.slice(5)).replaceAll('\\', '/') : normalized;
+        const path = 'packages/' + sourceAlias(identity), directory = join(stage, path);
+        visited.set(normalized, path);
+        mkdirSync(directory, { recursive: true });
+        let origin = directory;
+        let source;
+        if (isGitSource(normalized)) {
+            source = materializeGit(normalized, directory, offline, locked.get(normalized));
+            gitSources.set(normalized, source);
+        }
+        else if (normalized.startsWith('file:') && lstatSync(normalized.slice(5)).isDirectory()) {
+            origin = normalized.slice(5);
+            copySource(origin, directory);
+        }
+        else {
+            const transport = join(stage, 'transport', sourceAlias(normalized));
+            mkdirSync(transport, { recursive: true });
+            const request = normalized.startsWith('npm:') ? normalized.slice(4) : normalized.slice(5);
+            const packed = JSON.parse(npm(['pack', request, '--ignore-scripts', '--json', '--pack-destination', transport,
+                ...(offline ? ['--offline'] : [])], transport))[0];
+            if (!packed?.filename || !/^sha512-[A-Za-z0-9+/=]+$/.test(packed.integrity ?? ''))
+                throw new Error('Package archive is missing its SHA-512 integrity.');
+            registry[normalized] = { integrity: packed.integrity, name: packed.name, version: packed.version };
+            const archive = join(transport, basename(packed.filename));
+            const actual = 'sha512-' + createHash('sha512').update(readFileSync(archive)).digest('base64');
+            if (actual !== packed.integrity)
+                throw new Error('Package archive integrity mismatch.');
+            if (frozen && JSON.stringify(previous?.npm?.[normalized]) !== JSON.stringify(registry[normalized]))
+                throw new Error('Frozen package archive changed. Publish a new version instead of replacing an archive.');
+            unpackSource(archive, directory);
+        }
+        if (!existsSync(join(directory, 'aug-package.json'))) {
+            const folder = existsSync(join(directory, 'export.aug')) ? '.' : 'src';
+            const published = existsSync(join(directory, 'package.json')) ? json(join(directory, 'package.json')) : undefined;
+            writeJson(join(directory, 'aug-package.json'), { format: 1,
+                name: published?.name ?? '@git/' + sourceAlias(source ? source.repository + '/' + source.folder : identity),
+                version: published?.version ?? (source ? '0.0.0-git.' + source.commit : '0.0.0'),
+                compiler: compilerVersion(), source: folder, dependencies: published?.dependencies ?? {} });
+        }
+        const manifest = json(join(directory, 'aug-package.json'));
+        // A Git folder owns its August manifest. npm metadata and lifecycle scripts have no role here.
+        const dependencies = packageSpecifications(resolve(directory, manifest.source), { ...loadConfig(directory).config.packages, ...manifest.dependencies });
+        manifest.dependencies = dependencies;
+        writeJson(join(directory, 'aug-package.json'), manifest);
+        writeJson(join(directory, 'package.json'), { name: manifest.name, version: manifest.version, private: true, dependencies });
+        const { sourceRoot } = readPackage(directory);
+        const entry = { path, name: manifest.name, version: manifest.version, source: manifest.source,
+            digest: packageDigest(directory, sourceRoot), dependencies: {}, ...(manifest.native ? { native: manifest.native } : {}) };
+        packages.set(path, entry);
+        for (const [alias, request] of Object.entries(dependencies)) {
+            entry.dependencies[alias] = visit(request, origin);
+            verifyReference(request, packages.get(entry.dependencies[alias]));
+        }
+        return path;
+    };
     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 roots = Object.fromEntries(Object.entries(specifications).map(([alias, request]) => [alias, visit(request, root)]));
+        verifyIdentities(packages.values());
+        const lock = { format: 1, compiler: compilerVersion(), specifications, roots, npm: registry,
+            git: [...gitSources.values()].sort((a, b) => a.request.localeCompare(b.request)),
+            packages: [...packages.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+        if (previous?.native && JSON.stringify(lock.packages) === JSON.stringify(previous.packages))
+            lock.native = previous.native;
+        if (frozen && JSON.stringify(lock.packages) !== JSON.stringify(previous?.packages))
+            throw new Error('Frozen package contents changed; use aug install --update to choose new revisions.');
+        rmSync(join(stage, 'transport'), { recursive: true, force: true });
         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');
+            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);
+            writeJson(join(root, 'aug.lock.json.tmp'), lock);
+            renameSync(join(root, 'aug.lock.json.tmp'), join(root, 'aug.lock.json'));
         }
         catch (error) {
             rmSync(cache, { recursive: true, force: true });
@@ -263,16 +434,18 @@ export function installPackages(root, frozen = false, offline = false) {
         rmSync(stage, { recursive: true, force: true });
     }
 }
-export function initPackage(directory, name) {
+export function initPackage(directory, name, npmMetadata = false) {
     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 });
+    writeFileSync(join(directory, 'AGENTS.md'), agentInstructions);
     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: {} });
+    if (npmMetadata)
+        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`);
@@ -281,11 +454,13 @@ export function initPackage(directory, name) {
 /** 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'));
+    const transport = existsSync(join(root, 'package.json')) ? 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'])];
+    if (manifest.native)
+        transport.files.push('native.abi.json', 'THIRD_PARTY_NOTICES.md');
     writeJson(join(root, 'package.json'), transport);
     readPackage(root);
 }
@@ -297,3 +472,27 @@ export function packPackage(root) {
         throw new Error('npm pack returned no archive');
     return join(destination, basename(result.filename));
 }
+/** Give a source package a short import name and install its verified dependency graph. */
+export function addPackage(root, request, alias, offline = false) {
+    const loaded = loadConfig(root);
+    if (loaded.diagnostics.length)
+        throw new Error(loaded.diagnostics.map(issue => issue.message).join('\n'));
+    assertAlias(isLibrary(root) ? readPackage(root).sourceRoot : root, alias);
+    normalizeSpecifier(request, root);
+    const path = join(root, 'main.yaml'), existed = existsSync(path), before = existed ? readFileSync(path, 'utf8') : '';
+    const dependencies = { ...loaded.config.packages, [alias]: request };
+    const block = 'packages:\n' + Object.entries(ordered(dependencies)).map(([name, value]) => '  ' + name + ': ' + JSON.stringify(value)).join('\n') + '\n';
+    const expression = /^packages:[^\n]*(?:\n|$)(?:[ \t][^\n]*(?:\n|$)|\n)*/m;
+    const after = expression.test(before) ? before.replace(expression, block) : before.trimEnd() + (before.trim() ? '\n\n' : '') + block;
+    writeFileSync(path, after);
+    try {
+        return installPackages(root, false, offline);
+    }
+    catch (error) {
+        if (existed)
+            writeFileSync(path, before);
+        else
+            rmSync(path, { force: true });
+        throw error;
+    }
+}

package/src/parser.js

@@ -218,8 +218,14 @@ class Parser {
             return { kind: 'composition', name, typeParams: [], bindings, span: this.span(start) };
         }
         if (this.at('extern')) {
-            this.take();
+            const start = this.take().span;
             this.expect('C');
+            if (this.current().value === 'resource') {
+                this.take();
+                const name = this.expect('identifier').value;
+                this.endStatement();
+                return { kind: 'resource', name, typeParams: [], span: this.span(start) };
+            }
             return this.parseFunction(true);
         }
         if (this.looksLikeBareClass())
@@ -395,6 +401,11 @@ class Parser {
             this.parseTypeParams();
             if (this.at('('))
                 this.parseParams(true);
+            if (this.match('unless')) {
+                this.parseType();
+                while (this.match('and') || this.match(','))
+                    this.parseType();
+            }
             if (this.match('=>')) {
                 return true;
             }
@@ -416,7 +427,9 @@ class Parser {
         while (!everything && this.match('and'))
             names.push(this.expect('identifier').value);
         this.expect('from');
-        const from = [this.expect('identifier').value];
+        const from = [this.at('string') ? this.take().value : this.expect('identifier').value];
+        if (!/^(?:https:\/\/|git\+(?:https|file):\/\/)/.test(from[0]) && this.tokens[this.position - 1].kind === 'string')
+            throw new ParseFailure({ ...start, code: 'IMPORT', message: 'A quoted import source must be a public repository URL' });
         while (this.match('.'))
             from.push(this.expect('identifier').value);
         this.endStatement();
@@ -462,11 +475,13 @@ class Parser {
         const header = this.parseTypeParams();
         const fields = this.parseParams(true);
         const validationErrors = [];
-        if (this.match('unless')) {
+        const validationDeclared = !!this.match('unless');
+        if (validationDeclared) {
             validationErrors.push(this.parseType());
             while (this.match('and') || this.match(','))
                 validationErrors.push(this.parseType());
         }
+        const headerEnd = this.current().span.start;
         let constructorBody = this.match('=>') ? this.parseBlock(start) : undefined;
         let hasBody = !!constructorBody;
         if (!constructorBody && (this.at('{') || this.at(':'))) {
@@ -486,13 +501,20 @@ class Parser {
         if (!hasBody)
             this.endStatement();
         return { kind: 'class', record: true, name, ...header, fields, constructorBody,
-            validationErrors, implements: [], methods: [], span: this.span(start) };
+            validationErrors, validationDeclared, headerEnd, implements: [], methods: [], span: this.span(start) };
     }
     parseClass() {
         const start = this.current().span;
         const name = this.expect('identifier').value;
         const { typeParams, typeConstraints, typeVariance } = this.parseTypeParams();
         const fields = this.at('(') ? this.parseParams(true) : [];
+        const validationErrors = [];
+        const validationDeclared = !!this.match('unless');
+        if (validationDeclared) {
+            validationErrors.push(this.parseType());
+            while (this.match('and') || this.match(','))
+                validationErrors.push(this.parseType());
+        }
         let constructorBody = this.match('=>') ? this.parseBlock(start) : undefined;
         const implemented = [];
         if (!this.at('implements'))
@@ -502,6 +524,7 @@ class Parser {
         implemented.push(this.parseType());
         while (this.match(','))
             implemented.push(this.parseType());
+        const headerEnd = this.current().span.start;
         this.openBlock(start);
         const methods = [];
         const stateFields = [];
@@ -537,7 +560,7 @@ class Parser {
         }
         this.closeBrace();
         return { kind: 'class', name, typeParams, typeConstraints, typeVariance, fields, stateFields, constructorBody,
-            implements: implemented, methods, span: this.span(start) };
+            validationErrors, validationDeclared, implements: implemented, methods, headerEnd, span: this.span(start) };
     }
     parseInterface() {
         const keyword = this.take();
@@ -638,13 +661,16 @@ class Parser {
                 } while (this.match(',') || this.match('and'));
             }
         }
+        const headerEnd = this.current().span.start;
         const body = this.at('{') || this.at(':') ? this.parseBlock(start) : (this.endStatement(), undefined);
         if (externC && body) {
             throw new ParseFailure({ file: start.file, line: start.line, column: start.column,
                 message: 'extern C functions cannot have a body', code: 'PARSE' });
         }
         return { kind: 'function', name, typeParams, typeConstraints, typeVariance, params, returns, returnOwnership,
-            throws, changes, uses, body, externC, valueAbi, nativePure, endpoint, annotations, span: this.span(start) };
+            throws, changes, uses, body, externC, valueAbi, nativePure, endpoint, annotations,
+            declared: { returns: clauses.has('returns') || clauses.has('streams'), errors: clauses.has('unless'),
+                changes: clauses.has('changes'), uses: clauses.has('uses') }, headerEnd, span: this.span(start) };
     }
     parseTypeParams() {
         if (!this.match('<'))