@kal-elsam/kairo-runtime 0.1.0

package/scripts/install.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env sh
+# Bootstrap installer for Kairo Runtime (@kal-elsam/kairo-runtime).
+#
+# Safe by design:
+#   - no sudo
+#   - no shell profile changes
+#   - does not install Cursor/Codex/OpenCode/Claude
+#   - default ends with setup --dry-run (no writes)
+#   - explicit apply: pass --yes to run setup --yes
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh
+#   curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --dry-run
+#   curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --yes
+#   curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --version 0.13.0
+#   curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --agents all --yes
+#
+set -eu
+
+PACKAGE="@kal-elsam/kairo-runtime"
+PREFERRED_CLI="kairo"
+VERSION="latest"
+INSTALLER_DRY_RUN=0
+APPLY=0
+SETUP_EXTRA=""
+
+usage() {
+  printf '%s\n' \
+    "Kairo Runtime bootstrap installer" \
+    "" \
+    "Usage:" \
+    "  install.sh [--dry-run] [--yes] [--version <semver|latest>]" \
+    "             [--agents <list|all>] [--components <list>] [--no-default-components]" \
+    "" \
+    "Options:" \
+    "  --dry-run              Print the plan only. Does not download or run kairo." \
+    "  --yes, -y              Apply setup (runs kairo setup --yes)." \
+    "  --version <version>    Package version to run (default: latest)." \
+    "  --agents <list|all>    Passed through to kairo setup." \
+    "  --components <list>    Passed through to kairo setup." \
+    "  --no-default-components  Passed through to kairo setup." \
+    "  -h, --help             Show this help." \
+    "" \
+    "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." \
+    "" \
+    "Security:" \
+    "  - Never uses sudo." \
+    "  - Never modifies shell profiles (.bashrc, .zshrc, etc.)." \
+    "  - Never installs Cursor/Codex/OpenCode/Claude." \
+    "  - Default preview only (setup --dry-run). Writes managed sections only with --yes."
+}
+
+die() {
+  printf '%s\n' "$*" >&2
+  exit 1
+}
+
+append_setup_arg() {
+  SETUP_EXTRA="${SETUP_EXTRA}${SETUP_EXTRA:+ }$1"
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --dry-run)
+      INSTALLER_DRY_RUN=1
+      shift
+      ;;
+    --yes|-y)
+      APPLY=1
+      shift
+      ;;
+    --version)
+      [ "$#" -ge 2 ] || die "Missing value for --version"
+      VERSION="$2"
+      shift 2
+      ;;
+    --version=*)
+      VERSION="${1#*=}"
+      shift
+      ;;
+    --agents)
+      [ "$#" -ge 2 ] || die "Missing value for --agents"
+      append_setup_arg "--agents"
+      append_setup_arg "$2"
+      shift 2
+      ;;
+    --agents=*)
+      append_setup_arg "$1"
+      shift
+      ;;
+    --components)
+      [ "$#" -ge 2 ] || die "Missing value for --components"
+      append_setup_arg "--components"
+      append_setup_arg "$2"
+      shift 2
+      ;;
+    --components=*)
+      append_setup_arg "$1"
+      shift
+      ;;
+    --no-default-components)
+      append_setup_arg "--no-default-components"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "Unknown option: $1 (try --help)"
+      ;;
+  esac
+done
+
+[ -n "$VERSION" ] || die "--version must not be empty"
+
+if [ "$APPLY" -eq 1 ]; then
+  SETUP_MODE="--yes"
+else
+  SETUP_MODE="--dry-run"
+fi
+
+require_cmd() {
+  command_name="$1"
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    die "Missing required command: ${command_name}
+Install Node.js 20.12+ (includes npm), then re-run this installer.
+https://nodejs.org/"
+  fi
+}
+
+require_cmd node
+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
+
+printf '%s\n' \
+  "Kairo Runtime bootstrap installer" \
+  "================================" \
+  "" \
+  "Prerequisites:" \
+  "  node  ${NODE_VERSION:-unknown}" \
+  "  npm   ${NPM_VERSION:-unknown}" \
+  "  runner ${RUNNER}" \
+  "" \
+  "Will run:" \
+  "  ${RUN_CMD}" \
+  "" \
+  "Effects:" \
+  "  - Downloads/runs ${PACKAGE}@${VERSION} via npm (no global install required)." \
+  "  - Configures managed sections only (never installs AI apps)." \
+  "  - Never uses sudo or modifies shell profiles." \
+  ""
+
+if [ "$APPLY" -eq 1 ]; then
+  printf '%s\n' \
+    "  - Applies the ecosystem plan (setup --yes)." \
+    "  - Writes managed agent sections and ~/.harness components." \
+    ""
+else
+  printf '%s\n' \
+    "  - Previews the local ecosystem plan (setup --dry-run)." \
+    "  - Does NOT write agent configs or ~/.harness." \
+    ""
+fi
+
+if [ "$INSTALLER_DRY_RUN" -eq 1 ]; then
+  printf '%s\n' "Dry run: plan only. Nothing was downloaded or executed."
+  exit 0
+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
+
+if [ "$APPLY" -eq 1 ]; then
+  printf '%s\n' \
+    "" \
+    "Bootstrap complete (applied)." \
+    "Next steps:" \
+    "  1. Check health:    ${PREFERRED_CLI} status" \
+    "  2. Repair drift:    ${PREFERRED_CLI} sync" \
+    "  3. Upgrade latest:  npx ${PACKAGE}@latest setup --yes" \
+    "" \
+    "Version:" \
+    "  Installed CLI:      npx ${PACKAGE} --version" \
+    "  Published package:  npm view ${PACKAGE} version" \
+    "  Preview upgrade:    ${PREFERRED_CLI} upgrade --dry-run"
+else
+  printf '%s\n' \
+    "" \
+    "Bootstrap complete." \
+    "Next steps:" \
+    "  1. Apply the plan:  npx ${PACKAGE}@${VERSION} setup --yes" \
+    "     (or re-run installer: curl ... | sh -s -- --yes)" \
+    "  2. Check health:    npx ${PACKAGE}@${VERSION} status" \
+    "  3. Repair drift:    npx ${PACKAGE}@${VERSION} sync" \
+    "" \
+    "Version:" \
+    "  Installed CLI:      npx ${PACKAGE} --version" \
+    "  Published package:  npm view ${PACKAGE} version" \
+    "  Update / converge:  npx ${PACKAGE}@latest sync"
+fi

