soul-cli 0.8.1 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.all-contributorsrc +9 -0
- package/.bruno/auth/folder.bru +8 -0
- package/.bruno/auth/obtain-access-token.bru +25 -0
- package/.bruno/bruno.json +6 -0
- package/.bruno/environments/local.bru +3 -0
- package/.bruno/rows/folder.bru +8 -0
- package/.bruno/rows/list-rows-with-ordering.bru +25 -0
- package/.bruno/tables/folder.bru +8 -0
- package/.bruno/tables/list-tables.bru +16 -0
- package/.env.sample +11 -2
- package/.github/dependabot.yml +9 -0
- package/.github/workflows/ci.yml +33 -0
- package/.github/workflows/npm-publish.yml +19 -6
- package/.husky/pre-commit +0 -3
- package/README.md +46 -7
- package/ROADMAP.md +154 -0
- package/assets/images/soul-RA-app.png +0 -0
- package/assets/images/soul-standalone.png +0 -0
- package/docs/extensions-examples.md +96 -16
- package/docs/self-hosting.md +54 -0
- package/docs/ws-examples.md +4 -0
- package/eslint.config.js +29 -0
- package/package.json +40 -20
- package/scripts/dev.sh +64 -0
- package/src/cli.test.js +128 -0
- package/src/config/index.js +10 -2
- package/src/config/index.test.js +120 -0
- package/src/controllers/auth/common.js +1 -16
- package/src/controllers/auth/common.test.js +23 -0
- package/src/controllers/auth/tables.js +1 -1
- package/src/controllers/auth/token.js +30 -7
- package/src/controllers/auth/user.js +20 -20
- package/src/controllers/auth/user.test.js +232 -0
- package/src/controllers/auth.test.js +445 -0
- package/src/controllers/rows.js +183 -120
- package/src/controllers/rows.test.js +119 -2
- package/src/controllers/tables.js +63 -17
- package/src/controllers/tables.test.js +185 -0
- package/src/db/index.test.js +21 -0
- package/src/extensions.js +105 -36
- package/src/extensions.test.js +340 -0
- package/src/index.js +29 -20
- package/src/index.test.js +118 -0
- package/src/middlewares/api.js +1 -1
- package/src/middlewares/api.test.js +29 -0
- package/src/middlewares/auth.js +11 -48
- package/src/middlewares/auth.test.js +105 -0
- package/src/middlewares/validation.test.js +60 -0
- package/src/schemas/index.js +3 -1
- package/src/schemas/rows.js +16 -6
- package/src/schemas/tables.js +28 -4
- package/src/server.js +83 -1
- package/src/services/authService.js +33 -3
- package/src/services/authService.test.js +115 -0
- package/src/services/rowService.js +39 -14
- package/src/services/rowService.test.js +153 -0
- package/src/services/tableService.js +15 -17
- package/src/services/tableService.test.js +190 -0
- package/src/swagger/swagger.json +4 -7
- package/src/tests/globalSetup.js +8 -1
- package/src/tests/index.js +23 -0
- package/src/utils/index.js +25 -2
- package/src/utils/index.test.js +135 -0
- package/src/utils/logger.js +15 -0
- package/src/utils/sql.js +112 -0
- package/src/utils/sql.test.js +115 -0
- package/src/websocket.js +46 -8
- package/src/websocket.test.js +121 -0
- package/.eslintignore +0 -2
- package/.eslintrc.js +0 -24
- package/src/middlewares/logger.js +0 -13
package/.all-contributorsrc
CHANGED
|
@@ -62,6 +62,15 @@
|
|
|
62
62
|
"contributions": [
|
|
63
63
|
"code"
|
|
64
64
|
]
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
"login": "thoughtsunificator",
|
|
68
|
+
"name": "Romain Lebesle",
|
|
69
|
+
"avatar_url": "https://avatars.githubusercontent.com/u/85041649?v=4",
|
|
70
|
+
"profile": "http://thoughtsunificator.me",
|
|
71
|
+
"contributions": [
|
|
72
|
+
"code"
|
|
73
|
+
]
|
|
65
74
|
}
|
|
66
75
|
],
|
|
67
76
|
"contributorsPerLine": 7,
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
meta {
|
|
2
|
+
name: obtain-access-token
|
|
3
|
+
type: http
|
|
4
|
+
seq: 1
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
post {
|
|
8
|
+
url: {{base_url}}/api/auth/token/obtain
|
|
9
|
+
body: json
|
|
10
|
+
auth: inherit
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
body:json {
|
|
14
|
+
{
|
|
15
|
+
"fields": {
|
|
16
|
+
"username": "john",
|
|
17
|
+
"password": "johns_passowrd"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
settings {
|
|
23
|
+
encodeUrl: true
|
|
24
|
+
timeout: 0
|
|
25
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
meta {
|
|
2
|
+
name: list-rows-with-ordering
|
|
3
|
+
type: http
|
|
4
|
+
seq: 1
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
get {
|
|
8
|
+
url: {{base_url}}/api/tables/:tableName/rows/?_ordering=-CustomerId.LastName&_extend=CustomerId
|
|
9
|
+
body: none
|
|
10
|
+
auth: inherit
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
params:query {
|
|
14
|
+
_ordering: -CustomerId.LastName
|
|
15
|
+
_extend: CustomerId
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
params:path {
|
|
19
|
+
tableName: Invoice
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
settings {
|
|
23
|
+
encodeUrl: true
|
|
24
|
+
timeout: 0
|
|
25
|
+
}
|
package/.env.sample
CHANGED
|
@@ -5,9 +5,18 @@ NODE_ENV=development
|
|
|
5
5
|
CORS_ORIGIN_WHITELIST=http://localhost:3000,http://127.0.0.1:3000
|
|
6
6
|
AUTH=false
|
|
7
7
|
|
|
8
|
+
# Auth cookie attributes. Defaults (lax/false) are correct for same-origin
|
|
9
|
+
# setups (e.g. `soul -S`). For a frontend hosted on a different origin
|
|
10
|
+
# talking to this API with credentials, set CORS_ORIGIN_WHITELIST to that
|
|
11
|
+
# exact origin (never *), COOKIE_SAMESITE=none, and COOKIE_SECURE=true
|
|
12
|
+
# (browsers treat localhost as trustworthy even over plain http, so this
|
|
13
|
+
# still works for local cross-origin dev).
|
|
14
|
+
COOKIE_SAMESITE=lax
|
|
15
|
+
COOKIE_SECURE=false
|
|
16
|
+
|
|
8
17
|
RATE_LIMIT_ENABLED=false
|
|
9
|
-
|
|
10
|
-
|
|
18
|
+
RATE_LIMIT_WINDOW_MS=1000
|
|
19
|
+
RATE_LIMIT_MAX_REQUESTS=10
|
|
11
20
|
|
|
12
21
|
DB=foobar.db
|
|
13
22
|
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Please see the documentation for all configuration options:
|
|
2
|
+
# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
|
|
3
|
+
|
|
4
|
+
version: 2
|
|
5
|
+
updates:
|
|
6
|
+
- package-ecosystem: "npm" # See documentation for possible values
|
|
7
|
+
directory: "/" # Location of package manifests
|
|
8
|
+
schedule:
|
|
9
|
+
interval: "weekly"
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
test:
|
|
13
|
+
strategy:
|
|
14
|
+
fail-fast: false
|
|
15
|
+
matrix:
|
|
16
|
+
os: [ubuntu-latest, macos-latest]
|
|
17
|
+
node-version: [22.x, 24.x, 26.x]
|
|
18
|
+
|
|
19
|
+
runs-on: ${{ matrix.os }}
|
|
20
|
+
|
|
21
|
+
steps:
|
|
22
|
+
- uses: actions/checkout@v4
|
|
23
|
+
|
|
24
|
+
- uses: actions/setup-node@v4
|
|
25
|
+
with:
|
|
26
|
+
node-version: ${{ matrix.node-version }}
|
|
27
|
+
cache: npm
|
|
28
|
+
|
|
29
|
+
- run: npm ci
|
|
30
|
+
|
|
31
|
+
- run: npm run lint
|
|
32
|
+
|
|
33
|
+
- run: npm run test:coverage
|
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Publishes to npm via Trusted Publishing (OIDC) -- no long-lived npm
|
|
2
|
+
# token/secret involved. Requires a matching Trusted Publisher configured
|
|
3
|
+
# on the package's npmjs.com settings: GitHub Actions, owner/repo
|
|
4
|
+
# thevahidal/soul, workflow filename `npm-publish.yml`, action `npm publish`
|
|
5
|
+
# allowed. See https://docs.npmjs.com/trusted-publishers.
|
|
6
|
+
#
|
|
2
7
|
# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
|
|
3
8
|
|
|
4
9
|
name: Node.js Package
|
|
@@ -7,17 +12,25 @@ on:
|
|
|
7
12
|
release:
|
|
8
13
|
types: [created]
|
|
9
14
|
|
|
15
|
+
permissions:
|
|
16
|
+
contents: read
|
|
17
|
+
id-token: write
|
|
18
|
+
|
|
10
19
|
jobs:
|
|
11
20
|
publish-npm:
|
|
12
21
|
runs-on: ubuntu-latest
|
|
13
22
|
steps:
|
|
14
|
-
- uses: actions/checkout@
|
|
15
|
-
- uses: actions/setup-node@
|
|
23
|
+
- uses: actions/checkout@v4
|
|
24
|
+
- uses: actions/setup-node@v4
|
|
16
25
|
with:
|
|
17
|
-
node-version:
|
|
26
|
+
node-version: 22
|
|
18
27
|
registry-url: https://registry.npmjs.org/
|
|
19
28
|
|
|
29
|
+
# Trusted Publishing needs npm CLI >=11.5.1; the version bundled with
|
|
30
|
+
# setup-node's Node 22 isn't guaranteed to be that recent.
|
|
31
|
+
- name: Check tag matches package.json version
|
|
32
|
+
run: test "v$(node -p 'require("./package.json").version')" = "${{ github.event.release.tag_name }}"
|
|
33
|
+
- run: npm install -g npm@latest
|
|
20
34
|
- run: npm ci
|
|
35
|
+
- run: npm test
|
|
21
36
|
- run: npm publish
|
|
22
|
-
env:
|
|
23
|
-
NODE_AUTH_TOKEN: ${{secrets.npm_token}}
|
package/.husky/pre-commit
CHANGED
package/README.md
CHANGED
|
@@ -8,15 +8,47 @@
|
|
|
8
8
|
[](https://justforfunnoreally.dev)
|
|
9
9
|
[](#contributors)
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Usage
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
### Docker
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
npm install -g soul-cli
|
|
17
|
-
```
|
|
15
|
+
> This is a convenient way to run Soul without worrying about your local Node.js version. Soul requires Node.js `22.x`, `23.x`, `24.x`, `25.x`, or `26.x` (see `engines` in `package.json`) since its [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) dependency requires Node 22 or newer.
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
Using the following Dockerfile:
|
|
18
|
+
|
|
19
|
+
<details>
|
|
20
|
+
<summary>Dockerfile</summary>
|
|
21
|
+
|
|
22
|
+
```nginx
|
|
23
|
+
# node:22-alpine amd64
|
|
24
|
+
FROM node@sha256:76789712cd1ae89a1225eac9077010d68987a423588042dac30446f502f1858c AS node
|
|
25
|
+
|
|
26
|
+
WORKDIR /app
|
|
27
|
+
|
|
28
|
+
ENV NODE_ENV="production"
|
|
29
|
+
|
|
30
|
+
COPY package-lock.json package.json ./
|
|
31
|
+
|
|
32
|
+
# python3/build-base are a fallback in case no prebuilt native binary matches
|
|
33
|
+
|
|
34
|
+
# this platform (e.g. non-amd64/arm64 or a libc variant without a prebuild)
|
|
35
|
+
|
|
36
|
+
RUN apk update && apk add python3 build-base && npm ci
|
|
37
|
+
|
|
38
|
+
COPY . .
|
|
39
|
+
|
|
40
|
+
CMD [ "npm", "start" ]
|
|
41
|
+
|
|
42
|
+
````
|
|
43
|
+
</details>
|
|
44
|
+
|
|
45
|
+
You can proceed [to building the application](https://docs.docker.com/get-started/workshop/02_our_app/#build-the-apps-image).
|
|
46
|
+
|
|
47
|
+
### npm
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
npm install -g soul-cli
|
|
51
|
+
````
|
|
20
52
|
|
|
21
53
|
### 1. Running Soul
|
|
22
54
|
|
|
@@ -47,6 +79,8 @@ Options:
|
|
|
47
79
|
|
|
48
80
|
```
|
|
49
81
|
|
|
82
|
+
NOTE: If `--cors` is left at its default (or explicitly set to `*`), cookie-based credentials (used for auth) are disabled on cross-origin requests, since browsers reject the combination of a wildcard origin with credentials. Pass an explicit comma-separated origin list via `--cors` to allow authenticated cross-origin requests.
|
|
83
|
+
|
|
50
84
|
Then to test Soul is working run the following command
|
|
51
85
|
|
|
52
86
|
```bash
|
|
@@ -148,7 +182,7 @@ A collection of projects that revolve around the Soul ecosystem.
|
|
|
148
182
|
git clone https://github.com/thevahidal/soul # Clone project
|
|
149
183
|
|
|
150
184
|
cp .env.sample .env # Duplicate sample environment variables
|
|
151
|
-
|
|
185
|
+
vim .env # Update the environment variables
|
|
152
186
|
|
|
153
187
|
npm install # Install dependencies
|
|
154
188
|
npm run dev # Start the dev server
|
|
@@ -168,6 +202,10 @@ npm run dev # Start the dev server
|
|
|
168
202
|
|
|
169
203
|
Make sure to replace the placeholders with the appropriate values for your environment.
|
|
170
204
|
|
|
205
|
+
## Hosting Static Content Using Soul
|
|
206
|
+
|
|
207
|
+
You can host static content using Soul by utilizing its extensions feature. This allows you to expose your static application through Soul, enabling users to access your content without hosting multiple applications. please check [this](./docs/self-hosting.md) document
|
|
208
|
+
|
|
171
209
|
## Community
|
|
172
210
|
|
|
173
211
|
[Join](https://bit.ly/soul-discord) the discussion in our Discord server and help making Soul together.
|
|
@@ -198,6 +236,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
|
|
|
198
236
|
<td align="center" valign="top" width="14.28%"><a href="https://godot.id"><img src="https://avatars.githubusercontent.com/u/40712686?v=4?s=100" width="100px;" alt="Hanz"/><br /><sub><b>Hanz</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=HanzCEO" title="Code">💻</a></td>
|
|
199
237
|
<td align="center" valign="top" width="14.28%"><a href="https://github.com/KoenDG"><img src="https://avatars.githubusercontent.com/u/1440619?v=4?s=100" width="100px;" alt="Koen De Groote"/><br /><sub><b>Koen De Groote</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=KoenDG" title="Code">💻</a></td>
|
|
200
238
|
<td align="center" valign="top" width="14.28%"><a href="https://github.com/TahaKhanAbdalli"><img src="https://avatars.githubusercontent.com/u/50602678?v=4?s=100" width="100px;" alt="Muhammad Taha Khan"/><br /><sub><b>Muhammad Taha Khan</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=TahaKhanAbdalli" title="Code">💻</a></td>
|
|
239
|
+
<td align="center" valign="top" width="14.28%"><a href="http://thoughtsunificator.me"><img src="https://avatars.githubusercontent.com/u/85041649?v=4?s=100" width="100px;" alt="Romain Lebesle"/><br /><sub><b>Romain Lebesle</b></sub></a><br /><a href="https://github.com/thevahidal/soul/commits?author=thoughtsunificator" title="Code">💻</a></td>
|
|
201
240
|
</tr>
|
|
202
241
|
</tbody>
|
|
203
242
|
</table>
|
package/ROADMAP.md
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# Soul Roadmap
|
|
2
|
+
|
|
3
|
+
This document captures where Soul is today and the direction agreed on for
|
|
4
|
+
what comes next. Written to hand off to a fresh session — it should be
|
|
5
|
+
enough context to start executing without re-deriving the "why."
|
|
6
|
+
|
|
7
|
+
## Where Soul is today
|
|
8
|
+
|
|
9
|
+
Soul started as a lighter, JS-based take on PocketBase: point it at a
|
|
10
|
+
SQLite file and get an instant REST + realtime API, with auth/authorization
|
|
11
|
+
and an extensions mechanism. It picked up some attention via Hacker News
|
|
12
|
+
and Reddit early on.
|
|
13
|
+
|
|
14
|
+
As of `main` (merged PR #240, tagged `v0.9.0`), Soul just went through a
|
|
15
|
+
full production-hardening pass:
|
|
16
|
+
|
|
17
|
+
- Fixed `npm install` failing outright on modern Node (better-sqlite3/bcrypt
|
|
18
|
+
had no prebuilds for Node 20+; both bumped, `engines` now `22.x–26.x`).
|
|
19
|
+
- Closed a real, exploitable SQL injection surface across the rows/tables
|
|
20
|
+
endpoints (identifiers are now allowlist-validated against the live
|
|
21
|
+
schema; values are always parameter-bound; regression tests prove
|
|
22
|
+
injection payloads are neutralized).
|
|
23
|
+
- Added WebSocket auth (previously anyone could subscribe to realtime
|
|
24
|
+
changes on any table regardless of the REST permission model), graceful
|
|
25
|
+
shutdown, a global error handler that doesn't leak stack traces, CORS/
|
|
26
|
+
helmet hardening.
|
|
27
|
+
- Found and fixed several real latent bugs along the way: revoked-refresh-
|
|
28
|
+
token cleanup silently never worked (comparing an INTEGER timestamp
|
|
29
|
+
against a TEXT `CURRENT_TIMESTAMP` never matched), `authService` ignored
|
|
30
|
+
its own dependency-injection parameter, extension `POST`/`PUT`/`DELETE`
|
|
31
|
+
handlers never received `db` (only `GET` did, contradicting the docs),
|
|
32
|
+
a broken rate-limit config key mismatch.
|
|
33
|
+
- CI now runs lint + tests across a Node 22/24/26 × ubuntu/macos matrix,
|
|
34
|
+
plus CodeQL.
|
|
35
|
+
- Test coverage went from ~83% to ~94% (branches ~70% → ~88%), with a
|
|
36
|
+
coverage-threshold gate enforced in CI so it can't regress silently.
|
|
37
|
+
|
|
38
|
+
**Net effect: the core (rows/tables REST API, auth, realtime, permissions)
|
|
39
|
+
is now solid and reasonably well-defended.** That's the foundation the
|
|
40
|
+
rest of this roadmap builds on — it wasn't true before this pass.
|
|
41
|
+
|
|
42
|
+
Soul Studio (a Prisma-Studio-like data browser, separate repo) exists but
|
|
43
|
+
is pre-alpha — the main README still says "not useful to work with yet."
|
|
44
|
+
|
|
45
|
+
## Strategic direction
|
|
46
|
+
|
|
47
|
+
Considered and **rejected**: pivoting Soul + Soul Studio into a broad
|
|
48
|
+
business-app suite (CRM/inventory/accounting/etc. on a shared framework).
|
|
49
|
+
Reasoning: that market's moat is years of vertical business-app logic, not
|
|
50
|
+
infrastructure, and it means competing head-on with incumbents that are
|
|
51
|
+
15+ years in with large module ecosystems and paid-support businesses.
|
|
52
|
+
It would mean abandoning Soul's current, real niche to restart as a much
|
|
53
|
+
larger, much slower-to-differentiate project — and Soul Studio is nowhere
|
|
54
|
+
near ready to be the UI layer for that anyway.
|
|
55
|
+
|
|
56
|
+
**Decided direction instead: lean into Soul as the safe, instant backend
|
|
57
|
+
for AI-agent-built apps.** This niche got more relevant, not less, as
|
|
58
|
+
agents write more backend code — the bug list above (SQL injection, a
|
|
59
|
+
missing auth check, a silently-broken rate limiter) is exactly the class
|
|
60
|
+
of mistake an LLM writing bespoke CRUD+auth code from scratch tends to
|
|
61
|
+
ship. A tool that turns "here's a SQLite file" into a safe, permissioned,
|
|
62
|
+
realtime API removes that entire failure surface.
|
|
63
|
+
|
|
64
|
+
## Roadmap
|
|
65
|
+
|
|
66
|
+
Ordered by priority / leverage. Each item should be scoped and planned
|
|
67
|
+
properly (via `/plan` or similar) when picked up — this is direction, not
|
|
68
|
+
a detailed spec.
|
|
69
|
+
|
|
70
|
+
### 1. MCP server (start here)
|
|
71
|
+
|
|
72
|
+
Smallest scope, highest signal for where Soul's actual users increasingly
|
|
73
|
+
are. Expose the already-hardened service layer as MCP tools so agents
|
|
74
|
+
(Claude Code, Cursor, etc.) can attach to a Soul-backed DB directly instead
|
|
75
|
+
of hand-rolling HTTP calls.
|
|
76
|
+
|
|
77
|
+
Tools to expose (mirroring existing REST semantics):
|
|
78
|
+
|
|
79
|
+
- `list_tables`, `get_schema`
|
|
80
|
+
- `query_rows` (reuse the existing `_filters`/`_search`/`_ordering`/
|
|
81
|
+
`_schema`/`_extend` semantics from `rows.js`)
|
|
82
|
+
- `insert_row`, `update_row`, `delete_row`
|
|
83
|
+
- `create_table` (JSON schema in, same shape as the existing REST
|
|
84
|
+
`POST /tables`)
|
|
85
|
+
|
|
86
|
+
Should sit directly on `src/services/rowService.js` /
|
|
87
|
+
`src/services/tableService.js` / `src/utils/sql.js` — no new validation
|
|
88
|
+
logic needed, just a transport layer. Open question to resolve when
|
|
89
|
+
starting: ship as a separate package, or a mode on the existing CLI
|
|
90
|
+
(e.g. `soul --mcp`)?
|
|
91
|
+
|
|
92
|
+
### 2. Make the safety properties part of the pitch
|
|
93
|
+
|
|
94
|
+
Write up the specific bug classes found and fixed in the hardening pass
|
|
95
|
+
(injection via unvalidated identifiers, the WS auth gap, the rate-limit
|
|
96
|
+
bug) as the actual argument for "safe to let an agent drive this." The
|
|
97
|
+
regression tests added during that work are the receipts.
|
|
98
|
+
|
|
99
|
+
Consider: an ongoing adversarial/fuzz test suite (random or LLM-generated
|
|
100
|
+
filter/ordering/table-name payloads) as both a visible regression guard
|
|
101
|
+
and something to point to.
|
|
102
|
+
|
|
103
|
+
### 3. LLM-native schema workflows
|
|
104
|
+
|
|
105
|
+
Soul's `createTable` API already takes a JSON schema description rather
|
|
106
|
+
than raw DDL — lean into that explicitly ("describe your schema, don't
|
|
107
|
+
write SQL"). Add incremental schema evolution (an alter-table / add-column
|
|
108
|
+
endpoint) so an agent can iterate on a schema across a conversation
|
|
109
|
+
instead of only create-once. Consider migration history/versioning if
|
|
110
|
+
this sees real use.
|
|
111
|
+
|
|
112
|
+
### 4. Soul Studio v1 — scoped, not full-featured
|
|
113
|
+
|
|
114
|
+
Target workflow: agent writes to the DB via Soul, human opens Studio to
|
|
115
|
+
inspect and correct it. Not a general-purpose admin framework.
|
|
116
|
+
|
|
117
|
+
Needs: table/row browser, inline edit, respecting the same permission
|
|
118
|
+
model as the API. Explicitly **not** in scope for v1: dashboards, complex
|
|
119
|
+
relation UIs, anything Retool-shaped — get the core loop solid first.
|
|
120
|
+
|
|
121
|
+
### 5. Scoped agent credentials
|
|
122
|
+
|
|
123
|
+
Package the existing per-table CRUD permission/role system (see
|
|
124
|
+
`authService.hasTablePermission`) as a named feature: give an agent a key
|
|
125
|
+
that can only read/write specific tables. Likely needs a lighter API-key
|
|
126
|
+
auth mode alongside the current username/password + JWT flow, scoped at
|
|
127
|
+
key-creation time to specific tables/verbs. Addresses a real, currently
|
|
128
|
+
annoying problem in agentic products (over-broad tool access).
|
|
129
|
+
|
|
130
|
+
### 6. Cheap wins
|
|
131
|
+
|
|
132
|
+
- Ship an `llms.txt`.
|
|
133
|
+
- Explicitly point agents at the already-generated OpenAPI/Swagger spec
|
|
134
|
+
(`npm run swagger-autogen`) — "give this file to your coding agent and
|
|
135
|
+
it knows how to drive the API." Most of the work already exists.
|
|
136
|
+
|
|
137
|
+
## Explicitly out of scope (for now)
|
|
138
|
+
|
|
139
|
+
- ERP-style business-app suite.
|
|
140
|
+
- General-purpose no-code app builder.
|
|
141
|
+
- Multi-database support (Postgres/MySQL) — SQLite-native is a feature of
|
|
142
|
+
this niche, not a limitation to fix.
|
|
143
|
+
|
|
144
|
+
## Starting a new session
|
|
145
|
+
|
|
146
|
+
- Codebase state: `main` is current as of `v0.9.0` / PR #240 merge.
|
|
147
|
+
- Test commands: `npm test` (fast, no coverage) / `npm run test:coverage`
|
|
148
|
+
(enforces the coverage threshold — this is what CI runs).
|
|
149
|
+
- CI: Node 22/24/26 × ubuntu/macos, plus CodeQL, on push/PR.
|
|
150
|
+
- Key files for MCP work specifically: `src/services/rowService.js`,
|
|
151
|
+
`src/services/tableService.js`, `src/utils/sql.js` (identifier
|
|
152
|
+
validation — reuse this, don't reinvent it), `src/controllers/rows.js` /
|
|
153
|
+
`src/controllers/tables.js` (existing REST-layer patterns to mirror for
|
|
154
|
+
parameter semantics).
|
|
Binary file
|
|
Binary file
|
|
@@ -6,7 +6,6 @@ Soul extensions are a way to extend the functionality of Soul. Extensions are wr
|
|
|
6
6
|
|
|
7
7
|
- API Extensions: Add new endpoints to Soul
|
|
8
8
|
|
|
9
|
-
|
|
10
9
|
## Setup Environment
|
|
11
10
|
|
|
12
11
|
To follow the below examples we need to download a sample database and also install Soul CLI.
|
|
@@ -18,6 +17,7 @@ wget https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDa
|
|
|
18
17
|
```
|
|
19
18
|
|
|
20
19
|
### Using Soul CLI
|
|
20
|
+
|
|
21
21
|
```bash
|
|
22
22
|
npm install -g soul-cli
|
|
23
23
|
soul -d ./Chinook_Sqlite.sqlite -p 8000 -e "/absolute/path/to/_extensions/"
|
|
@@ -32,49 +32,68 @@ npm install # Install dependencies
|
|
|
32
32
|
npm link # might need `sudo`
|
|
33
33
|
soul -d ./Chinook_Sqlite.sqlite -p 8000 -e "/absolute/path/to/_extensions/"
|
|
34
34
|
```
|
|
35
|
-
</details>
|
|
36
35
|
|
|
36
|
+
</details>
|
|
37
37
|
|
|
38
38
|
## Creating an API extension
|
|
39
39
|
|
|
40
|
-
To create an extension, create a new folder named `_extensions`.
|
|
40
|
+
To create an extension, create a new folder named `_extensions`. Inside it, add
|
|
41
|
+
one or more `.js` files containing your route definitions -- Soul loads
|
|
42
|
+
**every** `.js` file in the extensions directory (not just a single `api.js`),
|
|
43
|
+
and merges all their exported routes together. This lets you split routes
|
|
44
|
+
across files however makes sense for your project (e.g. `users.js`,
|
|
45
|
+
`reports.js`), instead of cramming everything into one file.
|
|
46
|
+
|
|
47
|
+
Each route definition supports:
|
|
48
|
+
|
|
49
|
+
- `method` -- any HTTP method Express supports (`GET`, `POST`, `PUT`,
|
|
50
|
+
`DELETE`, `PATCH`, ...).
|
|
51
|
+
- `path` -- the Express route path.
|
|
52
|
+
- `handler(req, res, db)` -- your route handler. `db` is always the same
|
|
53
|
+
`better-sqlite3` database instance Soul itself uses, so you can run your
|
|
54
|
+
own queries against it.
|
|
55
|
+
- `auth` (optional) -- require authentication/authorization for this route,
|
|
56
|
+
reusing the same checks Soul's core REST API uses. See
|
|
57
|
+
[Protecting extension routes with `auth`](#protecting-extension-routes-with-auth)
|
|
58
|
+
below.
|
|
41
59
|
|
|
42
60
|
```js
|
|
61
|
+
// _extensions/api.js
|
|
43
62
|
const hello = {
|
|
44
|
-
method:
|
|
45
|
-
path:
|
|
63
|
+
method: "GET",
|
|
64
|
+
path: "/api/hello-soul",
|
|
46
65
|
handler: (req, res, db) => {
|
|
47
66
|
res.status(200).json({
|
|
48
|
-
|
|
67
|
+
message: "Hello Soul!",
|
|
49
68
|
});
|
|
50
69
|
},
|
|
51
70
|
};
|
|
52
71
|
|
|
53
72
|
const timestamp = {
|
|
54
|
-
method:
|
|
55
|
-
path:
|
|
73
|
+
method: "GET",
|
|
74
|
+
path: "/api/timestamp",
|
|
56
75
|
handler: (req, res, db) => {
|
|
57
76
|
res.status(200).json({
|
|
58
|
-
|
|
77
|
+
timestamp: Date.now(),
|
|
59
78
|
});
|
|
60
79
|
},
|
|
61
80
|
};
|
|
62
81
|
|
|
63
82
|
const greetings = {
|
|
64
|
-
method:
|
|
65
|
-
path:
|
|
83
|
+
method: "POST",
|
|
84
|
+
path: "/api/greetings/:name",
|
|
66
85
|
handler: (req, res, db) => {
|
|
67
86
|
const { name } = req.params;
|
|
68
87
|
const { greeting } = req.body;
|
|
69
88
|
res.status(200).json({
|
|
70
|
-
|
|
89
|
+
message: `${greeting} ${name}!`,
|
|
71
90
|
});
|
|
72
91
|
},
|
|
73
|
-
}
|
|
92
|
+
};
|
|
74
93
|
|
|
75
94
|
const searchTables = {
|
|
76
|
-
method:
|
|
77
|
-
path:
|
|
95
|
+
method: "GET",
|
|
96
|
+
path: "/api/search-tables",
|
|
78
97
|
handler: (req, res, db) => {
|
|
79
98
|
const { q } = req.query;
|
|
80
99
|
const sql = `
|
|
@@ -103,7 +122,6 @@ module.exports = {
|
|
|
103
122
|
greetings,
|
|
104
123
|
searchTables,
|
|
105
124
|
};
|
|
106
|
-
|
|
107
125
|
```
|
|
108
126
|
|
|
109
127
|
Alright, now we can test if the extension is working:
|
|
@@ -165,3 +183,65 @@ It should return:
|
|
|
165
183
|
]
|
|
166
184
|
}
|
|
167
185
|
```
|
|
186
|
+
|
|
187
|
+
## Protecting extension routes with `auth`
|
|
188
|
+
|
|
189
|
+
By default, extension routes are public, regardless of Soul's `AUTH` setting.
|
|
190
|
+
To require authentication (and optionally authorization), add an `auth`
|
|
191
|
+
field to the route definition. It accepts:
|
|
192
|
+
|
|
193
|
+
- `true` -- the request must have a valid access token. Any authenticated
|
|
194
|
+
user is allowed in; the handler doesn't run for anyone else.
|
|
195
|
+
- `{ superuserOnly: true }` -- the request must have a valid access token
|
|
196
|
+
**and** belong to a superuser.
|
|
197
|
+
- `{ table: 'tableName' }` -- the request must have a valid access token
|
|
198
|
+
**and** have permission on `tableName` for the request's HTTP method,
|
|
199
|
+
using the same role-based permission checks Soul's core `/api/:name`
|
|
200
|
+
routes use (so a route guarded with `{ table: 'orders' }` follows
|
|
201
|
+
whatever read/write permissions the caller's role already has on the
|
|
202
|
+
`orders` table).
|
|
203
|
+
|
|
204
|
+
If `auth` is omitted, the route is public and `AUTH` has no effect on it.
|
|
205
|
+
If Soul's `AUTH` setting is off, all `auth`-guarded routes behave as if
|
|
206
|
+
`auth` were omitted (no token is required), matching how the core REST API
|
|
207
|
+
behaves when auth is disabled.
|
|
208
|
+
|
|
209
|
+
```js
|
|
210
|
+
// _extensions/admin.js
|
|
211
|
+
const purgeSessions = {
|
|
212
|
+
method: "POST",
|
|
213
|
+
path: "/api/admin/purge-sessions",
|
|
214
|
+
auth: { superuserOnly: true },
|
|
215
|
+
handler: (req, res, db) => {
|
|
216
|
+
db.prepare("DELETE FROM _sessions").run();
|
|
217
|
+
res.status(200).json({ message: "Sessions purged" });
|
|
218
|
+
},
|
|
219
|
+
};
|
|
220
|
+
|
|
221
|
+
const myOrders = {
|
|
222
|
+
method: "GET",
|
|
223
|
+
path: "/api/my-orders",
|
|
224
|
+
auth: { table: "orders" },
|
|
225
|
+
handler: (req, res, db) => {
|
|
226
|
+
// req.user is the decoded access token payload
|
|
227
|
+
const orders = db
|
|
228
|
+
.prepare("SELECT * FROM orders WHERE userId = ?")
|
|
229
|
+
.all(req.user.id);
|
|
230
|
+
res.status(200).json({ orders });
|
|
231
|
+
},
|
|
232
|
+
};
|
|
233
|
+
|
|
234
|
+
module.exports = {
|
|
235
|
+
purgeSessions,
|
|
236
|
+
myOrders,
|
|
237
|
+
};
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Calling `purge-sessions` without a token returns a `401`:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
curl -i -X POST http://localhost:8000/api/admin/purge-sessions
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Calling it with a valid, non-superuser token returns a `403`; with a
|
|
247
|
+
superuser's token, it runs the handler and returns `200`.
|