155 lines
7.6 KiB
Markdown
155 lines
7.6 KiB
Markdown
# Brief za Claude Code — hive-mind CI pipeline + npm publish
|
||
|
||
**Datum**: 2026-04-19
|
||
**Izvor**: H-34 closure posle 2026-04-18 late-night sesije (282/282 green, 4 packages, ~8500 LOC vendored)
|
||
**Scope**: JEDNA sesija, jedan fokus. No new features, no scope creep.
|
||
**Output**: Green CI badge + 4 packages live na npm registry + first-run smoke skripta
|
||
|
||
---
|
||
|
||
## Session goal (one sentence)
|
||
|
||
Take the hive-mind repo from "locally 282/282 green" to "cloneable by a stranger, CI-validated, installable via `npm install @hive-mind/*` on any machine, with a smoke test script that proves end-to-end working MCP server in under 5 minutes."
|
||
|
||
## Why now
|
||
|
||
H-34 extraction is tehnički CLOSED (Waves 4–6 shipped 2026-04-18). But the repo is not "shipped" until:
|
||
1. A fresh clone on a clean runner passes all 282 tests without manual intervention.
|
||
2. The 4 packages are discoverable via `npm search` and installable via `npm install`.
|
||
3. A press/analyst persona (non-developer) can run a smoke script and see the MCP server work.
|
||
|
||
This session closes that gap. It is the last operational task before SOTA benchmark proof (LoCoMo 91.6% target) becomes the critical-path blocker for Waggle launch.
|
||
|
||
## Current state (as of H-34 closure)
|
||
|
||
- Repo: `D:\Projects\hive-mind`, Apache 2.0, 4 packages migrated.
|
||
- Packages: `@hive-mind/core`, `@hive-mind/wiki-compiler`, `@hive-mind/mcp-server`, `@hive-mind/cli`.
|
||
- Tests: 282/282 green across 38 test files (locally).
|
||
- Commits: Waves 4-6 landed in 2026-04-18 session (`9f774f7`, `74f2b76`, `a30d04a`, `6c32987`).
|
||
- Missing: GitHub Actions config, npm publish config, CHANGELOG, first-run smoke, release notes.
|
||
|
||
## Non-goals (strict)
|
||
|
||
- NO new features.
|
||
- NO refactoring beyond what CI forces.
|
||
- NO touching waggle-os monolith (companion fix `803c6f6` already landed separately).
|
||
- NO starting v2 GEPA, LoCoMo benchmark, or H13 landing work.
|
||
- NO npm scope changes, package renames, or version bumps beyond v0.1.0.
|
||
- NO platform-specific CI (Windows/macOS matrix) in this pass — Linux runner only. Cross-platform is a follow-up.
|
||
|
||
If any non-goal item appears tempting, STOP and write a follow-up issue instead.
|
||
|
||
## Acceptance criteria
|
||
|
||
### A. GitHub Actions CI pipeline
|
||
|
||
Path: `.github/workflows/ci.yml` in hive-mind repo.
|
||
|
||
- Triggers: push to `main`, PR to `main`.
|
||
- Runner: `ubuntu-latest`, Node 22 LTS, pnpm (use repo's pnpm version from `package.json` `packageManager` field or `.nvmrc` / `.tool-versions`).
|
||
- Steps (in order):
|
||
1. Checkout
|
||
2. Setup Node + pnpm + cache
|
||
3. `pnpm install --frozen-lockfile`
|
||
4. `pnpm -r run lint` (if lint scripts exist; skip gracefully if not)
|
||
5. `pnpm -r run typecheck` (if typecheck scripts exist)
|
||
6. `pnpm -r run test` — MUST pass with 282/282 on clean runner
|
||
7. `pnpm -r run build`
|
||
8. Artifact upload: dist folders of all 4 packages (for inspection)
|
||
- Required status check to be enabled on `main` branch protection.
|
||
- Green badge in README.md.
|
||
|
||
### B. npm publish readiness (dry-run first, then publish)
|
||
|
||
For each of the 4 packages:
|
||
|
||
- `package.json` has: `name`, `version: "0.1.0"`, `description`, `license: "Apache-2.0"`, `repository` (pointing to GitHub repo), `homepage`, `bugs`, `keywords`, `author`, `main`, `types` (if TS), `files` (explicit allowlist, not `.npmignore`), `publishConfig.access: "public"` (for scoped packages).
|
||
- `README.md` at package root (can be short, links to monorepo root README).
|
||
- LICENSE file at package root (Apache 2.0 text).
|
||
- `pnpm -r publish --dry-run` MUST succeed without warnings beyond informational.
|
||
- After dry-run clean: actual `npm publish` for all 4 packages.
|
||
- Verify via `npm view @hive-mind/core` etc. that all 4 are live.
|
||
|
||
Note on npm org scope: if `@hive-mind` org does not exist on npm yet, Claude Code stops and asks Marko to create it with his npm login (requires 2FA + organization creation flow). Alternative: unscoped names `hive-mind-core` etc. — but preferred is scoped.
|
||
|
||
### C. Root README normalization
|
||
|
||
Path: `README.md` at hive-mind repo root.
|
||
|
||
- CI badge (green)
|
||
- npm version badges for all 4 packages
|
||
- Quickstart: 5 lines max to go from `npm install` to first MCP tool call
|
||
- License: Apache 2.0
|
||
- Link to EXTRACTION.md (methodology doc)
|
||
- Link to first-run smoke (see D)
|
||
- Cross-repo link to `waggle-os` as consuming application
|
||
|
||
### D. First-run smoke script
|
||
|
||
Path: `scripts/first-run-smoke.sh` (+ Windows counterpart `scripts/first-run-smoke.ps1` if trivial; skip if not).
|
||
|
||
- Goal: A non-developer (press/analyst persona) runs one command and sees the MCP server respond.
|
||
- Steps automated:
|
||
1. Check Node 22+ available
|
||
2. `npm install -g @hive-mind/cli` (or temp-dir install)
|
||
3. `hive-mind init --tmp` (creates sample workspace in a temp dir)
|
||
4. `hive-mind mcp start &` (starts MCP server)
|
||
5. `hive-mind mcp call list_tools` (prints 21 tools)
|
||
6. `hive-mind harvest demo` (runs one small harvest from a public URL)
|
||
7. `hive-mind mcp call search "demo"` (returns results)
|
||
8. Print green checkmark + "smoke passed in Nms"
|
||
|
||
If any command does not exist in the current CLI surface, STOP — do not add it. Note the gap and return to Marko for decision (this is persona-facing; we do not invent commands).
|
||
|
||
### E. CHANGELOG.md
|
||
|
||
Path: `CHANGELOG.md` at root. Keep-a-Changelog format.
|
||
|
||
```
|
||
## [0.1.0] - 2026-04-19
|
||
|
||
### Added
|
||
- Initial public release extracted from waggle-os monolith
|
||
- @hive-mind/core: bitemporal KG, MPEG-4 I/P/B frame model, workspace, mind-cache
|
||
- @hive-mind/wiki-compiler: markdown compile pipeline with versioned output
|
||
- @hive-mind/mcp-server: 21 MCP tools + 4 resources
|
||
- @hive-mind/cli: 6 commands (init, harvest, mcp, wiki, search, status — verify exact names)
|
||
- 282 tests across 38 files
|
||
- Apache 2.0 license
|
||
```
|
||
|
||
### F. Release notes + GitHub Release
|
||
|
||
- Tag `v0.1.0` on the commit that passes CI green.
|
||
- GitHub Release from the tag, body = CHANGELOG entry + "installed via `npm install @hive-mind/core`".
|
||
- Marked as "latest release" and NOT pre-release (first stable public).
|
||
|
||
## Order of operations (recommended)
|
||
|
||
1. CI pipeline first (A). Do not touch anything else until CI runs green on a commit in `main` (or a feature branch). CI will expose any hidden local-only assumptions fast.
|
||
2. Package metadata hardening (B, up to dry-run). Dry-run surfaces missing fields without committing to npm.
|
||
3. Root README + CHANGELOG (C, E). Easy wins that unblock D.
|
||
4. First-run smoke (D). This is the riskiest item — it exercises the full surface from outside. Expect to find 1-2 small gaps in CLI surface area. Flag them to Marko via follow-up issue, do NOT patch inline.
|
||
5. npm org creation + real publish (B final step). Requires Marko.
|
||
6. Tag + GitHub Release (F).
|
||
|
||
## Definition of done
|
||
|
||
- CI green on `main` for the commit that ships v0.1.0.
|
||
- `npm view @hive-mind/core` returns `0.1.0`.
|
||
- `scripts/first-run-smoke.sh` on a clean Ubuntu runner exits 0 in under 5 minutes.
|
||
- CHANGELOG.md has v0.1.0 entry.
|
||
- GitHub Release `v0.1.0` exists with installation instructions.
|
||
- Root README has green CI badge + npm badges + 5-line quickstart.
|
||
|
||
## Escalation triggers (when to stop and ask Marko)
|
||
|
||
- npm `@hive-mind` org does not exist → needs Marko's npm login.
|
||
- CI fails on a test that passed locally → likely environment assumption; worth 30 min to diagnose, then stop.
|
||
- `pnpm publish --dry-run` warns about something non-trivial → confirm with Marko before proceeding.
|
||
- CLI surface gap in first-run smoke → do not invent commands; report and ask.
|
||
|
||
## Reporting at session end
|
||
|
||
Brief commit log (files touched, tests added if any), npm package URLs (once live), first-run smoke timing, and one-paragraph "what was surprising" note. Surface any technical debt discovered during CI surfacing — these go to follow-up issues, not patched in this session.
|