chore: first changesets release (server 2.4.1, cli 2.0.1) + release:publish hardening

.github/workflows/release.yml

@@ -30,8 +30,8 @@ jobs:
       - name: Version or publish
         uses: changesets/action@v1
         with:
-          version: bun run ci:version
-          publish: bun run ci:publish
+          version: bun run release:version
+          publish: bun run release:publish
           commit: "chore: version packages"
           title: "chore: version packages"
         env:

RELEASING.md

@@ -1,46 +1,104 @@
 # Releasing
 
-Versioning + publishing is driven by [Changesets](https://github.com/changesets/changesets),
-adapted for **bun**. The one bun-specific gotcha (researched + verified):
+Versioning is driven by [Changesets](https://github.com/changesets/changesets); publishing is done
+with **`bun publish`** (not `changeset publish`). We release **locally** — the CI workflow is
+optional (see the appendix).
 
-> `changeset publish` does **not** resolve bun's `workspace:` protocol — it shells out to
-> `npm publish`, and npm leaves `workspace:^` in the published `package.json` (a broken install).
-> **`bun publish` does** resolve it: `workspace:^` → `^<version>` at pack time. So we version with
-> Changesets but publish with `bun publish`.
+## Why `bun publish`, not `changeset publish`
 
-Inter-package deps therefore use `workspace:^` (e.g. `@samesake/server` → `@samesake/core: "workspace:^"`).
-In dev that always resolves to the local package (no version-range guessing — the bug that left
-`apps/playground` pinned to a stale `^1.3.0`). At publish, `bun pm pack`/`bun publish` rewrite it to
-the real `^<core-version>`. Verified: `bun pm pack` on `@samesake/server` emits `"@samesake/core": "^2.5.0"`.
+Inter-package deps use the `workspace:` protocol — e.g. `@samesake/server` depends on
+`@samesake/core: "workspace:^"`. In dev that always resolves to the local package (no version-range
+guessing). At publish time it must be rewritten to a real range, or consumers get a broken install.
 
-## Day-to-day
+- `changeset publish` shells out to **npm**, which leaves `workspace:^` untouched → broken package.
+- **`bun publish` rewrites it**: `workspace:^` → `^<version>`, `workspace:*` → `<version>`.
 
-Add a changeset with every user-facing change:
+Verified: `cd packages/server && bun pm pack` emits `"@samesake/core": "^2.5.0"` in the tarball.
+
+---
+
+## One-time setup
+
+You need npm publish rights on the `@samesake` scope:
+
+```bash
+npm login          # or put a token in ~/.npmrc
+npm whoami         # confirm you're logged in as a publisher
+```
+
+## Every change: add a changeset
+
+With any user-facing change to a published package, add a changeset **in the same PR**:
 
 ```bash
-bun run changeset        # pick packages + bump type, write the changelog line
-git add .changeset && git commit
+bun run changeset            # pick packages, bump type (patch/minor/major), write the summary
+git add .changeset && git commit -m "…"
 ```
 
-## Cutting a release
+Check what's pending at any time:
+
+```bash
+bun run changeset status     # lists packages that would bump + at what level
+```
 
-Automated via `.github/workflows/release.yml` (needs an `NPM_TOKEN` repo secret):
-on push to `main`, the changesets action opens a **"version packages"** PR; merging it publishes
-everything ahead of npm.
+Private packages (`apps/*`, `examples/*`) are excluded — they never version or publish.
 
-To release manually:
+## Cutting a release (local)
+
+Two steps, with a review in between:
 
 ```bash
-bun run ci:version       # changeset version && bun update  → bumps + per-package CHANGELOGs + lockfile
+# 1) bump versions + write per-package CHANGELOGs + consume the changesets
+bun run release:version
+git diff                                  # review the version bumps + CHANGELOG entries
 git commit -am "chore: version packages"
-bun run ci:publish       # build, `bun publish` each packages/* (skips already-published), then tag
+
+# 2) build, publish, tag
+bun run release:publish
 git push --follow-tags
 ```
 
-`ci:publish` loops `packages/*` and runs `bun publish || true`, so already-published versions are
-skipped and only the bumped ones go out. Private packages (`apps/*`, `examples/*`) are never published.
+### What `release:publish` does
+
+1. Builds `sdk`, `server`, `cli`, `mcp`.
+2. Runs `bun publish` in each `packages/*` — `|| true` means **already-published versions are
+   skipped**, so only the bumped packages actually go out.
+3. `bun publish` rewrites `workspace:` deps to real ranges (above).
+4. `changeset tag` creates the git tags for the released versions.
+
+## Verify
+
+```bash
+npm view @samesake/server version         # etc.
+```
+
+A brand-new package name can take a minute to appear in `npm view` (registry read-API lag) even
+though the publish succeeded — `npm publish` printing `+ @samesake/x@1.2.3` is the source of truth.
+
+## Sanity-check before publishing (optional)
+
+```bash
+cd packages/server && bun pm pack         # inspect the tarball
+tar -xzOf samesake-server-*.tgz package/package.json | grep '@samesake'   # deps should be ^x, not workspace:
+rm samesake-server-*.tgz
+```
+
+---
+
+## Appendix: CI automation (optional)
+
+`.github/workflows/release.yml` can run the same flow on push to `main`. It is **off by default in
+practice** because we release locally. To use it you must:
+
+1. **Settings → Actions → General → Workflow permissions** → enable *"Allow GitHub Actions to create
+   and approve pull requests"* (the action opens a "Version Packages" PR).
+2. **Settings → Secrets and variables → Actions** → add `NPM_TOKEN`.
+
+Then: push to `main` with pending changesets → the action opens a "Version Packages" PR → merging it
+runs `release:publish`. Until both are set, the `release` workflow run will fail at the PR-creation
+step — that's expected, not a regression.
 
 ## Note on CHANGELOG
 
-Changesets writes a **per-package** `CHANGELOG.md` going forward. The root `CHANGELOG.md` is the
-historical record through 2.5.0 (the last hand-maintained release).
+Changesets writes a **per-package** `CHANGELOG.md`. The root `CHANGELOG.md` is the historical record
+through 2.5.0 (the last hand-maintained release).

apps/playground/package.json

@@ -18,7 +18,7 @@
     "@porulle/adapter-postgres": "^0.1.0",
     "@porulle/adapter-local-storage": "^0.1.0",
     "@samesake/core": "^2.1.0",
-    "@samesake/server": "^2.2.0",
+    "@samesake/server": "^2.4.1",
     "better-auth": "1.6.18",
     "@better-auth/api-key": "1.6.18",
     "hono": "^4.12.0",

package.json

@@ -16,8 +16,8 @@
     "pack:assert": "bun scripts/pack-assert.ts",
     "build": "for d in packages/sdk packages/server packages/cli packages/mcp; do (cd \"$d\" && bun run build) || exit 1; done",
     "changeset": "changeset",
-    "ci:version": "changeset version && bun update",
-    "ci:publish": "bun run build && for dir in packages/*; do (cd \"$dir\" && bun publish || true); done && changeset tag"
+    "release:version": "changeset version && bun update",
+    "release:publish": "bun run build && for dir in packages/*; do [ -f \"$dir/package.json\" ] && (cd \"$dir\" && bun publish || true); done && changeset tag"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
@@ -30,6 +30,6 @@
     "@porulle/core": "0.1.0"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5.9.3"
   }
 }

