@litterthanlit/hypher-cli 0.1.0

package/vendor/hypher-git.mjs

@@ -0,0 +1,429 @@
+/**
+ * Hypher git helpers. Node built-ins only, synchronous, read-only against the
+ * real repository. Git failures return null or empty values; nothing throws.
+ *
+ * Canonical source: packages/hypher-git/index.mjs.
+ * Vendored copy: extensions/cursor/scripts/vendor/hypher-git.mjs
+ * (refresh with `node script/sync-hypher-git.mjs`; do not edit the copy).
+ */
+import { execFileSync } from "node:child_process";
+import { copyFileSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const GIT_TIMEOUT_MS = 10_000;
+export const TREE_TIMEOUT_MS = 60_000;
+
+/**
+ * Run git and return stdout (trimmed unless `trim` is false), or null when git fails or times out.
+ * @param {string | undefined} cwd
+ * @param {string[]} args
+ * @param {{ env?: Record<string, string>, timeoutMs?: number, trim?: boolean }} [options]
+ * @returns {string | null}
+ */
+export function git(cwd, args, { env, timeoutMs = GIT_TIMEOUT_MS, trim = true } = {}) {
+  try {
+    const out = execFileSync("git", args, {
+      encoding: "utf8",
+      timeout: timeoutMs,
+      stdio: ["ignore", "pipe", "ignore"],
+      ...(cwd ? { cwd } : {}),
+      ...(env ? { env: { ...process.env, ...env } } : {}),
+    });
+    return trim ? out.trim() : out;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `owner/repo` from a GitHub remote URL or `owner/repo`, else null.
+ * Mirrors hypher-web/shared/githubRepo.ts exactly (a parity test enforces it).
+ * @param {string | undefined | null} input
+ * @returns {string | null}
+ */
+export function normalizeGitHubRepo(input) {
+  const raw = (input ?? "").trim();
+  if (!raw) return null;
+
+  let value = raw.replace(/\.git$/i, "");
+  const sshMatch = value.match(/^git@github\.com:(.+)$/i);
+  if (sshMatch?.[1]) {
+    value = sshMatch[1];
+  } else if (/github\.com/i.test(value)) {
+    try {
+      const url = new URL(value.startsWith("http") ? value : `https://${value.replace(/^git\+/, "")}`);
+      const parts = url.pathname.split("/").filter(Boolean);
+      if (parts.length >= 2) {
+        value = `${parts[0]}/${parts[1]}`;
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  value = value.replace(/^\/+/, "").replace(/\.git$/i, "");
+  if (!/^[\w.-]+\/[\w.-]+$/.test(value)) return null;
+  return value;
+}
+
+/**
+ * URL of `origin`, else of the first remote, else null.
+ * @param {string | undefined} cwd
+ * @param {{ timeoutMs?: number }} [options]
+ * @returns {string | null}
+ */
+export function remoteUrl(cwd, { timeoutMs } = {}) {
+  const origin = git(cwd, ["remote", "get-url", "origin"], { timeoutMs });
+  if (origin) return origin;
+  const names = (git(cwd, ["remote"], { timeoutMs }) ?? "")
+    .split("\n").map((line) => line.trim()).filter(Boolean);
+  if (names.length === 0) return null;
+  const name = names.includes("origin") ? "origin" : names[0];
+  return git(cwd, ["remote", "get-url", name], { timeoutMs }) || null;
+}
+
+/**
+ * @typedef {object} RepoIdentity
+ * @property {string | null} root Work tree top level.
+ * @property {string | null} remote Origin URL, else first remote.
+ * @property {string | null} repository `owner/repo` for a GitHub remote.
+ * @property {string | null} branch Current branch (also on an unborn branch); "HEAD" when detached.
+ * @property {string | null} commit HEAD commit.
+ * @property {boolean} dirty
+ * @property {string[]} changedFiles `git status --porcelain` lines.
+ */
+
+/**
+ * Identity of the repository containing cwd. Outside git every field is null.
+ * @param {string} [cwd]
+ * @param {{ timeoutMs?: number }} [options]
+ * @returns {RepoIdentity}
+ */
+export function repoIdentity(cwd, { timeoutMs } = {}) {
+  const opts = { timeoutMs };
+  const root = git(cwd, ["rev-parse", "--show-toplevel"], opts) || null;
+  const remote = remoteUrl(cwd, opts);
+  const commit = git(cwd, ["rev-parse", "HEAD"], opts) || null;
+  const ref = git(cwd, ["symbolic-ref", "-q", "HEAD"], opts);
+  const branch = ref ? ref.replace(/^refs\/heads\//, "") : commit ? "HEAD" : null;
+  const status = git(cwd, ["status", "--porcelain"], { ...opts, trim: false });
+  const changedFiles = (status ?? "").split("\n").map((line) => line.trimEnd()).filter(Boolean);
+  return {
+    root,
+    remote,
+    repository: normalizeGitHubRepo(remote),
+    branch,
+    commit,
+    dirty: changedFiles.length > 0,
+    changedFiles,
+  };
+}
+
+/**
+ * Tree hash of the working tree (tracked edits plus untracked, non-ignored files),
+ * built in a throwaway index so the real index is never touched. Null on failure.
+ *
+ * The throwaway index starts as a copy of the real one, and `read-tree -m HEAD`
+ * resets it to HEAD while keeping the cached stat data of unchanged entries, so
+ * `add -A` rehashes only files that changed. The result is the same tree as
+ * `read-tree HEAD` in an empty index (HANDOFF_TREE_FINGERPRINT_COMMAND), which
+ * `worktreeTreeHashCold` keeps for the parity test.
+ * @param {string} [cwd]
+ * @returns {string | null}
+ */
+export function worktreeTreeHash(cwd) {
+  return treeHashInThrowawayIndex(cwd, { seed: true });
+}
+
+/** The original method: an empty throwaway index, every file rehashed. */
+export function worktreeTreeHashCold(cwd) {
+  return treeHashInThrowawayIndex(cwd, { seed: false });
+}
+
+function treeHashInThrowawayIndex(cwd, { seed }) {
+  const root = git(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!root) return null;
+  let dir;
+  try {
+    dir = mkdtempSync(path.join(os.tmpdir(), "hypher-index-"));
+    const index = path.join(dir, "index");
+    const opts = { env: { GIT_INDEX_FILE: index }, timeoutMs: TREE_TIMEOUT_MS };
+    let seeded = false;
+    if (seed) {
+      const real = git(root, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
+      try {
+        if (real) {
+          copyFileSync(real, index);
+          // Keep the real index's timestamp. Git trusts a cached entry only when the
+          // entry is older than the index file itself; a fresh mtime on the copy
+          // would make a same-size edit made in that same second look unchanged.
+          const { atime, mtime } = statSync(real);
+          utimesSync(index, atime, mtime);
+          seeded = git(root, ["read-tree", "-m", "HEAD"], opts) !== null;
+        }
+      } catch {
+        seeded = false;
+      }
+      if (!seeded) rmSync(index, { force: true });
+    }
+    if (!seeded && git(root, ["read-tree", "HEAD"], opts) === null) return null;
+    if (git(root, ["add", "-A"], opts) === null) return null;
+    const tree = git(root, ["write-tree"], opts);
+    return tree && /^[0-9a-f]{40,64}$/.test(tree) ? tree : null;
+  } catch {
+    return null;
+  } finally {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const HANDOFF_GITHUB_REMOTE = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?\/?$/;
+
+/**
+ * @typedef {object} HandoffRepoSnapshot
+ * @property {string} [repository]
+ * @property {string} branch
+ * @property {string} commit
+ * @property {boolean} dirty
+ * @property {string} [worktreePath]
+ * @property {string} [dirtyFingerprint] `tree:<sha>` when dirty.
+ */
+
+/**
+ * Repository snapshot for a structured handoff (`currentRepo` / `proposal.repo`).
+ * Reads only `origin`. Null outside a checkout with a commit.
+ * @param {string} [cwd]
+ * @returns {HandoffRepoSnapshot | null}
+ */
+export function handoffRepoSnapshot(cwd) {
+  const remote = git(cwd, ["config", "--get", "remote.origin.url"]);
+  const repository = remote?.match(HANDOFF_GITHUB_REMOTE)?.[1] ?? null;
+  const worktreePath = git(cwd, ["rev-parse", "--show-toplevel"]);
+  const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const commit = git(cwd, ["rev-parse", "HEAD"]);
+  const status = git(cwd, ["status", "--porcelain"]);
+  if (!branch || !commit) return null;
+  const dirty = Boolean(status);
+  const tree = dirty ? worktreeTreeHash(cwd) : null;
+  return {
+    ...(repository ? { repository } : {}),
+    branch,
+    commit,
+    dirty,
+    ...(worktreePath ? { worktreePath } : {}),
+    ...(tree ? { dirtyFingerprint: `tree:${tree}` } : {}),
+  };
+}
+
+function commitSha(cwd, rev) {
+  if (typeof rev !== "string" || !rev.trim() || rev.startsWith("-")) return null;
+  return git(cwd, ["rev-parse", "--verify", "-q", `${rev.trim()}^{commit}`]) || null;
+}
+
+/**
+ * Whether commit a is an ancestor of (or equal to) b. Null when unknown.
+ * @param {string | undefined} cwd
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean | null}
+ */
+export function isAncestor(cwd, a, b) {
+  const from = commitSha(cwd, a);
+  const to = commitSha(cwd, b);
+  if (!from || !to) return null;
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", from, to], {
+      timeout: GIT_TIMEOUT_MS,
+      stdio: "ignore",
+      ...(cwd ? { cwd } : {}),
+    });
+    return true;
+  } catch (error) {
+    return error?.status === 1 ? false : null;
+  }
+}
+
+/**
+ * Number of commits reachable from `to` but not from `from` (`from..to`). Null when unknown.
+ * @param {string | undefined} cwd
+ * @param {string} from
+ * @param {string} to
+ * @returns {number | null}
+ */
+export function commitsBetween(cwd, from, to) {
+  const a = commitSha(cwd, from);
+  const b = commitSha(cwd, to);
+  if (!a || !b) return null;
+  const count = Number(git(cwd, ["rev-list", "--count", `${a}..${b}`]) ?? NaN);
+  return Number.isInteger(count) ? count : null;
+}
+
+/**
+ * @typedef {"same" | "ahead" | "behind" | "diverged" | "unknown"} CommitRelationKind
+ * @typedef {{ relation: CommitRelationKind, ahead: number | null, behind: number | null }} CommitRelation
+ */
+
+/**
+ * How `current` relates to `saved`: ahead = commits only in current, behind = commits only in saved.
+ * @param {string | undefined} cwd
+ * @param {string} saved
+ * @param {string} current
+ * @returns {CommitRelation}
+ */
+export function commitRelation(cwd, saved, current) {
+  const unknown = { relation: /** @type {const} */ ("unknown"), ahead: null, behind: null };
+  const a = commitSha(cwd, saved);
+  const b = commitSha(cwd, current);
+  if (!a || !b) return unknown;
+  if (a === b) return { relation: "same", ahead: 0, behind: 0 };
+  const counts = git(cwd, ["rev-list", "--left-right", "--count", `${a}...${b}`])?.split(/\s+/).map(Number);
+  if (!counts || counts.length !== 2 || !counts.every(Number.isInteger)) return unknown;
+  const [behind, ahead] = counts;
+  const relation = ahead && behind ? "diverged" : ahead ? "ahead" : behind ? "behind" : "same";
+  return { relation, ahead, behind };
+}
+
+/** Tree of a commit, or null. */
+export function commitTree(cwd, rev) {
+  const sha = commitSha(cwd, rev);
+  return sha ? git(cwd, ["rev-parse", `${sha}^{tree}`]) || null : null;
+}
+
+/** True when the object exists in this repository. */
+export function hasObject(cwd, sha) {
+  return typeof sha === "string" && /^[0-9a-f]{40,64}$/.test(sha) && git(cwd, ["cat-file", "-e", sha]) !== null;
+}
+
+/**
+ * Paths that differ between two trees, or null when either tree is missing.
+ * @returns {string[] | null}
+ */
+export function changedPathsBetweenTrees(cwd, fromTree, toTree) {
+  if (!hasObject(cwd, fromTree) || !hasObject(cwd, toTree)) return null;
+  if (fromTree === toTree) return [];
+  const out = git(cwd, ["diff-tree", "-r", "--no-renames", "--name-only", fromTree, toTree]);
+  return out === null ? null : out.split("\n").filter(Boolean);
+}
+
+/** A ref-safe name for a branch: readable, plus a short hash so two branches never collide. */
+export function hypherRefBranch(branch) {
+  const text = String(branch ?? "HEAD");
+  const readable = text.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "branch";
+  let hash = 0;
+  for (const char of text) hash = (Math.imul(hash, 31) + char.codePointAt(0)) >>> 0;
+  return `${readable}-${hash.toString(16).padStart(8, "0")}`;
+}
+
+const HYPHER_REF_IDENTITY = {
+  GIT_AUTHOR_NAME: "Hypher",
+  GIT_AUTHOR_EMAIL: "hypher@localhost",
+  GIT_COMMITTER_NAME: "Hypher",
+  GIT_COMMITTER_EMAIL: "hypher@localhost",
+};
+
+/**
+ * Keep a handoff tree reachable under refs/hypher/<branch>/<tree>, so "edited
+ * since" can name files later. The tree holds untracked files, which can include
+ * secrets, so only the latest ref per branch is kept, the rest are pruned, and
+ * refs/hypher is never pushed. Returns the ref, or null.
+ * @param {string} cwd
+ * @param {{ branch: string, tree: string, commit?: string }} handoff
+ */
+export function keepHandoffTree(cwd, { branch, tree, commit }) {
+  if (!hasObject(cwd, tree)) return null;
+  const prefix = `refs/hypher/${hypherRefBranch(branch)}/`;
+  const ref = `${prefix}${tree.slice(0, 12)}`;
+  const parent = commit ? commitSha(cwd, commit) : null;
+  const wrapped = git(cwd, ["commit-tree", tree, ...(parent ? ["-p", parent] : []), "-m", "Hypher handoff tree (local only; never push refs/hypher)"],
+    { env: HYPHER_REF_IDENTITY });
+  if (!wrapped || git(cwd, ["update-ref", ref, wrapped]) === null) return null;
+  pruneHypherRefs(cwd, { keep: ref, prefix });
+  return ref;
+}
+
+/** Delete refs/hypher refs under `prefix` except `keep`. Returns the deleted refs. */
+export function pruneHypherRefs(cwd, { keep, prefix = "refs/hypher/" }) {
+  const refs = (git(cwd, ["for-each-ref", "--format=%(refname)", prefix]) ?? "").split("\n").filter(Boolean);
+  const deleted = [];
+  for (const ref of refs) {
+    if (ref === keep) continue;
+    if (git(cwd, ["update-ref", "-d", ref]) !== null) deleted.push(ref);
+  }
+  return deleted;
+}
+
+/**
+ * Remotes whose configuration would push refs/hypher (a mirror, or a push
+ * refspec that covers it). Reads config only; no network.
+ * @returns {string[]}
+ */
+export function remotesExposingHypherRefs(cwd) {
+  const names = (git(cwd, ["remote"]) ?? "").split("\n").map((name) => name.trim()).filter(Boolean);
+  const exposed = [];
+  for (const name of names) {
+    const mirror = git(cwd, ["config", "--bool", `remote.${name}.mirror`]) === "true";
+    const pushes = (git(cwd, ["config", "--get-all", `remote.${name}.push`]) ?? "").split("\n").filter(Boolean);
+    const covers = pushes.some((spec) => /^\+?(refs\/\*|refs\/hypher\/|\*)/.test(spec.replace(/:.*$/, "")) || spec === ":");
+    if (mirror || covers) exposed.push(name);
+  }
+  return exposed;
+}
+
+/**
+ * @typedef {"identical" | "committed-since" | "ahead" | "edited-since" | "behind" | "diverged" | "wrong-repository"} VerdictKind
+ * @typedef {object} TruthVerdict
+ * @property {VerdictKind} kind
+ * @property {boolean} stop Only behind, diverged, and wrong-repository stop the agent.
+ * @property {number} [ahead]
+ * @property {number} [behind]
+ * @property {string[]} [files] Paths changed since the handoff tree.
+ * @property {boolean} [filesUnavailable] The handoff tree is not on this machine.
+ * @property {boolean} [commitMissing] The handoff commit is not in this clone.
+ * @property {string} [branchNote] The current branch differs from the handoff's.
+ * @property {{ repository: string | null, branch: string | null, commit: string | null, tree: string | null }} current
+ */
+
+/**
+ * Compare the working tree with a handoff, locally, with git.
+ * @param {string} cwd
+ * @param {{ repository?: string, branch: string, commit: string, dirty?: boolean, dirtyFingerprint?: string }} saved
+ * @returns {TruthVerdict}
+ */
+export function truthCheck(cwd, saved) {
+  const repository = normalizeGitHubRepo(remoteUrl(cwd));
+  const ref = git(cwd, ["symbolic-ref", "-q", "HEAD"]);
+  const commit = git(cwd, ["rev-parse", "HEAD"]) || null;
+  const branch = ref ? ref.replace(/^refs\/heads\//, "") : commit ? "HEAD" : null;
+  const tree = worktreeTreeHash(cwd);
+  const current = { repository, branch, commit, tree };
+  const branchNote = saved.branch && branch && saved.branch !== branch ? `on branch ${branch}; the handoff was on ${saved.branch}` : undefined;
+  const base = { current, ...(branchNote ? { branchNote } : {}) };
+
+  const savedRepo = normalizeGitHubRepo(saved.repository ?? "");
+  if (!repository || !savedRepo || savedRepo.toLowerCase() !== repository.toLowerCase()) {
+    return { kind: "wrong-repository", stop: true, ...base };
+  }
+  const fingerprint = typeof saved.dirtyFingerprint === "string" && saved.dirtyFingerprint.startsWith("tree:")
+    ? saved.dirtyFingerprint.slice(5) : null;
+  // A dirty handoff without a fingerprint cannot say which edits it had.
+  const savedTree = fingerprint ?? (saved.dirty ? null : commitTree(cwd, saved.commit));
+  const relation = commitRelation(cwd, saved.commit, commit ?? "");
+  if (relation.relation === "unknown") {
+    return { kind: "behind", stop: true, behind: 0, commitMissing: true, ...base };
+  }
+  if (relation.relation === "behind") return { kind: "behind", stop: true, behind: relation.behind ?? 0, ...base };
+  if (relation.relation === "diverged") {
+    return { kind: "diverged", stop: true, ahead: relation.ahead ?? 0, behind: relation.behind ?? 0, ...base };
+  }
+  const files = savedTree && tree ? changedPathsBetweenTrees(cwd, savedTree, tree) : null;
+  const detail = files === null ? { filesUnavailable: true } : { files };
+  if (relation.relation === "same") {
+    if (savedTree && tree && savedTree === tree) return { kind: "identical", stop: false, ...base };
+    return { kind: "edited-since", stop: false, ...detail, ...base };
+  }
+  if (savedTree && tree && savedTree === tree) {
+    return { kind: "committed-since", stop: false, ahead: relation.ahead ?? 0, ...base };
+  }
+  return { kind: "ahead", stop: false, ahead: relation.ahead ?? 0, ...detail, ...base };
+}

package/vendor/secretScan.mjs

@@ -0,0 +1,47 @@
+// Generated from hypher-web/shared/secretScan.ts by script/sync-hypher-shared.mjs. Do not edit.
+/**
+ * Common secret shapes, refused in agent-written handoff text. The CLI scans
+ * before upload and the server scans again on every structured save, because
+ * saved text reaches every later session. The match itself is never echoed.
+ */
+export const SECRET_SHAPES = [
+    { name: "a Hypher API key (hyp_…)", pattern: /\bhyp_[A-Za-z0-9]{16,}/ },
+    { name: "an API secret key (sk-…)", pattern: /\bsk-(?:[A-Za-z]+-)?[A-Za-z0-9_-]{16,}/ },
+    { name: "a GitHub token (ghp_…)", pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}/ },
+    { name: "an AWS access key", pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+    { name: "a private key (PEM)", pattern: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/ },
+];
+/** The first secret shape in text, or null. */
+export function findSecret(text) {
+    for (const shape of SECRET_SHAPES) {
+        if (shape.pattern.test(text))
+            return shape;
+    }
+    return null;
+}
+/**
+ * Walk any JSON-like value and report the first string that holds a secret,
+ * with its field path (for example "decisions[1].reason").
+ */
+export function findSecretInValue(value, field = "text") {
+    if (typeof value === "string") {
+        const shape = findSecret(value);
+        return shape ? { field, shape: shape.name } : null;
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const found = findSecretInValue(value[index], `${field}[${index}]`);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, item] of Object.entries(value)) {
+            const found = findSecretInValue(item, field === "text" ? key : `${field}.${key}`);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}