chore: add live-credential smoke test across github/gitlab/gitea before merging push/pull/delete changes

[ClaudiaFang]

Context

Recent batch-push work (GitHub's pushBatch/deleteBatch switched to GraphQL createCommitOnBranch) was validated with mocked requestUrl only until manual live verification against a real repository. Real provider testing caught issues that mocks cannot detect:

• actual API request/response shape;
• HTTP status and provider-specific error behavior;
• GraphQL mutation failures returned as HTTP 200 with errors[];
• real commit/tree history behavior.

This repository supports three providers (GitHubService, GitLabService, GiteaService) with different API implementations. The goal is to create a reliable real-provider contract test process without over-coupling to provider internals.

Goal

Create a repeatable real-provider E2E harness that verifies production service code against real GitHub, GitLab, and Gitea environments.

The first PR should focus on provider contract verification, not a full CI testing platform.

Scope (v1)

E2E test foundation

• Add isolated e2e/vitest.e2e.config.ts
  • must not load existing mocked obsidian setup;
  • must import production service implementations directly.
• Add lightweight obsidian shim for E2E only
  • requestUrl backed by real fetch;
  • compatible response contract for BaseGitService.safeRequest();
  • token redaction before logging failures.
• Add provider runner script
  • do not pass custom flags directly to Vitest;
  • wrapper handles --provider, credential loading, and test filtering.
• Credentials must come from local files or secure CI secrets.
  • never commit tokens;
  • never print tokens.

Provider smoke scenarios

Shared scenarios (GitHub / GitLab / Gitea)

• testConnection
• pushFile create
• getFile
• pushFile update
• pushBatch
• deleteFile
• deleteBatch
• listFilesDetailed
• getBlob
• root path handling
• temporary branch/repository cleanup

GitHub additional scenarios

• GraphQL batch commit verification
• GraphQL errors[] handling verification
• symlink push (mode 120000)

Move / rename verification

• Verify commitBatch behavior
• Confirm new path exists
• Confirm old path is removed
• Validate provider-specific rename semantics

Independent verification

Tests must not only call the service under test to prove success.

Add provider-level verification helpers to check:

• branch head changes;
• commit history;
• file tree state;
• blob content;
• symlink mode where applicable.

SyncManager integration (limited v1)

Do not include full Obsidian UI automation in the first PR.

Before adding SyncManager E2E:

• Introduce or mock only the interaction boundary for confirmation/conflict dialogs.
• Keep provider services real.

Initial SyncManager coverage:

• push new file
• pull remote update

Defer:

• conflict resolution UI;
• full pushAll/pullAll flows;
• rename UI flows;
• symlink UI flows.

Environment strategy

Local/manual

• GitHub: disposable sandbox repository + fine-grained token.
• GitLab: disposable project + project access token.
• Gitea: pinned Docker image with runtime provisioning.

CI (future / limited)

Initial PR should avoid making GitHub/GitLab secrets required for every PR.

Recommended progression:

1. local/manual execution;
2. workflow_dispatch with protected secrets;
3. optional required checks after stability is proven.

Gitea provisioning

• Pin Gitea version.
• Start container.
• Wait for readiness endpoint.
• Create admin/test user.
• Generate access token.
• Create initialized repository.
• Execute E2E suite.
• Destroy environment.

Deferred follow-ups

• full CI release gating;
• scheduled API drift checks;
• large batch stress tests;
• binary file matrix;
• provider outage simulation;
• complete SyncManager E2E coverage.

Non-goals

• Not retroactively re-testing old changes.
• Not storing provider credentials in repository secrets for the first implementation.
• Not replacing existing mocked unit tests.

Implementation plan

Single branch / single PR:

branch: test/real-provider-e2e

Suggested order:

1. E2E infrastructure + credential handling
2. GitHub smoke suite (highest risk due GraphQL path)
3. GitLab smoke suite
4. Gitea container suite
5. Independent verification helpers
6. Minimal SyncManager integration (only if interaction boundary is ready)
7. Documentation

[ClaudiaFang]

Revised plan: real-provider E2E in one branch / one PR

Updated 2026-08-03. This replaces the earlier oversized proposal with a scope that can be implemented and reviewed in one branch and one PR, while still qualifying as real E2E for the plugin's core sync path.

Definition of “real E2E”

The suite must:

1. instantiate the production GitHubService, GitLabService, or GiteaService;
2. run them through SyncManager with an in-memory Vault where applicable;
3. execute real HTTP requests against GitHub, GitLab, and Gitea;
4. create real commits, trees, blobs, moves, and deletions;
5. verify the remote result with an independent raw API verifier, not through the service under test.

This PR does not attempt full Obsidian UI automation. Obsidian event ordering and modal interaction remain a short manual smoke checklist. The automated E2E boundary is the core sync logic + provider production code + real Git server.

---

Branch and PR

• Branch: test/real-provider-e2e
• PR: test(e2e): verify sync operations against GitHub, GitLab and Gitea

One branch, one PR, reviewable through separate commits.

---

Architecture

e2e/
├── vitest.e2e.config.ts
├── setup.ts
├── config.ts
├── reporter.ts
├── shim/
│   ├── obsidian.ts
│   └── fake-vault.ts
├── providers/
│   ├── provider-adapter.ts
│   ├── github-adapter.ts
│   ├── gitlab-adapter.ts
│   └── gitea-adapter.ts
├── provision/
│   ├── sandbox.ts
│   ├── github-sandbox.ts
│   ├── gitlab-sandbox.ts
│   └── gitea-sandbox.ts
├── suites/
│   ├── service-contract.e2e.test.ts
│   ├── sync-manager.e2e.test.ts
│   └── github-symlink.e2e.test.ts
└── fixtures/
    ├── text.ts
    └── binary.ts

scripts/
├── e2e-gitea-up.sh
├── e2e-gitea-down.sh
└── e2e-sweep-branches.mjs

docs/testing/
└── real-provider-e2e.md

NPM scripts:

{
  "test:e2e": "vitest run --config e2e/vitest.e2e.config.ts",
  "test:e2e:smoke": "vitest run --config e2e/vitest.e2e.config.ts --testNamePattern='@smoke'",
  "test:e2e:full": "vitest run --config e2e/vitest.e2e.config.ts"
}

The E2E suite must use a separate Vitest config so the current mocked obsidian module and mocked requestUrl from tests/setup.ts cannot leak into real-provider tests.

---

Load-bearing Obsidian shim

e2e/shim/obsidian.ts wraps native fetch and reproduces the requestUrl response contract expected by BaseGitService.safeRequest().

Required behavior:

• HTTP 4xx/5xx returns a response and does not throw automatically;
• only DNS/TLS/timeout/network failures throw;
• returns { status, headers, text, json, arrayBuffer };
• header names are normalized to lowercase;
• body bytes are read once and exposed as text/arrayBuffer;
• json is a lazy getter and throws when the body is not JSON;
• defines window.setTimeout, required by GitHub stale-head retry logic;
• sanitizes tokens before any failure is printed.

The suite must import the existing production service files. It must not reimplement GitHub/GitLab/Gitea request logic in the test harness.

---

Environments

GitHub

Use a dedicated sandbox repository, e.g.:

firstsun-dev/git-files-sync-e2e

Use a fine-grained PAT restricted to that one repository with Contents read/write. Do not write E2E branches into the plugin repository and do not reuse a broad organization token.

GitLab

Use a dedicated gitlab.com sandbox project with a project access token:

• scope: api;
• role: Developer or Maintainer;
• project restricted to the E2E sandbox.

write_repository alone is insufficient because GitLabService uses the REST API rather than Git-over-HTTP.

Gitea

Run a pinned Gitea container in CI and locally, initially:

docker.gitea.com/gitea:1.27.0

Provision at runtime:

1. wait for /api/v1/version;
2. create an admin test user;
3. generate an access token;
4. create an initialized repository;
5. execute tests;
6. destroy the container.

Gitea requires no stored repository secret and can therefore run on fork PRs.

---

Configuration and secret handling

Local and CI runs use the same file-based configuration:

{
  "github": {
    "owner": "firstsun-dev",
    "repo": "git-files-sync-e2e",
    "tokenFile": ".e2e/secrets/github.token"
  },
  "gitlab": {
    "baseUrl": "https://gitlab.com",
    "projectId": "<project-id>",
    "tokenFile": ".e2e/secrets/gitlab.token"
  },
  "gitea": {
    "baseUrl": "http://127.0.0.1:3000",
    "owner": "e2e",
    "repo": "git-files-sync-e2e",
    "tokenFile": ".e2e/secrets/gitea.token"
  }
}

Rules:

• add .e2e/ to .gitignore;
• no token CLI arguments;
• test code does not directly read provider tokens from process.env;
• CI masks each token before writing a chmod 600 token file;
• reporter redacts every configured token substring;
• request headers and secret-bearing bodies are never uploaded as artifacts;
• each CI job receives --require-provider=<provider> and fails if zero tests execute;
• a missing required secret is an explicit failure, never a silent skip/green result.

---

Sandbox lifecycle and concurrency

Each test job creates its own branch:

e2e-github-<run-id>-<attempt>
e2e-gitlab-<run-id>-<attempt>
e2e-gitea-<run-id>-<attempt>

Initial implementation deliberately avoids / in branch names because provider branch-path encoding should be tested separately rather than making the whole harness depend on it.

Lifecycle:

read seed/default head
  -> create ephemeral branch
  -> provision fixtures with raw provider API
  -> execute production service / SyncManager
  -> independently verify remote state
  -> delete branch in finally

Cleanup guarantees:

• afterAll plus outer try/finally teardown;
• startup sweeper removes e2e-* branches older than 24 hours;
• E2E_KEEP_BRANCH=1 retains a failing branch for debugging;
• tests within one provider run serially;
• GitHub, GitLab, and Gitea jobs may run in parallel.

---

Independent verification

A service must never validate its own write using its own getFile() or listFilesDetailed() implementation.

Provider adapters use raw API calls to verify:

• branch head before and after;
• exact commit-count delta;
• remote tree paths;
• raw blob content and binary bytes;
• file modes, including 120000 symlinks;
• old path removal and new path creation for moves;
• blob SHA cross-check using gitBlobSha.

This prevents symmetric write/read bugs from passing the test.

---

Service-contract matrix

Smoke tier — every relevant internal PR

Run for all three providers unless marked otherwise:

• testConnection: valid branch and missing branch;
• pushFile: create UTF-8/CJK content;
• getFile: real round-trip;
• pushFile: update an existing file using the current SHA;
• missing file returns { content: '', sha: '' };
• listFilesDetailed: path and SHA are correct;
• getBlob: content and SHA are correct;
• pushBatch: mixed create/update and exactly one new commit;
• commitBatch: real move, old path gone, new path exists, one commit;
• deleteFile: file is gone remotely;
• deleteBatch: all files gone and exactly one new commit;
• rootPath: writes and filtered listing stay inside the configured root;
• batch result returns usable SHA values where the interface/provider supports them.

Provider-specific smoke cases:

GitHub

• GraphQL createCommitOnBranch succeeds against the real API;
• HTTP 200 with GraphQL errors[] is surfaced as an exception;
• pushSymlink creates tree mode 120000 and the expected target;
• GitLab/Gitea expose no pushSymlink capability.

GitLab

• create vs update actions behave correctly;
• move uses the Commits API move action and correct previous path.

Gitea

• branch -> commit resolution works;
• blob -> tree -> commit -> ref flow works;
• batch deletion through null tree entries works.

Full tier — main, manual dispatch, scheduled API-drift run

• binary push/pull byte identity;
• paths containing spaces, CJK, #, +, and nested directories;
• stale SHA update conflict;
• atomic batch failure leaves the remote tree unchanged;
• approximately 30-file batch for payload/concurrency behavior;
• non-existent path inside deleteBatch with provider behavior pinned down;
• GitHub immediate push-then-delete stale-head retry;
• GitLab pagination;
• .gitignore retrieval;
• branch names containing / as an explicit encoding regression case.

---

SyncManager real-provider E2E

The first PR includes six high-value scenarios using an in-memory fake Vault and a real provider service:

1. Push new file

   • remote file exists;
   • syncMetadata.lastSyncedSha records the real remote SHA.

2. Push unchanged file

   • second push is skipped;
   • remote commit count does not change.

3. Pull remote update

   • raw provider API changes the remote file;
   • SyncManager.pullFile() updates the Vault and metadata.

4. Conflict protection

   • both local and remote change after the last sync;
   • push must not silently overwrite the remote;
   • metadata must not be falsely marked synced.

5. Rename / move

   • call trackRename(oldPath, newPath);
   • push removes the old remote path and creates the new one;
   • exactly one commit is created.

6. Batch push-all path

   • multiple Vault files are pushed through the batch-capable path;
   • all remote files are correct;
   • exactly one commit is created for the batch.

Additional conflict-modal choices, complete gitignore interaction, chunk-boundary stress, and every symlink mode stay out of this first PR unless implementation is unexpectedly small.

---

CI wiring

Add jobs to the existing .github/workflows/ci.yml:

changes
├── e2e-gitea
├── e2e-github
└── e2e-gitlab
        ↓
       CI (reusable workflow, including release)

Triggers:

• internal PR touching sync/provider paths: Gitea + GitHub + GitLab smoke;
• fork PR: Gitea smoke only;
• push to main: all three full tier;
• workflow_dispatch: choose provider/tier/keep-branch;
• weekly schedule: all three full tier for API-drift detection.

Relevant path filter:

src/services/**
src/logic/sync-manager.ts
src/utils/git-blob-sha.ts
src/utils/path.ts
src/utils/symlink.ts
e2e/**
package.json
package-lock.json
.github/workflows/ci.yml

Release gating

The current shared reusable workflow performs semantic release internally. Therefore the E2E jobs must run before the caller invokes the reusable CI job.

The CI job should needs the three E2E jobs and allow only successful or intentionally skipped provider jobs. This ensures a real-provider failure blocks the shared workflow and release rather than becoming a post-release canary.

Gitea should become the required E2E status check because it runs without secrets and works on fork PRs. GitHub/GitLab checks should remain non-required at branch-protection level so fork PRs cannot be wedged by unavailable secrets; internal PR release gating still depends on them through workflow job dependencies.

---

Commit breakdown inside the single PR

1. test(e2e): add real requestUrl shim and secure config loader
2. test(e2e): add provider sandboxes and service contract suite
3. test(e2e): add SyncManager real-provider scenarios
4. ci(e2e): run provider checks before shared CI and release
5. docs(e2e): document setup credentials cleanup and troubleshooting

---

Acceptance criteria

• existing lint, build, and unit tests remain green;
• Gitea provisions from a clean container without manual setup;
• GitHub, GitLab, and Gitea smoke suites each pass twice consecutively;
• pushBatch, commitBatch, and deleteBatch prove one-commit behavior;
• every remote assertion uses the independent verifier;
• no current-run branch remains after a successful run;
• a cancelled/crashed run is cleaned by the next sweeper;
• missing credentials cannot produce a zero-test green job;
• CI logs and uploaded artifacts contain no token value;
• fork PRs can complete the required Gitea check;
• a required provider E2E failure prevents the reusable CI/release workflow from starting;
• docs/testing/real-provider-e2e.md includes local setup, CI setup, cleanup, and failure investigation instructions.

---

Explicit non-goals for this PR

• full Obsidian desktop UI automation;
• exhaustive modal interaction testing;
• hundreds/thousands of file load testing;
• a large Gitea version compatibility matrix;
• production monitoring or alerting for sandbox failures;
• refactoring provider APIs unrelated to enabling E2E.

Those can follow once the core real-provider harness is stable.

[ClaudiaFang]

Backlog priority review — 2026-08-04

Priority: P1

Reason: Mock tests cannot verify real provider API semantics, and a live test has already caught production-relevant behavior. This is a reliability and credential-handling guardrail for every future push/pull/delete change.

Scheduling note: Build the repeatable local smoke-test harness before adding another provider or materially changing provider services. Keep credentials file-based and out of agent transcripts, and document cleanup of disposable test data.