packages/cli/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @samesake/cli
+
+## 2.0.1
+
+### Patch Changes
+
+- 87a8d9c: Use `workspace:^` for inter-package dependencies. In dev this always resolves to the local
+  workspace package; at publish `bun publish` rewrites it to a real `^<version>` (verified via
+  `bun pm pack`). Replaces the previous loose `^2.0.0` ranges that could silently resolve to a stale
+  published version (the bug that left `apps/playground` pinned to `^1.3.0`).
+- Updated dependencies [87a8d9c]
+  - @samesake/server@2.4.1

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samesake/cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/asyncdotengineering/samesake"

packages/server/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.4.1
+
+### Patch Changes
+
+- 87a8d9c: Use `workspace:^` for inter-package dependencies. In dev this always resolves to the local
+  workspace package; at publish `bun publish` rewrites it to a real `^<version>` (verified via
+  `bun pm pack`). Replaces the previous loose `^2.0.0` ranges that could silently resolve to a stale
+  published version (the bug that left `apps/playground` pinned to `^1.3.0`).
 
 # @samesake/server changelog
 
@@ -34,6 +42,7 @@ The parse-cache key includes a hash of the final composed prompt, so
 this change invalidates all cached parse results automatically.
 
 Consumers whose 0.5.3 override was a full prompt should split it into:
