oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b20b138fe485817e8d69d0c60e376e3c53af149a
waggle-os/docs/briefs/hive-mind-ci-npm-publish-brief-2026-04-19.md
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details
moving
2026-09-02 10:10:29 +02:00

7.6 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink