Skip to content
Agar0.5.0
API reference

git

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/agar/git";

Exports

Section titled “Exports”
Kind Export Description
type alias GitRepositoryName Local repository name decoded at a host’s repository boundary.
type alias RepositoryRef Installation-local repository or registered Team source, selected by its host.
type alias GitWriter Host-held writer identity; Workflow attribution reuses Puffball’s sole grammar.
type alias GitPushQuestion Ref question sent only after host grant and Workflow branch admission.
type alias GitPushVerdict Explicit permission or bounded per-ref refusal for the whole push.
type alias GitRefUpdate One bounded ref update, shared by push questions and accepted facts.
type alias AppGitPushFact Host-delivered push fact; retries retain the same event ID.
type alias AppGitLifecycle App-owned lifecycle handler, separate from its callable method catalog.
type alias GitRepositoryInfo Credential-free repository metadata, with installation-local names.
type alias GitCommit Artifacts commit metadata, with the provider’s credential fields absent.
type alias GitTreeEntry One immediate child of a Git tree.
type alias GitExchangeRequest Smart-HTTP request; the host supplies and keeps the provider credential.
type alias GitExchangeResponse Credential-free RPC response; host adapters own stream conversion and byte bounds.
type alias GitBinding Installation-scoped GIT backend binding; approved operations and actor grants bound every call.
constant gitRepositoryCapability Requested installation-scoped Git authority; a declaration is never a grant.
constant repositoryRefSchema Host-selected repository namespace. Team identity comes from the host; decoding this reference never grants access to either namespace.
constant gitWriterSchema Canonical Git writer decoder; identity is attested by a host, never by an App.
constant gitPushQuestionSchema The App’s question covers the whole push, under host-held attribution.
constant gitPushVerdictSchema A whole push verdict; refusal messages are shown by ordinary Git clients.
constant appGitPushFactSchema One accepted push, with host attribution and no remote or credential.
function repositoryRefKey() Stable namespace identity, serialized through the canonical repository decoder.
function repositoryRefsEqual() Compare repository namespace and coordinates independently of allocation or property order.
function dispatchAppGitPush() Parse a host-admitted fact and invoke its lifecycle handler, preserving rejection.

GitRepositoryNametype alias

Section titled “GitRepositoryName”
Signature
type GitRepositoryName = z.output<typeof gitRepositoryNameSchema>;

Local repository name decoded at a host’s repository boundary.

RepositoryReftype alias

Section titled “RepositoryRef”
Signature
type RepositoryRef = z.output<typeof repositoryRefSchema>;

Installation-local repository or registered Team source, selected by its host.

GitWritertype alias

Section titled “GitWriter”
Signature
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.

GitPushQuestiontype alias

Section titled “GitPushQuestion”
Signature
type GitPushQuestion = z.output<typeof gitPushQuestionSchema>;

Ref question sent only after host grant and Workflow branch admission.

GitPushVerdicttype alias

Section titled “GitPushVerdict”
Signature
type GitPushVerdict = z.output<typeof gitPushVerdictSchema>;

Explicit permission or bounded per-ref refusal for the whole push.

GitRefUpdatetype alias

Section titled “GitRefUpdate”
Signature
type GitRefUpdate = z.output<typeof appGitPushFactSchema>["updates"][number];

One bounded ref update, shared by push questions and accepted facts.

AppGitPushFacttype alias

Section titled “AppGitPushFact”
Signature
type AppGitPushFact = z.output<typeof appGitPushFactSchema>;

Host-delivered push fact; retries retain the same event ID.

AppGitLifecycletype alias

Section titled “AppGitLifecycle”
Signature
type AppGitLifecycle = Readonly<{
  authorizeGitPush?: (question) => Promise<GitPushVerdict>;
  onGitPush?: (fact) => Promise<void>;
}>;

App-owned lifecycle handler, separate from its callable method catalog.

GitRepositoryInfotype alias

Section titled “GitRepositoryInfo”
Signature
type GitRepositoryInfo = Readonly<{
  name: string;
  defaultBranch: string;
  lastPushAt: string | null;
  source: string | null;
}>;

Credential-free repository metadata, with installation-local names.

GitCommittype alias

Section titled “GitCommit”
Signature
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.

GitTreeEntrytype alias

