Arc Connect

Arc Connect records literal Arc Item markers in a Git repository and uploads code locations to Arc. It runs on Python 3.11 or later, uses only the standard library at runtime, and is MIT licensed.

python -m pip install arc-connect==0.1.0
arc-connect init

Run setup inside your GitHub.com or GitLab.com repository. Sign in through Cognito, select your Organization and one or several Programs by name or number, and accept or edit each suggested uppercase Program label. Source registration requires the same program.manage permission as Program settings. Labels are saved and reused when setup is interrupted or repeated. Setup registers sources idempotently; running it again also reconnects a source removed in Arc.

Setup creates arc-connect.json, an initial arc-links.json from staged text, an optional pre-commit integration, dedicated CI, and ARC_CONNECT.md instructions for people and coding assistants. It never stores Program tokens in your repository. Review and stage the generated files yourself. Existing AGENTS.md, CI, managed hooks and unknown hook languages are preserved. If a hook cannot safely be extended, setup prints integration instructions.

Credentials

Setup opens Arc's existing Program Settings → API page. Create a Read and write personal Program token for every configured Program, then set its exact environment variable locally and as a CI secret or masked/protected variable:

export ARC_TOKEN_BRAKES='your-personal-program-token'
export ARC_TOKEN_THERMAL='your-other-program-token'

Use a token owned by a member with program.edit to upload reports; source setup requires program.manage. API write mode does not grant Program permissions. Each token is bound to one Program. A missing or failed token does not prevent reports for other configured Programs. Keep token values out of source control, prompts, command logs and screenshots.

Cognito setup credentials are cached separately at ~/.arc-connect/tokens.json, with private directory and file permissions, PKCE S256, OAuth state validation, scope/configuration binding, and no credential-forwarding redirects. The client in oauth.py is adapted from Arc's examples/arc_api.py with its safeguards preserved. arc-connect logout revokes the cached refresh token and removes the cache. Issued access tokens may remain valid for up to 15 minutes.

Production defaults are the API transport https://api.archelps.com/api/v1/public, Cognito domain https://arc5-production.auth.eu-west-2.amazoncognito.com, public API client 3foiu1p2hb5nm09dc95g5c4m0j, and resource/audience https://arc5-api.onrender.com/api/v1/public. The transport and audience are distinct. Use --api-url, --cognito-domain, --client-id, --resource, and --cache for a different environment. Existing ARC_API_URL, ARC_COGNITO_DOMAIN, COGNITO_API_CLIENT_IDS, and ARC_API_RESOURCE environment values also work. Custom OAuth cache paths must remain outside your Git repository.

Literal markers

Put a marker near code, tests or documentation associated with an existing Arc Item:

# ARC-BRAKES-REQ-001
def stop():
    ...

The syntax is ARC-<PROGRAM_LABEL>-<ITEM_IDENTIFIER>. Labels use uppercase ASCII letters, digits and underscores, start with a letter, and have at most 32 characters. Canonical Item prefixes are SYS, REQ, PROP, TST, TPL, and RSK, followed by at least three digits. Leading zeros and the full literal marker are preserved. Markers can occur anywhere in tracked text and several markers can share a line. Unicode word characters and hyphens prevent matching a marker embedded in a longer identifier. Never invent an Item identifier: obtain the real identifier from Arc or the task's author. Arc resolves unknown identifiers; the CLI does not query Item IDs.

ARC_CONNECT.md contains a prompt for coding assistants. Read it alongside existing repository instructions. Setup does not overwrite AGENTS.md.

Local commits

The managed pre-commit block runs after existing shell-hook formatters finish. It preserves the original hook's success/failure status and runs Arc only after success. Hooks using their own exit traps, exec, a known manager, an unknown interpreter, or a symlink are preserved and receive manual integration instructions. core.hooksPath is respected. For the pre-commit manager, append this local hook after formatters:

repos:
  - repo: local
    hooks:
      - id: arc-connect
        name: Refresh Arc links
        entry: arc-connect hook
        language: system
        pass_filenames: false
        always_run: true

arc-connect hook scans the exact Git index using a single-threaded git grep, rebuilds stable arc-links.json, and stages its exact LF blob alongside the code. It reads no unstaged or untracked source. It ignores symlinks, submodules, binary blobs, LFS pointer blobs, and the root generated map/config/instructions. It uses no language parsers, AI, text conversion filters, timestamps or incremental caches. Each distinct marker/file/line appears once, sorted. Empty Programs remain present so removed markers can clear old locations. Interrupted or failed scans preserve the previous map and index. A failed hook says:

Couldn’t refresh Arc links. Your commit will continue.

Use arc-connect scan to inspect the generated map or arc-connect scan --stage to stage it explicitly. arc-connect scan --head prints a fresh report from the exact HEAD commit without modifying any files. --repo selects another checkout and --config selects another secrets-free config file relative to the Git root. Both options are accepted before or after a command.

CI reports

The generated GitHub workflow .github/workflows/arc-connect.yml runs only on pushes to the configured default branch, checks out the exact event SHA with depth one, installs arc-connect==0.1.0, and invokes arc-connect upload. It uses continue-on-error: true. The dedicated GitLab file .arc-connect.gitlab-ci.yml uses allow_failure: true and a default-branch push rule. Add its include to your existing .gitlab-ci.yml; setup prints this snippet and preserves the existing file:

include:
  - local: '/.arc-connect.gitlab-ci.yml'

CI variables/secrets must use the token names in arc-connect.json. Never expose Program tokens to pull-request pipelines. The generated jobs run on the configured default branch only and the uploader also checks branch and exact CI commit.

Uploads independently scan one pinned HEAD commit; they never trust the tracked mapping. Each Program receives a separate report through its own token at POST /api/v1/public/programs/{program_id}/code-links/sources/{source_id}/reports. The report includes schema version, full commit SHA, scanner version, and exactly one Program mapping. Raw JSON must fit within 32 MiB and 500,000 total file locations. Empty reports are uploaded. Network, 429 and 5xx failures retry at most three times with the same commit/report identity. Other API failures do not retry. Uploads continue for remaining Programs and the direct command returns nonzero if any fail; the generated CI integrations allow that failure so the code pipeline can continue.

The checked-in map contains only stable repository metadata and marker locations; it contains no SHA, timestamps, scanner version, source content or credentials. JSON schemas are distributed as mapping.schema.json and upload.schema.json. Arc owns the server-side Item association and report validation, including tenant, Program, source and current-membership checks.

Development

python -m pip install '.[test]'
python -m pytest --confcutdir=. tests
python -m build

The standalone package root deliberately maps arc_connect to this directory and does not package the Arc backend or its dependencies. Runtime dependencies are empty.