contextswitch 0.1.4 → 0.1.6

package/README.md

@@ -1,100 +1,123 @@
 # ContextSwitch
 
-Domain-based context management for Claude Code CLI. Switch between different project contexts while preserving session history.
+Manage domain-based contexts for Claude Code CLI. Switch between projects without losing session history -- each domain remembers where you left off via Claude's `--resume` flag.
 
-## Features
+## Installation
 
-✅ **Session Persistence** - Resume previous Claude sessions when switching domains
-✅ **Domain Management** - Organize projects with separate configurations
-✅ **MCP Server Support** - Configure Model Context Protocol servers per domain
-✅ **Cross-Platform** - Works on macOS, Linux, and Windows
-✅ **Session Archives** - Save and restore session snapshots
-✅ **Process Management** - Clean switching between Claude instances
+**Prerequisites**: Node.js 18 or later, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 
-## Installation
+```bash
+npm install -g contextswitch
+```
+
+This installs the `cs` command globally.
+
+## Quick Start
 
-### Quick Install
 ```bash
-# Clone the repository
-git clone https://github.com/yourusername/contextswitch.git
-cd contextswitch
+# Initialize ContextSwitch (creates a default domain)
+cs init
+
+# Create a domain for a project
+cs domain add backend --working-dir ~/projects/api
+
+# Switch to that domain (launches Claude in the domain's working directory)
+cs switch backend
 
-# Run the installation script
-chmod +x install.sh
-./install.sh
+# See all domains
+cs list
 ```
 
-This sets up the `cs` command for easy use. For other installation methods, see [INSTALLATION.md](INSTALLATION.md).
+## Commands
 
-### Manual Install
-```bash
-# Install dependencies
-npm install
+### Core
 
-# Build the project
-npm run build:node
+| Command | Description |
+|---|---|
+| `cs init` | Initialize ContextSwitch and create a default domain |
+| `cs switch <domain>` | Switch to a domain (kills any running Claude, launches a new one) |
+| `cs list` | List all domains (`ls` also works) |
+| `cs status [domain]` | Show session info for the current or specified domain |
 
-# Add alias to your shell
-echo "alias cs='node $(pwd)/dist/cli.js'" >> ~/.zshrc
-source ~/.zshrc
+**switch** accepts an optional flag:
 
-# Now you can use 'cs' command
-cs --help
+```bash
+cs switch backend            # Resume existing session if one exists
+cs switch backend --force    # Force a brand-new session
 ```
 
-## Quick Start
+### Domain Management
+
+| Command | Description |
+|---|---|
+| `cs domain add <name>` | Create a new domain |
+| `cs domain remove <name>` | Delete a domain (`rm` also works) |
+| `cs reset <domain>` | Reset a domain's session, archiving the current one first |
+| `cs archive <domain>` | Snapshot the current session without resetting |
+
+**domain add** options:
 
 ```bash
-# Initialize ContextSwitch
-node dist/cli.js init
+# Unix
+cs domain add backend --working-dir ~/projects/api
+cs domain add frontend -w ~/projects/app --description "React frontend"
+
+# Windows (Git Bash)
+cs domain add backend --working-dir C:/Users/you/projects/api
+cs domain add frontend -w C:/Users/you/projects/app -d "React frontend"
 
