@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/examples/weather-api/forecasts.aug.md

@@ -0,0 +1,32 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `forecasts.aug`
+
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
+
+<a id="symbol-WeatherForecast"></a>
+## `WeatherForecast` · immutable record · [source](forecasts.aug#L3)
+
+The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. It takes `date` as a string, kept read-only, `temperatureC` and `temperatureF` as integers, kept read-only, and `summary` as a string, kept read-only.
+
+<a id="symbol-weatherForecast"></a>
+## `weatherForecast` · [source](forecasts.aug#L6)
+
+`weatherForecast` handles `GET /weatherforecast`. Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. It returns a list of 5 [`WeatherForecast`](forecasts.aug.md#symbol-WeatherForecast) records, with `(date, temperatureC, temperatureF, summary)` values of `("2026-01-01", 0, 32, "Freezing")`, `("2026-01-02", 10, 50, "Cool")`, `("2026-01-03", 20, 68, "Mild")`, `("2026-01-04", 30, 86, "Warm")`, and `("2026-01-05", 35, 95, "Hot")`, in that order.
+
+<a id="symbol-test weatherForecast client"></a>
+## `test weatherForecast client` · [source](forecasts.aug#L40)
+
+Tests [`weatherForecast`](forecasts.aug.md#symbol-weatherForecast). Each case gets fresh setup and dependencies.
+
+### `forecasts`
+
+#### `returns_json` · [source](forecasts.aug#L42)
+
+It sets `response` to `client.request` with `method` `"GET"` and `path` `"/weatherforecast"`. The test requires `response.status` equals `200`.
+
+#### `rejects_other_methods` · [source](forecasts.aug#L45)
+
+It sets `response` to `client.request` with `method` `"POST"` and `path` `"/weatherforecast"`. The test requires `response.status` equals `405`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/weather-api/main.aug

@@ -0,0 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import weatherForecast from forecasts
+
+serve weatherForecast on port 8787

package/examples/weather-api/main.aug.md

@@ -0,0 +1,15 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug`
+
+## HTTP configuration
+
+Listen on `127.0.0.1`. Limit request bodies to 1048576 bytes and buffered responses to 4194304 bytes. Serve OpenAPI at `/openapi.json` and API docs at `/docs`.
+
+## Startup
+
+It serves [`weatherForecast`](forecasts.aug.md#symbol-weatherForecast) on port `8787`.
+
+## Dependencies
+
+It uses [`weatherForecast`](forecasts.aug.md#symbol-weatherForecast) from `forecasts`.

package/examples/weather-api/main.yaml

@@ -0,0 +1,5 @@
+block_style: indent
+openapi:
+  enabled: true
+  title: "Weather forecast API"
+  version: "0.1.0"

package/examples/weather-api/weather.http

@@ -0,0 +1,5 @@
+### Five simulated forecasts
+GET http://127.0.0.1:8787/weatherforecast
+
+### Generated OpenAPI document
+GET http://127.0.0.1:8787/openapi.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@greenpandastudios/aug-cli",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "August compiler, native build CLI, tests and language server",
   "type": "module",
   "license": "MIT",
@@ -23,9 +23,8 @@
     "THIRD_PARTY_NOTICES.md"
   ],
   "dependencies": {
-    "@greenpandastudios/aug-stdlib": "0.19.0",
-    "@greenpandastudios/aug-web": "0.19.0",
-    "@greenpandastudios/aug-crypto": "0.19.0"
+    "@greenpandastudios/aug-stdlib": "0.20.1",
+    "tar": "7.5.22"
   },
   "publishConfig": {
     "access": "public",

package/scripts/bootstrap-native.mjs

@@ -1,121 +1,196 @@
 #!/usr/bin/env node
 /** Build the pinned C dependencies privately; never install into system directories. */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync, renameSync, rmSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { availableParallelism } from 'node:os';
 import { nativeHome } from './native-home.mjs';
+import { cCompiler, requireBuildTool } from './native-toolchain.mjs';
+import { dependencyArtifacts, dependencyReady } from './native-setup.mjs';
 
-const root = resolve(import.meta.dirname, '..');
-const lock = JSON.parse(readFileSync(join(import.meta.dirname, 'native-dependencies.lock.json'), 'utf8'));
-const extractOnly = process.argv.includes('--extract-only');
-const onlyIndex = process.argv.indexOf('--only');
-const selected = onlyIndex >= 0 ? process.argv[onlyIndex + 1]?.split(',') : undefined;
-if (onlyIndex >= 0 && (!extractOnly || !selected?.length || selected.some(name => !lock.dependencies.some(dependency => dependency.name === name))))
-  throw new Error('--only requires --extract-only and comma-separated names from native-dependencies.lock.json.');
-const directory = nativeHome(root);
-const prefix = join(directory, 'prefix');
-const downloads = join(directory, 'downloads');
-const sources = join(directory, 'sources');
-const logs = join(directory, 'logs');
-for (const path of [prefix, downloads, sources, logs]) mkdirSync(path, { recursive: true });
-if (!extractOnly && !lock.platforms.includes(process.platform)) throw new Error(`Full native bootstrap supports ${lock.platforms.join(' and ')}; this host is ${process.platform}. Use --extract-only --only minicoro,yyjson for portable source dependencies.`);
-
-function run(command, args, cwd, label, env = process.env) {
-  const path = join(logs, label + '.log');
-  const descriptor = openSync(path, 'w');
-  let result;
-  try { result = spawnSync(command, args, { cwd, env, stdio: ['ignore', descriptor, descriptor] }); }
-  finally { closeSync(descriptor); }
-  if (result.error || result.status !== 0) throw new Error(`${label} failed: ${result.error?.message ?? result.status}. See ${path}\n` + readFileSync(path, 'utf8').split('\n').slice(-24).join('\n'));
-}
-
-const dependencies = lock.dependencies.filter(dependency => (!dependency.platforms || dependency.platforms.includes(process.platform)) && (!selected || selected.includes(dependency.name)));
-if (selected?.some(name => !dependencies.some(dependency => dependency.name === name)))
-  throw new Error(`One or more selected dependencies do not support ${process.platform}.`);
-for (const dependency of dependencies) {
-  const archive = join(downloads, dependency.archive);
-  if (!existsSync(archive)) {
-    process.stdout.write(`Downloading ${dependency.name} ${dependency.version}\n`);
-    const response = await fetch(dependency.url);
-    if (!response.ok) throw new Error(`${dependency.name}: HTTP ${response.status}`);
-    writeFileSync(archive, Buffer.from(await response.arrayBuffer()));
+async function setup() {
+  if (Number(process.versions.node.split('.')[0]) < 24) throw new Error(`August native setup needs Node.js 24 or newer; this is ${process.versions.node}.`);
+  if (process.argv.includes('--help')) {
+    process.stdout.write('Usage: aug-native [--profile crypto|web] [--offline]\n       aug-native --extract-only [--only minicoro,yyjson] [--offline]\n\nNative commands prepare dependencies automatically. Use this command to prewarm a cache without running a program.\nAUG_NATIVE_HOME selects the cache; system build tools remain prerequisites.\n');
+    return;
   }
-  const hash = createHash('sha256').update(readFileSync(archive)).digest('hex');
-  if (hash !== dependency.sha256) throw new Error(`${dependency.name}: archive checksum mismatch`);
-  const source = join(sources, dependency.name);
-  if (!existsSync(join(source, '.archive-sha256'))) {
-    mkdirSync(source, { recursive: true });
-    run('/usr/bin/tar', ['-xf', archive, '-C', source, '--strip-components=1'], directory, 'extract-' + dependency.name);
-    writeFileSync(join(source, '.archive-sha256'), hash + '\n');
-  } else if (readFileSync(join(source, '.archive-sha256'), 'utf8').trim() !== hash) {
-    throw new Error(`${dependency.name}: source tree differs from the dependency lock; choose a new build directory.`);
+  for (let index = 2; index < process.argv.length; index++) {
+    const option = process.argv[index];
+    if (['--only', '--profile'].includes(option)) {
+      if (!process.argv[index + 1] || process.argv[index + 1].startsWith('--')) throw new Error(`${option} needs a value. See aug-native --help.`);
+      index++;
+    } else if (!['--extract-only', '--offline'].includes(option)) throw new Error(`Unknown option ${option}. See aug-native --help.`);
   }
+  const root = resolve(import.meta.dirname, '..');
+  const lock = JSON.parse(readFileSync(join(import.meta.dirname, 'native-dependencies.lock.json'), 'utf8'));
+  const extractOnly = process.argv.includes('--extract-only');
+  const onlyIndex = process.argv.indexOf('--only');
+  const selected = onlyIndex >= 0 ? process.argv[onlyIndex + 1]?.split(',') : undefined;
+  const profileIndex = process.argv.indexOf('--profile');
+  const profile = profileIndex >= 0 ? process.argv[profileIndex + 1] : 'web';
+  const offline = process.argv.includes('--offline');
+  if (!['crypto', 'web'].includes(profile)) throw new Error('Use --profile crypto or --profile web.');
+  if (onlyIndex >= 0 && (!extractOnly || !selected?.length || selected.some(name => !lock.dependencies.some(dependency => dependency.name === name))))
+    throw new Error('--only requires --extract-only and comma-separated names from native-dependencies.lock.json.');
+  const directory = nativeHome(root);
+  const prefix = join(directory, 'prefix');
+  const downloads = join(directory, 'downloads');
+  const sources = join(directory, 'sources');
+  const logs = join(directory, 'logs');
+  for (const path of [prefix, downloads, sources, logs]) mkdirSync(path, { recursive: true });
+  if (!extractOnly && !lock.platforms.includes(process.platform)) throw new Error(`Full native bootstrap supports ${lock.platforms.join(' and ')}; this host is ${process.platform}. Use --extract-only --only minicoro,yyjson for portable source dependencies.`);
+  const cc = extractOnly ? undefined : cCompiler();
+  requireBuildTool('tar');
+  if (!extractOnly) { requireBuildTool('make'); requireBuildTool('m4'); if (profile === 'web' && process.platform !== 'darwin') requireBuildTool('cmake'); }
+  const release = await acquireLock(directory);
+  try {
+
+    function run(command, args, cwd, label, env = process.env) {
+      const path = join(logs, label + '.log');
+      const descriptor = openSync(path, 'w');
+      let result;
+      try { result = spawnSync(command, args, { cwd, env, stdio: ['ignore', descriptor, descriptor] }); }
+      finally { closeSync(descriptor); }
+      if (result.error || result.status !== 0) throw new Error(`${label} failed: ${result.error?.message ?? result.status}. See ${path}\n` + readFileSync(path, 'utf8').split('\n').slice(-24).join('\n'));
+    }
+
+    const dependencies = lock.dependencies.filter(dependency => (!dependency.platforms || dependency.platforms.includes(process.platform)) &&
+      (!selected || selected.includes(dependency.name)) && (extractOnly || profile === 'web' || ['pkgconf', 'gmp', 'nettle', 'gnutls'].includes(dependency.name)));
+    if (selected?.some(name => !dependencies.some(dependency => dependency.name === name)))
+      throw new Error(`One or more selected dependencies do not support ${process.platform}.`);
+    for (const dependency of dependencies) {
+      const archive = join(downloads, dependency.archive);
+      if (!existsSync(archive)) {
+        if (offline) throw new Error(`Offline setup cannot find the cached ${dependency.name} archive at ${archive}.\nRun aug run once with network access, then retry aug run --offline.`);
+        process.stdout.write(`Downloading ${dependency.name} ${dependency.version}\n`);
+        let bytes;
+        try {
+          const response = await fetch(dependency.url, { signal: AbortSignal.timeout(120000) });
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          bytes = Buffer.from(await response.arrayBuffer());
+        } catch (error) { throw new Error(`Could not download ${dependency.name}: ${error.message}.\nCheck your internet/proxy connection and retry aug run. URL: ${dependency.url}`); }
+        if (createHash('sha256').update(bytes).digest('hex') !== dependency.sha256)
+          throw new Error(`Downloaded ${dependency.name} failed its checksum. No files were installed. Check your connection and retry aug run.`);
+        const temporary = archive + '.tmp';
+        try { writeFileSync(temporary, bytes); renameSync(temporary, archive); }
+        finally { rmSync(temporary, { force: true }); }
+      }
+      const hash = createHash('sha256').update(readFileSync(archive)).digest('hex');
+      if (hash !== dependency.sha256) throw new Error(`${dependency.name}: cached archive checksum mismatch at ${archive}.\nRemove that archive and retry aug run to download the verified copy.`);
+      const source = join(sources, dependency.name);
+      if (existsSync(join(source, '.archive-sha256')) && readFileSync(join(source, '.archive-sha256'), 'utf8').trim() !== hash)
+        throw new Error(`${dependency.name}: source tree differs from the dependency lock. Set AUG_NATIVE_HOME to an empty directory and retry aug run.`);
+      if (!existsSync(join(source, '.archive-sha256')) || dependencyArtifacts(dependency.name).filter(file => file.startsWith('sources/')).some(file => !existsSync(join(directory, file)))) {
+        mkdirSync(source, { recursive: true });
+        run('tar', ['-xf', archive, '-C', source, '--strip-components=1'], directory, 'extract-' + dependency.name);
+        writeFileSync(join(source, '.archive-sha256'), hash + '\n');
+      }
+    }
+    if (extractOnly) return;
+
+    const sdk = '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk';
+    const mac = process.platform === 'darwin';
+    const sysroot = mac && existsSync(sdk) ? ' -isysroot ' + sdk : '';
+    const environment = { ...process.env, ...(mac && existsSync(sdk) && !process.env.SDKROOT ? { SDKROOT: sdk } : {}), CC: cc, CC_FOR_BUILD: cc, CXX: process.env.CXX ?? cc.replace(/clang$/, 'clang++').replace(/gcc$/, 'g++').replace(/^cc$/, 'c++'),
+      CFLAGS: `-O2 -fPIC${sysroot}`,
+      CXXFLAGS: `-O2 -fPIC${sysroot}`,
+      CPPFLAGS: `-I${prefix}/include${sysroot}`, LDFLAGS: `-L${prefix}/lib -Wl,-rpath,${prefix}/lib`,
+      PKG_CONFIG: join(prefix, 'bin', 'pkgconf'), PKG_CONFIG_PATH: join(prefix, 'lib', 'pkgconfig'),
+      LD_LIBRARY_PATH: `${prefix}/lib${process.env.LD_LIBRARY_PATH ? ':' + process.env.LD_LIBRARY_PATH : ''}`,
+      PATH: join(prefix, 'bin') + ':' + process.env.PATH,
+    };
+    const parallel = String(Math.min(8, availableParallelism()));
+    for (const name of ['pkgconf', 'gmp', 'nettle', 'gnutls']) {
+      const marker = join(prefix, '.built-' + name);
+      const checksum = lock.dependencies.find(dependency => dependency.name === name).sha256;
+      if (existsSync(marker)) {
+        if (readFileSync(marker, 'utf8').trim() !== checksum) throw new Error(`${name}: installed build differs from the dependency lock; choose a new build directory.`);
+        if (dependencyArtifacts(name).every(file => existsSync(join(directory, file)))) continue;
+      }
+      const source = join(sources, name);
+      const extra = name === 'gmp' ? ['--disable-cxx', '--with-pic'] : name === 'nettle' ? ['--disable-documentation'] : name === 'gnutls' ? [
+        '--disable-doc', '--disable-tests', '--disable-tools', '--disable-cxx', '--disable-guile',
+        '--disable-nls', '--disable-idn', '--without-p11-kit', '--without-brotli', '--without-zstd',
+        '--with-included-libtasn1', '--with-included-unistring', '--disable-libdane',
+      ] : [];
+      // GnuTLS 3.8.13's audit header does not define this diagnostic-only macro
+      // when Clang 14 reports __has_c_attribute but lacks [[maybe_unused]].
+      const buildEnvironment = name === 'gnutls' && !mac ?
+        {...environment, CFLAGS: environment.CFLAGS + ' -DCRAU_MAYBE_UNUSED='} : environment;
+      process.stdout.write(`Building ${name}; logs: ${logs}\n`);
+      // A relative invocation keeps Autoconf's srcdir local. An absolute alias (e.g. /var -> /private/var)
+      // can make GnuTLS treat this as a VPATH build and replace GNUmakefile with a link to itself.
+      run('./configure', ['--prefix=' + prefix, '--libdir=' + join(prefix, 'lib'), '--enable-shared', '--disable-static', ...extra], source, name + '-configure', buildEnvironment);
+      run('make', ['-j' + parallel], source, name + '-build', buildEnvironment);
+      run('make', ['install'], source, name + '-install', buildEnvironment);
+      if (name === 'nettle') run(join(prefix, 'bin', 'pkgconf'), ['--modversion', 'nettle', 'hogweed'], root, 'nettle-pkgconf', environment);
+      writeFileSync(marker, checksum + '\n');
+    }
+
+    if (profile === 'web') {
+    const cmake = mac ? join(sources, 'cmake', 'CMake.app', 'Contents', 'bin', 'cmake') : 'cmake';
+    const build = join(directory, 'build-libwebsockets');
+    const webMarker = join(prefix, '.built-libwebsockets');
+    const webChecksum = lock.dependencies.find(dependency => dependency.name === 'libwebsockets').sha256;
+    if (existsSync(webMarker) && readFileSync(webMarker, 'utf8').trim() !== webChecksum)
+      throw new Error('libwebsockets: installed build differs from the dependency lock; choose a new build directory.');
+    if (!existsSync(webMarker) || !dependencyArtifacts('libwebsockets').every(file => existsSync(join(directory, file)))) {
+      process.stdout.write(`Building libwebsockets with GnuTLS, HTTP/2 and HTTP/3\n`);
+      run(cmake, ['-S', join(sources, 'libwebsockets'), '-B', build,
+        '-DCMAKE_BUILD_TYPE=Release', '-DCMAKE_INSTALL_PREFIX=' + prefix, '-DCMAKE_INSTALL_LIBDIR=lib', '-DCMAKE_PREFIX_PATH=' + prefix,
+        '-DCMAKE_C_COMPILER=' + cc, ...(mac && existsSync(sdk) && !process.env.SDKROOT ? ['-DCMAKE_OSX_SYSROOT=' + sdk] : []),
+        '-DLWS_GNUTLS_LIBRARIES=' + join(prefix, 'lib', mac ? 'libgnutls.dylib' : 'libgnutls.so'),
+        '-DLWS_GNUTLS_INCLUDE_DIRS=' + join(prefix, 'include'),
+        '-DLWS_WITH_GNUTLS=ON', '-DLWS_WITH_HTTP2=ON', '-DLWS_WITH_HTTP3=ON',
+        '-DLWS_WITH_STATIC=ON', '-DLWS_WITH_SHARED=OFF', '-DLWS_WITHOUT_TESTAPPS=ON',
+        '-DLWS_WITHOUT_TEST_SERVER=ON', '-DLWS_WITHOUT_TEST_CLIENT=ON',
+        '-DLWS_WITH_LIBUV=OFF', '-DLWS_WITH_LIBEVENT=OFF', '-DLWS_WITH_LIBEV=OFF',
+        '-DLWS_WITH_GLIB=OFF', '-DLWS_WITHOUT_EXTENSIONS=ON', '-DLWS_WITH_ZLIB=OFF',
+      ], root, 'libwebsockets-configure', environment);
+      run(cmake, ['--build', build, '--parallel', parallel], root, 'libwebsockets-build', environment);
+      run(cmake, ['--install', build], root, 'libwebsockets-install', environment);
+      writeFileSync(webMarker, webChecksum + '\n');
+    }
+    }
+    writeFileSync(join(prefix, 'aug-native-manifest.json'), JSON.stringify({ platform: process.platform, architecture: process.arch,
+      dependencies: lock.dependencies.filter(dependency => dependencyReady(directory, dependency)).map(({name, version, revision, sha256}) => ({name, version, revision, sha256})) }, null, 2) + '\n');
+    process.stdout.write(`Native dependencies ready at ${prefix}\n`);
+  } finally { release(); }
 }
-if (extractOnly) process.exit(0);
 
-const sdk = '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk';
-const mac = process.platform === 'darwin';
-const cc = process.env.CC ?? (mac ? '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang' : 'clang');
-const sysroot = mac && existsSync(sdk) ? ' -isysroot ' + sdk : '';
-const environment = { ...process.env, ...(mac ? { SDKROOT: sdk } : {}), CC: cc, CC_FOR_BUILD: cc, CXX: process.env.CXX ?? cc.replace(/clang$/, 'clang++'),
-  CFLAGS: `-O2 -fPIC${sysroot}`,
-  CXXFLAGS: `-O2 -fPIC${sysroot}`,
-  CPPFLAGS: `-I${prefix}/include${sysroot}`, LDFLAGS: `-L${prefix}/lib -Wl,-rpath,${prefix}/lib`,
-  PKG_CONFIG: join(prefix, 'bin', 'pkgconf'), PKG_CONFIG_PATH: join(prefix, 'lib', 'pkgconfig'),
-  LD_LIBRARY_PATH: `${prefix}/lib${process.env.LD_LIBRARY_PATH ? ':' + process.env.LD_LIBRARY_PATH : ''}`,
-  PATH: join(prefix, 'bin') + ':' + process.env.PATH,
-};
-const parallel = String(Math.min(8, availableParallelism()));
-for (const name of ['pkgconf', 'gmp', 'nettle', 'gnutls']) {
-  const marker = join(prefix, '.built-' + name);
-  const checksum = lock.dependencies.find(dependency => dependency.name === name).sha256;
-  if (existsSync(marker)) {
-    if (readFileSync(marker, 'utf8').trim() !== checksum) throw new Error(`${name}: installed build differs from the dependency lock; choose a new build directory.`);
-    continue;
+/** One writer per cache. An interrupted setup leaves a recoverable PID lock. */
+async function acquireLock(directory) {
+  const path = join(directory, '.setup-lock');
+  const started = Date.now(); let announced = false;
+  while (true) {
+    try {
+      const descriptor = openSync(path, 'wx');
+      try { writeFileSync(descriptor, JSON.stringify({ pid: process.pid })); }
+      finally { closeSync(descriptor); }
+      return () => rmSync(path, { force: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try {
+        const owner = JSON.parse(readFileSync(path, 'utf8'));
+        if (Number.isInteger(owner.pid) && owner.pid > 0) {
+          try { process.kill(owner.pid, 0); }
+          catch (error) { if (error.code === 'ESRCH') { rmSync(path, { force: true }); continue; } }
+        } else if (Date.now() - statSync(path).mtimeMs > 30000) { rmSync(path, { force: true }); continue; }
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        if (error instanceof SyntaxError && Date.now() - statSync(path).mtimeMs > 30000) { rmSync(path, { force: true }); continue; }
+      }
+      if (!announced) { process.stdout.write('Waiting for another August process to prepare the native cache.\n'); announced = true; }
+      if (Date.now() - started > 600000) throw new Error(`Another native setup still holds ${path}. Wait for it to finish, then retry aug run.`);
+      await new Promise(accept => setTimeout(accept, 500));
+    }
   }
-  const source = join(sources, name);
-  const extra = name === 'gmp' ? ['--disable-cxx', '--with-pic'] : name === 'nettle' ? ['--disable-documentation'] : name === 'gnutls' ? [
-    '--disable-doc', '--disable-tests', '--disable-tools', '--disable-cxx', '--disable-guile',
-    '--disable-nls', '--disable-idn', '--without-p11-kit', '--without-brotli', '--without-zstd',
-    '--with-included-libtasn1', '--with-included-unistring', '--disable-libdane',
-  ] : [];
-  // GnuTLS 3.8.13's audit header does not define this diagnostic-only macro
-  // when Clang 14 reports __has_c_attribute but lacks [[maybe_unused]].
-  const buildEnvironment = name === 'gnutls' && !mac ?
-    {...environment, CFLAGS: environment.CFLAGS + ' -DCRAU_MAYBE_UNUSED='} : environment;
-  process.stdout.write(`Building ${name}; logs: ${logs}\n`);
-  run(join(source, 'configure'), ['--prefix=' + prefix, '--libdir=' + join(prefix, 'lib'), '--enable-shared', '--disable-static', ...extra], source, name + '-configure', buildEnvironment);
-  run('/usr/bin/make', ['-j' + parallel], source, name + '-build', buildEnvironment);
-  run('/usr/bin/make', ['install'], source, name + '-install', buildEnvironment);
-  if (name === 'nettle') run(join(prefix, 'bin', 'pkgconf'), ['--modversion', 'nettle', 'hogweed'], root, 'nettle-pkgconf', environment);
-  writeFileSync(marker, checksum + '\n');
 }
 
-const cmake = mac ? join(sources, 'cmake', 'CMake.app', 'Contents', 'bin', 'cmake') : 'cmake';
-const build = join(directory, 'build-libwebsockets');
-const webMarker = join(prefix, '.built-libwebsockets');
-const webChecksum = lock.dependencies.find(dependency => dependency.name === 'libwebsockets').sha256;
-if (existsSync(webMarker) && readFileSync(webMarker, 'utf8').trim() !== webChecksum)
-  throw new Error('libwebsockets: installed build differs from the dependency lock; choose a new build directory.');
-if (!existsSync(webMarker)) {
-  process.stdout.write(`Building libwebsockets with GnuTLS, HTTP/2 and HTTP/3\n`);
-  run(cmake, ['-S', join(sources, 'libwebsockets'), '-B', build,
-    '-DCMAKE_BUILD_TYPE=Release', '-DCMAKE_INSTALL_PREFIX=' + prefix, '-DCMAKE_INSTALL_LIBDIR=lib', '-DCMAKE_PREFIX_PATH=' + prefix,
-    '-DCMAKE_C_COMPILER=' + cc, ...(mac ? ['-DCMAKE_OSX_SYSROOT=' + sdk] : []),
-    '-DLWS_GNUTLS_LIBRARIES=' + join(prefix, 'lib', mac ? 'libgnutls.dylib' : 'libgnutls.so'),
-    '-DLWS_GNUTLS_INCLUDE_DIRS=' + join(prefix, 'include'),
-    '-DLWS_WITH_GNUTLS=ON', '-DLWS_WITH_HTTP2=ON', '-DLWS_WITH_HTTP3=ON',
-    '-DLWS_WITH_STATIC=ON', '-DLWS_WITH_SHARED=OFF', '-DLWS_WITHOUT_TESTAPPS=ON',
-    '-DLWS_WITHOUT_TEST_SERVER=ON', '-DLWS_WITHOUT_TEST_CLIENT=ON',
-    '-DLWS_WITH_LIBUV=OFF', '-DLWS_WITH_LIBEVENT=OFF', '-DLWS_WITH_LIBEV=OFF',
-    '-DLWS_WITH_GLIB=OFF', '-DLWS_WITHOUT_EXTENSIONS=ON', '-DLWS_WITH_ZLIB=OFF',
-  ], root, 'libwebsockets-configure', environment);
-  run(cmake, ['--build', build, '--parallel', parallel], root, 'libwebsockets-build', environment);
-  run(cmake, ['--install', build], root, 'libwebsockets-install', environment);
-  writeFileSync(webMarker, webChecksum + '\n');
+try { await setup(); }
+catch (error) {
+  const permission = ['EACCES', 'EPERM', 'EROFS'].includes(error.code) ? '\nChoose a writable cache: set AUG_NATIVE_HOME to a directory you own and retry aug run.' : '';
+  process.stderr.write(`Native setup: ${error.message}${permission}\n`);
+  process.exitCode = 1;
 }
-writeFileSync(join(prefix, 'aug-native-manifest.json'), JSON.stringify({ platform: process.platform, architecture: process.arch,
-  dependencies: dependencies.map(({name, version, revision, sha256}) => ({name, version, revision, sha256})) }, null, 2) + '\n');
-process.stdout.write(`Native dependencies ready at ${prefix}\n`);

package/scripts/native-setup.mjs

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { nativeHome } from './native-home.mjs';
+import { cCompiler } from './native-toolchain.mjs';
+
+/** Inspect C identifiers, excluding comments and string literals. Shared with the linker. */
+export function nativeRequirements(generated) {
+  const code = generated.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'/g, ' ');
+  const web = /\b(?:_?aug_http_|aug_headers_)\w*/.test(code);
+  return { web, crypto: web || /\b_aug_crypto_\w*/.test(code),
+    tasks: web || /\baug_task_\w*/.test(code), json: web || /\b_?aug_json_\w*/.test(code),
+    html: web || /\baug_html_\w*/.test(code), time: /\b_aug_time_\w*/.test(code) };
+}
+
+const artifacts = {
+  minicoro: ['sources/minicoro/minicoro.h'], yyjson: ['sources/yyjson/src/yyjson.c', 'sources/yyjson/src/yyjson.h'],
+  pkgconf: ['prefix/bin/pkgconf'], gmp: ['prefix/include/gmp.h'],
+  nettle: ['prefix/include/nettle/nettle-types.h'], gnutls: ['prefix/include/gnutls/gnutls.h'],
+  libwebsockets: ['prefix/lib/libwebsockets.a', 'prefix/include/libwebsockets.h'],
+};
+export function dependencyArtifacts(name) {
+  const library = { gmp: ['gmp'], nettle: ['nettle', 'hogweed'], gnutls: ['gnutls'] }[name] ?? [];
+  return [...(artifacts[name] ?? []), ...library.map(item => `prefix/lib/lib${item}.${process.platform === 'darwin' ? 'dylib' : 'so'}`)];
+}
+
+export function dependencyReady(directory, dependency) {
+  const marker = join(directory, ['minicoro', 'yyjson'].includes(dependency.name) ?
+    `sources/${dependency.name}/.archive-sha256` : `prefix/.built-${dependency.name}`);
+  return existsSync(marker) && readFileSync(marker, 'utf8').trim() === dependency.sha256 &&
+    dependencyArtifacts(dependency.name).every(file => existsSync(join(directory, file)));
+}
+
+/** Prepare the precise native capabilities emitted by the compiler, keeping stdout for the program. */
+export async function prepareNativeDependencies(generated, { offline = false, progress = message => process.stderr.write(message) } = {}) {
+  const needs = nativeRequirements(generated);
+  cCompiler(); // Fail before downloading when the host cannot compile the application.
+  if (!needs.json && !needs.tasks && !needs.crypto) return;
+  const root = resolve(import.meta.dirname, '..'), directory = nativeHome(root);
+  const lock = JSON.parse(readFileSync(join(import.meta.dirname, 'native-dependencies.lock.json'), 'utf8'));
+  const names = [...(needs.json ? ['yyjson'] : []), ...(needs.tasks ? ['minicoro'] : []),
+    ...(needs.crypto ? ['pkgconf', 'gmp', 'nettle', 'gnutls'] : []), ...(needs.web ? ['libwebsockets'] : [])];
+  const required = lock.dependencies.filter(item => names.includes(item.name));
+  const manifestPath = join(directory, 'prefix/aug-native-manifest.json');
+  let manifest;
+  if (needs.crypto && existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      if (!manifest || typeof manifest.platform !== 'string' || typeof manifest.architecture !== 'string' || !Array.isArray(manifest.dependencies))
+        throw new Error('Invalid metadata');
+    }
+    catch { throw new Error(`Native cache metadata is unreadable: ${manifestPath}\nSet AUG_NATIVE_HOME to an empty directory and retry aug run.`); }
+    if (manifest.platform !== process.platform || manifest.architecture !== process.arch)
+      throw new Error(`Native cache targets ${manifest.platform}/${manifest.architecture}; this computer is ${process.platform}/${process.arch}.\nSet AUG_NATIVE_HOME to a cache built on this computer, or unset it and retry aug run.`);
+  }
+  const libraries = required.filter(item => !['yyjson', 'minicoro'].includes(item.name));
+  const manifestReady = !needs.crypto || libraries.every(item => manifest?.dependencies?.some(entry => entry.name === item.name && entry.sha256 === item.sha256));
+  if (manifestReady && required.every(item => dependencyReady(directory, item))) return;
+  const capabilities = [needs.json && 'JSON', needs.tasks && 'tasks', needs.crypto && 'crypto', needs.web && 'HTTP'].filter(Boolean).join(', ');
+  progress(`Preparing native dependencies for ${capabilities} (cached at ${directory}). First use may take a few minutes.\n`);
+  const args = needs.crypto ? ['--profile', needs.web ? 'web' : 'crypto'] : ['--extract-only', '--only', names.join(',')];
+  // Crypto source packages can use JSON or tasks without needing HTTP. The
+  // crypto profile builds libraries only, so prepare those source dependencies
+  // separately. The web profile already includes both.
+  const portable = needs.crypto && !needs.web ? required.filter(item =>
+    ['yyjson', 'minicoro'].includes(item.name) && !dependencyReady(directory, item)).map(item => item.name) : [];
+  const preparations = [...(portable.length ? [['--extract-only', '--only', portable.join(',')]] : []), args];
+  for (const preparation of preparations) {
+    if (offline) preparation.push('--offline');
+    await new Promise((accept, reject) => {
+      const child = spawn(process.execPath, [join(import.meta.dirname, 'bootstrap-native.mjs'), ...preparation], {
+        stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+      let detail = '', interrupted;
+      const stop = signal => {
+        interrupted = signal;
+        try { if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal); else child.kill(signal); }
+        catch (error) { if (error.code !== 'ESRCH') child.kill(signal); }
+      };
+      const interrupt = () => stop('SIGINT'), terminate = () => stop('SIGTERM');
+      process.once('SIGINT', interrupt); process.once('SIGTERM', terminate);
+      const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
+      child.stdout.on('data', data => progress(data.toString()));
+      child.stderr.on('data', data => { detail = (detail + data.toString()).slice(-12000); progress(data.toString()); });
+      child.on('error', error => { cleanup(); reject(new Error(`Cannot start native dependency setup: ${error.message}\nRetry aug run after checking your Node installation.`)); });
+      child.on('close', (status, signal) => {
+        cleanup();
+        if (interrupted) {
+          const error = new Error(`Native setup cancelled by ${interrupted}. Retry aug run to resume using the completed dependencies.`);
+          error.exitCode = interrupted === 'SIGINT' ? 130 : 143; reject(error);
+        } else if (status === 0) accept();
+        else reject(new Error(`Native dependency setup ${signal ? `stopped by ${signal}` : `failed (exit ${status})`}. ${detail ? 'See the error above.' : `Check the setup logs in ${join(directory, 'logs')}.`}\nRetry aug run after addressing it; completed dependencies will be reused.`));
+      });
+    });
+  }
+  const missing = required.filter(item => !dependencyReady(directory, item)).map(item => item.name);
+  if (missing.length)
+    throw new Error(`Native setup did not prepare ${missing.join(', ')} in ${directory}.\nCheck the setup logs in ${join(directory, 'logs')} and retry aug run; completed dependencies will be reused.`);
+}

package/scripts/native-toolchain.mjs

@@ -0,0 +1,28 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+export function compilerHelp() {
+  const install = process.platform === 'darwin' ? 'Install the Apple Command Line Tools with: xcode-select --install' :
+    process.platform === 'linux' ? 'Install a C toolchain (Debian/Ubuntu: sudo apt-get install build-essential; Fedora: sudo dnf install gcc make).' :
+    'Use a Linux Dev Container or install a C11 compiler with POSIX threads support.';
+  return `${install}\nIf a compiler is already installed, set CC to its executable path and retry aug run.`;
+}
+
+/** Select an executable, including installations with only Apple's Command Line Tools. */
+export function cCompiler() {
+  const xcode = '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang';
+  const candidates = process.env.CC ? [process.env.CC] : [...(existsSync(xcode) ? [xcode] : []), 'clang', 'cc', 'gcc'];
+  for (const command of candidates) {
+    const result = spawnSync(command, ['--version'], { encoding: 'utf8', timeout: 10000 });
+    if (!result.error && result.status === 0) return command;
+  }
+  throw new Error(`Cannot use a C compiler${process.env.CC ? ` from CC=${process.env.CC}` : ' on this computer'}.\n${compilerHelp()}`);
+}
+
+export function requireBuildTool(command, args = ['--version']) {
+  const result = spawnSync(command, args, { encoding: 'utf8', timeout: 10000 });
+  if (!result.error && result.status === 0) return;
+  const install = process.platform === 'darwin' ? 'Install the Apple Command Line Tools with xcode-select --install.' :
+    'Install the build tools (Debian/Ubuntu: sudo apt-get install build-essential m4 cmake zlib1g-dev; Fedora: sudo dnf install gcc make m4 cmake zlib-devel).';
+  throw new Error(`Native dependency setup needs ${command}, but it could not run.\n${install}\nRetry aug run after installing it.`);
+}

package/src/builtins.js

@@ -85,7 +85,7 @@ export const builtinFunctions = [
     { name: 'exit', parameters: [{ label: 'status', type: 'int' }], returns: 'void', documentation: 'Exit from main with a status from 0 to 255 after cancellation and cleanup.', native: 'exit' },
     { name: 'c_int', parameters: [{ label: 'value', type: 'int' }], returns: 'c_int', errors: ['ConversionError'], documentation: 'Checked conversion to a signed 32-bit C int. Overflow raises ConversionError. AugScript int maps to int64_t at the C boundary.', native: 'to_c_int' },
     { name: 'int', parameters: [{ label: 'value', type: 'c_int' }], returns: 'int', documentation: 'Widen a C int to the signed 64-bit AugScript integer without loss.', native: 'to_int' },
-    { name: 'print', parameters: [{ label: 'value', type: 'any' }], returns: 'void', documentation: 'Composition and test output. Other callables receive Console and declare uses console.write.', native: 'print' },
+    { name: 'print', parameters: [{ label: 'value', type: 'any' }], returns: 'void', documentation: 'Write application startup or test output. Other callables receive a Console dependency and call console.write; their bodies infer that capability use.', native: 'print' },
     { name: 'assert', parameters: [{ label: 'condition', type: 'bool' }], returns: 'void', documentation: 'Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.', native: 'assert' },
     { name: 'arguments', parameters: [], returns: 'List<string>', documentation: 'Composition arguments. Other callables receive the Arguments capability.', native: 'arguments' },
     { name: 'read_file', parameters: [{ label: 'path', type: 'string' }], returns: 'string', errors: ['FileError'], documentation: 'Root-only UTF-8 text input. Other callables receive FileReader. Invalid Unicode and NUL raise FileError.', native: 'read_file' },