@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/git.md

@@ -0,0 +1,579 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / git
+
+# git
+
+## Type Aliases
+
+### GitRepositoryName
+
+```ts
+type GitRepositoryName = z.output<typeof gitRepositoryNameSchema>;
+```
+
+Local repository name decoded at a host's repository boundary.
+
+---
+
+### RepositoryRef
+
+```ts
+type RepositoryRef = z.output<typeof repositoryRefSchema>;
+```
+
+Installation-local repository or registered Team source, selected by its host.
+
+---
+
+### GitWriter
+
+```ts
+type GitWriter =
+  | Readonly<{
+      kind: "actor";
+      actor: HostActor;
+      role?: "owner" | "member";
+      workflow?: WorkflowAttestation & object;
+    }>
+  | Readonly<{
+      kind: "installation";
+      installationId: string;
+      onBehalfOf: HostActor | null;
+    }>;
+```
+
+Host-held writer identity; Workflow attribution reuses Puffball's sole grammar.
+
+---
+
+### GitPushQuestion
+
+```ts
+type GitPushQuestion = z.output<typeof gitPushQuestionSchema>;
+```
+
+Ref question sent only after host grant and Workflow branch admission.
+
+---
+
+### GitPushVerdict
+
+```ts
+type GitPushVerdict = z.output<typeof gitPushVerdictSchema>;
+```
+
+Explicit permission or bounded per-ref refusal for the whole push.
+
+---
+
+### GitRefUpdate
+
+```ts
+type GitRefUpdate = z.output<typeof appGitPushFactSchema>["updates"][number];
+```
+
+One bounded ref update, shared by push questions and accepted facts.
+
+---
+
+### AppGitPushFact
+
+```ts
+type AppGitPushFact = z.output<typeof appGitPushFactSchema>;
+```
+
+Host-delivered push fact; retries retain the same event ID.
+
+---
+
+### AppGitLifecycle
+
+```ts
+type AppGitLifecycle = Readonly<{
+  authorizeGitPush?: (question) => Promise<GitPushVerdict>;
+  onGitPush?: (fact) => Promise<void>;
+}>;
+```
+
+App-owned lifecycle handler, separate from its callable method catalog.
+
+---
+
+### GitRepositoryInfo
+
+```ts
+type GitRepositoryInfo = Readonly<{
+  name: string;
+  defaultBranch: string;
+  lastPushAt: string | null;
+  source: string | null;
+}>;
+```
+
+Credential-free repository metadata, with installation-local names.
+
+---
+
+### GitCommit
+
+```ts
+type GitCommit = Readonly<{
+  hash: string;
+  treeHash: string;
+  message: string;
+  author: {
+    name: string;
+    email: string;
+  };
+  committer: {
+    name: string;
+    email: string;
+  };
+  parents: string[];
+  authoredAt: number;
+  committedAt: number;
+}>;
+```
+
+Artifacts commit metadata, with the provider's credential fields absent.
+
+---
+
+### GitTreeEntry
+
+```ts
+type GitTreeEntry = Readonly<{
+  name: string;
+  mode: string;
+  hash: string;
+  type: "blob" | "tree" | "commit";
+}>;
+```
+
+One immediate child of a Git tree.
+
+---
+
+### GitExchangeRequest
+
+```ts
+type GitExchangeRequest = Readonly<{
+  service: "upload-pack" | "receive-pack";
+  phase: "advertise" | "exchange";
+  body: Uint8Array | null;
+  headers: Readonly<Record<string, string>>;
+}>;
+```
+
+Smart-HTTP request; the host supplies and keeps the provider credential.
+
+---
+
+### GitExchangeResponse
+
+```ts
+type GitExchangeResponse = Readonly<{
+  status: number;
+  headers: Readonly<Record<string, string>>;
+  body: Uint8Array;
+}>;
+```
+
+Credential-free RPC response; host adapters own stream conversion and byte
+bounds.
+
+---
+
+### GitBinding
+
+```ts
+type GitBinding = Readonly<{
+  create: Promise<
+    Readonly<{
+      name: string;
+      defaultBranch: string;
+      lastPushAt: string | null;
+      source: string | null;
+    }>
+  >;
+  fork: Promise<
+    Readonly<{
+      name: string;
+      defaultBranch: string;
+      lastPushAt: string | null;
+      source: string | null;
+    }>
+  >;
+  cloneUrl: Promise<string>;
+  info: Promise<Readonly<{
+    name: string;
+    defaultBranch: string;
+    lastPushAt: string | null;
+    source: string | null;
+  }> | null>;
+  delete: Promise<boolean>;
+  log: Promise<
+    Readonly<{
+      hash: string;
+      treeHash: string;
+      message: string;
+      author: {
+        name: string;
+        email: string;
+      };
+      committer: {
+        name: string;
+        email: string;
+      };
+      parents: string[];
+      authoredAt: number;
+      committedAt: number;
+    }>[]
+  >;
+  readCommit: Promise<Readonly<{
+    hash: string;
+    treeHash: string;
+    message: string;
+    author: {
+      name: string;
+      email: string;
+    };
+    committer: {
+      name: string;
+      email: string;
+    };
+    parents: string[];
+    authoredAt: number;
+    committedAt: number;
+  }> | null>;
+  readTree: Promise<
+    | Readonly<{
+        name: string;
+        mode: string;
+        hash: string;
+        type: "blob" | "tree" | "commit";
+      }>[]
+    | null
+  >;
+  readBlob: Promise<Uint8Array<ArrayBufferLike> | null>;
+  refs: Promise<object[]>;
+  exchange: Promise<
+    Readonly<{
+      status: number;
+      headers: Readonly<Record<string, string>>;
+      body: Uint8Array;
+    }>
+  >;
+}>;
+```
+
+Installation-scoped GIT backend binding; approved operations and actor grants
+bound every call.
+
+## Variables
+
+### gitRepositoryCapability
+
+```ts
+const gitRepositoryCapability: "git.repository";
+```
+
+Requested installation-scoped Git authority; a declaration is never a grant.
+
+---
+
+### repositoryRefSchema
+
+```ts
+const repositoryRefSchema: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        kind: ZodLiteral<"installation">;
+        installationId: ZodString;
+        repository: ZodString;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        kind: ZodLiteral<"team-source">;
+        repository: ZodString;
+      },
+      $strict
+    >,
+  ],
+  "kind"
+>;
+```
+
+Host-selected repository namespace. Team identity comes from the host; decoding
+this reference never grants access to either namespace.
+
+---
+
+### gitWriterSchema
+
+```ts
+const gitWriterSchema: ZodDiscriminatedUnion<[ZodObject<{
+  kind: ZodLiteral<"actor">;
+  actor: ZodDiscriminatedUnion<[ZodObject<{
+     kind: ZodMiniLiteral<"member">;
+     memberId: ZodMiniString<string>;
+   }, $strict>, ZodObject<{
+     kind: ZodMiniLiteral<"agent">;
+     agentId: ZodMiniString<string>;
+   }, $strict>, ZodObject<{
+     kind: ZodMiniLiteral<"team-key">;
+     keyId: ZodMiniString<string>;
+  }, $strict>], "kind">;
+  role: ZodMiniOptional<ZodMiniEnum<{
+     member: "member";
+     owner: "owner";
+  }>>;
+  workflow: ZodOptional<ZodObject<{
+     armedBy: ZodDiscriminatedUnion<[ZodObject<{
+        kind: ...;
+        memberId: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        agentId: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        keyId: ...;
+     }, $strict>], "kind">;
+     branches: ZodArray<ZodString>;
+     workflowId: ZodMiniString<string>;
+     runId: ZodMiniString<string>;
+     nodeId: ZodMiniString<string>;
+  }, $strict>>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"installation">;
+  installationId: ZodString;
+  onBehalfOf: ZodNullable<ZodDiscriminatedUnion<[ZodObject<{
+     kind: ZodMiniLiteral<"member">;
+     memberId: ZodMiniString<string>;
+   }, $strict>, ZodObject<{
+     kind: ZodMiniLiteral<"agent">;
+     agentId: ZodMiniString<string>;
+   }, $strict>, ZodObject<{
+     kind: ZodMiniLiteral<"team-key">;
+     keyId: ZodMiniString<string>;
+  }, $strict>], "kind">>;
+}, $strict>], "kind">;
+```
+
+Canonical Git writer decoder; identity is attested by a host, never by an App.
+
+---
+
+### gitPushQuestionSchema
+
+```ts
+const gitPushQuestionSchema: ZodObject<{
+  repository: ZodString;
+  writer: ZodObject<{
+     kind: ZodLiteral<"actor">;
+     actor: ZodDiscriminatedUnion<[ZodObject<{
+        kind: ZodMiniLiteral<"member">;
+        memberId: ZodMiniString<string>;
+      }, $strict>, ZodObject<{
+        kind: ZodMiniLiteral<"agent">;
+        agentId: ZodMiniString<string>;
+      }, $strict>, ZodObject<{
+        kind: ZodMiniLiteral<"team-key">;
+        keyId: ZodMiniString<string>;
+     }, $strict>], "kind">;
+     role: ZodMiniOptional<ZodMiniEnum<{
+        member: "member";
+        owner: "owner";
+     }>>;
+     workflow: ZodOptional<ZodObject<{
+        armedBy: ZodDiscriminatedUnion<[ZodObject<{
+           kind: ...;
+           memberId: ...;
+         }, $strict>, ZodObject<{
+           kind: ...;
+           agentId: ...;
+         }, $strict>, ZodObject<{
+           kind: ...;
+           keyId: ...;
+        }, $strict>], "kind">;
+        branches: ZodArray<ZodString>;
+        workflowId: ZodMiniString<string>;
+        runId: ZodMiniString<string>;
+        nodeId: ZodMiniString<string>;
+     }, $strict>>;
+  }, $strict>;
+  updates: ZodArray<ZodObject<{
+     ref: ZodString;
+     before: ZodString;
+     after: ZodString;
+  }, $strict>>;
+}, $strict>;
+```
+
+The App's question covers the whole push, under host-held attribution.
+
+---
+
+### gitPushVerdictSchema
+
+```ts
+const gitPushVerdictSchema: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        allowed: ZodLiteral<true>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        allowed: ZodLiteral<false>;
+        refused: ZodArray<
+          ZodObject<
+            {
+              ref: ZodString;
+              message: ZodString;
+            },
+            $strict
+          >
+        >;
+      },
+      $strict
+    >,
+  ],
+  "allowed"
+>;
+```
+
+A whole push verdict; refusal messages are shown by ordinary Git clients.
+
+---
+
+### appGitPushFactSchema
+
+```ts
+const appGitPushFactSchema: ZodObject<{
+  repository: ZodString;
+  writer: ZodDiscriminatedUnion<[ZodObject<{
+     kind: ZodLiteral<"actor">;
+     actor: ZodDiscriminatedUnion<[ZodObject<{
+        kind: ZodMiniLiteral<...>;
+        memberId: ZodMiniString<...>;
+      }, $strict>, ZodObject<{
+        kind: ZodMiniLiteral<...>;
+        agentId: ZodMiniString<...>;
+      }, $strict>, ZodObject<{
+        kind: ZodMiniLiteral<...>;
+        keyId: ZodMiniString<...>;
+     }, $strict>], "kind">;
+     role: ZodMiniOptional<ZodMiniEnum<{
+        member: "member";
+        owner: "owner";
+     }>>;
+     workflow: ZodOptional<ZodObject<{
+        armedBy: ZodDiscriminatedUnion<[..., ..., ...], "kind">;
+        branches: ZodArray<ZodString>;
+        workflowId: ZodMiniString<string>;
+        runId: ZodMiniString<string>;
+        nodeId: ZodMiniString<string>;
+     }, $strict>>;
+   }, $strict>, ZodObject<{
+     kind: ZodLiteral<"installation">;
+     installationId: ZodString;
+     onBehalfOf: ZodNullable<ZodDiscriminatedUnion<[ZodObject<{
+        kind: ...;
+        memberId: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        agentId: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        keyId: ...;
+     }, $strict>], "kind">>;
+  }, $strict>], "kind">;
+  updates: ZodArray<ZodObject<{
+     ref: ZodString;
+     before: ZodString;
+     after: ZodString;
+  }, $strict>>;
+  unexplained: ZodOptional<ZodArray<ZodObject<{
+     ref: ZodString;
+     journaled: ZodNullable<ZodString>;
+  }, $strict>>>;
+  eventId: ZodString;
+}, $strict>;
+```
+
+One accepted push, with host attribution and no remote or credential.
+
+## Functions
+
+### repositoryRefKey()
+
+```ts
+function repositoryRefKey(repository): string;
+```
+
+Stable namespace identity, serialized through the canonical repository decoder.
+
+#### Parameters
+
+| Parameter    | Type                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `repository` | \| \{ `kind`: `"installation"`; `installationId`: `string`; `repository`: `string`; \} \| \{ `kind`: `"team-source"`; `repository`: `string`; \} |
+
+#### Returns
+
+`string`
+
+---
+
+### repositoryRefsEqual()
+
+```ts
+function repositoryRefsEqual(left, right): boolean;
+```
+
+Compare repository namespace and coordinates independently of allocation or
+property order.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `left`    | \| \{ `kind`: `"installation"`; `installationId`: `string`; `repository`: `string`; \} \| \{ `kind`: `"team-source"`; `repository`: `string`; \} |
+| `right`   | \| \{ `kind`: `"installation"`; `installationId`: `string`; `repository`: `string`; \} \| \{ `kind`: `"team-source"`; `repository`: `string`; \} |
+
+#### Returns
+
+`boolean`
+
+---
+
+### dispatchAppGitPush()
+
+```ts
+function dispatchAppGitPush(lifecycle, raw): Promise<void>;
+```
+
+Parse a host-admitted fact and invoke its lifecycle handler, preserving
+rejection.
+
+#### Parameters
+
+| Parameter   | Type                                  |
+| ----------- | ------------------------------------- |
+| `lifecycle` | [`AppGitLifecycle`](#appgitlifecycle) |
+| `raw`       | `unknown`                             |
+
+#### Returns
+
+`Promise`\<`void`\>