@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/src/openapi.js

@@ -1,3 +1,4 @@
+import { callableResult } from "./contracts.js";
 import { createHash } from 'node:crypto';
 import { schemaType } from "./schemas.js";
 import { callableDocumentation } from "./documentation.js";
@@ -81,7 +82,7 @@ export function generateOpenApi(checked) {
                 result.push({ status: fn.endpoint?.status ?? 200, type: primitive('void') });
                 return;
             }
-            const type = checked.expressionTypes.get(expr) ?? schemaType(project, fn.returns, fn.span.file);
+            const type = checked.expressionTypes.get(expr) ?? callableResult(checked, fn);
             if (expr.kind === 'call' && expr.callee.kind === 'name' && type.name === 'HttpResponse') {
                 if (expr.callee.name !== 'HttpResponse') {
                     const def = project.scopes.get(fn.span.file)?.get(expr.callee.name);
@@ -125,8 +126,8 @@ export function generateOpenApi(checked) {
             }
             result.push({ status: fn.endpoint?.status ?? 200, type });
         });
-        if (!result.length && fn.returns.name !== 'HttpResponse')
-            result.push({ status: fn.endpoint?.status ?? 200, type: schemaType(project, fn.returns, fn.span.file) });
+        if (!result.length && callableResult(checked, fn).name !== 'HttpResponse')
+            result.push({ status: fn.endpoint?.status ?? 200, type: callableResult(checked, fn) });
         return result;
     };
     const served = new Map();
@@ -152,7 +153,7 @@ export function generateOpenApi(checked) {
                 current.schema = { oneOf: [current.schema, value] };
         };
         if (endpoint.streams) {
-            const item = schemaType(project, fn.returns, fn.span.file), sse = item.name === 'ServerEvent';
+            const item = callableResult(checked, fn), sse = item.name === 'ServerEvent';
             const itemSchema = sse ? { type: 'object', required: ['data'], properties: { data: { type: 'string', contentMediaType: 'application/json', contentSchema: schema(item.args[0], fn.span) }, id: { type: 'string' }, event: { type: 'string' }, retry: { type: 'integer', minimum: 0 } } } : schema(item, fn.span);
             responses[endpoint.status] = { description: 'Streaming response', content: { [sse ? 'text/event-stream' : item.name === 'Html' ? 'text/html' : 'application/octet-stream']: { itemSchema } } };
         }

package/src/package-locking.js

@@ -0,0 +1,45 @@
+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 });
+    }
+}

package/src/package-manager.js

@@ -2,9 +2,25 @@ 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";
 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 +54,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,7 +67,10 @@ export function sourcePaths(root) {
     return result;
 }
 export function readPackage(directory) {
-    const manifest = json(join(directory, 'aug-package.json'));
+    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 (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()}`);
@@ -64,12 +86,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 +105,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 +127,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'), ...sourcePaths(sourceRoot)].filter(existsSync).sort()) {
         hash.update(relative(directory, file).replaceAll('\\', '/'));
         hash.update('\0');
         hash.update(readFileSync(file));
@@ -111,7 +137,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 {
@@ -133,7 +159,7 @@ export function projectPackages(root, specifications, sourceFolder = root) {
             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, directory, sourceRoot, specifications: manifest.dependencies ?? {} });
         }
         verifyIdentities(lock.packages);
         for (const scope of result.scopes.values()) {
@@ -179,76 +205,208 @@ 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) {
+    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);
+    if (!Object.keys(specifications).length)
+        return;
+    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) {
+        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'].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: {} };
+        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 (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 +421,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,7 +441,7 @@ 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 ?? {};
@@ -297,3 +457,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

@@ -416,7 +416,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 +464,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,7 +490,7 @@ 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;
@@ -502,6 +506,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 +542,7 @@ class Parser {
         }
         this.closeBrace();
         return { kind: 'class', name, typeParams, typeConstraints, typeVariance, fields, stateFields, constructorBody,
-            implements: implemented, methods, span: this.span(start) };
+            implements: implemented, methods, headerEnd, span: this.span(start) };
     }
     parseInterface() {
         const keyword = this.take();
@@ -638,13 +643,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('<'))

package/src/policies.js

@@ -85,11 +85,11 @@ export function projectPolicies(project) {
                     if (!params.some(param => (param.label ?? param.name) === label))
                         report(node.span, `@param ${label} does not name a public input of ${node.name}`, 'DOC');
                 for (const tag of doc.tags ?? []) {
-                    if (['return', 'returns'].includes(tag.name) && !('returns' in node && node.returns.name !== 'void'))
+                    if (node.kind !== 'function' && ['return', 'returns'].includes(tag.name))
                         report(node.span, `@${tag.name} requires a value-returning callable`, 'DOC');
-                    if (['throws', 'exception'].includes(tag.name)) {
+                    if (node.kind !== 'function' && !(node.kind === 'class' && node.record && node.validationDeclared === false) && ['throws', 'exception'].includes(tag.name)) {
                         const name = tag.value.split(/\s/)[0];
-                        const errors = 'throws' in node ? node.throws : 'validationErrors' in node ? node.validationErrors ?? [] : [];
+                        const errors = node.kind === 'class' ? node.validationErrors ?? [] : [];
                         if (!('annotations' in node && node.annotations?.length) && !errors.some(error => error.name === name))
                             report(node.span, `@${tag.name} ${name} is absent from ${node.name}'s unless contract`, 'DOC');
                     }