cognitive-core 0.1.2 → 0.2.1

package/references/sessionlog/src/commands/explain.ts

@@ -0,0 +1,261 @@
+/**
+ * Explain Command
+ *
+ * Provides human-readable context about sessions, commits, and checkpoints.
+ * This is the library implementation - consumers (CLI, IDE plugins) handle
+ * their own output formatting and pager support.
+ */
+
+import type { CheckpointID, CommittedMetadata, Summary, AgentType, TokenUsage } from '../types.js';
+import { CHECKPOINTS_BRANCH, checkpointIDPath } from '../types.js';
+import { git, catFile, lsTree } from '../git-operations.js';
+import { parseCheckpoint, parseAllSessions } from '../utils/trailers.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CheckpointDetail {
+  checkpointID: CheckpointID;
+  sessionID: string;
+  agent?: AgentType;
+  strategy: string;
+  createdAt: string;
+  branch?: string;
+  checkpointsCount: number;
+  filesTouched: string[];
+  tokenUsage?: TokenUsage;
+  summary?: Summary;
+  isTaskCheckpoint?: boolean;
+  turnID?: string;
+  transcriptIdentifierAtStart?: string;
+  checkpointTranscriptStart: number;
+}
+
+export interface CheckpointListItem {
+  checkpointID: CheckpointID;
+  sessionID: string;
+  message: string;
+  date: string;
+  isTaskCheckpoint: boolean;
+  agent?: AgentType;
+  sessionCount: number;
+  sessionIDs: string[];
+}
+
+export interface ExplainOptions {
+  cwd?: string;
+  sessionFilter?: string;
+  maxDepth?: number;
+  searchAll?: boolean;
+}
+
+export interface CommitExplainResult {
+  commitSHA: string;
+  commitMessage: string;
+  checkpointID: CheckpointID | null;
+  detail: CheckpointDetail | null;
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * List checkpoints on the current branch.
+ * Optionally filtered by session ID prefix.
+ */
+export async function listCheckpoints(options: ExplainOptions = {}): Promise<CheckpointListItem[]> {
+  const cwd = options.cwd;
+  const maxDepth = options.searchAll ? 0 : (options.maxDepth ?? 500);
+
+  // Get commits on the current branch
+  const logArgs = ['log', '--format=%H %s'];
+  if (maxDepth > 0) logArgs.push(`-n`, `${maxDepth}`);
+
+  let logOutput: string;
+  try {
+    logOutput = await git(logArgs, { cwd });
+  } catch {
+    return [];
+  }
+
+  const items: CheckpointListItem[] = [];
+
+  for (const line of logOutput.split('\n')) {
+    if (!line.trim()) continue;
+
+    const spaceIdx = line.indexOf(' ');
+    if (spaceIdx === -1) continue;
+
+    const sha = line.slice(0, spaceIdx);
+    const message = line.slice(spaceIdx + 1);
+
+    // Get full commit message to check for trailers
+    let fullMessage: string;
+    try {
+      fullMessage = await git(['log', '-1', '--format=%B', sha], { cwd });
+    } catch {
+      continue;
+    }
+
+    const [cpID, hasCp] = parseCheckpoint(fullMessage);
+    if (!hasCp || !cpID) continue;
+
+    const sessionIDs = parseAllSessions(fullMessage);
+
+    // Apply session filter
+    if (options.sessionFilter) {
+      const hasMatch = sessionIDs.some((sid) => sid.startsWith(options.sessionFilter!));
+      if (!hasMatch) continue;
+    }
+
+    // Get commit date
+    let date: string;
+    try {
+      date = (await git(['log', '-1', '--format=%aI', sha], { cwd })).trim();
+    } catch {
+      date = '';
+    }
+
+    items.push({
+      checkpointID: cpID,
+      sessionID: sessionIDs[0] ?? '',
+      message: message.trim(),
+      date,
+      isTaskCheckpoint: message.includes('[task]'),
+      sessionCount: sessionIDs.length,
+      sessionIDs,
+    });
+  }
+
+  return items;
+}
+
+/**
+ * Get detailed information about a specific checkpoint.
+ */
+export async function getCheckpointDetail(
+  checkpointID: CheckpointID,
+  options: ExplainOptions = {},
+): Promise<CheckpointDetail | null> {
+  const cwd = options.cwd;
+
+  // Try to read committed metadata from the checkpoints branch
+  const metadataPath = `${checkpointIDPath(checkpointID)}/metadata.json`;
+
+  try {
+    const content = await catFile(`${CHECKPOINTS_BRANCH}:${metadataPath}`, cwd);
+    const metadata = JSON.parse(content) as CommittedMetadata;
+
+    return {
+      checkpointID: metadata.checkpointID,
+      sessionID: metadata.sessionID,
+      agent: metadata.agent,
+      strategy: metadata.strategy,
+      createdAt: metadata.createdAt,
+      branch: metadata.branch,
+      checkpointsCount: metadata.checkpointsCount,
+      filesTouched: metadata.filesTouched,
+      tokenUsage: metadata.tokenUsage,
+      summary: metadata.summary,
+      isTaskCheckpoint: metadata.isTask,
+      turnID: metadata.turnID,
+      transcriptIdentifierAtStart: metadata.transcriptIdentifierAtStart,
+      checkpointTranscriptStart: metadata.checkpointTranscriptStart,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the transcript content for a checkpoint.
+ */
+export async function getCheckpointTranscript(
+  checkpointID: CheckpointID,
+  options: ExplainOptions = {},
+): Promise<Buffer | null> {
+  const cwd = options.cwd;
+  const transcriptPath = `${checkpointIDPath(checkpointID)}/transcript`;
+
+  try {
+    const content = await catFile(`${CHECKPOINTS_BRANCH}:${transcriptPath}`, cwd);
+    return Buffer.from(content, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Explain a specific commit by finding its associated checkpoint.
+ */
+export async function explainCommit(
+  commitRef: string,
+  options: ExplainOptions = {},
+): Promise<CommitExplainResult | null> {
+  const cwd = options.cwd;
+
+  let fullMessage: string;
+  try {
+    fullMessage = await git(['log', '-1', '--format=%B', commitRef], { cwd });
+  } catch {
+    return null;
+  }
+
+  const [cpID] = parseCheckpoint(fullMessage);
+
+  let sha: string;
+  try {
+    sha = (await git(['rev-parse', commitRef], { cwd })).trim();
+  } catch {
+    return null;
+  }
+
+  const message = fullMessage.split('\n')[0] ?? '';
+
+  let detail: CheckpointDetail | null = null;
+  if (cpID) {
+    detail = await getCheckpointDetail(cpID, options);
+  }
+
+  return {
+    commitSHA: sha,
+    commitMessage: message,
+    checkpointID: cpID,
+    detail,
+  };
+}
+
+/**
+ * Find a checkpoint by ID prefix (partial match).
+ */
+export async function findCheckpointByPrefix(
+  prefix: string,
+  options: ExplainOptions = {},
+): Promise<CheckpointID | null> {
+  const cwd = options.cwd;
+
+  // For full IDs, just return directly
+  if (prefix.length === 12) return prefix as CheckpointID;
+
+  // Need at least 2 chars for shard prefix
+  if (prefix.length < 2) return null;
+
+  const shardPrefix = prefix.slice(0, 2);
+  const remainder = prefix.slice(2);
+
+  try {
+    const entries = await lsTree(CHECKPOINTS_BRANCH, shardPrefix, cwd);
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(remainder)) {
+        return `${shardPrefix}${entry.name}` as CheckpointID;
+      }
+    }
+  } catch {
+    // Shard doesn't exist
+  }
+
+  return null;
+}

package/references/sessionlog/src/commands/reset.ts

@@ -0,0 +1,105 @@
+/**
+ * Reset Command
+ *
+ * Deletes shadow branch and session state for the current HEAD.
+ * More targeted than clean — only affects the current commit's sessions.
+ */
+
+import type { SessionState } from '../types.js';
+import { getHead } from '../git-operations.js';
+import { createSessionStore } from '../store/session-store.js';
+import { createCheckpointStore } from '../store/checkpoint-store.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ResetOptions {
+  cwd?: string;
+  /** Reset a specific session instead of all */
+  sessionID?: string;
+  /** Skip confirmation (for programmatic use) */
+  force?: boolean;
+}
+
+export interface ResetResult {
+  sessionsReset: string[];
+  branchesDeleted: string[];
+  errors: string[];
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Reset shadow branches and session state for the current HEAD
+ */
+export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
+  const cwd = options.cwd;
+  const sessionStore = createSessionStore(cwd);
+  const checkpointStore = createCheckpointStore(cwd);
+  const head = await getHead(cwd);
+
+  const errors: string[] = [];
+  const sessionsReset: string[] = [];
+  const branchesDeleted: string[] = [];
+
+  const sessions = await sessionStore.list();
+
+  // Find sessions matching the current HEAD
+  let matchingSessions: SessionState[];
+
+  if (options.sessionID) {
+    matchingSessions = sessions.filter((s) => s.sessionID === options.sessionID);
+    if (matchingSessions.length === 0) {
+      errors.push(`Session not found: ${options.sessionID}`);
+      return { sessionsReset, branchesDeleted, errors };
+    }
+  } else {
+    matchingSessions = sessions.filter(
+      (s) => s.baseCommit === head || head.startsWith(s.baseCommit),
+    );
+  }
+
+  // Safety check: warn about active sessions
+  if (!options.force) {
+    const activeSessions = matchingSessions.filter((s) => s.phase === 'active');
+    if (activeSessions.length > 0) {
+      errors.push(
+        `${activeSessions.length} active session(s) found. Use --force to reset active sessions.`,
+      );
+      return { sessionsReset, branchesDeleted, errors };
+    }
+  }
+
+  for (const session of matchingSessions) {
+    // Delete shadow branch
+    if (session.baseCommit) {
+      const branchName = checkpointStore.getShadowBranchName(
+        session.baseCommit,
+        session.worktreeID,
+      );
+      try {
+        await checkpointStore.deleteShadowBranch(branchName);
+        branchesDeleted.push(branchName);
+      } catch (e) {
+        errors.push(
+          `Failed to delete branch ${branchName}: ${e instanceof Error ? e.message : String(e)}`,
+        );
+      }
+    }
+
+    // Delete session state
+    try {
+      await sessionStore.delete(session.sessionID);
+      sessionsReset.push(session.sessionID);
+    } catch (e) {
+      errors.push(
+        `Failed to delete session ${session.sessionID}: ${e instanceof Error ? e.message : String(e)}`,
+      );
+    }
+  }
+
+  return { sessionsReset, branchesDeleted, errors };
+}

package/references/sessionlog/src/commands/resume.ts

@@ -0,0 +1,180 @@
+/**
+ * Resume Command
+ *
+ * Library implementation for resuming agent sessions from branches.
+ * Handles branch checkout, session discovery from commit trailers,
+ * and transcript restoration.
+ */
+
+import type { CheckpointID } from '../types.js';
+import { git, refExists } from '../git-operations.js';
+import { parseCheckpoint, parseAllSessions } from '../utils/trailers.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ResumeInfo {
+  branchName: string;
+  sessionID: string;
+  sessionIDs: string[];
+  checkpointID: CheckpointID | null;
+  resumeCommand: string;
+  commitSHA: string;
+  commitMessage: string;
+  needsReset: boolean;
+  resetTargetSHA?: string;
+}
+
+export interface ResumeOptions {
+  cwd?: string;
+  force?: boolean;
+}
+
+export interface ResumeResult {
+  success: boolean;
+  info?: ResumeInfo;
+  error?: string;
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Discover resume information for a branch without performing any actions.
+ * This is useful for preview/dry-run scenarios.
+ */
+export async function discoverResumeInfo(
+  branchName: string,
+  options: ResumeOptions = {},
+): Promise<ResumeResult> {
+  const cwd = options.cwd;
+
+  // Check if branch exists locally
+  const localExists = await refExists(`refs/heads/${branchName}`, cwd);
+  if (!localExists) {
+    // Check remote
+    const remoteExists = await refExists(`refs/remotes/origin/${branchName}`, cwd);
+    if (!remoteExists) {
+      return {
+        success: false,
+        error: `Branch '${branchName}' not found locally or on origin`,
+      };
+    }
+
+    return {
+      success: false,
+      error: `Branch '${branchName}' exists on origin but not locally. Fetch it first.`,
+    };
+  }
+
+  // Find the most recent commit with a checkpoint trailer
+  const info = await findSessionInfo(branchName, cwd);
+  if (!info) {
+    return {
+      success: false,
+      error: `No checkpointed session found on branch '${branchName}'`,
+    };
+  }
+
+  return { success: true, info };
+}
+
+/**
+ * Get a list of branches that have checkpointed sessions.
+ */
+export async function listResumableBranches(
+  options: ResumeOptions = {},
+): Promise<Array<{ branch: string; sessionID: string; lastCommit: string }>> {
+  const cwd = options.cwd;
+  const results: Array<{ branch: string; sessionID: string; lastCommit: string }> = [];
+
+  let branchOutput: string;
+  try {
+    branchOutput = await git(['branch', '--format=%(refname:short)'], { cwd });
+  } catch {
+    return [];
+  }
+
+  for (const branch of branchOutput.split('\n')) {
+    const trimmed = branch.trim();
+    if (!trimmed) continue;
+
+    // Get the last few commits to check for checkpoint trailers
+    try {
+      const logOutput = await git(['log', '-10', '--format=%H', trimmed], { cwd });
+
+      for (const sha of logOutput.split('\n')) {
+        if (!sha.trim()) continue;
+
+        const fullMessage = await git(['log', '-1', '--format=%B', sha.trim()], { cwd });
+
+        const [cpID, hasCp] = parseCheckpoint(fullMessage);
+        if (hasCp && cpID) {
+          const sessionIDs = parseAllSessions(fullMessage);
+          if (sessionIDs.length > 0) {
+            results.push({
+              branch: trimmed,
+              sessionID: sessionIDs[0],
+              lastCommit: sha.trim().slice(0, 7),
+            });
+            break; // Only report first match per branch
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return results;
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+async function findSessionInfo(branchName: string, cwd?: string): Promise<ResumeInfo | null> {
+  // Walk commits on the branch looking for one with a checkpoint trailer
+  let logOutput: string;
+  try {
+    logOutput = await git(['log', '-50', '--format=%H', branchName], { cwd });
+  } catch {
+    return null;
+  }
+
+  const shas = logOutput.split('\n').filter(Boolean);
+  for (let i = 0; i < shas.length; i++) {
+    const sha = shas[i].trim();
+    if (!sha) continue;
+
+    let fullMessage: string;
+    try {
+      fullMessage = await git(['log', '-1', '--format=%B', sha], { cwd });
+    } catch {
+      continue;
+    }
+
+    const [cpID, hasCp] = parseCheckpoint(fullMessage);
+    if (!hasCp || !cpID) continue;
+
+    const sessionIDs = parseAllSessions(fullMessage);
+    const message = fullMessage.split('\n')[0] ?? '';
+    const needsReset = i > 0; // If not the tip commit, needs reset
+
+    return {
+      branchName,
+      sessionID: sessionIDs[0] ?? '',
+      sessionIDs,
+      checkpointID: cpID,
+      resumeCommand: '', // To be filled by consumer with agent-specific command
+      commitSHA: sha,
+      commitMessage: message,
+      needsReset,
+      resetTargetSHA: needsReset ? sha : undefined,
+    };
+  }
+
+  return null;
+}