cognitive-core 0.2.1 → 0.2.2

package/references/sessionlog/src/utils/tree-ops.ts

@@ -1,219 +0,0 @@
-/**
- * Git Tree Manipulation
- *
- * Structured tree operations for building and modifying git tree objects.
- * Provides higher-level abstractions over raw `git mktree` / `git ls-tree`.
- *
- * Ported from Go: checkpoint/parse_tree.go
- */
-
-import { lsTree, mktree, hashObject } from '../git-operations.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface TreeEntry {
-  mode: string;
-  type: string;
-  hash: string;
-  name: string;
-}
-
-export const enum MergeMode {
-  /** Replace the entire subtree at the target path */
-  ReplaceAll = 0,
-  /** Merge into existing subtree, keeping existing entries */
-  MergeKeepExisting = 1,
-}
-
-export interface TreeChange {
-  path: string;
-  mode: string;
-  hash: string;
-  deleted?: boolean;
-}
-
-// ============================================================================
-// Tree Operations
-// ============================================================================
-
-/**
- * Update (or create) a subtree at a given path within a root tree.
- *
- * @param rootTree - The root tree hash (or empty string for a new tree)
- * @param subtreePath - The path to the subtree (e.g., "a3/b2c4d5e6f7")
- * @param newSubtreeHash - The hash of the new subtree to place at path
- * @param mergeMode - How to handle existing entries at the path
- * @param cwd - Working directory for git commands
- */
-export async function updateSubtree(
-  rootTree: string,
-  subtreePath: string,
-  newSubtreeHash: string,
-  mergeMode: MergeMode = MergeMode.ReplaceAll,
-  cwd?: string,
-): Promise<string> {
-  const parts = subtreePath.split('/').filter(Boolean);
-  if (parts.length === 0) return newSubtreeHash;
-
-  // Walk the tree path, collecting existing entries at each level
-  return updateSubtreeRecursive(rootTree, parts, 0, newSubtreeHash, mergeMode, cwd);
-}
-
-async function updateSubtreeRecursive(
-  currentTree: string,
-  pathParts: string[],
-  depth: number,
-  newSubtreeHash: string,
-  mergeMode: MergeMode,
-  cwd?: string,
-): Promise<string> {
-  const targetName = pathParts[depth];
-  const isLeaf = depth === pathParts.length - 1;
-
-  // Get existing entries at this tree level
-  let existingEntries: TreeEntry[] = [];
-  if (currentTree) {
-    try {
-      existingEntries = await lsTree(currentTree, undefined, cwd);
-    } catch {
-      // Tree doesn't exist or is empty
-    }
-  }
-
-  if (isLeaf) {
-    let finalHash = newSubtreeHash;
-
-    // If merge mode, combine existing and new entries
-    if (mergeMode === MergeMode.MergeKeepExisting) {
-      const existingEntry = existingEntries.find((e) => e.name === targetName);
-      if (existingEntry && existingEntry.type === 'tree') {
-        finalHash = await mergeTreesKeepExisting(existingEntry.hash, newSubtreeHash, cwd);
-      }
-    }
-
-    // Replace or add the entry at this level
-    const filtered = existingEntries.filter((e) => e.name !== targetName);
-    filtered.push({
-      mode: '040000',
-      type: 'tree',
-      hash: finalHash,
-      name: targetName,
-    });
-
-    return mktree(filtered, cwd);
-  }
-
-  // Intermediate level: find or create the subtree
-  const existingEntry = existingEntries.find((e) => e.name === targetName);
-  const childTree = existingEntry?.hash ?? '';
-
-  const updatedChildHash = await updateSubtreeRecursive(
-    childTree,
-    pathParts,
-    depth + 1,
-    newSubtreeHash,
-    mergeMode,
-    cwd,
-  );
-
-  const filtered = existingEntries.filter((e) => e.name !== targetName);
-  filtered.push({
-    mode: '040000',
-    type: 'tree',
-    hash: updatedChildHash,
-    name: targetName,
-  });
-
-  return mktree(filtered, cwd);
-}
-
-/**
- * Merge two trees, keeping existing entries when conflicts arise.
- */
-async function mergeTreesKeepExisting(
-  existingTreeHash: string,
-  newTreeHash: string,
-  cwd?: string,
-): Promise<string> {
-  const existingEntries = await lsTree(existingTreeHash, undefined, cwd);
-  const newEntries = await lsTree(newTreeHash, undefined, cwd);
-
-  const existingNames = new Set(existingEntries.map((e) => e.name));
-  const merged = [...existingEntries];
-
-  for (const entry of newEntries) {
-    if (!existingNames.has(entry.name)) {
-      merged.push(entry);
-    }
-  }
-
-  return mktree(merged, cwd);
-}
-
-/**
- * Apply a batch of file-level changes to a tree.
- * Returns the hash of the new root tree.
- */
-export async function applyTreeChanges(
-  rootTree: string,
-  changes: TreeChange[],
-  cwd?: string,
-): Promise<string> {
-  if (changes.length === 0) return rootTree;
-
-  // Get existing entries
-  let entries: TreeEntry[] = [];
-  if (rootTree) {
-    try {
-      entries = await lsTree(rootTree, undefined, cwd);
-    } catch {
-      // Empty tree
-    }
-  }
-
-  for (const change of changes) {
-    if (change.deleted) {
-      entries = entries.filter((e) => e.name !== change.path);
-    } else {
-      const existing = entries.findIndex((e) => e.name === change.path);
-      const entry: TreeEntry = {
-        mode: change.mode,
-        type: change.mode === '040000' ? 'tree' : 'blob',
-        hash: change.hash,
-        name: change.path,
-      };
-      if (existing >= 0) {
-        entries[existing] = entry;
-      } else {
-        entries.push(entry);
-      }
-    }
-  }
-
-  return mktree(entries, cwd);
-}
-
-/**
- * Create a tree from a map of file paths to content strings.
- * Useful for building trees from scratch in tests.
- */
-export async function createTreeFromMap(
-  files: Record<string, string>,
-  cwd?: string,
-): Promise<string> {
-  const entries: TreeEntry[] = [];
-
-  for (const [name, content] of Object.entries(files)) {
-    const hash = await hashObject(content, cwd);
-    entries.push({
-      mode: '100644',
-      type: 'blob',
-      hash,
-      name,
-    });
-  }
-
-  return mktree(entries, cwd);
-}

