# Publishing with StaticDeploy

This guide is for AI agents. It explains how to put a folder of static files
online at a public URL using the StaticDeploy server at https://static.totalwebsolutions.co.

## Steps

1. Find the folder to publish. It must contain finished static files, normally
   with an `index.html` at its top level. For a project with a build step, run
   the build first and publish its output folder (often `dist`, `build` or
   `out`), not the project root.

2. Download the CLI. It needs Node.js 18 or newer and has no other dependencies.

   ```sh
   curl -fsSL https://static.totalwebsolutions.co/cli.js -o staticdeploy.cjs
   ```

3. Publish. If the user's prompt included a publish key (it starts with `sd_`),
   pass it the first time; it is remembered afterwards.

   ```sh
   node staticdeploy.cjs publish ./dist --key sd_... --json
   ```

   If the command says a publish key is needed and you were not given one, ask
   the user to open https://static.totalwebsolutions.co, press "Copy prompt", and send you
   the key from it. A person has to pass a human check there; you cannot get a
   key yourself.

   The output is one line of JSON: `{"url": "...", "updated": false, "files": 12, "expiresAt": "...", "skipped": []}`.

4. Tell the user the `url`, and when it expires if `expiresAt` is not null.

## Updating

Run the same `publish` command on the same folder again. The site is replaced
in place and the URL does not change. Pass `--new` to get a fresh URL instead.

## Other commands

- `node staticdeploy.cjs list` shows what was published from this machine.
- `node staticdeploy.cjs delete ./dist` takes a site down.

## Things to know

- Everything published is public to anyone with the link. Do not publish
  folders containing credentials or private data. The CLI skips `.env` files,
  key files, `.git` and `node_modules`, and reports what it skipped.
- Limits: 25 MB per file, 2000 files, 100 MB per site.
- You can also publish a single `.html` or `.md` file, or a `.zip`.
- The publish key and the access token for each site are stored in `~/.config/staticdeploy/sites.json`.
  Whoever has it can update or delete the site.

## Without the CLI

The HTTP API is small enough to call directly:

```sh
# 1. Create a site. Returns siteId, token, deployId and url.
#    $KEY is the publish key; the header can be left out on servers that need none.
curl -X POST -H "Authorization: Bearer $KEY" https://static.totalwebsolutions.co/api/sites

# 2. Upload each file.
curl -X PUT -H "Authorization: Bearer $TOKEN" --data-binary @index.html \
  https://static.totalwebsolutions.co/api/sites/$SITE_ID/deploys/$DEPLOY_ID/files/index.html

# 3. Go live.
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://static.totalwebsolutions.co/api/sites/$SITE_ID/deploys/$DEPLOY_ID/publish
```

To update, start a new deploy with `POST /api/sites/$SITE_ID/deploys`, upload
the complete file set to it, and publish it.