@synapsor/runner 0.1.0-alpha.15 → 0.1.0-alpha.17

package/CHANGELOG.md

@@ -2,13 +2,56 @@
 
 ## Unreleased
 
+No unreleased changes yet.
+
+## 0.1.0-alpha.17
+
+### Added
+
+- Prompt-free onboarding for `onboard db` / `init` through `--yes`,
+  `--non-interactive`, and `--answers <file.json>`.
+- Friendly scripted onboarding flags: `--tenant-column`, `--id-arg`, `--patch
+  column=fixed:value|arg:name`, `--patch-bounds`, `--status-guards`,
+  `--read-description`, `--read-returns-hint`, `--handler-output`, and
+  `--emit-handler`.
+- Answers-file onboarding can emit the same artifacts as the wizard: reviewed
+  config, `.env.example`, MCP snippets, and optional handler template.
+- Guided onboarding now shows a final "what I am about to write" preview where
+  users can revise visible fields or capability names before files are written.
+- README and runner README now include a short "How An External Handler Works"
+  explanation directly after the writeback rule.
+- `events webhook` / `events push` can POST local proposal/writeback lifecycle
+  events to a local/dev/staging HTTP endpoint for review UIs or notifications.
+
+### Changed
+
+- When `--namespace` is omitted, generated capability names derive a namespace
+  from the selected table instead of defaulting to `source.*`.
+- App-owned `http_handler` and `command_handler` generated configs mark the
+  Runner source as `read_only: true` when no writer env is supplied. These
+  configs now validate without a `WRITEBACK_DISABLED` warning.
+- Direct SQL review-mode proposal capabilities still require `write_url_env`
+  readiness; missing writer env remains visible as `WRITEBACK_DISABLED`.
+- Published docs/examples no longer contain install-looking
+  `@synapsor/handler` imports. The app-owned example uses the bundled
+  `synapsor-handler.mjs` shim directly.
+
+## 0.1.0-alpha.16
+
 ### Added
 
-- `result_format: 2` for a stable MCP result envelope with
-  `ok`, `summary`, `data`, `proposal`, `error`, `evidence`,
-  `source_database_changed`, and `_meta.canonical_capability`.
+- `synapsor-runner up` for first-session review-mode bring-up. It validates
+  the local config/store, checks active store leases, summarizes model-facing
+  tools, explains direct SQL versus app-owned executor writeback, and prints
+  the next smoke, approval, apply, replay, UI, and doctor commands.
+- Guided app-owned executor setup can now write a starter handler template
+  during `init --wizard` / `start --from-env ... --mode review`.
+- `result_format: 2` for a stable MCP result envelope with `ok`, `summary`,
+  `data`, `proposal`, `error`, `evidence`, `source_database_changed`, and
+  `_meta.canonical_capability`.
 - `--result-format v1|v2` for `mcp serve`, `mcp serve --transport
-  streamable-http`, `mcp serve-streamable-http`, and the legacy JSON-RPC bridge.
+  streamable-http`, `mcp serve-streamable-http`, and the legacy JSON-RPC
+  bridge.
 - Capability config fields `description`, per-argument `description`, and
   `returns_hint`; these are surfaced in MCP tool metadata.
 - `tools list` as a first-class alias for `tools preview`, including
@@ -16,16 +59,23 @@
 - `mcp client-config --include-instructions` for Claude/Cursor/OpenAI-style
   client snippets with propose-first agent guidance.
 - `schemas/synapsor.runner.schema.json` for editor validation.
-- `docs/capability-authoring.md` and `docs/result-envelope-v2.md`.
-- RFC source docs under `docs/rfcs/`.
+- `docs/capability-authoring.md`, `docs/result-envelope-v2.md`, and RFC source
+  docs under `docs/rfcs/`.
 
 ### Changed
 
+- Handler templates, template CLI output, app-owned writeback docs, and
+  examples now carry the explicit handler security warning: app handlers own the
+  final business write and must re-check tenant/scope, conflict guards,
+  idempotency, business action, transactions, and safe receipts.
 - OpenAI-safe aliases include the canonical Synapsor capability name in
   descriptions/metadata so model-visible aliases can still be audited against
   dotted capability names.
 - v2 MCP errors redact raw driver/infra strings and map failures to a small
   safe error-code enum.
+- Release policy now keeps the stable channel gated on `up`, review-mode wizard
+  verification, handler warning coverage, clean npm install checks, and at
+  least one external developer following the README without source reading.
 
 ### Compatibility
 

package/README.md

@@ -44,6 +44,25 @@ One-row update to an existing row: Runner can do guarded direct writeback.
 Anything else, such as inserting a row, touching two tables, or emitting an
 event: your app-owned executor does it after approval.
 
+## How An External Handler Works
+
+Some changes are too rich for Runner's one-row writeback: insert a credit row,
+touch two tables, or emit an event. For those, you run a small endpoint. The
+flow is:
+
+```text
+agent proposes
+-> human approves outside MCP
+-> Runner POSTs the approved change to your endpoint
+-> your code writes it in its own transaction and returns a receipt
+```
+
+The model never touches this code. You are the last line of defense: Runner
+hands you the tenant, expected row version, and idempotency key, and your
+handler must re-check all three. Skipping those checks reintroduces
+cross-tenant writes, lost updates, or duplicate writes. Start from
+`synapsor-runner handler template ...` instead of hand-rolling the safety checks.
+
 ## Deliberate Limits
 
 Runner does not expose raw SQL, write credentials, approval tools, or commit
@@ -129,6 +148,16 @@ Your own staging DB    -> export DATABASE_URL=... then run the inspect command b
 MCP risk review        -> npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp
 ```
 