-# Create a new domain for your project (working directory is REQUIRED)
-node dist/cli.js domain add backend --working-dir ~/projects/api
+# Inherit settings from another domain
+cs domain add staging --extends backend
+```
 
-# The working directory is where Claude will operate when you switch to this domain
-node dist/cli.js switch backend
+If `--working-dir` is omitted, the current directory is used.
 
-# Check status
-node dist/cli.js status
+**reset** options:
 
-# List all domains
-node dist/cli.js list
+```bash
+cs reset backend               # Archive current session, then reset
+cs reset backend --skip-archive  # Reset without archiving
 ```
 
-## Commands
+### Diagnostics
 
-### Core Commands
+| Command | Description |
+|---|---|
+| `cs doctor` | Check Claude CLI installation, config directory, running processes |
+| `cs --help` | Show help |
+| `cs --version` | Show version |
 
-- `cs init` - Initialize ContextSwitch configuration
-- `cs switch <domain>` - Switch to a different domain
-- `cs list` - List all available domains
-- `cs status [domain]` - Show current domain and session status
+## Platform Support
 
-### Domain Management
+| Platform | Status | Notes |
+|---|---|---|
+| macOS | Supported | Primary development platform |
+| Linux | Supported | |
+| Windows | Partial | Git Bash required; some process management features may not work |
 
-- `cs domain add <name>` - Create a new domain
-- `cs domain remove <name>` - Delete a domain
-- `cs reset <domain>` - Reset domain session (with auto-archive)
-- `cs archive <domain>` - Archive current session
+Config and state are stored in the platform-appropriate location:
 
-### Diagnostics
+- macOS: `~/Library/Application Support/contextswitch/`
+- Linux: `~/.config/contextswitch/`
+- Windows: `%APPDATA%\contextswitch\`
 
-- `cs doctor` - Check system configuration
-- `cs --help` - Show help information
-- `cs --version` - Show version
+## How It Works
 
-## Domain Configuration
+**Domains** are named project contexts. Each domain has a working directory, an optional description, optional MCP server configuration, and a session history. Domain config is stored as a YAML file and can be edited directly.
 
-Domains are stored as YAML files in the configuration directory. Example domain:
+**Sessions** are Claude conversation sessions identified by a UUID. When you run `cs switch`, ContextSwitch generates (or retrieves) a session ID for that domain and launches Claude with `--resume <sessionId>`, so Claude picks up where the previous conversation left off. Session IDs are deterministic -- the same domain always maps to the same base session ID.
+
+**MCP config** at `~/.config/claude/mcp/config.json` is updated on each switch to reflect the MCP servers defined in the active domain's config. This lets each domain have its own set of MCP tools.
+
+### Domain Config Example
+
+Domains are YAML files in the config directory. You can edit them directly after creating a domain with `cs domain add`:
 
 ```yaml
 name: backend
 workingDirectory: ~/projects/api
-
-claudeConfig:
-  instructions: ./CLAUDE.md
-  memory:
-    - ./context/api-overview.md
+metadata:
+  description: Backend API project
 
 mcpServers:
   filesystem:
@@ -107,79 +130,6 @@ env:
   NODE_ENV: development
 ```
 
-## Project Structure
-
-```
-contextswitch/
-├── src/
-│   ├── cli.ts              # Main CLI entry point
-│   ├── commands/           # Command implementations
-│   │   ├── switch.ts       # Domain switching logic
-│   │   ├── reset.ts        # Session reset
-│   │   └── archive.ts      # Session archiving
-│   └── core/               # Core modules
-│       ├── domain.ts       # Domain schemas (Zod)
-│       ├── config.ts       # Configuration management
-│       ├── session.ts      # Session ID generation
-│       ├── process.ts      # Process management
-│       └── paths.ts        # Cross-platform paths
-├── domains/                # Domain templates
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## Configuration Files
-
-- **Domains**: `~/Library/Application Support/contextswitch/domains/*.yml` (macOS)
-- **State**: `~/Library/Application Support/contextswitch/state.json`
-- **Archives**: `~/Library/Application Support/contextswitch/archives/`
-
-## Development
-
-```bash
-# Run TypeScript compiler check
-npx tsc --noEmit
-
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build:node
-
-# Run tests (when implemented)
-npm test
-```
-
-## Technical Details
-
-- Built with TypeScript and Commander.js
-- Uses Zod for runtime validation
-- Deterministic session IDs via UUID v5
-- Atomic file operations for data safety
-- Cross-platform process management
-
-## Status
-
-**Current Version**: 0.1.0 (MVP)
-
-### Implemented
-- ✅ Core domain management
-- ✅ Session persistence with `--resume`
-- ✅ Process management (kill/spawn Claude)
-- ✅ State tracking and atomic writes
-- ✅ Cross-platform path resolution
-- ✅ Basic CLI commands
-- ✅ Archive functionality
-
-### Not Yet Implemented
-- ⏳ Git sync for team sharing
-- ⏳ Token usage estimation
-- ⏳ Advanced diagnostics
-- ⏳ Binary compilation with Bun
-- ⏳ Automated tests
-- ⏳ Shell integration scripts
-
 ## License
 
-MIT
+MIT

package/dist/archive-MN425GUR.js

@@ -0,0 +1,10 @@
+import {
+  archiveCommand,
+  listArchives
+} from "./chunk-BGARUR7R.js";
+import "./chunk-D3DHIVER.js";
+import "./chunk-F36TGFK2.js";
+export {
+  archiveCommand,
+  listArchives
+};

package/dist/{chunk-2LUEUGBV.js → chunk-BGARUR7R.js}

