# saltcorn — dev environment for the dev-deploy plugin

This project root holds the `dev-deploy` Saltcorn plugin and the launcher
scripts + per-instance state needed to develop and test it against two local
Saltcorn instances. Upstream Saltcorn lives in `saltcorn/` (a sibling git
checkout managed independently from this project).

## Layout

```
saltcorn/                    project root (this git repo)
├── dev-deploy/              the plugin (Saltcorn plugin, sc_plugin_api_version 1)
├── startServer.sh           launch MAIN instance on :3000
├── startServerTest.sh       launch TEST instance on :3001
├── devServer.sh             launch MAIN under `saltcorn dev:serve` (tsc watch)
├── installSaltcorn.sh       reproduce this dev environment from scratch
├── .dev-state/              MAIN instance: env.sh, saltcorn.sqlite, files/, sessions
├── .dev-state-test/         TEST instance: same shape, separate port + secret
└── saltcorn/                upstream Saltcorn checkout (its own .git, gitignored here)
```

The upstream subfolder, both `.dev-state*` directories, and `node_modules/`
are all gitignored — only the plugin + scripts + this README are tracked.

## Prerequisites

- `git`, `curl`
- `nvm` (auto-installed at `~/.nvm` if missing) → Node 20
- `git-lfs` for the `.gitattributes` LFS filters (`git lfs install` once per clone)

`installSaltcorn.sh` handles nvm + Node 20 install for you.

## Fresh install

```bash
./installSaltcorn.sh [destination]    # default: ./saltcorn
```

Clones upstream Saltcorn into `<dest>/saltcorn/`, runs `npm install` + `npm
run tsc`, generates `<dest>/.dev-state/env.sh` with a fresh session secret,
initializes the SQLite schema, creates the admin user, and writes
`<dest>/startServer.sh`.

The script sets up the **MAIN** instance only. To add the **TEST** instance,
duplicate `.dev-state/` as `.dev-state-test/`, edit its `env.sh` to use a new
`SALTCORN_SESSION_SECRET` and add `export SALTCORN_PORT="3001"`, then:

```bash
source .dev-state-test/env.sh
saltcorn reset-schema -f
saltcorn create-user -a -e admin@local -p AdminP@ss1
```

The reference `.dev-state-test/env.sh` already in this repo shows the exact
pattern.

## Running

```bash
./startServer.sh        # MAIN  → http://localhost:3000/
./startServerTest.sh    # TEST  → http://localhost:3001/
./devServer.sh          # MAIN under `saltcorn dev:serve` (nodemon + tsc watch)
```

Login on either instance: `admin@local` / `AdminP@ss1`.

Each `startServer*.sh` runs `saltcorn install-plugin -d ./dev-deploy` on every
boot, so edits to `dev-deploy/` go live on the next restart.

## The dev-deploy plugin

`dev-deploy/` migrates Saltcorn metadata (tables, fields, views, pages,
triggers, roles, library, tags, constraints, files, page groups, workflow
steps, plus selected config keys and plugin configuration) across Dev/Test/Prod
environments via an append-only ops journal with stable cross-environment
UUIDs and HMAC-authenticated peer endpoints. Concurrent edits surface as
conflicts in the admin UI with theirs/mine/per-field-merge resolution. User
row data is left alone unless an admin explicitly marks a table as `managed`
or `starter`.

Admin UI: `/admin/dev-deploy/` (logged in as an admin). Machine API:
`/dev-deploy/api/{journal,ingest,file/:uuid,health}` (HMAC-signed peer requests).

## Tests

```bash
# Both servers must be running first.
./startServer.sh & ./startServerTest.sh &
cd dev-deploy && npm test
```

Runs `dev-deploy/test/e2e.js` — ~50+ end-to-end tests covering pairing,
promote, pull, conflict resolution, constraints, files, page groups,
workflow steps, config propagation, managed/starter row data, revert, and
machine-endpoint security. Tests run in order and share state; don't reorder.

`test/sc-exec.js` is a shim used by the tests to run JS against Saltcorn's
models with full `require()` access (saltcorn's built-in `run-js` uses a vm
sandbox that hides Field/TableConstraint/File/etc.).

## Notes

- **Per-instance `sessions.sqlite`.** Saltcorn's SQLite session store writes
  `sessions.sqlite` at process cwd (`packages/server/routes/utils.js`).
  `startServer.sh` and `startServerTest.sh` `cd` into their respective state
  directory before `exec saltcorn serve`, so each instance gets its own
  sessions DB. `devServer.sh` cannot do this (its `dev:serve` runs `npm run
  tsc` which needs cwd=upstream root), so its sessions land in
  `saltcorn/sessions.sqlite` — don't run `devServer.sh` and `startServer.sh`
  against the MAIN instance simultaneously.

- **`SALTCORN_SESSION_SECRET` is the pairing identity.** dev-deploy derives
  its at-rest encryption key (KEK) for peer secrets via HKDF from this value.
  Rotating it invalidates every peer pairing on the instance. The secret is
  generated once per instance and persisted in that instance's `env.sh`.

- **Upstream Saltcorn updates.** Pull from upstream via
  `git -C saltcorn pull` — the project root is a separate repo and doesn't
  see those commits. After a pull, you may need `npm install && npm run tsc`
  inside `saltcorn/`.