Share

Archie Share — Upload Blueprint for Sharing

Share your architecture blueprint via a URL. Useful for showing teammates, stakeholders, or clients an analysis of your codebase without needing them to install anything.

Prerequisites: Requires .archie/blueprint.json. Run {{COMMAND_PREFIX}}archie-deep-scan first if it doesn't exist.

Update notice (run before anything else, silent unless action needed)

python3 .archie/update_check.py check 2>/dev/null

If output is non-empty:

• UPGRADE_AVAILABLE old new → mention once: "Archie {new} is available (installed: {old}). Upgrade: npx @bitraptors/archie@latest \"$PWD\"". Continue.
• JUST_UPGRADED old new → say "Archie upgraded {old} → {new}." once, then continue.

Telemetry consent (one-time, run before anything else)

Read and follow {{WORKFLOW_ROOT}}/_shared/telemetry-consent.md. It checks whether this machine has been asked about anonymous usage telemetry and, if not, presents a one-time interactive opt-in. It self-skips after the first answer and on non-interactive sessions.

Pick upload target

Before uploading, check whether an enterprise profile already exists:

test -f ~/.archie/share-profile.json && echo "PROFILE_EXISTS" || echo "PROFILE_MISSING"

Then ask the user which target to use. Present options based on whether a profile is set up — ask a single-choice question, consistently with the rest of Archie.

If PROFILE_EXISTS:

Ask the user — {{>ask_user}}:

• question: "Which share target?"
• header: "Share"
• multiSelect: false
• options (exactly these four labels):
  1. label Default — description Upload to the BitRaptors share service (our Supabase). Fastest, one-click. Recommended for OSS / non-sensitive projects.
  2. label Enterprise (stored) — description Upload to your pre-configured bucket at ~/.archie/share-profile.json. Fully automated. Data never touches BitRaptors infra.
  3. label Enterprise (paste URL) — description Upload to any bucket via a fresh presigned PUT URL you provide now. Zero credentials stored.
  4. label Manage profile — description Re-run setup with new credentials, or compose a request to InfoSec for a different bucket.

Map: Default → MODE=default. Enterprise (stored) → MODE=enterprise-creds. Enterprise (paste URL) → MODE=enterprise-paste. Manage profile → ask a follow-up question ({{>ask_user}}) with two options:

• question: "What do you want to do?"
• header: "Profile"
• multiSelect: false
• options:
  1. label Re-run setup — description Update ~/.archie/share-profile.json with new bucket + credentials. Loops back to the share target picker after.
  2. label Ask InfoSec — description Compose a ready-to-paste request with CORS + IAM policy snippets tailored to your situation. No upload happens — for prepping a new bucket.

Map: Re-run setup → MODE=setup. Ask InfoSec → MODE=ask-infosec.

If PROFILE_MISSING:

Ask the user — {{>ask_user}}:

• question: "Which share target?"
• header: "Share"
• multiSelect: false
• options (exactly these four labels):
  1. label Default — description Upload to the BitRaptors share service (our Supabase). Fastest, one-click. Recommended for OSS / non-sensitive projects.
  2. label Enterprise (paste URL) — description Upload to any bucket via a presigned PUT URL you provide now. Zero credentials stored.
  3. label Set up enterprise — description I already have bucket + AWS credentials from InfoSec. Store them in ~/.archie/share-profile.json for future use.
  4. label Ask InfoSec — description Compose a ready-to-paste request with CORS + IAM policy snippets tailored to your situation. Use this if you don't have a bucket yet.

Map: Default → MODE=default. Enterprise (paste URL) → MODE=enterprise-paste. Set up enterprise → MODE=setup. Ask InfoSec → MODE=ask-infosec.

Handling the choice

• Default → MODE=default. No extra flags. Proceed to "Resolve target blueprint".

• Enterprise (stored) → MODE=enterprise-creds. No extra flags needed — upload.py reads ~/.archie/share-profile.json directly.

