Implementation Brief

Build the v1 Swift library for git-pont as a standalone Swift Package that lets apps connect to Git hosting platforms, read and write repository files, create branches/repositories/forks, create PRs/MRs (including cross-fork), submit changes end-to-end, and provide HTTPS credentials for system Git commands.

The canonical API surface is defined in Architecture; all model types are defined in Provider Model. Where any doc disagrees with those two, those two win.

git-pont is intended to support other platform kits later. The Swift Package is the first implementation, not a statement that the provider model is Swift-only. See Kits and Platforms.

Product Decisions

• Bitbucket Cloud is included in v1. Bitbucket Server/Data Center is not included.
• No SSH in the main integration model. Platform account connections over HTTPS are the default path.
• Codeberg is a preset Forgejo instance, not a separate provider kind.
• Apple/Swift is the only v1 implementation target.
• Android, web, and backend kits are future work, but v1 API/model decisions must remain portable.
• Language, OAuth ownership, and naming decisions are recorded in Decisions.

Supported v1 platforms:

• GitHub
• GitLab.com
• Self-hosted GitLab
• Codeberg (Forgejo preset)
• Forgejo custom instances
• Gitea custom instances

Definition of Done for v1

The Swift library is ready for app integration when:

• It builds as a Swift Package.
• Public API is documented enough for Lezin and GitFolder to consume.
• GitHub file read/write/delete, branch/repo/fork creation, and PR creation are implemented with mocked tests.
• GitLab.com and self-hosted GitLab file read/write/delete, branch/repo/fork creation, and MR creation are implemented with mocked tests.
• Codeberg/Forgejo/Gitea and Bitbucket Cloud file read/write/delete, branch/repo/fork creation, and PR creation are implemented with mocked tests.
• submitChange works for direct commit, branch + PR, fork + PR, and automatic strategy selection on all providers.
• Provider URL parsing is covered by a fixture matrix, including slashed-branch ambiguity and permalinks.
• Pagination is followed on all list endpoints with the documented safety cap.
• Credentials are stored only through CredentialStore; connections only through ConnectionStore.
• Apple Keychain credential store exists in a separate module.
• Provider constructors explicitly register public and self-hosted instances; custom hosts are never guessed.
• OAuth start/complete and token refresh APIs are implemented through provider-neutral auth models.
• Token refresh is automatic, race-free, and persisted (GitLab OAuth depends on it).
• Git CLI credential context exists for HTTPS remotes in GitPontGitCLI, exposed as a Swift extension on GitPont.
• No token is ever stored in repository config models or remote URLs.
• All network behavior is testable through an injected HTTP client.
• No default tests require live network access.

Current Build Status

The repository is buildable now:

• Swift package build passes from the root public SwiftPM manifest and from libs/swift.
• Swift package tests pass from the root public SwiftPM manifest and from libs/swift.
• Docs build from docs/content through docs/site/girk.json.
• Root npm run validate runs Swift build, Swift tests, and docs build.
• npm run validate:live is the explicit release gate for opt-in live write tests against dedicated provider repositories.
• The monorepo layout uses libs/swift for the Apple implementation and leaves room for future sibling libraries such as libs/kotlin and libs/typescript.

Implemented in the current Swift package:

• Core provider-neutral models, stores, facade, URL resolution helpers, and validation.
• GitHub, GitLab, Forgejo/Gitea, and Bitbucket Cloud provider operations for account, repositories, branches, file read/list/commit/delete, branch create/delete, repository create, fork, and PR/MR create.
• submitChange orchestration for direct commit, branch + PR, fork + PR, and automatic selection.
• Provider-neutral OAuth facade start/complete methods, backed by GitHub device flow, GitLab PKCE, and Forgejo/Gitea browser OAuth provider implementations.
• Token refresh for expiring OAuth credentials, serialized per connection and persisted before provider/API or Git CLI credential use, with one reactive refresh-and-retry after an unexpected authentication failure.
• Apple Keychain credential storage in GitPontKeychain.
• HTTPS Git credential context support in GitPontGitCLI.
• Mocked unit coverage for provider requests/responses, reusable JSON fixtures, pagination, URL parsing, OAuth, refresh race behavior, Keychain payloads, Git CLI credentials, change submission, branch cleanup, and blind-overwrite safety.
• Partial-submission reporting for branch/fork submission sequences that fail after an intermediate step.

Remaining before calling v1 complete:

• A verified run of the opt-in live write tests against dedicated disposable GitHub, GitLab, Forgejo/Gitea, and Bitbucket Cloud repositories.

Expected Repository Structure

