Metadata-Version: 2.4
Name: archelps
Version: 0.1.1
Summary: Arc CLI: connect Git repositories to Arc Items 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
Requires-Dist: click<9,>=8.1
Requires-Dist: certifi>=2026.6.17
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: jsonschema>=4; extra == "test"
Dynamic: license-file

# Arc CLI

Arc CLI's Connect commands record literal Arc Item markers in Git and upload file/line
locations to Arc. It uses Python 3.11 or later and Click, with plain terminal prompts. The
standalone package is MIT licensed; Arc's application/backend licence is unchanged.

```sh
python -m pip install --upgrade archelps
arc connect init
```

Setup and generated CI use the latest published package without a version
constraint. `--upgrade` also updates an existing installation.

The executable is `arc`. Connect groups the existing Git workflow under
`arc connect init`, `arc connect scan` and `arc connect upload`; `arc logout`
clears the saved sign-in. Setup handles browser sign-in. There is no separate
login command or general API command group.

Run setup in an interactive terminal inside a GitHub.com or GitLab.com repository.
Self-hosted GitLab is not currently supported.
Sign in through Cognito in the browser, then return to the terminal. Choose one
Organization and one or more Programs by name or number; confirm each Program's
repository-specific marker label immediately after selection. Existing registered
labels are frozen and reused. Confirm the repository/default branch, then choose
GitHub Actions, GitLab CI or other CI independently of the repository host. Declining
repository confirmation cancels setup; rerun with `--repository-url` and
`--default-branch` to correct it.

Setup writes secrets-free `.arc/config.json` with `schema_version`, `api_url`,
`organization_id`, `git`, `ci`, `programs` and `marker_instructions`. `git` contains
provider, canonical repository URL and default branch. Each Program entry contains
`program_id`, frozen `label`, `source_id` and `token_env` (`ARC_TOKEN_<LABEL>`).
Custom setup configuration paths must stay inside the repository for CI. Commit
the configuration and generated CI file, including the config if Git ignore rules
exclude it. Setup creates no hooks, tracked mapping/data file or customer README.

## Credentials and recovery

Setup automatically creates one personal write token per Program/source through
the OAuth-only `POST /programs/{program_id}/code-links/sources/{source_id}/token`
route. Source setup requires `program.manage`; token issuance also requires
`program.edit` and the normal personal-token membership/MFA rules. Write mode does
not grant Program permissions. Uploads recheck current authority.

Returned secrets are saved outside the repository in a private
`~/.arc-connect/ci-<hash>.json`, partitioned by checkout, API target and signed-in
account. The CLI prints only that path and CI secret names. Read the private file
and paste each value into its named CI secret or masked/protected variable, such
as `ARC_TOKEN_BRAKES`. Upload reads these environment variables; it does not read
the private handoff file.

Repeated init reuses saved settings and local credentials. A secrets-free draft
under Git's private metadata preserves selected Programs/labels during interrupted
registration. Configuration is saved before token issuance/CI generation. If an
existing server token has no local copy, setup requires an explicit replacement
choice; declining preserves it. `arc connect init --replace-tokens` deliberately
revokes and replaces only the current user's configured source tokens. Update CI
secrets afterward. No setup mutation is automatically retried after an uncertain
response.

Use `arc connect init --reconfigure` to choose Organization, Programs, repository
or CI again. An explicit API target conflicting with saved setup fails before
authentication unless reconfiguration is requested. Repeating init reconnects a
removed source through the existing source service. Superseded hooks/root files
have no compatibility path and are not deleted automatically.

Cognito credentials are cached separately at `~/.arc-connect/tokens.json`, with
private permissions, PKCE S256, state validation and domain/client/resource/scope
binding. Redirects do not receive bearer credentials. An expired refresh credential
reopens sign-in. `arc logout` clears a corrupt cache or revokes the cached
refresh token and removes the cache; it warns when revocation cannot be confirmed.
Issued access tokens can remain valid for up to 15 minutes. Personal CI tokens
remain separately managed.

HTTPS uses Python's default trusted certificates plus certifi's bundled roots.
An explicit `SSL_CERT_FILE` or `SSL_CERT_DIR` selects only that configured trust
store. Certificate errors retain saved credentials and stop with a clear error;
they do not reopen sign-in or retry uploads. Certificate and hostname checks stay enabled.

Production defaults are 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 audience/scope resource
`https://arc5-api.onrender.com/api/v1/public`. Transport and audience are distinct.
Use `--api-url`, `--cognito-domain`, `--client-id`, `--resource` and `--cache` for
another environment. `ARC_API_URL`, `ARC_COGNITO_DOMAIN`, `COGNITO_API_CLIENT_IDS`
and `ARC_API_RESOURCE` are also supported. Custom OAuth cache paths must remain
outside Git; the CI handoff is saved beside that cache.

## Literal markers and scanning

