@logicseek/hello-cc 0.1.4 → 0.1.6

package/lib/guidance.mjs

@@ -53,8 +53,16 @@ Before mutating work:
   explicitly; do not create or claim hidden extra tasks.
 
 Before editing or mutating shared resources:
-- Acquire an advisory lock for the file, directory, module, or shared resource.
-- If another live peer holds the lock, message that peer instead of editing.
+- Acquire an advisory lock for the file, directory, module scope, or shared
+  resource.
+- Locks are coordination signals, not task ownership and not read barriers.
+  A broad lock such as \`--resource bin/hcc.mjs\` protects the whole file, while
+  scoped locks such as \`--resource bin/hcc.mjs --scope db-schema\` and
+  \`--scope web-ui\` can be held by different peers at the same time.
+- If another live peer holds a conflicting lock, message that peer before
+  editing. When the work is in separate regions of the same file, agree on
+  narrower scoped locks and wait for all related scopes to hand off or release
+  before final tests, formatting, staging, or commit.
 - Acquire locks only before writes or shared-resource mutation, including file
   edits, formatting, staging/committing through \`.git/index\`, intentional DB
   data/schema changes, starting/stopping/restarting shared runtimes, or taking

package/lib/handoff.mjs

@@ -0,0 +1,26 @@
+import { runGit } from './runtime/project-context.mjs';
+
+export function normalizeListText(value, fallback = []) {
+  if (value === undefined || value === null || value === '') return JSON.stringify(fallback);
+  const text = String(value);
+  try {
+    JSON.parse(text);
+    return text;
+  } catch {
+    return JSON.stringify(text.split(',').map((item) => item.trim()).filter(Boolean));
+  }
+}
+
+export function changedFiles(cwd) {
+  const unstaged = runGit(['diff', '--name-only'], cwd);
+  const staged = runGit(['diff', '--cached', '--name-only'], cwd);
+  const files = new Set();
+  for (const block of [unstaged, staged]) {
+    if (!block) continue;
+    for (const line of block.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed) files.add(trimmed);
+    }
+  }
+  return [...files].sort();
+}

package/lib/help.mjs

@@ -0,0 +1,3 @@
+export {
+  createHelpFunctions
+} from './ui/help.mjs';

package/lib/integrations/hooks.mjs

@@ -0,0 +1,171 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonSafe, writeJsonSafe } from '../shared/json-file.mjs';
+
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const CODEX_HOOKS_PATH = path.join(os.homedir(), '.codex', 'hooks.json');
+
+/**
+ * Hook events we install handlers for.
+ * - SessionStart     : Inject initial coordination context
+ * - UserPromptSubmit : Inject fresh coordination context before the model answers
+ * - Stop             : Claude goes idle after a turn -> deliver inbox messages
+ * - PostToolUse      : After every tool call -> heartbeat + inbox check
+ * - PreToolUse       : Before every tool call -> register peer if not yet registered
+ */
+const CLAUDE_HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse', 'PreToolUse'];
+const CODEX_HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop'];
+
+/**
+ * Install (or update) hello-cc hooks in ~/.claude/settings.json.
+ * Non-destructive: only adds hcc entries, never removes existing ones.
+ * Returns the settings file path.
+ */
+export function installClaudeHooks(hccBin) {
+  const settings = readJsonSafe(CLAUDE_SETTINGS_PATH) || {};
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const hookCmd = `${hccBin} hook`;
+
+  for (const event of CLAUDE_HOOK_EVENTS) {
+    settings.hooks[event] = mergeHookEntry(
+      settings.hooks[event],
+      `${hookCmd} ${event.toLowerCase()}`
+    );
+  }
+
+  writeJsonSafe(CLAUDE_SETTINGS_PATH, settings);
+  return CLAUDE_SETTINGS_PATH;
+}
+
+/**
+ * Remove hello-cc hook entries from ~/.claude/settings.json.
+ */
+export function uninstallClaudeHooks() {
+  const settings = readJsonSafe(CLAUDE_SETTINGS_PATH);
+  if (!settings?.hooks) return false;
+
+  for (const event of Object.keys(settings.hooks)) {
+    if (!Array.isArray(settings.hooks[event])) continue;
+    settings.hooks[event] = settings.hooks[event].filter(entry => {
+      if (!Array.isArray(entry?.hooks)) return true;
+      return !entry.hooks.some(h => isHccHookCmd(h?.command));
+    });
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+
+  writeJsonSafe(CLAUDE_SETTINGS_PATH, settings);
+  return true;
+}
+
+/**
+ * Returns true if hello-cc hooks are present in ~/.claude/settings.json.
+ */
+export function verifyClaudeHooks() {
+  const settings = readJsonSafe(CLAUDE_SETTINGS_PATH);
+  if (!settings?.hooks) return false;
+  return CLAUDE_HOOK_EVENTS.every(event => hasHookEntry(settings.hooks[event]));
+}
+
+/**
+ * Install hello-cc hooks in ~/.codex/hooks.json.
+ *
+ * Codex hooks.json format:
+ *   { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [...] }], "Stop": [...] } }
+ */
+export function installCodexHooks(hccBin) {
+  const hooks = readJsonSafe(CODEX_HOOKS_PATH) || {};
+
+  if (!hooks.hooks) hooks.hooks = {};
+
+  const hookCmd = `${hccBin} hook`;
+
+  // SessionStart: inject initial coordination context on startup/resume.
+  hooks.hooks.SessionStart = mergeCodexHookEntry(
+    hooks.hooks.SessionStart,
+    `${hookCmd} sessionstart`,
+    null
+  );
+  // UserPromptSubmit: inject fresh coordination context before each model turn.
+  hooks.hooks.UserPromptSubmit = mergeCodexHookEntry(
+    hooks.hooks.UserPromptSubmit,
+    `${hookCmd} userpromptsubmit`,
+    null
+  );
+  // PreToolUse: fires before every Bash tool call - heartbeat + peer registration
+  hooks.hooks.PreToolUse = mergeCodexHookEntry(
+    hooks.hooks.PreToolUse,
+    `${hookCmd} pretooluse`,
+    'Bash'
+  );
+  // Stop: fires when Codex goes idle - deliver inbox messages
+  hooks.hooks.Stop = mergeCodexHookEntry(
+    hooks.hooks.Stop,
+    `${hookCmd} stop`,
+    null
+  );
+
+  writeJsonSafe(CODEX_HOOKS_PATH, hooks);
+  return CODEX_HOOKS_PATH;
+}
+
+export function uninstallCodexHooks() {
+  const hooks = readJsonSafe(CODEX_HOOKS_PATH);
+  if (!hooks?.hooks) return false;
+
+  for (const event of Object.keys(hooks.hooks)) {
+    if (!Array.isArray(hooks.hooks[event])) continue;
+    hooks.hooks[event] = hooks.hooks[event].filter(entry => {
+      if (!Array.isArray(entry?.hooks)) return true;
+      return !entry.hooks.some(h => isHccHookCmd(h?.command));
+    });
+    if (hooks.hooks[event].length === 0) delete hooks.hooks[event];
+  }
+
+  writeJsonSafe(CODEX_HOOKS_PATH, hooks);
+  return true;
+}
+
+export function verifyCodexHooks() {
+  const hooks = readJsonSafe(CODEX_HOOKS_PATH);
+  if (!hooks?.hooks) return false;
+  return CODEX_HOOK_EVENTS.every(event => hasHookEntry(hooks.hooks[event]));
+}
+
+function mergeHookEntry(existing, command) {
+  const entries = Array.isArray(existing) ? [...existing] : [];
+  const alreadyInstalled = entries.some(
+    e => Array.isArray(e?.hooks) && e.hooks.some(h => isHccHookCmd(h?.command))
+  );
+  if (alreadyInstalled) return entries;
+  entries.push({ hooks: [{ type: 'command', command }] });
+  return entries;
+}
+
+function hasHookEntry(entries) {
+  if (!Array.isArray(entries)) return false;
+  return entries.some(e =>
+    Array.isArray(e?.hooks) && e.hooks.some(h => isHccHookCmd(h?.command))
+  );
+}
+
+function isHccHookCmd(cmd) {
+  if (typeof cmd !== 'string') return false;
+  return /\bhcc\b.*\bhook\b/.test(cmd) || /hello-cc.*hook/.test(cmd);
+}
+
+function mergeCodexHookEntry(existing, command, matcher) {
+  const entries = Array.isArray(existing) ? [...existing] : [];
+  const alreadyInstalled = entries.some(
+    e => Array.isArray(e?.hooks) && e.hooks.some(h => isHccHookCmd(h?.command))
+  );
+  if (alreadyInstalled) return entries;
+
+  const entry = {
+    hooks: [{ type: 'command', command }],
+  };
+  if (matcher) entry.matcher = matcher;
+  entries.push(entry);
+  return entries;
+}

package/lib/integrations/peers/identity.mjs

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import {
+  autoPeerBasis as coreAutoPeerBasis,
+  autoPeerId as coreAutoPeerId,
+  autoPeerKind as coreAutoPeerKind,
+  autoPeerProviderSession as coreAutoPeerProviderSession,
+  autoPeerResumeId as coreAutoPeerResumeId,
+  autoPeerSessionId as coreAutoPeerSessionId,
+  currentPeer as coreCurrentPeer,
+  resolveCurrentPeer as coreResolveCurrentPeer,
+  sanitizePeerPart,
+  shortHash
+} from '../../core/peers/identity.mjs';
+
+export { sanitizePeerPart, shortHash } from '../../core/peers/identity.mjs';
+
+export function currentTtyName() {
+  if (process.env.TTY) return process.env.TTY;
+  const result = spawnSync('tty', [], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  });
+  if (result.status !== 0) return '';
+  const tty = result.stdout.trim();
+  return tty && tty !== 'not a tty' ? tty : '';
+}
+
+let ancestorCliInfoCache = undefined;
+
+function readProcCmdline(pid) {
+  if (process.platform !== 'linux' || !pid) return [];
+  try {
+    return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function readProcEnv(pid) {
+  const env = {};
+  if (process.platform !== 'linux' || !pid) return env;
+  try {
+    for (const entry of fs.readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0')) {
+      const eq = entry.indexOf('=');
+      if (eq > 0) env[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+  } catch {}
+  return env;
+}
+
+function readProcParentPid(pid) {
+  if (process.platform !== 'linux' || !pid) return null;
+  try {
+    const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+    const match = status.match(/^PPid:\s+(\d+)/m);
+    return match ? Number.parseInt(match[1], 10) : null;
+  } catch {
+    return null;
+  }
+}
+
+function argsLookLikeCli(args, kind) {
+  return args.some((arg) => {
+    const text = String(arg || '').toLowerCase();
+    const base = path.basename(text);
+    if (kind === 'codex') return base === 'codex' || text.includes('/codex') || text.includes('@openai/codex');
+    if (kind === 'claude') return base === 'claude' || base === 'claude-code' || text.includes('/claude') || text.includes('@anthropic-ai/claude-code');
+    return false;
+  });
+}
+
+function detectCliKindFromProcess(args, env) {
+  if (env.CLAUDE_CODE_SESSION_ID || env.CLAUDECODE === '1' || argsLookLikeCli(args, 'claude')) return 'claude';
+  if (
+    env.CODEX_SESSION_ID ||
+    env.CODEX_THREAD_ID ||
+    env.CODEX_MANAGED_BY_NPM === '1' ||
+    env.CODEX_MANAGED_BY_BUN === '1' ||
+    argsLookLikeCli(args, 'codex')
+  ) return 'codex';
+  return null;
+}
+
+export function readAncestorCliInfo() {
+  if (ancestorCliInfoCache !== undefined) return ancestorCliInfoCache;
+  if (process.platform !== 'linux') {
+    ancestorCliInfoCache = null;
+    return ancestorCliInfoCache;
+  }
+
+  let pid = process.ppid;
+  const seen = new Set();
+  for (let depth = 0; pid && pid > 1 && depth < 12 && !seen.has(pid); depth += 1) {
+    seen.add(pid);
+    const args = readProcCmdline(pid);
+    const env = readProcEnv(pid);
+    const kind = detectCliKindFromProcess(args, env);
+    if (kind) {
+      ancestorCliInfoCache = { pid, kind, args, env };
+      return ancestorCliInfoCache;
+    }
+    pid = readProcParentPid(pid);
+  }
+
+  ancestorCliInfoCache = null;
+  return ancestorCliInfoCache;
+}
+
+export function resumeIdFromArgs(kind, args) {
+  if (!Array.isArray(args)) return null;
+  if (kind === 'claude') {
+    if (args.includes('--fork-session')) return null;
+    for (let i = 0; i < args.length; i += 1) {
+      const arg = args[i];
+      if ((arg === '--resume' || arg === '-r') && args[i + 1]) return args[i + 1];
+      if (arg.startsWith('--resume=')) return arg.slice('--resume='.length);
+    }
+  }
+  if (kind === 'codex') {
+    const idx = args.indexOf('resume');
+    if (idx >= 0) {
+      for (let i = idx + 1; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--last') return null;
+        if (arg.startsWith('-')) continue;
+        return arg;
+      }
+    }
+  }
+  return null;
+}
+
+function peerObservation(kind = null) {
+  const ancestor = readAncestorCliInfo();
+  const ancestorEnv = ancestor?.kind === kind ? ancestor.env || {} : {};
+  const sessionId = kind === 'claude'
+    ? (process.env.CLAUDE_CODE_SESSION_ID || ancestorEnv.CLAUDE_CODE_SESSION_ID || '')
+    : kind === 'codex'
+      ? (process.env.CODEX_SESSION_ID || process.env.CODEX_THREAD_ID || ancestorEnv.CODEX_SESSION_ID || ancestorEnv.CODEX_THREAD_ID || '')
+      : '';
+  const resumeId = ancestor?.kind === kind ? resumeIdFromArgs(kind, ancestor.args) : null;
+  return {
+    ancestor,
+    env: process.env,
+    ppid: process.ppid,
+    resumeId,
+    sessionId,
+    tmuxPane: process.env.TMUX_PANE || '',
+    tty: currentTtyName()
+  };
+}
+
+export function autoPeerProviderSession(kind) {
+  return coreAutoPeerProviderSession(kind, peerObservation(kind));
+}
+
+export function autoPeerSessionId(kind) {
+  return coreAutoPeerSessionId(kind, peerObservation(kind));
+}
+
+export function autoPeerResumeId(kind) {
+  return coreAutoPeerResumeId(kind, peerObservation(kind));
+}
+
+export function autoPeerKind(kindHint = 'shell') {
+  const ancestor = readAncestorCliInfo();
+  let kind = '';
+  if (process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDECODE === '1') kind = 'claude';
+  else if (
+    process.env.CODEX_SESSION_ID ||
+    process.env.CODEX_THREAD_ID ||
+    process.env.CODEX_MANAGED_BY_NPM === '1' ||
+    process.env.CODEX_MANAGED_BY_BUN === '1'
+  ) kind = 'codex';
+  else kind = ancestor?.kind || '';
+  return coreAutoPeerKind(kindHint, { kind });
+}
+
+export function autoPeerBasis(kind = null) {
+  return coreAutoPeerBasis(kind, peerObservation(kind));
+}
+
+export function autoPeerId(ctx, kindHint = 'shell') {
+  const kind = autoPeerKind(kindHint);
+  return coreAutoPeerId(ctx, kindHint, {
+    ...peerObservation(kind),
+    kind
+  });
+}
+
+export function resolveCurrentPeer(ctx, opts = {}, key = 'peer', kindHint = 'shell') {
+  const kind = autoPeerKind(kindHint);
+  return coreResolveCurrentPeer(ctx, opts, key, kindHint, {
+    ...peerObservation(kind),
+    kind
+  });
+}
+
+export function currentPeer(ctx, opts = {}, key = 'peer', kindHint = 'shell') {
+  const kind = autoPeerKind(kindHint);
+  return coreCurrentPeer(ctx, opts, key, kindHint, {
+    ...peerObservation(kind),
+    kind
+  });
+}

package/lib/integrations/peers/processes.mjs

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resumeIdFromArgs } from './identity.mjs';
+
+function readProcCmdline(pid) {
+  if (process.platform !== 'linux' || !pid) return [];
+  try {
+    return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function readProcEnv(pid) {
+  const env = {};
+  if (process.platform !== 'linux' || !pid) return env;
+  try {
+    for (const entry of fs.readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0')) {
+      const eq = entry.indexOf('=');
+      if (eq > 0) env[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+  } catch {}
+  return env;
+}
+
+function readProcParentPid(pid) {
+  if (process.platform !== 'linux' || !pid) return null;
+  try {
+    const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+    const match = status.match(/^PPid:\s+(\d+)/m);
+    return match ? Number.parseInt(match[1], 10) : null;
+  } catch {
+    return null;
+  }
+}
+
+function readProcChildren(pid) {
+  if (process.platform !== 'linux' || !pid) return [];
+  try {
+    return fs.readFileSync(`/proc/${pid}/task/${pid}/children`, 'utf8')
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((value) => Number.parseInt(value, 10))
+      .filter((value) => Number.isFinite(value) && value > 1);
+  } catch {
+    return [];
+  }
+}
+
+function argsLookLikeCli(args, kind) {
+  return args.some((arg) => {
+    const text = String(arg || '').toLowerCase();
+    const base = path.basename(text);
+    if (kind === 'codex') return base === 'codex' || text.includes('/codex') || text.includes('@openai/codex');
+    if (kind === 'claude') return base === 'claude' || base === 'claude-code' || text.includes('/claude') || text.includes('@anthropic-ai/claude-code');
+    return false;
+  });
+}
+
+function detectKind(args, env, kindHint = null) {
+  if (kindHint && argsLookLikeCli(args, kindHint)) return kindHint;
+  if (env.CLAUDE_CODE_SESSION_ID || env.CLAUDECODE === '1' || argsLookLikeCli(args, 'claude')) return 'claude';
+  if (
+    env.CODEX_SESSION_ID ||
+    env.CODEX_THREAD_ID ||
+    env.CODEX_MANAGED_BY_NPM === '1' ||
+    env.CODEX_MANAGED_BY_BUN === '1' ||
+    argsLookLikeCli(args, 'codex')
+  ) return 'codex';
+  return null;
+}
+
+function sessionFromEnv(kind, env) {
+  if (kind === 'claude') return env.CLAUDE_CODE_SESSION_ID || '';
+  if (kind === 'codex') return env.CODEX_SESSION_ID || env.CODEX_THREAD_ID || '';
+  return '';
+}
+
+export function inspectProviderProcess(pid, kindHint = null, opts = {}) {
+  if (process.platform !== 'linux' || !pid) return null;
+  const maxDepth = Number.isFinite(opts.maxDepth) ? opts.maxDepth : 8;
+  const queue = [{ pid: Number(pid), depth: 0 }];
+  const seen = new Set();
+
+  while (queue.length) {
+    const current = queue.shift();
+    const currentPid = current?.pid;
+    const depth = current?.depth || 0;
+    if (!currentPid || currentPid <= 1 || depth > maxDepth || seen.has(currentPid)) continue;
+    seen.add(currentPid);
+    const args = readProcCmdline(currentPid);
+    const env = readProcEnv(currentPid);
+    const kind = detectKind(args, env, kindHint);
+    if (kind) {
+      const envSession = sessionFromEnv(kind, env);
+      if (envSession) {
+        return {
+          pid: currentPid,
+          kind,
+          provider_session: envSession,
+          source: `process.env.${kind}`
+        };
+      }
+      const resumeId = resumeIdFromArgs(kind, args);
+      if (resumeId) {
+        return {
+          pid: currentPid,
+          kind,
+          provider_session: resumeId,
+          source: `process.argv.${kind}`
+        };
+      }
+    }
+    for (const childPid of readProcChildren(currentPid)) {
+      queue.push({ pid: childPid, depth: depth + 1 });
+    }
+  }
+
+  let currentPid = Number(pid);
+  seen.clear();
+
+  for (let depth = 0; currentPid && currentPid > 1 && depth <= maxDepth && !seen.has(currentPid); depth += 1) {
+    seen.add(currentPid);
+    const args = readProcCmdline(currentPid);
+    const env = readProcEnv(currentPid);
+    const kind = detectKind(args, env, kindHint);
+    if (kind) {
+      const envSession = sessionFromEnv(kind, env);
+      if (envSession) {
+        return {
+          pid: currentPid,
+          kind,
+          provider_session: envSession,
+          source: `process.env.${kind}`
+        };
+      }
+      const resumeId = resumeIdFromArgs(kind, args);
+      if (resumeId) {
+        return {
+          pid: currentPid,
+          kind,
+          provider_session: resumeId,
+          source: `process.argv.${kind}`
+        };
+      }
+    }
+    currentPid = readProcParentPid(currentPid);
+  }
+  return null;
+}