archelps 0.1.1__tar.gz

archelps-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archelps-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md LICENSE data.schema.json
+recursive-include tests *.py
+recursive-include tests/tls *.pem

archelps-0.1.1/PKG-INFO

@@ -0,0 +1,224 @@
+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.

archelps-0.1.1/README.md

@@ -0,0 +1,200 @@
+# 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.

archelps-0.1.1/__init__.py

@@ -0,0 +1,3 @@
+"""Metadata-only, deterministic Arc code links for Git repositories."""
+
+__version__ = "0.1.1"

archelps-0.1.1/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())