@kal-elsam/kairo-runtime 0.1.1 → 0.1.2

package/README.md

@@ -51,14 +51,14 @@ curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/inst
 The bootstrap installer:
 
 - requires Node.js 20.12+ and npm
-- runs `@kal-elsam/kairo-runtime` via `npx` (or `npm exec`)
-- ends with `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
+- installs `@kal-elsam/kairo-runtime` globally (`kairo` CLI)
+- runs `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
 - never uses `sudo`, never modifies shell profiles, and never installs AI apps
 
 Apply the plan when you are ready:
 
 ```bash
-npx @kal-elsam/kairo-runtime --yes
+kairo setup --yes
 # or
 curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --yes
 ```
@@ -66,8 +66,8 @@ curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/inst
 CI, scripts, and advanced non-interactive configure:
 
 ```bash
-npx @kal-elsam/kairo-runtime install --agents cursor,codex --yes
-npx @kal-elsam/kairo-runtime setup --yes --agents all
+kairo install --agents cursor,codex --yes
+kairo setup --yes --agents all
 ```
 
 Passthrough examples:
@@ -83,11 +83,11 @@ Control plane:
 kairo status
 kairo sync
 kairo upgrade --dry-run
-npx @kal-elsam/kairo-runtime@latest setup --yes
+kairo setup --yes
 ```
 
 After `install.sh --yes`, verify health with `kairo status`, repair drift with `kairo sync`,
-and move to the latest package with `npx @kal-elsam/kairo-runtime@latest setup --yes`.
+and preview upgrades with `kairo upgrade --dry-run`.
 
 ### Version and updates
 
@@ -737,7 +737,7 @@ git fetch --tags origin
 git fetch origin main
 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:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
 npm run smoke:bridge
 ```
 
