Cloudflare Artifacts adapter

Package:

@gittrix/[email protected]

Imports:

import {
  CloudflareArtifactsDurableAdapter,
  CloudflareArtifactsEphemeralAdapter,
} from '@gittrix/adapter-cloudflare-artifacts'

Options

Durable:

interface CloudflareArtifactsDurableOptions {
  accountId: string
  apiToken: string
  namespace?: string
  repoName: string
  branch?: string
  mirrorRoot?: string
}

Ephemeral:

interface CloudflareArtifactsEphemeralOptions {
  accountId: string
  apiToken: string
  namespace?: string
  workingRoot?: string
}

Capabilities

Cloudflare durable:

{ git: true, push: true, fetch: true, history: true, ttl: false, latencyClass: 'regional' }

Cloudflare ephemeral:

{ git: true, push: false, fetch: false, history: false, ttl: true, latencyClass: 'regional' }

Durable behavior

• Creates or fetches an Artifacts repo by repoName.
• Mints a repo token through the Artifacts API.
• Maintains a local mirror under ~/.gittrix/durable-mirrors by default.
• Reads durable content from git objects.
• Applies promoted files as a commit and pushes to the selected branch.

Ephemeral behavior

• Creates one Artifacts repo per session named gittrix-eph-<session-id>.
• Mints a repo token.
• Clones the repo locally under ~/.gittrix/cf-artifacts-ephemeral/<session-id> by default.
• Falls back to git init if clone fails.
• Materializes the durable baseline into the local workspace when a durable adapter is provided.
• Commits a gittrix baseline <sha> commit, or an empty baseline commit if needed.
• Tracks API-written files, deleted files, unstaged changes, staged changes, and untracked files.
• Excludes .git, .gittrix, .glib, and .gittrix-touched.json from session changes.
• Destroys both the local workspace and remote ephemeral repo on eviction.

Cloudflare durable + ephemeral

import { GitTrix } from '@gittrix/core'
import {
  CloudflareArtifactsDurableAdapter,
  CloudflareArtifactsEphemeralAdapter,
} from '@gittrix/adapter-cloudflare-artifacts'

const gittrix = new GitTrix({
  durable: new CloudflareArtifactsDurableAdapter({
    accountId: process.env.CF_ACCOUNT_ID!,
    apiToken: process.env.CF_API_TOKEN!,
    repoName: 'app',
    branch: 'main',
  }),
  ephemeral: new CloudflareArtifactsEphemeralAdapter({
    accountId: process.env.CF_ACCOUNT_ID!,
    apiToken: process.env.CF_API_TOKEN!,
  }),
})

GitHub durable + Cloudflare ephemeral

GitHub can stay the durable source of truth while Cloudflare Artifacts provides the isolated git-backed workspace where agents run.

flowchart LR
  GH["GitHub durable\nsource of truth"] --> Router["GitTrix"]
  Router --> CF["Cloudflare Artifacts\nephemeral session repo"]
  Agent["Agent tools"] --> CF
  CF --> Diff["session diff"]
  Diff --> User["human review"]
  User --> Promote["promote selected files"]
  Promote --> GH

import { GitTrix } from '@gittrix/core'
import { GitHubDurableAdapter } from '@gittrix/adapter-github'
import { CloudflareArtifactsEphemeralAdapter } from '@gittrix/adapter-cloudflare-artifacts'

const gittrix = new GitTrix({
  durable: new GitHubDurableAdapter({
    owner: 'acme',
    repo: 'app',
    branch: 'main',
    token: process.env.GITHUB_TOKEN,
  }),
  ephemeral: new CloudflareArtifactsEphemeralAdapter({
    accountId: process.env.CF_ACCOUNT_ID!,
    apiToken: process.env.CF_API_TOKEN!,
  }),
})