@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/docs/examples/native-sqlite/dependencies/packages/@greenpandastudios/aug-sqlite/0.1.3/bindings.md

@@ -0,0 +1,51 @@
+---
+title: "packages/@greenpandastudios/aug-sqlite/0.1.3/bindings.aug · A database with SQLite"
+generated: true
+source: "examples/native-sqlite/.aug-spec/packages/@greenpandastudios/aug-sqlite/0.1.3/bindings.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-sqlite/0.1.3/bindings.aug`
+
+[A database with SQLite](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "bindings.aug.md" explains this file. Read it before changes; refresh with aug spec.
+extern C resource Database
+```
+
+```aug [Braces]
+// aug-spec: "bindings.aug.md" explains this file. Read it before changes; refresh with aug spec.
+extern C resource Database
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `Database` · native resource · [source](bindings.md#code) {#symbol-Database}
+
+Native implementation: `@greenpandastudios/aug-sqlite@0.1.3`, `3.53.4`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi-json.md) (SHA-256 `3c75c2925c85f1b83db06ee00fa04f1d2d37c9fd6edca0d074ce89b4647ffffb`). An owned value releases its opaque handle through `aug_sqlite_release_v1` when its scope ends, including error and return paths.
+
+::::
+
+:::::

package/docs/examples/native-sqlite/dependencies/packages/@greenpandastudios/aug-sqlite/0.1.3/contracts.md

@@ -0,0 +1,75 @@
+---
+title: "packages/@greenpandastudios/aug-sqlite/0.1.3/contracts.aug · A database with SQLite"
+generated: true
+source: "examples/native-sqlite/.aug-spec/packages/@greenpandastudios/aug-sqlite/0.1.3/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-sqlite/0.1.3/contracts.aug`
+
+[A database with SQLite](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Database from bindings
+SqliteError(int code, string message) implements Error:
+    pass
+/** Permission to open database files. Select the native adapter in main.aug. */
+capability DatabaseStorage:
+    open(string path) returns own Database uses DatabaseStorage.open unless SqliteError
+```
+
+```aug [Braces]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Database from bindings
+SqliteError(int code, string message) implements Error {
+    pass
+}
+/** Permission to open database files. Select the native adapter in main.aug. */
+capability DatabaseStorage {
+    open(string path) returns own Database uses DatabaseStorage.open unless SqliteError
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `SqliteError` · class · [source](contracts.md#code) {#symbol-SqliteError}
+
+It implements `Error`. It takes `code` as an integer, kept read-only and `message` as a string, kept read-only.
+
+### `DatabaseStorage` · capability interface · [source](contracts.md#code) {#symbol-DatabaseStorage}
+
+Permission to open database files. Select the native adapter in main.aug.
+
+#### `DatabaseStorage.open` · [source](contracts.md#code) {#symbol-DatabaseStorage.open}
+
+It takes `path` as a string. It returns ownership of [`Database`](bindings.md#symbol-Database). It can call [`DatabaseStorage.open`](contracts.md#symbol-DatabaseStorage.open). Failures can raise [`SqliteError`](contracts.md#symbol-SqliteError).
+
+### Dependencies
+
+It uses [`Database`](bindings.md#symbol-Database) from `bindings`.
+
+::::
+
+:::::

package/docs/examples/native-sqlite/dependencies/packages/@greenpandastudios/aug-sqlite/0.1.3/native.abi-json.md

@@ -0,0 +1,119 @@
+---
+title: "Native binding contract · A database with SQLite"
+generated: true
+source: "examples/native-sqlite/.aug-spec/packages/@greenpandastudios/aug-sqlite/0.1.3/native.abi.json"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+---
+
+# Native binding contract
+
+[A database with SQLite](../../../../../index.md)
+
+This is the exact descriptor checked for this dependency. It records native symbols, ownership, errors, and ABI boundaries. The compiler checks August declarations against it; foreign implementations remain the native author’s responsibility.
+
+```json
+{
+  "format": 1,
+  "profile": "aug-native-abi-1",
+  "resources": [
+    {
+      "module": "bindings",
+      "name": "Database",
+      "release": "aug_sqlite_release_v1"
+    }
+  ],
+  "functions": [
+    {
+      "module": "api",
+      "name": "_open",
+      "symbol": "aug_sqlite_open_v1",
+      "params": [
+        {
+          "name": "path",
+          "kind": "utf8"
+        }
+      ],
+      "result": {
+        "kind": "resource",
+        "resource": "bindings.Database"
+      },
+      "error": "contracts.SqliteError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    },
+    {
+      "module": "api",
+      "name": "_execute",
+      "symbol": "aug_sqlite_execute_v1",
+      "params": [
+        {
+          "name": "database",
+          "kind": "resource",
+          "resource": "bindings.Database",
+          "ownership": "borrow"
+        },
+        {
+          "name": "sql",
+          "kind": "utf8"
+        },
+        {
+          "name": "parameters",
+          "kind": "utf8-list"
+        }
+      ],
+      "result": {
+        "kind": "i64"
+      },
+      "error": "contracts.SqliteError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [
+        "database"
+      ],
+      "thread": "caller",
+      "retainsInputs": false
+    },
+    {
+      "module": "api",
+      "name": "_queryScalar",
+      "symbol": "aug_sqlite_scalar_v1",
+      "params": [
+        {
+          "name": "database",
+          "kind": "resource",
+          "resource": "bindings.Database",
+          "ownership": "read"
+        },
+        {
+          "name": "sql",
+          "kind": "utf8"
+        },
+        {
+          "name": "parameters",
+          "kind": "utf8-list"
+        }
+      ],
+      "result": {
+        "kind": "utf8",
+        "release": "aug_sqlite_text_release_v1"
+      },
+      "error": "contracts.SqliteError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    }
+  ]
+}
+```

package/docs/examples/native-sqlite/index.md

@@ -0,0 +1,38 @@
+---
+title: "A database with SQLite"
+generated: true
+source: "examples/native-sqlite"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# A database with SQLite
+
+Create an in-memory database, insert a labeled bound value, and query it through the real SQLite implementation. Mutation requires a borrow; scope exit closes the database.
+
+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.
+
+This project requires the August `0.21.0` LLVM preview on macOS 14+ with Apple Silicon, or Debian/Ubuntu GNU/Linux x64 or ARM64 with glibc 2.36+. The library archives are public; the matching compiler release is still being qualified.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`database.aug`](database.md)
+
+
+## Try this project
+
+[Download this project](/downloads/native-sqlite.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 native-sqlite
+aug install .
+aug check .
+aug spec .
+aug test .
+aug run .
+```
+
+[Browse all examples](../index.md)

package/docs/examples/native-sqlite/main.md

@@ -0,0 +1,73 @@
+---
+title: "main.aug · A database with SQLite"
+generated: true
+source: "examples/native-sqlite/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[A database with SQLite](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`database.aug`](database.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 storedName from database
+import SqliteError from "https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3"
+try:
+    print(value=storedName())
+catch SqliteError error:
+    print(value=error.message)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import storedName from database
+import SqliteError from "https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3"
+try {
+    print(value=storedName())
+}
+catch SqliteError error {
+    print(value=error.message)
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It prints [`storedName`](database.md#symbol-storedName). If this work raises [`SqliteError`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/contracts.md#symbol-SqliteError) as `error`, it prints `error.message`.
+
+### Dependencies
+
+It uses [`SqliteError`](dependencies/packages/%40greenpandastudios/aug-sqlite/0.1.3/contracts.md#symbol-SqliteError) (`message`) from `https://github.com/GreenPandaStudios/aug-sqlite#v0.1.3`. It uses [`storedName`](database.md#symbol-storedName) from `database`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

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

@@ -0,0 +1,99 @@
+---
+title: "compression.aug · Compression with zlib"
+generated: true
+source: "examples/native-zlib/compression.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `compression.aug`
+
+[Compression with zlib](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`compression.aug`](compression.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// 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)
+```
+
+```aug [Braces]
+// 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)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `roundTrip` · [source](compression.md#code) {#symbol-roundTrip}
+
+Compress text with zlib, then restore its bytes within a fixed output limit. Failures can raise [`CompressionError`](dependencies/packages/%40greenpandastudios/aug-zlib/0.1.3/contracts.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`](dependencies/packages/%40greenpandastudios/aug-zlib/0.1.3/api.md#symbol-compress) with `input`. It returns [`decompress`](dependencies/packages/%40greenpandastudios/aug-zlib/0.1.3/api.md#symbol-decompress) with `input` from `compressed` and `maximumOutput` `4096`.
+
+### `test roundTrip` · [source](compression.md#code) {#symbol-test-20-roundTrip}
+
+Tests [`roundTrip`](compression.md#symbol-roundTrip). Each case gets fresh setup and dependencies.
+
+#### `compression`
+
+##### `preserves_the_original_bytes` · [source](compression.md#code)
+
+It gets `restored` of type `Bytes` from [`roundTrip`](compression.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`](dependencies/packages/%40greenpandastudios/aug-zlib/0.1.3/api.md#symbol-compress), [`decompress`](dependencies/packages/%40greenpandastudios/aug-zlib/0.1.3/api.md#symbol-decompress), and [`CompressionError`](dependencies/packages/%40greenpandastudios/aug-zlib/0.1.3/contracts.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/docs/examples/native-zlib/dependencies/packages/@greenpandastudios/aug-zlib/0.1.3/api.md

@@ -0,0 +1,153 @@
+---
+title: "packages/@greenpandastudios/aug-zlib/0.1.3/api.aug · Compression with zlib"
+generated: true
+source: "examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/api.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-zlib/0.1.3/api.aug`
+
+[Compression with zlib](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// 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)
+```
+
+```aug [Braces]
+// 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)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `compress` · [source](api.md#code) {#symbol-compress}
+
+Compress bytes with the standard zlib framing. It takes `input` as `Bytes`. Failures can raise [`CompressionError`](contracts.md#symbol-CompressionError).
+
+Within an unsafe block, it returns [`_compress`](api.md#symbol-_compress) with `input`. Native operations must satisfy their declared C contracts.
+
+### `decompress` · [source](api.md#code) {#symbol-decompress}
+
+Decompress at most maximumOutput bytes (maximum 256 MiB). It takes `input` as `Bytes` and `maximumOutput` as an integer. Failures can raise [`CompressionError`](contracts.md#symbol-CompressionError).
+
+Within an unsafe block, it returns [`_decompress`](api.md#symbol-_decompress) with `input` and `maximumOutput`. Native operations must satisfy their declared C contracts.
+
+### `_compress` · [source](api.md#code) {#symbol-_compress}
+
+It is private to its defining scope. It takes `input` as `Bytes`. It returns `Bytes`. Failures can raise [`CompressionError`](contracts.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.md) (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.
+
+### `_decompress` · [source](api.md#code) {#symbol-_decompress}
+
+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.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.md) (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.
+
+### `test compress` · [source](api.md#code) {#symbol-test-20-compress}
+
+Tests [`compress`](api.md#symbol-compress). Each case gets fresh setup and dependencies.
+
+#### `compression`
+
+##### `preserves_bytes` · [source](api.md#code)
+
+It sets `input` of type `Bytes` to `bytes` on `"The world runs on language"`. It sets `packed` of type `Bytes` to [`compress`](api.md#symbol-compress) with `input`. It sets `restored` of type `Bytes` to [`decompress`](api.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.md#code)
+
+It sets `packed` of type `Bytes` to [`compress`](api.md#symbol-compress) with `input` from `bytes` on `"length limit"`. It sets `rejected` to `false`.
+
+It tries to call [`decompress`](api.md#symbol-decompress) with `input` from `packed` and `maximumOutput` `1`. If this work raises [`CompressionError`](contracts.md#symbol-CompressionError), it sets `rejected` to `true`. The test requires `rejected` is true.
+
+### Dependencies
+
+It uses [`CompressionError`](contracts.md#symbol-CompressionError) from `contracts`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

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

@@ -0,0 +1,54 @@
+---
+title: "packages/@greenpandastudios/aug-zlib/0.1.3/contracts.aug · Compression with zlib"
+generated: true
+source: "examples/native-zlib/.aug-spec/packages/@greenpandastudios/aug-zlib/0.1.3/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-zlib/0.1.3/contracts.aug`
+
+[Compression with zlib](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+CompressionError(int code, string message) implements Error:
+    pass
+```
+
+```aug [Braces]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+CompressionError(int code, string message) implements Error {
+    pass
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `CompressionError` · class · [source](contracts.md#code) {#symbol-CompressionError}
+
+It implements `Error`. It takes `code` as an integer, kept read-only and `message` as a string, kept read-only.
+
+::::
+
+:::::