@kal-elsam/kairo-runtime 0.1.0 → 0.1.1

package/README.md

@@ -12,6 +12,10 @@ The npm package (`@kal-elsam/kairo-runtime`) is how Kairo Runtime is distributed
 product identity is the local control plane: setup, status, sync, doctor (with `update`
 as a technical alias).
 
+`@kal-elsam/harness` remains available as a **compatibility bridge** that delegates to
+Kairo Runtime and prints a migration warning. Prefer `@kal-elsam/kairo-runtime` and the
+`kairo` CLI for new installs. See [`packages/harness-bridge/README.md`](packages/harness-bridge/README.md).
+
 Terminal UX aims for Pi-like clarity (clear modes, non-interactive flags, extensible
 commands) without depending on Pi as a runtime or adding a Pi adapter.
 
@@ -649,7 +653,23 @@ Install the harness in enterprise mode because this project will have AI, API, D
 
 ## Publishing
 
-Published on npm as `@kal-elsam/kairo-runtime`. Releases use **npm Trusted Publishing/OIDC** from GitHub Actions — no `NPM_TOKEN`.
+Published on npm as `@kal-elsam/kairo-runtime`. Releases use **npm Trusted Publishing/OIDC**
+from GitHub Actions — no `NPM_TOKEN`.
+
+`@kal-elsam/harness` is published separately as a compatibility bridge from
+`packages/harness-bridge/` (see bridge README).
+
+### Git tags (package-aware)
+
+| Tag pattern | Package | Publish root |
+|---|---|---|
+| `kairo-runtime-v*` | `@kal-elsam/kairo-runtime` | repo root |
+| `harness-bridge-v*` | `@kal-elsam/harness` | `packages/harness-bridge/` |
+| `v*` | legacy / historical root releases | repo root |
+
+Kairo Runtime releases should use `kairo-runtime-vX.Y.Z` going forward. The first
+bootstrap used `v0.1.0`; later releases use package-aware tags such as
+`kairo-runtime-v0.1.1`.
 
 Before tagging a new version:
 
@@ -684,37 +704,68 @@ to end:
   rollback apply (with safety backup), `uninstall`.
 - **workspace:** `install --scope=workspace`, `doctor`, `update --dry-run`.
 
-Release flow:
+Release flow (Kairo Runtime):
 
 ```bash
 # bump version in package.json and package-lock.json
 git add .
-git commit -m "chore: release 0.5.0"
+git commit -m "chore: release kairo-runtime 0.1.1"
 npm run release:check
-git tag v0.5.0
+git tag kairo-runtime-v0.1.1
 git push origin main
-git push origin v0.5.0
+git push origin kairo-runtime-v0.1.1
 ```
 
+Bridge release flow:
+
+```bash
+# bump packages/harness-bridge/package.json (+ lockfile)
+git add .
+git commit -m "chore: release harness bridge 0.30.0"
+npm run release:check
+git tag harness-bridge-v0.30.0
+git push origin main
+git push origin harness-bridge-v0.30.0
+```
+
+Legacy `v*` tags still publish from the repo root for historical continuity.
+
 After npm publishes the tag, verify published provenance against git and the registry:
 
 ```bash
 git fetch --tags origin
 git fetch origin main
-npm run release:published -- --version 0.1.0
-npm run smoke:registry -- --version 0.1.0
-npm run smoke:installer -- --version 0.1.0
+npm run release:published -- --version 0.1.1 --tag kairo-runtime-v0.1.1
+npm run smoke:registry -- --version 0.1.1
+npm run smoke:installer -- --version 0.1.1
+npm run smoke:bridge
+```
+
+`release:published` checks npm `version`, npm `gitHead`, the release git tag on
+`origin`, and `origin/main`. Override the package and tag when needed:
+
+```bash
+npm run release:published -- \
+  --package @kal-elsam/kairo-runtime \
+  --tag kairo-runtime-v0.1.1 \
+  --version 0.1.1
+
+npm run release:published -- \
+  --package @kal-elsam/harness \
+  --tag harness-bridge-v0.30.0 \
+  --version 0.30.0
 ```
 
