archelps 0.1.1__py3-none-any.whl

arc_connect/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.

arc_connect/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.

arc_connect/__init__.py

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

arc_connect/__main__.py

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

arc_connect/cli.py

@@ -0,0 +1,148 @@
+"""Arc CLI with interactive Connect setup and unattended exact-commit reporting."""
+
+from __future__ import annotations
+
+from argparse import Namespace
+from pathlib import Path
+import sys
+
+import click
+
+from . import __version__, config, onboarding as setup, scanner, upload
+
+
+def _common(function):
+    for name, help_text in (
+        ("repo", "Git repository directory (default: current directory)"),
+        ("config", "Secrets-free config path, relative to Git root"),
+        ("api-url", "API transport ending in /api/v1/public"),
+        ("cognito-domain", "Cognito Managed Login HTTPS origin"),
+        ("client-id", "Public Cognito API client ID"),
+        ("resource", "Cognito API audience and scope resource"),
+        ("cache", "Private OAuth cache outside the repository"),
+    ):
+        function = click.option("--" + name, default=None, help=help_text)(function)
+    return function
+
+
+def _arguments(context, values):
+    result = {
+        **context.parent.params,
+        **{key: value for key, value in values.items() if value is not None},
+    }
+    result["config"] = result.get("config") or config.CONFIG_NAME
+    return Namespace(**result)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="arc")
+def app():
+    """Arc CLI."""
+
+
+@app.group()
+@_common
+def connect(**_options):
+    """Connect literal Arc Item markers in Git to Arc Programs."""
+
+
+@connect.command()
+@_common
+@click.option("--provider", type=click.Choice(["github", "gitlab"]))
+@click.option("--repository-url", help="Repository HTTPS URL (otherwise origin)")
+@click.option("--default-branch", help="Repository default branch")
+@click.option("--ci", type=click.Choice(["github", "gitlab", "other"]))
+@click.option("--reconfigure", is_flag=True, help="Choose Organization, Programs and CI again")
+@click.option(
+    "--replace-tokens", is_flag=True, help="Revoke and replace this user's configured source tokens"
+)
+@click.pass_context
+def init(context, **values):
+    """Sign in, choose Programs and generate CI configuration."""
+    args = _arguments(context, values)
+    root = scanner.repository_root(Path(args.repo or Path.cwd()))
+    setup.initialize(root, args)
+
+
+@connect.command()
+@_common
+@click.pass_context
+def scan(context, **values):
+    """Print JSON from exact HEAD without modifying any files."""
+    args = _arguments(context, values)
+    root, value, excluded = _configured(args)
+    sha = scanner.git(root, "rev-parse", "--verify", "HEAD^{commit}").decode().strip()
+    click.echo(
+        scanner.mapping_bytes(
+            scanner.scan_repository(root, value, revision=sha, excluded_paths=excluded)
+        ).decode(),
+        nl=False,
+    )
+
+
+@connect.command("upload")
+@_common
+@click.option("--commit-sha", help="Exact checked-out CI commit (use with --branch)")
+@click.option("--branch", help="CI branch name (use with --commit-sha)")
+@click.pass_context
+def upload_command(context, commit_sha, branch, **values):
+    """Scan exact HEAD and upload on the configured default branch."""
+    args = _arguments(context, values)
+    root, value, excluded = _configured(args)
+    code = upload.upload_reports(
+        root, value, excluded_paths=excluded, commit_sha=commit_sha, branch=branch
+    )
+    if code:
+        raise click.exceptions.Exit(code)
+
+
+@app.command()
+@_common
+@click.pass_context
+def logout(context, **values):
+    """Revoke and remove the private OAuth sign-in cache."""
+    args = _arguments(context, values)
+    try:
+        root = scanner.repository_root(Path(getattr(args, "repo", None) or Path.cwd()))
+    except ValueError:
+        root = None
+    setup.logout(args, root)
+
+
+def _configured(args):
+    root = scanner.repository_root(Path(args.repo or Path.cwd()))
+    path = config.config_path(root, args.config)
+    value = config.read_config(path)
+    if args.api_url:
+        value = {**value, "api_url": config.validate_api_url(args.api_url)}
+    excluded = (str(path.relative_to(root)),) if path.is_relative_to(root) else ()
+    return root, value, excluded
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    try:
+        result = app.main(args=argv, prog_name="arc", standalone_mode=False)
+        return result if isinstance(result, int) else 0
+    except click.exceptions.Exit as exc:
+        return exc.exit_code
+    except click.ClickException as exc:
+        exc.show()
+        return exc.exit_code
+    except (OSError, ValueError) as exc:
+        click.echo(f"arc: {exc}", err=True)
+        return 1
+    except (click.Abort, KeyboardInterrupt, EOFError):
+        command = next(
+            (arg for arg in argv if arg in connect.commands or arg == "logout"), "operation"
+        )
+        if command == "init":
+            message = (
+                "Arc setup cancelled. Run arc connect init to resume saved Programs and labels."
+            )
+        elif command == "logout":
+            message = "Sign-out cancelled. Run arc logout to retry."
+        else:
+            message = "Arc operation cancelled."
+        click.echo(message, err=True)
+        return 130

