Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: add TypeScript declaration files for all core libraries

Affaan Mustafabe0ba0cabc9c
diff --git a/scripts/lib/package-manager.d.ts b/scripts/lib/package-manager.d.ts
new file mode 100644
index 000000000..ecfa78a61
--- /dev/null
+++ b/scripts/lib/package-manager.d.ts
@@ -0,0 +1,119 @@
+/**
+ * Package Manager Detection and Selection.
+ * Supports: npm, pnpm, yarn, bun.
+ */
+
+/** Supported package manager names */
+export type PackageManagerName = 'npm' | 'pnpm' | 'yarn' | 'bun';
+
+/** Configuration for a single package manager */
+export interface PackageManagerConfig {
+ name: PackageManagerName;
+ /** Lock file name (e.g., "package-lock.json", "pnpm-lock.yaml") */
+ lockFile: string;
+ /** Install command (e.g., "npm install") */
+ installCmd: string;
+ /** Run script command prefix (e.g., "npm run", "pnpm") */
+ runCmd: string;
+ /** Execute binary command (e.g., "npx", "pnpm dlx") */
+ execCmd: string;
+ /** Test command (e.g., "npm test") */
+ testCmd: string;
+ /** Build command (e.g., "npm run build") */
+ buildCmd: string;
+ /** Dev server command (e.g., "npm run dev") */
+ devCmd: string;
+}
+
+/** How the package manager was detected */
+export type DetectionSource =
+ | 'environment'
+ | 'project-config'
+ | 'package.json'
+ | 'lock-file'
+ | 'global-config'
+ | 'default';
+
+/** Result from getPackageManager() */
+export interface PackageManagerResult {
+ name: PackageManagerName;
+ config: PackageManagerConfig;
+ source: DetectionSource;
+}
+
+/** Map of all supported package managers keyed by name */
+export const PACKAGE_MANAGERS: Record<PackageManagerName, PackageManagerConfig>;
+
+/** Priority order for lock file detection */
+export const DETECTION_PRIORITY: PackageManagerName[];
+
+export interface GetPackageManagerOptions {
+ /** Project directory to detect from (default: process.cwd()) */
+ projectDir?: string;
+}
+
+/**
+ * Get the package manager to use for the current project.
+ *
+ * Detection priority:
+ * 1. CLAUDE_PACKAGE_MANAGER environment variable
+ * 2. Project-specific config (.claude/package-manager.json)
+ * 3. package.json `packageManager` field
+ * 4. Lock file detection
+ * 5. Global user preference (~/.claude/package-manager.json)
+ * 6. Default to npm (no child processes spawned)
+ */
+export function getPackageManager(options?: GetPackageManagerOptions): PackageManagerResult;
+
+/**
+ * Set the user's globally preferred package manager.
+ * Saves to ~/.claude/package-manager.json.
+ * @throws If pmName is not a known package manager
+ */
+export function setPreferredPackageManager(pmName: PackageManagerName): { packageManager: string; setAt: string };
+
+/**
+ * Set a project-specific preferred package manager.
+ * Saves to <projectDir>/.claude/package-manager.json.
+ * @throws If pmName is not a known package manager
+ */
+export function setProjectPackageManager(pmName: PackageManagerName, projectDir?: string): { packageManager: string; setAt: string };
+
+/**
+ * Get package managers installed on the system.
+ * WARNING: Spawns child processes for each PM check.
+ * Do NOT call during session startup hooks.
+ */
+export function getAvailablePackageManagers(): PackageManagerName[];
+
+/** Detect package manager from lock file in the given directory */
+export function detectFromLockFile(projectDir?: string): PackageManagerName | null;
+
+/** Detect package manager from package.json `packageManager` field */
+export function detectFromPackageJson(projectDir?: string): PackageManagerName | null;
+
+/**
+ * Get the full command string to run a script.
+ * @param script - Script name: "install", "test", "build", "dev", or custom
+ */
+export function getRunCommand(script: string, options?: GetPackageManagerOptions): string;
+
+/**
+ * Get the full command string to execute a package binary.
+ * @param binary - Binary name (e.g., "prettier", "eslint")
+ * @param args - Arguments to pass to the binary
+ */
+export function getExecCommand(binary: string, args?: string, options?: GetPackageManagerOptions): string;
+
+/**
+ * Get a message prompting the user to configure their package manager.
+ * Does NOT spawn child processes.
+ */
+export function getSelectionPrompt(): string;
+
+/**
+ * Generate a regex pattern string that matches commands for all package managers.
+ * @param action - Action like "dev", "install", "test", "build", or custom
+ * @returns Parenthesized alternation regex string, e.g., "(npm run dev|pnpm( run)? dev|...)"
+ */
+export function getCommandPattern(action: string): string;
diff --git a/scripts/lib/session-aliases.d.ts b/scripts/lib/session-aliases.d.ts
new file mode 100644
index 000000000..8c26cd385
--- /dev/null
+++ b/scripts/lib/session-aliases.d.ts
@@ -0,0 +1,136 @@
+/**
+ * Session Aliases Library for Claude Code.
+ * Manages named aliases for session files, stored in ~/.claude/session-aliases.json.
+ */
+
+/** Internal alias storage entry */
+export interface AliasEntry {
+ sessionPath: string;
+ createdAt: string;
+ updatedAt?: string;
+ title: string | null;
+}
+
+/** Alias data structure stored on disk */
+export interface AliasStore {
+ version: string;
+ aliases: Record<string, AliasEntry>;
+ metadata: {
+ totalCount: number;
+ lastUpdated: string;
+ };
+}
+
+/** Resolved alias information returned by resolveAlias */
+export interface ResolvedAlias {
+ alias: string;
+ sessionPath: string;
+ createdAt: string;
+ title: string | null;
+}
+
+/** Alias entry returned by listAliases */
+export interface AliasListItem {
+ name: string;
+ sessionPath: string;
+ createdAt: string;
+ updatedAt?: string;
+ title: string | null;
+}
+
+/** Result from mutation operations (set, delete, rename, update, cleanup) */
+export interface AliasResult {
+ success: boolean;
+ error?: string;
+ [key: string]: unknown;
+}
+
+export interface SetAliasResult extends AliasResult {
+ isNew?: boolean;
+ alias?: string;
+ sessionPath?: string;
+ title?: string | null;
+}
+
+export interface DeleteAliasResult extends AliasResult {
+ alias?: string;
+ deletedSessionPath?: string;
+}
+
+export interface RenameAliasResult extends AliasResult {
+ oldAlias?: string;
+ newAlias?: string;
+ sessionPath?: string;
+}
+
+export interface CleanupResult {
+ totalChecked: number;
+ removed: number;
+ removedAliases: Array<{ name: string; sessionPath: string }>;
+ error?: string;
+}
+
+export interface ListAliasesOptions {
+ /** Filter aliases by name or title (partial match, case-insensitive) */
+ search?: string | null;
+ /** Maximum number of aliases to return */
+ limit?: number | null;
+}
+
+/** Get the path to the aliases JSON file */
+export function getAliasesPath(): string;
+
+/** Load all aliases from disk. Returns default structure if file doesn't exist. */
+export function loadAliases(): AliasStore;
+
+/**
+ * Save aliases to disk with atomic write (temp file + rename).
+ * Creates backup before writing; restores on failure.
+ */
+export function saveAliases(aliases: AliasStore): boolean;
+
+/**
+ * Resolve an alias name to its session data.
+ * @returns Alias data, or null if not found or invalid name
+ */
+export function resolveAlias(alias: string): ResolvedAlias | null;
+
+/**
+ * Create or update an alias for a session.
+ * Alias names must be alphanumeric with dashes/underscores.
+ * Reserved names (list, help, remove, delete, create, set) are rejected.
+ */
+export function setAlias(alias: string, sessionPath: string, title?: string | null): SetAliasResult;
+
+/**
+ * List all aliases, optionally filtered and limited.
+ * Results are sorted by updated time (newest first).
+ */
+export function listAliases(options?: ListAliasesOptions): AliasListItem[];
+
+/** Delete an alias by name */
+export function deleteAlias(alias: string): DeleteAliasResult;
+
+/**
+ * Rename an alias. Fails if old alias doesn't exist or new alias already exists.
+ * New alias name must be alphanumeric with dashes/underscores.
+ */
+export function renameAlias(oldAlias: string, newAlias: string): RenameAliasResult;
+
+/**
+ * Resolve an alias or pass through a session path.
+ * First tries to resolve as alias; if not found, returns the input as-is.
+ */
+export function resolveSessionAlias(aliasOrId: string): string;
+
+/** Update the title of an existing alias */
+export function updateAliasTitle(alias: string, title: string): AliasResult;
+
+/** Get all aliases that point to a specific session path */
+export function getAliasesForSession(sessionPath: string): Array<{ name: string; createdAt: string; title: string | null }>;
+
+/**
+ * Remove aliases whose sessions no longer exist.
+ * @param sessionExists - Function that returns true if a session path is valid
+ */
+export function cleanupAliases(sessionExists: (sessionPath: string) => boolean): CleanupResult;
diff --git a/scripts/lib/session-manager.d.ts b/scripts/lib/session-manager.d.ts
new file mode 100644
index 000000000..31e903b12
--- /dev/null
+++ b/scripts/lib/session-manager.d.ts
@@ -0,0 +1,130 @@
+/**
+ * Session Manager Library for Claude Code.
+ * Provides CRUD operations for session files stored as markdown in ~/.claude/sessions/.
+ */
+
+/** Parsed metadata from a session filename */
+export interface SessionFilenameMeta {
+ /** Original filename */
+ filename: string;
+ /** Short ID extracted from filename, or "no-id" for old format */
+ shortId: string;
+ /** Date string in YYYY-MM-DD format */
+ date: string;
+ /** Parsed Date object from the date string */
+ datetime: Date;
+}
+
+/** Metadata parsed from session markdown content */
+export interface SessionMetadata {
+ title: string | null;
+ date: string | null;
+ started: string | null;
+ lastUpdated: string | null;
+ completed: string[];
+ inProgress: string[];
+ notes: string;
+ context: string;
+}
+
+/** Statistics computed from session content */
+export interface SessionStats {
+ totalItems: number;
+ completedItems: number;
+ inProgressItems: number;
+ lineCount: number;
+ hasNotes: boolean;
+ hasContext: boolean;
+}
+
+/** A session object returned by getAllSessions and getSessionById */
+export interface Session extends SessionFilenameMeta {
+ /** Full filesystem path to the session file */
+ sessionPath: string;
+ /** Whether the file has any content */
+ hasContent?: boolean;
+ /** File size in bytes */
+ size: number;
+ /** Last modification time */
+ modifiedTime: Date;
+ /** File creation time (falls back to ctime on Linux) */
+ createdTime: Date;
+ /** Session markdown content (only when includeContent=true) */
+ content?: string | null;
+ /** Parsed metadata (only when includeContent=true) */
+ metadata?: SessionMetadata;
+ /** Session statistics (only when includeContent=true) */
+ stats?: SessionStats;
+}
+
+/** Pagination result from getAllSessions */
+export interface SessionListResult {
+ sessions: Session[];
+ total: number;
+ offset: number;
+ limit: number;
+ hasMore: boolean;
+}
+
+export interface GetAllSessionsOptions {
+ /** Maximum number of sessions to return (default: 50) */
+ limit?: number;
+ /** Number of sessions to skip (default: 0) */
+ offset?: number;
+ /** Filter by date in YYYY-MM-DD format */
+ date?: string | null;
+ /** Search in short ID */
+ search?: string | null;
+}
+
+/**
+ * Parse a session filename to extract date and short ID.
+ * @returns Parsed metadata, or null if the filename doesn't match the expected pattern
+ */
+export function parseSessionFilename(filename: string): SessionFilenameMeta | null;
+
+/** Get the full filesystem path for a session filename */
+export function getSessionPath(filename: string): string;
+
+/**
+ * Read session markdown content from disk.
+ * @returns Content string, or null if the file doesn't exist
+ */
+export function getSessionContent(sessionPath: string): string | null;
+
+/** Parse session metadata from markdown content */
+export function parseSessionMetadata(content: string | null): SessionMetadata;
+
+/**
+ * Calculate statistics for a session.
+ * Accepts either a file path (ending in .tmp) or pre-read content string.
+ */
+export function getSessionStats(sessionPathOrContent: string): SessionStats;
+
+/** Get the title from a session file, or "Untitled Session" if none */
+export function getSessionTitle(sessionPath: string): string;
+
+/** Get human-readable file size (e.g., "1.2 KB") */
+export function getSessionSize(sessionPath: string): string;
+
+/** Get all sessions with optional filtering and pagination */
+export function getAllSessions(options?: GetAllSessionsOptions): SessionListResult;
+
+/**
+ * Find a session by short ID or filename.
+ * @param sessionId - Short ID prefix, full filename, or filename without .tmp
+ * @param includeContent - Whether to read and parse the session content
+ */
+export function getSessionById(sessionId: string, includeContent?: boolean): Session | null;
+
+/** Write markdown content to a session file */
+export function writeSessionContent(sessionPath: string, content: string): boolean;
+
+/** Append content to an existing session file */
+export function appendSessionContent(sessionPath: string, content: string): boolean;
+
+/** Delete a session file */
+export function deleteSession(sessionPath: string): boolean;
+
+/** Check if a session file exists and is a regular file */
+export function sessionExists(sessionPath: string): boolean;
diff --git a/scripts/lib/utils.d.ts b/scripts/lib/utils.d.ts
new file mode 100644
index 000000000..7c5a0b188
--- /dev/null
+++ b/scripts/lib/utils.d.ts
@@ -0,0 +1,169 @@
+/**
+ * Cross-platform utility functions for Claude Code hooks and scripts.
+ * Works on Windows, macOS, and Linux.
+ */
+
+import type { ExecSyncOptions } from 'child_process';
+
+// Platform detection
+export const isWindows: boolean;
+export const isMacOS: boolean;
+export const isLinux: boolean;
+
+// --- Directories ---
+
+/** Get the user's home directory (cross-platform) */
+export function getHomeDir(): string;
+
+/** Get the Claude config directory (~/.claude) */
+export function getClaudeDir(): string;
+
+/** Get the sessions directory (~/.claude/sessions) */
+export function getSessionsDir(): string;
+
+/** Get the learned skills directory (~/.claude/skills/learned) */
+export function getLearnedSkillsDir(): string;
+
+/** Get the temp directory (cross-platform) */
+export function getTempDir(): string;
+
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ * Handles EEXIST race conditions from concurrent creation.
+ * @throws If directory cannot be created (e.g., permission denied)
+ */
+export function ensureDir(dirPath: string): string;
+
+// --- Date/Time ---
+
+/** Get current date in YYYY-MM-DD format */
+export function getDateString(): string;
+
+/** Get current time in HH:MM format */
+export function getTimeString(): string;
+
+/** Get current datetime in YYYY-MM-DD HH:MM:SS format */
+export function getDateTimeString(): string;
+
+// --- Session/Project ---
+
+/**
+ * Get short session ID from CLAUDE_SESSION_ID environment variable.
+ * Returns last 8 characters, falls back to project name then the provided fallback.
+ */
+export function getSessionIdShort(fallback?: string): string;
+
+/** Get the git repository name from the current working directory */
+export function getGitRepoName(): string | null;
+
+/** Get project name from git repo or current directory basename */
+export function getProjectName(): string | null;
+
+// --- File operations ---
+
+export interface FileMatch {
+ /** Absolute path to the matching file */
+ path: string;
+ /** Modification time in milliseconds since epoch */
+ mtime: number;
+}
+
+export interface FindFilesOptions {
+ /** Maximum age in days. Only files modified within this many days are returned. */
+ maxAge?: number | null;
+ /** Whether to search subdirectories recursively */
+ recursive?: boolean;
+}
+
+/**
+ * Find files matching a glob-like pattern in a directory.
+ * Supports `*` (any chars), `?` (single char), and `.` (literal dot).
+ * Results are sorted by modification time (newest first).
+ */
+export function findFiles(dir: string, pattern: string, options?: FindFilesOptions): FileMatch[];
+
+/**
+ * Read a text file safely. Returns null if the file doesn't exist or can't be read.
+ */
+export function readFile(filePath: string): string | null;
+
+/** Write a text file, creating parent directories if needed */
+export function writeFile(filePath: string, content: string): void;
+
+/** Append to a text file, creating parent directories if needed */
+export function appendFile(filePath: string, content: string): void;
+
+/**
+ * Replace text in a file (cross-platform sed alternative).
+ * @returns true if the file was found and updated, false if file not found
+ */
+export function replaceInFile(filePath: string, search: string | RegExp, replace: string): boolean;
+
+/**
+ * Count occurrences of a pattern in a file.
+ * The global flag is enforced automatically for correct counting.
+ */
+export function countInFile(filePath: string, pattern: string | RegExp): number;
+
+export interface GrepMatch {
+ /** 1-based line number */
+ lineNumber: number;
+ /** Full content of the matching line */
+ content: string;
+}
+
+/** Search for a pattern in a file and return matching lines with line numbers */
+export function grepFile(filePath: string, pattern: string | RegExp): GrepMatch[];
+
+// --- Hook I/O ---
+
+export interface ReadStdinJsonOptions {
+ /**
+ * Timeout in milliseconds. Prevents hooks from hanging indefinitely
+ * if stdin never closes. Default: 5000
+ */
+ timeoutMs?: number;
+}
+
+/**
+ * Read JSON from stdin (for hook input).
+ * Returns an empty object if stdin is empty or times out.
+ */
+export function readStdinJson(options?: ReadStdinJsonOptions): Promise<Record<string, unknown>>;
+
+/** Log a message to stderr (visible to user in Claude Code terminal) */
+export function log(message: string): void;
+
+/** Output data to stdout (returned to Claude's context) */
+export function output(data: string | Record<string, unknown>): void;
+
+// --- System ---
+
+/**
+ * Check if a command exists in PATH.
+ * Only allows alphanumeric, dash, underscore, and dot characters.
+ * WARNING: Spawns a child process (where.exe on Windows, which on Unix).
+ */
+export function commandExists(cmd: string): boolean;
+
+export interface CommandResult {
+ success: boolean;
+ /** Trimmed stdout on success, stderr or error message on failure */
+ output: string;
+}
+
+/**
+ * Run a shell command and return the output.
+ * SECURITY: Only use with trusted, hardcoded commands.
+ * Never pass user-controlled input directly.
+ */
+export function runCommand(cmd: string, options?: ExecSyncOptions): CommandResult;
+
+/** Check if the current directory is inside a git repository */
+export function isGitRepo(): boolean;
+
+/**
+ * Get git modified files (staged + unstaged), optionally filtered by regex patterns.
+ * Invalid regex patterns are silently skipped.
+ */
+export function getGitModifiedFiles(patterns?: string[]): string[];