@greenpandastudios/aug-cli 0.19.0

package/docs/examples/hello/logging/console.md

@@ -0,0 +1,121 @@
+---
+title: "logging/console.aug · Hello world with dependencies"
+generated: true
+source: "examples/hello/logging/console.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `logging/console.aug`
+
+[Hello world with dependencies](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`app/export.aug`](../app/export.md)
+- [`app/greeter.aug`](../app/greeter.md)
+- [`logging/console.aug`](console.md)
+- [`logging/export.aug`](export.md)
+- [`logging/logger.aug`](logger.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console from august.io
+import Logger from logger
+ConsoleLogger() implements Logger:
+    log(resolve Console console, string message) uses Console.write:
+        console.write(value=message)
+```
+
+```aug [Braces]
+import Console from august.io
+import Logger from logger
+ConsoleLogger() implements Logger {
+    log(resolve Console console, string message) uses Console.write {
+        console.write(value=message)
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- [`ConsoleLogger`](console.md#symbol-ConsoleLogger) is a class implementing `Logger`.
+
+### `ConsoleLogger` {#symbol-ConsoleLogger}
+
+[source](console.md#code)
+
+Behavioral class.
+
+Satisfies [`Logger`](logger.md#symbol-Logger).
+
+#### `ConsoleLogger.log` {#symbol-ConsoleLogger.log}
+
+[source](console.md#code)
+
+**Inputs**
+
+- `console` ([`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+**What it does**
+
+- Call [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write) on `console` with `value` = `message`.
+
+**Author documentation**
+
+Writes one message.
+
+**Parameters**
+- `message`: Text to write.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+
+#### [`Logger`](logger.md#symbol-Logger)
+
+Interface from `logger`.
+
+Used as a type or provider.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/hello/logging/export.md

@@ -0,0 +1,71 @@
+---
+title: "logging/export.aug · Hello world with dependencies"
+generated: true
+source: "examples/hello/logging/export.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `logging/export.aug`
+
+[Hello world with dependencies](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`app/export.aug`](../app/export.md)
+- [`app/greeter.aug`](../app/greeter.md)
+- [`logging/console.aug`](console.md)
+- [`logging/export.aug`](export.md)
+- [`logging/logger.aug`](logger.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+export Logger from logger
+export ConsoleLogger from console
+```
+
+```aug [Braces]
+export Logger from logger
+export ConsoleLogger from console
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Export `Logger` from this folder.
+- Export `ConsoleLogger` from this folder.
+
+### Folder exports
+
+- Export the declaration `Logger` from [`logger.aug`](logger.md#symbol-Logger).
+- Export the declaration `ConsoleLogger` from [`console.aug`](console.md#symbol-ConsoleLogger).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/hello/logging/logger.md

@@ -0,0 +1,120 @@
+---
+title: "logging/logger.aug · Hello world with dependencies"
+generated: true
+source: "examples/hello/logging/logger.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `logging/logger.aug`
+
+[Hello world with dependencies](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`app/export.aug`](../app/export.md)
+- [`app/greeter.aug`](../app/greeter.md)
+- [`logging/console.aug`](console.md)
+- [`logging/export.aug`](export.md)
+- [`logging/logger.aug`](logger.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console from august.io
+/** Writes messages to an application log. */
+interface Logger:
+    /**
+    * Writes one message.
+    * @param message Text to write.
+    */
+    log(resolve Console console, string message) uses Console.write
+```
+
+```aug [Braces]
+import Console from august.io
+/** Writes messages to an application log. */
+interface Logger {
+    /**
+    * Writes one message.
+    * @param message Text to write.
+    */
+    log(resolve Console console, string message) uses Console.write
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- [`Logger`](logger.md#symbol-Logger) is an interface.
+
+### `Logger` {#symbol-Logger}
+
+[source](logger.md#code)
+
+Interface.
+
+**Author documentation**
+
+Writes messages to an application log.
+
+#### `Logger.log` {#symbol-Logger.log}
+
+[source](logger.md#code)
+
+**Inputs**
+
+- `console` ([`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Writes one message.
+
+**Parameters**
+- `message`: Text to write.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/hello/main.md

@@ -0,0 +1,115 @@
+---
+title: "main.aug · Hello world with dependencies"
+generated: true
+source: "examples/hello/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Hello world with dependencies](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`app/export.aug`](app/export.md)
+- [`app/greeter.aug`](app/greeter.md)
+- [`logging/console.aug`](logging/console.md)
+- [`logging/export.aug`](logging/export.md)
+- [`logging/logger.aug`](logging/logger.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Logger from logging
+import ConsoleLogger from logging
+import Greeter from app
+implement Logger with ConsoleLogger
+implement app with Greeter
+resolve app to greeter
+greeter.greet(name="AugScript")
+```
+
+```aug [Braces]
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Logger from logging
+import ConsoleLogger from logging
+import Greeter from app
+implement Logger with ConsoleLogger
+implement app with Greeter
+resolve app to greeter
+greeter.greet(name="AugScript")
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Register 3 dependency providers before startup.
+- Run 2 other startup steps in source order.
+
+### Dependency providers
+
+Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+
+- Provide [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+- Provide [`ConsoleLogger`](logging/console.md#symbol-ConsoleLogger) when `Logger` is requested. Reuse one instance.
+- Provide [`Greeter`](app/greeter.md#symbol-Greeter) when `app` is requested. Reuse one instance. Required dependencies: `Logger`.
+
+### Startup, in source order
+
+- Set `greeter` to the instance provided for `app`.
+- Call [`Greeter.greet`](app/greeter.md#symbol-Greeter.greet) on `greeter` with `name` = `"AugScript"`; inject `console` from `Console`.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+#### [`Greeter`](app/greeter.md#symbol-Greeter)
+
+Class from `app`.
+
+- [`Greeter.greet`](app/greeter.md#symbol-Greeter.greet) (`name`: `string`) → `void`; inject `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+#### [`ConsoleLogger`](logging/console.md#symbol-ConsoleLogger)
+
+Class from `logging`.
+
+Used as a type or provider.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/http-benchmark/index.md

@@ -0,0 +1,35 @@
+---
+title: "HTTP benchmark"
+generated: true
+source: "benchmarks/http"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# HTTP benchmark
+
+Serve the typed JSON endpoint used in the throughput measurements.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`routes.aug`](routes.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check benchmarks/http
+aug spec benchmarks/http
+aug run benchmarks/http
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

package/docs/examples/http-benchmark/main.md

@@ -0,0 +1,79 @@
+---
+title: "main.aug · HTTP benchmark"
+generated: true
+source: "benchmarks/http/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[HTTP benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`routes.aug`](routes.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import reply from routes
+serve reply on port 0
+```
+
+```aug [Braces]
+import reply from routes
+serve reply on port 0
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Serve 1 HTTP route.
+
+### HTTP configuration
+
+Listen on `127.0.0.1`. Limit request bodies to 1048576 bytes and buffered responses to 4194304 bytes.
+
+### Startup, in source order
+
+- Serve [`reply`](routes.md#symbol-reply) on port `0`.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`reply`](routes.md#symbol-reply)
+
+Function from `routes`.
+
+- [`reply`](routes.md#symbol-reply) (no caller inputs) → [`Reply`](routes.md#symbol-Reply).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/http-benchmark/routes.md

@@ -0,0 +1,88 @@
+---
+title: "routes.aug · HTTP benchmark"
+generated: true
+source: "benchmarks/http/routes.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `routes.aug`
+
+[HTTP benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`routes.aug`](routes.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+record Reply(int id, string message)
+endpoint GET "/bench" as reply() returns Reply:
+    return Reply(id=7, message="hello")
+```
+
+```aug [Braces]
+record Reply(int id, string message)
+endpoint GET "/bench" as reply() returns Reply {
+    return Reply(id=7, message="hello")
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- [`Reply`](routes.md#symbol-Reply) is an immutable record.
+- [`reply`](routes.md#symbol-reply) handles `GET` `/bench` returning `Reply`.
+
+### `Reply` {#symbol-Reply}
+
+[source](routes.md#code)
+
+Immutable record.
+
+**Inputs**
+
+- `id` (`int`) — required labeled input — stored as `id` and read-only after initialization.
+- `message` (`string`) — required labeled input — stored as `message` and read-only after initialization.
+
+### `reply` {#symbol-reply}
+
+[source](routes.md#code)
+
+Returns: [`Reply`](routes.md#symbol-Reply).
+
+HTTP route: `GET` `/bench`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
+
+**What it does**
+
+- Return call [`Reply`](routes.md#symbol-Reply) with `id` = `7`; `message` = `"hello"`.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/index.md

@@ -0,0 +1,60 @@
+---
+title: "Example projects"
+generated: true
+source: "examples and benchmarks"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Example projects
+
+Browse complete August projects here in the wiki. Each source file includes formatted code in **Indentation** and **Braces** styles and its actual compiled specification. Dependency links open the matching version’s source and explanation in this wiki.
+
+Start with [Hello world with dependencies](hello/index.md), then try [a small tested application](developer-workflow/index.md). The [OpenID Connect application](oidc-login/index.md) shows a larger project with server-rendered pages and HTTP handlers.
+
+## Start here
+
+- [Hello world with dependencies](hello/index.md) — A greeter, a logger, narrow folder exports, and explicit application bindings.
+- [Labeled calls and injection](new-syntax/index.md) — Constructor injection, named inputs, ordinary functions, and same-file tests.
+- [A small tested application](developer-workflow/index.md) — A calculator module with logging, fixtures, groups, and parameterized tests.
+- [Command-line arguments](cli-args/index.md) — Read arguments, inspect collections, and return a process exit status.
+
+## Values and errors
+
+- [Lists, tuples, sets, and maps](collections/index.md) — Create typed collections and update them through checked mutable access.
+- [Generic contracts](generics/index.md) — Write reusable records, interfaces, classes, and functions with type parameters.
+- [Generic dependency injection](generic-di/index.md) — Bind a generic interface and resolve a class that uses it.
+- [Checked failures](errors/index.md) — Declare errors with unless, catch them, and run cleanup.
+
+## State and lifetime
+
+- [Read access and mutable borrows](ownership/index.md) — Share a reference for reading and grant explicit access for mutation.
+- [Move ownership](ownership-transfer/index.md) — Transfer an owned resource between labeled calls.
+- [Resource cleanup](drop/index.md) — Release an owned resource when its lifetime ends.
+- [Private state and helpers](visibility/index.md) — Keep underscore-prefixed implementation details inside their scope.
+
+## Modules and packages
+
+- [Modules and composition](approved-design/index.md) — Combine domain modules, generic values, explicit capabilities, and scoped providers.
+- [Function and constructor middleware](interceptors/index.md) — Layer interceptors, map inputs, and keep logging dependencies explicit.
+- [Create a package](packages-math/index.md) — Publish a small arithmetic library through export.aug and test its public surface.
+- [Use a package](packages-app/index.md) — Install the neighboring arithmetic package and import it through a local alias.
+
+## Native applications
+
+- [A native C boundary](ffi/index.md) — Declare a C operation and call it inside an unsafe block.
+- [A finite benchmark](benchmark/index.md) — Measure a deterministic arithmetic workload with aug bench.
+
+## Web applications
+
+- [OpenID Connect login application](oidc-login/index.md) — A login page, provider, client, session JWT, and logout flow in one August project.
+
+## Measured programs
+
+- [Startup benchmark](startup-benchmark/index.md) — The small program used to measure process startup.
+- [CPU benchmark](cpu-benchmark/index.md) — Two million dependent integer steps with a checked result.
+- [Map and Set benchmark](collections-benchmark/index.md) — Insert, find, and iterate over 20,000 collection entries.
+- [JSON benchmark](json-benchmark/index.md) — Parse, decode, and serialize a typed record 5,000 times.
+- [HTTP benchmark](http-benchmark/index.md) — Serve the typed JSON endpoint used in the throughput measurements.