@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/examples/ownership-transfer/resource.aug.md

@@ -1,89 +1,30 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `resource.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`Resource`](resource.aug.md#symbol-Resource) is a class implementing `IResource`.
-- [`IResource`](resource.aug.md#symbol-IResource) is an interface.
-- [`make`](resource.aug.md#symbol-make) is a function returning `Resource`.
-- [`consume`](resource.aug.md#symbol-consume) is a function.
+# `resource.aug`
 
 <a id="symbol-Resource"></a>
+## `Resource` · class · [source](resource.aug#L3)
 
-## `Resource`
-
-[source](resource.aug#L2)
-
-Behavioral class.
-
-Satisfies [`IResource`](resource.aug.md#symbol-IResource).
+It implements [`IResource`](resource.aug.md#symbol-IResource).
 
 <a id="symbol-Resource.drop"></a>
+### `Resource.drop` · [source](resource.aug#L4)
 
-### `Resource.drop`
-
-[source](resource.aug#L3)
-
-Returns: no value.
-
-**What it does**
-
-- Continue without another operation.
+It continues without an operation.
 
 <a id="symbol-IResource"></a>
-
-## `IResource`
-
-[source](resource.aug#L7)
-
-Interface.
+## `IResource` · interface · [source](resource.aug#L8)
 
 <a id="symbol-make"></a>
+## `make` · [source](resource.aug#L11)
 
-## `make`
-
-[source](resource.aug#L10)
-
-Returns: ownership of [`Resource`](resource.aug.md#symbol-Resource).
-
-**What it does**
-
-- Set `value` of type [`Resource`](resource.aug.md#symbol-Resource) to call [`Resource`](resource.aug.md#symbol-Resource).
-- This variable owns the value.
-- Return `value`.
+It returns ownership of [`Resource`](resource.aug.md#symbol-Resource). It sets `value` of type [`Resource`](resource.aug.md#symbol-Resource) to a [`Resource`](resource.aug.md#symbol-Resource). `value` of type [`Resource`](resource.aug.md#symbol-Resource) owns this value. It returns `value`.
 
 <a id="symbol-consume"></a>
+## `consume` · [source](resource.aug#L15)
 
-## `consume`
-
-[source](resource.aug#L14)
-
-**Inputs**
-
-- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
-- `value` ([`Resource`](resource.aug.md#symbol-Resource)) — required labeled input — transfers ownership.
-
-Returns: no value.
-
-Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-**What it does**
-
-- Call [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write) on `console` with `value` = `"consumed"`.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
-
-Capability interface from `august.io`.
-
-- [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+It takes `value` as [`Resource`](resource.aug.md#symbol-Resource) with ownership transferred. It gets `console` ([`Console`](.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console)) from dependency injection. It passes `"consumed"` to [`console.write`](.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console.write).
 
-## Shared language rules
+## Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console) ([`write`](.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console.write)) from `august.io`.

package/examples/packages/app/.aug-spec/manifest.json

@@ -5,5 +5,5 @@
     ".aug-spec/packages/@example/aug-math/0.1.0/arithmetic.aug.md",
     "main.aug.md"
   ],
-  "digest": "07fb73723b85a1925de6fcddbb4f26d2d0913f6f5a0d30c351b2c972e627c234"
+  "digest": "c9e2bd5b1eebfa1e89e7a757f0c5dc39370705c62d5fdeada8273bc6bcde3448"
 }

package/examples/packages/app/.aug-spec/packages/@example/aug-math/0.1.0/arithmetic.aug

@@ -1,6 +1,7 @@
 // Generated by aug spec. This is a copy of the installed dependency source.
+// aug-spec: "arithmetic.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Add two integers. @param left First value. @param right Second value. @return Their sum. */
-add(int left, int right) returns int:
+add(int left, int right) :
     return left + right
 
 test add:

package/examples/packages/app/.aug-spec/packages/@example/aug-math/0.1.0/arithmetic.aug.md

@@ -1,63 +1,21 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `arithmetic.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`add`](arithmetic.aug.md#symbol-add) is a function returning `int`.
-- [`test add`](arithmetic.aug.md#symbol-test%20add) is a same-file test suite.
+# `arithmetic.aug`
 
 <a id="symbol-add"></a>
+## `add` · [source](arithmetic.aug#L4)
 
-## `add`
-
-[source](arithmetic.aug#L3)
-
-**Inputs**
-
-- `left` (`int`) — required labeled input.
-- `right` (`int`) — required labeled input.
-
-Returns: `int`.
-
-**What it does**
-
-- Return `left` plus `right`.
-
-**Author documentation**
-
-Add two integers.
-
-**Returns** Their sum.
-
-**Parameters**
-- `left`: First value.
-- `right`: Second value.
+Add two integers. It takes `left` as an integer (First value) and `right` as an integer (Second value). It returns `int` — Their sum. It returns `left` plus `right`.
 
 <a id="symbol-test add"></a>
+## `test add` · [source](arithmetic.aug#L7)
 
-## `test add`
-
-[source](arithmetic.aug#L6)
-
-Same-file function tests for [`add`](arithmetic.aug.md#symbol-add). Each case gets isolated setup and dependency bindings.
-
-### Group `addition`
-
-#### `adds_two_integers`
-
-[source](arithmetic.aug#L8)
-
-- Call `assert` with (call [`add`](arithmetic.aug.md#symbol-add) with `left` = `2`; `right` = `3` equals `5`).
-
-## Built-in operations used by this file
+Tests [`add`](arithmetic.aug.md#symbol-add). Each case gets fresh setup and dependencies.
 
-- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
+### `addition`
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+#### `adds_two_integers` · [source](arithmetic.aug#L9)
 
-## Shared language rules
+The test requires [`add`](arithmetic.aug.md#symbol-add) with `left` `2` and `right` `3` equals `5`.
 
-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/examples/packages/app/main.aug

@@ -1,2 +1,3 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import add from math
 print(value=add(left=20, right=22))

package/examples/packages/app/main.aug.md

@@ -1,33 +1,13 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Startup
 
-## In this file
+It prints [`add`](.aug-spec/packages/%40example/aug-math/0.1.0/arithmetic.aug.md#symbol-add) with `left` `20` and `right` `22`.
 
-- Run 1 other startup step in source order.
+## Dependencies
 
-## Startup, in source order
+It uses [`add`](.aug-spec/packages/%40example/aug-math/0.1.0/arithmetic.aug.md#symbol-add) from `math`.
 
-- Call `print` with `value` = call [`add`](.aug-spec/packages/%40example/aug-math/0.1.0/arithmetic.aug.md#symbol-add) with `left` = `20`; `right` = `22`.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`add`](.aug-spec/packages/%40example/aug-math/0.1.0/arithmetic.aug.md#symbol-add)
-
-Function from `math`.
-
-- [`add`](.aug-spec/packages/%40example/aug-math/0.1.0/arithmetic.aug.md#symbol-add) (`left`: `int`, `right`: `int`) → `int`.
-
-## 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/examples/packages/math/.aug-spec/manifest.json

@@ -4,5 +4,5 @@
     "src/arithmetic.aug.md",
     "src/export.aug.md"
   ],
-  "digest": "2958866ecd2fe09820dc207135c3c8deae7bd2c9ab4c5999b496e34a97713b70"
+  "digest": "33e22d8c37a90b5d3259affe917ecc7c01a05aed72f713e7c9078616b2dc461a"
 }

package/examples/packages/math/aug-package.json

@@ -2,7 +2,7 @@
   "format": 1,
   "name": "@example/aug-math",
   "version": "0.1.0",
-  "compiler": "0.19.0",
+  "compiler": "0.20.1",
   "source": "src",
   "dependencies": {}
 }

package/examples/packages/math/src/arithmetic.aug

@@ -1,5 +1,6 @@
+// aug-spec: "arithmetic.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Add two integers. @param left First value. @param right Second value. @return Their sum. */
-add(int left, int right) returns int:
+add(int left, int right) :
     return left + right
 
 test add:

package/examples/packages/math/src/arithmetic.aug.md

@@ -1,63 +1,21 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `arithmetic.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`add`](arithmetic.aug.md#symbol-add) is a function returning `int`.
-- [`test add`](arithmetic.aug.md#symbol-test%20add) is a same-file test suite.
+# `arithmetic.aug`
 
 <a id="symbol-add"></a>
+## `add` · [source](arithmetic.aug#L3)
 
-## `add`
-
-[source](arithmetic.aug#L2)
-
-**Inputs**
-
-- `left` (`int`) — required labeled input.
-- `right` (`int`) — required labeled input.
-
-Returns: `int`.
-
-**What it does**
-
-- Return `left` plus `right`.
-
-**Author documentation**
-
-Add two integers.
-
-**Returns** Their sum.
-
-**Parameters**
-- `left`: First value.
-- `right`: Second value.
+Add two integers. It takes `left` as an integer (First value) and `right` as an integer (Second value). It returns `int` — Their sum. It returns `left` plus `right`.
 
 <a id="symbol-test add"></a>
+## `test add` · [source](arithmetic.aug#L6)
 
-## `test add`
-
-[source](arithmetic.aug#L5)
-
-Same-file function tests for [`add`](arithmetic.aug.md#symbol-add). Each case gets isolated setup and dependency bindings.
-
-### Group `addition`
-
-#### `adds_two_integers`
-
-[source](arithmetic.aug#L7)
-
-- Call `assert` with (call [`add`](arithmetic.aug.md#symbol-add) with `left` = `2`; `right` = `3` equals `5`).
-
-## Built-in operations used by this file
+Tests [`add`](arithmetic.aug.md#symbol-add). Each case gets fresh setup and dependencies.
 
-- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
+### `addition`
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+#### `adds_two_integers` · [source](arithmetic.aug#L8)
 
-## Shared language rules
+The test requires [`add`](arithmetic.aug.md#symbol-add) with `left` `2` and `right` `3` equals `5`.
 
-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/examples/packages/math/src/export.aug

@@ -1 +1,2 @@
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export add from arithmetic

package/examples/packages/math/src/export.aug.md

@@ -1,17 +1,7 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `export.aug` specification
+# `export.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Exports
 
-## In this file
-
-- Export `add` from this folder.
-
-## Folder exports
-
-- Export the declaration `add` from [`arithmetic.aug`](arithmetic.aug.md#symbol-add).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `add` from [`arithmetic.aug`](arithmetic.aug.md#symbol-add).

package/examples/visibility/.aug-spec/manifest.json

@@ -4,5 +4,5 @@
     "counter.aug.md",
     "main.aug.md"
   ],
-  "digest": "e1db6169882af7977c15c64a4c1739515c33d6bc940bff9ed10e45895831eb50"
+  "digest": "8da3308d21d6b02bf732832776769f237640b30ef679b02f4c29af326a7abe68"
 }

package/examples/visibility/counter.aug

@@ -1,14 +1,15 @@
+// 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"
 }

package/examples/visibility/counter.aug.md

@@ -1,87 +1,31 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `counter.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`ICounter`](counter.aug.md#symbol-ICounter) is an interface.
-- [`Counter`](counter.aug.md#symbol-Counter) is a class implementing `ICounter`.
-- [`_prefix`](counter.aug.md#symbol-_prefix) is a function returning `string`.
+# `counter.aug`
 
 <a id="symbol-ICounter"></a>
-
-## `ICounter`
-
-[source](counter.aug#L1)
-
-Interface.
+## `ICounter` · interface · [source](counter.aug#L2)
 
 <a id="symbol-ICounter.label"></a>
+### `ICounter.label` · [source](counter.aug#L3)
 
-### `ICounter.label`
-
-[source](counter.aug#L2)
-
-Returns: `string`.
-
-Interface contract. A selected implementation supplies the behavior.
+It returns `string`.
 
 <a id="symbol-Counter"></a>
+## `Counter` · class · [source](counter.aug#L5)
 
-## `Counter`
-
-[source](counter.aug#L4)
-
-Behavioral class.
-
-Satisfies [`ICounter`](counter.aug.md#symbol-ICounter).
-
-**Inputs**
-
-- `value` (`int`) — required labeled input — stored as `value` and mutable.
+It implements [`ICounter`](counter.aug.md#symbol-ICounter). It takes `value` as an integer, kept mutable.
 
 <a id="symbol-Counter._label"></a>
+### `Counter._label` · [source](counter.aug#L6)
 
-### `Counter._label`
-
-[source](counter.aug#L5)
-
-Private to its defining scope.
-
-Returns: `string`.
-
-**What it does**
-
-- Return call [`_prefix`](counter.aug.md#symbol-_prefix).
+It is private to its defining scope. It returns [`_prefix`](counter.aug.md#symbol-_prefix).
 
 <a id="symbol-Counter.label"></a>
+### `Counter.label` · [source](counter.aug#L9)
 
-### `Counter.label`
-
-[source](counter.aug#L8)
-
-Returns: `string`.
-
-**What it does**
-
-- Return call [`Counter._label`](counter.aug.md#symbol-Counter._label) on `self`.
+It returns [`self._label`](counter.aug.md#symbol-Counter._label).
 
 <a id="symbol-_prefix"></a>
+## `_prefix` · [source](counter.aug#L13)
 
-## `_prefix`
-
-[source](counter.aug#L12)
-
-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/examples/visibility/main.aug

@@ -1,3 +1,4 @@
+// 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())

package/examples/visibility/main.aug.md

@@ -1,39 +1,13 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-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.aug.md#symbol-Counter) with `value` `1`. It prints [`counter.label`](counter.aug.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.aug.md#symbol-Counter) ([`label`](counter.aug.md#symbol-Counter.label) and `value`) from `counter`.
 
-- Set `counter` to call [`Counter`](counter.aug.md#symbol-Counter) with `value` = `1`.
-- Call `print` with `value` = call [`Counter.label`](counter.aug.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.aug.md#symbol-Counter)
-
-Class from `counter`.
-
-- Construct with `value`: `int` → [`Counter`](counter.aug.md#symbol-Counter).
-- Read `value` (`int`); its owner can change it.
-- [`Counter.label`](counter.aug.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/examples/weather-api/.aug-spec/manifest.json

@@ -0,0 +1,8 @@
+{
+  "format": 1,
+  "files": [
+    "forecasts.aug.md",
+    "main.aug.md"
+  ],
+  "digest": "4cf5cab0ad2829b1364139fef04e639e2d0cc43e590b357b2e2dffde68a711eb"
+}

package/examples/weather-api/AGENTS.md

@@ -0,0 +1,17 @@
+# Working on this August project
+
+Start in main.aug. It shows the imports, dependency bindings, and application startup.
+Read the adjacent .aug.md specification before changing a source file. Generate missing
+or stale explanations with aug spec; they describe checked behavior and link dependencies.
+
+Keep tests in the file that declares the behavior. Run aug check, aug test, and aug spec
+after a change, and use aug run to compile and run the application. Run prepares required
+source packages and native libraries. Commit aug.lock.json; do not edit .aug-packages.
+
+Use labeled inputs, narrow export.aug files, and underscore-prefixed private helpers.
+Leave return types, effects, and errors to inference when an executable body provides
+the answer. Bodyless interfaces still declare their contracts. Use borrow for mutation,
+and keep unsafe native calls inside small adapters. Explain intent in Javadoc when it
+is not evident from the code. Follow the existing indentation or brace style.
+
+Language guide: https://greenpandastudios.github.io/augscript/

package/examples/weather-api/README.md

@@ -0,0 +1,19 @@
+# weather-api
+
+A simulated weather API in August. Its endpoint, JSON record, and tests live in forecasts.aug.
+
+Run the server:
+
+```sh
+aug run
+```
+
+Open http://127.0.0.1:8787/weatherforecast for five forecasts, or http://127.0.0.1:8787/docs for the OpenAPI viewer. These are fixed examples, not live weather observations.
+
+```sh
+curl http://127.0.0.1:8787/weatherforecast
+aug test
+aug spec
+```
+
+Guide: https://greenpandastudios.github.io/augscript/weather-api

package/examples/weather-api/forecasts.aug

@@ -0,0 +1,47 @@
+// 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)