Section titled “GitTreeEntry”
Signature
type GitTreeEntry = Readonly<{
  name: string;
  mode: string;
  hash: string;
  type: "blob" | "tree" | "commit";
}>;

One immediate child of a Git tree.

GitExchangeRequesttype alias

Section titled “GitExchangeRequest”
Signature
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.

GitExchangeResponsetype alias

Section titled “GitExchangeResponse”
Signature
type GitExchangeResponse = Readonly<{
  status: number;
  headers: Readonly<Record<string, string>>;
  body: Uint8Array;
}>;

Credential-free RPC response; host adapters own stream conversion and byte bounds.

GitBindingtype alias

Section titled “GitBinding”
Signature
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.

gitRepositoryCapabilityconstant

Section titled “gitRepositoryCapability”
Signature
const gitRepositoryCapability: "git.repository";

Requested installation-scoped Git authority; a declaration is never a grant.

repositoryRefSchemaconstant

Section titled “repositoryRefSchema”
Signature
const repositoryRefSchema: ZodLazy<
  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.

gitWriterSchemaconstant

Section titled “gitWriterSchema”
Signature
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.

gitPushQuestionSchemaconstant

Section titled “gitPushQuestionSchema”
Signature
const gitPushQuestionSchema: ZodLazy<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<..., ...>, ZodObject<..., ...>, ZodObject<..., ...>], "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.

gitPushVerdictSchemaconstant

Section titled “gitPushVerdictSchema”
Signature
const gitPushVerdictSchema: ZodLazy<
  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.

appGitPushFactSchemaconstant

Section titled “appGitPushFactSchema”
Signature
const appGitPushFactSchema: ZodLazy<ZodObject<{
  repository: ZodString;
  writer: ZodDiscriminatedUnion<[ZodObject<{
     kind: ZodLiteral<"actor">;
     actor: ZodDiscriminatedUnion<[ZodObject<{
        kind: ...;
        memberId: ...;
      }, $strict>, ZodObject<{
        kind: ...;
        agentId: ...;
      }, $strict>, ZodObject<{
        kind: ...;
        keyId: ...;
     }, $strict>], "kind">;
     role: ZodMiniOptional<ZodMiniEnum<{
        member: "member";
        owner: "owner";
     }>>;
     workflow: ZodOptional<ZodObject<{
        armedBy: ZodDiscriminatedUnion<..., ...>;
        branches: ZodArray<...>;
        workflowId: ZodMiniString<...>;
        runId: ZodMiniString<...>;
        nodeId: ZodMiniString<...>;
     }, $strict>>;
   }, $strict>, ZodObject<{
     kind: ZodLiteral<"installation">;
     installationId: ZodString;
     onBehalfOf: ZodNullable<ZodDiscriminatedUnion<[ZodObject<..., ...>, ZodObject<..., ...>, ZodObject<..., ...>], "kind">>;
  }, $strict>], "kind">;
  updates: ZodArray<ZodObject<{
     ref: ZodString;
     before: ZodString;
     after: ZodString;
  }, $strict>>;
  unexplained: ZodOptional<ZodArray<ZodObject<{
     ref: ZodString;
     journaled: ZodNullable<ZodString>;
  }, $strict>>>;
  eventId: ZodLazy<ZodString>;
}, $strict>>;

One accepted push, with host attribution and no remote or credential.

repositoryRefKey()function

Section titled “repositoryRefKey()”
Signature
function repositoryRefKey(repository): string;

Stable namespace identity, serialized through the canonical repository decoder.

Parameters

Section titled “Parameters”
Parameter Type
repository | { kind: "installation"; installationId: string; repository: string; } | { kind: "team-source"; repository: string; }

Returns

Section titled “Returns”

string

repositoryRefsEqual()function

Section titled “repositoryRefsEqual()”
Signature
function repositoryRefsEqual(left, right): boolean;

Compare repository namespace and coordinates independently of allocation or property order.

Parameters

Section titled “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

Section titled “Returns”

boolean

dispatchAppGitPush()function

Section titled “dispatchAppGitPush()”
Signature
function dispatchAppGitPush(lifecycle, raw): Promise<void>;

Parse a host-admitted fact and invoke its lifecycle handler, preserving rejection.

Parameters

Section titled “Parameters”
Parameter Type
lifecycle AppGitLifecycle
raw unknown

Returns

Section titled “Returns”

Promise<void>