codequill 0.8.1-beta.4 → 0.9.1

package/README.md

@@ -1,121 +1,368 @@
-CodeQuill CLI
+# CodeQuill CLI
 
-CodeQuill CLI lets you authenticate, claim repositories, create on-chain snapshots, and push backups via the CodeQuill backend. The CLI makes only HTTP requests; all on-chain activity and backup processing happen on the backend.
+> Secure snapshots, authorship, and code preservation
+
+Command-line interface for CodeQuill — memory infrastructure for software. Create snapshots, claim repositories, publish releases, attest artifacts, and preserve source code with zero-custody encryption.
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g codequill
+```
+
+### From source
+
+```bash
+git clone https://github.com/codequill/codequill-cli.git
+cd codequill-cli
+npm install
+npm run build
+npm link
+```
+
+## Requirements
 
-Requirements
 - Node.js 18+
-- TypeScript 5+
-
-Install (from source)
-- npm install
-- npm run build
-- npm link (optional, to get the `codequill` binary on PATH)
-
-Configuration
-- API base URL: set environment variable `CODEQUILL_API_BASE_URL` (defaults to `https://api.staging.codequill.dev`).
-- Tokens are stored at `~/.config/codequill/config.json` with 0600 permissions.
-- For testing or sandboxing, you can override the config directory with `CODEQUILL_CONFIG_DIR` (mainly used by unit tests).
-
-Session duration and auto-refresh
-- The CLI automatically refreshes your access token using the stored `refresh_token` when it expires.
-- As long as your refresh token remains valid (typically around 30 days), you will stay signed in and won’t be prompted to log in again.
-- If your access token is expired and no valid `refresh_token` is present, the CLI will ask you to run `codequill login` again.
-
-Usage
-- Show help
-  - `codequill --help`
-  - `codequill <command> --help`
-
-Commands
-- codequill login
-  - Authenticates via device-code flow.
-  - Behavior:
-    - POST `/api/v1/cli/device-code` with `{ client_name: "codequill-cli", client_version }`.
-    - Prints a `verification_url` — open it in your browser.
-    - Prerequisite: make sure you are already signed in to the CodeQuill web app in that browser session.
-    - Polls POST `/api/v1/cli/device-token` until approved.
-    - Saves tokens with a small expiry margin. Subsequent commands auto-refresh access tokens using the stored `refresh_token`.
-
-- codequill whoami
-  - Displays the current authenticated user and repos.
-  - GET `/api/v1/cli/me` with `Authorization: Bearer <access_token>`.
-
-- codequill quota
-  - Shows your subscription plan and quota usage details.
-  - GET `/v1/cli/quota` with `Authorization: Bearer <access_token>`.
-  - Displays:
-    - Plan code
-    - Claimed repos (public/private used vs limit)
-    - Snapshots used this month vs limit
-    - Backups used this month vs limit
-    - GitHub Actions used vs limit
-    - Plagiarism scans used this month vs limit
-
-- codequill claim [--repo <name>] [--path <path>]
-  - Claims authorship of a repository via the backend.
-  - If run inside a git repo, auto-detects repo name from `origin` remote or folder name.
-  - POST `/api/v1/cli/claim` with `{ repo_name, path, git_remote }`.
-
-- codequill snapshot [--repo <name>] [--commit <hash>] [--path <path>] [--dry-run]
-  - Creates a new on-chain snapshot for a repo+commit (backend performs on-chain work).
-  - If inside git, defaults to `HEAD` commit and derives repo name from remote.
-  - `--dry-run` prints resolved parameters without calling the API.
-  - POST `/api/v1/cli/snapshot` with `{ repo_name, commit_hash, path, git: { is_repo, remote } }`.
-
-- codequill push [--repo <name>] [--path <path>] [--snapshot-id <id>] [--dry-run]
-  - Backs up the latest (or a specified) snapshot.
-  - Important: the backend performs zipping, encryption, and IPFS upload. The CLI only sends intent and metadata.
-  - `--dry-run` prints resolved parameters without calling the API.
-  - POST `/api/v1/cli/push` with `{ repo_name, path, snapshot_id }`.
-
-Git-aware vs explicit mode
-- When run inside a git repository, the CLI tries to determine:
-  - repo root (`git rev-parse --show-toplevel`)
-  - `HEAD` commit hash
-  - `origin` remote URL to derive `user/name`
-- When run outside git, pass `--repo` and optionally `--commit` and `--path`.
-
-Environment variables
-- `CODEQUILL_API_BASE_URL` — base HTTP URL for backend (default: staging placeholder).
-- `CODEQUILL_CONFIG_DIR` — override tokens/config directory (used by tests).
-
-Development
-- Build: `npm run build`
-- Watch: `npm run dev`
-- Tests: `npm test`
-- Coverage: `npm run coverage`
-
-Project Structure
-- src/index.ts — Commander entrypoint
-- src/version.ts — CLI version via package.json
-- src/commands/login.ts — device-code login
-- src/commands/whoami.ts — prints current user
-- src/commands/claim.ts — claim authorship
-- src/commands/snapshot.ts — create snapshots
-- src/commands/push.ts — request backups (backend handles zip/encrypt/upload)
-- src/services/apiClient.ts — HTTP wrapper with auth header injection
-- src/services/authStore.ts — token persistence (0600)
-- src/services/config.ts — config dir/file paths
-- src/services/errors.ts — ApiError type
-- src/services/ui.ts — colors, spinner, open browser helper
-- src/services/git.ts — git detection (root/head/remote) and repo name derivation
-- src/services/paths.ts — path helpers
-- src/services/zip.ts — zip helper (currently unused in `push` since backend handles it)
-- src/services/ipfs.ts — placeholder IPFS helper (currently unused)
-- src/types/api.ts — API types
-- test/*.test.ts — unit tests (Vitest)
-
-Testing
-- The test suite is API-free and uses mocks; it verifies:
-  - Token storage and permissions
-  - API client behavior and error handling
-  - Git remote parsing logic
-  - Command flows for `login`, `whoami`, `claim`, `snapshot` (incl. dry-run), and `push` (incl. dry-run)
-- Run: `npm test`
-
-Notes & assumptions
-- The CLI relies on the backend for all on-chain actions and, for backups, for zipping/encryption/IPFS upload.
-- Token refresh is not yet implemented; if expired, the CLI asks you to re-login.
-
-License
-MIT © CodeQuill
+- Git (for repository detection)
+
+## Quick Start
+
+```bash
+# Authenticate with CodeQuill
+codequill login
+
+# Claim authorship of current repository
+codequill claim
+
+# Create a snapshot of your latest commit
+codequill snapshot
+
+# Publish a release
+codequill publish
+
+# Create an encrypted preservation
+codequill preserve <snapshot-id>
+```
+
+## Commands
+
+### Authentication
+
+#### `codequill login`
+
+Authenticate via device-code flow. Opens your browser to authorize the CLI.
+
+```bash
+codequill login
+```
+
+#### `codequill who`
+
+Show the current authenticated user.
+
+```bash
+codequill who
+```
+
+#### `codequill quota`
+
+Display your subscription plan and usage:
+- Claimed repositories
+- Snapshots created
+- Preservations stored
+- Attestations made
+
+```bash
+codequill quota
+```
+
+### Repository Management
+
+#### `codequill claim`
+
+Claim authorship of a repository on-chain.
+
+```bash
+# Auto-detect from current git repository
+codequill claim
+
+# Skip confirmation prompt
+codequill claim --no-confirm
+```
+
+**Options:**
+- `--no-confirm` - Skip interactive confirmation
+- `--confirmations <n>` - Wait for N confirmations (default: 1)
+- `--timeout <ms>` - Timeout for confirmation
+- `--no-wait` - Submit transaction and return immediately
+- `--json` - Output in JSON format
+
+#### `codequill status`
+
+Show repository status and recent snapshots.
+
+```bash
+codequill status
+```
+
+#### `codequill log`
+
+View snapshot history for the current repository.
+
+```bash
+codequill log
+```
+
+### Snapshots
+
+#### `codequill snapshot`
+
+Create a deterministic snapshot (Merkle tree) of the repository at a specific commit.
+
+```bash
+# Snapshot current HEAD
+codequill snapshot
+
+# Snapshot specific commit
+codequill snapshot --commit abc123
+
+# Custom concurrency
+codequill snapshot --concurrency 16
+```
+
+**Options:**
+- `--commit <hash>` - Commit hash to snapshot (default: HEAD)
+- `--concurrency <n>` - Number of concurrent file reads (default: 8)
+- `--salt <hex>` - Custom salt for path hashing (64 hex chars)
+- `--print-salt` - Display the salt in output
+
+#### `codequill pull`
+
+Download all published snapshot manifests for the current repository.
+
+```bash
+codequill pull
+```
+
+Manifests are stored in `.codequill/snapshots/`.
+
+### Publishing
+
+#### `codequill publish`
+
+Publish a snapshot by anchoring its Merkle root on-chain and storing the manifest on IPFS.
+
+```bash
+# Publish latest snapshot
+codequill publish
+
+# Publish specific commit
+codequill publish <commit-hash>
+```
+
+**Options:**
+- `--no-confirm` - Skip confirmation prompt
+- `--confirmations <n>` - Wait for N confirmations (default: 1)
+- `--timeout <ms>` - Timeout for confirmation
+- `--no-wait` - Submit and return immediately
+- `--json` - Output in JSON format
+
+**Note:** Releases (named, governed versions) are created in the web app at app.codequill.xyz. The CLI publishes snapshots.
+
+#### `codequill wait`
+
+Wait for a transaction to confirm.
+
+```bash
+codequill wait <tx-hash>
+```
+
+### Attestations
+
+#### `codequill attest`
+
+Create an attestation linking a build artifact to a published release.
+
+```bash
+codequill attest <artifact> <release-id>
+```
+
+**Arguments:**
+- `<artifact>` - Path to the build artifact
+- `<release-id>` - Release ID to attest against
+
+**Options:**
+- `--subject-name <name>` - Artifact name
+- `--subject-version <ver>` - Artifact version
+- `--upstream <purl>` - Upstream dependency (repeatable)
+- `--no-confirm` - Skip confirmation
+- `--confirmations <n>` - Wait for N confirmations
+- `--json` - Output in JSON format
+
+**Note:** Attestations require an **accepted release**. The release must pass governance approval before attestation.
+
+#### `codequill verify-attestation`
+
+Verify an attestation (offline operation).
+
+```bash
+codequill verify-attestation <attestation-file>
+```
+
+### Proofs
+
+#### `codequill prove`
+
+Generate a Merkle proof that a specific file was included in a snapshot.
+
+```bash
+codequill prove <file> <snapshot-id>
+
+# Include plaintext path in proof
+codequill prove <file> <snapshot-id> --disclose
+
+# Custom output path
+codequill prove LICENSE <snapshot-id> --out evidence/license-proof.json
+```
+
+**Arguments:**
+- `<file>` - Path to file to prove inclusion for
+- `<snapshot-id>` - Snapshot ID to prove against
+
+**Options:**
+- `--disclose` - Include plaintext path in proof (privacy tradeoff)
+- `--out <file>` - Output path for proof file
+
+#### `codequill verify-proof`
+
+Verify a proof of inclusion (offline operation).
+
+```bash
+codequill verify-proof <proof-file>
+```
+
+### Preservations
+
+#### `codequill preserve`
+
+Create an encrypted preservation (backup) of source code tied to a published snapshot.
+
+```bash
+codequill preserve <snapshot-id>
+```
+
+**Arguments:**
+- `<snapshot-id>` - Published snapshot ID to preserve
+
+**Options:**
+- `--no-confirm` - Skip confirmation
+- `--confirmations <n>` - Wait for N confirmations
+- `--timeout <ms>` - Timeout for confirmation
+- `--no-wait` - Submit and return immediately
+- `--json` - Output in JSON format
+
+**Encryption:** Uses AES-256-GCM with passkey-derived keys (zero-custody). CodeQuill never sees plaintext source code.
+
+### Learning
+
+#### `codequill why`
+
+Learn about CodeQuill concepts.
+
+```bash
+# Overview
+codequill why
+
+# Specific topics
+codequill why claim
+codequill why snapshot
+codequill why publish
+codequill why prove
+codequill why attest
+codequill why preserve
+```
+
+**Options:**
+- `--short` - Brief explanation
+- `--ci` - CI-friendly explanation
+
+## Configuration
+
+### API Endpoint
+
+Set the CodeQuill API base URL:
+
+```bash
+export CODEQUILL_API_BASE_URL=https://api.codequill.xyz
+```
+
+Default: `https://api.codequill.xyz`
+
+### Config Directory
+
+Authentication tokens are stored at `~/.config/codequill/config.json` with `0600` permissions.
+
+Override for testing:
+
+```bash
+export CODEQUILL_CONFIG_DIR=/custom/path
+```
+
+### Session Management
+
+- Access tokens auto-refresh using your refresh token
+- Refresh tokens valid for ~30 days
+- Run `codequill login` to re-authenticate when expired
+
+## How It Works
+
+The CLI is a lightweight client that communicates with the CodeQuill backend:
+
+1. **Snapshots** - Created locally by hashing files and building a Merkle tree. No source code is uploaded.
+2. **Privacy** - File paths are salted before hashing (passkey-derived salt). Enables selective disclosure.
+3. **Publishing** - Anchors snapshot Merkle roots on Ethereum and stores manifests on IPFS.
+4. **Releases** - Created in the web app. Named, governed versions that group snapshots and enable attestations.
+5. **Attestations** - Links build artifacts to accepted releases. Records who, what, and when on-chain.
+6. **Preservations** - Encrypts full source archives client-side. Zero-custody (passkey-derived encryption).
+7. **Proofs** - Merkle proofs of file inclusion. Verifiable by anyone, created with authority.
+
+## Architecture
+
+- **CLI** - Evidence production (snapshots, attestations, proofs)
+- **Web App** - Configuration and governance (app.codequill.xyz)
+- **Smart Contracts** - Immutable on-chain records (Ethereum)
+- **IPFS** - Decentralized storage (manifests, preservations)
+
+Even if CodeQuill servers are compromised, the evidence layer remains independently verifiable.
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:watch
+npm run coverage
+```
+
+## Documentation
+
+Full documentation: [docs.codequill.xyz](https://docs.codequill.xyz)
+
+## License
+
+MIT © CodeQuill