@@ -760,7 +760,13 @@ 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.
+`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. For package-aware Kairo Runtime tags, pass the git tag explicitly:
+
+```bash
+npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
+```
+
+Without `--tag`, the install script resolves from legacy `v${version}` tags.
 
 Suggested first Kairo Runtime tag after bootstrap: `kairo-runtime-v0.1.1`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",

package/scripts/install.sh

@@ -43,8 +43,9 @@ usage() {
     "" \
     "What it does:" \
     "  1. Checks for Node.js and npm." \
-    "  2. Runs the package via npx (or npm exec) with setup --dry-run (default) or setup --yes (--yes)." \
-    "  3. Prints next steps." \
+    "  2. Installs ${PACKAGE} globally (adds kairo to npm global bin)." \
+    "  3. Runs kairo setup --dry-run (default) or kairo setup --yes (--yes)." \
+    "  4. Prints next steps." \
     "" \
     "Security:" \
     "  - Never uses sudo." \
@@ -62,6 +63,51 @@ append_setup_arg() {
   SETUP_EXTRA="${SETUP_EXTRA}${SETUP_EXTRA:+ }$1"
 }
 
+resolve_global_spec() {
+  if [ "$VERSION" = "latest" ]; then
+    printf '%s@latest' "$PACKAGE"
+  else
+    printf '%s@%s' "$PACKAGE" "$VERSION"
+  fi
+}
+
+resolve_npm_global_bin() {
+  npm_prefix="$(npm prefix -g 2>/dev/null || true)"
+  [ -n "$npm_prefix" ] || return 1
+  printf '%s/bin' "$(printf '%s' "$npm_prefix" | sed 's#/*$##')"
+}
+
+resolve_kairo_bin() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    command -v "$PREFERRED_CLI"
+    return 0
+  fi
+
+  global_bin="$(resolve_npm_global_bin || true)"
+  if [ -n "$global_bin" ] && [ -x "${global_bin}/${PREFERRED_CLI}" ]; then
+    printf '%s\n' "${global_bin}/${PREFERRED_CLI}"
+    return 0
+  fi
+
+  return 1
+}
+
+print_path_hint_if_needed() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  global_bin="$(resolve_npm_global_bin || true)"
+  if [ -n "$global_bin" ]; then
+    printf '%s\n' \
+      "" \
+      "PATH note:" \
+      "  ${PREFERRED_CLI} was installed to ${global_bin}." \
+      "  Add it to PATH if the command is not found:" \
+      "    export PATH=\"${global_bin}:\$PATH\""
+  fi
+}
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --dry-run)
@@ -137,14 +183,9 @@ require_cmd npm
 
 NODE_VERSION="$(node --version 2>/dev/null || true)"
 NPM_VERSION="$(npm --version 2>/dev/null || true)"
-
-if command -v npx >/dev/null 2>&1; then
-  RUNNER="npx"
-  RUN_CMD="npx --yes ${PACKAGE}@${VERSION} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
-else
-  RUNNER="npm-exec"
-  RUN_CMD="npm exec --yes --package=${PACKAGE}@${VERSION} -- ${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
-fi
+GLOBAL_SPEC="$(resolve_global_spec)"
+GLOBAL_INSTALL_CMD="npm install -g ${GLOBAL_SPEC}"
+SETUP_CMD="${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
 
 printf '%s\n' \
   "Kairo Runtime bootstrap installer" \
@@ -153,13 +194,13 @@ printf '%s\n' \
   "Prerequisites:" \
   "  node  ${NODE_VERSION:-unknown}" \
   "  npm   ${NPM_VERSION:-unknown}" \
-  "  runner ${RUNNER}" \
   "" \
   "Will run:" \
-  "  ${RUN_CMD}" \
+  "  ${GLOBAL_INSTALL_CMD}" \
+  "  ${SETUP_CMD}" \
   "" \
   "Effects:" \
-  "  - Downloads/runs ${PACKAGE}@${VERSION} via npm (no global install required)." \
+  "  - Installs ${GLOBAL_SPEC} globally (kairo CLI in npm global bin)." \
   "  - Configures managed sections only (never installs AI apps)." \
   "  - Never uses sudo or modifies shell profiles." \
   ""
@@ -181,19 +222,25 @@ if [ "$INSTALLER_DRY_RUN" -eq 1 ]; then
   exit 0
 fi
 
+printf '%s\n' "Installing global CLI..." ""
+# shellcheck disable=SC2086
+npm install -g ${GLOBAL_SPEC}
+
+KAIRO_BIN="$(resolve_kairo_bin || true)"
+if [ -z "$KAIRO_BIN" ]; then
+  die "Installed ${GLOBAL_SPEC}, but ${PREFERRED_CLI} is not available.
+Check npm global bin: $(resolve_npm_global_bin || echo unknown)
+Add it to PATH, then re-run: ${SETUP_CMD}"
+fi
+
 if [ "$APPLY" -eq 1 ]; then
   printf '%s\n' "Applying setup..." ""
 else
   printf '%s\n' "Running preview..." ""
 fi
 
-if [ "$RUNNER" = "npx" ]; then
-  # shellcheck disable=SC2086
-  npx --yes "${PACKAGE}@${VERSION}" setup ${SETUP_MODE} ${SETUP_EXTRA}
-else
-  # shellcheck disable=SC2086
-  npm exec --yes --package="${PACKAGE}@${VERSION}" -- ${PREFERRED_CLI} setup ${SETUP_MODE} ${SETUP_EXTRA}
-fi
+# shellcheck disable=SC2086
+"$KAIRO_BIN" setup ${SETUP_MODE} ${SETUP_EXTRA}
 
 if [ "$APPLY" -eq 1 ]; then
   printf '%s\n' \
@@ -202,24 +249,25 @@ if [ "$APPLY" -eq 1 ]; then
     "Next steps:" \
     "  1. Check health:    ${PREFERRED_CLI} status" \
     "  2. Repair drift:    ${PREFERRED_CLI} sync" \
-    "  3. Upgrade latest:  npx ${PACKAGE}@latest setup --yes" \
+    "  3. Upgrade latest:  ${PREFERRED_CLI} upgrade --dry-run" \
     "" \
     "Version:" \
-    "  Installed CLI:      npx ${PACKAGE} --version" \
-    "  Published package:  npm view ${PACKAGE} version" \
-    "  Preview upgrade:    ${PREFERRED_CLI} upgrade --dry-run"
+    "  Installed CLI:      ${PREFERRED_CLI} --version" \
+    "  Published package:  npm view ${PACKAGE} version"
+  print_path_hint_if_needed
 else
   printf '%s\n' \
     "" \
     "Bootstrap complete." \
     "Next steps:" \
-    "  1. Apply the plan:  npx ${PACKAGE}@${VERSION} setup --yes" \
+    "  1. Apply the plan:  ${PREFERRED_CLI} setup --yes" \
     "     (or re-run installer: curl ... | sh -s -- --yes)" \
-    "  2. Check health:    npx ${PACKAGE}@${VERSION} status" \
-    "  3. Repair drift:    npx ${PACKAGE}@${VERSION} sync" \
+    "  2. Check health:    ${PREFERRED_CLI} status" \
+    "  3. Repair drift:    ${PREFERRED_CLI} sync" \
     "" \
     "Version:" \
-    "  Installed CLI:      npx ${PACKAGE} --version" \
+    "  Installed CLI:      ${PREFERRED_CLI} --version" \
     "  Published package:  npm view ${PACKAGE} version" \
-    "  Update / converge:  npx ${PACKAGE}@latest sync"
+    "  Update / converge:  ${PREFERRED_CLI} sync"
+  print_path_hint_if_needed
 fi

package/scripts/installer-smoke-test.sh

@@ -4,7 +4,9 @@ set -euo pipefail
 PACKAGE="@kal-elsam/kairo-runtime"
 PREFERRED_CLI="kairo"
 VERSION="latest"
+GIT_TAG=""
 REPO="Kal-elSam/harness"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -24,6 +26,14 @@ while [ "$#" -gt 0 ]; do
       VERSION="${1#*=}"
       shift
       ;;
+    --tag)
+      GIT_TAG="$2"
+      shift 2
+      ;;
+    --tag=*)
+      GIT_TAG="${1#*=}"
+      shift
+      ;;
     *)
       echo "Unknown option: $1" >&2
       exit 1
@@ -53,12 +63,13 @@ assert_harness_home_isolated() {
 }
 
 resolve_install_script_url() {
-  if [ "$VERSION" = "latest" ]; then
-    printf '%s\n' "https://raw.githubusercontent.com/${REPO}/main/scripts/install.sh"
-    return
+  local args=(--version "$VERSION" --repo "$REPO")
+
+  if [ -n "$GIT_TAG" ]; then
+    args+=(--tag "$GIT_TAG")
   fi
 
-  printf '%s\n' "https://raw.githubusercontent.com/${REPO}/v${VERSION}/scripts/install.sh"
+  node "${SCRIPT_DIR}/lib/install-script-url.mjs" "${args[@]}"
 }
 
 assert_no_harness_state() {
@@ -117,6 +128,9 @@ cd "$WORKDIR"
 
 INSTALL_SCRIPT_URL="$(resolve_install_script_url)"
 echo "Installer smoke for ${PACKAGE}@${VERSION}"
+if [ -n "$GIT_TAG" ]; then
+  echo "Git tag: ${GIT_TAG}"
+fi
 echo "Install script: ${INSTALL_SCRIPT_URL}"
 echo "Harness home: ${HARNESS_HOME}"
 
@@ -140,15 +154,36 @@ if [ ! -d "$FAKE_HOME/.harness" ]; then
   exit 1
 fi
 
+NPM_GLOBAL_BIN="$(npm prefix -g 2>/dev/null)/bin"
+export PATH="${NPM_GLOBAL_BIN}:${PATH}"
+
+resolve_kairo_bin() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    command -v "$PREFERRED_CLI"
+    return 0
+  fi
+  if [ -x "${NPM_GLOBAL_BIN}/${PREFERRED_CLI}" ]; then
+    printf '%s\n' "${NPM_GLOBAL_BIN}/${PREFERRED_CLI}"
+    return 0
+  fi
+  return 1
+}
+
+KAIRO_BIN="$(resolve_kairo_bin || true)"
+if [ -z "$KAIRO_BIN" ]; then
+  echo "Expected ${PREFERRED_CLI} after install.sh global install" >&2
+  exit 1
+fi
+
 echo
 echo "== ${PREFERRED_CLI} status --json =="
-STATUS_JSON="$(npx --yes "${PACKAGE}@${VERSION}" status --json)"
+STATUS_JSON="$("$KAIRO_BIN" status --json)"
 echo "$STATUS_JSON"
 assert_status_ok "$STATUS_JSON"
 
 echo
 echo "== ${PREFERRED_CLI} uninstall =="
-npx --yes "${PACKAGE}@${VERSION}" uninstall
+"$KAIRO_BIN" uninstall
 assert_managed_configs_removed
 
 echo

package/scripts/lib/install-script-url.mjs

@@ -0,0 +1,85 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const DEFAULT_REPO = "Kal-elSam/harness";
+
+export function resolveInstallScriptRef({ version, tag = null }) {
+  if (version === "latest") {
+    return "main";
+  }
+
+  if (tag) {
+    return tag;
+  }
+
+  return `v${version}`;
+}
+
+export function resolveInstallScriptUrl({
+  repo = DEFAULT_REPO,
+  version,
+  tag = null
+}) {
+  const ref = resolveInstallScriptRef({ version, tag });
+  return `https://raw.githubusercontent.com/${repo}/${ref}/scripts/install.sh`;
+}
+
+export function parseInstallScriptUrlArgs(argv) {
+  const args = [...argv];
+  let version = "latest";
+  let tag = null;
+  let repo = DEFAULT_REPO;
+
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--version") {
+      version = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--version=")) {
+      version = arg.slice("--version=".length);
+      continue;
+    }
+
+    if (arg === "--tag") {
+      tag = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--tag=")) {
+      tag = arg.slice("--tag=".length);
+      continue;
+    }
+
+    if (arg === "--repo") {
+      repo = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--repo=")) {
+      repo = arg.slice("--repo=".length);
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  return { version, tag, repo };
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+
+  if (!entry) {
+    return false;
+  }
+
+  return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(entry);
+}
+
+if (isMainModule()) {
+  const { version, tag, repo } = parseInstallScriptUrlArgs(process.argv);
+  console.log(resolveInstallScriptUrl({ repo, version, tag }));
+}

