cognitive-core 0.1.0 → 0.2.0

package/references/sessionlog/src/hooks/git-hooks.ts

@@ -0,0 +1,165 @@
+/**
+ * Git Hooks
+ *
+ * Installation and management of git hooks (prepare-commit-msg,
+ * commit-msg, post-commit, pre-push) that integrate Sessionlog into the git workflow.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getGitDir } from '../git-operations.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const HOOK_MARKER = '# Sessionlog CLI hook';
+const HOOK_NAMES = ['prepare-commit-msg', 'commit-msg', 'post-commit', 'pre-push'] as const;
+
+export type GitHookName = (typeof HOOK_NAMES)[number];
+
+// ============================================================================
+// Git Hook Installation
+// ============================================================================
+
+/**
+ * Install git hooks for Sessionlog into a repository
+ */
+export async function installGitHooks(
+  repoPath: string,
+  sessionlogExecutable = 'sessionlog',
+): Promise<number> {
+  const gitDir = await getGitDir(repoPath);
+  const hooksDir = path.resolve(repoPath, gitDir, 'hooks');
+
+  await fs.promises.mkdir(hooksDir, { recursive: true });
+
+  let installed = 0;
+
+  for (const hookName of HOOK_NAMES) {
+    const hookPath = path.join(hooksDir, hookName);
+    const hookScript = generateHookScript(hookName, sessionlogExecutable);
+
+    // Read existing content if any
+    let existingContent = '';
+    try {
+      existingContent = await fs.promises.readFile(hookPath, 'utf-8');
+    } catch {
+      // File doesn't exist
+    }
+
+    // Check if Sessionlog hook already installed
+    if (existingContent.includes(HOOK_MARKER)) {
+      continue;
+    }
+
+    // Append or create
+    if (existingContent) {
+      // Append to existing hook
+      const newContent = existingContent.trimEnd() + '\n\n' + hookScript + '\n';
+      await fs.promises.writeFile(hookPath, newContent);
+    } else {
+      // Create new hook
+      await fs.promises.writeFile(hookPath, '#!/bin/sh\n\n' + hookScript + '\n');
+    }
+
+    // Make executable
+    await fs.promises.chmod(hookPath, 0o755);
+    installed++;
+  }
+
+  return installed;
+}
+
+/**
+ * Uninstall git hooks for Sessionlog from a repository
+ */
+export async function uninstallGitHooks(repoPath: string): Promise<void> {
+  const gitDir = await getGitDir(repoPath);
+  const hooksDir = path.resolve(repoPath, gitDir, 'hooks');
+
+  for (const hookName of HOOK_NAMES) {
+    const hookPath = path.join(hooksDir, hookName);
+
+    try {
+      const content = await fs.promises.readFile(hookPath, 'utf-8');
+
+      // Remove Sessionlog section
+      const lines = content.split('\n');
+      const filtered: string[] = [];
+      let inSessionlogSection = false;
+
+      for (const line of lines) {
+        if (line.includes(HOOK_MARKER)) {
+          inSessionlogSection = true;
+          continue;
+        }
+        if (inSessionlogSection && line.trim() === '') {
+          inSessionlogSection = false;
+          continue;
+        }
+        if (!inSessionlogSection) {
+          filtered.push(line);
+        }
+      }
+
+      const newContent = filtered.join('\n').trim();
+
+      if (newContent === '#!/bin/sh' || newContent === '') {
+        // Hook is now empty, remove it
+        await fs.promises.unlink(hookPath);
+      } else {
+        await fs.promises.writeFile(hookPath, newContent + '\n');
+      }
+    } catch {
+      // Hook doesn't exist
+    }
+  }
+}
+
+/**
+ * Check if git hooks are installed
+ */
+export async function areGitHooksInstalled(repoPath: string): Promise<boolean> {
+  const gitDir = await getGitDir(repoPath);
+  const hooksDir = path.resolve(repoPath, gitDir, 'hooks');
+
+  for (const hookName of HOOK_NAMES) {
+    const hookPath = path.join(hooksDir, hookName);
+    try {
+      const content = await fs.promises.readFile(hookPath, 'utf-8');
+      if (content.includes(HOOK_MARKER)) return true;
+    } catch {
+      // Hook doesn't exist
+    }
+  }
+
+  return false;
+}
+
+// ============================================================================
+// Hook Script Generation
+// ============================================================================
+
+function generateHookScript(hookName: GitHookName, executable: string): string {
+  switch (hookName) {
+    case 'prepare-commit-msg':
+      return [
+        HOOK_MARKER,
+        `${executable} hooks git prepare-commit-msg "$@" 2>/dev/null || true`,
+      ].join('\n');
+
+    case 'commit-msg':
+      return [
+        HOOK_MARKER,
+        '# Commit-msg hook: strip trailer if no user content (allows aborting empty commits)',
+        `${executable} hooks git commit-msg "$1" || exit 1`,
+      ].join('\n');
+
+    case 'post-commit':
+      return [HOOK_MARKER, `${executable} hooks git post-commit 2>/dev/null || true`].join('\n');
+
+    case 'pre-push':
+      return [HOOK_MARKER, `${executable} hooks git pre-push "$@" 2>/dev/null || true`].join('\n');
+  }
+}

