stagent 0.9.6 → 0.11.0

package/src/lib/instance/bootstrap.ts

@@ -0,0 +1,270 @@
+import { randomUUID } from "crypto";
+import { existsSync, readFileSync, writeFileSync, chmodSync, renameSync } from "fs";
+import { join } from "path";
+import type { EnsureStepResult, EnsureResult, GitOps, ConsentStatus } from "./types";
+import { getInstanceConfig, setInstanceConfig, getGuardrails, setGuardrails } from "./settings";
+import { isPrivateInstance, isDevMode, hasGitDir, detectRebaseInProgress } from "./detect";
+import { createGitOps } from "./git-ops";
+
+const DEFAULT_BRANCH_NAME = "local";
+
+/**
+ * Phase A step 1: ensure the instance config row exists with a stable instanceId.
+ * Idempotent — returns early if config already exists.
+ */
+export async function ensureInstanceConfig(): Promise<EnsureStepResult> {
+  const existing = getInstanceConfig();
+  if (existing) {
+    return { step: "instance-config", status: "skipped", reason: "already_exists" };
+  }
+  await setInstanceConfig({
+    instanceId: randomUUID(),
+    branchName: DEFAULT_BRANCH_NAME,
+    isPrivateInstance: isPrivateInstance(),
+    createdAt: Math.floor(Date.now() / 1000),
+  });
+  return { step: "instance-config", status: "ok" };
+}
+
+/**
+ * Phase A step 2: create the `local` branch at current HEAD if it doesn't exist.
+ * Non-destructive: `git checkout -b local` preserves whatever branch the user
+ * was on, including any local commits. Safe on drifted-main scenarios.
+ */
+export function ensureLocalBranch(git: GitOps): EnsureStepResult {
+  if (git.branchExists(DEFAULT_BRANCH_NAME)) {
+    return { step: "local-branch", status: "skipped", reason: "branch_exists" };
+  }
+  try {
+    git.createAndCheckoutBranch(DEFAULT_BRANCH_NAME);
+    return { step: "local-branch", status: "ok" };
+  } catch (err) {
+    return {
+      step: "local-branch",
+      status: "failed",
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export const STAGENT_HOOK_VERSION = "1.0.0";
+
+/**
+ * Pre-push hook template. Installed verbatim at .git/hooks/pre-push.
+ *
+ * Reads the blocked branch list from the stagent SQLite settings table
+ * via a bounded sqlite3 invocation. The query is hardcoded — no user
+ * input reaches the shell.
+ *
+ * Escape hatch: set ALLOW_PRIVATE_PUSH=1 in env to bypass the guardrail
+ * for legitimate cherry-pick pushes.
+ */
+const PRE_PUSH_HOOK_TEMPLATE = `#!/bin/sh
+# STAGENT_HOOK_VERSION=${STAGENT_HOOK_VERSION}
+# Blocks pushes of private instance branches to origin.
+# Escape hatch: ALLOW_PRIVATE_PUSH=1 git push ...
+#
+# Generated by src/lib/instance/bootstrap.ts — do not edit manually.
+
+if [ "$ALLOW_PRIVATE_PUSH" = "1" ]; then
+  exit 0
+fi
+
+current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$current_branch" ]; then
+  exit 0
+fi
+
+data_dir="\${STAGENT_DATA_DIR:-$HOME/.stagent}"
+db_path="$data_dir/stagent.db"
+if [ ! -f "$db_path" ] || ! command -v sqlite3 >/dev/null 2>&1; then
+  exit 0
+fi
+
+blocked_json=$(sqlite3 "$db_path" "SELECT value FROM settings WHERE key='instance.guardrails';" 2>/dev/null)
+if [ -z "$blocked_json" ]; then
+  exit 0
+fi
+
+if echo "$blocked_json" | grep -q "\\"$current_branch\\""; then
+  echo "stagent: refusing to push private instance branch '$current_branch' to origin." >&2
+  echo "stagent: set ALLOW_PRIVATE_PUSH=1 to override (not recommended)." >&2
+  exit 1
+fi
+
+exit 0
+`;
+
+/**
+ * Phase B step 1: install the pre-push hook at .git/hooks/pre-push.
+ * Idempotent: checks version marker in existing file; backs up foreign hooks.
+ */
+export function ensurePrePushHook(git: GitOps): EnsureStepResult {
+  const hookPath = join(git.getGitDir(), "hooks", "pre-push");
+  const markerLine = `STAGENT_HOOK_VERSION=${STAGENT_HOOK_VERSION}`;
+
+  if (existsSync(hookPath)) {
+    const existing = readFileSync(hookPath, "utf-8");
+    if (existing.includes(markerLine)) {
+      return { step: "pre-push-hook", status: "skipped", reason: "already_installed" };
+    }
+    if (existing.includes("STAGENT_HOOK_VERSION=")) {
+      try {
+        writeFileSync(hookPath, PRE_PUSH_HOOK_TEMPLATE, { mode: 0o755 });
+        return { step: "pre-push-hook", status: "ok", reason: "upgraded" };
+      } catch (err) {
+        return {
+          step: "pre-push-hook",
+          status: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+    try {
+      renameSync(hookPath, `${hookPath}.stagent-backup`);
+    } catch (err) {
+      return {
+        step: "pre-push-hook",
+        status: "failed",
+        reason: `backup_failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  try {
+    writeFileSync(hookPath, PRE_PUSH_HOOK_TEMPLATE, { mode: 0o755 });
+    chmodSync(hookPath, 0o755);
+    return { step: "pre-push-hook", status: "ok" };
+  } catch (err) {
+    return {
+      step: "pre-push-hook",
+      status: "failed",
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Phase B step 2: set branch.<name>.pushRemote=no_push for each blocked branch.
+ * Idempotent via git config semantics (setting the same value is a no-op).
+ */
+export function ensureBranchPushConfig(git: GitOps, branches: string[]): EnsureStepResult {
+  const failures: string[] = [];
+  for (const branch of branches) {
+    try {
+      git.setConfig(`branch.${branch}.pushRemote`, "no_push");
+    } catch (err) {
+      failures.push(`${branch}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (failures.length > 0) {
+    return {
+      step: "branch-push-config",
+      status: "failed",
+      reason: failures.join("; "),
+    };
+  }
+  return { step: "branch-push-config", status: "ok" };
+}
+
+export interface ConsentDecision {
+  shouldRunPhaseB: boolean;
+  reason: ConsentStatus;
+}
+
+/**
+ * Reads the current consent status from settings and returns a decision
+ * about whether Phase B (destructive guardrail installation) should run.
+ *
+ * On first call, stamps firstBootCompletedAt so the system has a record
+ * that bootstrap has run at least once. This enables the upgrade-session
+ * feature to distinguish "never booted" from "booted but consent not yet
+ * given" in its Settings → Instance UI.
+ *
+ * Does NOT create any UI artifact. The prompt surface is owned by
+ * upgrade-session, which renders a "Enable guardrails" action in the
+ * Settings → Instance section reading from settings.instance.guardrails.
+ */
+export async function resolveConsentDecision(): Promise<ConsentDecision> {
+  const current = getGuardrails();
+
+  if (current.firstBootCompletedAt === null) {
+    await setGuardrails({
+      ...current,
+      firstBootCompletedAt: Math.floor(Date.now() / 1000),
+    });
+  }
+
+  return {
+    shouldRunPhaseB: current.consentStatus === "enabled",
+    reason: current.consentStatus,
+  };
+}
+
+/**
+ * Main entry point called from src/instrumentation.ts.
+ * Idempotent — safe to run on every boot.
+ *
+ * Execution order:
+ * 1. Dev-mode gates (env + sentinel) — skip entirely if active
+ * 2. .git presence check — skip if absent (npx runtime)
+ * 3. Phase A: instanceId, local branch (non-destructive, always runs)
+ * 4. Consent: resolves consent decision (stamps firstBootCompletedAt on first call)
+ * 5. Phase B: pre-push hook, pushRemote config (only if consent=enabled)
+ */
+export async function ensureInstance(cwd: string = process.cwd()): Promise<EnsureResult> {
+  if (isDevMode(cwd)) {
+    const reason = process.env.STAGENT_DEV_MODE === "true" ? "dev_mode_env" : "dev_mode_sentinel";
+    return { skipped: reason, steps: [] };
+  }
+
+  if (!hasGitDir(cwd)) {
+    return { skipped: "no_git", steps: [] };
+  }
+
+  const steps: EnsureStepResult[] = [];
+  const git = createGitOps(cwd);
+
+  // Phase A step 1: instance config
+  steps.push(await ensureInstanceConfig());
+
+  // Phase A step 2: local branch — skip if rebase in progress
+  if (detectRebaseInProgress(cwd)) {
+    steps.push({ step: "local-branch", status: "skipped", reason: "rebase_in_progress" });
+  } else {
+    steps.push(ensureLocalBranch(git));
+  }
+
+  // Resolve consent (stamps firstBootCompletedAt on first call, returns decision)
+  const decision = await resolveConsentDecision();
+
+  // Phase B — only if user has explicitly enabled guardrails
+  if (decision.shouldRunPhaseB) {
+    const hookResult = ensurePrePushHook(git);
+    steps.push(hookResult);
+
+    const config = getInstanceConfig();
+    const blockedBranches = config ? [config.branchName] : [];
+    if (blockedBranches.length > 0) {
+      const configResult = ensureBranchPushConfig(git, blockedBranches);
+      steps.push(configResult);
+
+      // Persist guardrail state back to settings so the pre-push hook can
+      // read the list of blocked branches at push time (the hook greps the
+      // serialized JSON of settings.instance.guardrails for the current
+      // branch name). Without this write, the hook would silently allow
+      // all pushes because pushRemoteBlocked would stay [].
+      if (hookResult.status !== "failed" && configResult.status !== "failed") {
+        const current = getGuardrails();
+        await setGuardrails({
+          ...current,
+          prePushHookInstalled: true,
+          prePushHookVersion: STAGENT_HOOK_VERSION,
+          pushRemoteBlocked: blockedBranches,
+        });
+      }
+    }
+  }
+
+  return { steps };
+}

package/src/lib/instance/detect.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+import { homedir } from "os";
+
+/**
+ * Returns true if the current environment is the canonical stagent dev repo
+ * and should skip all instance bootstrap operations.
+ *
+ * Layered gates:
+ * 1. STAGENT_DEV_MODE=true env var (primary, per-developer)
+ * 2. .git/stagent-dev-mode sentinel file (secondary, git-dir-scoped)
+ *
+ * Override: STAGENT_INSTANCE_MODE=true forces bootstrap to run even in dev
+ * mode, so contributors can test the feature in the main repo.
+ */
+export function isDevMode(cwd: string = process.cwd()): boolean {
+  if (process.env.STAGENT_INSTANCE_MODE === "true") return false;
+  if (process.env.STAGENT_DEV_MODE === "true") return true;
+  if (existsSync(join(cwd, ".git", "stagent-dev-mode"))) return true;
+  return false;
+}
+
+/** Returns true if a .git directory exists at the given path. */
+export function hasGitDir(cwd: string = process.cwd()): boolean {
+  return existsSync(join(cwd, ".git"));
+}
+
+/**
+ * Returns true if STAGENT_DATA_DIR is set to a non-default path,
+ * indicating this clone is running as an isolated private instance.
+ */
+export function isPrivateInstance(): boolean {
+  const override = process.env.STAGENT_DATA_DIR;
+  if (!override) return false;
+  const defaultDir = join(homedir(), ".stagent");
+  return resolve(override) !== resolve(defaultDir);
+}
+
+/**
+ * Returns true if a rebase is in progress in the current repo.
+ * Both rebase-merge (interactive) and rebase-apply (non-interactive) are detected.
+ */
+export function detectRebaseInProgress(cwd: string = process.cwd()): boolean {
+  const gitDir = join(cwd, ".git");
+  return (
+    existsSync(join(gitDir, "rebase-merge")) ||
+    existsSync(join(gitDir, "rebase-apply"))
+  );
+}

package/src/lib/instance/fingerprint.ts

@@ -0,0 +1,76 @@
+/**
+ * Machine fingerprint generator.
+ *
+ * Produces a stable, non-identifying hash that uniquely identifies the machine
+ * this stagent instance is running on. Used to give each stagent instance a
+ * durable identity (e.g., for telemetry correlation and multi-instance
+ * disambiguation); no billing or cloud-metering dependency.
+ *
+ * The fingerprint is derived from:
+ *   1. os.hostname() — e.g., "macbook-pro.local"
+ *   2. os.userInfo().username — e.g., "navam"
+ *   3. SHA-256 of the first non-internal MAC address
+ *
+ * The MAC is hashed before it leaves the process so the raw network identifier
+ * never appears in logs or telemetry. The combined inputs are SHA-256'd
+ * together to produce a 64-character hex string.
+ *
+ * Stability: the fingerprint is stable across reboots and stagent restarts
+ * on the same machine. It changes if the user renames their account, renames
+ * their machine, or swaps network hardware.
+ */
+
+import { createHash } from "crypto";
+import { hostname, userInfo, networkInterfaces } from "os";
+
+let cachedFingerprint: string | null = null;
+
+export function getMachineFingerprint(): string {
+  if (cachedFingerprint !== null) return cachedFingerprint;
+
+  const host = safeHostname();
+  const user = safeUsername();
+  const macHash = hashPrimaryMac();
+
+  const combined = `${host}|${user}|${macHash}`;
+  cachedFingerprint = createHash("sha256").update(combined).digest("hex");
+  return cachedFingerprint;
+}
+
+/** Exposed for tests that need to reset the module-level cache. */
+export function _resetFingerprintCache(): void {
+  cachedFingerprint = null;
+}
+
+function safeHostname(): string {
+  try {
+    return hostname();
+  } catch {
+    return "unknown-host";
+  }
+}
+
+function safeUsername(): string {
+  try {
+    return userInfo().username;
+  } catch {
+    return "unknown-user";
+  }
+}
+
+function hashPrimaryMac(): string {
+  try {
+    const interfaces = networkInterfaces();
+    for (const name of Object.keys(interfaces).sort()) {
+      const addrs = interfaces[name] ?? [];
+      for (const addr of addrs) {
+        if (addr.internal) continue;
+        if (!addr.mac || addr.mac === "00:00:00:00:00:00") continue;
+        return createHash("sha256").update(addr.mac).digest("hex");
+      }
+    }
+  } catch {
+    // fall through to the default below
+  }
+  return "no-mac-detected";
+}

package/src/lib/instance/git-ops.ts

@@ -0,0 +1,95 @@
+import { execFileSync } from "child_process";
+import { join, resolve } from "path";
+import type { GitOps } from "./types";
+
+/**
+ * Real git operations wrapper. All commands use execFileSync with argv arrays —
+ * no shell interpolation, ever. File is the literal "git"; user-provided values
+ * flow through the args array which git parses without shell involvement.
+ *
+ * The cwd parameter is normalized to an absolute path at factory creation time
+ * so getGitDir() honors its interface contract of returning an absolute path.
+ */
+export function createGitOps(cwd: string = process.cwd()): GitOps {
+  const absoluteCwd = resolve(cwd);
+  function run(args: string[]): string {
+    return execFileSync("git", args, {
+      cwd: absoluteCwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  }
+
+  return {
+    isGitRepo(): boolean {
+      try {
+        run(["rev-parse", "--is-inside-work-tree"]);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    getGitDir(): string {
+      return join(absoluteCwd, ".git");
+    },
+
+    getCurrentBranch(): string | null {
+      try {
+        const branch = run(["rev-parse", "--abbrev-ref", "HEAD"]);
+        return branch === "HEAD" ? null : branch;
+      } catch {
+        return null;
+      }
+    },
+
+    branchExists(name: string): boolean {
+      try {
+        run(["rev-parse", "--verify", `refs/heads/${name}`]);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    createAndCheckoutBranch(name: string): void {
+      run(["checkout", "-b", name]);
+    },
+
+    setConfig(key: string, value: string): void {
+      run(["config", key, value]);
+    },
+
+    fetchOrigin(): void {
+      run(["fetch", "origin", "main"]);
+    },
+
+    revParse(ref: string): string | null {
+      try {
+        return run(["rev-parse", ref]);
+      } catch {
+        return null;
+      }
+    },
+
+    countCommitsAhead(from: string, to: string): number {
+      try {
+        const out = run(["rev-list", "--count", `${from}..${to}`]);
+        const n = parseInt(out, 10);
+        return Number.isFinite(n) ? n : 0;
+      } catch {
+        return 0;
+      }
+    },
+  };
+}
+
+/** Test helper: detect if execFileSync would find git on this system. */
+export function isGitAvailable(): boolean {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/instance/settings.ts

@@ -0,0 +1,61 @@
+import { getSettingSync, setSetting } from "@/lib/settings/helpers";
+import type { InstanceConfig, Guardrails, UpgradeState } from "./types";
+
+const INSTANCE_KEY = "instance";
+const GUARDRAILS_KEY = "instance.guardrails";
+
+const DEFAULT_GUARDRAILS: Guardrails = {
+  prePushHookInstalled: false,
+  prePushHookVersion: "",
+  pushRemoteBlocked: [],
+  consentStatus: "not_yet",
+  firstBootCompletedAt: null,
+};
+
+function readJson<T>(key: string): T | null {
+  const raw = getSettingSync(key);
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function getInstanceConfig(): InstanceConfig | null {
+  return readJson<InstanceConfig>(INSTANCE_KEY);
+}
+
+export async function setInstanceConfig(config: InstanceConfig): Promise<void> {
+  await setSetting(INSTANCE_KEY, JSON.stringify(config));
+}
+
+export function getGuardrails(): Guardrails {
+  return readJson<Guardrails>(GUARDRAILS_KEY) ?? { ...DEFAULT_GUARDRAILS };
+}
+
+export async function setGuardrails(guardrails: Guardrails): Promise<void> {
+  await setSetting(GUARDRAILS_KEY, JSON.stringify(guardrails));
+}
+
+const UPGRADE_KEY = "instance.upgrade";
+
+const DEFAULT_UPGRADE_STATE: UpgradeState = {
+  lastPolledAt: null,
+  lastUpstreamSha: null,
+  localMainSha: null,
+  upgradeAvailable: false,
+  commitsBehind: 0,
+  lastSuccessfulUpgradeAt: null,
+  lastUpgradeTaskId: null,
+  pollFailureCount: 0,
+  lastPollError: null,
+};
+
+export function getUpgradeState(): UpgradeState {
+  return readJson<UpgradeState>(UPGRADE_KEY) ?? { ...DEFAULT_UPGRADE_STATE };
+}
+
+export async function setUpgradeState(state: UpgradeState): Promise<void> {
+  await setSetting(UPGRADE_KEY, JSON.stringify(state));
+}

package/src/lib/instance/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Instance bootstrap shared types.
+ * See features/instance-bootstrap.md for full design rationale.
+ */
+
+export interface InstanceConfig {
+  instanceId: string;
+  branchName: string;
+  isPrivateInstance: boolean;
+  createdAt: number;
+}
+
+export type ConsentStatus = "not_yet" | "enabled" | "declined_permanently";
+
+export interface Guardrails {
+  prePushHookInstalled: boolean;
+  prePushHookVersion: string;
+  pushRemoteBlocked: string[];
+  consentStatus: ConsentStatus;
+  firstBootCompletedAt: number | null;
+}
+
+export interface UpgradeState {
+  lastPolledAt: number | null;
+  lastUpstreamSha: string | null;
+  localMainSha: string | null;
+  upgradeAvailable: boolean;
+  commitsBehind: number;
+  lastSuccessfulUpgradeAt: number | null;
+  lastUpgradeTaskId: string | null;
+  pollFailureCount: number;
+  lastPollError: string | null;
+}
+
+export type EnsureSkipReason =
+  | "dev_mode_env"
+  | "dev_mode_sentinel"
+  | "no_git";
+
+export type EnsureStepStatus = "ok" | "skipped" | "failed";
+
+export interface EnsureStepResult {
+  step: string;
+  status: EnsureStepStatus;
+  reason?: string;
+}
+
+export interface EnsureResult {
+  skipped?: EnsureSkipReason;
+  steps: EnsureStepResult[];
+}
+
+/**
+ * Injectable wrapper around git commands.
+ * Real implementation in git-ops.ts uses execFileSync.
+ * Tests provide a mock implementation.
+ */
+export interface GitOps {
+  /** Returns true if the current working directory is inside a git repo (not a worktree of the main repo). */
+  isGitRepo(): boolean;
+  /** Returns the absolute path to the .git directory for the current repo. */
+  getGitDir(): string;
+  /** Returns the currently checked-out branch name, or null if detached HEAD. */
+  getCurrentBranch(): string | null;
+  /** Returns true if a branch with the given name exists locally. */
+  branchExists(name: string): boolean;
+  /** Creates a new branch at the current HEAD and checks it out. */
+  createAndCheckoutBranch(name: string): void;
+  /** Sets a git config value. Throws on failure. */
+  setConfig(key: string, value: string): void;
+  /** Fetches from origin. Throws on failure. */
+  fetchOrigin(): void;
+  /** Returns the SHA for a given ref (branch name or remote ref like "origin/main"). Returns null if the ref is unknown. */
+  revParse(ref: string): string | null;
+  /** Returns the count of commits reachable from `to` but not from `from`. Returns 0 if either ref is unknown. */
+  countCommitsAhead(from: string, to: string): number;
+}