@greenpandastudios/aug-cli 0.19.0

package/examples/oidc-login/provider/views.aug.md

@@ -0,0 +1,63 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `views.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`ProviderLogin`](views.aug.md#symbol-ProviderLogin) is a function returning `Html`.
+- [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) is a function returning `Html`.
+
+<a id="symbol-ProviderLogin"></a>
+
+## `ProviderLogin`
+
+[source](views.aug#L3)
+
+**Inputs**
+
+- `requestId` (`string`) — required labeled input.
+- `csrf` (`string`) — required labeled input.
+- `message` (`string`) — required labeled input.
+- `submit` (`HttpAction`) — required labeled input.
+
+Returns: `Html`.
+
+**What it does**
+
+- Return the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign in with the August provider"` containing the HTML element `p` containing `message` (rendered on the server with embedded text escaped), the HTML element `p` with `style` = `"background:#f3f5f9;padding:12px;border-radius:8px"` containing `Demo account: `, the HTML element `strong` containing `ada` (rendered on the server with embedded text escaped), ` · password `, the HTML element `strong` containing `august-demo` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `form` with `method` = `"post"`, `action` = `"/provider/login"`, `onSubmit` = `submit` containing the HTML element `input` with `type` = `"hidden"`, `name` = `"request_id"`, `value` = `requestId` (rendered on the server with embedded text escaped), the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `csrf` (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `label` with `for` = `"username"` containing `Username` (rendered on the server with embedded text escaped), the HTML element `br` (rendered on the server with embedded text escaped), the HTML element `input` with `id` = `"username"`, `name` = `"username"`, `autocomplete` = `"username"`, `value` = `"ada"`, `maxlength` = `"64"`, `required` = `true`, `style` = `"padding:10px;width:90%"` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `label` with `for` = `"password"` containing `Password` (rendered on the server with embedded text escaped), the HTML element `br` (rendered on the server with embedded text escaped), the HTML element `input` with `id` = `"password"`, `type` = `"password"`, `name` = `"password"`, `autocomplete` = `"current-password"`, `maxlength` = `"256"`, `required` = `true`, `style` = `"padding:10px;width:90%"` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `button` with `type` = `"submit"`, `style` = `"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"` containing `Sign in and return to the app` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` with `style` = `"font-size:14px;color:#677189"` containing `The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
+
+**Author documentation**
+
+A server form with a checked HTTP action. The browser submits to the provider endpoint.
+
+<a id="symbol-ProviderFailure"></a>
+
+## `ProviderFailure`
+
+[source](views.aug#L17)
+
+**Inputs**
+
+- `message` (`string`) — required labeled input.
+
+Returns: `Html`.
+
+**What it does**
+
+- Return the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign-in could not continue"` containing the HTML element `p` containing `message` (rendered on the server with embedded text escaped), the HTML element `a` with `href` = `"/login/start"` containing `Start a new sign-in` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`Page`](../common/views.aug.md#symbol-Page)
+
+Function from `common`.
+
+- [`Page`](../common/views.aug.md#symbol-Page) (`title`: `string`, `children`: `List<Html>`) → `Html`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,8 @@
+{
+  "format": 1,
+  "files": [
+    "counter.aug.md",
+    "main.aug.md"
+  ],
+  "digest": "963a9ed380d8c2dcd5cb2f8545a9ace3770b304d6bb172d08a25283afc8b72a7"
+}

package/examples/ownership/counter.aug

@@ -0,0 +1,14 @@
+Counter(mutable int value) implements ICounter {
+    increment() changes self {
+        borrow self {
+            value = value + 1
+        }
+    }
+    read() returns int {
+        return value
+    }
+}
+interface ICounter {
+    increment() changes self
+    read() returns int
+}

package/examples/ownership/counter.aug.md

@@ -0,0 +1,85 @@
+<!-- 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
+
+- [`Counter`](counter.aug.md#symbol-Counter) is a class implementing `ICounter`.
+- [`ICounter`](counter.aug.md#symbol-ICounter) is an interface.
+
+<a id="symbol-Counter"></a>
+
+## `Counter`
+
+[source](counter.aug#L1)
+
+Behavioral class.
+
+Satisfies [`ICounter`](counter.aug.md#symbol-ICounter).
+
+**Inputs**
+
+- `value` (`int`) — required labeled input — stored as `value` and mutable.
+
+<a id="symbol-Counter.increment"></a>
+
+### `Counter.increment`
+
+[source](counter.aug#L2)
+
+Returns: no value.
+
+May change: `self`.
+
+**What it does**
+
+- Grant exclusive mutable access to `self` for this block, then end the borrow:
+  - Set `value` to `value` plus `1`.
+
+<a id="symbol-Counter.read"></a>
+
+### `Counter.read`
+
+[source](counter.aug#L7)
+
+Returns: `int`.
+
+**What it does**
+
+- Return `value`.
+
+<a id="symbol-ICounter"></a>
+
+## `ICounter`
+
+[source](counter.aug#L11)
+
+Interface.
+
+<a id="symbol-ICounter.increment"></a>
+
+### `ICounter.increment`
+
+[source](counter.aug#L12)
+
+Returns: no value.
+
+May change: `self`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-ICounter.read"></a>
+
+### `ICounter.read`
+
+[source](counter.aug#L13)
+
+Returns: `int`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/ownership/main.aug

@@ -0,0 +1,4 @@
+import Counter from counter
+own Counter counter = Counter(value=1)
+counter.increment()
+print(value=counter.read())

package/examples/ownership/main.aug.md

@@ -0,0 +1,38 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Run 3 other startup steps in source order.
+
+## Startup, in source order
+
+- Set `counter` of type [`Counter`](counter.aug.md#symbol-Counter) to call [`Counter`](counter.aug.md#symbol-Counter) with `value` = `1`.
+- This variable owns the value.
+- Call [`Counter.increment`](counter.aug.md#symbol-Counter.increment) on `counter`.
+- Call `print` with `value` = call [`Counter.read`](counter.aug.md#symbol-Counter.read) on `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).
+- [`Counter.increment`](counter.aug.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
+- [`Counter.read`](counter.aug.md#symbol-Counter.read) (no caller inputs) → `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.

package/examples/ownership-transfer/.aug-spec/august/0.19.0/io/contracts.aug

@@ -0,0 +1,36 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+/** 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) returns string unless FileError:
+        return read_file(path=path)
+    write(string path, string content) unless FileError:
+        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() returns List<string>:
+        return arguments()

package/examples/ownership-transfer/.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/ownership-transfer/.aug-spec/manifest.json

@@ -0,0 +1,10 @@
+{
+  "format": 1,
+  "files": [
+    ".aug-spec/august/0.19.0/io/contracts.aug",
+    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    "main.aug.md",
+    "resource.aug.md"
+  ],
+  "digest": "0647bd67edecc9f86adc5dfccefbfac3fb6aa5d23e2e010c4bb4e657d37bb259"
+}

package/examples/ownership-transfer/main.aug

@@ -0,0 +1,9 @@
+import Console and SystemConsole from august.io
+implement Console with SystemConsole
+import Resource from resource
+import make from resource
+import consume from resource
+own Resource first = make()
+consume(value=first)
+own Resource second = make()
+print(value="end of main")

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

@@ -0,0 +1,63 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Register 1 dependency provider before startup.
+- Run 4 other startup steps in source order.
+
+## Dependency providers
+
+Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+
+- Provide [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+
+## Startup, in source order
+
+- Set `first` of type [`Resource`](resource.aug.md#symbol-Resource) to call [`make`](resource.aug.md#symbol-make).
+- This variable owns the value.
+- Call [`consume`](resource.aug.md#symbol-consume) with `value` = `first`; inject `console` from `Console`.
+- Set `second` of type [`Resource`](resource.aug.md#symbol-Resource) to call [`make`](resource.aug.md#symbol-make).
+- This variable owns the value.
+- Call `print` with `value` = `"end of main"`.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+### [`Resource`](resource.aug.md#symbol-Resource)
+
+Class from `resource`.
+
+Used as a type or provider.
+
+### [`consume`](resource.aug.md#symbol-consume)
+
+Function from `resource`.
+
+- [`consume`](resource.aug.md#symbol-consume) (`value`: [`Resource`](resource.aug.md#symbol-Resource)) → `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).
+
+### [`make`](resource.aug.md#symbol-make)
+
+Function from `resource`.
+
+- [`make`](resource.aug.md#symbol-make) (no caller inputs) → [`Resource`](resource.aug.md#symbol-Resource).
+
+## 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.

package/examples/ownership-transfer/resource.aug

@@ -0,0 +1,16 @@
+import Console from august.io
+Resource() implements IResource {
+    drop() {
+        pass
+    }
+}
+interface IResource {
+    pass
+}
+make() returns own Resource {
+    own Resource value = Resource()
+    return value
+}
+consume(resolve Console console, own Resource value) uses Console.write {
+    console.write(value="consumed")
+}