release: v0.4.0

.agents/skills/design-contracts/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: design-contracts
+description: Enforces smriti's three design contracts (observability, dry-run, versioning) when writing or modifying CLI command handlers or JSON output.
+---
+
+# smriti Design Contract Guardrails
+
+This skill activates whenever you are **adding or modifying a CLI command**,
+**changing JSON output**, **touching telemetry/logging code**, or **altering
+config defaults** in the smriti project.
+
+---
+
+## Contract 1 — Dry Run
+
+### Mutating commands MUST support `--dry-run`
+
+The following commands write to disk, the database, or the network. Every one of
+them **must** honour `--dry-run`:
+
+| Command      | Expected guard pattern                                                        |
+| ------------ | ----------------------------------------------------------------------------- |
+| `ingest`     | `const dryRun = hasFlag(args, "--dry-run");` then no DB/file writes when true |
+| `embed`      | same                                                                          |
+| `categorize` | same                                                                          |
+| `tag`        | same                                                                          |
+| `share`      | same                                                                          |
+| `sync`       | same                                                                          |
+| `context`    | already implemented — keep it                                                 |
+
+When `--dry-run` is active:
+
+- `stdout` must describe **what would happen** (e.g. `Would ingest N sessions`).
+- `stderr` must note what was skipped (`No changes were made (--dry-run)`).
+- Exit code follows normal success/error rules — dry-run is NOT an error.
+- If `--json` is also set, the output envelope must include
+  `"meta": { "dry_run": true }`.
+
+### Read-only commands MUST reject `--dry-run`
+
+These commands never mutate state. If they receive `--dry-run`, they must print
+a usage error and `process.exit(1)`:
+
+`search`, `recall`, `list`, `status`, `show`, `compare`, `projects`, `team`,
+`categories`
+
+---
+
+## Contract 2 — Observability / Telemetry
+
+### Never log user content
+
+The following are **forbidden** in any `console.log`, `console.error`, or
+log/audit output:
+
+- Message content (`.content`, `.text`, `.body`)
+- Query strings passed by the user
+- Memory text or embedding data
+- File paths provided by the user (as opposed to system-derived paths)
+
+✅ OK to log: command name, exit code, duration, session IDs, counts, smriti
+version.
+
+### Telemetry default must be OFF
+
+- `SMRITI_TELEMETRY` must default to `0`/`false`/`"off"` — never `1`.
+- Telemetry calls must be guarded: `if (telemetryEnabled) { ... }`.
+- Any new telemetry signal must be added to `smriti telemetry sample` output.
+
+---
+
+## Contract 3 — JSON & CLI Versioning
+
+### JSON output is a hard contract
+
+The standard output envelope is:
+
+```json
+{ "ok": true, "data": { ... }, "meta": { ... } }
+```
+
+Rules:
+
+- **Never remove a field** from `data` or `meta` — add `@deprecated` in a
+  comment instead.
+- **Never rename a field**.
+- **Never change a field's type** (e.g. string → number).
+- New fields in `data` or `meta` must be **optional**.
+- If you must replace a field: add the new one AND keep the old one with a
+  `_deprecated: true` sibling or comment.
+
+### CLI interface stability
+
+Once a command or flag has shipped:
+
+- **Command names**: frozen.
+- **Flag names**: frozen. You may add aliases (e.g. `--dry-run` → `-n`) but not
+  rename.
+- **Positional argument order**: frozen.
+- **Deprecated flags**: must keep working, must emit a `stderr` warning.
+
+---
+
+## Pre-Submission Checklist
+
+Before finishing any edit that touches `src/index.ts` or a command handler:
+
+- [ ] If command is mutating → `--dry-run` is supported and guarded
+- [ ] If command is read-only → `--dry-run` is rejected with a usage error
+- [ ] No user-supplied content appears in `console.log`/`console.error`
+- [ ] If JSON output changed → only fields were **added**, not
+      removed/renamed/retyped
+- [ ] If a new flag was added → it does not conflict with any existing flag name
+- [ ] Telemetry default remains off in `config.ts`
+
+If any item fails, fix it before proceeding.

.github/PULL_REQUEST_TEMPLATE/dev-to-main.md

@@ -0,0 +1,19 @@
+## Release Summary
+- Version: `v<package.json.version>`
+- Source: `dev`
+- Target: `main`
+- Scope: promote validated changes from `dev` to `main`
+
+## Changes Included
+<!-- AUTO-GENERATED:COMMITS -->
+- _Auto-filled by workflow from PR commits._
+<!-- /AUTO-GENERATED:COMMITS -->
+
+## Validation
+- [ ] CI passed on `dev`
+- [ ] Perf bench reviewed (if relevant)
+- [ ] Breaking changes documented
+- [ ] Release notes verified
+
+## Notes
+- Replace or extend this section with any release-specific context.