@@ -1,16 +1,9 @@
 import {
   configManager
-} from "./chunk-XGE4JP55.js";
-import {
-  init_session,
-  session_exports
-} from "./chunk-UKMZ4CUZ.js";
+} from "./chunk-D3DHIVER.js";
 import {
   paths
-} from "./chunk-A7YXSI66.js";
-import {
-  __toCommonJS
-} from "./chunk-PNKVD2UK.js";
+} from "./chunk-F36TGFK2.js";
 
 // src/commands/archive.ts
 import picocolors from "picocolors";
@@ -33,18 +26,18 @@ async function archiveCommand(domainName) {
     if (!existsSync(archiveDir)) {
       mkdirSync(archiveDir, { recursive: true });
     }
+    const domain = configManager.loadDomain(domainName);
     const timestamp = /* @__PURE__ */ new Date();
     const archiveMetadata = {
       domain: domainName,
       session,
       timestamp: timestamp.toISOString(),
-      config: configManager.loadDomain(domainName)
+      config: domain
     };
     const dateStr = timestamp.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, -5);
     const archiveName = `${dateStr}.json`;
     const archivePath = join(archiveDir, archiveName);
     writeFileSync(archivePath, JSON.stringify(archiveMetadata, null, 2), "utf-8");
-    const domain = configManager.loadDomain(domainName);
     if (domain.claudeConfig?.memory) {
       const memoryArchiveDir = join(archiveDir, dateStr, "memory");
       mkdirSync(memoryArchiveDir, { recursive: true });
@@ -63,10 +56,10 @@ async function archiveCommand(domainName) {
     console.log(pc.green(`\u2705 Session archived successfully`));
     console.log(pc.gray(`Archive: ${archivePath}`));
     console.log(pc.gray(`Size: ${sizeKB} KB`));
-    console.log(pc.gray(`Session age: ${(init_session(), __toCommonJS(session_exports)).SessionManager.getSessionAge(session.started)}`));
+    const { SessionManager } = await import("./session-H5HPE5OT.js");
+    console.log(pc.gray(`Session age: ${SessionManager.getSessionAge(session.started)}`));
   } catch (error) {
-    console.error(pc.red(`\u274C Failed to archive session: ${error}`));
-    process.exit(1);
+    throw new Error(`Failed to archive session: ${error}`);
   }
 }
 function listArchives(domainName) {

package/dist/{chunk-XGE4JP55.js → chunk-D3DHIVER.js}

@@ -1,10 +1,7 @@
 import {
+  debug,
   paths
-} from "./chunk-A7YXSI66.js";
-
-// src/core/config.ts
-import { readFileSync, existsSync, writeFileSync, readdirSync, renameSync, unlinkSync } from "fs";
-import { parse, stringify } from "yaml";
+} from "./chunk-F36TGFK2.js";
 
 // src/core/domain.ts
 import { z } from "zod";
@@ -13,15 +10,35 @@ var MCPServerSchema = z.object({
   args: z.array(z.string()).optional().describe("Arguments for the command"),
   env: z.record(z.string()).optional().describe("Environment variables")
 });
