Skip to content

Commit 92e7300

Browse files
Complete 9 parallel tasks: mesh specs + Zig npm packaging + release planning
Spec Phase 1 (7 tasks): - TASK-039: Global mesh package map (10 new packages proposed) - TASK-040: crsql-mesh-protocol (message types) - TASK-041: crsql-mesh core sync engine - TASK-042: crsql-mesh-transport (pluggable transports) - TASK-043: crsql-mesh-integration (existing package changes) - TASK-044: libcrsql-next (Zig artifact transition) - TASK-045: crsql-mesh-runtime (platform adapters) Infrastructure (2 tasks): - TASK-034: npm packaging for Zig-built extensions - Added implementation selection (CRSQLITE_IMPL env var) - New build scripts: build-zig.sh, bundle-zig-lib.sh - Bundled macOS Zig artifacts (arm64, x86_64, universal) - Extended dist.test.ts for Zig verification - TASK-036: Release planning proposal - research/zig-cr/103-release-planning-proposal.md - 4-stage rollout: browser beta → linux → mac/win → stable All task cards moved to .tasks/done/
1 parent 8665963 commit 92e7300

27 files changed

+1333
-270
lines changed

.tasks/backlog/TASK-034-npm-package-zig-native.md

Lines changed: 0 additions & 49 deletions
This file was deleted.

.tasks/backlog/TASK-036-release-planning-proposal.md

Lines changed: 0 additions & 45 deletions
This file was deleted.

.tasks/backlog/TASK-041-spec-crsql-mesh-core.md

Lines changed: 0 additions & 45 deletions
This file was deleted.

.tasks/backlog/TASK-044-spec-libcrsql-next.md

Lines changed: 0 additions & 41 deletions
This file was deleted.

.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md