• Enterprise (paste URL) → Ask for two URLs:

  Paste the PUT URL (Archie uploads the blueprint JSON here):

  Paste the GET URL (viewer fetches from here; packed into the share URL's fragment):

  Pass them as args on the upload.py command line. Double-quote them — presigned URLs contain & and =.

• Set up enterprise or Re-run setup → Ask for bucket + credentials:

  Bucket name (e.g. acme-archie-shares):

  Region (e.g. us-east-1):

  Access key ID (AKIA…):

  Secret access key:

  Key prefix (default archie-shares/):

  Then run setup, then loop back and ask the user which mode to use for this share:

  python3 .archie/share_setup.py --bucket "<BUCKET>" --region "<REGION>" --access-key-id "<AKID>" --secret-access-key "<SECRET>" --key-prefix "<PREFIX>"
  

  Security note: tell the user their credentials will appear in the command string for this shell invocation. For the highest security, they should edit ~/.archie/share-profile.json directly instead — see docs/enterprise-share-setup.md for the JSON schema.

• Ask InfoSec → Compose a tailored request. First ask the user 3 quick context questions (one at a time, OR as a batched prompt — whichever flows better):

  1. Company / org name? (e.g. Acme Corp — used in the greeting and bucket name suggestion)
  2. Preferred bucket name? (default: <company>-archie-shares, e.g. acme-archie-shares)
  3. What cloud does your company use? (AWS S3 / Azure Blob / GCS / other S3-compatible)

  Then compose a ready-to-paste message that the user can send to InfoSec via Slack/email/ticket. The message MUST include:

  1. Brief context (1–2 sentences): what Archie is, why you're asking for a bucket, which specific InfoSec concern this solves (no BitRaptors infrastructure in the data path).
  2. The CORS policy they need to apply — copy-paste JSON from docs/enterprise-share-setup.md Step 2, with AllowedOrigins set to https://archie-viewer.vercel.app.
  3. The IAM policy they need to apply — copy-paste JSON from docs/enterprise-share-setup.md Step 3, with Resource ARN substituted to the user's proposed bucket name (e.g. arn:aws:s3:::acme-archie-shares/archie-shares/*).
  4. What InfoSec should send back — bucket name, region, access key ID, secret access key (via 1Password or their secure channel).
  5. Data-flow summary for their security review: "Archie uploads blueprint JSON to our bucket via sigv4-signed PUT. The share URL points at archie-viewer.vercel.app with a URL fragment (#...) carrying the presigned GET URL. Fragments are browser-only — never transmitted to any server. When a teammate opens the share, their browser fetches directly from our bucket. BitRaptors stores nothing and sees no data."
  6. Link to the full walkthrough at docs/enterprise-share-setup.md for InfoSec to read if they want more detail.

  Adapt phrasing to the chosen cloud (e.g. if Azure, mention SAS tokens instead of AWS credentials; if GCS, HMAC keys). For non-AWS clouds, flag that enterprise-creds mode currently supports only AWS S3 (and S3-compatible services) — for Azure / GCS, they'd use the paste-URL mode with a presigned PUT URL generated by InfoSec on demand.

  Present the composed message in a fenced block so the user can copy it cleanly. After presenting, ask: "Want me to loop back to the share target picker once you have the credentials, or are we done for now?" If done, exit cleanly without uploading.

  Do NOT proceed to upload when this option is picked — the user is preparing to ask InfoSec, not sharing right now.

Resolve target blueprint

Read the persisted scope config to determine which blueprint(s) can be shared:

python3 .archie/intent_layer.py scan-config "$PWD" read

• Exit 1 (no config) or scope is single or whole → there's one blueprint at the repo root. Use TARGET="$PWD".
• scope is per-package → multiple workspace-level blueprints exist.
  • If exactly one workspace is listed → use that one: TARGET="$PWD/<workspace>".
  • If multiple → ask the user which to share.
    • Ask the user which workspaces to share — {{>ask_user}}. Allow multiple selections: one option per workspace, label <workspace-name>, description Path: <path>. If presenting a numbered list, accept number/name/all. Map the user's picks to workspace paths.
    • If the user picks more than one (multi-select picks, or all), loop and upload each separately.
• scope is hybrid → root has a monorepo-wide blueprint AND each listed workspace has its own.
  • Ask the user which blueprints to share (they may want root + one workspace in the same share run).
    • Ask the user which blueprints to share — {{>ask_user}}. Allow multiple selections: first option label Monorepo-wide (root), one option per workspace labeled by workspace name. If presenting a numbered list, accept root, workspace names comma-separated, or all. Loop over the user's picks and upload each.
  • root → TARGET="$PWD". Workspace name → TARGET="$PWD/<workspace>".

Run

For each resolved TARGET:

Heads-up for Codex CLI users: the upload step makes one outbound HTTPS request. Codex's default workspace-write sandbox blocks network egress, so the first upload in a session pauses for a one-time approval prompt. This is expected — approve once and the rest of the session is uninterrupted. (On Claude Code the request runs prompt-free under the existing Bash(python3 .archie/*.py *) allow rule.)

Default mode:

python3 .archie/upload.py "$TARGET"

Enterprise (stored credentials) mode:

python3 .archie/upload.py "$TARGET" --mode enterprise-creds

Enterprise (paste URL) mode — pass the URLs as args in the same command so there's no env-var state to persist across tool calls:

python3 .archie/upload.py "$TARGET" --mode enterprise-paste --put-url "<PUT_URL>" --get-url "<GET_URL>"

Substitute the actual URLs the user pasted. Double-quote them — presigned URLs contain & and = that must not be shell-expanded.

The script prints a shareable URL on success. For all mode in per-package, print one URL per workspace with a label (e.g., apps/webui: <url>).

If the upload fails (network issues, server down, bucket misconfigured, expired presigned URL), your local blueprint is unaffected. Try again later — or in enterprise mode, ask InfoSec to mint fresh URLs.

Enterprise mode notes

• The share URL returned looks like https://archie-viewer.vercel.app/r/ext#<base64url-encoded-GET-URL>. The GET URL lives in the URL fragment (#...), which browsers never transmit to any server. BitRaptors sees nothing about the share.
• The viewer fetches directly from the GET URL. The customer's bucket must allow CORS from https://archie-viewer.vercel.app or the viewer shows a fetch error.
• Presigned GET URLs expire (max 7 days on AWS S3 for IAM-user-signed URLs). When a share URL stops working, re-run {{COMMAND_PREFIX}}archie-share with fresh URLs from InfoSec.

Telemetry (run after upload completes, silent if opted out)

After the share URL is printed, record an anonymous event so we can track adoption. The blueprint contents are NEVER sent through this channel — only the fact that a share happened, plus the project's stack categories.

python3 .archie/telemetry_sync.py record-event --command share --outcome success --project-root "$PWD" 2>/dev/null || true

If the upload failed, swap success for error and pass --error <error_class>.