21c506dcae
Add DEPLOYMENT-MODES.md with canonical mode taxonomy. Update CLI.md, DEVELOPING.md, PRODUCT.md, and SPEC-implementation.md with local_trusted/ authenticated nomenclature. Revise humans-and-permissions plan with Better Auth choice, bootstrap flow, unified invite semantics, and expanded criteria. Add implementation guide and additional plan documents for cursor cloud adapter and deployment auth mode consolidation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
155 lines
3.8 KiB
Markdown
155 lines
3.8 KiB
Markdown
# Developing
|
|
|
|
This project can run fully in local dev without setting up PostgreSQL manually.
|
|
|
|
## Deployment Modes
|
|
|
|
For mode definitions and intended CLI behavior, see `doc/DEPLOYMENT-MODES.md`.
|
|
|
|
Current implementation status:
|
|
|
|
- canonical model: `local_trusted` and `authenticated` (with `private/public` exposure)
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+
|
|
- pnpm 9+
|
|
|
|
## Start Dev
|
|
|
|
From repo root:
|
|
|
|
```sh
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
This starts:
|
|
|
|
- API server: `http://localhost:3100`
|
|
- UI: served by the API server in dev middleware mode (same origin as API)
|
|
|
|
## One-Command Local Run
|
|
|
|
For a first-time local install, you can bootstrap and run in one command:
|
|
|
|
```sh
|
|
pnpm paperclip run
|
|
```
|
|
|
|
`paperclip run` does:
|
|
|
|
1. auto-onboard if config is missing
|
|
2. `paperclip doctor` with repair enabled
|
|
3. starts the server when checks pass
|
|
|
|
## Database in Dev (Auto-Handled)
|
|
|
|
For local development, leave `DATABASE_URL` unset.
|
|
The server will automatically use embedded PostgreSQL and persist data at:
|
|
|
|
- `~/.paperclip/instances/default/db`
|
|
|
|
Override home and instance:
|
|
|
|
```sh
|
|
PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
|
|
```
|
|
|
|
No Docker or external database is required for this mode.
|
|
|
|
## Storage in Dev (Auto-Handled)
|
|
|
|
For local development, the default storage provider is `local_disk`, which persists uploaded images/attachments at:
|
|
|
|
- `~/.paperclip/instances/default/data/storage`
|
|
|
|
Configure storage provider/settings:
|
|
|
|
```sh
|
|
pnpm paperclip configure --section storage
|
|
```
|
|
|
|
## Quick Health Checks
|
|
|
|
In another terminal:
|
|
|
|
```sh
|
|
curl http://localhost:3100/api/health
|
|
curl http://localhost:3100/api/companies
|
|
```
|
|
|
|
Expected:
|
|
|
|
- `/api/health` returns `{"status":"ok"}`
|
|
- `/api/companies` returns a JSON array
|
|
|
|
## Reset Local Dev Database
|
|
|
|
To wipe local dev data and start fresh:
|
|
|
|
```sh
|
|
rm -rf ~/.paperclip/instances/default/db
|
|
pnpm dev
|
|
```
|
|
|
|
## Optional: Use External Postgres
|
|
|
|
If you set `DATABASE_URL`, the server will use that instead of embedded PostgreSQL.
|
|
|
|
## Secrets in Dev
|
|
|
|
Agent env vars now support secret references. By default, secret values are stored with local encryption and only secret refs are persisted in agent config.
|
|
|
|
- Default local key path: `~/.paperclip/instances/default/secrets/master.key`
|
|
- Override key material directly: `PAPERCLIP_SECRETS_MASTER_KEY`
|
|
- Override key file path: `PAPERCLIP_SECRETS_MASTER_KEY_FILE`
|
|
|
|
Strict mode (recommended outside local trusted machines):
|
|
|
|
```sh
|
|
PAPERCLIP_SECRETS_STRICT_MODE=true
|
|
```
|
|
|
|
When strict mode is enabled, sensitive env keys (for example `*_API_KEY`, `*_TOKEN`, `*_SECRET`) must use secret references instead of inline plain values.
|
|
|
|
CLI configuration support:
|
|
|
|
- `pnpm paperclip onboard` writes a default `secrets` config section (`local_encrypted`, strict mode off, key file path set) and creates a local key file when needed.
|
|
- `pnpm paperclip configure --section secrets` lets you update provider/strict mode/key path and creates the local key file when needed.
|
|
- `pnpm paperclip doctor` validates secrets adapter configuration and can create a missing local key file with `--repair`.
|
|
|
|
Migration helper for existing inline env secrets:
|
|
|
|
```sh
|
|
pnpm secrets:migrate-inline-env # dry run
|
|
pnpm secrets:migrate-inline-env --apply # apply migration
|
|
```
|
|
|
|
## CLI Client Operations
|
|
|
|
Paperclip CLI now includes client-side control-plane commands in addition to setup commands.
|
|
|
|
Quick examples:
|
|
|
|
```sh
|
|
pnpm paperclip issue list --company-id <company-id>
|
|
pnpm paperclip issue create --company-id <company-id> --title "Investigate checkout conflict"
|
|
pnpm paperclip issue update <issue-id> --status in_progress --comment "Started triage"
|
|
```
|
|
|
|
Set defaults once with context profiles:
|
|
|
|
```sh
|
|
pnpm paperclip context set --api-base http://localhost:3100 --company-id <company-id>
|
|
```
|
|
|
|
Then run commands without repeating flags:
|
|
|
|
```sh
|
|
pnpm paperclip issue list
|
|
pnpm paperclip dashboard get
|
|
```
|
|
|
|
See full command reference in `doc/CLI.md`.
|