package/references/sessionlog/src/utils/tty.ts

@@ -1,72 +0,0 @@
-/**
- * TTY Interaction Helpers
- *
- * Utilities for detecting and interacting with a controlling terminal.
- * Important for git hooks which need user confirmation even when stdin
- * is redirected.
- *
- * Ported from Go: strategy/manual_commit_hooks.go
- */
-
-import * as fs from 'node:fs';
-import * as readline from 'node:readline';
-
-/**
- * Detect if a controlling terminal (TTY) is available.
- *
- * Respects environment variables:
- * - `SESSIONLOG_TEST_TTY=1` forces TTY detection to true (for testing)
- * - `GEMINI_CLI=1` forces TTY detection to false (Gemini runs non-interactively)
- */
-export function hasTTY(): boolean {
-  // Check environment overrides
-  if (process.env.SESSIONLOG_TEST_TTY === '1') return true;
-  if (process.env.GEMINI_CLI === '1') return false;
-
-  // Try opening /dev/tty — this works even when stdin is redirected
-  try {
-    const fd = fs.openSync('/dev/tty', 'r');
-    fs.closeSync(fd);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Prompt the user for yes/no confirmation via /dev/tty.
- *
- * This works even when stdin is redirected (important for git hooks).
- * Returns false if no TTY is available or the user declines.
- */
-export async function askConfirmTTY(prompt: string): Promise<boolean> {
-  if (!hasTTY()) return false;
-
-  let ttyIn: fs.ReadStream | undefined;
-  let ttyOut: fs.WriteStream | undefined;
-
-  try {
-    ttyIn = fs.createReadStream('/dev/tty');
-    ttyOut = fs.createWriteStream('/dev/tty');
-
-    const rl = readline.createInterface({
-      input: ttyIn,
-      output: ttyOut,
-    });
-
-    const result = await new Promise<boolean>((resolve) => {
-      rl.question(`${prompt} [y/N] `, (answer) => {
-        rl.close();
-        const normalized = answer.trim().toLowerCase();
-        resolve(normalized === 'y' || normalized === 'yes');
-      });
-    });
-
-    return result;
-  } catch {
-    return false;
-  } finally {
-    ttyIn?.destroy();
-    ttyOut?.destroy();
-  }
-}

package/references/sessionlog/src/utils/validation.ts

@@ -1,65 +0,0 @@
-/**
- * Input Validation
- *
- * Validates user-supplied IDs to prevent path traversal attacks when
- * IDs are used to construct file paths (session state, metadata, etc.).
- *
- * This module has no dependencies to avoid import cycles.
- */
-
-/** Matches alphanumeric characters, underscores, and hyphens only. */
-const pathSafeRegex = /^[a-zA-Z0-9_-]+$/;
-
-/**
- * Validate that a session ID doesn't contain path separators.
- * Prevents path traversal when session IDs are used in file paths.
- */
-export function validateSessionID(id: string): void {
-  if (!id) {
-    throw new Error('session ID cannot be empty');
-  }
-  if (id.includes('/') || id.includes('\\')) {
-    throw new Error(`invalid session ID "${id}": contains path separators`);
-  }
-}
-
-/**
- * Validate that a tool use ID contains only safe characters for paths.
- * Tool use IDs can be UUIDs or prefixed identifiers like "toolu_xxx".
- * Empty is allowed (optional field).
- */
-export function validateToolUseID(id: string): void {
-  if (!id) return;
-  if (!pathSafeRegex.test(id)) {
-    throw new Error(
-      `invalid tool use ID "${id}": must be alphanumeric with underscores/hyphens only`,
-    );
-  }
-}
-
-/**
- * Validate that an agent ID contains only safe characters for paths.
- * Empty is allowed (optional field).
- */
-export function validateAgentID(id: string): void {
-  if (!id) return;
-  if (!pathSafeRegex.test(id)) {
-    throw new Error(`invalid agent ID "${id}": must be alphanumeric with underscores/hyphens only`);
-  }
-}
-
-/**
- * Validate that an agent session ID contains only safe characters for paths.
- * Agent session IDs can be UUIDs (Claude Code), test identifiers, or other
- * formats depending on the agent.
- */
-export function validateAgentSessionID(id: string): void {
-  if (!id) {
-    throw new Error('agent session ID cannot be empty');
-  }
-  if (!pathSafeRegex.test(id)) {
-    throw new Error(
-      `invalid agent session ID "${id}": must be alphanumeric with underscores/hyphens only`,
-    );
-  }
-}

package/references/sessionlog/src/utils/worktree.ts

@@ -1,58 +0,0 @@
-/**
- * Git Worktree Utilities
- *
- * Provides detection and identification of git worktrees.
- * Linked worktrees have `.git` as a file pointing to the main repository,
- * while the main worktree has `.git` as a directory.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-
-/**
- * Get the internal git worktree identifier for the given path.
- *
- * - For the main worktree (where .git is a directory), returns empty string.
- * - For linked worktrees (where .git is a file), extracts the name from
- *   `.git/worktrees/<name>/` path. This name is stable across `git worktree move`.
- */
-export async function getWorktreeID(worktreePath: string): Promise<string> {
-  const gitPath = path.join(worktreePath, '.git');
-
-  let stat: fs.Stats;
-  try {
-    stat = await fs.promises.stat(gitPath);
-  } catch {
-    throw new Error(`failed to stat .git: ${gitPath}`);
-  }
-
-  // Main worktree has .git as a directory
-  if (stat.isDirectory()) {
-    return '';
-  }
-
-  // Linked worktree has .git as a file with content: "gitdir: /path/to/.git/worktrees/<name>"
-  const content = await fs.promises.readFile(gitPath, 'utf-8');
-  const line = content.trim();
-
-  if (!line.startsWith('gitdir: ')) {
-    throw new Error(`invalid .git file format: ${line}`);
-  }
-
-  const gitdir = line.slice('gitdir: '.length);
-
-  // Extract worktree name from path like /repo/.git/worktrees/<name>
-  const marker = '.git/worktrees/';
-  const idx = gitdir.indexOf(marker);
-  if (idx === -1) {
-    throw new Error(`unexpected gitdir format (no worktrees): ${gitdir}`);
-  }
-
-  let worktreeID = gitdir.slice(idx + marker.length);
-  // Remove trailing slashes if any
-  if (worktreeID.endsWith('/')) {
-    worktreeID = worktreeID.slice(0, -1);
-  }
-
-  return worktreeID;
-}

package/references/sessionlog/src/wire-types.ts

@@ -1,59 +0,0 @@
-/**
- * Wire Format Types
- *
- * Snake_case types describing how sessionlog checkpoint data is formatted
- * for external consumption over wire protocols (e.g., MAP trajectory sync).
- *
- * These are the canonical wire-format definitions. External systems
- * (e.g., OpenHive hub) import these to construct properly-typed messages.
- */
-
-/** Token usage stats for a checkpoint (wire format) */
-export interface SessionSyncTokenUsage {
-  input_tokens: number;
-  output_tokens: number;
-  cache_creation_tokens: number;
-  cache_read_tokens: number;
-  api_call_count: number;
-}
-
-/** AI-generated session summary (wire format) */
-export interface SessionSyncSummary {
-  intent: string;
-  outcome: string;
-  learnings?: {
-    repo: string[];
-    workflow: string[];
-  };
-  friction?: string[];
-  open_items?: string[];
-}
-
-/** Attribution stats for agent vs human contributions (wire format) */
-export interface SessionSyncAttribution {
-  agent_lines: number;
-  human_added: number;
-  agent_percentage: number;
-}
-
-/** Inline checkpoint metadata for session sync notifications (wire format) */
-export interface SessionSyncCheckpoint {
-  /** 12-char hex checkpoint ID */
-  id: string;
-  /** Sessionlog session ID */
-  session_id: string;
-  /** Agent type (e.g., "Claude Code", "Cursor IDE") */
-  agent: string;
-  /** Git branch the checkpoint was created on */
-  branch?: string;
-  /** Files modified in this checkpoint */
-  files_touched: string[];
-  /** Number of temporary checkpoints before this commit */
-  checkpoints_count: number;
-  /** Token usage for this checkpoint */
-  token_usage?: SessionSyncTokenUsage;
-  /** AI-generated summary of the session */
-  summary?: SessionSyncSummary;
-  /** Agent vs human contribution attribution */
-  attribution?: SessionSyncAttribution;
-}

package/references/sessionlog/templates/setup-env.sh

@@ -1,153 +0,0 @@
-#!/bin/sh
-# Sessionlog setup script for Claude Code Web (ccweb)
-#
-# This script is executed as a SessionStart hook in Claude Code Web sessions.
-# It installs the sessionlog CLI, enables it for the current repo, and
-# configures GitHub direct-push access for session/checkpoint branches.
-#
-# Generated by: sessionlog setup-ccweb
-set -e
-
-# Only run in remote Claude Code environments
-if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
-  exit 0
-fi
-
-# ============================================================================
-# Configuration
-# ============================================================================
-
-# Branch prefixes allowed for direct push (space-separated).
-# Edit this to allow additional prefixes beyond sessionlog's defaults.
-ALLOWED_PUSH_PREFIXES="sessionlog/ claude/"
-
-# ============================================================================
-# Install sessionlog CLI
-# ============================================================================
-
-if ! command -v sessionlog >/dev/null 2>&1; then
-  echo "[sessionlog-ccweb] Installing sessionlog CLI..."
-  npm install -g sessionlog 2>/dev/null || {
-    echo "[sessionlog-ccweb] Warning: Failed to install sessionlog globally, trying npx..."
-  }
-fi
-
-# ============================================================================
-# Enable sessionlog for this repository
-# ============================================================================
-
-if command -v sessionlog >/dev/null 2>&1; then
-  # Enable with Claude Code agent (idempotent)
-  sessionlog enable --agent claude-code --local 2>/dev/null || true
-  echo "[sessionlog-ccweb] Sessionlog enabled."
-else
-  echo "[sessionlog-ccweb] Warning: sessionlog not found. Skipping enable."
-fi
-
-# ============================================================================
-# Configure GitHub direct-push access
-# ============================================================================
-
-# The ccweb proxy only allows pushing to the current working branch.
-# We need direct GitHub access to push sessionlog shadow branches.
-
-if [ -n "$GITHUB_TOKEN" ]; then
-  # Get the remote URL and extract owner/repo
-  REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
-
-  if [ -n "$REMOTE_URL" ]; then
-    # Extract owner/repo from various URL formats
-    OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's#.*github\.com[:/]([^/]+/[^/.]+)(\.git)?$#\1#')
-
-    if [ -n "$OWNER_REPO" ]; then
-      # Configure git to push directly to GitHub (bypassing ccweb proxy)
-      DIRECT_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${OWNER_REPO}.git"
-      git remote set-url --push origin "$DIRECT_URL" 2>/dev/null || true
-      echo "[sessionlog-ccweb] Configured direct GitHub push access."
-    fi
-  fi
-else
-  echo "[sessionlog-ccweb] Warning: GITHUB_TOKEN not set. Session push will be limited."
-fi
-
-# ============================================================================
-# Install pre-push branch filter
-# ============================================================================
-
-# Restrict direct pushes to only allowed prefixes and the current working branch.
-# This prevents accidental pushes to other branches via the direct GitHub URL.
-
-HOOKS_DIR="$(git rev-parse --git-dir)/hooks"
-PRE_PUSH_HOOK="$HOOKS_DIR/pre-push"
-
-install_push_filter() {
-  mkdir -p "$HOOKS_DIR"
-
-  # Check if pre-push hook already exists
-  if [ -f "$PRE_PUSH_HOOK" ]; then
-    # Check if our filter is already installed
-    if grep -q "sessionlog-ccweb-push-filter" "$PRE_PUSH_HOOK" 2>/dev/null; then
-      return
-    fi
-
-    # Append to existing hook
-    cat >> "$PRE_PUSH_HOOK" << 'HOOKEOF'
-
-# sessionlog-ccweb-push-filter
-CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
-while read local_ref local_sha remote_ref remote_sha; do
-  BRANCH_NAME=$(echo "$remote_ref" | sed 's#refs/heads/##')
-  # Allow current working branch
-  if [ "$BRANCH_NAME" = "$CURRENT_BRANCH" ]; then
-    continue
-  fi
-  # Check allowed prefixes
-  ALLOWED=false
-  for prefix in ALLOWED_PUSH_PREFIXES_PLACEHOLDER; do
-    case "$BRANCH_NAME" in
-      "$prefix"*) ALLOWED=true; break ;;
-    esac
-  done
-  if [ "$ALLOWED" = "false" ]; then
-    echo "[sessionlog-ccweb] Blocked push to '$BRANCH_NAME' (not in allowed prefixes)"
-    exit 1
-  fi
-done
-HOOKEOF
-  else
-    # Create new hook
-    cat > "$PRE_PUSH_HOOK" << 'HOOKEOF'
-#!/bin/sh
-# sessionlog-ccweb-push-filter
-CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
-while read local_ref local_sha remote_ref remote_sha; do
-  BRANCH_NAME=$(echo "$remote_ref" | sed 's#refs/heads/##')
-  # Allow current working branch
-  if [ "$BRANCH_NAME" = "$CURRENT_BRANCH" ]; then
-    continue
-  fi
-  # Check allowed prefixes
-  ALLOWED=false
-  for prefix in ALLOWED_PUSH_PREFIXES_PLACEHOLDER; do
-    case "$BRANCH_NAME" in
-      "$prefix"*) ALLOWED=true; break ;;
-    esac
-  done
-  if [ "$ALLOWED" = "false" ]; then
-    echo "[sessionlog-ccweb] Blocked push to '$BRANCH_NAME' (not in allowed prefixes)"
-    exit 1
-  fi
-done
-HOOKEOF
-  fi
-
-  chmod +x "$PRE_PUSH_HOOK"
-}
-
-# Replace placeholder with actual prefixes and install
-install_push_filter
-if [ -f "$PRE_PUSH_HOOK" ]; then
-  sed -i "s/ALLOWED_PUSH_PREFIXES_PLACEHOLDER/$ALLOWED_PUSH_PREFIXES/g" "$PRE_PUSH_HOOK"
-fi
-
-echo "[sessionlog-ccweb] Setup complete."

package/references/sessionlog/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "src/**/__tests__"]
-}

package/references/sessionlog/vitest.config.ts

@@ -1,12 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    include: ['src/**/*.test.ts'],
-    watch: false,
-    testTimeout: 5000,
-    hookTimeout: 10000,
-  },
-});

package/references/skill-tree/.claude/settings.json

@@ -1,6 +0,0 @@
-{
-    "attribution": {
-    "commit": "",
-    "pr": ""
-  }
-}