.github/workflows/ci.yml

@@ -1,4 +1,8 @@
-name: CI
+name: CI Core
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 on:
   push:
@@ -7,8 +11,34 @@ on:
     branches: [main, dev]
 
 jobs:
-  test:
-    name: Test (${{ matrix.os }})
+  test-pr:
+    if: >
+      github.event_name == 'pull_request' &&
+      !(github.event.pull_request.head.ref == 'dev' && github.event.pull_request.base.ref == 'main')
+    name: PR / Tests (ubuntu)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run tests
+        # Fast PR validation on Linux only.
+        run: bun test test/
+
+  test-merge:
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
+    name: Push / Tests (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -30,7 +60,86 @@ jobs:
         run: bun install
 
       - name: Run tests
-        # We only run tests in the smriti/test directory.
-        # qmd/ tests are skipped here as they are part of the backbone submodule
-        # and may have heavy dependencies (like local LLMs) that the runner lacks.
+        # Full cross-platform test matrix for merge branches.
         run: bun test test/
+
+  dev-draft-release:
+    name: Push(dev) / Draft Release
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    needs: test-merge
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Compute dev tag
+        id: meta
+        run: |
+          bun run scripts/release-meta.ts --allow-invalid --github-output "$GITHUB_OUTPUT"
+          DEV_TAG="${{ steps.meta.outputs.next_version }}-dev.${{ github.run_number }}"
+          echo "dev_tag=${DEV_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Remove previous dev draft releases and tags
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              owner,
+              repo,
+              per_page: 100,
+            });
+
+            for (const release of releases) {
+              const isDevTag = /-dev\.\d+$/.test(release.tag_name || "");
+              if (isDevTag && release.draft) {
+                await github.rest.repos.deleteRelease({
+                  owner,
+                  repo,
+                  release_id: release.id,
+                });
+              }
+            }
+
+            const refs = await github.paginate(github.rest.git.listMatchingRefs, {
+              owner,
+              repo,
+              ref: "tags/v",
+              per_page: 100,
+            });
+            for (const ref of refs) {
+              const tagName = ref.ref.replace("refs/tags/", "");
+              if (/-dev\.\d+$/.test(tagName)) {
+                await github.rest.git.deleteRef({
+                  owner,
+                  repo,
+                  ref: `tags/${tagName}`,
+                }).catch(() => {});
+              }
+            }
+
+      - name: Create draft prerelease
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.meta.outputs.dev_tag }}
+          target_commitish: ${{ github.sha }}
+          name: Dev Draft ${{ steps.meta.outputs.dev_tag }}
+          body: ${{ steps.meta.outputs.release_notes }}
+          generate_release_notes: false
+          draft: true
+          prerelease: true

.github/workflows/commitlint.yml

@@ -0,0 +1,30 @@
+name: PR Commit Lint
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  lint:
+    name: PR / Commit Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Lint commits (PR range)
+        run: |
+          bun run scripts/release-meta.ts \
+            --mode lint \
+            --from-ref "${{ github.event.pull_request.base.sha }}" \
+            --to "${{ github.event.pull_request.head.sha }}"

.github/workflows/dev-draft-release.yml

@@ -0,0 +1,73 @@
+name: Dev Draft Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+jobs:
+  draft-release:
+    name: Create/Update Dev Draft Release
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'dev'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout dev commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Compute dev tag
+        id: tag
+        run: |
+          BASE_VERSION=$(node -p "require('./package.json').version")
+          DEV_SUFFIX="dev.${{ github.event.workflow_run.run_number }}"
+          DEV_TAG="v${BASE_VERSION}-${DEV_SUFFIX}"
+          echo "base_version=${BASE_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "dev_tag=${DEV_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Remove previous dev draft releases
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              per_page: 100,
+            });
+
+            for (const release of releases) {
+              const isDevTag = /-dev\.\d+$/.test(release.tag_name || "");
+              if (isDevTag && release.draft) {
+                await github.rest.repos.deleteRelease({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  release_id: release.id,
+                });
+              }
+            }
+
+      - name: Remove previous dev tags
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          for tag in $(git tag --list 'v*-dev.*'); do
+            git push origin ":refs/tags/${tag}" || true
+          done
+
+      - name: Create dev draft prerelease
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.dev_tag }}
+          target_commitish: ${{ github.event.workflow_run.head_sha }}
+          name: Dev Draft ${{ steps.tag.outputs.dev_tag }}
+          generate_release_notes: true
+          draft: true
+          prerelease: true