Metadata-Version: 2.4
Name: arc-connect
Version: 0.1.0
Summary: Deterministic Git-to-Arc Item links using literal source markers
Author: Arc
License-Expression: MIT
Project-URL: Homepage, https://archelps.com
Project-URL: Documentation, https://app.archelps.com/api-guide
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: jsonschema>=4; extra == "test"
Dynamic: license-file

# 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.

```sh
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:

```sh
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:

```python
# 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:

```yaml
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:

```yaml
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

```sh
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.
