@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/src/formatter.js

@@ -1,6 +1,7 @@
 import { typeName } from "./ast.js";
 import { lex } from "./lexer.js";
 import { parse } from "./parser.js";
+import { importSource } from "./git-packages.js";
 /** Canonical syntax comes from the parsed program; comments stay with their lexical owner. */
 export function formatFile(project, file) {
     return printFile(project, file, false);
@@ -43,7 +44,7 @@ function printFile(project, file, migrate) {
         if (!value || typeof value !== 'object')
             return value;
         const node = value;
-        return Object.fromEntries(Object.entries(node).filter(([key, value]) => !['span', 'nameSpan', 'sourceSpan'].includes(key) && value !== undefined)
+        return Object.fromEntries(Object.entries(node).filter(([key, value]) => !['span', 'nameSpan', 'sourceSpan', 'headerEnd'].includes(key) && value !== undefined)
             .sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, shape(value)]));
     };
     if (JSON.stringify(shape(parsed.file.items)) !== JSON.stringify(shape(verified.file.items)))
@@ -67,7 +68,15 @@ class Printer {
         this.indent = project.config.block_style === 'indent';
         this.assign = project.config.assignment === 'to' ? 'to' : '=';
     }
-    line(text = '') { this.lines.push(text ? this.step.repeat(this.level) + text : ''); }
+    line(text = '') {
+        this.lines.push(...text.split('\n').map(line => line ? this.step.repeat(this.level) + line : ''));
+    }
+    delimited(open, values, close, trailing = '') {
+        const flat = open + values.join(', ') + trailing + close;
+        if (!values.length || (!flat.includes('\n') && flat.length <= 80 - this.level * 4))
+            return flat;
+        return open + '\n' + values.map(value => this.step + value.replaceAll('\n', '\n' + this.step)).join(',\n') + trailing + '\n' + close;
+    }
     before(offset, parentColumn) {
         while (this.comments[0]?.span.start < offset) {
             if (parentColumn !== undefined && this.comments[0].span.column <= parentColumn)
@@ -123,7 +132,7 @@ class Printer {
         this.annotations(method.annotations);
         const header = `${method.endpoint ? `endpoint ${method.endpoint.method} ${JSON.stringify(method.endpoint.path)} as ` : ''}${method.fixture ? 'fixture ' : ''}${method.externC ? 'extern C ' + (method.valueAbi ? 'value ' : '') + (method.nativePure ? 'pure ' : '') : ''}${method.name}${this.generics(method)}` +
             `(${method.params.map(param => this.param(param)).join(', ')})` +
-            (method.returns.name !== 'void' ? ` ${method.endpoint?.streams ? 'streams' : 'returns'} ${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}` : '') +
+            (method.returns.name !== 'void' || method.declared?.returns ? ` ${method.endpoint?.streams ? 'streams' : 'returns'} ${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}` : '') +
             (method.endpoint && method.endpoint.status !== 200 ? ` with status ${method.endpoint.status}` : '') +
             (method.changes?.length ? ` changes ${method.changes.join(' and ')}` : '') +
             (method.uses?.length ? ` uses ${method.uses.map(use => `${use.source}.${use.operation}`).join(' and ')}` : '') +
@@ -159,14 +168,16 @@ class Printer {
             value = `resolve ${expr.name}` + (expr.typeArgs.length ? '<' + expr.typeArgs.map(typeName).join(', ') + '>' : '');
         else if (expr.kind === 'member')
             value = `${this.expression(expr.object, 8)}.${expr.name}`;
-        else if (expr.kind === 'call')
-            value = this.expression(expr.callee, 8) + (expr.typeArgs.length ? '<' + expr.typeArgs.map(typeName).join(', ') + '>' : '') +
-                '(' + expr.args.map((arg, index) => (expr.argLabels[index] ? expr.argLabels[index] + '=' : '') + this.expression(arg)).join(', ') + this.inline(expr.span.end) + ')';
+        else if (expr.kind === 'call') {
+            const open = this.expression(expr.callee, 8) + (expr.typeArgs.length ? '<' + expr.typeArgs.map(typeName).join(', ') + '>' : '') + '(';
+            const values = expr.args.map((arg, index) => (expr.argLabels[index] ? expr.argLabels[index] + '=' : '') + this.expression(arg));
+            value = this.delimited(open, values, ')', this.inline(expr.span.end));
+        }
         else if (expr.kind === 'collection') {
             const open = expr.collection === 'List' ? '[' : expr.collection === 'Tuple' ? '(' : '{';
             const close = open === '[' ? ']' : open === '(' ? ')' : '}';
             const values = expr.collection === 'Map' ? expr.items.filter((_, index) => index % 2 === 0).map((item, index) => `${this.expression(item)}: ${this.expression(expr.items[index * 2 + 1])}`) : expr.items.map(item => this.expression(item));
-            value = open + values.join(', ') + (expr.collection === 'Tuple' && values.length === 1 ? ',' : '') + this.inline(expr.span.end) + close;
+            value = this.delimited(open, values, close, (expr.collection === 'Tuple' && values.length === 1 ? ',' : '') + this.inline(expr.span.end));
         }
         else if (expr.kind === 'unary') {
             const power = expr.op === '!' ? 2.5 : 7;
@@ -232,7 +243,7 @@ class Printer {
     item(item) {
         this.before('annotations' in item ? item.annotations?.[0]?.span.start ?? item.span.start : item.span.start);
         if (item.kind === 'import') {
-            this.line(`import ${item.everything ? 'everything' : item.names.join(' and ')} from ${item.from.join('.')}`);
+            this.line(`import ${item.everything ? 'everything' : item.names.join(' and ')} from ${importSource(item.from)}`);
         }
         else if (item.kind === 'export')
             this.line('export ' + (item.folder ? 'folder ' + item.name : `${item.name} from ${item.from}`));

package/src/git-packages.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { withPackageLock } from "./package-locking.js";
+export const isGitSource = (value) => /^(?:https:\/\/|git\+(?:https|file):\/\/)/.test(value);
+export const sourceAlias = (value) => 'url_' + createHash('sha256').update(value).digest('hex').slice(0, 20);
+export const importSource = (parts) => (isGitSource(parts[0]) ? JSON.stringify(parts[0]) : parts[0]) + parts.slice(1).map(part => '.' + part).join('');
+/** A repository URL can select a tag and, on GitHub, a folder within the repository. */
+export function gitReference(request) {
+    try {
+        if (decodeURIComponent(request.split('#')[0]).split(/[\\/]/).some(part => part === '.' || part === '..'))
+            throw new Error('Repository URLs cannot contain path traversal.');
+    }
+    catch {
+        throw new Error('Invalid repository URL or path traversal.');
+    }
+    let url;
+    try {
+        url = new URL(request.replace(/^git\+/, ''));
+    }
+    catch {
+        throw new Error(`Invalid package repository URL: ${request}`);
+    }
+    if (!['https:', 'file:'].includes(url.protocol) || url.username || url.password || url.search ||
+        url.protocol === 'file:' && !request.startsWith('git+file:'))
+        throw new Error('Use a public HTTPS repository URL without credentials, or git+file:///PATH for a local Git repository.');
+    const revision = decodeURIComponent(url.hash.slice(1)) || 'HEAD';
+    url.hash = '';
+    let folder = '', ref = revision;
+    if (url.hostname === 'github.com') {
+        const parts = url.pathname.split('/').filter(Boolean).map(decodeURIComponent);
+        if (parts.length < 2)
+            throw new Error('A GitHub package URL needs an owner and repository.');
+        if (parts[2] === 'tree') {
+            if (!parts[3] || revision !== 'HEAD')
+                throw new Error('Choose the revision with /tree/TAG/FOLDER or #TAG, not both.');
+            ref = parts[3];
+            folder = parts.slice(4).join('/');
+        }
+        else
+            folder = parts.slice(2).join('/');
+        url.pathname = '/' + parts.slice(0, 2).join('/').replace(/\.git$/, '') + '.git';
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/+-]*$/.test(ref) || ref.includes('..') || ref.endsWith('/'))
+        throw new Error('Package revision must be a commit, tag, or branch name.');
+    if (folder.split('/').some(part => part === '..' || part === '.' || part.startsWith('_')) || folder.includes('\\'))
+        throw new Error('Package folders must stay inside the repository and cannot be private.');
+    return { request, repository: url.href, revision: ref, folder };
+}
+function git(args, cwd) {
+    const result = spawnSync(process.env.AUG_GIT ?? 'git', ['-c', 'core.hooksPath=/dev/null', ...args], {
+        cwd, timeout: 120000, maxBuffer: 32 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+    });
+    if (result.error)
+        throw new Error(`Cannot read a Git package: ${result.error.message}. Install Git or set AUG_GIT to its executable.`);
+    if (result.status !== 0)
+        throw new Error(`Cannot read a Git package: ${result.stderr.toString().trim()}. Check the repository URL and revision; private repositories are outside this workflow.`);
+    return result.stdout;
+}
+/** Read source blobs without checking out files, executing hooks, or following repository symlinks. */
+export function materializeGit(request, destination, offline, locked) {
+    const reference = gitReference(request);
+    if (locked && (locked.repository !== reference.repository || locked.folder !== reference.folder || locked.revision !== reference.revision ||
+        !/^[a-f0-9]{40,64}$/.test(locked.commit)))
+        throw new Error('Git package lock has an invalid repository, folder, or commit.');
+    const cache = resolve(process.env.AUG_PACKAGE_CACHE ?? join(homedir(), '.cache', 'augscript', 'packages'));
+    const repository = join(cache, sourceAlias(reference.repository));
+    mkdirSync(cache, { recursive: true });
+    return withPackageLock(repository + '.lock', () => {
+        if (!existsSync(repository)) {
+            if (offline)
+                throw new Error(`Git package is not cached: ${request}. Run aug run online once before using --offline.`);
+            git(['init', '--bare', repository]);
+        }
+        let commit = locked?.commit;
+        const objectExists = commit && spawnSync(process.env.AUG_GIT ?? 'git', ['--git-dir', repository, 'cat-file', '-e', commit + '^{commit}']).status === 0;
+        if (!objectExists) {
+            if (offline)
+                throw new Error(`Git revision is not cached: ${commit ?? request}. Restore the package cache or run aug run online.`);
+            git(['--git-dir', repository, 'fetch', '--no-tags', '--depth=1', '--', reference.repository, commit ?? reference.revision]);
+            commit = git(['--git-dir', repository, 'rev-parse', 'FETCH_HEAD^{commit}']).toString().trim();
+        }
+        const result = { ...reference, commit: commit };
+        const prefix = reference.folder ? reference.folder + '/' : '';
+        const listing = git(['--git-dir', repository, 'ls-tree', '-rz', '--full-tree', result.commit, '--', prefix || '.']).toString();
+        let bytes = 0, count = 0;
+        for (const entry of listing.split('\0').filter(Boolean)) {
+            const match = /^(\d+) blob ([a-f0-9]+)\t([\s\S]+)$/.exec(entry);
+            if (!match || !match[3].startsWith(prefix))
+                continue;
+            const file = match[3].slice(prefix.length);
+            if (!file.endsWith('.aug') && !['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE'].includes(file))
+                continue;
+            if (!['100644', '100755'].includes(match[1]) || file.includes('\\') || file.split('/').some(part => !part || part === '..' || part.startsWith('.')))
+                throw new Error(`Git package source must be regular files inside its folder: ${file}`);
+            const contents = git(['--git-dir', repository, 'cat-file', 'blob', match[2]]);
+            bytes += contents.length;
+            if (++count > 10000 || bytes > 32 * 1024 * 1024)
+                throw new Error('Git source package exceeds 10,000 files or 32 MiB.');
+            const path = join(destination, file);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, contents);
+        }
+        if (!count)
+            throw new Error(`No August source at ${request}. Choose the folder containing export.aug or aug-package.json.`);
+        return result;
+    });
+}

package/src/help.js

@@ -4,9 +4,9 @@ const type = (detail, documentation) => ({ detail, documentation, category: 'typ
 const fn = (detail, documentation) => ({ detail, documentation, category: 'function' });
 const operator = (detail, documentation) => ({ detail, documentation, category: 'operator' });
 export const languageHelp = {
-    RequireLogin: { category: 'tag', detail: '[RequireLogin(authentication=auth)]', documentation: 'Verify credentials before typed body decoding. Map auth to an explicit resolve Authentication parameter and declare uses auth.authenticate. null produces 401; the adapter validates the credential. HTTP policies precede custom parameter interceptors.' },
+    RequireLogin: { category: 'tag', detail: '[RequireLogin(authentication=auth)]', documentation: 'Verify credentials before typed body decoding. Map auth to an explicit resolve Authentication parameter and infer its authenticate operation. null produces 401; the adapter validates the credential. HTTP policies precede custom parameter interceptors.' },
     RequirePermission: { category: 'tag', detail: '[RequirePermission(authentication=auth, authorization=permissions, permission="users.read")]', documentation: 'Authenticate the request and authorize one literal permission before decoding. Both dependencies are explicit resolve parameters; declare their authenticate and authorize effects. Missing credentials produce 401 and a denied permission produces 403.' },
-    LogRequest: { category: 'tag', detail: '[LogRequest(logger=logger)]', documentation: 'Map a resolve RequestLogger parameter and declare uses logger.complete. Observe the final status and monotonic duration after output finishes, or status 499 on disconnect. Layers complete in reverse written order.' },
+    LogRequest: { category: 'tag', detail: '[LogRequest(logger=logger)]', documentation: 'Map a resolve RequestLogger parameter and infer its complete operation. Observe the final status and monotonic duration after output finishes, or status 499 on disconnect. Layers complete in reverse written order.' },
     RateLimit: { category: 'tag', detail: '[RateLimit(requests=100, seconds=60)]', documentation: 'A bounded per-endpoint, per-peer fixed-window request limit. Uses the transport peer address, never an untrusted forwarding header. Rejected requests return 429 before body decoding. The table has 2048 entries and rejects new identities when full.' },
     Timeout: { category: 'tag', detail: '[Timeout(milliseconds=5000)]', documentation: 'Bound the request and its streaming producer with a monotonic deadline. Before output, return 504. After headers, terminate the stream. Cancellation joins children and runs always cleanup; native C operations finish before cancellation can be observed.' },
     Cors: { category: 'tag', detail: '[Cors(origins=["https://example.test"], headers=["content-type"], credentials=true)]', documentation: 'Allow exact literal HTTP(S) origins and explicit request header names. OPTIONS preflight checks the selected method and headers. Wildcard origins cannot use credentials. Valid responses include CORS and Vary headers; disallowed origins return 403.' },
@@ -38,15 +38,15 @@ export const languageHelp = {
     Task: type('Task<T>', 'A child computation owned by a scope. wait for reads its result; the scope joins children before releasing dependencies.'),
     Shared: type('Shared<T>', 'Synchronized mutable state. Construction takes a fresh or owned value. Read and mutate the value only through lock shared as state. A child borrowing an owned Shared<T> pins the wrapper until it finishes; the parent cannot move it into another owner while the child uses it.'),
     Bytes: type('Bytes', 'Immutable length-aware binary data. text() validates UTF-8; base64url() emits canonical unpadded URL-safe base64.'),
-    Json: type('Json', 'Immutable JSON data. Parse with august.json, decode concrete records with decode<T>(), and stringify with lossless integer handling.'),
+    Json: type('Json', 'Immutable JSON data. Import parse from the JSON source package, decode concrete records with decode<T>(), and stringify with lossless integer handling.'),
     Html: type('Html', 'Checked server markup produced with JSX elements and components. Interpolated text and attributes are escaped automatically.'),
     HttpAction: type('HttpAction', 'An immutable deferred HTTP call created with handle endpoint(...). Bind it to a form onSubmit or button onClick. The browser sends the request; endpoint dependencies and application logic run on the server.'),
     ServerEvent: type('ServerEvent<T>', 'One SSE event containing concrete JSON data, plus optional id, event, and retry milliseconds. CR, LF and NUL are rejected in metadata. The endpoint streams ServerEvent<T> and yields each event under transport backpressure.'),
     Headers: type('Headers', 'Immutable HTTP fields. with adds a checked field; get and all read case-insensitively. Duplicate Set-Cookie values remain separate.'),
     HttpRequest: type('HttpRequest', 'A request supplied through from request. Its method, path, headers and bounded body are explicit. form<T>() allows protocol-specific form errors.'),
     HttpResponse: type('HttpResponse<T>', 'A typed HTTP body with explicit status and headers. HttpResponse(body=value, status=201, headers=headers) constructs a response. Status literals range from 200 to 599; a dynamic status requires handling or declaring HttpError.'),
-    record: keyword('record Point(int x, int y)', 'Declare deeply immutable data with labeled construction and structural equality/hashing. Records contain primitives, tuples and other records. An initialize block validates inputs; declare rejected inputs with unless ErrorType.'),
-    initialize: keyword('initialize: ...', 'Run constructor work once after header inputs and local fields are initialized, before returning the class or record. Put this block inside the declaration, before class methods. Construction stays pure. Records can validate inputs and raise declared unless errors, but cannot replace immutable fields.'),
+    record: keyword('record Point(int x, int y)', 'Declare deeply immutable data with labeled construction and structural equality/hashing. Records contain primitives, tuples and other records. An initialize block validates inputs; validation infers rejected inputs; an explicit unless ErrorType limits permitted failures.'),
+    initialize: keyword('initialize: ...', 'Run constructor work once after header inputs and local fields are initialized, before returning the class or record. Put this block inside the declaration, before class methods. Construction stays pure. Records can validate inputs and raise checked errors, but cannot replace immutable fields.'),
     fixture: keyword('fixture example() returns Data: ...', 'Declare reusable test data through an ordinary checked function. Other files must import the fixture explicitly. Its dependencies and capabilities follow the same header contract rules as other functions.'),
     for: keyword('for item in items: ...', 'Traverse a List, Set, homogeneous Tuple, or Map. Map entries are tuples, so for (key, value) in map unpacks them. Iteration snapshots the collection in insertion order and gives elements read-only access.'),
     match: keyword('match value: when ...', 'Choose a checked case. Cover true and false for bool, null and some for nullable values, or add else. Concrete class cases narrow the named value. Duplicate and unreachable cases are rejected.'),
@@ -57,14 +57,14 @@ export const languageHelp = {
     scope: keyword('scope: ...', 'Create a local DI and child-task lifetime. Children join before dependencies are reclaimed; unhandled failures cancel siblings. Scoped references cannot escape. Nested scopes have independent caches.'),
     composition: keyword('composition Services: implement Logger with Adapter', 'Group static bindings behind an explicitly imported module declaration. Include the composition in main before executable statements; its own file must import every referenced contract and implementation.'),
     include: keyword('include Services', 'Expand an explicitly imported composition into the application root. Duplicate bindings and dependency cycles are checked after all includes are collected.'),
-    IndexError: type('IndexError implements Error', 'Checked failure for an invalid List.get position. Catch it, declare unless IndexError, or use List.at for a nullable lookup.'),
+    IndexError: type('IndexError implements Error', 'Checked failure for an invalid List.get position. Catch it or let it propagate. List.at returns a value or null instead.'),
     ArithmeticError: type('ArithmeticError implements Error', 'Checked failure for division by zero. int arithmetic otherwise wraps in the signed 64-bit range.'),
-    ConversionError: type('ConversionError implements Error', 'Checked failure when c_int(value=number) cannot fit the signed 32-bit C int range. Catch it or declare unless ConversionError.'),
+    ConversionError: type('ConversionError implements Error', 'Checked failure when c_int(value=number) cannot fit the signed 32-bit C int range. Catch it or let it propagate.'),
     c_int: type('c_int', 'Signed 32-bit C int. Convert explicitly with c_int(value=number), which raises ConversionError on overflow. It widens to int without loss. AugScript int maps to int64_t at the C boundary.'),
     interceptor: keyword('interceptor Name<T>(resolve Dependency dependency) { around(...) returns T { ... } }', 'Declare a reusable wrapper for functions, methods, or class construction. Apply it with `[Name]` or `[Name(y=x)]`. Inputs match target labels automatically; explicit mappings rename them. Tags enter in written order and results unwind in reverse. Each layer creates a fresh instance; dependencies are forwarded from the target header. Effective contracts include every layer\u2019s changes, capabilities, errors, and dependencies. Generic types are inferred from the target. Interceptors follow normal imports, exports, and underscore privacy.'),
-    around: fn('around(Type input) returns Type { return next(); }', 'The required entry point of an interceptor. Its parameters select target arguments, and its result must fit the target return type. Omit `returns` for void. It may validate, override mapped arguments, inspect the result, throw a checked error, or return early. Declare generic parameters on the interceptor header. Helper methods can be declared alongside around.'),
+    around: fn('around(Type input) returns Type { return next(); }', 'The required entry point of an interceptor. Its parameters select target arguments, and its result must fit the target return type. A forwarding body can omit returns and inherit the target result. It may validate, override mapped arguments, inspect the result, throw a checked error, or return early. Declare generic parameters on the interceptor header. Helper methods can be declared alongside around.'),
     next: fn('next(mappedLabel=value) returns TargetResult', 'Continue to the next interceptor layer or the original function/constructor. Available only inside an interceptor around body. `next()` forwards original arguments unchanged; optional labeled overrides use the interceptor parameter names and map back to the target. Unselected arguments are forwarded automatically. The compiler requires at most one next call on each execution path. Target errors propagate through the chain; additional errors declared by around become checked errors of the tagged callable.'),
-    import: keyword('import Logger and ConsoleLogger from logging', 'Bring public declarations into this file. Use `and` for several names, or `import everything from logging` for all public sibling declarations or folder exports. Imported dependencies are never re-exported implicitly. Names or modules starting with `_` stay private. A sibling module uses its filename without `.aug`; a folder exposes only names listed in `export.aug`.'),
+    import: keyword('import Logger and ConsoleLogger from logging', 'Bring public declarations into this file. Use `and` for several names, or `import everything from logging` for all public sibling declarations or folder exports. Imported dependencies are never re-exported implicitly. Names or modules starting with `_` stay private. A sibling module uses its filename without `.aug`; a folder exposes only names listed in `export.aug`. A quoted public repository URL declares a source dependency; `aug run` installs it and locks its commit. Use `aug add URL --as NAME` for a shorter import alias.'),
     and: keyword('left and right', 'Logical AND on bool values. Skip the right operand when the left operand is false. Also join named imports, checked errors, contracts, and grouped task waits. Comparisons and not bind before and; and binds before or.'),
     or: keyword('left or right', 'Logical OR on bool values. Skip the right operand when the left operand is true. This is the lowest-precedence boolean operator. Symbolic || is rejected.'),
     not: keyword('not count == 0', 'Negate a bool expression. Comparisons bind before not, so not count == 0 means not (count == 0). not binds before and and or. Use parentheses to negate only one comparison operand. Symbolic ! is rejected; != remains inequality.'),
@@ -75,10 +75,10 @@ export const languageHelp = {
     pass: keyword('pass', 'An empty body. Use it inside an indented interface, class, function, or statement block. It performs no operation. Empty braced blocks may use {} instead.'),
     in: keyword('interface Consumer<in T>', 'Declare a contravariant interface type parameter. It may occur only in checked input positions. User-defined types are otherwise invariant. The same word is used by for iteration.'),
     out: keyword('interface Producer<out T>', 'Declare a covariant interface type parameter. It may occur only in checked output positions. Mutable containers are invariant; classes and interceptors cannot declare variance.'),
-    changes: keyword('increment() changes self', 'Declare observable mutation of self or a borrowed input. Callers must provide mutable access. Ordinary functions and methods are pure by default; changing a local variable or a fresh local object does not change caller-owned state.'),
-    uses: keyword('save(resolve FileWriter files, string path) uses files.write unless FileError', 'Declare the external capability operations this callable may use. Interfaces, public standalone functions, default methods and interceptor around methods keep explicit contracts. Class implementations and private helpers infer uses when omitted; hover, explain and API docs show the result. An explicit uses clause remains an upper bound. Effects are checked through calls and interceptor layers; implementations cannot exceed their interface contract. changes and unless remain explicit, and construction stays pure.'),
-    mutable: keyword('Counter(mutable int initial to _count)', 'Declare mutable class storage. Header fields are otherwise read-only after construction. An explicit public argument label can initialize private storage with Type label to _field. Mutating methods declare changes self and callers provide mutable access.'),
-    capability: keyword('capability Console { write(string value) uses Console.write }', 'Declare an interface for an external effect. Import the standard Console, FileReader, FileWriter and Arguments contracts from august.io, select adapters in main, and receive them through resolve parameters. Operations remain visible in uses clauses and can be replaced in tests.'),
+    changes: keyword('increment() changes self', 'Describe observable mutation of self or a borrowed input. Bodies infer changes when omitted; callers still need mutable access. Bodyless interface contracts declare permitted mutation. Local variables and fresh local objects do not change caller-owned state. An explicit clause limits the body.'),
+    uses: keyword('save(resolve FileWriter files, string path)', 'Bodies infer external capability operations when uses is omitted, including public functions, default methods and interceptor around methods. The editor shows non-editable inline hints; hover, explain, API docs and compiled specs expose checked contracts. Bodyless interfaces and extern declarations keep explicit contracts. An explicit uses clause remains an upper bound. Implementations cannot exceed their interface contract; construction and cleanup stay pure.'),
+    mutable: keyword('Counter(mutable int initial to _count)', 'Declare mutable class storage. Header fields are otherwise read-only after construction. An explicit public argument label can initialize private storage with Type label to _field. Bodies infer changes self; callers provide mutable access.'),
+    capability: keyword('capability Console { write(string value) uses Console.write }', 'Declare an interface for an external effect. Import the standard Console, FileReader, FileWriter and Arguments contracts from august.io, select adapters in main, and receive them through resolve parameters. Operations stay visible in inferred hints, hover and specs and can be replaced in tests.'),
     from: keyword('import Name from module;', 'Names the source of an import or export. Dotted paths cross folders; each crossed folder must expose the next one with `export folder child;`. A module starting with `_` is private.'),
     export: keyword('export Name from sibling;', 'Expose a public sibling declaration to other folders. Names, modules, and folders starting with `_` are private and cannot be exported. Export declarations belong only in `export.aug`.\n\n```aug\nexport Logger from logger;\n```'),
     folder: keyword('export folder child;', 'Expose a public child folder through the current folder’s `export.aug`. A folder starting with `_` cannot be exported.'),
@@ -91,12 +91,12 @@ export const languageHelp = {
     interface: keyword('interface Name extends Parent { ... }', 'Declare a contract. Interfaces may extend several interfaces and may provide default method bodies. A class must implement every method without a default. Method signatures start with their name, for example `log(string message);`.'),
     implements: keyword('Name() implements Interface { ... }', 'Marks a declaration as a class and lists the interfaces it satisfies. Every class needs at least one interface. Method signatures must match. Conflicting default implementations require an override. Put constructor work in an initialize block inside the class.'),
     extends: keyword('interface Child extends Parent, Other { ... }', 'Inherit methods from one or more interfaces. Class inheritance is not supported.'),
-    function: keyword('No function keyword', 'Functions and methods start with their name: `greet(string name) { ... }` or `greet(string name) returns string;`. Remove the old `function` prefix. Parameters use `Type name` order and callers use labels. Omit `returns` for a `void` result.'),
-    returns: keyword('name() returns Type', 'Specify a function or method return type. Without this clause, the result is `void`; the body may end without `return` or use `return;`. Returning a value requires a declared return type. `returns own Type` transfers ownership to the caller.'),
+    function: keyword('No function keyword', 'Functions and methods start with their name: greet(string name) { ... }. Remove the old function prefix. Parameters use Type name order and callers use labels. Bodies infer omitted returns, changes, uses and unless clauses; declarations without a body keep explicit contracts.'),
+    returns: keyword('name() returns Type', 'Bodies infer their result from return expressions or their implemented interface when this clause is omitted. No returned value means void. Bodyless signatures still need non-void result types. Explicit result types are checked assertions; returns own Type explicitly transfers ownership. Recursive or ambiguous results may require a type anchor.'),
     return: keyword('return expression;', 'Finish the current function or method and give its result to the caller. A `void` function can use `return;`.'),
-    unless: keyword('load(bool fail) returns string unless FileError', 'Declare checked failures a function may raise instead of returning its result. Callers must catch the failures or declare them with unless too. Separate several types with `and` or commas; `unless Error` accepts any error type. The statement that raises an error remains `throw`.'),
+    unless: keyword('load(bool fail) unless FileError', 'Describe checked failures that escape a call. Bodies infer uncaught errors when unless is omitted; catch blocks remove handled errors. Main must handle escaping errors. Bodyless interfaces declare permitted failures. Explicit unless remains an upper bound; unless Error accepts any error type. Record validation can infer its failures too.'),
     throws: keyword('Use unless', 'This old error-contract spelling is rejected. Replace `throws FileError` with `unless FileError`. Javadoc `@throws` remains supported.'),
-    throw: keyword('throw error;', 'Raise a value whose class implements `Error`. The enclosing function must declare the error or the call must be handled by a matching `catch`.'),
+    throw: keyword('throw error;', 'Raise a value whose class implements `Error`. An executable body infers uncaught errors; main must handle them with a matching catch.'),
     try: keyword('try { ... } catch Error error { ... }', 'Run statements that may throw checked errors. Add a `catch` for each error, or use `catch Error` for any throwable error.'),
     catch: keyword('catch Error error { ... }', 'Handle a thrown error from the preceding `try` block. The caught value is available under the name after its type.'),
     if: keyword('if condition: ...', 'Run a block when its condition is bool. Use braces or a trailing colon and an indented body. Tabs or spaces are accepted; mixed indentation prefixes are rejected.'),
@@ -105,7 +105,7 @@ export const languageHelp = {
     own: keyword('own Type name to expression;', 'Give a value exclusive ownership and deterministic cleanup at scope exit. Owned values cannot be copied; they can move into `own` parameters, fields, or returns. `=` is also accepted.\n\n```aug\nown Resource resource to Resource();\n```'),
     borrow: keyword('borrow value { ... }', 'Take exclusive mutable access for the duration of this block. Ordinary reads need no borrow. Managed List, Set, and Map mutations require one. Starting a child that reads the value suspends this mutation right until wait for the child.\n\n```aug\nborrow items { items.append(value=1) }\n```'),
     unsafe: keyword('unsafe { ... }', 'Permit calls to declared `extern C` functions within this block. The compiler does not verify the safety of foreign code.'),
-    extern: keyword('extern C name(Type arg) returns Type', 'Declare a C function. Calls require unsafe and external callables declare uses C.name. int maps to int64_t, c_int to signed 32-bit int, float to double, bool to C bool, and string to a temporary UTF-8 const char pointer. Foreign code must respect the declared ABI and cannot retain managed pointers.'),
+    extern: keyword('extern C name(Type arg) returns Type', 'Declare a C function. Calls require unsafe and executable callers infer uses C.name. int maps to int64_t, c_int to signed 32-bit int, float to double, bool to C bool, and string to a temporary UTF-8 const char pointer. Foreign code must respect the declared ABI and cannot retain managed pointers.'),
     C: keyword('extern C name(...);', 'Selects C as the foreign function interface for an `extern` declaration.'),
     true: keyword('true', 'Boolean true. Conditions and logical operators require `bool`.'),
     false: keyword('false', 'Boolean false. and and or evaluate the right side only when needed. Conditions require bool values.'),
@@ -116,7 +116,7 @@ export const languageHelp = {
     string: type('string', 'Immutable valid Unicode encoded as UTF-8, without embedded NUL. Invalid literals are compile errors and invalid text files raise FileError. The + operator joins strings. C string pointers live only for the unsafe call.'),
     void: type('void', 'No return value. A function can omit `returns void`.'),
     Error: type('Error', 'Root throwable interface. User defined error classes implement `Error`; `catch Error` handles any throwable type.'),
-    FileError: type('FileError', 'Built in checked error from text file operations. Catch it or declare `unless FileError`.'),
+    FileError: type('FileError', 'Checked failure from text file operations. Catch it or let it propagate.'),
     List: type('List<T>', 'Ordered collection: `[1, 2]` infers List<int>. A typed declaration supplies empty or nested literal types: `List<int> numbers = []`. `List<T>(...)` also accepts positional elements. `append(value=...)` requires mutable access; `get(index=...)` reads; `length()` returns its size.'),
     Set: type('Set<T>', 'Hash set of unique values: `{1, 2, 1}` infers Set<int> with two items. Use `Set<int> numbers = {}` or `Set<int>()` for an empty set. `add(value=...)` requires mutable access; `contains(value=...)` and `length()` read. Primitive values and immutable tuples use value equality; other objects use identity.'),
     Tuple: type('Tuple<T1, T2, ...>', 'Fixed immutable positions: `(1, 2)` infers Tuple<int, int>, `(1, "apple")` infers Tuple<int, string>. `(1)` is grouping, `(1,)` is a singleton tuple, and `()` is empty. `get(index=0)` requires a constant index so its result type is known. `length()` reads its size. Tuples compare by their items; contained objects remain managed references.'),
@@ -170,9 +170,9 @@ for (const operation of builtinFunctions)
             (operation.errors?.length ? ` unless ${operation.errors.join(' and ')}` : ''), operation.documentation);
 export const diagnosticHelp = {
     SYNTAX: 'Use word boolean operators, initialize blocks, optional Type, implement with, and resolve Key to name. The editor migration fix or aug migrate --write upgrades rejected legacy spellings while preserving grouping.',
-    NATIVE: 'The native C toolchain reported an error at this AugScript source location. Check the external C declaration, linker configuration, and generated .aug-build/program.c; debug builds retain source line mapping.',
+    NATIVE: 'The C compiler reported an error at this August location. Check the external C declaration and main.yaml libraries/library_paths. Native commands prepare required pinned libraries automatically. Missing system tools include installation help. If valid August code fails without an external C boundary, report the compiler output and generated .aug-build/program.c.',
     CONFIG: 'main.yaml uses the documented scalar settings and list settings. Duplicate keys, unsupported values, and unknown lint rules are errors during check.',
-    PACKAGE: 'Declare an import alias in main.yaml packages (or aug-package.json dependencies for a library), then run aug install. Commit aug.lock.json; use --frozen in CI. Imports cross only export.aug boundaries. Installed sources and compiler versions must match the lock; build/check never fetch packages.',
+    PACKAGE: 'Import directly from a quoted public repository URL, or use aug add URL --as NAME to declare an alias in main.yaml. aug run prepares declared application packages; aug install prepares them explicitly. Commit aug.lock.json and use aug install --frozen in CI. Changed installed sources require an explicit reinstall. Imports cross only export.aug boundaries. Installed sources and compiler versions must match the lock; build/check never fetch source packages.',
     MODULE: 'Keep imports acyclic and follow main.yaml module_dependencies. strict_modules also requires sibling public imports to appear in export.aug.',
     LINT: 'Optional project policies point out hidden dependencies, discarded errors, and growing public surfaces. Enable individual rules in main.yaml lint.',
     DOC: 'Javadoc @param names use public input labels. @return requires a value-returning callable; @throws names an unless error. Enable public_docs for missing-documentation warnings.',
@@ -182,8 +182,9 @@ export const diagnosticHelp = {
     ITERATION: 'for traverses a List, Set, Map, or homogeneous Tuple. Use tuple destructuring for map entries and heterogeneous tuples.',
     NUMBER: 'int is signed 64-bit with defined wrapping arithmetic. Integer literal spelling is exact. Float literals must be finite.',
     TEXT: 'Strings contain valid Unicode encoded as UTF-8, without NUL. Binary data needs an explicit unsafe adapter.',
-    EFFECT: 'Public function and interface contracts explicitly declare uses capability.operation. Implementations and private helpers infer omitted uses, while explicit clauses remain upper bounds. Declare changes for mutation and unless for errors. Receive dependencies in resolve header parameters; constructors and cleanup remain pure. Inferred effects cannot exceed an implemented interface or hold a lock during I/O.',
-    MUTABILITY: 'Class storage is read-only after construction unless marked mutable. Managed function inputs grant reading; use a borrow parameter and a changes contract to mutate them. Public read-only fields do not grant mutable access through aliases.',
+    EFFECT: 'Bodies infer capability use and mutation. Bodyless interfaces declare permitted effects; explicit clauses remain upper bounds. Receive dependencies in resolve header parameters. Inferred effects cannot exceed an implemented interface, grant mutation of managed inputs, add constructor I/O, or hold a lock during I/O.',
+    INFERENCE: 'Add a result or effect type anchor when recursion has no evidence or keeps expanding generic types. Bodies infer omitted contracts; bodyless and foreign declarations describe them explicitly.',
+    MUTABILITY: 'Class storage is read-only after construction unless marked mutable. Managed function inputs grant reading; use a borrow parameter to mutate them; bodies infer the changes contract. Public read-only fields do not grant mutable access through aliases.',
     GENERIC: 'Type arguments must be concrete at a call and consistent across labeled inputs. Mutable and user-defined types are invariant by default. Supply explicit type arguments when inputs do not determine them.',
     INDENT: 'Put the body after a trailing colon on the next line. Indent beyond its header, keep each block level consistent, and use tabs or spaces without mixing them in a prefix. Dedent to an enclosing level; use pass for an empty body.',
     COLLECTION: 'Use compatible item types or a declared collection type. Empty [] and {} need a contextual type. A tuple may contain different types; tuple.get needs a constant index.',

package/src/http-contracts.js

@@ -0,0 +1,14 @@
+import { parse } from "./parser.js";
+// These declarations describe the native policy ABI. Package names do not determine compatibility.
+// Keep this schema aligned with the capabilities exported by the web library.
+const source = `record Principal(string subject, List<string> permissions)
+capability Authentication:
+    authenticate(HttpRequest request) returns optional Principal uses Authentication.authenticate unless HttpError
+capability Authorization:
+    authorize(Principal identity, string permission) returns bool uses Authorization.authorize unless HttpError
+capability RequestLogger:
+    complete(string method, string path, int status, int milliseconds) uses RequestLogger.complete
+`;
+export const nativeHttpContracts = new Map(parse('<native-http-contracts>', source).file.items
+    .filter(item => item.kind === 'interface' || item.kind === 'class')
+    .map(item => [item.name, item]));

package/src/http-policies.js

@@ -10,10 +10,10 @@ export const httpPolicyOptions = {
     Cors: { origins: 'strings', headers: 'optional strings', credentials: 'optional bool' }, Compress: {},
 };
 export const httpPolicyOptionHelp = {
-    authentication: 'Map an explicit resolve Authentication input. Declare uses input.authenticate. Missing identity returns 401 before wire decoding.',
-    authorization: 'Map an explicit resolve Authorization input. Declare uses input.authorize. Denied permission returns 403.',
+    authentication: 'Map an explicit resolve Authentication input. The compiler infers input.authenticate. Missing identity returns 401 before wire decoding.',
+    authorization: 'Map an explicit resolve Authorization input. The compiler infers input.authorize. Denied permission returns 403.',
     permission: 'Literal nonempty permission checked by the authorization adapter.',
-    logger: 'Map an explicit resolve RequestLogger input. Declare uses input.complete. The logger runs after completion or disconnect; put LogRequest first to observe rejected requests.',
+    logger: 'Map an explicit resolve RequestLogger input. The compiler infers input.complete. The logger runs after completion or disconnect; put LogRequest first to observe rejected requests.',
     requests: 'Literal request count per trusted transport peer and endpoint, from 1 to 1000000. Excess returns 429.',
     seconds: 'Literal fixed-window duration, from 1 to 86400 seconds.',
     milliseconds: 'Literal deadline from 1 to 3600000 milliseconds, covering handler, child tasks and response transport. Before output it returns 504; after output it closes the stream.',
@@ -44,10 +44,10 @@ export function checkHttpPolicy(annotation, fn, diagnostics, canonical) {
             if (entry.value || !param?.injected || param.type.name !== type || param.type.nullable || param.type.optional)
                 report(`${name}.${entry.name} maps an explicit resolve ${type} endpoint parameter`);
             else if (!canonical(param, type))
-                report(`${name}.${entry.name} requires the august.web ${type} capability`);
+                report(`${name}.${entry.name} requires a compatible ${type} capability from the web library`);
             else {
                 dependencies[Object.keys(specs[name]).filter(key => specs[name][key].startsWith('dependency:')).indexOf(entry.name)] = index;
-                if (!fn.uses?.some(effect => effect.source === param.name && effect.operation === operation))
+                if (fn.uses?.length && !fn.uses.some(effect => effect.source === param.name && effect.operation === operation))
                     report(`Declare uses ${param.name}.${operation} for ${name}`);
             }
             continue;

package/src/libraries.js

@@ -15,7 +15,7 @@ export function standardLibraries() {
             throw new Error(`August ${name} must match compiler ${version}; reinstall the CLI and its pinned libraries.`);
         return join(dirname(file), manifest.source);
     };
-    return { root: load('stdlib'), modules: new Map([['web', load('web')], ['crypto', load('crypto')]]) };
+    return { root: load('stdlib'), modules: new Map() };
 }
 export function libraryChild(libraries, folder, name) {
     return folder === libraries.root ? libraries.modules.get(name) ?? join(folder, name) : join(folder, name);

package/src/lsp.js

@@ -49,7 +49,7 @@ export async function runLanguageServer(root) {
         if (message.method === 'initialize')
             result = { capabilities: {
                     textDocumentSync: { openClose: true, change: 1 }, hoverProvider: true, completionProvider: { triggerCharacters: ['.', '(', '=', ' '] },
-                    definitionProvider: true, documentFormattingProvider: true, codeActionProvider: true,
+                    definitionProvider: true, documentFormattingProvider: true, codeActionProvider: true, inlayHintProvider: true,
                     semanticTokensProvider: { legend: { tokenTypes, tokenModifiers: ['declaration'] }, full: true },
                 }, serverInfo: { name: 'AugScript', version: compilerVersion() } };
         else if (message.method === 'shutdown')
@@ -92,7 +92,8 @@ export async function runLanguageServer(root) {
             const view = document(uri), offset = params.offset ?? 0;
             result = params.command === 'hover' ? view.hover(offset) ?? null : params.command === 'complete' ? view.complete(offset) :
                 params.command === 'fixes' ? view.fixes() : params.command === 'semantic-tokens' ? view.tokens() :
-                    params.command === 'format' ? view.format() : params.command === 'definition' ? view.definition(offset) ?? null : params.command === 'diagnostics' ? view.diagnostics.map(issue => ({ ...issue, help: diagnosticHelp[issue.code] })) : view.describe(params.options);
+                    params.command === 'inlay-hints' ? view.inlayHints(params.options?.start, params.options?.end) :
+                        params.command === 'format' ? view.format() : params.command === 'definition' ? view.definition(offset) ?? null : params.command === 'diagnostics' ? view.diagnostics.map(issue => ({ ...issue, help: diagnosticHelp[issue.code] })) : view.describe(params.options);
         }
         else if (message.method.startsWith('textDocument/')) {
             const view = document(params.textDocument.uri);
@@ -101,11 +102,18 @@ export async function runLanguageServer(root) {
                 const hover = view.hover(offset);
                 result = hover ? { contents: { kind: 'markdown', value: `\`\`\`augscript\n${hover.detail}\n\`\`\`\n\n${hover.documentation ?? ''}` } } : null;
             }
+            else if (message.method === 'textDocument/inlayHint')
+                result = view.inlayHints(params.range ? offsetAt(view.source, params.range.start) : undefined, params.range ? offsetAt(view.source, params.range.end) : undefined).map(hint => ({
+                    position: positionAt(view.source, hint.offset), label: hint.label, kind: 1,
+                    paddingLeft: true, tooltip: { kind: 'markdown', value: hint.tooltip },
+                }));
             else if (message.method === 'textDocument/completion')
                 result = view.complete(offset).map(item => ({ label: item.label,
                     kind: { method: 2, function: 3, variable: 6, class: 7, interface: 8, property: 10, keyword: 14, snippet: 15, type: 25 }[item.kind] ?? 6,
                     detail: item.detail, documentation: { kind: 'markdown', value: item.documentation ?? '' }, insertText: item.insertText ?? item.label,
-                    insertTextFormat: item.kind === 'snippet' ? 2 : 1 }));
+                    insertTextFormat: item.insertText ? 2 : 1, sortText: item.sortText,
+                    textEdit: item.replacement ? { range: { start: positionAt(view.source, item.replacement.start), end: positionAt(view.source, item.replacement.end) }, newText: item.insertText ?? item.label } : undefined,
+                    additionalTextEdits: item.additionalEdits?.map(edit => ({ range: { start: positionAt(view.source, edit.start), end: positionAt(view.source, edit.end) }, newText: edit.text })) }));
             else if (message.method === 'textDocument/definition') {
                 const target = view.definition(offset);
                 result = target ? { uri: pathToFileURL(target.file).href,
@@ -114,13 +122,14 @@ export async function runLanguageServer(root) {
             else if (message.method === 'textDocument/formatting')
                 result = [{ range: { start: { line: 0, character: 0 }, end: positionAt(view.source, view.source.length) }, newText: view.format() }];
             else if (message.method === 'textDocument/codeAction')
-                result = view.fixes().map(fix => {
+                result = view.fixes().filter(fix => !params.range || fix.issue.line - 1 >= params.range.start.line && fix.issue.line - 1 <= params.range.end.line).map(fix => {
                     const changes = {};
                     for (const edit of fix.edits) {
                         const source = workspace.document(edit.file).source, uri = pathToFileURL(edit.file).href;
                         (changes[uri] ??= []).push({ range: { start: positionAt(source, edit.start), end: positionAt(source, edit.end) }, newText: edit.text });
                     }
-                    return { title: fix.title, kind: 'quickfix', edit: { changes } };
+                    return { title: fix.title, kind: 'quickfix', isPreferred: fix.preferred, diagnostics: [{ code: fix.issue.code, message: fix.issue.message,
+                                range: { start: { line: fix.issue.line - 1, character: fix.issue.column - 1 }, end: { line: fix.issue.line - 1, character: fix.issue.column } } }], edit: { changes } };
                 });
             else if (message.method === 'textDocument/semanticTokens/full') {
                 let line = 0, column = 0;

package/src/native.js

@@ -6,6 +6,8 @@ import { createHash } from 'node:crypto';
 import { loadConfig } from "./config.js";
 import { generateOpenApi } from "./openapi.js";
 import { nativeHome } from '../scripts/native-home.mjs';
+import { nativeRequirements } from '../scripts/native-setup.mjs';
+import { cCompiler, compilerHelp } from '../scripts/native-toolchain.mjs';
 export function compileNative(root, generated, options = {}) {
     const config = loadConfig(root).config;
     const buildDir = join(root, '.aug-build', ...(options.testIndex === undefined ? [] : ['tests']));
@@ -27,38 +29,38 @@ export function compileNative(root, generated, options = {}) {
     copyFileSync(join(runtimeDir, 'aug_values.c'), valuesPath);
     const outputName = options.testIndex === undefined ? options.output ?? config.output ?? basename(root) : name;
     const output = isAbsolute(outputName) ? outputName : join(buildDir, outputName);
-    const cc = process.env.CC ?? (existsSync('/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang') ?
-        '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang' : 'clang');
+    mkdirSync(dirname(output), { recursive: true });
+    const cc = cCompiler();
     const release = options.release ?? config.optimization === 'release';
     const args = [release ? '-O2' : '-O0', '-g', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra',
         '-pthread',
         cPath, runtimePath, valuesPath, ...config.library_paths.map(path => `-L${resolve(root, path)}`), ...config.libraries.map(name => `-l${name}`), '-o', output];
-    const web = generated.includes('aug_http_') || generated.includes('_aug_http_') || generated.includes('aug_headers_');
+    const needs = nativeRequirements(generated), web = needs.web;
     if (web)
         args.push('-DAUG_HTTP_RUNTIME');
-    if (generated.includes('aug_html_') || web) {
+    if (needs.html) {
         const htmlSource = join(buildDir, 'aug_html.c');
         copyFileSync(join(runtimeDir, 'aug_html.c'), htmlSource);
         args.push(htmlSource);
     }
-    if (generated.includes('_aug_time_')) {
+    if (needs.time) {
         const timeSource = join(buildDir, 'aug_time.c');
         copyFileSync(join(runtimeDir, 'aug_time.c'), timeSource);
         args.push(timeSource);
     }
-    if (web || generated.includes('aug_task_')) {
+    if (needs.tasks) {
         const taskSource = join(buildDir, 'aug_tasks.c');
         copyFileSync(join(runtimeDir, 'aug_tasks.c'), taskSource);
         const minicoro = join(nativeRoot, 'sources', 'minicoro');
         if (!existsSync(join(minicoro, 'minicoro.h')))
-            throw new Error('Task dependency is missing. Run the compiler scripts/bootstrap-native.mjs with --extract-only; AUG_NATIVE_HOME selects its directory.');
+            throw new Error('Task dependencies are missing. Run aug run to prepare them automatically, or use aug-native --extract-only --only minicoro to prewarm the cache.');
         args.push(taskSource, '-I' + minicoro, process.platform === 'darwin' ? '-D_DARWIN_C_SOURCE' : '-D_DEFAULT_SOURCE');
     }
-    if (generated.includes('_aug_crypto_') || web) {
+    if (needs.crypto) {
         const prefix = join(nativeRoot, 'prefix');
         const manifestPath = join(prefix, 'aug-native-manifest.json');
         if (!existsSync(manifestPath))
-            throw new Error('Native libraries are not ready. Run node scripts/bootstrap-native.mjs in the compiler directory; AUG_NATIVE_HOME selects its directory.');
+            throw new Error('Native libraries are not ready. Run aug run to prepare them automatically, or use aug-native to prewarm the cache.');
         const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
         if (manifest.platform !== process.platform || manifest.architecture !== process.arch)
             throw new Error(`Native dependencies target ${manifest.platform}/${manifest.architecture}; this compiler runs on ${process.platform}/${process.arch}. Build dependencies on this host.`);
@@ -74,12 +76,12 @@ export function compileNative(root, generated, options = {}) {
                 args.push('-framework', 'CoreFoundation', '-framework', 'SystemConfiguration');
         }
     }
-    if (generated.includes('_aug_json_') || generated.includes('aug_json_') || web) {
+    if (needs.json) {
         const jsonSource = join(buildDir, 'aug_json.c');
         copyFileSync(join(runtimeDir, 'aug_json.c'), jsonSource);
         const yyjson = join(nativeRoot, 'sources', 'yyjson', 'src');
         if (!existsSync(join(yyjson, 'yyjson.c')))
-            throw new Error('JSON dependency is missing. Run node scripts/bootstrap-native.mjs --extract-only.');
+            throw new Error('JSON dependencies are missing. Run aug run to prepare them automatically, or use aug-native --extract-only --only yyjson to prewarm the cache.');
         args.push(jsonSource, join(yyjson, 'yyjson.c'), '-I' + yyjson);
     }
     const sdk = '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk';
@@ -87,8 +89,12 @@ export function compileNative(root, generated, options = {}) {
         args.unshift('-isysroot', sdk);
     const compile = spawnSync(cc, args, { encoding: 'utf8', cwd: root });
     if (compile.error)
-        throw compile.error;
-    const error = compile.status === 0 ? '' : compile.stderr || compile.stdout || 'C compiler failed';
+        throw new Error(`Cannot compile the program with ${cc}: ${compile.error.message}.\n${compilerHelp()}`);
+    const detail = (compile.stderr || compile.stdout || (compile.signal ? `Compiler stopped by ${compile.signal}` : 'C compiler failed')).trim();
+    const error = compile.status === 0 ? '' : `Native compilation failed with ${cc}.\n${detail}\n` +
+        (/cannot find -l|library not found|file not found|No such file/.test(detail) ?
+            'Check main.yaml libraries/library_paths and the named header or library. On Linux, HTTP also needs zlib development headers.\n' : '') +
+        `Generated C: ${cPath}\nIf this is valid August code without external C declarations, please report it with this compiler output.`;
     const diagnostics = [];
     for (const match of error.matchAll(/^(.+\.aug):(\d+):(\d+):\s*(?:fatal )?error:\s*(.+)$/gm))
         diagnostics.push({ file: match[1], line: Number(match[2]), column: Number(match[3]), code: 'NATIVE', message: match[4] });

package/src/navigation.js

@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { lex } from "./lexer.js";
 import { libraryChild } from "./libraries.js";
+import { isGitSource, sourceAlias } from "./git-packages.js";
 function definitionTarget(def) {
     const span = def.node.kind === 'interceptor' ? def.node.nameSpan : def.node.span;
     return { name: def.name, file: def.file, line: span.line,
@@ -41,7 +42,8 @@ function importPathTarget(project, importer, from, name, segment) {
         return exportTarget(project, folder, name, segment < from.length - 1 ? from[segment + 1] : undefined);
     }
     const owner = importer.package ? project.packages.scopes.get(importer.package) : undefined;
-    const dependency = owner ? project.packages.scopes.get(owner.dependencies[from[0]]) : project.packages.roots.get(from[0]);
+    const alias = isGitSource(from[0]) ? sourceAlias(from[0]) : from[0];
+    const dependency = owner ? project.packages.scopes.get(owner.dependencies[alias]) : project.packages.roots.get(alias);
     if (dependency) {
         const folder = join(dependency.sourceRoot, ...from.slice(1, segment + 1));
         return exportTarget(project, folder, name, segment < from.length - 1 ? from[segment + 1] : undefined);
@@ -128,7 +130,7 @@ export function definitionAt(project, fileName, offset) {
             entry.span.end <= item.span.end);
         const fromIndex = declarationTokens.findIndex(entry => entry.kind === 'from');
         const sourceTokens = declarationTokens.slice(fromIndex + 1)
-            .filter(entry => entry.kind === 'identifier');
+            .filter(entry => entry.kind === 'identifier' || entry.kind === 'string');
         const segments = item.kind === 'import' ? item.from : [item.from];
         const selected = token.kind === 'from' ? segments.length - 1 :
             sourceTokens.findIndex((entry) => entry === token);