-`release:published` checks npm `version`, npm `gitHead`, local tag `v*`, remote tag on `origin`, and `origin/main`. Override the package with `--package @kal-elsam/kairo-runtime` when needed.
+Without `--tag`, provenance checks fall back to `v${version}` (legacy tags).
 
 `smoke:registry` installs `@kal-elsam/kairo-runtime` from the npm registry (not the local tarball) into a throwaway workspace with a fake `HARNESS_HOME` and npm cache, then runs the recommended flow via `kairo`: `setup --dry-run`, `setup --yes`, `status`, drift simulation, `sync`, `status --json` (expects `overall=ok`), and `uninstall`. Use `latest` by default, pin with `--version x.y.z`, or override with `--package`.
 
 `smoke:installer` validates the public one-liner path: `curl .../install.sh | sh` against GitHub `raw` and the npm registry with isolated `HARNESS_HOME`. Preview must not write `~/.harness`; `--yes --agents all` must reach `kairo status --json` with `overall=ok`, then `kairo uninstall` must remove managed sections. Pin with `--version x.y.z` after publish.
 
-Suggested first publish tag: `kairo-runtime-v0.1.0` (or `v0.30.0` if you prefer repo version continuity).
+Suggested first Kairo Runtime tag after bootstrap: `kairo-runtime-v0.1.1`.
 
-The `publish.yml` workflow runs on `v*` tags and publishes to npm using the `npm-publish` environment.
+The `publish.yml` workflow runs on `v*`, `kairo-runtime-v*`, and `harness-bridge-v*`
+tags and publishes to npm using the `npm-publish` environment.
 It runs `npm run release:check` on `HEAD` immediately before `npm publish`.
 
 See the full policy in `SECURITY.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",
@@ -35,6 +35,7 @@
     "ux:smoke": "bash scripts/ux-smoke-test.sh",
     "smoke:registry": "bash scripts/registry-smoke-test.sh",
     "smoke:installer": "bash scripts/installer-smoke-test.sh",
+    "smoke:bridge": "bash scripts/bridge-smoke-test.sh",
     "release:check": "node scripts/check-release-commit.mjs",
     "release:published": "node scripts/check-published-release.mjs"
   },

package/scripts/bridge-smoke-test.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+BRIDGE_DIR="$ROOT/packages/harness-bridge"
+WORKDIR="$(mktemp -d)"
+FAKE_HOME="$(mktemp -d)"
+NPM_CACHE="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$WORKDIR" "$FAKE_HOME" "$NPM_CACHE"
+}
+trap cleanup EXIT
+
+export HARNESS_HOME="$FAKE_HOME"
+export npm_config_cache="$NPM_CACHE"
+
+mkdir -p \
+  "$FAKE_HOME/.cursor" \
+  "$FAKE_HOME/.codex" \
+  "$FAKE_HOME/.config/opencode" \
+  "$FAKE_HOME/.claude"
+
+echo "Packing @kal-elsam/kairo-runtime from $ROOT"
+RUNTIME_TGZ="$(cd "$ROOT" && npm pack --silent --pack-destination "$WORKDIR")"
+RUNTIME_TGZ_PATH="$WORKDIR/$RUNTIME_TGZ"
+
+echo "Packing @kal-elsam/harness bridge"
+BRIDGE_TGZ="$(cd "$BRIDGE_DIR" && npm pack --silent --pack-destination "$WORKDIR")"
+BRIDGE_TGZ_PATH="$WORKDIR/$BRIDGE_TGZ"
+
+INSTALL_DIR="$WORKDIR/project"
+mkdir -p "$INSTALL_DIR"
+(
+  cd "$INSTALL_DIR"
+  npm init -y >/dev/null
+  npm install "$RUNTIME_TGZ_PATH" "$BRIDGE_TGZ_PATH" --ignore-scripts
+)
+
+HARNESS_BIN="$INSTALL_DIR/node_modules/@kal-elsam/harness/bin/harness.js"
+
+echo
+echo "== harness --version (warning on stderr, version on stdout) =="
+VERSION_OUTPUT="$(node "$HARNESS_BIN" --version 2>"$WORKDIR/version.stderr" || true)"
+VERSION_STDERR="$(cat "$WORKDIR/version.stderr")"
+
+if ! grep -q "@kal-elsam/harness has moved to @kal-elsam/kairo-runtime" <<<"$VERSION_STDERR"; then
+  echo "Expected migration warning on stderr" >&2
+  echo "stderr: $VERSION_STDERR" >&2
+  exit 1
+fi
+
+if ! grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' <<<"$VERSION_OUTPUT"; then
+  echo "Expected semver on stdout, got: $VERSION_OUTPUT" >&2
+  exit 1
+fi
+
+if grep -q "@kal-elsam/harness has moved" <<<"$VERSION_OUTPUT"; then
+  echo "Migration warning must not appear on stdout" >&2
+  exit 1
+fi
+
+echo "stdout version: $VERSION_OUTPUT"
+
+echo
+echo "== harness status --json (JSON on stdout only) =="
+set +e
+STATUS_OUTPUT="$(node "$HARNESS_BIN" status --json 2>"$WORKDIR/status.stderr")"
+STATUS_EXIT=$?
+set -e
+STATUS_STDERR="$(cat "$WORKDIR/status.stderr")"
+
+if [ "$STATUS_EXIT" -ne 0 ] && [ "$STATUS_EXIT" -ne 1 ]; then
+  echo "Unexpected exit code from harness status --json: $STATUS_EXIT" >&2
+  exit 1
+fi
+
+if ! grep -q "@kal-elsam/harness has moved to @kal-elsam/kairo-runtime" <<<"$STATUS_STDERR"; then
+  echo "Expected migration warning on stderr for status --json" >&2
+  exit 1
+fi
+
+node -e "JSON.parse(process.argv[1])" "$STATUS_OUTPUT"
+
+if grep -q "@kal-elsam/harness has moved" <<<"$STATUS_OUTPUT"; then
+  echo "Migration warning must not appear in JSON stdout" >&2
+  exit 1
+fi
+
+echo
+echo "Bridge smoke test passed."

package/scripts/check-published-release.mjs

@@ -15,10 +15,19 @@ async function defaultFetchJson(url) {
   return response.json();
 }
 
+export function resolveReleaseTag({ version, tag = null }) {
+  if (tag) {
+    return tag;
+  }
+
+  return `v${version}`;
+}
+
 export function parsePublishedReleaseArgs(argv) {
   const args = [...argv];
   let version = null;
   let packageName = "@kal-elsam/kairo-runtime";
+  let tag = null;
 
   for (let index = 2; index < args.length; index += 1) {
     const arg = args[index];
@@ -43,6 +52,16 @@ export function parsePublishedReleaseArgs(argv) {
       continue;
     }
 
+    if (arg === "--tag") {
+      tag = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--tag=")) {
+      tag = arg.slice("--tag=".length);
+      continue;
+    }
+
     throw new Error(`Unknown option "${arg}".`);
   }
 
@@ -50,16 +69,17 @@ export function parsePublishedReleaseArgs(argv) {
     throw new Error("Missing required --version <x.y.z>.");
   }
 
-  return { version, packageName };
+  return { version, packageName, tag };
 }
 
 export async function verifyPublishedRelease({
   version,
   packageName = "@kal-elsam/kairo-runtime",
+  tag = null,
   runGit = defaultRunGit,
   fetchJson = defaultFetchJson
 }) {
-  const tag = `v${version}`;
+  const releaseTag = resolveReleaseTag({ version, tag });
   const encodedPackage = encodeURIComponent(packageName);
   const meta = await fetchJson(`https://registry.npmjs.org/${encodedPackage}/${version}`);
 