package/scripts/installer-smoke-test.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="@kal-elsam/kairo-runtime"
+PREFERRED_CLI="kairo"
+VERSION="latest"
+REPO="Kal-elSam/harness"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --package)
+      PACKAGE="$2"
+      shift 2
+      ;;
+    --package=*)
+      PACKAGE="${1#*=}"
+      shift
+      ;;
+    --version)
+      VERSION="$2"
+      shift 2
+      ;;
+    --version=*)
+      VERSION="${1#*=}"
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+WORKDIR="$(mktemp -d)"
+FAKE_HOME="$(mktemp -d)"
+NPM_CACHE="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$WORKDIR" "$FAKE_HOME" "$NPM_CACHE"
+}
+trap cleanup EXIT
+
+assert_harness_home_isolated() {
+  if [ -z "${HARNESS_HOME:-}" ]; then
+    echo "HARNESS_HOME must be set for installer smoke tests" >&2
+    exit 1
+  fi
+
+  if [ "$HARNESS_HOME" = "$HOME" ] || [ "$HARNESS_HOME" = "${HOME}/.harness" ]; then
+    echo "Installer smoke must not use the real home directory" >&2
+    exit 1
+  fi
+}
+
+resolve_install_script_url() {
+  if [ "$VERSION" = "latest" ]; then
+    printf '%s\n' "https://raw.githubusercontent.com/${REPO}/main/scripts/install.sh"
+    return
+  fi
+
+  printf '%s\n' "https://raw.githubusercontent.com/${REPO}/v${VERSION}/scripts/install.sh"
+}
+
+assert_no_harness_state() {
+  if [ -d "$HARNESS_HOME/.harness" ]; then
+    echo "Expected no ~/.harness state at $HARNESS_HOME/.harness" >&2
+    exit 1
+  fi
+}
+
+assert_status_ok() {
+  local status_json="$1"
+  node -e "
+const payload = JSON.parse(process.argv[1]);
+if (!payload.ok || payload.overall !== 'ok') {
+  console.error('Expected status --json overall=ok');
+  process.exit(1);
+}
+const managed = payload.agents.filter((agent) => agent.managed).map((agent) => agent.id).sort();
+const expected = ['claude', 'codex', 'cursor', 'opencode'];
+if (JSON.stringify(managed) !== JSON.stringify(expected)) {
+  console.error('Expected all four agents managed');
+  process.exit(1);
+}
+" "$status_json"
+}
+
+assert_managed_configs_removed() {
+  node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const home = process.env.HARNESS_HOME;
+const targets = [
+  '.cursor/AGENTS.md',
+  '.codex/AGENTS.md',
+  '.config/opencode/AGENTS.md',
+  '.claude/CLAUDE.md'
+];
+
+for (const relativePath of targets) {
+  const filePath = path.join(home, relativePath);
+  if (!fs.existsSync(filePath)) continue;
+  const content = fs.readFileSync(filePath, 'utf8');
+  if (content.includes('<!-- harness:managed:start -->')) {
+    console.error('Managed marker still present in ' + relativePath);
+    process.exit(1);
+  }
+}
+"
+}
+
+export HARNESS_HOME="$FAKE_HOME"
+export npm_config_cache="$NPM_CACHE"
+assert_harness_home_isolated
+
+cd "$WORKDIR"
+
+INSTALL_SCRIPT_URL="$(resolve_install_script_url)"
+echo "Installer smoke for ${PACKAGE}@${VERSION}"
+echo "Install script: ${INSTALL_SCRIPT_URL}"
+echo "Harness home: ${HARNESS_HOME}"
+
+echo
+echo "== curl install.sh | sh --version ${VERSION} (preview, no writes) =="
+curl -fsSL "$INSTALL_SCRIPT_URL" | sh -s -- --version "$VERSION"
+assert_no_harness_state
+
+mkdir -p \
+  "$FAKE_HOME/.cursor" \
+  "$FAKE_HOME/.codex" \
+  "$FAKE_HOME/.config/opencode" \
+  "$FAKE_HOME/.claude"
+
+echo
+echo "== curl install.sh | sh --version ${VERSION} --yes --agents all =="
+curl -fsSL "$INSTALL_SCRIPT_URL" | sh -s -- --version "$VERSION" --yes --agents all
+
+if [ ! -d "$FAKE_HOME/.harness" ]; then
+  echo "Expected install.sh --yes to create ~/.harness state" >&2
+  exit 1
+fi
+
+echo
+echo "== ${PREFERRED_CLI} status --json =="
+STATUS_JSON="$(npx --yes "${PACKAGE}@${VERSION}" status --json)"
+echo "$STATUS_JSON"
+assert_status_ok "$STATUS_JSON"
+
+echo
+echo "== ${PREFERRED_CLI} uninstall =="
+npx --yes "${PACKAGE}@${VERSION}" uninstall
+assert_managed_configs_removed
+
+echo
+echo "Installer smoke test passed."

