@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.1/native.abi.json

@@ -0,0 +1,57 @@
+{
+  "format": 1,
+  "profile": "aug-native-abi-1",
+  "resources": [],
+  "functions": [
+    {
+      "module": "api",
+      "name": "_compress",
+      "symbol": "aug_zlib_compress_v1",
+      "params": [
+        {
+          "name": "input",
+          "kind": "bytes"
+        }
+      ],
+      "result": {
+        "kind": "bytes",
+        "release": "aug_zlib_release_v1"
+      },
+      "error": "contracts.CompressionError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    },
+    {
+      "module": "api",
+      "name": "_decompress",
+      "symbol": "aug_zlib_decompress_v1",
+      "params": [
+        {
+          "name": "input",
+          "kind": "bytes"
+        },
+        {
+          "name": "maximumOutput",
+          "kind": "i64",
+          "minimum": 0,
+          "maximum": 268435456
+        }
+      ],
+      "result": {
+        "kind": "bytes",
+        "release": "aug_zlib_release_v1"
+      },
+      "error": "contracts.CompressionError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    }
+  ]
+}

package/examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/api.aug

@@ -0,0 +1,29 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import CompressionError from contracts
+extern C _compress(Bytes input) returns Bytes unless CompressionError
+extern C _decompress(Bytes input, int maximumOutput) returns Bytes unless CompressionError
+/** Compress bytes with the standard zlib framing. */
+compress(Bytes input) returns Bytes:
+    unsafe:
+        return _compress(input)
+/** Decompress at most maximumOutput bytes (maximum 256 MiB). */
+decompress(Bytes input, int maximumOutput) returns Bytes:
+    unsafe:
+        return _decompress(input, maximumOutput)
+
+test compress:
+    when compression:
+        it preserves_bytes:
+            Bytes input = "The world runs on language".bytes()
+            Bytes packed = compress(input)
+            Bytes restored = decompress(input=packed, maximumOutput=4096)
+            assert(restored.text() == "The world runs on language")
+        it checks_output_limit:
+            Bytes packed = compress(input="length limit".bytes())
+            bool rejected = false
+            try:
+                decompress(input=packed, maximumOutput=1)
+            catch CompressionError error:
+                rejected = true
+            assert(rejected)

package/examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/api.aug.md

@@ -0,0 +1,54 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `api.aug`
+
+<a id="symbol-compress"></a>
+## `compress` · [source](api.aug#L7)
+
+Compress bytes with the standard zlib framing. It takes `input` as `Bytes`. Failures can raise [`CompressionError`](contracts.aug.md#symbol-CompressionError).
+
+Within an unsafe block, it returns [`_compress`](api.aug.md#symbol-_compress) with `input`. Native operations must satisfy their declared C contracts.
+
+<a id="symbol-decompress"></a>
+## `decompress` · [source](api.aug#L11)
+
+Decompress at most maximumOutput bytes (maximum 256 MiB). It takes `input` as `Bytes` and `maximumOutput` as an integer. Failures can raise [`CompressionError`](contracts.aug.md#symbol-CompressionError).
+
+Within an unsafe block, it returns [`_decompress`](api.aug.md#symbol-_decompress) with `input` and `maximumOutput`. Native operations must satisfy their declared C contracts.
+
+<a id="symbol-_compress"></a>
+## `_compress` · [source](api.aug#L4)
+
+It is private to its defining scope. It takes `input` as `Bytes`. It returns `Bytes`. Failures can raise [`CompressionError`](contracts.aug.md#symbol-CompressionError).
+
+Native implementation: `@greenpandastudios/aug-zlib@0.1.3`, `1.3.2`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi.json) (SHA-256 `c3d4b36eadcccd13caff71597ed77a8e7307f0cfe3d13660a8e9127efe942b3d`). It calls `aug_zlib_compress_v1` through the C ABI on the caller thread; a blocking native call blocks that thread. August copies the returned buffer, then calls `aug_zlib_release_v1` to release it. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
+
+<a id="symbol-_decompress"></a>
+## `_decompress` · [source](api.aug#L5)
+
+It is private to its defining scope. It takes `input` as `Bytes` and `maximumOutput` as an integer. It returns `Bytes`. Failures can raise [`CompressionError`](contracts.aug.md#symbol-CompressionError).
+
+Native implementation: `@greenpandastudios/aug-zlib@0.1.3`, `1.3.2`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi.json) (SHA-256 `c3d4b36eadcccd13caff71597ed77a8e7307f0cfe3d13660a8e9127efe942b3d`). It calls `aug_zlib_decompress_v1` through the C ABI on the caller thread; a blocking native call blocks that thread. August copies the returned buffer, then calls `aug_zlib_release_v1` to release it. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
+
+<a id="symbol-test compress"></a>
+## `test compress` · [source](api.aug#L15)
+
+Tests [`compress`](api.aug.md#symbol-compress). Each case gets fresh setup and dependencies.
+
+### `compression`
+
+#### `preserves_bytes` · [source](api.aug#L17)
+
+It sets `input` of type `Bytes` to `bytes` on `"The world runs on language"`. It sets `packed` of type `Bytes` to [`compress`](api.aug.md#symbol-compress) with `input`. It sets `restored` of type `Bytes` to [`decompress`](api.aug.md#symbol-decompress) with `input` from `packed` and `maximumOutput` `4096`. The test requires `restored.text` equals `"The world runs on language"`.
+
+#### `checks_output_limit` · [source](api.aug#L22)
+
+It sets `packed` of type `Bytes` to [`compress`](api.aug.md#symbol-compress) with `input` from `bytes` on `"length limit"`. It sets `rejected` to `false`.
+
+It tries to call [`decompress`](api.aug.md#symbol-decompress) with `input` from `packed` and `maximumOutput` `1`. If this work raises [`CompressionError`](contracts.aug.md#symbol-CompressionError), it sets `rejected` to `true`. The test requires `rejected` is true.
+
+## Dependencies
+
+It uses [`CompressionError`](contracts.aug.md#symbol-CompressionError) from `contracts`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/contracts.aug

@@ -0,0 +1,4 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+CompressionError(int code, string message) implements Error:
+    pass

package/examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/contracts.aug.md

@@ -0,0 +1,8 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug`
+
+<a id="symbol-CompressionError"></a>
+## `CompressionError` · class · [source](contracts.aug#L3)
+
+It implements `Error`. It takes `code` as an integer, kept read-only and `message` as a string, kept read-only.

package/examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/native.abi.json

@@ -0,0 +1,57 @@
+{
+  "format": 1,
+  "profile": "aug-native-abi-1",
+  "resources": [],
+  "functions": [
+    {
+      "module": "api",
+      "name": "_compress",
+      "symbol": "aug_zlib_compress_v1",
+      "params": [
+        {
+          "name": "input",
+          "kind": "bytes"
+        }
+      ],
+      "result": {
+        "kind": "bytes",
+        "release": "aug_zlib_release_v1"
+      },
+      "error": "contracts.CompressionError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    },
+    {
+      "module": "api",
+      "name": "_decompress",
+      "symbol": "aug_zlib_decompress_v1",
+      "params": [
+        {
+          "name": "input",
+          "kind": "bytes"
+        },
+        {
+          "name": "maximumOutput",
+          "kind": "i64",
+          "minimum": 0,
+          "maximum": 268435456
+        }
+      ],
+      "result": {
+        "kind": "bytes",
+        "release": "aug_zlib_release_v1"
+      },
+      "error": "contracts.CompressionError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    }
+  ]
+}

package/examples/native-zlib/AGENTS.md

@@ -0,0 +1,5 @@
+# Working on this August project
+
+Read each file's adjacent `.aug.md` before editing; change `.aug` source and regenerate with `aug spec .`.
+This project imports real zlib through a tagged public package. Keep dependency versions and the decompressed output bound explicit. Do not replace native operations with a mock.
+Use the August 0.21.0 LLVM preview on macOS 14+ ARM64. Run `aug install .`, `aug check .`, `aug test .`, and `aug run .`. Consumer installation must not invoke native build scripts.

package/examples/native-zlib/aug.lock.json

@@ -0,0 +1,236 @@
+{
+  "format": 1,
+  "compiler": "0.21.0",
+  "specifications": {
+    "url_d228d2263a1adea428cd": "https://github.com/GreenPandaStudios/aug-zlib#v0.1.3"
+  },
+  "roots": {
+    "url_d228d2263a1adea428cd": "packages/url_d228d2263a1adea428cd"
+  },
+  "npm": {},
+  "git": [
+    {
+      "request": "https://github.com/GreenPandaStudios/aug-zlib#v0.1.3",
+      "repository": "https://github.com/GreenPandaStudios/aug-zlib.git",
+      "revision": "v0.1.3",
+      "folder": "",
+      "commit": "827a8dde5d0d013d00fff6a2a19036b299d0085f"
+    }
+  ],
+  "packages": [
+    {
+      "path": "packages/url_d228d2263a1adea428cd",
+      "name": "@greenpandastudios/aug-zlib",
+      "version": "0.1.3",
+      "source": "src",
+      "digest": "655984ba9c26061fb89b2dbc9764a114926c1b5e1bce1fb1ff0b4f0283aab74b",
+      "dependencies": {},
+      "native": {
+        "profile": "aug-native-abi-1",
+        "bindings": "native.abi.json",
+        "bindingsSha256": "c3d4b36eadcccd13caff71597ed77a8e7307f0cfe3d13660a8e9127efe942b3d",
+        "upstream": {
+          "repository": "https://github.com/madler/zlib",
+          "version": "1.3.2",
+          "sourceRevision": "bb329a0a2cd0274d05519d61c667c062e06990d72e125ee2dfa8de64f0119d16"
+        },
+        "artifacts": [
+          {
+            "id": "linux-arm64",
+            "target": {
+              "triple": "aarch64-unknown-linux-gnu",
+              "os": "linux",
+              "arch": "arm64",
+              "minimumLibc": "2.36",
+              "cpuBaseline": "armv8-a",
+              "libc": "glibc"
+            },
+            "url": "https://github.com/GreenPandaStudios/aug-zlib/releases/download/v0.1.3/native-linux-arm64.tar.gz",
+            "sha256": "6da832fa341a1fba96643244da2bb63957107d2b1413743c363fca002e500c66",
+            "maximumDownloadBytes": 101094,
+            "maximumUnpackedBytes": 248063,
+            "link": {
+              "kind": "dynamic",
+              "libraries": [
+                "lib/libaug_zlib.so.1"
+              ]
+            },
+            "runtime": {
+              "files": [
+                "lib/libaug_zlib.so.1"
+              ],
+              "closureManifest": "runtime-files.json",
+              "relocation": "loader-relative"
+            },
+            "components": [
+              {
+                "id": "https://github.com/madler/zlib",
+                "version": "1.3.2",
+                "compatibilityKey": "aug-zlib-runtime",
+                "linkage": "static",
+                "required": true
+              }
+            ],
+            "fileManifest": "files.json",
+            "provenance": "provenance.json",
+            "notices": "THIRD_PARTY_NOTICES.md"
+          },
+          {
+            "id": "linux-x64",
+            "target": {
+              "triple": "x86_64-unknown-linux-gnu",
+              "os": "linux",
+              "arch": "x64",
+              "minimumLibc": "2.36",
+              "cpuBaseline": "x86-64",
+              "libc": "glibc"
+            },
+            "url": "https://github.com/GreenPandaStudios/aug-zlib/releases/download/v0.1.3/native-linux-x64.tar.gz",
+            "sha256": "c2a6e6522e3a96e1ee99f1b195f7457a7ab633dc05b65a29020aa5ea1ec7aa5d",
+            "maximumDownloadBytes": 109033,
+            "maximumUnpackedBytes": 205301,
+            "link": {
+              "kind": "dynamic",
+              "libraries": [
+                "lib/libaug_zlib.so.1"
+              ]
+            },
+            "runtime": {
+              "files": [
+                "lib/libaug_zlib.so.1"
+              ],
+              "closureManifest": "runtime-files.json",
+              "relocation": "loader-relative"
+            },
+            "components": [
+              {
+                "id": "https://github.com/madler/zlib",
+                "version": "1.3.2",
+                "compatibilityKey": "aug-zlib-runtime",
+                "linkage": "static",
+                "required": true
+              }
+            ],
+            "fileManifest": "files.json",
+            "provenance": "provenance.json",
+            "notices": "THIRD_PARTY_NOTICES.md"
+          },
+          {
+            "id": "macos-arm64",
+            "target": {
+              "triple": "aarch64-apple-darwin",
+              "os": "macos",
+              "arch": "arm64",
+              "minimumOS": "14.0",
+              "cpuBaseline": "armv8-a",
+              "libc": "libSystem"
+            },
+            "url": "https://github.com/GreenPandaStudios/aug-zlib/releases/download/v0.1.3/native-macos-arm64.tar.gz",
+            "sha256": "62419afbf81826f939e89be6c025781edb0cae4fe60e43736b2d3fa9fdf28dd4",
+            "maximumDownloadBytes": 39969,
+            "maximumUnpackedBytes": 106060,
+            "link": {
+              "kind": "dynamic",
+              "libraries": [
+                "lib/libaug_zlib.1.dylib"
+              ]
+            },
+            "runtime": {
+              "files": [
+                "lib/libaug_zlib.1.dylib"
+              ],
+              "closureManifest": "runtime-files.json",
+              "relocation": "loader-relative"
+            },
+            "components": [
+              {
+                "id": "https://github.com/madler/zlib",
+                "version": "1.3.2",
+                "compatibilityKey": "aug-zlib-runtime",
+                "linkage": "static",
+                "required": true
+              }
+            ],
+            "fileManifest": "files.json",
+            "provenance": "provenance.json",
+            "notices": "THIRD_PARTY_NOTICES.md"
+          }
+        ],
+        "sourceBuild": {
+          "recipe": "native/build.json",
+          "inputs": "native/sources.lock.json",
+          "tools": [
+            "Node 24+",
+            "Clang",
+            "macOS: Apple SDK",
+            "GNU/Linux: Docker with the pinned Debian 12 maintainer image and patchelf"
+          ],
+          "automatic": false
+        }
+      }
+    }
+  ],
+  "native": {
+    "format": 1,
+    "targets": {
+      "aarch64-apple-darwin/macos14": {
+        "target": {
+          "triple": "aarch64-apple-darwin",
+          "os": "macos",
+          "arch": "arm64",
+          "cpuBaseline": "armv8-a",
+          "libc": "libSystem",
+          "minimumOS": "26.0"
+        },
+        "packages": [
+          {
+            "sourcePackage": "@greenpandastudios/aug-zlib@0.1.3",
+            "sourceDigest": "655984ba9c26061fb89b2dbc9764a114926c1b5e1bce1fb1ff0b4f0283aab74b",
+            "sourceCommit": "827a8dde5d0d013d00fff6a2a19036b299d0085f",
+            "contractSha256": "c3d4b36eadcccd13caff71597ed77a8e7307f0cfe3d13660a8e9127efe942b3d",
+            "artifact": {
+              "id": "macos-arm64",
+              "target": {
+                "triple": "aarch64-apple-darwin",
+                "os": "macos",
+                "arch": "arm64",
+                "minimumOS": "14.0",
+                "cpuBaseline": "armv8-a",
+                "libc": "libSystem"
+              },
+              "url": "https://github.com/GreenPandaStudios/aug-zlib/releases/download/v0.1.3/native-macos-arm64.tar.gz",
+              "sha256": "62419afbf81826f939e89be6c025781edb0cae4fe60e43736b2d3fa9fdf28dd4",
+              "maximumDownloadBytes": 39969,
+              "maximumUnpackedBytes": 106060,
+              "link": {
+                "kind": "dynamic",
+                "libraries": [
+                  "lib/libaug_zlib.1.dylib"
+                ]
+              },
+              "runtime": {
+                "files": [
+                  "lib/libaug_zlib.1.dylib"
+                ],
+                "closureManifest": "runtime-files.json",
+                "relocation": "loader-relative"
+              },
+              "components": [
+                {
+                  "id": "https://github.com/madler/zlib",
+                  "version": "1.3.2",
+                  "compatibilityKey": "aug-zlib-runtime",
+                  "linkage": "static",
+                  "required": true
+                }
+              ],
+              "fileManifest": "files.json",
+              "provenance": "provenance.json",
+              "notices": "THIRD_PARTY_NOTICES.md"
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/examples/native-zlib/compression.aug

@@ -0,0 +1,15 @@
+// aug-spec: "compression.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import CompressionError and compress and decompress from "https://github.com/GreenPandaStudios/aug-zlib#v0.1.3"
+
+/** Compress text with zlib, then restore its bytes within a fixed output limit. */
+roundTrip() returns Bytes unless CompressionError:
+    Bytes input = "The world runs on language".bytes()
+    Bytes compressed = compress(input)
+    return decompress(input=compressed, maximumOutput=4096)
+
+test roundTrip:
+    when compression:
+        it preserves_the_original_bytes:
+            Bytes restored = roundTrip()
+            assert(restored.text() == "The world runs on language")
+            assert(restored.length() == 26)

package/examples/native-zlib/compression.aug.md

@@ -0,0 +1,27 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `compression.aug`
+
+<a id="symbol-roundTrip"></a>
+## `roundTrip` · [source](compression.aug#L5)
+
+Compress text with zlib, then restore its bytes within a fixed output limit. Failures can raise [`CompressionError`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/contracts.aug.md#symbol-CompressionError).
+
+It sets `input` of type `Bytes` to the UTF-8 bytes of `"The world runs on language"`. It sets `compressed` of type `Bytes` to [`compress`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/api.aug.md#symbol-compress) with `input`. It returns [`decompress`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/api.aug.md#symbol-decompress) with `input` from `compressed` and `maximumOutput` `4096`.
+
+<a id="symbol-test roundTrip"></a>
+## `test roundTrip` · [source](compression.aug#L10)
+
+Tests [`roundTrip`](compression.aug.md#symbol-roundTrip). Each case gets fresh setup and dependencies.
+
+### `compression`
+
+#### `preserves_the_original_bytes` · [source](compression.aug#L12)
+
+It gets `restored` of type `Bytes` from [`roundTrip`](compression.aug.md#symbol-roundTrip). The test requires `restored.text` equals `"The world runs on language"`. The test requires the byte length of `restored` equals `26`.
+
+## Dependencies
+
+It uses [`compress`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/api.aug.md#symbol-compress), [`decompress`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/api.aug.md#symbol-decompress), and [`CompressionError`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/contracts.aug.md#symbol-CompressionError) from `https://github.com/GreenPandaStudios/aug-zlib#v0.1.3`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/native-zlib/main.aug

@@ -0,0 +1,10 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import roundTrip from compression
+import CompressionError from "https://github.com/GreenPandaStudios/aug-zlib#v0.1.3"
+
+try:
+    print(value=roundTrip().text())
+catch CompressionError error:
+    print(value=error.message)
+catch ConversionError error:
+    print(value="Invalid UTF-8")

package/examples/native-zlib/main.aug.md

@@ -0,0 +1,13 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug`
+
+## Startup
+
+It prints `text` on [`roundTrip`](compression.aug.md#symbol-roundTrip). If this work raises [`CompressionError`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/contracts.aug.md#symbol-CompressionError) as `error`, it prints `error.message`. If this work raises `ConversionError`, it prints `"Invalid UTF-8"`.
+
+## Dependencies
+
+It uses [`CompressionError`](.aug-spec/packages/%40greenpandastudios/aug-zlib/0.1.3/contracts.aug.md#symbol-CompressionError) (`message`) from `https://github.com/GreenPandaStudios/aug-zlib#v0.1.3`. It uses [`roundTrip`](compression.aug.md#symbol-roundTrip) from `compression`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/new-syntax/.aug-spec/august/0.21.0/io/contracts.aug

@@ -0,0 +1,37 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console:
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console:
+    write<T>(T value):
+        print(value=value)
+
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader:
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter:
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter:
+    read(string path) :
+        return read_file(path=path)
+    write(string path, string content) :
+        write_file(path=path, content=content)
+
+/** Read command-line input through an explicit dependency. */
+capability Arguments:
+    read() returns List<string> uses Arguments.read
+
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments:
+    read() :
+        return arguments()

package/examples/new-syntax/.aug-spec/august/0.21.0/io/contracts.aug.md

@@ -0,0 +1,82 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug`
+
+<a id="symbol-Console"></a>
+## `Console` · capability interface · [source](contracts.aug#L4)
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+### `Console.write` · [source](contracts.aug#L6)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It can call [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+<a id="symbol-SystemConsole"></a>
+## `SystemConsole` · class · [source](contracts.aug#L9)
+
+The native standard-output adapter. Construction performs no output. It implements [`Console`](contracts.aug.md#symbol-Console).
+
+<a id="symbol-SystemConsole.write"></a>
+### `SystemConsole.write` · [source](contracts.aug#L10)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It prints `value`.
+
+<a id="symbol-FileReader"></a>
+## `FileReader` · capability interface · [source](contracts.aug#L14)
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+### `FileReader.read` · [source](contracts.aug#L16)
+
+Read text. It takes `path` as a string (File path).
+
+It returns `string`. It can call [`FileReader.read`](contracts.aug.md#symbol-FileReader.read). Failures can raise `FileError` (The file could not be read).
+
+<a id="symbol-FileWriter"></a>
+## `FileWriter` · capability interface · [source](contracts.aug#L19)
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+### `FileWriter.write` · [source](contracts.aug#L21)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). It can call [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write). Failures can raise `FileError` (Writing failed).
+
+<a id="symbol-LocalFiles"></a>
+## `LocalFiles` · class · [source](contracts.aug#L24)
+
+Native files. Operations are explicit; construction opens no files. It implements [`FileReader`](contracts.aug.md#symbol-FileReader) and [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+<a id="symbol-LocalFiles.read"></a>
+### `LocalFiles.read` · [source](contracts.aug#L25)
+
+Read text. It takes `path` as a string (File path). Failures can raise `FileError` (The file could not be read). It returns `read_file` with `path`.
+
+<a id="symbol-LocalFiles.write"></a>
+### `LocalFiles.write` · [source](contracts.aug#L27)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). Failures can raise `FileError` (Writing failed). It calls `write_file` with `path` and `content`.
+
+<a id="symbol-Arguments"></a>
+## `Arguments` · capability interface · [source](contracts.aug#L31)
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+### `Arguments.read` · [source](contracts.aug#L32)
+
+It returns `List<string>`. It can call [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+<a id="symbol-ProcessArguments"></a>
+## `ProcessArguments` · class · [source](contracts.aug#L35)
+
+Native command-line arguments. It implements [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+<a id="symbol-ProcessArguments.read"></a>
+### `ProcessArguments.read` · [source](contracts.aug#L36)
+
+It returns `arguments`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).