# wisp-deploy

`wisp-deploy` is a small, non-interactive go cli for deploying a directory to [wisp.place](https://wisp.place) from ci. it resolves an at protocol handle, finds its pds, uploads changed files, and writes the `place.wisp.*` records used by wisp.place.

it only deploys sites. use [wispctl](https://tangled.org/nekomimi.pet/wisp.place-monorepo/tree/main/cli) if you want oauth login or the other interactive commands.

## authentication

create an app password for the account and put it in the environment under `WISP_APP_PASSWORD`. this is the preferred option because the password does not appear in the process arguments.

`--password` is kept for compatibility with wispctl. command arguments may be visible to other processes or recorded by a ci runner, so avoid it when the environment variable is available. `--password-file` is also supported. an explicit flag or password file takes precedence over `WISP_APP_PASSWORD`; `--password` and `--password-file` cannot be used together.

handles are normally resolved through their `/.well-known/atproto-did` endpoint, with the `_atproto` dns record as a fallback. the resulting `did:plc` or `did:web` document provides the pds endpoint. pds connections must use https.

set `WISP_MINIDOC_URL` to the full `blue.microcosm.identity.resolveMiniDoc` xrpc endpoint to use a slingshot instance instead. this bypasses local handle and did resolution, so its response decides which pds receives the app password. use an https endpoint; plain http is only accepted for localhost.

## usage

```text
usage: wisp-deploy [options] <handle>

deploy a static site to wisp.place

options:
  -p, --path <path>          directory to deploy (required)
  -s, --site <name>          site name (defaults to the directory name)
  --directory                enable directory listing
  --spa                      serve index.html for routes without a file
  -c, --concurrency <n>      number of concurrent uploads (default: 3)
  --force-gzip               gzip every file
  --password <password>      app password for headless authentication
  --password-file <path>     read the app password from a file
  -h, --help                 show help
```

for example:

```sh
export WISP_APP_PASSWORD='your app password'

wisp-deploy \
  example.com \
  --path ./dist \
  --site example
```

site names are at protocol record keys. they may contain letters, numbers, `.`, `-`, `_`, `:`, or `~`, but cannot be `.` or `..`.

## files

all regular files below `--path` are deployed unless they match the built-in ignore list or `.wispignore`. symlinks and other non-regular files are skipped.

`.wispignore` uses gitignore-style patterns. the built-in list already skips version control directories, `node_modules`, virtual environments, caches, `.env` files, and `.wispignore` itself. point `--path` at the built site rather than the repository root unless you have checked everything that will be uploaded.

wisp.place currently allows up to 1,000 files, 300 mib per site, and 200 mib per file. the cli stops before uploading when a deployment exceeds one of those limits.

text files are gzipped before upload. unchanged blobs are reused from the existing manifest. uploads start with the requested concurrency and drop to two after a rate-limit response.

## tangled ci

add `WISP_APP_PASSWORD` to the spindle secrets, then use a step like this:

```yaml
when:
  - event: ["push"]
    branch: ["main"]

engine: "nixery"

environment:
  SITE_PATH: "dist"
  SITE_NAME: "example"
  WISP_HANDLE: "example.com"

caches:
  https://madoka-systems.cachix.org: "madoka-systems.cachix.org-1:nUYOriy5WXsFsO/eok8g/IgME2IT+6Vmna3itvuxJH8="

dependencies:
  - git+https://tangled.org/madoka.systems/wisp-deploy#default

steps:
  - name: deploy to wisp
    command: |
      wisp-deploy \
        "$WISP_HANDLE" \
        --path "$SITE_PATH" \
        --site "$SITE_NAME"
```

use `?ref=refs/tags/v1.1.0` to pin this release. the did-based repository url is `git+https://tangled.org/did:plc:ne3mufdifemv72zui4bqlp32`.

## license

MIT. see [`LICENSE`](LICENSE).