@kigo-dev/sindri 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @kigo-dev/sindri — the Sindri connector
+
+An MCP server (stdio) that turns a product manager's Claude into a builder of Kigo internal
+apps. Claude edits the app files on the PM's computer with the PM's own plan; this connector
+does everything around that: installs the toolchain, runs the app locally with an embedded
+database, publishes it at `https://<name>.sindri.kigo.dev` and keeps versions.
+
+Everything the PM reads (the `summary` of every tool result, error messages) is Spanish; tool
+names, parameters and this document are English. The contract lives in
+`docs/conector-v4-contratos.md`, section D.
+
+## Tools
+
+| Tool | Arguments | What it does |
+|---|---|---|
+| `setup` | – | Installs Node LTS and pnpm under the user's home with [fnm](https://github.com/Schniz/fnm) (no sudo), creates `~/Sindri`. Reuses an existing Node ≥ 20 + pnpm. Idempotent. |
+| `login` | – | OAuth 2.0 authorization code + PKCE (S256) with a loopback redirect, Vercel-CLI style: listens on `http://127.0.0.1:<random>/callback`, opens Identity's `authorization_endpoint` (client `sindri-connector`, public, `audience=sindri-api`), validates `state`, exchanges the code with the verifier, shows "Listo, ya entraste a Sindri" and closes. Waits up to 5 minutes. Device flow only as a fallback when no browser can be opened and discovery advertises the device grant. Tokens go to the macOS keychain (service `sindri`) or `~/.sindri/credentials.json` (0600). Refreshes silently. |
+| `create_app` | `name`, `description` | `POST /v1/apps`, downloads the personalised template into `~/Sindri/<name>`, `pnpm install`, migrates and seeds the local database. |
+| `preview` | `app` | `pnpm db:migrate` (and seed on first run), then `pnpm dev --port <free>` detached with `KIGO_ENV=local` (PGlite), waits for `/healthz`, opens the browser. Reuses a healthy preview. |
+| `publish` | `app`, `message` | `tsc --noEmit`, checks the running preview, tars the tree (without `node_modules`, `.next`, `.sindri`, `.env*`, `dist`, `.turbo`), `POST /v1/apps/<app>/publish`. On failure the published version does not change. |
+| `status` | `app` | Address and last version from the API, plus whether the local folder exists and has unpublished edits (tree hash vs `.sindri/last-published.json`). |
+| `list_apps` | – | The PM's apps, with local folder state. |
+| `versions` | `app` | Published versions, most recent first. |
+| `rollback` | `app`, `version` | `POST rollback`, then downloads that version's archive and replaces the local tree (keeps `node_modules`, `.sindri`, `.env.local`). Stops the preview first: PGlite allows one process per data dir. |
+| `share` | `app` | The Slack line. |
+
+Every result is `{ ok, summary, ...data }`. `needs_login: true` / `needs_setup: true` tell Claude
+which tool to run first. The server also ships `instructions` describing how to talk to the PM.
+
+## Install
+
+**Claude Desktop (recommended for PMs):** double-click the `sindri.mcpb` extension (built from
+`manifest.json` with `npx @anthropic-ai/mcpb pack`), accept, done. The first conversation runs
+`setup` and `login`.
+
+**Claude Code:**
+
+```
+claude mcp add sindri -- npx -y @kigo-dev/sindri
+```
+
+**Manual check without an MCP client:**
+
+```
+npx @kigo-dev/sindri status '{"app":"visitas"}'
+```
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `SINDRI_API_URL` | `https://api.sindri.kigo.dev` | Sindri API |
+| `SINDRI_ISSUER` | `https://id.kigo.dev` | Identity issuer (OpenID discovery) |
+| `SINDRI_CLIENT_ID` | `sindri-connector` | Public OAuth client |
+| `SINDRI_AUDIENCE` | `sindri-api` | Audience requested for the access token |
+| `SINDRI_HOME` | `~/Sindri` | Where app folders live |
+| `SINDRI_STATE_DIR` | `~/.sindri` | Credentials fallback, preview registry |
+| `SINDRI_CREDENTIAL_STORE` | keychain on macOS, file elsewhere | `file` forces the JSON file |
+| `SINDRI_FNM_DIR` | `~/.local/share/fnm` | Where `setup` installs Node |
+| `SINDRI_OPENER` | `open` / `xdg-open` | Browser opener; empty disables |
+
+## Development
+
+```
+pnpm install --ignore-workspace
+pnpm typecheck && pnpm test && pnpm build
+```
+
+Tests run against a fake Identity issuer (`/authorize` redirecting to the loopback, `/token`
+checking the PKCE verifier, plus the device endpoints for the fallback), a fake Sindri API and
+stub `node`/`pnpm` binaries under a temporary HOME; nothing is installed on the developer's machine.
+
+Identity must register `sindri-connector` as a PUBLIC client with `redirect_uri_globs`
+`http://127.0.0.1:*/callback` (loopback ports are random, RFC 8252 §7.3), PKCE required, grant
+types `authorization_code` and `refresh_token`.
+
+## Local layout
+
+`~/Sindri/<name>/` is the sparse root of the kigo-sindri-apps monorepo exactly as Sindri's
+archive ships it (`package.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, `tsconfig.base.json`,
+`packages/`, `apps/<owner>/<name>`), because the app uses `catalog:` and `workspace:` specifiers
+and cannot install standalone. `pnpm install` runs at that root; `preview`, `db:migrate`,
+`db:seed`, `tsc`, the tree hash, `.env.local`, `.sindri/last-published.json` and the `publish`
+tarball (paths relative to the app) all live at `apps/<owner>/<name>`. `replaceTree` swaps the
+whole root on `create_app`/`rollback` but keeps every `node_modules` and the app's `.sindri/`
+and `.env*`. The owner is the single folder under `apps/`, else the `owner` from `GET /v1/me`
+(cached in `~/.sindri/me.json`).
+
+## Local database
+
+The template runs on PGlite when `KIGO_ENV=local` and no `DATABASE_URL` is set; data lives in
+`<app>/.sindri/pglite/`. PGlite is single-process: the connector never runs migrations while a
+preview is up, and stops the preview before a rollback replaces the tree.