@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/files.md

@@ -0,0 +1,117 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / files
+
+# files
+
+## Type Aliases
+
+### FileEntry
+
+```ts
+type FileEntry = Readonly<{
+  name: string;
+  type: "file" | "directory" | "symlink";
+  size: number;
+  modifiedAt: number;
+}>;
+```
+
+One entry of a directory listing, in Agar's `computer.list` contract.
+
+---
+
+### FileListing
+
+```ts
+type FileListing = Readonly<{
+  path: string;
+  entries: readonly FileEntry[];
+  nextOffset: number | null;
+}>;
+```
+
+A page of a directory, in Agar's `computer.list` contract.
+
+---
+
+### FileReplaceOutcome
+
+```ts
+type FileReplaceOutcome =
+  | Readonly<{
+      kind: "replaced";
+      path: string;
+      bytes: number;
+    }>
+  | Readonly<{
+      kind: "conflict";
+    }>;
+```
+
+What a conditional replace did, in Agar's `computer.writeFile` contract.
+
+---
+
+### FileSource
+
+```ts
+type FileSource = Readonly<{
+  list: Promise<Readonly<{
+    path: string;
+    entries: readonly FileEntry[];
+    nextOffset: number | null;
+  }> | null>;
+  read: Promise<Uint8Array<ArrayBufferLike> | null>;
+  write: Promise<void>;
+  mkdir: Promise<void>;
+  replace: Promise<FileReplaceOutcome>;
+}>;
+```
+
+Where an Oyster's files live. Paths are absolute (`/notes/a.md`) and already
+normalized by the routes; a source never sees `..`.
+
+## Functions
+
+### normalizeFilePath()
+
+```ts
+function normalizeFilePath(raw): string | null;
+```
+
+Normalize an absolute path; `null` when it is not one or escapes the root.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `raw`     | `string` |
+
+#### Returns
+
+`string` \| `null`
+
+---
+
+### fileCapabilities()
+
+```ts
+function fileCapabilities(source): readonly Readonly<object & object>[];
+```
+
+File capabilities sharing the existing `/files/` wire and one file source.
+
+#### Parameters
+
+| Parameter | Type                        |
+| --------- | --------------------------- |
+| `source`  | [`FileSource`](#filesource) |
+
+#### Returns
+
+readonly `Readonly`\<`object` & `object`\>[]

package/docs/api/git.md

@@ -0,0 +1,470 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / git
+
+# git
+
+## Type Aliases
+
+### GitStore
+
+```ts
+type GitStore = GitBinding;
+```
+
+Installation-scoped storage; transport and credentials stay with its provider
+adapter.
+
+---
+
+### GitGrants
+
+```ts
+type GitGrants = Readonly<{
+  admits: Promise<boolean>;
+}>;
+```
+
+Live host authority, reopened before every provider call. Null is an anonymous
+reader.
+
+---
+
+### GitPolicy
+
+```ts
+type GitPolicy = Readonly<{
+  authorize: Promise<
+    | {
+        allowed: z.ZodLiteral<true>;
+      }
+    | {
+        allowed: z.ZodLiteral<false>;
+        refused: z.ZodArray<
+          z.ZodObject<
+            {
+              ref: z.ZodString;
+              message: z.ZodString;
+            },
+            z.core.$strict
+          >
+        >;
+      }
+  >;
+}>;
+```
+
+Repository rules owned by the selected App; a missing or malformed answer
+refuses.
+
+---
+
+### GitJournal
+
+```ts
+type GitJournal = Readonly<{
+  tip: Promise<string | null>;
+  record: Promise<void>;
+}>;
+```
+
+Durable accepted-ref journal; record commits before the provider result is
+acknowledged.
+
+---
+
+### AdmittedGit
+
+```ts
+type AdmittedGit = Readonly<{
+  push: Promise<
+    Readonly<{
+      status: number;
+      headers: Readonly<Record<string, string>>;
+      body: Uint8Array;
+    }>
+  >;
+  read: Promise<
+    Readonly<{
+      status: number;
+      headers: Readonly<Record<string, string>>;
+      body: Uint8Array;
+    }>
+  >;
+  binding: GitBinding;
+}>;
+```
+
+Host-held read/write path; Apps receive only its installation-authored binding.
+
+---
+
+### GitDoorTarget
+
+```ts
+type GitDoorTarget = Readonly<{
+  installationId: string;
+  repository: string;
+  scope: "read" | "write";
+}>;
+```
+
+The repository and access one smart-HTTP request names.
+
+---
+
+### GitDoorHost
+
+```ts
+type GitDoorHost = Readonly<{
+  authenticate: Promise<
+     | Readonly<{
+     kind: "actor";
+     actor: HostActor;
+     role?: "owner" | "member";
+     workflow?: WorkflowAttestation & object;
+   }>
+    | null>;
+  isPublic: Promise<boolean>;
+  git: Promise<
+     | Readonly<{
+     push: Promise<Readonly<{
+        status: number;
+        headers: Readonly<Record<..., ...>>;
+        body: Uint8Array;
+     }>>;
+     read: Promise<Readonly<{
+        status: number;
+        headers: Readonly<Record<..., ...>>;
+        body: Uint8Array;
+     }>>;
+     binding: GitBinding;
+   }>
+    | null>;
+}>;
+```
+
+Identity and selected installation come only from host-held ports.
+
+---
+
+### GitPushJournalPorts
+
+```ts
+type GitPushJournalPorts = Readonly<{
+  owner: WatchdogSqliteOwner;
+  deliver: Promise<void>;
+  deliverSync: Promise<PostDeliveryResult>;
+  scheduleWake: Promise<void>;
+  now?: () => number;
+}>;
+```
+
+The standalone composition supplies selected-Instance admission and its alarm.
+
+---
+
+### EventSink
+
+```ts
+type EventSink = Readonly<{
+  emit: Promise<void>;
+}>;
+```
+
+The EVENTS binding: an App emits typed events the host routes.
+
+---
+
+### StandardWebhookPayload
+
+```ts
+type StandardWebhookPayload = Readonly<{
+  type: string;
+  timestamp: string;
+  data: Schema.Json;
+}>;
+```
+
+The Standard Webhooks payload shape.
+
+## Variables
+
+### workflowGitPassPrefix
+
+```ts
+const workflowGitPassPrefix: "wgp." = "wgp.";
+```
+
+A Workflow Git pass presented as `Authorization: Bearer` starts with this.
+
+## Functions
+
+### createInstallationGitAdmission()
+
+```ts
+function createInstallationGitAdmission(
+  ports,
+): (writer, repository, scope) => Promise<boolean>;
+```
+
+Reuse the live installation/verified Release rule without opening provider
+storage.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ports`   | `Readonly`\<\{ `currentInstallation`: `Promise`\< \| `Readonly`\<\{ `installationId`: `string`; `instanceId`: [`InstanceId`](index.md#instanceid) \| `null`; `appId`: `AppId`; `release`: \{ `releaseId`: `Schema.refine`\<`ReleaseId`, `Schema.String`\>; `appId`: `Schema.refine`\<`AppId`, `Schema.String`\>; `artifact`: `Schema.Struct`\<\{ `artifactRef`: `Schema.refine`\<`ArtifactRef`, `Schema.String`\>; `artifactDigest`: `Schema.refine`\<`Sha256Digest`, `Schema.String`\>; `provenance`: `Schema.Struct`\<\{ `sourceRevision`: ...; `sourceTreeDigest`: ...; `buildRecipeDigest`: ...; \}\>; \}\>; \}; `releasePin`: `"pinned"` \| `"floating"`; `authorityVersion`: `number`; `status`: `"enabled"` \| `"disabled"` \| `"deleted"`; `visibility`: `"private"` \| `"public"`; `declaredOperationsDigest`: `Sha256Digest`; `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `capabilityApproved`: `true`; `operations`: readonly `string`[]; `resources`: `"tenant-scope"` \| readonly ...[]; \}\>[]; `approval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: ...; `memberId`: ...; \} \| \{ `kind`: ...; `agentId`: ...; \} \| \{ `kind`: ...; `keyId`: ...; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; `approvedAnonymousMethods`: readonly `Readonly`\<\{ `name`: `string`; `digest`: `Sha256Digest`; \}\>[]; `anonymousApproval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: ...; `memberId`: ...; \} \| \{ `kind`: ...; `agentId`: ...; \} \| \{ `kind`: ...; `keyId`: ...; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; \}\> \| `null`\>; `declaration`: `Promise`\< \| `Readonly`\<\{ `api?`: `AppApi`; `displayName?`: `string`; `capabilities`: readonly `AppCapabilityId`[]; `calls?`: readonly `Readonly`\<\{ `appId`: ...; `methods`: ...; \}\>[]; `guidance?`: `string`; `handlers`: readonly `AppHandler`[]; `receives?`: readonly `"git.push"`[]; `icon?`: `string`; `roles`: readonly `AppRole`[]; `storage?`: readonly `AppStorageKey`[]; `commands?`: readonly `AppDeclaredCommand`[]; `gills?`: readonly `AppDeclaredGill`[]; `backend?`: `Readonly`\<\{ `bindings`: readonly ...[]; `sync?`: `Readonly`\<\{ `method`: ...; \}\>; \}\>; \}\> \| `null`\>; \}\> |
+
+#### Returns
+
+```ts
+(
+   writer,
+   repository,
+   scope
+): Promise<boolean>;
+```
+
+Reopen the host authority for this repository and requested scope.
+
+##### Parameters
+
+| Parameter    | Type                  |
+| ------------ | --------------------- |
+| `writer`     | `GitWriter` \| `null` |
+| `repository` | `string`              |
+| `scope`      | `"read"` \| `"write"` |
+
+##### Returns
+
+`Promise`\<`boolean`\>
+
+---
+
+### createAdmittedGit()
+
+```ts
+function createAdmittedGit(ports): AdmittedGit;
+```
+
+Fixed order: host grant, Workflow ceiling, App policy, provider exchange,
+durable journal.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ports`   | `Readonly`\<\{ `installationId`: `string`; `store`: [`GitStore`](#gitstore); `grants`: [`GitGrants`](#gitgrants); `policy`: [`GitPolicy`](#gitpolicy); `journal`: [`GitJournal`](#gitjournal); `beforeProvider?`: () => `void`; \}\> |
+
+#### Returns
+
+[`AdmittedGit`](#admittedgit)
+
+---
+
+### smartHttpExchange()
+
+```ts
+function smartHttpExchange(
+  method,
+  url,
+  suffix,
+): Readonly<{
+  scope: "read" | "write";
+  advertise: boolean;
+}> | null;
+```
+
+One smart-HTTP exchange: the method, `service` query and path suffix a Git
+client sends, whatever path names the repository. Null otherwise.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `method`  | `string` |
+| `url`     | `URL`    |
+| `suffix`  | `string` |
+
+#### Returns
+
+\| `Readonly`\<\{ `scope`: `"read"` \| `"write"`; `advertise`: `boolean`; \}\>
+\| `null`
+
+---
+
+### gitDoorRoute()
+
+```ts
+function gitDoorRoute(
+  method,
+  url,
+):
+  | (Readonly<{
+      installationId: string;
+      repository: string;
+      scope: "read" | "write";
+    }> &
+      Readonly<{
+        advertise: boolean;
+      }>)
+  | null;
+```
+
+Oyster's own Git address: the repository, scope and phase one request names, or
+null when it is not an exact Oyster Git exchange.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `method`  | `string` |
+| `url`     | `URL`    |
+
+#### Returns
+
+\| `Readonly`\<\{ `installationId`: `string`; `repository`: `string`; `scope`:
+`"read"` \| `"write"`; \}\> & `Readonly`\<\{ `advertise`: `boolean`; \}\> \|
+`null`
+
+---
+
+### createGitDoor()
+
+```ts
+function createGitDoor(host): Hono;
+```
+
+Mount one smart-HTTP door with no provider credentials or alternate write
+branch.
+
+#### Parameters
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `host`    | [`GitDoorHost`](#gitdoorhost) |
+
+#### Returns
+
+`Hono`
+
+---
+
+### createGitPushJournal()
+
+```ts
+function createGitPushJournal(ports): Promise<{
+  armSync: Promise<number>;
+  tip: string | null;
+  accept: Promise<"duplicate" | "recorded">;
+  alarm: Promise<void>;
+  nextWake: () => number | null;
+}>;
+```
+
+Carrier owns delivery state; this journal owns accepted fact identity.
+
+#### Parameters
+
+| Parameter | Type                                          |
+| --------- | --------------------------------------------- |
+| `ports`   | [`GitPushJournalPorts`](#gitpushjournalports) |
+
+#### Returns
+
+`Promise`\<\{ `armSync`: `Promise`\<`number`\>; `tip`: `string` \| `null`;
+`accept`: `Promise`\<`"duplicate"` \| `"recorded"`\>; `alarm`:
+`Promise`\<`void`\>; `nextWake`: () => `number` \| `null`; \}\>
+
+---
+
+### lsRefsRequest()
+
+```ts
+function lsRefsRequest(): Uint8Array;
+```
+
+The protocol-v2 ls-refs request body.
+
+#### Returns
+
+`Uint8Array`
+
+---
+
+### parseLsRefs()
+
+```ts
+function parseLsRefs(response): object[];
+```
+
+Parse an ls-refs response into refs.
+
+#### Parameters
+
+| Parameter  | Type         |
+| ---------- | ------------ |
+| `response` | `Uint8Array` |
+
+#### Returns
+
+`object`[]
+
+---
+
+### signStandardWebhook()
+
+```ts
+function signStandardWebhook(secret, id, timestamp, body): Promise<string>;
+```
+
+The Standard Webhooks `webhook-signature` value for one delivery.
+
+#### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `secret`    | `string` |
+| `id`        | `string` |
+| `timestamp` | `number` |
+| `body`      | `string` |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+---
+
+### webhookHeaders()
+
+```ts
+function webhookHeaders(
+  secret,
+  id,
+  type,
+  timestamp,
+  body,
+): Promise<Record<string, string>>;
+```
+
+Headers for one signed delivery: Standard Webhooks plus `X-Hub-Signature-256`.
+
+#### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `secret`    | `string` |
+| `id`        | `string` |
+| `type`      | `string` |
+| `timestamp` | `number` |
+| `body`      | `string` |
+
+#### Returns
+
+`Promise`\<`Record`\<`string`, `string`\>\>