package/references/sessionlog/src/hooks/lifecycle.ts

@@ -0,0 +1,391 @@
+/**
+ * Lifecycle Management
+ *
+ * Dispatches normalized agent events through the session state machine.
+ * This is the orchestration layer between agent hooks and checkpoint operations.
+ */
+
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import type { Event, SessionState } from '../types.js';
+import { EventType, addTokenUsage } from '../types.js';
+import type { SessionStore } from '../store/session-store.js';
+import type { CheckpointStore } from '../store/checkpoint-store.js';
+import type { Agent } from '../agent/types.js';
+import { hasTranscriptAnalyzer, hasTokenCalculator } from '../agent/types.js';
+import { getHead, getCurrentBranch, getUntrackedFiles, getGitAuthor } from '../git-operations.js';
+import { normalizeStoredPath } from '../utils/paths.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LifecycleConfig {
+  sessionStore: SessionStore;
+  checkpointStore: CheckpointStore;
+  cwd?: string;
+}
+
+export interface LifecycleHandler {
+  /** Dispatch an event through the lifecycle state machine */
+  dispatch(agent: Agent, event: Event): Promise<void>;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+export function createLifecycleHandler(config: LifecycleConfig): LifecycleHandler {
+  const { sessionStore, cwd } = config;
+
+  return {
+    async dispatch(agent: Agent, event: Event): Promise<void> {
+      switch (event.type) {
+        case EventType.SessionStart:
+          await handleSessionStart(agent, event);
+          break;
+        case EventType.TurnStart:
+          await handleTurnStart(agent, event);
+          break;
+        case EventType.TurnEnd:
+          await handleTurnEnd(agent, event);
+          break;
+        case EventType.SessionEnd:
+          await handleSessionEnd(agent, event);
+          break;
+        case EventType.Compaction:
+          await handleCompaction(agent, event);
+          break;
+        case EventType.SubagentStart:
+          await handleSubagentStart(agent, event);
+          break;
+        case EventType.SubagentEnd:
+          await handleSubagentEnd(agent, event);
+          break;
+        case EventType.TaskCreate:
+          await handleTaskCreate(agent, event);
+          break;
+        case EventType.TaskUpdate:
+          await handleTaskUpdate(agent, event);
+          break;
+        case EventType.PlanModeEnter:
+          await handlePlanModeEnter(agent, event);
+          break;
+        case EventType.PlanModeExit:
+          await handlePlanModeExit(agent, event);
+          break;
+        case EventType.SkillUse:
+          await handleSkillUse(agent, event);
+          break;
+      }
+    },
+  };
+
+  async function handleSessionStart(agent: Agent, event: Event): Promise<void> {
+    // Check if session already exists
+    const existing = await sessionStore.load(event.sessionID);
+    if (existing && existing.phase !== 'ended') {
+      // Session already active, update interaction time
+      existing.lastInteractionTime = new Date().toISOString();
+      await sessionStore.save(existing);
+      return;
+    }
+
+    // Create new session state
+    const head = await getHead(cwd);
+    const _branch = await getCurrentBranch(cwd);
+    const untrackedFiles = await getUntrackedFiles(cwd);
+
+    const state: SessionState = {
+      sessionID: event.sessionID,
+      baseCommit: head,
+      attributionBaseCommit: head,
+      startedAt: new Date().toISOString(),
+      phase: 'idle',
+      turnCheckpointIDs: [],
+      stepCount: 0,
+      checkpointTranscriptStart: 0,
+      untrackedFilesAtStart: untrackedFiles,
+      filesTouched: [],
+      agentType: agent.type,
+      transcriptPath: event.sessionRef,
+      worktreePath: cwd,
+    };
+
+    await sessionStore.save(state);
+  }
+
+  async function handleTurnStart(agent: Agent, event: Event): Promise<void> {
+    let state = await sessionStore.load(event.sessionID);
+
+    if (!state) {
+      // Auto-create session on first turn
+      await handleSessionStart(agent, {
+        ...event,
+        type: EventType.SessionStart,
+      });
+      state = await sessionStore.load(event.sessionID);
+      if (!state) return;
+    }
+
+    // Generate a new turn ID
+    state.turnID = crypto.randomUUID().slice(0, 8);
+    state.phase = 'active';
+    state.lastInteractionTime = new Date().toISOString();
+    state.transcriptPath = event.sessionRef;
+
+    if (event.prompt && !state.firstPrompt) {
+      state.firstPrompt = event.prompt.slice(0, 500);
+    }
+
+    // Capture pre-prompt transcript position
+    if (hasTranscriptAnalyzer(agent) && event.sessionRef) {
+      try {
+        state.checkpointTranscriptStart = await agent.getTranscriptPosition(event.sessionRef);
+        state.transcriptIdentifierAtStart = event.sessionRef;
+      } catch {
+        // Ignore transcript position errors
+      }
+    }
+
+    await sessionStore.save(state);
+  }
+
+  async function handleTurnEnd(agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    state.lastInteractionTime = new Date().toISOString();
+
+    // Extract modified files from transcript
+    if (hasTranscriptAnalyzer(agent) && state.transcriptPath) {
+      try {
+        const { files } = await agent.extractModifiedFilesFromOffset(
+          state.transcriptPath,
+          state.checkpointTranscriptStart,
+        );
+
+        // Merge new files into filesTouched
+        const fileSet = new Set(state.filesTouched);
+        for (const file of files) fileSet.add(file);
+        state.filesTouched = Array.from(fileSet);
+      } catch {
+        // Ignore extraction errors
+      }
+    }
+
+    // Create shadow branch checkpoint so prepareCommitMsg can detect overlap
+    if (state.filesTouched.length > 0) {
+      try {
+        const { name: authorName, email: authorEmail } = await getGitAuthor(cwd);
+        // Use flat name (no slashes) — mergeMetadataIntoTree can't handle nested paths
+        const metadataDir = `sessionlog-${state.sessionID}`;
+        const metadataDirAbs = path.resolve(cwd ?? '.', metadataDir);
+
+        const result = await config.checkpointStore.writeTemporary({
+          sessionID: state.sessionID,
+          baseCommit: state.baseCommit,
+          worktreeID: state.worktreeID,
+          modifiedFiles: state.filesTouched,
+          newFiles: [],
+          deletedFiles: [],
+          metadataDir,
+          metadataDirAbs,
+          commitMessage: `Checkpoint: ${state.filesTouched.length} file(s)\n\nSession: ${state.sessionID}`,
+          authorName,
+          authorEmail,
+          isFirstCheckpoint: state.stepCount === 0,
+        });
+
+        if (!result.skipped) {
+          state.stepCount++;
+        }
+      } catch (err) {
+        // Non-fatal: shadow branch creation failure shouldn't break lifecycle
+
+        if (process.env.SESSIONLOG_DEBUG) console.error('[sessionlog] shadow branch error:', err);
+      }
+    }
+
+    // Calculate token usage
+    if (hasTokenCalculator(agent) && state.transcriptPath) {
+      try {
+        const transcript = await agent.readTranscript(state.transcriptPath);
+        const usage = await agent.calculateTokenUsage(transcript, state.checkpointTranscriptStart);
+        state.tokenUsage = state.tokenUsage ? addTokenUsage(state.tokenUsage, usage) : usage;
+      } catch {
+        // Ignore token calculation errors
+      }
+    }
+
+    // Transition to idle
+    state.phase = 'idle';
+    await sessionStore.save(state);
+  }
+
+  async function handleSessionEnd(agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    state.phase = 'ended';
+    state.endedAt = new Date().toISOString();
+    state.lastInteractionTime = new Date().toISOString();
+
+    await sessionStore.save(state);
+  }
+
+  async function handleCompaction(agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    // Update transcript offset for next checkpoint
+    if (hasTranscriptAnalyzer(agent) && state.transcriptPath) {
+      try {
+        state.checkpointTranscriptStart = await agent.getTranscriptPosition(state.transcriptPath);
+      } catch {
+        // Ignore
+      }
+    }
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handleSubagentStart(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handleSubagentEnd(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handleTaskCreate(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    if (!state.tasks) state.tasks = {};
+
+    const taskID = event.taskID || event.toolUseID || '';
+    if (taskID) {
+      state.tasks[taskID] = {
+        id: taskID,
+        subject: event.taskSubject ?? '',
+        description: event.taskDescription,
+        status: 'pending',
+        activeForm: event.taskActiveForm,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+    }
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handleTaskUpdate(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    if (!state.tasks) state.tasks = {};
+
+    const taskID = event.taskID ?? '';
+    if (taskID) {
+      if (state.tasks[taskID]) {
+        if (event.taskStatus) state.tasks[taskID].status = event.taskStatus;
+        if (event.taskSubject) state.tasks[taskID].subject = event.taskSubject;
+        if (event.taskDescription) state.tasks[taskID].description = event.taskDescription;
+        state.tasks[taskID].updatedAt = new Date().toISOString();
+      } else {
+        // Task not previously tracked
+        state.tasks[taskID] = {
+          id: taskID,
+          subject: event.taskSubject ?? '',
+          description: event.taskDescription,
+          status: event.taskStatus ?? 'pending',
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        };
+      }
+    }
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handlePlanModeEnter(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    state.inPlanMode = true;
+    state.planModeEntries = (state.planModeEntries ?? 0) + 1;
+
+    // Push a new plan entry (will be completed on exit)
+    if (!state.planEntries) state.planEntries = [];
+    state.planEntries.push({
+      enteredAt: new Date().toISOString(),
+    });
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handlePlanModeExit(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    state.inPlanMode = false;
+
+    // Complete the last plan entry
+    const lastEntry = (state.planEntries ?? []).at(-1);
+    if (lastEntry && !lastEntry.exitedAt) {
+      lastEntry.exitedAt = new Date().toISOString();
+
+      if (event.planFilePath) {
+        lastEntry.filePath = cwd
+          ? normalizeStoredPath(event.planFilePath, cwd)
+          : event.planFilePath;
+        try {
+          // Always read from the original absolute path
+          const content = await readFile(event.planFilePath, 'utf-8');
+          lastEntry.content = content;
+        } catch {
+          // File may have been cleaned up already — store path only
+        }
+      }
+
+      if (event.planAllowedPrompts) {
+        lastEntry.allowedPrompts = event.planAllowedPrompts;
+      }
+    }
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+
+  async function handleSkillUse(_agent: Agent, event: Event): Promise<void> {
+    const state = await sessionStore.load(event.sessionID);
+    if (!state) return;
+
+    if (!state.skillsUsed) state.skillsUsed = [];
+
+    if (event.skillName) {
+      state.skillsUsed.push({
+        name: event.skillName,
+        args: event.skillArgs,
+        usedAt: new Date().toISOString(),
+      });
+    }
+
+    state.lastInteractionTime = new Date().toISOString();
+    await sessionStore.save(state);
+  }
+}