+var DOMAIN_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var ENV_VAR_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function validateDomainName(name) {
+  if (!name || name.length === 0) {
+    return "Domain name cannot be empty";
+  }
+  if (name.length > 64) {
+    return "Domain name must be 64 characters or fewer";
+  }
+  if (!DOMAIN_NAME_REGEX.test(name)) {
+    return "Domain name must start with a letter or number and contain only letters, numbers, hyphens, underscores, and dots";
+  }
+  if (name === "." || name === "..") {
+    return 'Domain name cannot be "." or ".."';
+  }
+  return null;
+}
 var DomainConfigSchema = z.object({
-  name: z.string().min(1).describe("Domain identifier"),
+  name: z.string().min(1).regex(DOMAIN_NAME_REGEX, "Domain name must start with a letter or number and contain only letters, numbers, hyphens, underscores, and dots").describe("Domain identifier"),
   workingDirectory: z.string().describe("Working directory for this domain"),
   claudeConfig: z.object({
     instructions: z.string().optional().describe("Path to CLAUDE.md file"),
     memory: z.array(z.string()).optional().describe("Memory file paths")
   }).optional(),
   mcpServers: z.record(MCPServerSchema).optional().describe("MCP server configurations"),
-  env: z.record(z.string()).optional().describe("Environment variables for this domain"),
+  env: z.record(
+    z.string().regex(ENV_VAR_NAME_REGEX, "Environment variable names must start with a letter or underscore and contain only letters, digits, and underscores"),
+    z.string()
+  ).optional().describe("Environment variables for this domain"),
   extends: z.string().optional().describe("Parent domain to inherit from"),
   metadata: z.object({
     description: z.string().optional(),
@@ -56,6 +73,10 @@ var GlobalConfigSchema = z.object({
     killTimeout: z.number().default(5e3).describe("Milliseconds to wait before force kill")
   }).optional()
 });
+var SessionFallbackMarkerSchema = z.object({
+  domain: z.string().min(1).regex(DOMAIN_NAME_REGEX),
+  sessionId: z.string().min(1)
+});
 var DEFAULT_DOMAIN_TEMPLATE = {
   name: "default",
   workingDirectory: process.cwd(),
@@ -70,6 +91,15 @@ var DEFAULT_DOMAIN_TEMPLATE = {
     tags: []
   }
 };
+function validateEnvVarName(name) {
+  if (!name || name.length === 0) {
+    return "Environment variable name cannot be empty";
+  }
+  if (!ENV_VAR_NAME_REGEX.test(name)) {
+    return `Invalid environment variable name '${name}': must start with a letter or underscore and contain only letters, digits, and underscores`;
+  }
+  return null;
+}
 function validateDomain(data) {
   return DomainConfigSchema.parse(data);
 }
@@ -86,33 +116,28 @@ function createInitialState() {
 }
 
 // src/core/config.ts
+import { readFileSync, existsSync, writeFileSync, readdirSync, renameSync, unlinkSync } from "fs";
+import { parse, stringify } from "yaml";
 var ConfigManager = class {
-  globalConfig = null;
-  state = null;
-  domainCache = /* @__PURE__ */ new Map();
   /**
    * Load global configuration
    */
   loadGlobalConfig() {
-    if (this.globalConfig) {
-      return this.globalConfig;
-    }
     const configPath = paths.globalConfigFile;
     if (!existsSync(configPath)) {
-      this.globalConfig = {
+      const defaultConfig = {
         version: "1.0.0",
         defaultDomain: "default",
         autoArchive: true,
         logLevel: "info"
       };
-      this.saveGlobalConfig(this.globalConfig);
-      return this.globalConfig;
+      this.saveGlobalConfig(defaultConfig);
+      return defaultConfig;
     }
     try {
       const content = readFileSync(configPath, "utf-8");
       const data = parse(content);
-      this.globalConfig = GlobalConfigSchema.parse(data);
-      return this.globalConfig;
+      return GlobalConfigSchema.parse(data);
     } catch (error) {
       throw new Error(`Failed to load global config: ${error}`);
     }
@@ -122,28 +147,29 @@ var ConfigManager = class {
    */
   saveGlobalConfig(config) {
     const configPath = paths.globalConfigFile;
+    const tempPath = `${configPath}.tmp`;
     const content = stringify(config, { indent: 2 });
-    writeFileSync(configPath, content, "utf-8");
-    this.globalConfig = config;
+    writeFileSync(tempPath, content, "utf-8");
+    renameSync(tempPath, configPath);
   }
   /**
    * Load state file
    */
   loadState() {
-    if (this.state) {
-      return this.state;
-    }
     const statePath = paths.stateFile;
+    debug("config", `Loading state from ${statePath}`);
     if (!existsSync(statePath)) {
-      this.state = createInitialState();
-      this.saveState(this.state);
-      return this.state;
+      debug("config", "No state file found, creating initial state");
+      const initial = createInitialState();
+      this.saveState(initial);
+      return initial;
     }
     try {
       const content = readFileSync(statePath, "utf-8");
       const data = JSON.parse(content);
-      this.state = validateState(data);
-      return this.state;
+      const state = validateState(data);
+      debug("config", `State loaded: activeDomain=${state.activeDomain}, sessions=${Object.keys(state.sessions || {}).join(",") || "none"}`);
+      return state;
     } catch (error) {
       throw new Error(`Failed to load state: ${error}`);
     }
@@ -154,19 +180,23 @@ var ConfigManager = class {
   saveState(state) {
     const statePath = paths.stateFile;
     const tempPath = `${statePath}.tmp`;
+    debug("config", `Saving state to ${statePath} (activeDomain=${state.activeDomain})`);
     const content = JSON.stringify(state, null, 2);
     writeFileSync(tempPath, content, "utf-8");
     renameSync(tempPath, statePath);
-    this.state = state;
   }
   /**
    * Load a domain configuration
    */
   loadDomain(domainName) {
-    if (this.domainCache.has(domainName)) {
-      return this.domainCache.get(domainName);
-    }
+    return this.loadDomainInternal(domainName, []);
+  }
+  /**
+   * Internal domain loader with cycle detection for inheritance chains.
+   */
+  loadDomainInternal(domainName, ancestors) {
     const domainPath = paths.domainConfigFile(domainName);
+    debug("config", `Loading domain '${domainName}' from ${domainPath}`);
     if (!existsSync(domainPath)) {
       throw new Error(`Domain '${domainName}' not found`);
     }
@@ -175,7 +205,11 @@ var ConfigManager = class {
       const data = parse(content);
       let domain = validateDomain(data);
       if (domain.extends) {
-        const parent = this.loadDomain(domain.extends);
+        if (ancestors.includes(domain.extends)) {
+          throw new Error(`Circular inheritance detected: ${[...ancestors, domainName, domain.extends].join(" -> ")}`);
+        }
+        debug("config", `Domain '${domainName}' extends '${domain.extends}', merging`);
+        const parent = this.loadDomainInternal(domain.extends, [...ancestors, domainName]);
         domain = this.mergeDomains(parent, domain);
       }
       domain.workingDirectory = paths.expandPath(domain.workingDirectory);
@@ -185,7 +219,6 @@ var ConfigManager = class {
       if (domain.claudeConfig?.memory) {
         domain.claudeConfig.memory = domain.claudeConfig.memory.map((p) => paths.expandPath(p));
       }
-      this.domainCache.set(domainName, domain);
       return domain;
     } catch (error) {
       throw new Error(`Failed to load domain '${domainName}': ${error}`);
@@ -196,9 +229,10 @@ var ConfigManager = class {
    */
   saveDomain(domain) {
     const domainPath = paths.domainConfigFile(domain.name);
+    const tempPath = `${domainPath}.tmp`;
     const content = stringify(domain, { indent: 2 });
-    writeFileSync(domainPath, content, "utf-8");
-    this.domainCache.set(domain.name, domain);
+    writeFileSync(tempPath, content, "utf-8");
+    renameSync(tempPath, domainPath);
   }
   /**
    * Create a new domain from template
@@ -243,7 +277,6 @@ var ConfigManager = class {
       throw new Error(`Domain '${domainName}' not found`);
     }
     unlinkSync(domainPath);
-    this.domainCache.delete(domainName);
   }
   /**
    * Merge two domain configurations (child overrides parent)
@@ -291,13 +324,13 @@ var ConfigManager = class {
    * Clear cache
    */
   clearCache() {
-    this.globalConfig = null;
-    this.state = null;
-    this.domainCache.clear();
   }
 };
 var configManager = new ConfigManager();
 
 export {
+  validateDomainName,
+  SessionFallbackMarkerSchema,
+  validateEnvVarName,
   configManager
 };

package/dist/{chunk-A7YXSI66.js → chunk-F36TGFK2.js}

@@ -72,6 +72,9 @@ var Paths = class _Paths {
    * Get domain config file path
    */
   domainConfigFile(domainName) {
+    if (domainName.includes("/") || domainName.includes("\\") || domainName === ".." || domainName === ".") {
+      throw new Error(`Unsafe domain name: ${domainName}`);
+    }
     return join(this.domainsDir, `${domainName}.yml`);
   }
   /**
@@ -108,7 +111,9 @@ var Paths = class _Paths {
    * Expand environment variables and ~ in paths
    */
   expandPath(inputPath) {
-    if (inputPath.startsWith("~/")) {
+    if (inputPath === "~") {
+      inputPath = homedir();
+    } else if (inputPath.startsWith("~/")) {
       inputPath = join(homedir(), inputPath.slice(2));
     }
     inputPath = inputPath.replace(/\$([A-Z_][A-Z0-9_]*)/gi, (match, varName) => {
@@ -158,6 +163,20 @@ var Paths = class _Paths {
 };
 var paths = Paths.instance;
 
+// src/core/debug.ts
+import picocolors from "picocolors";
+var pc = picocolors;
+var enabled = false;
+function enableDebug() {
+  enabled = true;
+}
+function debug(context, message) {
+  if (!enabled) return;
+  console.log(pc.dim(`[debug:${context}] ${message}`));
+}
+
 export {
-  paths
+  paths,
+  enableDebug,
+  debug
 };