@@ -72,10 +92,12 @@ export async function verifyPublishedRelease({
   }
 
   const gitHead = meta.gitHead.trim();
-  const tagSha = runGit(`git rev-parse ${tag}^{commit}`).trim();
+  const tagSha = runGit(`git rev-parse ${releaseTag}^{commit}`).trim();
 
   if (tagSha !== gitHead) {
-    throw new Error(`Local tag ${tag} (${tagSha}) does not match npm gitHead (${gitHead})`);
+    throw new Error(
+      `Local tag ${releaseTag} (${tagSha}) does not match npm gitHead (${gitHead})`
+    );
   }
 
   const mainSha = runGit("git rev-parse origin/main").trim();
@@ -90,17 +112,19 @@ export async function verifyPublishedRelease({
     }
   }
 
-  const remoteTagLine = runGit(`git ls-remote --tags origin refs/tags/${tag}`).trim();
+  const remoteTagLine = runGit(`git ls-remote --tags origin refs/tags/${releaseTag}`).trim();
 
   if (!remoteTagLine.startsWith(gitHead)) {
-    throw new Error(`Remote tag ${tag} on origin does not point to npm gitHead (${gitHead})`);
+    throw new Error(
+      `Remote tag ${releaseTag} on origin does not point to npm gitHead (${gitHead})`
+    );
   }
 
   return {
     version,
     packageName,
     gitHead,
-    tag,
+    tag: releaseTag,
     mainSha,
     tagSha,
     mainAhead: mainSha !== gitHead
@@ -114,8 +138,8 @@ function isMainModule() {
 }
 
 if (isMainModule()) {
-  const { version, packageName } = parsePublishedReleaseArgs(process.argv);
-  const result = await verifyPublishedRelease({ version, packageName });
+  const { version, packageName, tag } = parsePublishedReleaseArgs(process.argv);
+  const result = await verifyPublishedRelease({ version, packageName, tag });
 
   console.log("Published release provenance OK");
   console.log(`Package: ${result.packageName}@${result.version}`);