@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/visibility/counter.md

@@ -29,30 +29,32 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 interface ICounter:
     label() returns string
 Counter(mutable int value) implements ICounter:
-    _label() returns string:
+    _label():
         return _prefix()
-    label() returns string:
+    label():
         return self._label()
-_prefix() returns string:
+_prefix():
     return "count"
 ```
 
 ```aug [Braces]
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 interface ICounter {
     label() returns string
 }
 Counter(mutable int value) implements ICounter {
-    _label() returns string {
+    _label() {
         return _prefix()
     }
-    label() returns string {
+    label() {
         return self._label()
     }
 }
-_prefix() returns string {
+_prefix() {
     return "count"
 }
 ```
@@ -65,77 +67,27 @@ _prefix() returns string {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `ICounter` · interface · [source](counter.md#code) {#symbol-ICounter}
 
-### In this file
+#### `ICounter.label` · [source](counter.md#code) {#symbol-ICounter.label}
 
-- [`ICounter`](counter.md#symbol-ICounter) is an interface.
-- [`Counter`](counter.md#symbol-Counter) is a class implementing `ICounter`.
-- [`_prefix`](counter.md#symbol-_prefix) is a function returning `string`.
+It returns `string`.
 
-### `ICounter` {#symbol-ICounter}
+### `Counter` · class · [source](counter.md#code) {#symbol-Counter}
 
-[source](counter.md#code)
+It implements [`ICounter`](counter.md#symbol-ICounter). It takes `value` as an integer, kept mutable.
 
-Interface.
+#### `Counter._label` · [source](counter.md#code) {#symbol-Counter._label}
 
-#### `ICounter.label` {#symbol-ICounter.label}
+It is private to its defining scope. It returns [`_prefix`](counter.md#symbol-_prefix).
 
-[source](counter.md#code)
+#### `Counter.label` · [source](counter.md#code) {#symbol-Counter.label}
 
-Returns: `string`.
+It returns [`self._label`](counter.md#symbol-Counter._label).
 
-Interface contract. A selected implementation supplies the behavior.
+### `_prefix` · [source](counter.md#code) {#symbol-_prefix}
 
-### `Counter` {#symbol-Counter}
-
-[source](counter.md#code)
-
-Behavioral class.
-
-Satisfies [`ICounter`](counter.md#symbol-ICounter).
-
-**Inputs**
-
-- `value` (`int`) — required labeled input — stored as `value` and mutable.
-
-#### `Counter._label` {#symbol-Counter._label}
-
-[source](counter.md#code)
-
-Private to its defining scope.
-
-Returns: `string`.
-
-**What it does**
-
-- Return call [`_prefix`](counter.md#symbol-_prefix).
-
-#### `Counter.label` {#symbol-Counter.label}
-
-[source](counter.md#code)
-
-Returns: `string`.
-
-**What it does**
-
-- Return call [`Counter._label`](counter.md#symbol-Counter._label) on `self`.
-
-### `_prefix` {#symbol-_prefix}
-
-[source](counter.md#code)
-
-Private to its defining scope.
-
-Returns: `string`.
-
-**What it does**
-
-- Return `"count"`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It is private to its defining scope. It returns `"count"`.
 
 ::::
 

package/docs/examples/visibility/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Keep underscore-prefixed implementation details inside their scope.
 
-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.
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
 
 ## Project files
 
@@ -22,12 +22,13 @@ Read a file below to see its highlighted source and the Markdown produced by `au
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/visibility.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
 
 ```sh
-aug check examples/visibility
-aug spec examples/visibility
-aug run examples/visibility
+cd visibility
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/visibility/main.md

@@ -29,6 +29,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 counter = Counter(value=1)
 print(value=counter.label())
@@ -38,6 +39,7 @@ print(value=counter.value)
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 counter = Counter(value=1)
 print(value=counter.label())
@@ -55,41 +57,15 @@ print(value=counter.value)
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Startup
 
-### In this file
+It sets `counter` to a [`Counter`](counter.md#symbol-Counter) with `value` `1`. It prints [`counter.label`](counter.md#symbol-Counter.label). With temporary permission to change `counter`, it sets `counter.value` to `2`. It prints `counter.value`.
 
-- Run 4 other startup steps in source order.
+### Dependencies
 
-### Startup, in source order
+It uses [`Counter`](counter.md#symbol-Counter) ([`label`](counter.md#symbol-Counter.label) and `value`) from `counter`.
 
-- Set `counter` to call [`Counter`](counter.md#symbol-Counter) with `value` = `1`.
-- Call `print` with `value` = call [`Counter.label`](counter.md#symbol-Counter.label) on `counter`.
-- Grant exclusive mutable access to `counter` for this block, then end the borrow:
-  - Set `value` of `counter` to `2`.
-- Call `print` with `value` = `value` of `counter`.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Counter`](counter.md#symbol-Counter)
-
-Class from `counter`.
-
-- Construct with `value`: `int` → [`Counter`](counter.md#symbol-Counter).
-- Read `value` (`int`); its owner can change it.
-- [`Counter.label`](counter.md#symbol-Counter.label) (no caller inputs) → `string`.
-
-### Built-in operations used by this file
-
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

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

@@ -0,0 +1,168 @@
+---
+title: "forecasts.aug · Weather API"
+generated: true
+source: "examples/weather-api/forecasts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `forecasts.aug`
+
+[Weather API](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`forecasts.aug`](forecasts.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "forecasts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. */
+record WeatherForecast(string date, int temperatureC, int temperatureF, string summary)
+/** Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. */
+endpoint GET "/weatherforecast" as weatherForecast():
+    return [
+        WeatherForecast(
+            date="2026-01-01",
+            temperatureC=0,
+            temperatureF=32,
+            summary="Freezing"
+        ),
+        WeatherForecast(
+            date="2026-01-02",
+            temperatureC=10,
+            temperatureF=50,
+            summary="Cool"
+        ),
+        WeatherForecast(
+            date="2026-01-03",
+            temperatureC=20,
+            temperatureF=68,
+            summary="Mild"
+        ),
+        WeatherForecast(
+            date="2026-01-04",
+            temperatureC=30,
+            temperatureF=86,
+            summary="Warm"
+        ),
+        WeatherForecast(
+            date="2026-01-05",
+            temperatureC=35,
+            temperatureF=95,
+            summary="Hot"
+        )
+    ]
+test endpoint weatherForecast client:
+    when "forecasts":
+        it "returns_json":
+            response = client.request(method="GET", path="/weatherforecast")
+            assert(condition=response.status == 200)
+        it "rejects_other_methods":
+            response = client.request(method="POST", path="/weatherforecast")
+            assert(condition=response.status == 405)
+```
+
+```aug [Braces]
+// aug-spec: "forecasts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. */
+record WeatherForecast(string date, int temperatureC, int temperatureF, string summary)
+/** Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. */
+endpoint GET "/weatherforecast" as weatherForecast() {
+    return [
+        WeatherForecast(
+            date="2026-01-01",
+            temperatureC=0,
+            temperatureF=32,
+            summary="Freezing"
+        ),
+        WeatherForecast(
+            date="2026-01-02",
+            temperatureC=10,
+            temperatureF=50,
+            summary="Cool"
+        ),
+        WeatherForecast(
+            date="2026-01-03",
+            temperatureC=20,
+            temperatureF=68,
+            summary="Mild"
+        ),
+        WeatherForecast(
+            date="2026-01-04",
+            temperatureC=30,
+            temperatureF=86,
+            summary="Warm"
+        ),
+        WeatherForecast(
+            date="2026-01-05",
+            temperatureC=35,
+            temperatureF=95,
+            summary="Hot"
+        )
+    ]
+}
+test endpoint weatherForecast client {
+    when "forecasts" {
+        it "returns_json" {
+            response = client.request(method="GET", path="/weatherforecast")
+            assert(condition=response.status == 200)
+        }
+        it "rejects_other_methods" {
+            response = client.request(method="POST", path="/weatherforecast")
+            assert(condition=response.status == 405)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+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.
+
+### `WeatherForecast` · immutable record · [source](forecasts.md#code) {#symbol-WeatherForecast}
+
+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.
+
+### `weatherForecast` · [source](forecasts.md#code) {#symbol-weatherForecast}
+
+`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.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.
+
+### `test weatherForecast client` · [source](forecasts.md#code) {#symbol-test-20-weatherForecast-20-client}
+
+Tests [`weatherForecast`](forecasts.md#symbol-weatherForecast). Each case gets fresh setup and dependencies.
+
+#### `forecasts`
+
+##### `returns_json` · [source](forecasts.md#code)
+
+It sets `response` to `client.request` with `method` `"GET"` and `path` `"/weatherforecast"`. The test requires `response.status` equals `200`.
+
+##### `rejects_other_methods` · [source](forecasts.md#code)
+
+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/docs/examples/weather-api/index.md

@@ -0,0 +1,42 @@
+---
+title: "Weather API"
+generated: true
+source: "examples/weather-api"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Weather API
+
+Serve five simulated forecasts as typed JSON. The record, endpoint, and tests share a file; main.aug starts the listener and main.yaml enables OpenAPI.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Follow the program
+
+Read [`main.aug`](main.md). Import the forecast endpoint and serve it on port 8787.
+
+Read [`forecasts.aug`](forecasts.md). Read the response record, five fixed forecasts, and cases that exercise the endpoint pipeline.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`forecasts.aug`](forecasts.md)
+
+- [`main.yaml`](main-yaml.md)
+
+## Try this project
+
+[Download this project](/downloads/weather-api.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd weather-api
+aug check .
+aug spec .
+aug test .
+aug run .
+```
+
+[Browse all examples](../index.md)

package/docs/examples/weather-api/main-yaml.md

@@ -0,0 +1,21 @@
+---
+title: "main.yaml · Weather API"
+generated: true
+source: "examples/weather-api/main.yaml"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `main.yaml`
+
+[Weather API](index.md) · Project configuration
+
+```yaml
+block_style: indent
+openapi:
+  enabled: true
+  title: "Weather forecast API"
+  version: "0.1.0"
+```

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

@@ -0,0 +1,65 @@
+---
+title: "main.aug · Weather API"
+generated: true
+source: "examples/weather-api/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Weather API](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`forecasts.aug`](forecasts.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// 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
+```
+
+```aug [Braces]
+// 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
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### 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.md#symbol-weatherForecast) on port `8787`.
+
+### Dependencies
+
+It uses [`weatherForecast`](forecasts.md#symbol-weatherForecast) from `forecasts`.
+
+::::
+
+:::::

package/docs/examples.json

@@ -2,6 +2,15 @@
   "readme": {
     "stdout": "4\n"
   },
+  "getting-started": {
+    "stdout": "Hello, August!\n",
+    "tests": 1
+  },
+  "wiki-home": {"stdout": "21\n", "tests": 2},
+  "book-functions": {"stdout": "21\n0\n"},
+  "book-data": {"stdout": "21\nQuantity must be positive\nNo name for this identifier\n"},
+  "book-modules": {"stdout": "Hello, August!\n"},
+  "book-state": {"stdout": "4\n", "tests": 2},
   "quickstart": {
     "stdout": "Hello, AugScript!\n"
   },
@@ -40,6 +49,7 @@
   "benchmark-collections": {"stdout":"599970000\ntrue\n"},
   "benchmark-json": {"stdout":"250000\n"},
   "benchmark-http": {"buildOnly":true},
+  "docker-http": {"buildOnly":true, "tests":1},
   "web-guide": {
     "buildOnly": true,
     "tests": 3

package/docs/getting-started.md

@@ -1,5 +1,108 @@
-# Getting started
+---
+prev:
+  text: The August book
+  link: /learn/
+next:
+  text: Values and functions
+  link: /learn/values-and-functions
+---
+
+# Your first project
+
+Build a greeting application, run its test, and read its generated explanation. You will see how an August project starts and how a small module keeps its contract, implementation, and test together.
+
+You need Node.js 24 or later and npm on macOS 14+ with Apple Silicon, or GNU/Linux x64/ARM64 with glibc 2.36+. August downloads its own LLVM compiler and prebuilt runtime. You do not install Clang, LLVM, or an SDK.
+
+You can run the compiler and native libraries in [a VS Code Dev Container](dev-containers.md). The [Docker guide](docker.md) covers container builds and deployment. This chapter targets the pending 0.21.0 release; the published 0.20.1 CLI still requires a C11 compiler.
+
+## Create and run the starter
+
+Install August once, then create and run the starter:
 
 ```sh
-npx @greenpandastudios/aug-cli@next init hello-august
+npm install --global @greenpandastudios/aug-cli@next
+aug init hello-august
+cd hello-august
+aug run
 ```
+
+`init` creates a starter, including `AGENTS.md`, and refuses to replace a nonempty destination. npm supplies the CLI and its core I/O library. `aug run` defaults to the current folder: it checks the project, prepares its dependencies, compiles it, and starts it. The starter needs no additional native libraries. It prints:
+
+```text
+Hello, August!
+```
+
+Keep the terminal in `hello-august` for the rest of this chapter. The first run downloads the compiler pack; later runs reuse it. JSON, tasks, crypto, and HTTP use its prebuilt runtime components. Native packages can download additional libraries with matching platform requirements and checksums. Setup progress goes to the terminal's error stream so it does not become application output. [Packages and installation](packages.md) covers version pinning, offline runs, and the optional `npx` workflow.
+
+## Read the startup file
+
+The starter's `main.aug` contains its imports, dependency choice, and startup work:
+
+```aug project=getting-started file=main.aug
+import Greeter and SimpleGreeter from greeting
+
+implement Greeter with SimpleGreeter
+resolve Greeter to greeter
+print(value=greeter.greet(name="August"))
+```
+
+`main.aug` is the application entry point. It imports two public declarations from the sibling file `greeting.aug`. `implement` selects the provider for `Greeter`, and `resolve` obtains it as `greeter`. The last line asks for a greeting and prints the result.
+
+The call labels its input `name`. You can read what the string is for without opening the declaration. Labels also let you reorder inputs when a call has several of them.
+
+## Read the module beside it
+
+Open `greeting.aug`. These are the important declarations:
+
+```aug project=getting-started file=greeting.aug
+/** Build a greeting for a named person. */
+interface Greeter:
+    /** Return a greeting for the named person. */
+    greet(string name) returns string
+
+/** A plain-language greeting. */
+SimpleGreeter() implements Greeter:
+    greet(string name):
+        return "Hello, " + name + "!"
+
+test SimpleGreeter greeter:
+    when greetings:
+        greeter = SimpleGreeter()
+        it greets_a_person:
+            assert(greeter.greet(name="August") == "Hello, August!")
+```
+
+The interface is the caller's contract: give `greet` a string named `name`, and receive a string. `SimpleGreeter` implements that contract. Its constructor has no inputs. The method builds a string and returns it.
+
+The test lives beside the class. Its group constructs a greeter, and its case checks an exact result. The comments explain intent and supply editor help. The code describes what happens when the operation runs.
+
+## Change the greeting
+
+In `main.aug`, change `name="August"` to `name="Ada"`. Run:
+
+```sh
+aug check .
+aug run .
+aug test .
+```
+
+The application should print `Hello, Ada!`. The existing test should still pass: it constructs its own subject and checks the greeting for August. Application startup does not run during the test.
+
+Now deliberately change the call's label from `name` to `person`. `check` should fail because `greet` has no input named `person`. Restore `name` and check again. The checker verifies the contract; the test verifies a behavior you chose to exercise.
+
+## Read the generated explanation
+
+```sh
+aug spec .
+aug spec . --check
+```
+
+Open `main.aug.md` and `greeting.aug.md`. They describe the bindings, call, greeting behavior, and test. Their dependency links lead to the used declarations. Generation is deterministic and offline; it does not ask a model to summarize your application.
+
+After an edit, regenerate before committing the explanation. `--check` reports stale files and does not write them. [Compiled specifications](specifications.md) explains the full workflow and its limits.
+
+## Continue with a calculation
+
+You have created, checked, run, tested, and explained an August application. In [Values and functions](learn/values-and-functions.md), you will write a calculation without an injected dependency and learn how labeled shorthand and conditions read.
+
+For a service, try [the weather API starter](weather-api.md). You can also [browse complete projects](examples/index.md) with code and actual compiled specs beside each other. The gallery's Indentation and Braces controls display the same checked program in either block style.