Metadata-Version: 2.4
Name: mirrorcommons
Version: 0.5.2
Summary: CLI for Mirror Commons: create continuity manifests for external AI artifacts and publish reviewed community mirrors.
Author: Mirror Commons
License-Expression: MIT
Project-URL: Homepage, https://mirrorcommons.com
Project-URL: Source, https://github.com/Hashem-Al-Qurashi/mirrorcommons-cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface_hub>=0.30
Provides-Extra: s3
Requires-Dist: boto3>=1.35; extra == "s3"
Dynamic: license-file

# ArtifactGrid CLI

`mirrorcommons` is the public-facing command alias for this package; `artifactgrid` remains available for continuity-report compatibility. The same CLI powers Mirror Commons publisher submissions and ArtifactGrid private continuity reports.

This local-first CLI creates a private Consumer Continuity Report for a third-party public Hugging Face dependency. It can download an exact pinned revision or validate a snapshot you already hold. ArtifactGrid does not receive cloud credentials or host model weights.

Supported V1 files are `.safetensors`, `.json`, `.md`, `.txt`, and `.model`, plus a root `LICENSE` file. If a root `LICENSE`, `LICENSE.md`, or `LICENSE.txt` is present, the manifest records its path and SHA-256 as a factual observation. This is not a legal review. Symlinks and unsupported formats are deliberately skipped; ArtifactGrid never loads model code or unsafe serialized formats.

## Run locally

```bash
cd cli
python3 -m pip install -e .
artifactgrid inspect \
  --source-url https://huggingface.co/owner/repository \
  --revision <full-40-character-commit> \
  --download
```

For a public Mirror Commons submission, use the identical command with the `mirrorcommons` alias:

```bash
mirrorcommons publish create --help
```

The local workflow needs no cloud-storage package. Install the optional S3 support only when using S3 or R2:

```bash
python3 -m pip install -e '.[s3]'
```

Use `--snapshot-dir ./snapshot` instead of `--download` when the customer has already retrieved the pinned snapshot.

With `--download`, ArtifactGrid materializes ordinary files in a temporary directory so Hugging Face cache symlinks and local `.cache` metadata cannot enter the manifest. The CLI removes that temporary directory after `inspect` or `protect` finishes.

Record whether the upstream public source currently resolves to the exact pinned commit. This uses Hugging Face's public API without a user token and does not download model weights:

```bash
artifactgrid source-check \
  --source-url https://huggingface.co/owner/repository \
  --revision <full-40-character-commit> \
  --output ./source-observation.json
```

Create a customer-attested backup in a directory the customer controls:

```bash
artifactgrid protect \
  --source-url https://huggingface.co/owner/repository \
  --revision <full-40-character-commit> \
  --download \
  --backup-dir ./customer-backup \
  --output ./continuity-manifest.json
```

`--output` is optional. It writes a portable copy of the same manifest kept with the customer backup.

Or copy directly into customer-controlled R2/S3. The CLI uses the customer's standard local AWS credential chain or environment variables and never sends them to ArtifactGrid:

```bash
artifactgrid protect \
  --source-url https://huggingface.co/owner/repository \
  --revision <full-40-character-commit> \
  --snapshot-dir ./snapshot \
  --s3-bucket customer-ai-artifacts \
  --s3-prefix artifactgrid/production-model \
  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
  --output ./continuity-manifest.json
```

Verify a recovery copy:

```bash
artifactgrid verify \
  --manifest ./customer-backup/artifactgrid-manifest.json \
  --backup-dir ./customer-backup
```

With scoped read access, verify every protected S3/R2 object directly:

```bash
artifactgrid verify \
  --manifest ./continuity-manifest.json \
  --s3-bucket customer-ai-artifacts \
  --s3-prefix artifactgrid/production-model \
  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com
```

Run a clean restore drill into an empty directory, then produce a private portable report:

```bash
artifactgrid restore \
  --manifest ./customer-backup/artifactgrid-manifest.json \
  --backup-dir ./customer-backup \
  --restore-dir ./restore-drill

artifactgrid report \
  --manifest ./customer-backup/artifactgrid-manifest.json \
  --backup-dir ./customer-backup \
  --restore-result ./restore-drill/artifactgrid-restore-result.json \
  --source-observation ./source-observation.json \
  --output ./continuity-report.html
```

