archive-labs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archive Labs
+
+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.

package/README.md

@@ -0,0 +1,357 @@
+# Archive Labs CLI
+
+Install:
+
+```bash
+npm install -g archive-labs
+archive
+```
+
+Development:
+
+```bash
+corepack pnpm install
+corepack pnpm build
+```
+
+The default `archive` launcher is interactive in a real terminal:
+
+- use the arrow keys to move
+- press `Enter` to run the highlighted command
+- press `?` to open the full help screen
+- press `Esc` to return from the help screen
+- press `Ctrl+C` to exit
+- the selected command is highlighted in the launcher
+
+Login:
+
+```bash
+archive login
+```
+
+Supported sign-in methods:
+
+- GitHub
+- Google
+- Microsoft
+- email and password
+
+For browser-based sign-in, the CLI opens the Archive Labs auth page and completes login through a localhost callback back into the terminal session.
+
+After sign-in, the CLI now shows a minimal post-login summary with:
+
+- who signed in
+- the resolved workspace or repo context
+- current sync state
+- one clear next step, or a short set of suggested commands when the repo is already ready
+
+No-install run:
+
+```bash
+npx archive-labs
+```
+
+The CLI surface follows the Archive V2 command groups below. Commands now route to the live Archive backend and return actionable errors when auth, repository access, or workspace setup is missing.
+
+The CLI is the supported terminal interface. It uses authenticated Archive backend routes for setup, sync, status, impact, ask, and release workflows. The documented external HTTP API is the smaller `/v1` decision API in `../../docs/api/v1.md`; TypeScript integrations can use the SDK in `../sdk`.
+
+`archive init` behavior:
+
+- `archive init` is the setup-readiness command
+- it saves the API and app targets for the current workspace, then immediately verifies what is actually ready
+- it stays distinct from nearby setup commands:
+  - `archive ping` = narrow API connectivity check
+  - `archive doctor` = raw diagnostics and local wiring details
+  - `archive sync` = repository connection and indexing
+- it never starts a sync automatically
+- it always returns one exact next step:
+  - `archive login`
+  - `archive sync`
+  - `archive sync --wait`
+  - dashboard setup URL text
+  - or `archive status` when the repo is fully ready
+
+`archive recent` behavior:
+
+- `archive recent` shows locally stored recent Archive commands from this machine
+- it is CLI-only and does not require backend or SQL changes
+- default text output stays compact and scan-friendly
+- the interactive launcher also surfaces a small `Recent` section for one-click reruns
+- recent history includes both successes and failures, clearly labeled
+
+`archive sync` behavior:
+
+- in a terminal, `archive sync` waits by default and shows live indexing progress
+- in non-interactive usage, `archive sync` starts or attaches and returns immediately by default
+- use `--wait` to block until indexing finishes
+- use `--no-wait` to return immediately even in an interactive terminal
+
+`archive status` behavior:
+
+- works as the instant daily health read for the current repo
+- default terminal output stays compact: `Status`, `Integrity`, `Confidence`, one `Issue`, and one `Next Action` when needed
+- returns partial status when secondary signals are unavailable instead of failing the whole command
+- keeps follow-up guidance to a single next step only when action is needed
+
+Machine-readable output:
+
+```bash
+archive init -y --json
+archive recent --json
+archive doctor --json
+archive ping --json
+archive sync --json --repository acme/repo --no-wait
+archive ask --json --repository acme/repo "where is auth handled?"
+archive impact file --json --repository acme/repo src/app.ts
+```
+
+`archive status --json` now includes the compatibility fields above plus `status`, `integrityScore`, `primaryIssue`, `verdict`, `confidenceLevel`, `missingSignals`, `nextAction`, and a stable `signals` object for UI and scripting consumers.
+
+Command roles:
+
+- setup commands (`init`, `login`, `sync`, `doctor`, `ping`) make the local and CI environment trustworthy
+- awareness commands (`status`, `events`) explain current repository state
+- advisory commands (`impact`, `ask`, `why`) explain blast radius, evidence, and intent without making merge decisions
+- gate commands (`check pr`, `check diff`, `release risk`) produce `PASS`, `WARN`, or `BLOCK` where that workflow is appropriate
+
+CI Gate:
+
+Use `archive check pr` as the protected-branch CI gate. CI mode is non-interactive: it never opens prompts, never prints launcher navigation, and treats gate decisions as process outcomes. A failing Archive command blocks a merge only when the repository's CI and GitHub branch protection require that job or check. Add `--json` for machine-readable output; JSON mode emits exactly one JSON object on stdout, with no spinner, progress, ANSI, help text, or parser logs mixed in.
+
+Protected-branch gate:
+
+```bash
+archive check pr 182 --repository acme/payments --ci --json --strict
+```
+
+`archive check diff` is best for local/pre-push checks unless CI passes a deterministic diff context. `archive release risk` is a release readiness gate, not a PR merge gate.
+
+GitHub Actions example:
+
+```yaml
+name: Archive Gate
+
+on:
+  pull_request:
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install -g archive-labs
+      - name: Archive PR gate
+        env:
+          ARCHIVE_TOKEN: ${{ secrets.ARCHIVE_TOKEN }}
+          ARCHIVE_GITHUB_TOKEN: ${{ secrets.ARCHIVE_GITHUB_TOKEN }}
+          CI: true
+        run: archive check pr "${{ github.event.pull_request.number }}" --repository "${{ github.repository }}" --ci --json --strict --timeout 600000
+```
+
+Release gate example:
+
+```yaml
+- name: Archive release risk
+  env:
+    ARCHIVE_TOKEN: ${{ secrets.ARCHIVE_TOKEN }}
+    ARCHIVE_GITHUB_TOKEN: ${{ secrets.ARCHIVE_GITHUB_TOKEN }}
+    CI: true
+  run: archive release risk "${{ github.ref_name }}" --repository "${{ github.repository }}" --ci --json --strict
+```
+
+Exit codes are stable for CI:
+
+- `0`: PASS, or WARN when `--strict` is not set
+- `2`: usage or argument error
+- `3`: risk or policy BLOCK, including WARN with `--strict`
+- `4`: auth, config, or setup missing
+- `5`: network, service, or API failure
+- `6`: timeout
+- `7`: internal CLI or tooling failure
+
+JSON success envelope:
+
+```json
+{
+  "ok": true,
+  "command": "archive check pr",
+  "mode": "pr",
+  "verdict": "pass",
+  "exitCode": 0,
+  "confidence": "high",
+  "repository": "acme/payments",
+  "branch": "main",
+  "summary": "No blocking guardrails found.",
+  "evidence": [],
+  "requiredActions": [],
+  "nextAction": null,
+  "meta": { "schemaVersion": 1, "ci": true, "strict": true }
+}
+```
+
+JSON failure envelope:
+
+```json
+{
+  "ok": false,
+  "command": "archive check pr",
+  "exitCode": 4,
+  "error": {
+    "code": "auth_required",
+    "category": "setup",
+    "message": "Run archive login before using this command.",
+    "hint": "Run archive login to continue.",
+    "retryable": false,
+    "statusCode": null,
+    "requestId": null
+  },
+  "meta": { "schemaVersion": 1 }
+}
+```
+
+Gate outputs include normalized `verdict`, `confidence`, `riskScore`, `riskLevel`, `affectedFiles`, `affectedServices`, `owners`, `evidence`, `requiredActions`, and `nextAction` fields when Archive can derive them. Missing auth/config fails as setup, API and network failures fail as service, and bounded backend requests or polling exit `6` instead of hanging. The default total polling timeout is 10 minutes in CI and 20 minutes in an interactive terminal; override it with `--timeout <ms>`.
+
+Config and token storage:
+
+- CLI config is stored under `~/.archive-labs/config.json`
+- default production targets are `https://api.archivelabs.dev` and `https://app.archivelabs.dev`; localhost targets are opt-in through flags, environment variables, or local config
+- CI can provide `ARCHIVE_TOKEN` or `ARCHIVE_LABS_TOKEN`; GitHub-backed commands can also provide `ARCHIVE_GITHUB_TOKEN`
+- malformed config fails clearly instead of being ignored
+- token-bearing config is written with `0600` file permissions on Unix
+- Windows currently uses plaintext file storage; secret handling is isolated behind a storage adapter so Windows Credential Manager support can be added without changing command behavior
+
+`archive check` behavior:
+
+- `archive check` is now a smart default
+- when your working tree is dirty, it runs the local change gate and shows `Mode: Diff`
+- when your working tree is clean, it runs the readiness/system-trust check and shows `Mode: Readiness`
+
+`archive check diff` behavior:
+
+- `archive check diff` now focuses only on the current working-tree changes
+- it returns a decision-first guardrail result: `PASS`, `WARN`, or `BLOCK`
+- risk stays separate from the decision with a numeric score and `Low` / `Moderate` / `High` labeling
+- it stays distinct from `archive impact diff` by emphasizing safety, owners, visibility gaps, and the next action instead of a broader impact report
+
+`archive check pr` behavior:
+
+- `archive check pr` is the merge-decision command
+- it combines impact, ownership, policy, confidence, and required actions into one short PR verdict
+- Archive publishes the GitHub check as `Archive PR Check`
+- without `--ci`, it exits `0` even when the decision is `BLOCK` so humans can inspect the result
+- with `--ci`, `BLOCK` exits `3`; `WARN` exits `3` only when `--strict` is set
+
+`archive impact file <path>` behavior:
+
+- `archive impact file <path>` is the path-level impact explorer
+- it answers one question: if this file changes, what does it affect?
+- it stays non-gating and does not print a merge decision, score, or risk label
+- it uses the shared impact engine first, then enriches the result with dependency-graph and ownership signals when available
+- it prioritizes service-level consequences with visible owners and only falls back to `Downstream Files` when service mapping is too weak to explain the impact
+- it keeps `Likely First Impact`, `Critical Surfaces`, `Visibility`, and `Next Step` intentionally rare so the default output stays focused
+
+`archive impact diff` behavior:
+
+- `archive impact diff` stays non-gating
+- it analyzes the current working tree automatically: staged, unstaged, added, deleted, renamed, and untracked non-ignored changes
+- it focuses on blast radius, affected services with visible owners, rare likely-first-impact hints, and one next step only when it is actually useful
+- it only shows `Visibility` when Archive's dependency/impact view is degraded
+- it does not print a merge decision or any risk score
+
+`archive why <path>` behavior:
+
+- `archive why <path>` is the file-memory command
+- it is file-first and uses path-specific commits, PRs, code structure, and ownership before falling back to broader repo context
+- it explains `Role`, `Why It Exists`, and only shows `Why It Looks Like This` when there is explicit structural evidence
+- it keeps `Related` tight to high-signal memory aids such as owner, top related file, or top symbol
+- it stays distinct from `archive ask` and `archive impact file` by focusing on intent and evidence, not open-ended Q&A or blast radius
+
+`archive events` behavior:
+
+- `archive events` is the curated repo-awareness command
+- by default it shows up to 7 meaningful repo-level events from the last 7 days
+- it stays chronological and quiet: no counters, no raw logs, no dashboard-style dump
+- every event must explain `Why it matters`
+- optional follow-up action stays rare and defaults to at most one clear next command
+- use `archive events --since 24h`, `archive events --since 7d`, or `archive events --since 30d` to adjust the window quickly
+- `archive release summarize <tag>` is the engineering handoff command
+- it stays distinct from `archive release risk <tag>` by answering `What is in this release?`, not `Should we feel nervous shipping it?`
+- it keeps the default output short and structured around summary, highlights, affected systems, and included changes
+- it is explicit about first-tag inference, uncertain baselines, and partial coverage instead of pretending the release window is cleaner than it is
+- `archive release risk <tag>` is the pre-ship confidence command
+- it stays distinct from `archive release summarize <tag>` by answering `How risky is it to ship this release tag?`
+- it reuses grouped release impact as the scoring spine, then overlays release-size, guardrail, ownership, and visibility signals
+- it is explicit about first-tag inference, weak visibility, and uncertain baselines instead of pretending the release window is cleaner than it is
+
+Local development:
+
+```bash
+cd packages/cli
+corepack pnpm install
+corepack pnpm build
+npm link
+archive
+archive help
+archive-labs help
+```
+
+Starter commands:
+
+```bash
+archive
+archive init
+archive login
+archive status
+archive recent
+archive events
+archive events --since 24h
+archive sync
+archive check
+archive check diff
+archive check pr 182
+archive impact file src/app.ts
+archive impact diff
+archive ask "Where is auth handled?"
+archive why src/lib/auth.ts
+archive release summarize v1.2.0
+archive help
+archive version
+archive doctor
+archive ping https://api.example.com
+```
+
+Command catalog:
+
+- `System`: `archive status`, `archive events`
+- `Setup`: `archive init`, `archive sync`
+- `Guardrails`: `archive check`, `archive check pr`, `archive check diff`
+- `Impact`: `archive impact file <path>`, `archive impact diff`
+- `Intelligence`: `archive ask "<question>"`, `archive why <path>`
+- `Release`: `archive release summarize <tag>`, `archive release risk <tag>`
+- `Utility`: `archive login`, `archive recent`, `archive version`, `archive help`, `archive doctor`, `archive ping`
+
+Launch flow:
+
+```bash
+archive init
+archive login
+archive sync
+archive recent
+archive ask "where is auth handled?"
+archive impact file src/app.ts
+archive why src/lib/auth.ts
+```
+
+Publish flow:
+
+```bash
+npm pack
+npm publish
+```
+
+This package is developed with pnpm and shipped through the npm registry.