cognitive-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,195 @@
+/**
+ * Rewind Command
+ *
+ * Browse checkpoints and restore session state to a previous point.
+ * Supports both shadow branch (temporary) and committed checkpoint rewind.
+ */
+
+import type { RewindPoint } from '../types.js';
+import { git, hasUncommittedChanges } from '../git-operations.js';
+import { createCheckpointStore } from '../store/checkpoint-store.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface RewindOptions {
+  cwd?: string;
+  /** Maximum number of rewind points to return */
+  limit?: number;
+}
+
+export interface RewindResult {
+  success: boolean;
+  message: string;
+  rewindPoint?: RewindPoint;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * List available rewind points
+ */
+export async function listRewindPoints(options: RewindOptions = {}): Promise<RewindPoint[]> {
+  const cwd = options.cwd;
+  const limit = options.limit ?? 20;
+  const points: RewindPoint[] = [];
+
+  const checkpointStore = createCheckpointStore(cwd);
+
+  // 1. Shadow branch checkpoints (temporary, most recent)
+  const temporaryBranches = await checkpointStore.listTemporary();
+  for (const temp of temporaryBranches) {
+    points.push({
+      id: temp.latestCommit,
+      message: `Shadow checkpoint on ${temp.branchName}`,
+      date: temp.timestamp,
+      isTaskCheckpoint: false,
+      isLogsOnly: false,
+      sessionID: temp.sessionID,
+      sessionCount: 1,
+      sessionIDs: temp.sessionID ? [temp.sessionID] : [],
+    });
+  }
+
+  // 2. Committed checkpoints (permanent)
+  const committed = await checkpointStore.listCommitted(limit);
+  for (const cp of committed) {
+    const sessionIDs = cp.sessions
+      .map((s) => {
+        const match = s.metadata.match(/\/(\d+)\/metadata\.json$/);
+        return match ? match[1] : '';
+      })
+      .filter(Boolean);
+
+    points.push({
+      id: cp.checkpointID,
+      message: `Checkpoint ${cp.checkpointID.slice(0, 8)}`,
+      checkpointID: cp.checkpointID,
+      date: new Date().toISOString(), // Will be populated from metadata
+      isTaskCheckpoint: false,
+      isLogsOnly: true,
+      agent: undefined,
+      sessionCount: cp.sessions.length,
+      sessionIDs,
+    });
+
+    // Read detailed metadata for each committed checkpoint
+    for (let i = 0; i < cp.sessions.length; i++) {
+      const content = await checkpointStore.readSessionContent(cp.checkpointID, i);
+      if (content) {
+        const lastPoint = points[points.length - 1];
+        lastPoint.date = content.metadata.createdAt;
+        lastPoint.agent = content.metadata.agent;
+        lastPoint.sessionID = content.metadata.sessionID;
+        if (content.metadata.isTask) {
+          lastPoint.isTaskCheckpoint = true;
+        }
+      }
+    }
+  }
+
+  // Sort by date (most recent first) and limit
+  points.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+  return points.slice(0, limit);
+}
+
+/**
+ * Rewind to a specific point (non-interactive)
+ */
+export async function rewindTo(
+  pointID: string,
+  options: { cwd?: string; logsOnly?: boolean; reset?: boolean } = {},
+): Promise<RewindResult> {
+  const cwd = options.cwd;
+
+  // Safety check: uncommitted changes
+  if (await hasUncommittedChanges(cwd)) {
+    return {
+      success: false,
+      message: 'Cannot rewind: there are uncommitted changes. Commit or stash them first.',
+    };
+  }
+
+  // Find the rewind point
+  const points = await listRewindPoints({ cwd, limit: 50 });
+  const point = points.find((p) => p.id === pointID || p.checkpointID === pointID);
+
+  if (!point) {
+    return { success: false, message: `Rewind point not found: ${pointID}` };
+  }
+
+  if (point.isLogsOnly && !options.logsOnly && !options.reset) {
+    return {
+      success: false,
+      message:
+        'This is a logs-only checkpoint. Use --logs-only to restore logs, or --reset to reset the branch.',
+    };
+  }
+
+  if (options.reset) {
+    // Destructive: git reset --hard
+    try {
+      await git(['reset', '--hard', pointID], { cwd });
+      return {
+        success: true,
+        message: `Reset to ${pointID.slice(0, 8)}`,
+        rewindPoint: point,
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: `Reset failed: ${e instanceof Error ? e.message : String(e)}`,
+      };
+    }
+  }
+
+  if (point.isLogsOnly || options.logsOnly) {
+    // Restore logs only (no checkout)
+    return {
+      success: true,
+      message: `Logs restored for checkpoint ${point.checkpointID ?? pointID}`,
+      rewindPoint: point,
+    };
+  }
+
+  // Full rewind: checkout to the shadow branch commit
+  try {
+    await git(['checkout', pointID], { cwd });
+    return {
+      success: true,
+      message: `Rewound to ${pointID.slice(0, 8)}`,
+      rewindPoint: point,
+    };
+  } catch (e) {
+    return {
+      success: false,
+      message: `Rewind failed: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}
+
+/**
+ * List rewind points as JSON (for CLI --list flag)
+ */
+export async function listRewindPointsJSON(options: RewindOptions = {}): Promise<string> {
+  const points = await listRewindPoints(options);
+  return JSON.stringify(
+    points.map((p) => ({
+      id: p.id,
+      message: p.message,
+      date: p.date,
+      is_task_checkpoint: p.isTaskCheckpoint,
+      is_logs_only: p.isLogsOnly,
+      checkpoint_id: p.checkpointID,
+      agent: p.agent,
+      session_id: p.sessionID,
+      session_prompt: p.sessionPrompt,
+      session_count: p.sessionCount,
+    })),
+    null,
+    2,
+  );
+}

package/references/sessionlog/src/commands/setup-ccweb.ts

@@ -0,0 +1,275 @@
+/**
+ * Setup ccweb Command
+ *
+ * Configures a repository for Sessionlog integration with Claude Code Web.
+ * Creates .claude/settings.json SessionStart hook and .claude/scripts/setup-env.sh
+ * so that sessionlog is automatically installed and enabled on every ccweb session.
+ *
+ * Inspired by the entire-setup-ccweb pattern:
+ * https://github.com/aromarious/entire-setup-ccweb
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { isGitRepository, getWorktreeRoot } from '../git-operations.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const CLAUDE_SCRIPTS_DIR = '.claude/scripts';
+const CLAUDE_SETTINGS_FILE = '.claude/settings.json';
+const SETUP_SCRIPT_FILE = '.claude/scripts/setup-env.sh';
+const SETUP_HOOK_COMMAND = 'sh .claude/scripts/setup-env.sh';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SetupCcwebOptions {
+  /** Working directory */
+  cwd?: string;
+
+  /** Allowed push prefixes (space-separated, overrides template default) */
+  pushPrefixes?: string;
+
+  /** Force overwrite existing setup */
+  force?: boolean;
+}
+
+export interface SetupCcwebResult {
+  success: boolean;
+  settingsCreated: boolean;
+  scriptCreated: boolean;
+  errors: string[];
+}
+
+// ============================================================================
+// Claude Settings Types
+// ============================================================================
+
+interface ClaudeHookEntry {
+  type: string;
+  command: string;
+}
+
+interface ClaudeHookMatcher {
+  matcher: string;
+  hooks: ClaudeHookEntry[];
+}
+
+interface ClaudeSettings {
+  hooks?: {
+    SessionStart?: ClaudeHookMatcher[];
+    [key: string]: ClaudeHookMatcher[] | undefined;
+  };
+  permissions?: {
+    allow?: string[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Set up a repository for Sessionlog on Claude Code Web.
+ *
+ * This creates:
+ * 1. `.claude/settings.json` — adds a SessionStart hook that runs the setup script
+ * 2. `.claude/scripts/setup-env.sh` — installs sessionlog, enables it, configures push access
+ *
+ * After running this command, commit the `.claude/` directory and push. When the
+ * repository is opened in ccweb, sessionlog will be automatically installed and
+ * configured on every session start.
+ */
+export async function setupCcweb(options: SetupCcwebOptions = {}): Promise<SetupCcwebResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const errors: string[] = [];
+
+  // Validate git repository
+  if (!(await isGitRepository(cwd))) {
+    return {
+      success: false,
+      settingsCreated: false,
+      scriptCreated: false,
+      errors: ['Not a git repository'],
+    };
+  }
+
+  const root = await getWorktreeRoot(cwd);
+
+  // Create directories
+  const scriptsDir = path.join(root, CLAUDE_SCRIPTS_DIR);
+  await fs.promises.mkdir(scriptsDir, { recursive: true });
+
+  // Update .claude/settings.json
+  let settingsCreated = false;
+  try {
+    settingsCreated = await updateClaudeSettings(root, options.force);
+  } catch (e) {
+    errors.push(`Failed to update settings: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  // Create/update setup script
+  let scriptCreated = false;
+  try {
+    scriptCreated = await writeSetupScript(root, options);
+  } catch (e) {
+    errors.push(`Failed to write setup script: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  return {
+    success: errors.length === 0,
+    settingsCreated,
+    scriptCreated,
+    errors,
+  };
+}
+
+// ============================================================================
+// Settings Management
+// ============================================================================
+
+/**
+ * Add the SessionStart hook to .claude/settings.json
+ */
+async function updateClaudeSettings(root: string, force = false): Promise<boolean> {
+  const settingsPath = path.join(root, CLAUDE_SETTINGS_FILE);
+  let settings: ClaudeSettings = {};
+
+  // Read existing settings
+  try {
+    const content = await fs.promises.readFile(settingsPath, 'utf-8');
+    settings = JSON.parse(content) as ClaudeSettings;
+  } catch {
+    // No existing settings — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  // Check if our hook is already installed
+  const sessionStartHooks = settings.hooks.SessionStart ?? [];
+  const hasOurHook = sessionStartHooks.some((m) =>
+    m.hooks.some((h) => h.command.includes('setup-env.sh')),
+  );
+
+  if (hasOurHook && !force) {
+    return false; // Already installed
+  }
+
+  if (hasOurHook && force) {
+    // Remove existing hook for reinstall
+    settings.hooks.SessionStart = sessionStartHooks.filter(
+      (m) => !m.hooks.some((h) => h.command.includes('setup-env.sh')),
+    );
+  }
+
+  // Add SessionStart hook
+  const matchers = settings.hooks.SessionStart ?? [];
+  matchers.push({
+    matcher: '',
+    hooks: [
+      {
+        type: 'command',
+        command: SETUP_HOOK_COMMAND,
+      },
+    ],
+  });
+  settings.hooks.SessionStart = matchers;
+
+  // Add bash permission for the setup script
+  if (!settings.permissions) settings.permissions = {};
+  if (!settings.permissions.allow) settings.permissions.allow = [];
+  const allowEntry = `Bash(sh .claude/scripts/setup-env.sh)`;
+  if (!settings.permissions.allow.includes(allowEntry)) {
+    settings.permissions.allow.push(allowEntry);
+  }
+
+  // Write settings
+  const dir = path.dirname(settingsPath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  await fs.promises.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  return true;
+}
+
+// ============================================================================
+// Setup Script
+// ============================================================================
+
+/**
+ * Write the setup-env.sh script from the bundled template.
+ * Preserves user-customized ALLOWED_PUSH_PREFIXES on update.
+ */
+async function writeSetupScript(root: string, options: SetupCcwebOptions): Promise<boolean> {
+  const scriptPath = path.join(root, SETUP_SCRIPT_FILE);
+
+  // Check if script already exists
+  let existingContent = '';
+  try {
+    existingContent = await fs.promises.readFile(scriptPath, 'utf-8');
+  } catch {
+    // File doesn't exist
+  }
+
+  if (existingContent && !options.force) {
+    // Preserve existing script unless --force
+    return false;
+  }
+
+  // Preserve user-customized ALLOWED_PUSH_PREFIXES from existing script
+  let pushPrefixes = options.pushPrefixes ?? 'sessionlog/ claude/';
+  if (existingContent && !options.pushPrefixes) {
+    const match = existingContent.match(/^ALLOWED_PUSH_PREFIXES="([^"]*)"$/m);
+    if (match) {
+      pushPrefixes = match[1];
+    }
+  }
+
+  // Load the template
+  const template = loadTemplate();
+
+  // Apply push prefixes customization
+  const content = template.replace(
+    /^ALLOWED_PUSH_PREFIXES="[^"]*"$/m,
+    `ALLOWED_PUSH_PREFIXES="${pushPrefixes}"`,
+  );
+
+  await fs.promises.writeFile(scriptPath, content, { mode: 0o755 });
+
+  return true;
+}
+
+/**
+ * Load the setup-env.sh template.
+ * Tries the bundled template first (from package dist), then falls back to
+ * the source template for development.
+ */
+function loadTemplate(): string {
+  const require = createRequire(import.meta.url);
+
+  // Try relative paths from the compiled output location (dist/commands/)
+  const thisDir = path.dirname(new URL(import.meta.url).pathname);
+  const candidates = [
+    // Installed via npm: template is in templates/ relative to package root
+    path.resolve(path.dirname(require.resolve('../../package.json')), 'templates', 'setup-env.sh'),
+    // Development: template is in templates/ at repo root (from dist/commands/ or src/commands/)
+    path.resolve(thisDir, '..', '..', 'templates', 'setup-env.sh'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      return fs.readFileSync(candidate, 'utf-8');
+    } catch {
+      // Try next candidate
+    }
+  }
+
+  throw new Error(
+    'Could not find setup-env.sh template. Ensure the templates/ directory is included in the package.',
+  );
+}

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

@@ -0,0 +1,172 @@
+/**
+ * Status Command
+ *
+ * Shows the current Sessionlog setup status, active sessions,
+ * and configuration.
+ */
+
+import { type SessionlogSettings, CHECKPOINTS_BRANCH } from '../types.js';
+import {
+  isGitRepository,
+  getWorktreeRoot,
+  getCurrentBranch,
+  refExists,
+  initSessionRepo,
+  resolveSessionRepoPath,
+  getProjectID,
+} from '../git-operations.js';
+import { loadSettings } from '../config.js';
+import { createSessionStore } from '../store/session-store.js';
+import { SESSION_DIR_NAME } from '../types.js';
+import { areGitHooksInstalled } from '../hooks/git-hooks.js';
+import { detectAgents } from '../agent/registry.js';
+import { hasHookSupport } from '../agent/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StatusResult {
+  /** Whether Sessionlog is set up and enabled */
+  enabled: boolean;
+
+  /** Current strategy */
+  strategy: string;
+
+  /** Current branch */
+  branch: string | null;
+
+  /** Whether the checkpoints branch exists */
+  hasCheckpointsBranch: boolean;
+
+  /** Active sessions */
+  sessions: SessionStatus[];
+
+  /** Installed agents with hooks */
+  agents: string[];
+
+  /** Whether git hooks are installed */
+  gitHooksInstalled: boolean;
+
+  /** Effective settings */
+  settings: SessionlogSettings;
+}
+
+export interface SessionStatus {
+  sessionID: string;
+  agentType: string;
+  phase: string;
+  startedAt: string;
+  firstPrompt?: string;
+  filesTouched: string[];
+  stepCount: number;
+  tokenUsage?: {
+    input: number;
+    output: number;
+  };
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Get the current status of Sessionlog
+ */
+export async function status(cwd?: string): Promise<StatusResult> {
+  const isRepo = await isGitRepository(cwd);
+
+  if (!isRepo) {
+    return {
+      enabled: false,
+      strategy: 'manual-commit',
+      branch: null,
+      hasCheckpointsBranch: false,
+      sessions: [],
+      agents: [],
+      gitHooksInstalled: false,
+      settings: { enabled: false, strategy: 'manual-commit' },
+    };
+  }
+
+  const root = await getWorktreeRoot(cwd);
+  const settings = await loadSettings(cwd);
+  const branch = await getCurrentBranch(cwd);
+  const gitHooks = await areGitHooksInstalled(root);
+
+  // Resolve session repo if configured
+  let sessionRepoCwd: string | undefined;
+  let sessionsDir: string | undefined;
+  let cpBranch = CHECKPOINTS_BRANCH;
+  if (settings.sessionRepoPath) {
+    try {
+      const projectID = getProjectID(root);
+      const resolved = resolveSessionRepoPath(settings.sessionRepoPath, root);
+      sessionRepoCwd = await initSessionRepo(resolved);
+      sessionsDir = `${sessionRepoCwd}/${SESSION_DIR_NAME}/${projectID}`;
+      cpBranch = `${CHECKPOINTS_BRANCH}/${projectID}`;
+    } catch {
+      // Fall back to project repo if session repo can't be initialized
+    }
+  }
+
+  const checkpointsCwd = sessionRepoCwd ?? cwd;
+  const hasCheckpoints = await refExists(`refs/heads/${cpBranch}`, checkpointsCwd);
+
+  // Detect agents with hooks
+  const agents = await detectAgents(cwd);
+  const agentNames: string[] = [];
+  for (const agent of agents) {
+    if (hasHookSupport(agent)) {
+      const installed = await agent.areHooksInstalled(root);
+      if (installed) agentNames.push(agent.name);
+    }
+  }
+
+  // Load sessions
+  const sessionStore = createSessionStore(cwd, sessionsDir);
+  const allSessions = await sessionStore.list();
+
+  const sessions: SessionStatus[] = allSessions.map((s) => ({
+    sessionID: s.sessionID,
+    agentType: s.agentType,
+    phase: s.phase,
+    startedAt: s.startedAt,
+    firstPrompt: s.firstPrompt,
+    filesTouched: s.filesTouched,
+    stepCount: s.stepCount,
+    tokenUsage: s.tokenUsage
+      ? {
+          input: s.tokenUsage.inputTokens + s.tokenUsage.cacheReadTokens,
+          output: s.tokenUsage.outputTokens,
+        }
+      : undefined,
+  }));
+
+  return {
+    enabled: settings.enabled,
+    strategy: settings.strategy,
+    branch,
+    hasCheckpointsBranch: hasCheckpoints,
+    sessions,
+    agents: agentNames,
+    gitHooksInstalled: gitHooks,
+    settings,
+  };
+}
+
+/**
+ * Format status for display (JSON output)
+ */
+export function formatStatusJSON(result: StatusResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+/**
+ * Format token count for display
+ */
+export function formatTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+  return String(count);
+}