`--source-observation` is optional. When provided, ArtifactGrid accepts it only when it proves that the same repository and exact pinned revision were reachable at the recorded time.

You can run the same clean recovery drill directly from customer-controlled R2/S3. The CLI first streams and checksum-verifies every declared object, then restores the allowlisted files into the empty destination and rechecks the restored copy:

```bash
artifactgrid restore \
  --manifest ./continuity-manifest.json \
  --s3-bucket customer-ai-artifacts \
  --s3-prefix artifactgrid/production-model \
  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
  --restore-dir ./restore-drill
```

Generate the private report directly from that same verified S3/R2 copy. Add `--restore-result ./restore-drill/artifactgrid-restore-result.json` after running the drill to include its outcome:

```bash
artifactgrid report \
  --manifest ./continuity-manifest.json \
  --s3-bucket customer-ai-artifacts \
  --s3-prefix artifactgrid/production-model \
  --s3-endpoint-url https://<account-id>.r2.cloudflarestorage.com \
  --source-observation ./source-observation.json \
  --output ./continuity-report.html
```

`customer_attested` means the CLI copied and immediately verified the listed files in customer-controlled storage. It is not an ArtifactGrid independently verified storage claim. A Consumer Continuity Report never asserts repository control, publisher ownership, or redistribution legality.

## Commons publisher workflow

The same control plane powers the web contributor workspace and the CLI. This CLI does not save a token; obtain a short-lived token from the configured production sign-in flow and supply it only through your current shell:

```bash
export ARTIFACTGRID_TOKEN='<short-lived-token>'

artifactgrid publish create \
  --slug acme-model \
  --display-name 'Acme Model' \
  --declared-license apache-2.0 \
  --origin source_mirror \
  --source-url https://huggingface.co/acme/model \
  --revision <full-40-character-commit>

artifactgrid publish source-challenge --draft <mirror-id>
# Commit the returned JSON token to .artifactgrid/controller.json at that exact revision.
artifactgrid publish verify-source --draft <mirror-id>

artifactgrid publish inspect \
  --snapshot-dir ./model \
  --slug acme-model \
  --origin source_mirror \
  --source-control official_source_controller_verified \
  --source-url https://huggingface.co/acme/model \
  --revision <full-40-character-commit> \
  --output ./publisher-mirror-manifest.json

artifactgrid publish upload \
  --draft <mirror-id> \
  --manifest ./publisher-mirror-manifest.json \
  --snapshot-dir ./model

artifactgrid publish status --draft <mirror-id>
```

To propose a third-party model as a **community mirror**, use the same pinned source details but do not run a controller challenge. The resulting record truthfully says that upstream repository control is not claimed; it stays private until review decides whether it is eligible for the Commons.

```bash
artifactgrid publish create \
  --slug community-model \
  --display-name 'Community Model' \
  --declared-license apache-2.0 \
  --origin community_mirror \
  --source-url https://huggingface.co/vendor/model \
  --revision <full-40-character-commit>

artifactgrid publish inspect \
  --snapshot-dir ./model \
  --slug community-model \
  --origin community_mirror \
  --source-control not_claimed \
  --source-url https://huggingface.co/vendor/model \
  --revision <full-40-character-commit> \
  --output ./publisher-mirror-manifest.json
```

For original work, use `--origin original_creator_submission` and `--source-control not_applicable`, without a third-party source URL or revision. It is intentionally labeled as an original-creator submission, not as repository-controller verified.

`publish upload` obtains only short-lived per-file R2 PUT URLs from ArtifactGrid, streams the declared files to its private staging prefix, and then submits the staging inventory for review. A completed upload becomes `review_required`; it is never automatically public.

Configured reviewers use the same short-lived-token mechanism for the explicit two-step decision and publication action:

```bash
artifactgrid review decision --case <review-case-id> --decision approved
artifactgrid review publish --mirror <mirror-id>
```

`review publish` copies an approved staged version server-side into the versioned public Commons prefix and writes its public manifest. Restricting or rejecting a review case never creates a public model page.
