cognitive-core 0.2.1 → 0.2.3

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

@@ -1,261 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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

@@ -1,180 +0,0 @@
-/**
- * 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;
-}