@greenpandastudios/aug-cli 0.19.0

package/examples/developer-workflow/.aug-spec/august/0.19.0/io/contracts.aug.md

@@ -0,0 +1,316 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Console`](contracts.aug.md#symbol-Console) is a capability interface.
+- [`SystemConsole`](contracts.aug.md#symbol-SystemConsole) is a class implementing `Console`.
+- [`FileReader`](contracts.aug.md#symbol-FileReader) is a capability interface.
+- [`FileWriter`](contracts.aug.md#symbol-FileWriter) is a capability interface.
+- [`LocalFiles`](contracts.aug.md#symbol-LocalFiles) is a class implementing `FileReader`, `FileWriter`.
+- [`Arguments`](contracts.aug.md#symbol-Arguments) is a capability interface.
+- [`ProcessArguments`](contracts.aug.md#symbol-ProcessArguments) is a class implementing `Arguments`.
+
+<a id="symbol-Console"></a>
+
+## `Console`
+
+[source](contracts.aug#L3)
+
+Capability interface.
+
+**Author documentation**
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+
+### `Console.write`
+
+[source](contracts.aug#L5)
+
+Type parameters: `T`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Write one line of text.
+
+**Parameters**
+- `value`: Text to display.
+
+<a id="symbol-SystemConsole"></a>
+
+## `SystemConsole`
+
+[source](contracts.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Console`](contracts.aug.md#symbol-Console).
+
+**Author documentation**
+
+The native standard-output adapter. Construction performs no output.
+
+<a id="symbol-SystemConsole.write"></a>
+
+### `SystemConsole.write`
+
+[source](contracts.aug#L9)
+
+Type parameters: `T`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Call `print` with `value` = `value`.
+
+**Author documentation**
+
+Write one line of text.
+
+**Parameters**
+- `value`: Text to display.
+
+<a id="symbol-FileReader"></a>
+
+## `FileReader`
+
+[source](contracts.aug#L13)
+
+Capability interface.
+
+**Author documentation**
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+
+### `FileReader.read`
+
+[source](contracts.aug#L15)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`FileReader.read`](contracts.aug.md#symbol-FileReader.read).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Read text.
+
+**Parameters**
+- `path`: File path.
+
+**Throws**
+- `FileError`: The file could not be read.
+
+<a id="symbol-FileWriter"></a>
+
+## `FileWriter`
+
+[source](contracts.aug#L18)
+
+Capability interface.
+
+**Author documentation**
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+
+### `FileWriter.write`
+
+[source](contracts.aug#L20)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+- `content` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Write text.
+
+**Parameters**
+- `path`: File path.
+- `content`: Text.
+
+**Throws**
+- `FileError`: Writing failed.
+
+<a id="symbol-LocalFiles"></a>
+
+## `LocalFiles`
+
+[source](contracts.aug#L23)
+
+Behavioral class.
+
+Satisfies [`FileReader`](contracts.aug.md#symbol-FileReader), [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+**Author documentation**
+
+Native files. Operations are explicit; construction opens no files.
+
+<a id="symbol-LocalFiles.read"></a>
+
+### `LocalFiles.read`
+
+[source](contracts.aug#L24)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`FileReader.read`](contracts.aug.md#symbol-FileReader.read).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Return call `read_file` with `path` = `path`.
+
+**Author documentation**
+
+Read text.
+
+**Parameters**
+- `path`: File path.
+
+**Throws**
+- `FileError`: The file could not be read.
+
+<a id="symbol-LocalFiles.write"></a>
+
+### `LocalFiles.write`
+
+[source](contracts.aug#L26)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+- `content` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Call `write_file` with `path` = `path`; `content` = `content`.
+
+**Author documentation**
+
+Write text.
+
+**Parameters**
+- `path`: File path.
+- `content`: Text.
+
+**Throws**
+- `FileError`: Writing failed.
+
+<a id="symbol-Arguments"></a>
+
+## `Arguments`
+
+[source](contracts.aug#L30)
+
+Capability interface.
+
+**Author documentation**
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+
+### `Arguments.read`
+
+[source](contracts.aug#L31)
+
+Returns: `List<string>`.
+
+Capabilities: [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-ProcessArguments"></a>
+
+## `ProcessArguments`
+
+[source](contracts.aug#L34)
+
+Behavioral class.
+
+Satisfies [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+**Author documentation**
+
+Native command-line arguments.
+
+<a id="symbol-ProcessArguments.read"></a>
+
+### `ProcessArguments.read`
+
+[source](contracts.aug#L35)
+
+Returns: `List<string>`.
+
+Capabilities: [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+**What it does**
+
+- Return call `arguments`.
+
+## Built-in operations used by this file
+
+- `arguments` (no inputs) → `List<string>`: Composition arguments. Other callables receive the Arguments capability.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+- `read_file` (`path`: `string`) → `string`: Root-only UTF-8 text input. Other callables receive FileReader. Invalid Unicode and NUL raise FileError. Can fail with `FileError`.
+- `write_file` (`path`: `string`, `content`: `string`) → `void`: Root-only UTF-8 text output. Other callables receive FileWriter. Can fail with `FileError`.
+
+[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.

package/examples/developer-workflow/.aug-spec/manifest.json

@@ -0,0 +1,13 @@
+{
+  "format": 1,
+  "files": [
+    ".aug-spec/august/0.19.0/io/contracts.aug",
+    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    "calculator.aug.md",
+    "logging/console.aug.md",
+    "logging/export.aug.md",
+    "logging/logger.aug.md",
+    "main.aug.md"
+  ],
+  "digest": "315eaa1aa7535c1e0d877120cc13528bdba05fb193bcba9e466597f98958b47b"
+}

package/examples/developer-workflow/calculator.aug

@@ -0,0 +1,55 @@
+import Console and SystemConsole from august.io
+import Logger from logging
+/** Adds two integers. */
+interface Arithmetic {
+    add(resolve Console console, int left, int right) returns int uses Console.write
+}
+/** Uses the selected logger to describe each addition. */
+Calculator(resolve Logger logger to _logger) implements Arithmetic {
+    /**
+    * Adds left and right, logging the operation.
+    * @param left First integer.
+    * @param right Second integer.
+    * @return Sum of the two integers.
+    */
+    add(resolve Console console, int left, int right) returns int uses Console.write {
+        _logger.log(message="adding integers")
+        return left + right
+    }
+}
+/**
+* Demonstrates a checked failure instead of a successful result.
+* @param fail Whether to simulate a failed load.
+* @throws FileError When fail is true.
+*/
+load(bool fail) returns string unless FileError {
+    if fail {
+        throw FileError()
+    }
+    return "loaded"
+}
+/** Test adapter: keeps calculator tests independent of console output. */
+_SilentLogger() implements Logger {
+    log(resolve Console console, string message) uses Console.write {
+        pass
+    }
+}
+test Calculator calculator {
+    when "addition" {
+        implement Console with SystemConsole
+        implement Logger with _SilentLogger
+        calculator = Calculator()
+        List<int> values = [1, 2]
+        it "adds labeled inputs" {
+            assert(calculator.add(right=2, left=1) == 3)
+            borrow values {
+                values.append(value=3)
+            }
+            assert(values.length() == 3)
+        }
+        it "starts with fresh setup" {
+            assert(values.length() == 2)
+            assert(calculator.add(left=values.get(index=0), right=values.get(index=1)) == 3)
+        }
+    }
+}

package/examples/developer-workflow/calculator.aug.md

@@ -0,0 +1,228 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `calculator.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Arithmetic`](calculator.aug.md#symbol-Arithmetic) is an interface.
+- [`Calculator`](calculator.aug.md#symbol-Calculator) is a class implementing `Arithmetic`.
+- [`load`](calculator.aug.md#symbol-load) is a function returning `string`.
+- [`_SilentLogger`](calculator.aug.md#symbol-_SilentLogger) is a class implementing `Logger`.
+- [`test Calculator calculator`](calculator.aug.md#symbol-test%20Calculator%20calculator) is a same-file test suite.
+
+<a id="symbol-Arithmetic"></a>
+
+## `Arithmetic`
+
+[source](calculator.aug#L4)
+
+Interface.
+
+**Author documentation**
+
+Adds two integers.
+
+<a id="symbol-Arithmetic.add"></a>
+
+### `Arithmetic.add`
+
+[source](calculator.aug#L5)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `left` (`int`) — required labeled input.
+- `right` (`int`) — required labeled input.
+
+Returns: `int`.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-Calculator"></a>
+
+## `Calculator`
+
+[source](calculator.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Arithmetic`](calculator.aug.md#symbol-Arithmetic).
+
+**Author documentation**
+
+Uses the selected logger to describe each addition.
+
+**Inputs**
+
+- `logger` ([`Logger`](logging/logger.aug.md#symbol-Logger)) — injected; callers omit it — stored as `_logger` (private) and read-only after initialization.
+
+<a id="symbol-Calculator.add"></a>
+
+### `Calculator.add`
+
+[source](calculator.aug#L15)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `left` (`int`) — required labeled input.
+- `right` (`int`) — required labeled input.
+
+Returns: `int`.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Call [`Logger.log`](logging/logger.aug.md#symbol-Logger.log) on `_logger` with `message` = `"adding integers"`; inject `console` from `console`.
+- Return `left` plus `right`.
+
+**Author documentation**
+
+Adds left and right, logging the operation.
+
+**Returns** Sum of the two integers.
+
+**Parameters**
+- `left`: First integer.
+- `right`: Second integer.
+
+<a id="symbol-load"></a>
+
+## `load`
+
+[source](calculator.aug#L25)
+
+**Inputs**
+
+- `fail` (`bool`) — required labeled input.
+
+Returns: `string`.
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- If `fail` is true:
+  - Fail with call `FileError`. Transfer control to a matching catch or propagate the failure.
+- Return `"loaded"`.
+
+**Author documentation**
+
+Demonstrates a checked failure instead of a successful result.
+
+**Parameters**
+- `fail`: Whether to simulate a failed load.
+
+**Throws**
+- `FileError`: When fail is true.
+
+<a id="symbol-_SilentLogger"></a>
+
+## `_SilentLogger`
+
+[source](calculator.aug#L32)
+
+Behavioral class, private to this file.
+
+Satisfies [`Logger`](logging/logger.aug.md#symbol-Logger).
+
+**Author documentation**
+
+Test adapter: keeps calculator tests independent of console output.
+
+<a id="symbol-_SilentLogger.log"></a>
+
+### `_SilentLogger.log`
+
+[source](calculator.aug#L33)
+
+**Inputs**
+
+- `console` ([`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Continue without another operation.
+
+**Author documentation**
+
+**Parameters**
+- `message`: Text to write.
+
+<a id="symbol-test Calculator calculator"></a>
+
+## `test Calculator calculator`
+
+[source](calculator.aug#L37)
+
+Same-file class tests for [`Calculator`](calculator.aug.md#symbol-Calculator). Each case gets isolated setup and dependency bindings.
+
+### Group `addition`
+
+**Setup before each case**
+
+- Provide [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole) when `Console` is requested. Use a fresh instance when this provider retains state; otherwise reuse one instance.
+- Provide [`_SilentLogger`](calculator.aug.md#symbol-_SilentLogger) when `Logger` is requested. Use a fresh instance when this provider retains state; otherwise reuse one instance.
+- Set `calculator` to call [`Calculator`](calculator.aug.md#symbol-Calculator); inject `_logger` from `Logger`.
+- Set `values` of type `List<int>` to a list containing `1`, `2`.
+
+#### `adds labeled inputs`
+
+[source](calculator.aug#L43)
+
+- Call `assert` with (call [`Calculator.add`](calculator.aug.md#symbol-Calculator.add) on `calculator` with `right` = `2`; `left` = `1`; inject `console` from `Console` equals `3`).
+- Grant exclusive mutable access to `values` for this block, then end the borrow:
+  - Call `append` on `values` with `value` = `3`.
+- Call `assert` with (call `length` on `values` equals `3`).
+
+#### `starts with fresh setup`
+
+[source](calculator.aug#L50)
+
+- Call `assert` with (call `length` on `values` equals `2`).
+- Call `assert` with (call [`Calculator.add`](calculator.aug.md#symbol-Calculator.add) on `calculator` with `left` = call `get` on `values` with `index` = `0`; `right` = call `get` on `values` with `index` = `1`; inject `console` from `Console` equals `3`).
+
+## 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`.
+
+### [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+### [`Logger`](logging/logger.aug.md#symbol-Logger)
+
+Interface from `logging`.
+
+- [`Logger.log`](logging/logger.aug.md#symbol-Logger.log) (`message`: `string`) → `void`; inject `console`: [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console); uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+## Built-in operations used by this file
+
+- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
+- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<int>.length` (no inputs) → `int`: Read the number of elements.
+- `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.
+
+[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.

package/examples/developer-workflow/logging/console.aug

@@ -0,0 +1,8 @@
+import Console from august.io
+import Logger from logger
+/** Writes application messages to standard output. */
+ConsoleLogger() implements Logger {
+    log(resolve Console console, string message) uses Console.write {
+        console.write(value=message)
+    }
+}

package/examples/developer-workflow/logging/console.aug.md

@@ -0,0 +1,67 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `console.aug` 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.aug.md#symbol-ConsoleLogger) is a class implementing `Logger`.
+
+<a id="symbol-ConsoleLogger"></a>
+
+## `ConsoleLogger`
+
+[source](console.aug#L4)
+
+Behavioral class.
+
+Satisfies [`Logger`](logger.aug.md#symbol-Logger).
+
+**Author documentation**
+
+Writes application messages to standard output.
+
+<a id="symbol-ConsoleLogger.log"></a>
+
+### `ConsoleLogger.log`
+
+[source](console.aug#L5)
+
+**Inputs**
+
+- `console` ([`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it.
+- `message` (`string`) — required labeled input.
+
+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` = `message`.
+
+**Author documentation**
+
+**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`](../.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`.
+
+### [`Logger`](logger.aug.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/examples/developer-workflow/logging/export.aug

@@ -0,0 +1,2 @@
+export Logger from logger
+export ConsoleLogger from console