+
 1. Their domain content (role + examples + extraction rules) → keep
    in their entity's `parse.instructions`.
 2. Schema contract — DELETE from the consumer override; framework now
@@ -73,7 +82,7 @@ GPT-5 / Vercel AI SDK prompt-engineering guidance:
 
 The parse-cache key includes a hash of the instructions string, so
 this change invalidates all cached parse results automatically.
-Existing rows in the per-project entity_<kind>_match tables retain
+Existing rows in the per-project entity\_<kind>\_match tables retain
 their stored parsed columns; they will not be re-parsed unless the
 caller re-upserts. For demos and design-partner deploys, wipe and
 re-seed; for production, re-upsert affected rows when convenient.
@@ -127,7 +136,7 @@ Day-1-import flow for Sri Lankan SME customer books:
   Tamil, `ச` at word-start is the `s` sound — the per-script map
   was factually wrong.
 - Even when phonetic keys converged (e.g. `Anuja Wiwarana ↔ අනූජ
-  විවරණ` both → `NCVRN`), the trigram channel returned 0 because
+විවරණ` both → `NCVRN`), the trigram channel returned 0 because
   the two scripts share no character n-grams in their original
   form. With cosine alone carrying ~85% of the combined-score
   weight, cross-script same-name pairs sat at the 0.78 suggest
@@ -136,14 +145,16 @@ Day-1-import flow for Sri Lankan SME customer books:
 ### Changes
 
 **`samesake_phonetic` (system DDL)**
+
 - Tamil `ச` → `S` (was `C`). Aligns with how Latin `s` already maps.
 - Tamil `ஜ` → `C` explicitly (was bundled with ச in `'சஜ' → 'CC'`).
   Preserves the j-class mapping to align with Latin `j`.
 
 **Generated `match_<kind>` SQL (people-shape)**
+
 - Trigram channel is now `GREATEST(similarity(query.norm,
-  candidate.name_normalised), similarity(query.phon,
-  candidate.phon_hash))`. Intra-script pairs still use the richer
+candidate.name_normalised), similarity(query.phon,
+candidate.phon_hash))`. Intra-script pairs still use the richer
   normalised-text similarity (no behavior change). Cross-script
   pairs gain a trigram bridge via their phonetic signatures — for
   identical phonetic keys, trigram ≈ 1.0 instead of 0.

packages/server/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@samesake/server",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/asyncdotengineering/samesake"
   },
-  "description": "createMatcher factory \u2014 hybrid search (FTS+vector RRF, filters, facets, NLQ, enrichment) and entity resolution on PostgreSQL + pgvector. Hono app with universal fetch handler; BYO embed/generate/parse functions.",
+  "description": "createMatcher factory — hybrid search (FTS+vector RRF, filters, facets, NLQ, enrichment) and entity resolution on PostgreSQL + pgvector. Hono app with universal fetch handler; BYO embed/generate/parse functions.",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.cjs",