Copy the real marker from an Arc Item and place it near associated code or tests:

```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 literal marker are preserved;
several markers can share a line. Unicode word characters and hyphens prevent
matches embedded in longer identifiers. Never invent identifiers or substitute
import identifiers. Coding agents can read `.arc/config.json` for configured labels
and marker guidance. A code link is not proof that an Item's obligation is met.

`arc connect scan` prints deterministic schema `1.0.0` JSON from one exact `HEAD` commit
without writing files or changing the index. Sequential Git search scans tracked
regular text; binary/LFS/submodule/symlink payloads, `.arc/` and a custom config
path are excluded. There is no AI, language parser, concurrency or incremental
cache. Git failures never produce successful empty reports. `--repo` selects a
checkout and `--config` a secrets-free configuration path relative to its Git root;
Connect's common options are accepted before or after its `init`, `scan` or
`upload` subcommand.

## CI reports

GitHub Actions generates `.github/workflows/arc.yml`: a separate default-branch
push workflow that checks out the exact event SHA, installs the latest published
package and runs `arc connect upload` with `continue-on-error: true`.

GitHub, GitLab and other-CI instructions all install with
`python -m pip install --upgrade archelps`, without a version constraint.

GitLab CI generates `.arc/gitlab-ci.yml`; append the printed include to your
existing `.gitlab-ci.yml`, merging with existing includes:

```yaml
include:
  - local: '/.arc/gitlab-ci.yml'
```

Select GitLab CI during setup, or run `arc connect init --ci gitlab`. In the
GitLab project, open **Settings → CI/CD → Variables** and add each named
`ARC_TOKEN_<LABEL>` from the private handoff file as a masked variable. Use
protected variables only when the configured default branch is protected.
Commit `.arc/config.json`, `.arc/gitlab-ci.yml`, the include and your Item markers,
then push to that branch. A runner must be available. Check the `arc` job's upload
output, then Arc's **Last sync** and the Item's **Code links**; the job allows
failure, so a successful overall pipeline does not prove the upload succeeded.

Its job uses default-branch push rules with `when: always`, stage `.post` and
`allow_failure: true`, so earlier job failures do not skip it. Global workflow
rules must still allow that pipeline to be created. Existing customer files and
symlinks are preserved; setup prints generated content for manual insertion when
needed and never rewrites the customer's GitLab pipeline. Changing CI removes only
Arc-generated files for the other CI choice and prints a reminder to remove an
obsolete GitLab include.

Other CI receives exact-checkout, secret and nonblocking-step instructions. After
checking out the exact event commit, pass the commit and branch together for a
detached checkout, using your CI's actual event variables:

```sh
arc connect upload --commit-sha "$YOUR_CI_COMMIT_SHA" --branch "$YOUR_CI_BRANCH"
```

Configure the step to allow failure. GitHub/GitLab events are checked automatically;
a mismatched checkout fails before sending and other branches skip. Keep CI token
names from `.arc/config.json` and do not expose tokens to pull-request pipelines.

Upload scans one pinned commit and generates JSON in memory. One complete data
format, `schema_version: "1.0.0"`, contains the full `commit_sha`, `scanner_version`
and `git` repository identity with Program UUID/label marker locations. Each
Program is sent separately through its own token to
`POST /api/v1/public/programs/{program_id}/code-links/sources/{source_id}/reports`.
Reports are bounded to 32 MiB and 500,000 locations. Network, 429 and 5xx failures
use at most three total attempts with identical bodies; other API failures do not
retry. Missing/failed tokens do not prevent remaining Program uploads; the direct
command returns nonzero if any fail while generated CI remains nonblocking.

`data.schema.json` describes both scan output and uploads; there is no nested report
wrapper. Scan output can contain all configured Programs; each upload contains
exactly one Program matching its token and route. Config's independent
`schema_version` remains integer `1`, and the CLI package version is `0.1.1`.
Future data-schema releases must deploy server acceptance before publishing a CLI
that sends the new format. The current data schema remains `1.0.0`; no compatibility
implementation is added by this release policy.
No source text or secrets are uploaded. Arc retains five report bodies
and resolved projections, with older deduplication receipts. Invalid/failed reports
preserve current links; complete empty reports clear them. Duplicate retries never
promote old reports. Removal hides links and disables uploads; identical source
reconnection restores the retained current report. These links do not create Item
revisions or appear in historic model views.

## Development

```sh
python -m pip install '.[test]'
# Run only tests created or edited for the current change; for example:
python -m pytest --confcutdir=. tests/test_setup.py::test_noninteractive_init_does_not_open_browser
python -m build
```

The standalone `archelps` package root maps the existing `arc_connect` Python
module to this directory and does not package the Arc backend or its dependencies.
Click and certifi are the runtime dependencies. The internal module name and private
`~/.arc-connect` credential location are unchanged.