package/src/cli.js

@@ -31,51 +31,21 @@ import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
 import {
-  ALL_CLI_NAMES,
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
   PREFERRED_CLI,
   formatCliCommand,
-  maybeWarnLegacyCli
+  maybeWarnLegacyCli,
+  resolveSuggestedInvocation
 } from "./global/brand/cli.js";
 import { BRAND } from "./global/brand/index.js";
 
+export { resolveSuggestedInvocation };
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const SCOPES = new Set(["agent-global", "workspace"]);
 
-export function resolveSuggestedInvocation(packageName, argv = process.argv) {
-  const invokedPath = argv[1] ?? PREFERRED_CLI;
-  const invokedBase = basename(invokedPath);
-
-  if (!invokedBase.endsWith(".js") && ALL_CLI_NAMES.has(invokedBase)) {
-    return invokedBase;
-  }
-
-  const packageManager = detectInvocationPackageManager();
-
-  switch (packageManager) {
-    case "pnpm":
-      return `pnpm dlx ${packageName}`;
-    case "yarn":
-      return `yarn dlx ${packageName}`;
-    case "bun":
-      return `bunx ${packageName}`;
-    default:
-      return `npx ${packageName}`;
-  }
-}
-
-function detectInvocationPackageManager() {
-  const execPath = process.env.npm_execpath ?? "";
-  const userAgent = process.env.npm_config_user_agent ?? "";
-
-  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
-  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
-  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
-  return "npm";
-}
-
 export async function runCli(argv) {
   const { command, options } = parseArgs(argv);
   maybeWarnLegacyCli(process.argv, { json: options.json });

package/src/global/brand/cli.js

@@ -50,3 +50,44 @@ export function formatCliCommand(subcommand, cliName = PREFERRED_CLI) {
   const trimmed = subcommand.trim();
   return trimmed ? `${cliName} ${trimmed}` : cliName;
 }
+
+function detectInvocationPackageManager() {
+  const execPath = process.env.npm_execpath ?? "";
+  const userAgent = process.env.npm_config_user_agent ?? "";
+
+  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
+  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
+  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
+  return "npm";
+}
+
+export function resolveSuggestedInvocation(packageName = PACKAGE_NAME, argv = process.argv) {
+  const invokedPath = argv[1] ?? PREFERRED_CLI;
+  const invokedBase = basename(invokedPath);
+
+  if (!invokedBase.endsWith(".js") && ALL_CLI_NAMES.has(invokedBase)) {
+    return invokedBase;
+  }
+
+  const packageManager = detectInvocationPackageManager();
+
+  switch (packageManager) {
+    case "pnpm":
+      return `pnpm dlx ${packageName}`;
+    case "yarn":
+      return `yarn dlx ${packageName}`;
+    case "bun":
+      return `bunx ${packageName}`;
+    default:
+      return `npx ${packageName}`;
+  }
+}
+
+export function formatSuggestedCliCommand(
+  subcommand,
+  { packageName = PACKAGE_NAME, argv = process.argv, suggestedInvocation } = {}
+) {
+  const invoke = suggestedInvocation ?? resolveSuggestedInvocation(packageName, argv);
+  const trimmed = subcommand.trim();
+  return trimmed ? `${invoke} ${trimmed}` : invoke;
+}

package/src/global/brand/index.js

@@ -82,4 +82,10 @@ export function commandHeader(label) {
   return `${BRAND.displayName} ${label}`;
 }
 
-export { formatCliCommand, PREFERRED_CLI } from "./cli.js";
+export {
+  formatCliCommand,
+  formatSuggestedCliCommand,
+  PACKAGE_NAME,
+  PREFERRED_CLI,
+  resolveSuggestedInvocation
+} from "./cli.js";

package/src/global/ink/setup-state.js

@@ -1,4 +1,4 @@
-import { AGENT_HINTS, BRAND, PREFERRED_CLI, formatCliCommand, getAgentLabel, WIZARD_COPY } from "../brand/index.js";
+import { AGENT_HINTS, BRAND, formatCliCommand, getAgentLabel, PREFERRED_CLI, WIZARD_COPY } from "../brand/index.js";
 import { formatAgentMultiselectHint } from "../clack/theme.js";
 
 export const SETUP_STEPS = {