arc_connect/config.py

@@ -0,0 +1,180 @@
+"""Small, secrets-free repository configuration."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+import unicodedata
+from urllib.parse import urlsplit
+import uuid
+
+from .contract import canonical_repository, validate_git
+from .scanner import git
+
+CONFIG_NAME = ".arc/config.json"
+MARKER_INSTRUCTIONS = "Use ARC-<PROGRAM_LABEL>-<ITEM_IDENTIFIER> near relevant code or tests. Copy real identifiers from Arc; never invent them."
+
+
+def suggest_label(name: str) -> str:
+    words = re.findall(
+        r"[A-Z0-9]+", unicodedata.normalize("NFKD", name).encode("ascii", "ignore").decode().upper()
+    )
+    value = "_".join(words) or "PROGRAM"
+    if not value[0].isalpha():
+        value = "PROGRAM_" + value
+    return value[:32].rstrip("_")
+
+
+def _uuid(value: object, name: str) -> str:
+    try:
+        result = str(uuid.UUID(value))
+    except (ValueError, AttributeError, TypeError) as exc:
+        raise ValueError(f"{name} must be a canonical UUID.") from exc
+    if result != value:
+        raise ValueError(f"{name} must be a canonical UUID.")
+    return result
+
+
+def validate_api_url(value: object) -> str:
+    if not isinstance(value, str):
+        raise ValueError("API URL must end in /api/v1/public.")
+    try:
+        parsed = urlsplit(value)
+        port = parsed.port
+        if (
+            parsed.scheme not in {"https", "http"}
+            or not parsed.hostname
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+            or parsed.path != "/api/v1/public"
+            or (port is not None and not 1 <= port <= 65535)
+            or (
+                parsed.scheme == "http" and parsed.hostname not in {"localhost", "127.0.0.1", "::1"}
+            )
+            or any(character.isspace() for character in value)
+        ):
+            raise ValueError()
+    except ValueError as exc:
+        raise ValueError(
+            "Use an HTTPS API URL ending in /api/v1/public (HTTP only on localhost)."
+        ) from exc
+    return value
+
+
+def validate_branch(value: object) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or len(value) > 255
+        or value.startswith(("-", "/", "."))
+        or value.endswith(("/", ".", ".lock"))
+        or any(character.isspace() or ord(character) < 32 for character in value)
+        or any(character in "~^:?*[\\" for character in value)
+        or ".." in value
+        or "@{" in value
+        or "//" in value
+        or value == "@"
+        or any(part.startswith(".") or part.endswith(".lock") for part in value.split("/"))
+    ):
+        raise ValueError("Use a valid Git default branch name.")
+    return value
+
+
+def validate_config(value: object, *, allow_pending: bool = False) -> dict:
+    if not isinstance(value, dict) or set(value) != {
+        "schema_version",
+        "api_url",
+        "organization_id",
+        "git",
+        "programs",
+        "ci",
+        "marker_instructions",
+    }:
+        raise ValueError("Invalid Arc configuration fields; never store tokens in this file.")
+    if type(value["schema_version"]) is not int or value["schema_version"] != 1:
+        raise ValueError("Unsupported Arc configuration version.")
+    if not isinstance(value["ci"], str) or value["ci"] not in {"github", "gitlab", "other"}:
+        raise ValueError("Choose GitHub Actions, GitLab CI or other CI.")
+    if (
+        not isinstance(value["marker_instructions"], str)
+        or not 1 <= len(value["marker_instructions"]) <= 2000
+    ):
+        raise ValueError("Include concise marker instructions.")
+    validate_api_url(value["api_url"])
+    _uuid(value["organization_id"], "Organization ID")
+    repo = value["git"]
+    if not isinstance(repo, dict) or set(repo) != {"provider", "repository_url", "default_branch"}:
+        raise ValueError("Invalid Git configuration fields.")
+    validate_branch(repo["default_branch"])
+    if not isinstance(value["programs"], list):
+        raise ValueError("Configure at least one Program.")
+    mapping_programs = []
+    for program in value["programs"]:
+        if not isinstance(program, dict) or set(program) != {
+            "program_id",
+            "label",
+            "source_id",
+            "token_env",
+        }:
+            raise ValueError(
+                "Invalid Program configuration fields; tokens belong in environment variables."
+            )
+        if program["source_id"] is not None or not allow_pending:
+            _uuid(program["source_id"], "Source ID")
+        if program["token_env"] != "ARC_TOKEN_" + str(program["label"]):
+            raise ValueError("Token environment variable must be ARC_TOKEN_<LABEL>.")
+        mapping_programs.append(
+            {"program_id": program["program_id"], "label": program["label"], "links": {}}
+        )
+    validate_git(
+        {
+            "provider": repo["provider"],
+            "repository_url": repo["repository_url"],
+            "programs": mapping_programs,
+        }
+    )
+    return value
+
+
+def read_config(path: Path) -> dict:
+    if path.is_symlink():
+        raise ValueError("Arc configuration cannot be a symlink.")
+    try:
+        return validate_config(json.loads(path.read_text(encoding="utf-8")))
+    except FileNotFoundError as exc:
+        raise ValueError("No Arc configuration found. Run arc connect init.") from exc
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(
+            "Could not read .arc/config.json. Restore the configuration or run init."
+        ) from exc
+
+
+def config_path(root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else root / path
+
+
+def discover_repository(root: Path) -> dict[str, str]:
+    remote = git(root, "remote", "get-url", "origin").decode("utf-8").strip()
+    if match := re.fullmatch(r"git@(github\.com|gitlab\.com):(.+)", remote):
+        remote = "https://" + match[1] + "/" + match[2]
+    elif remote.startswith("ssh://git@"):
+        parsed = urlsplit(remote)
+        remote = "https://" + str(parsed.hostname) + parsed.path
+    host = urlsplit(remote).hostname
+    provider = {"github.com": "github", "gitlab.com": "gitlab"}.get(host)
+    if provider is None:
+        raise ValueError(
+            "Origin must point to GitHub.com or GitLab.com; provide --repository-url and --provider."
+        )
+    repository_url = canonical_repository(remote, provider)
+    reference = (
+        git(root, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD", allowed=(0, 1))
+        .decode()
+        .strip()
+    )
+    branch = reference.removeprefix("refs/remotes/origin/") if reference else ""
+    return {"provider": provider, "repository_url": repository_url, "default_branch": branch}