package/scripts/lib/attribution-guard.mjs

@@ -0,0 +1,59 @@
+const ATTRIBUTION_PATTERN = /co-authored-by/i;
+
+export function assertCleanReleaseMessage(message) {
+  if (ATTRIBUTION_PATTERN.test(message)) {
+    throw new Error("Release commit message must not contain Co-authored-by or AI attribution.");
+  }
+}
+
+export function assertCleanReleaseMessages(messages) {
+  for (const message of messages) {
+    assertCleanReleaseMessage(message);
+  }
+}
+
+export function parseAttributionGuardArgs(argv) {
+  const args = [...argv];
+  let range = null;
+
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--range") {
+      range = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--range=")) {
+      range = arg.slice("--range=".length);
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  if (range !== null && range.trim() === "") {
+    throw new Error("Missing value for --range.");
+  }
+
+  return { range };
+}
+
+export function readCommitMessages({ range = null, runGit }) {
+  if (range) {
+    const output = runGit(`git log ${range} --format=%B%x1E`).trim();
+    if (!output) return [];
+
+    return output
+      .split("\x1E")
+      .filter((message) => message.length > 0);
+  }
+
+  return [runGit("git log -1 --format=%B")];
+}
+
+export function runAttributionGuard({ range = null, runGit }) {
+  const messages = readCommitMessages({ range, runGit });
+  assertCleanReleaseMessages(messages);
+  return { checked: messages.length, range };
+}