+For your own database, do this before wiring Claude, Cursor, OpenAI Agents SDK,
+or another MCP client:
+
+```text
+1. Generate the config with start/init/onboard.
+2. Run tools preview to confirm no raw SQL or write credentials are exposed.
+3. Run smoke call against one generated inspect tool.
+4. Only then run up --serve or mcp serve.
+```
+
 `synapsor-runner` is the public command for this OSS runner. `synapsor` is
 reserved for the Synapsor Cloud CLI.
 
@@ -223,10 +252,60 @@ The end-to-end shape is:
 The generated config is just the safety contract. A small reviewed version
 looks like this:
 
+Bring the generated review-mode workspace up with one command:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner up \
+  --serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+`up` validates the config/store, summarizes model-facing tools, shows whether
+proposal tools use direct SQL writeback or app-owned executors, checks active
+store leases, and prints the next smoke, approve, apply, replay, UI, and doctor
+commands. By default, `up` is guidance-only. Use `up --serve` to start the
+standard Streamable HTTP MCP server after the checklist; use `--dry-run` to
+rehearse without starting it. For app-owned executor configs, add
+`--with-handler` to run the handler doctor before serving.
+
+For CI, shell scripts, or an LLM driving the setup, use the prompt-free path:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner onboard db \
+  --from-env DATABASE_URL \
+  --schema public \
+  --table invoices \
+  --mode review \
+  --tenant-column tenant_id \
+  --primary-key id \
+  --conflict-column updated_at \
+  --namespace billing \
+  --object-name invoice \
+  --id-arg invoice_id \
+  --visible-columns id,tenant_id,late_fee_cents,waiver_reason,updated_at \
+  --patch late_fee_cents=fixed:0,waiver_reason=arg:reason \
+  --patch-bounds late_fee_cents=0:5500 \
+  --write-url-env SYNAPSOR_DATABASE_WRITE_URL \
+  --yes
+```
+
+If `--namespace` is omitted, Runner derives a namespace from the table name
+instead of creating `source.*` tools. Use `--read-tool` and `--proposal-tool`
+when you need exact model-facing names.
+
+For app-owned writeback, replace `--write-url-env ...` with
+`--writeback http_handler --handler-url-env APP_WRITEBACK_URL --emit-handler`.
+Runner marks that source as read-only unless you explicitly pass a writer env,
+so `config validate` does not warn that direct SQL writeback is disabled.
+You can also pass `--answers ./answers.json --yes` for a fully declarative
+setup file.
+
 ```json
 {
   "version": 1,
   "mode": "review",
+  "result_format": 2,
   "sources": {
     "app_postgres": {
       "engine": "postgres",
@@ -300,7 +379,8 @@ trusted context -> capability -> MCP tool
 
 It asks which table/view backs the context, which tenant/scope column and
 backend session env vars are trusted, which fields are visible, and what
-semantic capability name to expose.
+semantic capability name to expose. Before writing files, it shows a final
+preview and lets you revise visible fields or capability names.
 
 ```bash
 npx -y -p @synapsor/runner@alpha synapsor-runner init \
@@ -369,6 +449,17 @@ synapsor-runner mcp serve-streamable-http \
   --alias-mode openai
 ```
 
+You can also start the same review-mode server through the safer startup
+checklist:
+
+```bash
+synapsor-runner up --serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
 Equivalent unified command:
 
 ```bash
@@ -457,6 +548,22 @@ For a longer local session, you can install the alpha package explicitly:
 npm install -g @synapsor/runner@alpha
 ```
 
+## Stable Compatibility Promise
+
+Until the first stable `0.1.0` tag is published, install with `@alpha` or an
+exact alpha version. Do not treat the untagged `latest` dist-tag as stable yet.
+
+After `0.1.0` is promoted to `latest`, Synapsor Runner will keep the documented
+`synapsor-runner` binary, `synapsor.runner.json` schema version `1`, result
+envelope v2, stdio MCP, Streamable HTTP MCP, MCP client snippets, proposal/
+approval/writeback inspection commands, direct SQL writeback contract, and
+app-owned executor contract compatible through the `0.1.x` line unless a
+release note marks a deprecation first.
+
+Stable does not mean production SLA, hosted Cloud features, compliance
+certification, physical Postgres/MySQL branching, generic SQL writeback, or
+support for undocumented local SQLite internals.
+
 ## Runtime Flow
 
 The local runner keeps the model-facing tool call separate from approval and
@@ -541,6 +648,8 @@ relying on `latest`:
 
 ```bash
 synapsor-runner activity search --tenant acme --object invoice:INV-3001
+synapsor-runner events tail --store ./.synapsor/local.db
+synapsor-runner events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created --store ./.synapsor/local.db
 synapsor-runner proposals list --tenant acme --object invoice:INV-3001 --status approved
 synapsor-runner evidence show ev_...
 synapsor-runner query-audit list --evidence ev_...
@@ -573,11 +682,17 @@ Inspect or compact the local ledger:
 
 ```bash
 synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner events tail --store ./.synapsor/local.db --follow
+synapsor-runner events webhook --url-env SYNAPSOR_EVENT_WEBHOOK_URL --auth-token-env SYNAPSOR_EVENT_WEBHOOK_TOKEN --follow --store ./.synapsor/local.db
 synapsor-runner store vacuum --store ./.synapsor/local.db
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
 synapsor-runner store reset --store ./.synapsor/local.db --yes
 ```
 
+`events webhook` is a local/dev/staging convenience for review UIs, Slack
+bridges, or app-local notifications. It POSTs one redacted local event envelope
+per lifecycle event; it is not a hosted central ledger.
+
 This is local indexed search for local/dev/staging usage. It is not external
 database time travel, not cross-runner search, and not hosted compliance
 retention.
@@ -588,10 +703,18 @@ Use direct guarded DB writeback for simple local/staging single-row updates. If
 your application service already owns business writes, configure an
 `http_handler` or `command_handler` executor. Approval still happens outside
 MCP, and the handler returns an applied/conflict/failed receipt for replay.
+
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 Starter handlers are included under `examples/app-owned-writeback`.
 The packaged app-owned billing example also includes a bundled
-`synapsor-handler.mjs` helper shim; `@synapsor/handler` is not published as a
-standalone npm package yet.
+`synapsor-handler.mjs` helper shim. There is no separate handler package to
+install.
 You can also generate a starter handler directly:
 
 ```bash

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAmB3P,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAoS3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkD1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA6OjB;AA4uDD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAmB3P,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA4U3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmD1D;AA+DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2TjB;AAo7DD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}