@greenpandastudios/aug-cli 0.19.0

package/examples/oidc-login/.aug-spec/august/0.19.0/memory/store.aug.md

@@ -0,0 +1,250 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `store.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`StoreFull`](store.aug.md#symbol-StoreFull) is a class implementing `Error`.
+- [`_Entry`](store.aug.md#symbol-_Entry) is an immutable record.
+- [`ExpiringStore`](store.aug.md#symbol-ExpiringStore) is a capability interface.
+- [`MemoryStore`](store.aug.md#symbol-MemoryStore) is a class implementing `ExpiringStore<T>`.
+
+<a id="symbol-StoreFull"></a>
+
+## `StoreFull`
+
+[source](store.aug#L3)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+**Author documentation**
+
+The bounded store could not accept another live entry.
+
+<a id="symbol-ExpiringStore"></a>
+
+## `ExpiringStore`
+
+[source](store.aug#L8)
+
+Capability interface.
+
+Type parameters: `T` must satisfy `Data`.
+
+**Author documentation**
+
+A bounded, expiring capability for immutable values. Each generic DI binding has its own table.
+
+<a id="symbol-ExpiringStore.put"></a>
+
+### `ExpiringStore.put`
+
+[source](store.aug#L10)
+
+**Inputs**
+
+- `key` (`string`) — required labeled input.
+- `value` (`T`) — required labeled input.
+- `expires` (`int`) — required labeled input.
+- `now` (`int`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`ExpiringStore.put`](store.aug.md#symbol-ExpiringStore.put).
+
+Can fail with `StoreFull`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Remove expired entries, then store at most 512 live entries. Time is supplied by the caller.
+
+<a id="symbol-ExpiringStore.take"></a>
+
+### `ExpiringStore.take`
+
+[source](store.aug#L12)
+
+**Inputs**
+
+- `key` (`string`) — required labeled input.
+- `now` (`int`) — required labeled input.
+
+Returns: `optional T`.
+
+Capabilities: [`ExpiringStore.take`](store.aug.md#symbol-ExpiringStore.take).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Atomically remove a value. Expired or absent entries return null.
+
+<a id="symbol-ExpiringStore.get"></a>
+
+### `ExpiringStore.get`
+
+[source](store.aug#L14)
+
+**Inputs**
+
+- `key` (`string`) — required labeled input.
+- `now` (`int`) — required labeled input.
+
+Returns: `optional T`.
+
+Capabilities: [`ExpiringStore.get`](store.aug.md#symbol-ExpiringStore.get).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Read a live value without consuming it.
+
+<a id="symbol-MemoryStore"></a>
+
+## `MemoryStore`
+
+[source](store.aug#L17)
+
+Behavioral class.
+
+Type parameters: `T` must satisfy `Data`.
+
+Satisfies [`ExpiringStore`](store.aug.md#symbol-ExpiringStore).
+
+**Author documentation**
+
+A synchronized table with short critical sections and no I/O while locked.
+
+**Field initialization**
+
+- Initialize `_entries` of type `Shared<Map<string,_Entry<T>>>` to call `Shared` with `value` = an empty map from `string` to [`_Entry<T>`](store.aug.md#symbol-_Entry). Read-only storage, private to this class.
+
+<a id="symbol-MemoryStore.put"></a>
+
+### `MemoryStore.put`
+
+[source](store.aug#L19)
+
+**Inputs**
+
+- `key` (`string`) — required labeled input.
+- `value` (`T`) — required labeled input.
+- `expires` (`int`) — required labeled input.
+- `now` (`int`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`ExpiringStore<T>.put`](store.aug.md#symbol-ExpiringStore.put).
+
+Can fail with `StoreFull`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Set `entry` to call [`_Entry`](store.aug.md#symbol-_Entry) with type arguments `T` with `value` = `value`; `expires` = `expires`.
+- Lock `_entries`, expose its mutable value as `entries`, and release the lock on every exit:
+  - For each `name` and `saved` in a snapshot of `entries`, in iteration order:
+    - If `expires` of `saved` is at most `now`:
+      - Call `take` on `entries` with `key` = `name`.
+  - If (call `length` on `entries` is at least `512`) and not (call `contains` on `entries` with `key` = `key`):
+    - Fail with call [`StoreFull`](store.aug.md#symbol-StoreFull). Transfer control to a matching catch or propagate the failure.
+  - Call `set` on `entries` with `key` = `key`; `value` = `entry`.
+
+**Author documentation**
+
+Remove expired entries, then store at most 512 live entries. Time is supplied by the caller.
+
+<a id="symbol-MemoryStore.take"></a>
+
+### `MemoryStore.take`
+
+[source](store.aug#L28)
+
+**Inputs**
+
+- `key` (`string`) — required labeled input.
+- `now` (`int`) — required labeled input.
+
+Returns: `optional T`.
+
+Capabilities: [`ExpiringStore<T>.take`](store.aug.md#symbol-ExpiringStore.take).
+
+**What it does**
+
+- Lock `_entries`, expose its mutable value as `entries`, and release the lock on every exit:
+  - Select the matching case for call `take` on `entries` with `key` = `key`:
+    - A null value, including omitted optional input:
+      - Return null.
+    - A present, non-null value, named `saved`:
+      - If `expires` of `saved` is at most `now`:
+        - Return null.
+      - Return `value` of `saved`.
+
+**Author documentation**
+
+Atomically remove a value. Expired or absent entries return null.
+
+<a id="symbol-MemoryStore.get"></a>
+
+### `MemoryStore.get`
+
+[source](store.aug#L37)
+
+**Inputs**
+
+- `key` (`string`) — required labeled input.
+- `now` (`int`) — required labeled input.
+
+Returns: `optional T`.
+
+Capabilities: [`ExpiringStore<T>.get`](store.aug.md#symbol-ExpiringStore.get).
+
+**What it does**
+
+- Lock `_entries`, expose its mutable value as `entries`, and release the lock on every exit:
+  - Select the matching case for call `get` on `entries` with `key` = `key`:
+    - A null value, including omitted optional input:
+      - Return null.
+    - A present, non-null value, named `saved`:
+      - If `expires` of `saved` is at most `now`:
+        - Return null.
+      - Return `value` of `saved`.
+
+**Author documentation**
+
+Read a live value without consuming it.
+
+<a id="symbol-_Entry"></a>
+
+## `_Entry`
+
+[source](store.aug#L5)
+
+Immutable record, private to this file.
+
+Type parameters: `T` must satisfy `Data`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input — stored as `value` and read-only after initialization.
+- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+
+## Built-in operations used by this file
+
+- `Map<string, _Entry<T>>.contains` (`key`: `string`) → `bool`: Check for a key, including entries whose value is null.
+- `Map<string, _Entry<T>>.get` (`key`: `string`) → `optional _Entry<T>`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
+- `Map<string, _Entry<T>>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<string, _Entry<T>>.set` (`key`: `string`, `value`: `_Entry<T>`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
+- `Map<string, _Entry<T>>.take` (`key`: `string`) → `optional _Entry<T>`: Remove and return an entry under exclusive access. An absent key returns null. Changes the receiver.
+
+[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/oidc-login/.aug-spec/august/0.19.0/time/contracts.aug

@@ -0,0 +1,11 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+/** An explicit clock dependency makes time-based behavior replaceable in tests. */
+capability Clock:
+    /** Read whole Unix seconds in UTC. */
+    now() returns int uses Clock.now unless TimeError
+extern C value _aug_time_now() returns int uses Clock.now unless TimeError
+/** Operating-system wall clock. */
+SystemClock() implements Clock:
+    now() returns int unless TimeError:
+        unsafe:
+            return _aug_time_now()

package/examples/oidc-login/.aug-spec/august/0.19.0/time/contracts.aug.md

@@ -0,0 +1,96 @@
+<!-- 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
+
+- [`Clock`](contracts.aug.md#symbol-Clock) is a capability interface.
+- [`_aug_time_now`](contracts.aug.md#symbol-_aug_time_now) is a function returning `int`.
+- [`SystemClock`](contracts.aug.md#symbol-SystemClock) is a class implementing `Clock`.
+
+<a id="symbol-Clock"></a>
+
+## `Clock`
+
+[source](contracts.aug#L3)
+
+Capability interface.
+
+**Author documentation**
+
+An explicit clock dependency makes time-based behavior replaceable in tests.
+
+<a id="symbol-Clock.now"></a>
+
+### `Clock.now`
+
+[source](contracts.aug#L5)
+
+Returns: `int`.
+
+Capabilities: [`Clock.now`](contracts.aug.md#symbol-Clock.now).
+
+Can fail with `TimeError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Read whole Unix seconds in UTC.
+
+<a id="symbol-SystemClock"></a>
+
+## `SystemClock`
+
+[source](contracts.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Clock`](contracts.aug.md#symbol-Clock).
+
+**Author documentation**
+
+Operating-system wall clock.
+
+<a id="symbol-SystemClock.now"></a>
+
+### `SystemClock.now`
+
+[source](contracts.aug#L9)
+
+Returns: `int`.
+
+Capabilities: [`Clock.now`](contracts.aug.md#symbol-Clock.now).
+
+Can fail with `TimeError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Return call [`_aug_time_now`](contracts.aug.md#symbol-_aug_time_now).
+
+**Author documentation**
+
+Read whole Unix seconds in UTC.
+
+<a id="symbol-_aug_time_now"></a>
+
+## `_aug_time_now`
+
+[source](contracts.aug#L6)
+
+Private to its defining scope.
+
+Returns: `int`.
+
+Capabilities: [`Clock.now`](contracts.aug.md#symbol-Clock.now).
+
+Can fail with `TimeError`. Callers must catch or propagate these errors.
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/oidc-login/.aug-spec/august/0.19.0/web/contracts.aug

@@ -0,0 +1,58 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+/** Immutable identity returned by an explicitly injected authentication adapter. */
+record Principal(string subject, List<string> permissions)
+
+/** Verify the request's credentials. null means unauthenticated; adapter failures raise HttpError. */
+capability Authentication:
+    authenticate(HttpRequest request) returns optional Principal uses Authentication.authenticate unless HttpError
+
+/** Decide whether a verified identity has one named permission. */
+capability Authorization:
+    authorize(Principal identity, string permission) returns bool uses Authorization.authorize unless HttpError
+
+/** Observe a completed HTTP exchange, including failures and disconnects. */
+capability RequestLogger:
+    complete(string method, string path, int status, int milliseconds) uses RequestLogger.complete
+
+extern C value _aug_http_log(string method, string path, int status, int milliseconds) uses RequestLogger.complete
+/** Emit escaped JSON request metadata to standard error. Credentials and query strings are excluded. */
+WebRequestLogger() implements RequestLogger:
+    complete(string method, string path, int status, int milliseconds):
+        unsafe:
+            _aug_http_log(method, path, status, milliseconds)
+
+/** An explicit outbound network capability. TLS verifies the peer and redirects are returned to the caller. */
+capability HttpClient:
+    /** Perform an HTTP request with bounded bytes. Inside a task, waiting suspends the task's C stack. */
+    request(string method, string url, optional Headers headers, optional Bytes body) returns HttpResponse<Bytes> uses HttpClient.request unless HttpError
+
+extern C value _aug_http_request(string method, string url, optional Headers headers, optional Bytes body) returns HttpResponse<Bytes> uses HttpClient.request unless HttpError
+
+/** Native libwebsockets transport. No socket is opened by construction. */
+WebHttpClient() implements HttpClient:
+    request(string method, string url, optional Headers headers, optional Bytes body) returns HttpResponse<Bytes> unless HttpError:
+        unsafe:
+            return _aug_http_request(method=method, url=url, headers=headers, body=body)
+
+/** Return a redirect with an explicit status. Location is checked as a header value. */
+redirect(string location, optional int status) returns HttpResponse<string> unless HttpError:
+    code = 303
+    match status:
+        when null:
+            pass
+        when some value:
+            code = value
+    headers = Headers().with(name="location", value=location)
+    return HttpResponse(body="", status=code, headers=headers)
+
+extern C value pure _aug_http_url_encode(string input) returns string unless HttpError
+/** Encode a UTF-8 value as one URL query or form component using RFC 3986 unreserved characters. */
+urlEncode(string input) returns string unless HttpError:
+    unsafe:
+        return _aug_http_url_encode(input)
+
+extern C value pure _aug_http_cookie(string name, string value, string path, int maxAge, bool secure) returns Headers unless HttpError
+/** Construct an HttpOnly, SameSite=Lax session cookie. Secure defaults are chosen explicitly at the call site. Values and paths reject delimiters and controls. maxAge=0 clears the cookie. */
+cookie(string name, string value, string path, int maxAge, bool secure) returns Headers unless HttpError:
+    unsafe:
+        return _aug_http_cookie(name, value, path, maxAge, secure)