package/scripts/registry-smoke-test.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="@kal-elsam/kairo-runtime"
+PREFERRED_CLI="kairo"
+VERSION="latest"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --package)
+      PACKAGE="$2"
+      shift 2
+      ;;
+    --package=*)
+      PACKAGE="${1#*=}"
+      shift
+      ;;
+    --version)
+      VERSION="$2"
+      shift 2
+      ;;
+    --version=*)
+      VERSION="${1#*=}"
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+WORKDIR="$(mktemp -d)"
+FAKE_HOME="$(mktemp -d)"
+NPM_CACHE="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$WORKDIR" "$FAKE_HOME" "$NPM_CACHE"
+}
+trap cleanup EXIT
+
+assert_harness_home_isolated() {
+  if [ -z "${HARNESS_HOME:-}" ]; then
+    echo "HARNESS_HOME must be set for registry smoke tests" >&2
+    exit 1
+  fi
+
+  if [ "$HARNESS_HOME" = "$HOME" ] || [ "$HARNESS_HOME" = "${HOME}/.harness" ]; then
+    echo "Registry smoke must not use the real home directory" >&2
+    exit 1
+  fi
+}
+
+export HARNESS_HOME="$FAKE_HOME"
+export npm_config_cache="$NPM_CACHE"
+assert_harness_home_isolated
+
+mkdir -p \
+  "$FAKE_HOME/.cursor" \
+  "$FAKE_HOME/.codex" \
+  "$FAKE_HOME/.config/opencode" \
+  "$FAKE_HOME/.claude"
+
+echo "Installing ${PACKAGE}@${VERSION} from npm registry"
+cd "$WORKDIR"
+npm init -y >/dev/null
+npm install "${PACKAGE}@${VERSION}" >/dev/null
+
+INSTALLED_VERSION="$(node -p "require('./node_modules/${PACKAGE}/package.json').version")"
+echo "Installed ${PACKAGE}@${INSTALLED_VERSION}"
+
+if [ "$VERSION" != "latest" ] && [ "$INSTALLED_VERSION" != "$VERSION" ]; then
+  echo "Expected version ${VERSION}, got ${INSTALLED_VERSION}" >&2
+  exit 1
+fi
+
+CLI_VERSION="$(npx --no-install ${PREFERRED_CLI} --version)"
+if [ "$CLI_VERSION" != "$INSTALLED_VERSION" ]; then
+  echo "${PREFERRED_CLI} --version (${CLI_VERSION}) does not match installed package (${INSTALLED_VERSION})" >&2
+  exit 1
+fi
+
+echo
+echo "== ${PREFERRED_CLI} setup --dry-run =="
+npx --no-install ${PREFERRED_CLI} setup --dry-run
+
+echo
+echo "== ${PREFERRED_CLI} setup --yes =="
+npx --no-install ${PREFERRED_CLI} setup --yes
+
+echo
+echo "== ${PREFERRED_CLI} adapters --json =="
+ADAPTERS_JSON="$(npx --no-install ${PREFERRED_CLI} adapters --json)"
+echo "$ADAPTERS_JSON"
+node -e "
+const payload = JSON.parse(process.argv[1]);
+const expected = ['cursor', 'codex', 'opencode', 'claude'].sort();
+if (payload.managedCount !== 4 || payload.detectedCount !== 4) process.exit(1);
+const managed = payload.adapters.filter((entry) => entry.managed).map((entry) => entry.id).sort();
+if (JSON.stringify(managed) !== JSON.stringify(expected)) process.exit(1);
+" "$ADAPTERS_JSON"
+
+echo
+echo "== ${PREFERRED_CLI} status --json =="
+STATUS_JSON="$(npx --no-install ${PREFERRED_CLI} status --json)"
+echo "$STATUS_JSON"
+node -e "
+const payload = JSON.parse(process.argv[1]);
+if (!payload.ok || payload.overall !== 'ok') process.exit(1);
+const managed = payload.agents.filter((agent) => agent.managed).map((agent) => agent.id).sort();
+const expected = ['claude', 'codex', 'cursor', 'opencode'];
+if (JSON.stringify(managed) !== JSON.stringify(expected)) process.exit(1);
+" "$STATUS_JSON"
+
+echo
+echo "== ${PREFERRED_CLI} upgrade --dry-run =="
+npx --no-install ${PREFERRED_CLI} upgrade --dry-run
+
+echo
+echo "== simulate drift =="
+rm -f "$FAKE_HOME/.harness/components/sdd-core/workflow.md"
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const config = path.join(process.env.HARNESS_HOME, '.config', 'opencode', 'AGENTS.md');
+const content = fs.readFileSync(config, 'utf8');
+fs.writeFileSync(config, content.replace('### SDD Core', '### Broken'));
+"
+
+echo
+echo "== ${PREFERRED_CLI} sync =="
+npx --no-install ${PREFERRED_CLI} sync --yes
+
+echo
+echo "== ${PREFERRED_CLI} status --json confirms OK =="
+STATUS_JSON="$(npx --no-install ${PREFERRED_CLI} status --json)"
+echo "$STATUS_JSON"
+OVERALL="$(node -e "const p=JSON.parse(process.argv[1]); if(!p.ok||p.overall!=='ok'){process.exit(1)} console.log(p.overall)" "$STATUS_JSON")"
+if [ "$OVERALL" != "ok" ]; then
+  echo "Expected status --json overall=ok after sync" >&2
+  exit 1
+fi
+
+echo
+echo "== ${PREFERRED_CLI} uninstall =="
+npx --no-install ${PREFERRED_CLI} uninstall
+
+echo
+echo "Registry smoke test passed."