package.json
libs/
  swift/
    Package.swift
    Sources/
      GitPontCore/
      GitPontGitHub/
      GitPontGitLab/
      GitPontForge/
      GitPontKeychain/
      GitPontGitCLI/
    Tests/
      GitPontCoreTests/
      GitPontGitHubTests/
        Fixtures/
      GitPontGitLabTests/
        Fixtures/
      GitPontForgeTests/
        Fixtures/
      GitPontGitCLITests/
docs/
  content/
  site/
kits/
  # reserved for app/demo kits if needed later
scripts/

First Consumer Use Cases

Lezin

Open a remote Markdown file URL, edit it, and save by committing through the provider API — directly when the user can push, via branch + PR, or via fork + PR when the user has no write access. Lezin does not need local Git.

GitFolder

Use provider connections and credentials for HTTPS remotes while GitFolder continues to run its own sync loop through system git. Also: repository listing, branch listing, and remote repository creation during folder setup.

Implementation Warnings

• Do not assume GitLab namespaces are one segment.
• Do not assume branch names are slash-free — URL parsing is two-phase (see Architecture).
• Do not assume custom domains are GitLab/Forgejo unless configured.
• Do not embed tokens in remote URLs.
• Do not overwrite remote files without conflict protection; blind overwrite requires an explicit opt-in flag.
• Do not read only the first page of any list endpoint.
• Do not run two concurrent token refreshes for one connection.
• Do not leave OAuth start/complete or refresh as app-specific behavior.
• Do not make GitPontCore depend on GitPontGitCLI.
• Do not make Markdown-specific APIs.
• Do not make UI components part of core.
• Do not put Keychain code in core.
• Do not hardcode consuming app names into the package.

Kits and Platforms

git-pont should be designed as a family of reusable platform libraries that share one provider-neutral contract. Kits are reserved for app/demo bundles or composed starter integrations.

The first library is the Swift implementation:

libs/swift

libs/swift is implemented as a Swift Package for Apple platforms and was the first v1 implementation target. Lezin and GitFolder are the first consumers. A TypeScript library (libs/typescript) and Cloudflare Worker kit (kits/worker) now sit alongside it — see below.

The repository root also contains a public Package.swift that points SwiftPM at the libs/swift source and test paths. External Swift projects should depend on the repository URL, not on a libs/swift subdirectory URL.

A TypeScript implementation now exists alongside the Swift library, following the same libs-vs-kits split — a reusable library plus a deployable service:

libs/typescript   @git-pont/core    TypeScript port of the contract (auth + REST proxy)
kits/worker        @git-pont/worker  Cloudflare Worker consuming @git-pont/core

libs/typescript is a framework-agnostic library (fetch + WebCrypto only) that runs in Workers, Node, and browsers, mirroring libs/swift; kits/worker is a deployable app kit that adds OAuth callback handling, sessions, and persistence for web consumers such as gitKanban. See TypeScript Core Kit and Cloudflare Worker Service.

Further libraries may be added without changing the shared product model:

libs/kotlin       Kotlin/Android

These names are planning labels, not committed package names.

Shared Contract

Every reusable library should implement the same behavioral contract:

• supported provider kinds and provider instances
• normalized repository, branch, file, directory, commit, and pull request models
• two-phase URL parsing with slashed-branch ambiguity resolution
• conflict-safe file create/update/delete behavior
• direct commit, branch + pull request, and fork + pull request submission flows
• provider-neutral authentication and credential storage concepts
• normalized errors that preserve provider context without leaking secrets
• internal pagination with a truncation flag
• no content-type assumptions about file data
• no app-specific UI or settings ownership

For v1, the canonical contract is expressed in Swift in Architecture and Provider Model. Future libraries should translate those models idiomatically while preserving field meanings and behavior.

Swift Library Boundary

The Swift library owns:

• Swift public API
• async/await implementation
• Apple Keychain credential store module
• native OAuth helper primitives where useful
• Git CLI credential context for macOS apps that shell out to git

The Swift library must not bake in Apple-only assumptions into provider semantics. In particular:

• URL parsing rules must not depend on Foundation-specific quirks.
• Provider model fields must map cleanly to JSON-like data shapes.
• Credential and connection persistence must stay behind protocols.
• Network behavior must stay behind an injected HTTP client.
• Core models should avoid UI framework types.

Future Kit Notes

Android would likely provide:

• Kotlin data classes matching the shared model
• coroutine-based async APIs
• Android Keystore-backed credential storage
• browser/custom-tab OAuth helpers

Web would likely provide:

• TypeScript types matching the shared model
• fetch-based HTTP client injection
• storage adapters selected by the consuming app
• OAuth flows appropriate for browser or backend-mediated auth

None of this is v1 scope. It only constrains v1 documentation and API design so the Swift package is not a dead end.