ci: add engine workflows (CI + tag release to npm)

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+# Lint, test, boundary and bundle checks on every PR and push to main.
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build packages
+        run: npm run build
+
+      - name: Validate (lint, test, boundary, bundle)
+        run: npm run engine:validate

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+# Publishes @kiploks/engine-* to npm via Trusted Publishing (OIDC).
+# Trigger: push tag v* (e.g. v0.2.0). VERSION file must match the tag (0.2.0).
+# Configure the same workflow filename on npmjs.com for each package.
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      # Trusted publishing requires npm CLI >= 11.5.1 (see npm trusted-publishers docs).
+      - name: Ensure npm for OIDC
+        run: npm install -g npm@^11.5.1
+
+      - name: Verify VERSION matches tag
+        run: |
+          set -euo pipefail
+          VER=$(tr -d '[:space:]' < VERSION)
+          TAG="${GITHUB_REF_NAME#v}"
+          if [ "$VER" != "$TAG" ]; then
+            echo "::error::VERSION file ($VER) must match git tag (${GITHUB_REF_NAME} -> $TAG). Run sync-versions after bumping VERSION."
+            exit 1
+          fi
+          echo "VERSION=$VER matches tag ${GITHUB_REF_NAME}"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build packages
+        run: npm run build
+
+      - name: Validate before publish
+        run: npm run engine:validate
+
+      - name: Publish to npm (workspaces)
+        run: |
+          npm publish -w @kiploks/engine-contracts \
+            -w @kiploks/engine-core \
+            -w @kiploks/engine-adapters \
+            -w @kiploks/engine-cli \
+            -w @kiploks/engine-test-vectors

README.md

@@ -5,6 +5,8 @@
 
 Deterministic **walk-forward analysis** and backtest validation engine for algorithmic trading strategies - as **TypeScript npm packages** under **Apache 2.0**.
 
+**Browse the full docs on the web:** **[kiploks.com/open-engine](https://kiploks.com/open-engine)** (same Markdown as in `docs/` below).
+
 **New here?** Read **[`docs/ENTRYPOINTS.md`](docs/ENTRYPOINTS.md)** first — it maps **which function to call** (`analyze`, `analyzeFromTrades`, `analyzeFromWindows`, CSV adapters, `mapPayloadToUnified`) and what each expects.
 
 **Main repository:** [github.com/kiploks/engine](https://github.com/kiploks/engine)

RELEASE_CHECKLIST.md

@@ -36,6 +36,8 @@ See **[`docs/OSS_PUBLIC_REPO_SYNC.md`](docs/OSS_PUBLIC_REPO_SYNC.md)** and root
 npm run sync-versions
 ```
 
+Then merge to `main`, create an annotated tag `vX.Y.Z` matching `VERSION`, and push the tag. GitHub Actions **release.yml** publishes to npm (Trusted Publishing).
+
 ## 4. Optional follow-ups
 
 - Add CI that fails when markdown references removed types (future).

docs/OSS_PUBLIC_REPO_SYNC.md

@@ -37,8 +37,9 @@ This sets every workspace `package.json` `version` and internal `@kiploks/engine
 
 After changing `VERSION`, commit, then sync, then rebuild and run checks before publishing.
 
-## Publish workflow (later)
+## CI and publish (GitHub Actions)
 
-- GitHub Actions on **this** repo (CI, npm publish).
-- npm org scope `@kiploks` and access tokens.
-- GitHub Release notes and tags (optional).
+- **CI** (`.github/workflows/ci.yml`): on every PR and push to `main` - `npm ci`, `npm run build`, `npm run engine:validate`.
+- **Release** (`.github/workflows/release.yml`): on push of tag `v*` (e.g. `v0.2.0`). The `VERSION` file must equal the tag without the `v` prefix (`0.2.0`). After bumping `VERSION`, run `npm run sync-versions`, commit, merge, then create and push the tag on that commit.
+- **npm:** publishing uses **Trusted Publishing** (OIDC) from this workflow file - no long-lived `NPM_TOKEN` in GitHub. Each `@kiploks/engine-*` package on npmjs.com must list this workflow under Trusted Publisher (filename must match: `release.yml`).
+- Optional: create a **GitHub Release** from the tag for notes; it does not affect npm publish.