soul-cli 0.9.3 → 0.10.0

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.
@@ -0,0 +1,8 @@
1
+ ## What and why
2
+
3
+ <!-- Short description of the change. -->
4
+
5
+ > **PR title must follow [Conventional Commits](https://www.conventionalcommits.org):** `feat: ...` (minor), `fix: ...` / `perf: ...` (patch), `feat!: ...` (breaking), or `docs:` / `chore:` / `ci:` / `test:` / `refactor:` (no release). The title becomes the commit on `main` and decides the next version.
6
+
7
+ - [ ] Tests added or updated
8
+ - [ ] Docs / `.env.sample` updated if behavior or config changed
@@ -0,0 +1,27 @@
1
+ # release-please reads the squash-merge commit, which is the PR title.
2
+ name: PR title
3
+
4
+ on:
5
+ pull_request_target:
6
+ types: [opened, edited, synchronize, reopened]
7
+
8
+ permissions:
9
+ pull-requests: read
10
+
11
+ jobs:
12
+ conventional-title:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: amannn/action-semantic-pull-request@v5
16
+ env:
17
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
18
+ with:
19
+ types: |
20
+ feat
21
+ fix
22
+ perf
23
+ docs
24
+ chore
25
+ ci
26
+ test
27
+ refactor
@@ -0,0 +1,44 @@
1
+ # Publishes to npm via Trusted Publishing (OIDC), no npm token involved.
2
+ # The Trusted Publisher on npmjs.com must point at workflow file `release.yml`.
3
+ # Publishing lives here because releases created with GITHUB_TOKEN don't
4
+ # trigger other workflows.
5
+
6
+ name: Release
7
+
8
+ on:
9
+ push:
10
+ branches: [main]
11
+
12
+ permissions:
13
+ contents: write
14
+ pull-requests: write
15
+ id-token: write
16
+
17
+ jobs:
18
+ release-please:
19
+ runs-on: ubuntu-latest
20
+ outputs:
21
+ release_created: ${{ steps.release.outputs.release_created }}
22
+ tag_name: ${{ steps.release.outputs.tag_name }}
23
+ steps:
24
+ - id: release
25
+ uses: googleapis/release-please-action@v4
26
+
27
+ publish-npm:
28
+ needs: release-please
29
+ if: needs.release-please.outputs.release_created == 'true'
30
+ runs-on: ubuntu-latest
31
+ steps:
32
+ - uses: actions/checkout@v4
33
+ with:
34
+ ref: ${{ needs.release-please.outputs.tag_name }}
35
+ - uses: actions/setup-node@v4
36
+ with:
37
+ node-version: 24
38
+ registry-url: https://registry.npmjs.org/
39
+
40
+ # Trusted Publishing needs npm CLI >=11.5.1
41
+ - run: npm install -g npm@latest
42
+ - run: npm ci
43
+ - run: npm test
44
+ - run: npm publish
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.10.0"
3
+ }
package/AGENTS.md ADDED
@@ -0,0 +1,31 @@
1
+ # Soul
2
+
3
+ SQLite REST and realtime (WebSocket) server. Published to npm as `soul-cli` (CLI: `soul`). Node 22/24/26, CommonJS, Express 5, better-sqlite3.
4
+
5
+ ## Commands
6
+
7
+ - `npm run dev` — regenerate swagger, run with nodemon
8
+ - `npm test` — jest (needs no setup; env vars are set in the script)
9
+ - `npm run test:coverage` — enforces thresholds in `package.json` (`jest.coverageThreshold`)
10
+ - `npm run lint` / `npm run format` — eslint / prettier
11
+ - `npm run swagger-autogen` — regenerates `src/swagger/swagger.json`; commit it when routes change
12
+ - `scripts/dev.sh` — local instance with a ready superuser
13
+
14
+ A husky pre-commit hook runs the full test suite and lint-staged.
15
+
16
+ ## Layout (`src/`)
17
+
18
+ Request flow: `routes/` → `middlewares/` (+ `schemas/` Joi validation) → `controllers/` → `services/` → `db/`.
19
+
20
+ - `controllers/auth/` — users, roles, tokens
21
+ - `extensions.js` — user-provided extensions (`docs/extensions-examples.md`)
22
+ - `websocket.js` — realtime; `cli.js` / `commands.js` — CLI
23
+ - `config/` — env-driven config; new env vars go in `.env.sample` and `README.md`
24
+ - Tests live next to the code as `*.test.js`; shared helpers in `src/tests/`
25
+
26
+ ## Conventions
27
+
28
+ - Single quotes, 2-space indent, prettier-formatted. Few comments.
29
+ - Add or update tests with every change; keep coverage above the thresholds.
30
+ - Commits and PR titles use conventional prefixes: `feat:`, `fix:`, `perf:`, `docs:`, `chore:`, `ci:`, `test:`, `refactor:`. Breaking changes use `feat!:` or a `BREAKING CHANGE:` footer. These drive the version bump; `pr-title.yml` checks PR titles (squash-merge commit message).
31
+ - Don't edit `version` in `package.json` by hand. release-please opens a release PR from merged commits; merging it tags, creates the GitHub Release and publishes to npm (`.github/workflows/release.yml`). Force a version with a `Release-As: x.y.z` commit footer.
package/CHANGELOG.md ADDED
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ ## [0.10.0](https://github.com/thevahidal/soul/compare/soul-cli-v0.9.4...soul-cli-v0.10.0) (2026-11-16)
4
+
5
+
6
+ ### Features
7
+
8
+ * add global error handling, graceful shutdown, WebSocket auth, CORS/helmet ([e8c6c7b](https://github.com/thevahidal/soul/commit/e8c6c7b2bfe5f671974c785107cb652e62843d14))
9
+ * **core/cli:** Added `-S` flag ([654c1f5](https://github.com/thevahidal/soul/commit/654c1f598ed288e2d58c2284697d962f57c615ba))
10
+ * **core:** Integrated soul-studio ([60f240f](https://github.com/thevahidal/soul/commit/60f240f6a695ccf9e322a892f1d2ee6606eaee40))
11
+ * expose foreign key info on GET /api/tables/:name ([b3eff42](https://github.com/thevahidal/soul/commit/b3eff42c471c36f6927ceaceade17e2d1ff8a4f0))
12
+ * harden extensions with multi-file loading, opt-in auth, generic methods ([e832b94](https://github.com/thevahidal/soul/commit/e832b9460292710f8cfed6e0bec35b77fa846d6d))
13
+ * make auth cookie SameSite/Secure configurable ([1a9ac43](https://github.com/thevahidal/soul/commit/1a9ac432aae6ce63a70b246664ebc568c18943b4))
14
+ * **npm-publish:** Added proper ci, build, publish procedure ([82cf9d4](https://github.com/thevahidal/soul/commit/82cf9d42230dfa0ee78d17f3ef4cb3f78922d021))
15
+ * **npm-publish:** Added proper ci, build, publish procedure ([553b7be](https://github.com/thevahidal/soul/commit/553b7be19915afd3e95d95452a527cb9c8225ffd))
16
+
17
+
18
+ ### Bug Fixes
19
+
20
+ * **ci:** drop Node 20 from engines/CI matrix, unsupported by better-sqlite3 13 ([35b63ed](https://github.com/thevahidal/soul/commit/35b63ed49a3d649eece7cda8cc1ae6c267445f39))
21
+ * **core:** Fixed Soul Studio startup misconfiguration ([2b39777](https://github.com/thevahidal/soul/commit/2b3977759b78fb2c3a3a86991273f843931bfa7e))
22
+ * correct _users_roles unique constraint to (user_id, role_id) ([021c058](https://github.com/thevahidal/soul/commit/021c058ee825db17d9e9c844b936dbd0fad4f3a7))
23
+ * correct _users_roles unique constraint to (user_id, role_id) ([c06b403](https://github.com/thevahidal/soul/commit/c06b4039e600176e96400ce21ef0d2a6f12a3ea4))
24
+ * don't reject requests over an unrelated cookie the browser sends ([a99a329](https://github.com/thevahidal/soul/commit/a99a3296d8acd15edc8760a01d644fe3627241b7))
25
+ * give every JWT a unique jti to prevent cross-session revocation ([27f920e](https://github.com/thevahidal/soul/commit/27f920ea3a0c076bea1d1fa79fce68c5c52ba70c))
26
+ * keep yargs on 17 (v18 is ESM-only, breaks Jest on Node 22) ([a908687](https://github.com/thevahidal/soul/commit/a90868725282e2f2906a8a1102e0212baac7ad71))
27
+ * mount Studio at root and filter by path, not app.use('/studio', ...) ([acb66d9](https://github.com/thevahidal/soul/commit/acb66d911b355847c9bb59e4b52605f1da748135))
28
+ * mount Studio at root and filter by path, not app.use('/studio', ...) ([8f1b2fa](https://github.com/thevahidal/soul/commit/8f1b2fac7d80e1584fb375770c3072dd12c7972c))
29
+ * **npm-publish:** Removed `needs` key ([51a64cf](https://github.com/thevahidal/soul/commit/51a64cf103ccf0b89d175573ecf89923ad9d43cc))
30
+ * **npm-publish:** Removed `needs` key ([cdef494](https://github.com/thevahidal/soul/commit/cdef4943ba4dcb5ba0b10f99b6ca7ada3efe023c))
31
+ * **security:** address CodeQL findings on workflow permissions and PRAGMA/DROP ([97ae630](https://github.com/thevahidal/soul/commit/97ae6305be0ddd866a0ab3f7e6abdf6569464409))
32
+ * **security:** close SQL injection surface, validate identifiers against schema ([efeb8d1](https://github.com/thevahidal/soul/commit/efeb8d1152a0f0d8bfbf4c0dfd705aa4aae56fa7))
33
+ * **security:** eliminate PRAGMA identifier interpolation via table-valued functions ([aca2756](https://github.com/thevahidal/soul/commit/aca27566094d677a622edf5f41c8fe129cd4c8d3))
34
+ * unblock npm install, fix startup race, and rate-limit config bug ([e3b4f16](https://github.com/thevahidal/soul/commit/e3b4f16ac84fe697606085c9726b42a7c102df16))
35
+ * updatesuperuser crashes when setting --is_superuser via SQLite bind ([f5c3038](https://github.com/thevahidal/soul/commit/f5c30389d3e701314998229a2dee19e1232d855b))
package/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
package/README.md CHANGED
@@ -12,14 +12,14 @@
12
12
 
13
13
  ### Docker
14
14
 
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.
15
+ > This is a convenient way to run Soul without worrying about your local Node.js version. Soul requires Node.js `22.x`, `24.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.
16
16
 
17
17
  Using the following Dockerfile:
18
18
 
19
19
  <details>
20
20
  <summary>Dockerfile</summary>
21
-
22
- ```nginx
21
+
22
+ ```nginx
23
23
  # node:22-alpine amd64
24
24
  FROM node@sha256:76789712cd1ae89a1225eac9077010d68987a423588042dac30446f502f1858c AS node
25
25
 
@@ -39,7 +39,8 @@ COPY . .
39
39
 
40
40
  CMD [ "npm", "start" ]
41
41
 
42
- ````
42
+ ```
43
+
43
44
  </details>
44
45
 
45
46
  You can proceed [to building the application](https://docs.docker.com/get-started/workshop/02_our_app/#build-the-apps-image).
@@ -48,7 +49,7 @@ You can proceed [to building the application](https://docs.docker.com/get-starte
48
49
 
49
50
  ```bash
50
51
  npm install -g soul-cli
51
- ````
52
+ ```
52
53
 
53
54
  ### 1. Running Soul
54
55
 
package/SECURITY.md ADDED
@@ -0,0 +1,19 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ Only the latest release receives security fixes.
6
+
7
+ | Version | Supported |
8
+ | -------- | ------------------ |
9
+ | 0.9.x | :white_check_mark: |
10
+ | < 0.9 | :x: |
11
+
12
+ ## Reporting a Vulnerability
13
+
14
+ Please do not open a public issue. Report it privately through GitHub:
15
+ https://github.com/thevahidal/soul/security/advisories/new
16
+
17
+ You can expect an initial response within a few days. If the report is accepted,
18
+ we will work on a fix and publish it in a new release with credit to the reporter
19
+ (if wanted). If it is declined, we will explain why.
package/package.json CHANGED
@@ -1,20 +1,20 @@
1
1
  {
2
2
  "name": "soul-cli",
3
- "version": "0.9.3",
3
+ "version": "0.10.0",
4
4
  "description": "A SQLite REST and Realtime server",
5
5
  "main": "src/server.js",
6
6
  "bin": {
7
7
  "soul": "./src/server.js"
8
8
  },
9
9
  "engines": {
10
- "node": "22.x || 23.x || 24.x || 25.x || 26.x"
10
+ "node": "22.x || 24.x || 26.x"
11
11
  },
12
12
  "scripts": {
13
13
  "start": "node src/server.js",
14
14
  "dev": "npm run swagger-autogen && cross-env NO_CLI=true nodemon src/server.js",
15
15
  "cli": "nodemon src/server.js --database foobar.db",
16
16
  "swagger-autogen": "cross-env NO_CLI=true node src/swagger/index.js",
17
- "test": "cross-env CI=true NODE_ENV=test NO_CLI=true DB=test.db CORE_PORT=8001 AUTH=true TOKEN_SECRET=test-only-ci-secret-0123456789 INITIAL_USER_USERNAME=admin INITIAL_USER_PASSWORD=Str0ngTestPw!1 jest --testTimeout=10000 --runInBand --forceExit",
17
+ "test": "cross-env NODE_OPTIONS=--experimental-vm-modules CI=true NODE_ENV=test NO_CLI=true DB=test.db CORE_PORT=8001 AUTH=true TOKEN_SECRET=test-only-ci-secret-0123456789 INITIAL_USER_USERNAME=admin INITIAL_USER_PASSWORD=Str0ngTestPw!1 jest --testTimeout=10000 --runInBand --forceExit",
18
18
  "test:coverage": "npm test -- --coverage --coverageProvider=v8",
19
19
  "prepare": "husky",
20
20
  "lint": "eslint . --fix --max-warnings=0",
@@ -33,23 +33,23 @@
33
33
  "dependencies": {
34
34
  "bcrypt": "^6.0.0",
35
35
  "better-sqlite3": "^13.0.3",
36
- "body-parser": "^1.20.2",
36
+ "body-parser": "^2.4.0",
37
37
  "check-password-strength": "^2.0.7",
38
- "cookie": "^0.7.2",
38
+ "cookie": "^2.0.2",
39
39
  "cookie-parser": "^1.4.6",
40
40
  "cors": "^2.8.5",
41
41
  "dotenv": "^17.4.2",
42
42
  "express": "^5.1.0",
43
- "express-rate-limit": "^8.6.1",
43
+ "express-rate-limit": "^8.7.4",
44
44
  "express-winston": "^4.2.0",
45
45
  "helmet": "^8.3.0",
46
46
  "joi": "^18.2.3",
47
47
  "jsonwebtoken": "^9.0.3",
48
48
  "soul-studio": "^0.0.3",
49
- "swagger-ui-express": "^4.6.1",
49
+ "swagger-ui-express": "^5.0.1",
50
50
  "winston": "^3.19.0",
51
51
  "ws": "^8.21.3",
52
- "yargs": "^17.7.1"
52
+ "yargs": "^17.7.3"
53
53
  },
54
54
  "devDependencies": {
55
55
  "@eslint/js": "^10.0.1",
@@ -61,8 +61,8 @@
61
61
  "jest": "^30.4.2",
62
62
  "lint-staged": "^17.3.0",
63
63
  "nodemon": "^3.1.3",
64
- "prettier": "3.1.0",
65
- "supertest": "^7.1.4",
64
+ "prettier": "3.9.6",
65
+ "supertest": "^7.3.2",
66
66
  "swagger-autogen": "^2.23.1"
67
67
  },
68
68
  "jest": {
@@ -0,0 +1,10 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
3
+ "packages": {
4
+ ".": {
5
+ "release-type": "node",
6
+ "package-name": "soul-cli",
7
+ "bump-minor-pre-major": true
8
+ }
9
+ }
10
+ }
package/src/index.js CHANGED
@@ -31,6 +31,14 @@ const { runCLICommands } = require('./commands');
31
31
  const app = express();
32
32
 
33
33
  app.use(bodyParser.json());
34
+ // body-parser v2 leaves req.body undefined when there is no body (v1 set {}).
35
+ // The request validators expect `body` to be present, so keep the v1 behaviour.
36
+ app.use((req, res, next) => {
37
+ if (req.body === undefined) {
38
+ req.body = {};
39
+ }
40
+ next();
41
+ });
34
42
  app.use(cookieParser());
35
43
  app.use(helmet());
36
44
 
package/src/server.js CHANGED
@@ -12,9 +12,8 @@ const { authConstants } = require('./constants');
12
12
 
13
13
  if (config.startWithStudio) {
14
14
  (async () => {
15
- const { handler: soulStudioHandler } = await import(
16
- 'soul-studio/build/handler.js'
17
- );
15
+ const { handler: soulStudioHandler } =
16
+ await import('soul-studio/build/handler.js');
18
17
  // Deliberately not `app.use('/studio', soulStudioHandler)`: Express
19
18
  // strips the mount prefix from `req.url` before invoking a path-mounted
20
19
  // middleware, but soul-studio's adapter-node build has `paths.base:
@@ -10,7 +10,7 @@ const dropTestTable = (table = 'users') => {
10
10
  const dropTestDatabase = async (path = 'test.db') => {
11
11
  // delete test database file e.g. test.db
12
12
  try {
13
- await unlink(path), console.log(`successfully deleted ${path}`);
13
+ (await unlink(path), console.log(`successfully deleted ${path}`));
14
14
  } catch (error) {
15
15
  console.error('there was an error:', error);
16
16
  }
package/src/websocket.js CHANGED
@@ -1,5 +1,4 @@
1
1
  const { WebSocketServer } = require('ws');
2
- const cookie = require('cookie');
3
2
 
4
3
  const db = require('./db/index');
5
4
  const config = require('./config/index');
@@ -50,7 +49,9 @@ wss.on('connection', async function (ws, request) {
50
49
  // REST API -- unauthenticated/unauthorized clients must not be able to
51
50
  // subscribe to row changes on a table they can't read via the REST API.
52
51
  if (config.auth) {
53
- const cookies = cookie.parse(request.headers.cookie || '');
52
+ // cookie v2 is ESM-only, so it is loaded lazily here.
53
+ const { parseCookie } = await import('cookie');
54
+ const cookies = parseCookie(request.headers.cookie || '');
54
55
  const accessToken = cookies.accessToken;
55
56
 
56
57
  if (!accessToken) {
@@ -1,36 +0,0 @@
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
- #
7
- # For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
8
-
9
- name: Node.js Package
10
-
11
- on:
12
- release:
13
- types: [created]
14
-
15
- permissions:
16
- contents: read
17
- id-token: write
18
-
19
- jobs:
20
- publish-npm:
21
- runs-on: ubuntu-latest
22
- steps:
23
- - uses: actions/checkout@v4
24
- - uses: actions/setup-node@v4
25
- with:
26
- node-version: 22
27
- registry-url: https://registry.npmjs.org/
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
34
- - run: npm ci
35
- - run: npm test
36
- - run: npm publish