Lines changed: 0 additions & 42 deletions
This file was deleted.
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# TASK-034: npm Packaging for Zig-built Native Extensions
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [x] Complete
9+
10+
## Priority
11+
high
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` ("Cross-platform Packaging & CI" / "Remaining Work for Production Release")
18+
- Existing JS package entry: `index.js`, `package.json`, `scripts/*`
19+
- Existing prebuilt artifacts: `lib/`
20+
- Zig build artifacts: `zig/zig-out*/lib/libcrsqlite.*`
21+
22+
## Description
23+
Package Zig-built native artifacts in the main npm package so users can install and load Zig `crsqlite` without building from source.
24+
25+
This repository already ships C/Rust prebuilt artifacts in `lib/`. Extend or parallel that mechanism for Zig builds.
26+
27+
Constraints:
28+
- Do not introduce a new TS project; stay within existing build tooling.
29+
- Prefer reproducible builds (Nix).
30+
31+
## Files to Modify
32+
- `package.json`
33+
- `scripts/*` (likely `scripts/build-production.ts` / `scripts/build-production.cjs`)
34+
- `index.js` (if selection logic changes)
35+
- `lib/*` (only if intentionally adding artifacts)
36+
- `research/zig-cr/92-gap-backlog.md` (status notes)
37+
38+
## Acceptance Criteria
39+
- [x] Build pipeline produces Zig artifacts for at least one platform and places them in a deterministic location.
40+
- [x] Runtime loader can select Zig artifacts deterministically (or explicitly documents why it can't yet).
41+
- [x] `dist.test.ts` (or equivalent existing packaging sanity tests) extended to assert Zig artifacts presence/selection.
42+
- [x] No regression in existing C/Rust artifact selection.
43+
44+
## Progress Log
45+
### 2025-12-14
46+
- Task created during gap review; not yet started
47+
48+
### 2025-12-14 (Implementation)
49+
- Updated `index.js` with implementation selection logic:
50+
- New `PREFER_IMPLEMENTATION` export (controlled by `CRSQLITE_IMPL` env var)
51+
- `getExtensionPath()` now accepts `{ implementation: 'zig' | 'c-rust' | 'auto' }` option
52+
- Default 'auto' mode prefers Zig, falls back to C/Rust
53+
- Updated `index.d.ts` with new types and exports
54+
- Created `scripts/build-zig.sh` - builds Zig extension for various platforms
55+
- Created `scripts/bundle-zig-lib.sh` - bundles Zig artifacts to `lib/` with naming convention `crsqlite-zig-<platform>-<arch>.<ext>`
56+
- Updated `package.json` with new scripts:
57+
- `build:zig` - build for current platform
58+
- `build:zig:all` - build all platforms
59+
- `bundle-lib:zig` - bundle Zig artifacts to lib/
60+
- `test:zig` - run packaging tests
61+
- Updated `dist.test.ts` with Zig artifact verification tests
62+
- Bundled macOS Zig artifacts (universal, aarch64, x86_64) to lib/
63+
- All tests pass:
64+
- Loader correctly prefers Zig artifacts in 'auto' mode
65+
- Explicit implementation selection works
66+
- No regression in C/Rust artifact selection logic
67+
68+
## Completion Notes
69+
**Completed 2025-12-14**
70+
71+
Changes made:
72+
1. `index.js` - Added implementation selection (zig/c-rust/auto)
73+
2. `index.d.ts` - Added new types for implementation selection
74+
3. `scripts/build-zig.sh` - New script to build Zig extension cross-platform
75+
4. `scripts/bundle-zig-lib.sh` - New script to bundle Zig artifacts to lib/
76+
5. `package.json` - Added new npm scripts for Zig builds
77+
6. `dist.test.ts` - Extended with Zig artifact verification
78+
79+
Naming convention:
80+
- C/Rust: `crsqlite-<platform>-<arch>.<ext>`
81+
- Zig: `crsqlite-zig-<platform>-<arch>.<ext>`
82+
83+
Artifacts in lib/:
84+
- `crsqlite-zig-darwin-universal.dylib` (macOS universal)
85+
- `crsqlite-zig-darwin-aarch64.dylib` (macOS ARM64)
86+
- `crsqlite-zig-darwin-x86_64.dylib` (macOS x64)
87+
- Linux artifacts can be built with `npm run build:zig linux && npm run bundle-lib:zig linux`
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# TASK-036: Release Planning Proposal (Where + How)
2+
3+
## Status
4+
- [x] Planned
5+
- [x] Assigned
6+
- [x] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [x] Complete
9+
10+
## Priority
11+
medium
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Wish: `.wishes/release-planning.md`
18+
- Current packages: `package.json`, `zig/browser-dist/package.json`
19+
- CI: `.github/workflows/*`
20+
- **Proposal:** `research/zig-cr/103-release-planning-proposal.md`
21+
22+
## Description
23+
Write a proposal for how/where to release the Zig work (native + browser):
24+
25+
- Which registries/channels: Nix, npm, GitHub releases, etc.
26+
- What versioning strategy: aligned with root package version or independent
27+
- What artifact matrix: darwin arm64/x64, linux x64/arm64, windows, wasm
28+
- What docs are needed and where they live (prefer in-repo, near code)
29+
30+
Do not publish anything. Output should be a checklist and a proposed staged rollout.
31+
32+
## Files to Modify
33+
- `research/zig-cr/*` (small proposal doc) or `README.md` (if appropriate)
34+
- `.wishes/release-planning.md` (mark done + link to proposal)
35+
36+
## Acceptance Criteria
37+
- [x] Proposal enumerates channels + pros/cons.
38+
- [x] Proposal has a staged plan (MVP web beta → linux → mac/windows, etc.).
39+
- [x] Proposal lists concrete next engineering tasks and where they live in `.tasks/`.
40+
41+
## Progress Log
42+
### 2025-12-14
43+
- Task created during gap review; not yet started
44+
- Analyzed existing package structure and distribution
45+
- Researched competitor distribution patterns (better-sqlite3, sql.js, libsql)
46+
- Wrote comprehensive proposal at `research/zig-cr/103-release-planning-proposal.md`
47+
- Updated `.wishes/release-planning.md` with completion notes
48+
- Task complete
49+
50+
## Completion Notes
51+
52+
**Completed:** 2025-12-14
53+
54+
**Deliverables:**
55+
1. `research/zig-cr/103-release-planning-proposal.md` - Full release planning proposal
56+
57+
**Key Recommendations:**
58+
- **Primary channel:** npm with platform-specific optional dependency packages (follow better-sqlite3 model)
59+
- **Secondary channels:** GitHub Releases for raw binaries, Nix flakes for reproducible builds
60+
- **Versioning:** Aligned versions across all packages (e.g., 0.17.0)
61+
- **Staged rollout:** Browser beta (week 1) -> Linux (week 2) -> macOS/Windows (week 3) -> Stable (week 4)
62+
63+
**Next Tasks Identified:**
64+
- TASK-037: Publish browser package to npm beta
65+
- TASK-038: Set up Zig Linux CI builds
66+
- TASK-039: Create platform-specific npm packages
67+
- TASK-040: Update root README for Zig transition
68+
- TASK-041: Write browser package README
69+
- TASK-042: Create GitHub Release workflow

0 commit comments

Comments
 (0)