cognitive-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,133 @@
+/**
+ * Clean Command
+ *
+ * Removes orphaned Sessionlog data: shadow branches, stale session files,
+ * and temporary files that are no longer referenced.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { SESSIONLOG_TMP_DIR, SHADOW_BRANCH_PREFIX, CHECKPOINTS_BRANCH } from '../types.js';
+import { getWorktreeRoot, listBranches, deleteBranch } from '../git-operations.js';
+import { createSessionStore } from '../store/session-store.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CleanupItem {
+  type: 'shadow-branch' | 'session-file' | 'temp-file';
+  path: string;
+  reason: string;
+}
+
+export interface CleanResult {
+  items: CleanupItem[];
+  deletedCount: number;
+  errors: string[];
+}
+
+export interface CleanOptions {
+  cwd?: string;
+  /** Actually delete (default: preview only) */
+  force?: boolean;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Find orphaned items
+ */
+export async function findOrphaned(cwd?: string): Promise<CleanupItem[]> {
+  const items: CleanupItem[] = [];
+  const sessionStore = createSessionStore(cwd);
+  const sessions = await sessionStore.list();
+  const activeBaseCommits = new Set(sessions.map((s) => s.baseCommit).filter(Boolean));
+
+  // 1. Orphaned shadow branches
+  const branches = await listBranches(`${SHADOW_BRANCH_PREFIX}*`, cwd);
+  for (const branch of branches) {
+    if (branch === CHECKPOINTS_BRANCH) continue;
+
+    // Extract base commit from branch name
+    const hashPart = branch.slice(SHADOW_BRANCH_PREFIX.length);
+    const baseCommit = hashPart.split('-')[0];
+
+    // A shadow branch is orphaned if no active session references its base commit
+    if (!activeBaseCommits.has(baseCommit)) {
+      // Check against full base commits (the hash part is a short hash)
+      const isReferenced = sessions.some(
+        (s) => s.baseCommit && s.baseCommit.startsWith(baseCommit),
+      );
+
+      if (!isReferenced) {
+        items.push({
+          type: 'shadow-branch',
+          path: branch,
+          reason: 'No active session references this branch',
+        });
+      }
+    }
+  }
+
+  // 2. Orphaned temp files
+  try {
+    const root = await getWorktreeRoot(cwd);
+    const tmpDir = path.join(root, SESSIONLOG_TMP_DIR);
+
+    const files = await fs.promises.readdir(tmpDir).catch(() => []);
+    for (const file of files) {
+      const filePath = path.join(tmpDir, file);
+      const stat = await fs.promises.stat(filePath);
+
+      // Consider temp files older than 24 hours as orphaned
+      if (Date.now() - stat.mtimeMs > 24 * 60 * 60 * 1000) {
+        items.push({
+          type: 'temp-file',
+          path: filePath,
+          reason: 'Temporary file older than 24 hours',
+        });
+      }
+    }
+  } catch {
+    // Temp dir may not exist
+  }
+
+  return items;
+}
+
+/**
+ * Clean orphaned items
+ */
+export async function clean(options: CleanOptions = {}): Promise<CleanResult> {
+  const cwd = options.cwd;
+  const items = await findOrphaned(cwd);
+  const errors: string[] = [];
+  let deletedCount = 0;
+
+  if (!options.force) {
+    return { items, deletedCount: 0, errors: [] };
+  }
+
+  for (const item of items) {
+    try {
+      switch (item.type) {
+        case 'shadow-branch':
+          await deleteBranch(item.path, true, cwd);
+          deletedCount++;
+          break;
+        case 'session-file':
+        case 'temp-file':
+          await fs.promises.unlink(item.path);
+          deletedCount++;
+          break;
+      }
+    } catch (e) {
+      errors.push(`Failed to delete ${item.path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  return { items, deletedCount, errors };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Disable Command
+ *
+ * Disables Sessionlog in a repository. Can optionally fully uninstall
+ * hooks and clean up all Sessionlog data.
+ */
+
+import { getWorktreeRoot, isGitRepository } from '../git-operations.js';
+import { saveProjectSettings, saveLocalSettings } from '../config.js';
+import { uninstallGitHooks } from '../hooks/git-hooks.js';
+import { detectAgents } from '../agent/registry.js';
+import { hasHookSupport } from '../agent/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DisableOptions {
+  cwd?: string;
+  /** Fully uninstall hooks (not just disable) */
+  uninstall?: boolean;
+  /** Disable in local settings instead of project settings */
+  local?: boolean;
+}
+
+export interface DisableResult {
+  disabled: boolean;
+  uninstalled: boolean;
+  errors: string[];
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Disable Sessionlog in a repository
+ */
+export async function disable(options: DisableOptions = {}): Promise<DisableResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const errors: string[] = [];
+
+  if (!(await isGitRepository(cwd))) {
+    return { disabled: false, uninstalled: false, errors: ['Not a git repository'] };
+  }
+
+  const root = await getWorktreeRoot(cwd);
+
+  // Update settings
+  if (options.local) {
+    await saveLocalSettings({ enabled: false }, cwd);
+  } else {
+    await saveProjectSettings({ enabled: false }, cwd);
+  }
+
+  let uninstalled = false;
+
+  if (options.uninstall) {
+    // Remove git hooks
+    try {
+      await uninstallGitHooks(root);
+    } catch (e) {
+      errors.push(`Failed to uninstall git hooks: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    // Remove agent hooks
+    const agents = await detectAgents(cwd);
+    for (const agent of agents) {
+      if (hasHookSupport(agent)) {
+        try {
+          await agent.uninstallHooks(root);
+        } catch (e) {
+          errors.push(
+            `Failed to uninstall ${agent.name} hooks: ${e instanceof Error ? e.message : String(e)}`,
+          );
+        }
+      }
+    }
+
+    uninstalled = true;
+  }
+
+  return { disabled: true, uninstalled, errors };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Doctor Command
+ *
+ * Identifies and fixes stuck sessions. A session is "stuck" if it's
+ * in ACTIVE phase with no recent interaction, or in ENDED phase with
+ * uncondensed checkpoint data.
+ */
+
+import type { SessionState } from '../types.js';
+import { createSessionStore } from '../store/session-store.js';
+import { createCheckpointStore } from '../store/checkpoint-store.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StuckSession {
+  sessionID: string;
+  reason: 'active-stale' | 'ended-uncondensed';
+  session: SessionState;
+  hasShadowBranch: boolean;
+  canCondense: boolean;
+}
+
+export interface DoctorResult {
+  stuckSessions: StuckSession[];
+  fixedCount: number;
+  discardedCount: number;
+  errors: string[];
+}
+
+export interface DoctorOptions {
+  cwd?: string;
+  /** Auto-fix without prompting */
+  force?: boolean;
+  /** Stale threshold in milliseconds (default: 1 hour) */
+  staleThresholdMs?: number;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Diagnose stuck sessions
+ */
+export async function diagnose(options: DoctorOptions = {}): Promise<StuckSession[]> {
+  const cwd = options.cwd;
+  const staleThreshold = options.staleThresholdMs ?? 60 * 60 * 1000; // 1 hour
+
+  const sessionStore = createSessionStore(cwd);
+  const checkpointStore = createCheckpointStore(cwd);
+
+  const sessions = await sessionStore.list();
+  const temporaryBranches = await checkpointStore.listTemporary();
+  const stuck: StuckSession[] = [];
+
+  for (const session of sessions) {
+    // Check for active stale sessions
+    if (session.phase === 'active') {
+      const lastInteraction = session.lastInteractionTime
+        ? new Date(session.lastInteractionTime).getTime()
+        : new Date(session.startedAt).getTime();
+
+      if (Date.now() - lastInteraction > staleThreshold) {
+        const hasShadow = temporaryBranches.some((b) => b.sessionID === session.sessionID);
+
+        stuck.push({
+          sessionID: session.sessionID,
+          reason: 'active-stale',
+          session,
+          hasShadowBranch: hasShadow,
+          canCondense: hasShadow && session.filesTouched.length > 0,
+        });
+      }
+    }
+
+    // Check for ended sessions with uncondensed data
+    if (session.phase === 'ended') {
+      const hasShadow = temporaryBranches.some((b) => b.sessionID === session.sessionID);
+
+      if (hasShadow) {
+        stuck.push({
+          sessionID: session.sessionID,
+          reason: 'ended-uncondensed',
+          session,
+          hasShadowBranch: true,
+          canCondense: session.filesTouched.length > 0,
+        });
+      }
+    }
+  }
+
+  return stuck;
+}
+
+/**
+ * Discard a stuck session (delete state + shadow branch)
+ */
+export async function discardSession(
+  sessionID: string,
+  options: { cwd?: string } = {},
+): Promise<void> {
+  const cwd = options.cwd;
+  const sessionStore = createSessionStore(cwd);
+  const checkpointStore = createCheckpointStore(cwd);
+
+  const session = await sessionStore.load(sessionID);
+  if (!session) return;
+
+  // Delete shadow branch if it exists
+  if (session.baseCommit) {
+    const branchName = checkpointStore.getShadowBranchName(session.baseCommit, session.worktreeID);
+    await checkpointStore.deleteShadowBranch(branchName);
+  }
+
+  // Delete session state
+  await sessionStore.delete(sessionID);
+}
+
+/**
+ * Run doctor with auto-fix
+ */
+export async function doctor(options: DoctorOptions = {}): Promise<DoctorResult> {
+  const stuck = await diagnose(options);
+  const errors: string[] = [];
+  const fixedCount = 0;
+  let discardedCount = 0;
+
+  if (options.force) {
+    for (const s of stuck) {
+      try {
+        // For now, discard all stuck sessions
+        await discardSession(s.sessionID, { cwd: options.cwd });
+        discardedCount++;
+      } catch (e) {
+        errors.push(
+          `Failed to fix session ${s.sessionID}: ${e instanceof Error ? e.message : String(e)}`,
+        );
+      }
+    }
+  }
+
+  return { stuckSessions: stuck, fixedCount, discardedCount, errors };
+}

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

@@ -0,0 +1,202 @@
+/**
+ * Enable Command
+ *
+ * Enables Sessionlog in a repository: creates settings, installs hooks,
+ * auto-detects agents.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  type SessionlogSettings,
+  type AgentName,
+  SESSION_DIR_NAME,
+} from '../types.js';
+import {
+  isGitRepository,
+  getWorktreeRoot,
+  getGitDir,
+  getHead,
+  initSessionRepo,
+  resolveSessionRepoPath,
+} from '../git-operations.js';
+import { resolveSessionlogDir, saveProjectSettings, saveLocalSettings, ensureGitignore } from '../config.js';
+import { installGitHooks } from '../hooks/git-hooks.js';
+import { detectAgent, getAgent, listAgentNames } from '../agent/registry.js';
+import { hasHookSupport } from '../agent/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface EnableOptions {
+  /** Working directory */
+  cwd?: string;
+
+  /** Specific agent to enable (auto-detect if not specified) */
+  agent?: AgentName;
+
+  /** Force reinstall hooks even if already present */
+  force?: boolean;
+
+  /** Save to local settings instead of project settings */
+  local?: boolean;
+
+  /** Write to settings.json even if already present */
+  project?: boolean;
+
+  /** Disable automatic session log pushing */
+  skipPushSessions?: boolean;
+
+  /** Opt out of anonymous analytics */
+  telemetry?: boolean;
+
+  /** Path to a separate repository for session/checkpoint storage */
+  sessionRepoPath?: string;
+}
+
+export interface EnableResult {
+  enabled: boolean;
+  agent: AgentName | null;
+  agentHooksInstalled: number;
+  gitHooksInstalled: number;
+  errors: string[];
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Enable Sessionlog in a repository
+ */
+export async function enable(options: EnableOptions = {}): Promise<EnableResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const errors: string[] = [];
+
+  // Validate git repository
+  if (!(await isGitRepository(cwd))) {
+    return {
+      enabled: false,
+      agent: null,
+      agentHooksInstalled: 0,
+      gitHooksInstalled: 0,
+      errors: ['Not a git repository'],
+    };
+  }
+
+  // Validate repository has at least one commit
+  try {
+    await getHead(cwd);
+  } catch {
+    return {
+      enabled: false,
+      agent: null,
+      agentHooksInstalled: 0,
+      gitHooksInstalled: 0,
+      errors: ['Repository has no commits'],
+    };
+  }
+
+  const root = await getWorktreeRoot(cwd);
+
+  // Detect or resolve agent
+  const agent = options.agent ? getAgent(options.agent) : await detectAgent(cwd);
+
+  if (!agent) {
+    errors.push(
+      `No agent detected. Available agents: ${listAgentNames().join(', ')}. ` +
+        `Install an agent or specify one with --agent.`,
+    );
+  }
+
+  // Create directories
+  await createDirectories(root, cwd);
+
+  // Save settings
+  const settings: Partial<SessionlogSettings> = {
+    enabled: true,
+    strategy: 'manual-commit',
+  };
+
+  if (options.skipPushSessions !== undefined) {
+    settings.skipPushSessions = options.skipPushSessions;
+  }
+
+  if (options.telemetry !== undefined) {
+    settings.telemetryEnabled = options.telemetry;
+  }
+
+  if (options.sessionRepoPath) {
+    settings.sessionRepoPath = options.sessionRepoPath;
+  }
+
+  if (options.local) {
+    await saveLocalSettings(settings, cwd);
+  } else {
+    await saveProjectSettings(settings, cwd);
+  }
+
+  // Initialize separate session repo if configured
+  if (options.sessionRepoPath) {
+    try {
+      const resolved = resolveSessionRepoPath(options.sessionRepoPath, root);
+      await initSessionRepo(resolved);
+    } catch (e) {
+      errors.push(
+        `Failed to initialize session repo: ${e instanceof Error ? e.message : String(e)}`,
+      );
+    }
+  }
+
+  // Set up .gitignore for local files
+  await ensureGitignore(cwd);
+
+  // Install git hooks
+  let gitHooksInstalled = 0;
+  try {
+    gitHooksInstalled = await installGitHooks(root);
+  } catch (e) {
+    errors.push(`Failed to install git hooks: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  // Install agent hooks
+  let agentHooksInstalled = 0;
+  if (agent && hasHookSupport(agent)) {
+    try {
+      agentHooksInstalled = await agent.installHooks(root, options.force);
+    } catch (e) {
+      errors.push(`Failed to install agent hooks: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  return {
+    enabled: true,
+    agent: agent?.name ?? null,
+    agentHooksInstalled,
+    gitHooksInstalled,
+    errors,
+  };
+}
+
+async function createDirectories(root: string, cwd: string): Promise<void> {
+  const sessionlogDir = resolveSessionlogDir(root);
+  const dirs = [
+    sessionlogDir,
+    path.join(sessionlogDir, 'metadata'),
+    path.join(sessionlogDir, 'tmp'),
+  ];
+
+  // Also create .git/sessionlog-sessions/
+  try {
+    const gitDir = await getGitDir(cwd);
+    const sessionsDir = path.resolve(root, gitDir, SESSION_DIR_NAME);
+    dirs.push(sessionsDir);
+  } catch {
+    // Ignore if git dir resolution fails
+  }
+
+  for (const dir of dirs) {
+    await fs.promises.mkdir(dir, { recursive: true });
+  }
+}