npm - @leynier/ccst - Versions diffs - 0.5.3 → 1.0.0 - Mend

@leynier/ccst 0.5.3 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/AGENTS.md +47 -85
package/package.json +4 -2
package/readme.md +112 -0
package/src/commands/ccs/install.ts +136 -0
package/src/commands/ccs/setup.ts +39 -0
package/src/commands/ccs/start.ts +93 -12
package/src/commands/ccs/status.ts +44 -25
package/src/commands/ccs/stop.ts +21 -2
package/src/commands/import-profiles/ccs.ts +27 -11
package/src/index.ts +33 -1
package/src/scripts/watcher.ts +88 -0
package/src/utils/daemon.ts +83 -2
package/src/utils/interactive.ts +3 -0
package/src/utils/watcher-daemon.ts +191 -0

package/AGENTS.md CHANGED Viewed

@@ -1,105 +1,67 @@
-Default to using Bun instead of Node.js.
+# CLAUDE.md
-- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
-- Use `bun test` instead of `jest` or `vitest`
-- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
-- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
-- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
-- Use `bunx <package> <command>` instead of `npx <package> <command>`
-- Bun automatically loads .env, so don't use dotenv.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-## APIs
+## Build & Development Commands
-- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
-- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
-- `Bun.redis` for Redis. Don't use `ioredis`.
-- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
-- `WebSocket` is built-in. Don't use `ws`.
-- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
-- Bun.$`ls` instead of execa.
+```bash
+# Install dependencies
+bun install
-## Testing
+# Format code
+bun run format
-Use `bun test` to run tests.
+# Lint code (with auto-fix)
+bun run lint
-```ts#index.test.ts
-import { test, expect } from "bun:test";
+# Run both format and lint
+bun run validate
-test("hello world", () => {
-  expect(1).toBe(1);
-});
-```
+# Run tests
+bun test
+# Run a single test file
+bun test src/core/context-manager.test.ts
-## Frontend
-Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
-Server:
-```ts#index.ts
-import index from "./index.html"
-Bun.serve({
-  routes: {
-    "/": index,
-    "/api/users/:id": {
-      GET: (req) => {
-        return new Response(JSON.stringify({ id: req.params.id }));
-      },
-    },
-  },
-  // optional websocket support
-  websocket: {
-    open: (ws) => {
-      ws.send("Hello, world!");
-    },
-    message: (ws, message) => {
-      ws.send(message);
-    },
-    close: (ws) => {
-      // handle close
-    }
-  },
-  development: {
-    hmr: true,
-    console: true,
-  }
-})
+# Run CLI locally during development
+bun src/index.ts [args]
 ```
-HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+## Architecture Overview
-```html#index.html
-<html>
-  <body>
-    <h1>Hello, world!</h1>
-    <script type="module" src="./frontend.tsx"></script>
-  </body>
-</html>
-```
+**ccst** (Claude Code Switch Tools) is a CLI tool that manages Claude Code IDE contexts and configurations. It allows users to switch between different permission sets, environments, and settings at user, project, and local levels.
-With the following `frontend.tsx`:
+### Core Components
-```tsx#frontend.tsx
-import React from "react";
-import { createRoot } from "react-dom/client";
+- **`src/index.ts`** - Main CLI entry point using Commander.js. Defines all commands and routes to handlers.
+- **`src/core/context-manager.ts`** - Central class for all context operations (CRUD, switching, merging). All operations flow through this class.
+- **`src/core/merge-manager.ts`** - Handles permission merging with history tracking and smart deduplication.
+- **`src/utils/daemon.ts`** - Cross-platform daemon process management (Windows/Unix). Critical for CCS daemon commands.
+- **`src/utils/paths.ts`** - Resolves paths for all three settings levels (user/project/local).
-// import .css files directly and it works
-import './index.css';
+### Settings Levels
-const root = createRoot(document.body);
+The tool operates at three hierarchical levels:
-export default function Frontend() {
-  return <h1>Hello, world!</h1>;
-}
+- **User:** `~/.claude/settings.json` and `~/.claude/settings/`
+- **Project:** `./.claude/settings.json` and `./.claude/settings/`
+- **Local:** `./.claude/settings.local.json` and `./.claude/settings/`
-root.render(<Frontend />);
-```
+### Command Structure
-Then, run index.ts
+Commands in `src/commands/` are organized by function:
-```sh
-bun --hot ./index.ts
-```
+- `ccs/` - CCS daemon management (start, stop, status, logs, setup, install)
+- `config/` - Configuration backup/restore (dump, load)
+- `import-profiles/` - Profile importers (ccs, configs)
+## Development Guidelines
+- **Use Bun, not Node.js** - All file operations use `Bun.file()`, `Bun.write()`, `Bun.remove()`. See `AGENTS.md` for Bun API patterns.
+- **Use `Bun.$` for shell commands** - Not execa or child_process.
+- **Cross-platform handling** - `src/utils/daemon.ts` has separate code paths for Windows (taskkill, netstat) and Unix (lsof, kill signals). Test both when modifying.
+- **Formatting/Linting** - Uses Biome. Run `bun run validate` before committing.
+## Commit Message Pattern
-For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
+Follow existing commit prefixes: `feat:`, `fix:`, `chore:`

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "@leynier/ccst",
-	"version": "0.5.3",
+	"version": "1.0.0",
 	"description": "Claude Code Switch Tools for managing contexts",
 	"keywords": [
 		"claude",
@@ -32,6 +32,7 @@
 	},
 	"dependencies": {
 		"commander": "^12.1.0",
+		"get-port": "^7.1.0",
 		"jszip": "^3.10.1",
 		"picocolors": "^1.1.0"
 	},
@@ -45,6 +46,7 @@
 	"files": [
 		"src",
 		"index.ts",
+		"readme.md",
 		"README.md",
 		"LICENSE",
 		"AGENTS.md",
@@ -56,4 +58,4 @@
 	"publishConfig": {
 		"access": "public"
 	}
-}
+}

package/readme.md CHANGED Viewed

@@ -185,6 +185,85 @@ ccst import configs
 ccst import configs -d /path/to/configs
 ```
+## CCS Daemon Management
+ccst can manage the CCS (Claude Code Server) daemon for background processing:
+### Installation & Setup
+```bash
+# Install CCS CLI tool (interactive package manager selection)
+ccst ccs install
+# Run initial setup
+ccst ccs setup
+# Force setup even if already configured
+ccst ccs setup -f
+```
+### Starting & Stopping
+```bash
+# Start daemon
+ccst ccs start
+# Start with specific dashboard port
+ccst ccs start -p 3001
+# Force restart if already running
+ccst ccs start -f
+# Keep existing logs (append instead of truncate)
+ccst ccs start --keep-logs
+# Stop daemon
+ccst ccs stop
+# Force kill daemon
+ccst ccs stop -f
+```
+### Monitoring
+```bash
+# Check daemon status
+ccst ccs status
+# View logs (last 50 lines by default)
+ccst ccs logs
+# View more lines
+ccst ccs logs -n 100
+# Follow logs in real-time
+ccst ccs logs -f
+```
+## Configuration Backup
+Backup and restore all CCS configuration:
+```bash
+# Export configuration to ZIP file
+ccst config dump
+# Export to custom path
+ccst config dump my-backup.zip
+# Import configuration from ZIP
+ccst config load
+# Import from custom path
+ccst config load my-backup.zip
+# Replace all existing files during import
+ccst config load -r
+# Skip confirmation prompt
+ccst config load -y
+```
 ## File Structure
 Contexts are stored as individual JSON files at different levels:
@@ -213,6 +292,15 @@ Project level (`./.claude/`):
     └── .cctx-state.local.json # Local state
 ```
+CCS daemon files (`~/.ccs/`):
+```text
+~/.ccs/
+├── .daemon.pid            # Daemon process ID
+├── .daemon.log            # Daemon log file
+└── .daemon.ports          # Dashboard port tracking
+```
 ## Interactive Mode
 When no arguments are provided, ccst can enter interactive mode:
@@ -311,10 +399,34 @@ ccst -c
 - `ccst --in-project` - Project-level contexts (`./.claude/settings.json`)
 - `ccst --local` - Local project contexts (`./.claude/settings.local.json`)
+### CCS Daemon Commands
+- `ccst ccs install` - Install CCS CLI tool (interactive package manager selection)
+- `ccst ccs setup` - Run CCS initial setup
+- `ccst ccs setup -f` - Force setup even if already configured
+- `ccst ccs start` - Start CCS daemon
+- `ccst ccs start -f` - Force restart if already running
+- `ccst ccs start -p <port>` - Start with specific dashboard port
+- `ccst ccs start --keep-logs` - Keep existing logs (append instead of truncate)
+- `ccst ccs stop` - Stop CCS daemon
+- `ccst ccs stop -f` - Force kill daemon (SIGKILL)
+- `ccst ccs status` - Show daemon status, PID, and log info
+- `ccst ccs logs` - View daemon logs (last 50 lines)
+- `ccst ccs logs -n <lines>` - View specified number of lines
+- `ccst ccs logs -f` - Follow log output in real-time
+### Configuration Commands
+- `ccst config dump [output]` - Export CCS config to ZIP (default: ccs-config.zip)
+- `ccst config load [input]` - Import CCS config from ZIP (default: ccs-config.zip)
+- `ccst config load -r` - Replace all existing files during import
+- `ccst config load -y` - Skip confirmation prompt
 ### Other Options
 - `ccst --completions <shell>` - Generate shell completions
 - `ccst --help` - Show help information
+- `ccst --version` - Show version
 ## Compatibility Note

package/src/commands/ccs/install.ts ADDED Viewed

@@ -0,0 +1,136 @@
+import { spawnSync } from "node:child_process";
+import pc from "picocolors";
+import { promptInput } from "../../utils/interactive.js";
+type PackageManager = {
+	name: string;
+	displayCommand: string;
+	command: string;
+	args: string[];
+};
+const packageManagers: PackageManager[] = [
+	{
+		name: "bun",
+		displayCommand: "bun add -g @kaitranntt/ccs",
+		command: "bun",
+		args: ["add", "-g", "@kaitranntt/ccs"],
+	},
+	{
+		name: "npm",
+		displayCommand: "npm install -g @kaitranntt/ccs",
+		command: "npm",
+		args: ["install", "-g", "@kaitranntt/ccs"],
+	},
+	{
+		name: "pnpm",
+		displayCommand: "pnpm add -g @kaitranntt/ccs",
+		command: "pnpm",
+		args: ["add", "-g", "@kaitranntt/ccs"],
+	},
+	{
+		name: "yarn",
+		displayCommand: "yarn global add @kaitranntt/ccs",
+		command: "yarn",
+		args: ["global", "add", "@kaitranntt/ccs"],
+	},
+];
+const selectPackageManager = async (): Promise<PackageManager | undefined> => {
+	const lines = packageManagers.map(
+		(pm, index) => `${index + 1}. ${pm.name} (${pm.displayCommand})`,
+	);
+	console.log("Select package manager to install @kaitranntt/ccs:");
+	console.log(lines.join("\n"));
+	const input = await promptInput("Select option (1-4)");
+	const index = Number.parseInt(input || "", 10);
+	if (!Number.isFinite(index) || index < 1 || index > packageManagers.length) {
+		console.log(pc.red("Invalid selection"));
+		return undefined;
+	}
+	return packageManagers[index - 1];
+};
+const verifyInstallation = async (): Promise<string | null> => {
+	const result = spawnSync("ccs", ["--version"], {
+		stdio: ["ignore", "pipe", "pipe"],
+		encoding: "utf8",
+	});
+	if (result.status !== 0) {
+		return null;
+	}
+	const version = result.stdout?.trim();
+	return version && version.length > 0 ? version : null;
+};
+const promptForSetup = async (): Promise<boolean> => {
+	const response = await promptInput("Run ccs setup now? (y/n)");
+	return response?.toLowerCase() === "y";
+};
+export const ccsInstallCommand = async (): Promise<void> => {
+	// Step 1: Select package manager
+	const selectedPm = await selectPackageManager();
+	if (!selectedPm) {
+		console.log(pc.dim("Installation cancelled"));
+		return;
+	}
+	// Step 2: Execute installation
+	console.log(
+		pc.dim(
+			`Installing @kaitranntt/ccs using ${selectedPm.name}... (this may take a moment)`,
+		),
+	);
+	const installResult = spawnSync(selectedPm.command, selectedPm.args, {
+		stdio: "inherit",
+	});
+	if (installResult.status !== 0) {
+		console.log(
+			pc.red(
+				`Error: Installation failed with exit code ${installResult.status}`,
+			),
+		);
+		return;
+	}
+	// Step 3: Verify installation
+	console.log(pc.dim("Verifying installation..."));
+	const version = await verifyInstallation();
+	if (!version) {
+		console.log(
+			pc.yellow("Warning: ccs installed but could not verify installation"),
+		);
+		console.log(pc.dim("You may need to restart your terminal"));
+		console.log(pc.dim("Try running 'which ccs' or 'ccs --version' manually"));
+		return;
+	}
+	console.log(pc.green(`ccs installed successfully (${version})`));
+	// Step 4: Ask if user wants to run setup
+	const shouldRunSetup = await promptForSetup();
+	if (shouldRunSetup) {
+		console.log(pc.dim("Running ccs setup..."));
+		const setupResult = spawnSync("ccs", ["setup"], { stdio: "inherit" });
+		if (setupResult.status === 0) {
+			console.log(pc.green("Setup completed successfully"));
+		} else {
+			console.log(
+				pc.yellow(
+					`Setup exited with code ${setupResult.status} (this may not be an error)`,
+				),
+			);
+		}
+	} else {
+		console.log(pc.dim("You can run 'ccst ccs setup' later to configure ccs"));
+	}
+};

package/src/commands/ccs/setup.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+import pc from "picocolors";
+export type SetupOptions = {
+	force?: boolean;
+};
+export const ccsSetupCommand = async (
+	options?: SetupOptions,
+): Promise<void> => {
+	// Check if ccs is installed
+	const which = spawnSync("which", ["ccs"], { stdio: "ignore" });
+	if (which.status !== 0) {
+		console.log(pc.red("Error: ccs command not found"));
+		console.log(pc.dim("Run 'ccst ccs install' to install it"));
+		return;
+	}
+	// Build arguments
+	const args = ["setup"];
+	if (options?.force) {
+		args.push("--force");
+	}
+	// Execute ccs setup with real-time output
+	const result = spawnSync("ccs", args, {
+		stdio: "inherit",
+	});
+	// Check exit code
+	if (result.status !== 0) {
+		console.log(
+			pc.red(`Error: ccs setup failed with exit code ${result.status}`),
+		);
+		return;
+	}
+	console.log(pc.green("Setup completed successfully"));
+};

package/src/commands/ccs/start.ts CHANGED Viewed

@@ -1,19 +1,34 @@
 import { spawn } from "node:child_process";
-import { openSync } from "node:fs";
+import { openSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import getPort from "get-port";
 import pc from "picocolors";
 import {
 	ensureDaemonDir,
 	getCcsExecutable,
+	getCliproxyPort,
 	getLogPath,
 	getProcessByPort,
 	getRunningDaemonPid,
 	isProcessRunning,
 	killProcessTree,
+	truncateFile,
 	writePid,
+	writePorts,
 } from "../../utils/daemon.js";
+import {
+	getRunningWatcherPid,
+	startWatcher,
+	stopWatcher,
+} from "../../utils/watcher-daemon.js";
 export type StartOptions = {
 	force?: boolean;
+	keepLogs?: boolean;
+	port?: number;
+	noWatch?: boolean;
+	timeout?: number;
 };
 export const ccsStartCommand = async (
@@ -32,6 +47,11 @@ export const ccsStartCommand = async (
 	if (existingPid !== null && options?.force) {
 		console.log(pc.dim(`Stopping existing daemon (PID: ${existingPid})...`));
 		await killProcessTree(existingPid, true);
+		// Also stop watcher if running
+		const watcherPid = await getRunningWatcherPid();
+		if (watcherPid !== null) {
+			await stopWatcher(true);
+		}
 		// Wait for process to terminate
 		const maxWait = 3000;
 		const startTime = Date.now();
@@ -44,28 +64,78 @@ export const ccsStartCommand = async (
 	}
 	ensureDaemonDir();
 	const logPath = getLogPath();
+	if (!options?.keepLogs) {
+		try {
+			await truncateFile(logPath);
+		} catch {
+			console.warn(
+				pc.yellow(
+					`Warning: could not truncate log; continuing (logs will be appended): ${logPath}`,
+				),
+			);
+		}
+	}
+	// Detect ports
+	const cliproxyPort = await getCliproxyPort();
+	const dashboardPort =
+		options?.port ??
+		(await getPort({
+			port: [3000, 3001, 3002, 8000, 8080],
+		}));
+	// Save ports for stop command
+	await writePorts({ dashboard: dashboardPort, cliproxy: cliproxyPort });
+	console.log(
+		pc.dim(
+			`Using dashboard port: ${dashboardPort}, CLIProxy port: ${cliproxyPort}`,
+		),
+	);
 	const ccsPath = getCcsExecutable();
 	let pid: number | undefined;
 	if (process.platform === "win32") {
-		// On Windows, use cmd /c start /B to launch without creating a new window
-		// This works with npm-installed .cmd wrappers that create their own console
-		const proc = spawn("cmd", ["/c", `start /B "" "${ccsPath}" config`], {
+		// VBScript is the ONLY reliable way to run a process completely hidden on Windows
+		// WScript.Shell.Run with 0 = hidden window, False = don't wait
+		// Redirect output to log file using cmd /c with shell redirection
+		const escapedLogPath = logPath.replace(/\\/g, "\\\\");
+		const vbsContent = `CreateObject("WScript.Shell").Run "cmd /c ${ccsPath} config --port ${dashboardPort} >> ${escapedLogPath} 2>&1", 0, False`;
+		const vbsPath = join(tmpdir(), `ccs-start-${Date.now()}.vbs`);
+		await Bun.write(vbsPath, vbsContent);
+		// Run the vbs file (wscript itself doesn't show a window)
+		const proc = spawn("wscript", [vbsPath], {
+			detached: true,
 			stdio: "ignore",
 			windowsHide: true,
-			detached: true,
 		});
 		proc.unref();
-		// Wait for the process to start, then find it by port
-		console.log(pc.dim("Starting CCS config daemon..."));
-		await new Promise((resolve) => setTimeout(resolve, 2000));
+		// Clean up the vbs file after a short delay
+		setTimeout(() => {
+			try {
+				unlinkSync(vbsPath);
+			} catch {}
+		}, 1000);
+		// Poll for the port to become available
+		// ccs config takes ~6s to start (5s CLIProxy timeout + dashboard startup)
+		console.log(
+			pc.dim("Starting CCS config daemon (this may take a few seconds)..."),
+		);
+		const maxWaitMs = options?.timeout ?? 30000;
+		const pollIntervalMs = 500;
+		const startTime = Date.now();
+		let foundPid: number | null = null;
+		while (Date.now() - startTime < maxWaitMs) {
+			foundPid = await getProcessByPort(dashboardPort);
+			if (foundPid !== null) break;
+			await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+		}
-		// Find the process by port 3000 (dashboard port)
-		const foundPid = await getProcessByPort(3000);
 		if (foundPid === null) {
 			console.log(pc.red("Failed to start CCS config daemon"));
 			console.log(
-				pc.dim("Check if ccs is installed: npm install -g @anthropic/ccs"),
+				pc.dim("Check if ccs is installed: npm install -g @kaitranntt/ccs"),
 			);
 			return;
 		}
@@ -73,7 +143,7 @@ export const ccsStartCommand = async (
 	} else {
 		// On Unix, use regular spawn with detached mode
 		const logFd = openSync(logPath, "a");
-		const child = spawn(ccsPath, ["config"], {
+		const child = spawn(ccsPath, ["config", "--port", String(dashboardPort)], {
 			detached: true,
 			stdio: ["ignore", logFd, logFd],
 		});
@@ -87,6 +157,17 @@ export const ccsStartCommand = async (
 	await writePid(pid);
 	console.log(pc.green(`CCS config daemon started (PID: ${pid})`));
 	console.log(pc.dim(`Logs: ${logPath}`));
+	// Start file watcher unless --no-watch is specified
+	if (!options?.noWatch) {
+		const watcherPid = await startWatcher();
+		if (watcherPid) {
+			console.log(pc.dim(`File watcher started (PID: ${watcherPid})`));
+		} else {
+			console.log(pc.yellow("Warning: Failed to start file watcher"));
+		}
+	}
 	console.log(pc.dim("Run 'ccst ccs status' to check status"));
 	console.log(pc.dim("Run 'ccst ccs logs' to view logs"));
 };

package/src/commands/ccs/status.ts CHANGED Viewed

@@ -5,37 +5,56 @@ import {
 	getPidPath,
 	getRunningDaemonPid,
 } from "../../utils/daemon.js";
+import {
+	getRunningWatcherPid,
+	getWatcherLogPath,
+} from "../../utils/watcher-daemon.js";
 export const ccsStatusCommand = async (): Promise<void> => {
+	// Show daemon status
 	const pid = await getRunningDaemonPid();
 	if (pid === null) {
 		console.log(pc.yellow("CCS config daemon is not running"));
-		return;
-	}
-	console.log(pc.green(`CCS config daemon is running (PID: ${pid})`));
-	// Show additional info
-	const pidPath = getPidPath();
-	const logPath = getLogPath();
-	console.log(pc.dim(`PID file: ${pidPath}`));
-	if (existsSync(logPath)) {
-		const stats = statSync(logPath);
-		const sizeKb = (stats.size / 1024).toFixed(2);
-		console.log(pc.dim(`Log file: ${logPath} (${sizeKb} KB)`));
-	}
-	// Try to get process uptime (Unix only)
-	if (process.platform !== "win32") {
-		try {
-			const proc = Bun.spawn(["ps", "-p", String(pid), "-o", "etime="], {
-				stdout: "pipe",
-				stderr: "ignore",
-			});
-			const output = await new Response(proc.stdout).text();
-			const uptime = output.trim();
-			if (uptime) {
-				console.log(pc.dim(`Uptime: ${uptime}`));
+	} else {
+		console.log(pc.green(`CCS config daemon is running (PID: ${pid})`));
+		const pidPath = getPidPath();
+		const logPath = getLogPath();
+		console.log(pc.dim(`PID file: ${pidPath}`));
+		if (existsSync(logPath)) {
+			const stats = statSync(logPath);
+			const sizeKb = (stats.size / 1024).toFixed(2);
+			console.log(pc.dim(`Log file: ${logPath} (${sizeKb} KB)`));
+		}
+		// Try to get process uptime (Unix only)
+		if (process.platform !== "win32") {
+			try {
+				const proc = Bun.spawn(["ps", "-p", String(pid), "-o", "etime="], {
+					stdout: "pipe",
+					stderr: "ignore",
+				});
+				const output = await new Response(proc.stdout).text();
+				const uptime = output.trim();
+				if (uptime) {
+					console.log(pc.dim(`Uptime: ${uptime}`));
+				}
+			} catch {
+				// ps command not available or failed
 			}
-		} catch {
-			// ps command not available or failed
 		}
 	}
+	// Show watcher status
+	console.log();
+	const watcherPid = await getRunningWatcherPid();
+	if (watcherPid !== null) {
+		console.log(pc.green(`File watcher is running (PID: ${watcherPid})`));
+		const watcherLogPath = getWatcherLogPath();
+		if (existsSync(watcherLogPath)) {
+			const stats = statSync(watcherLogPath);
+			const sizeKb = (stats.size / 1024).toFixed(2);
+			console.log(pc.dim(`Watcher log: ${watcherLogPath} (${sizeKb} KB)`));
+		}
+	} else {
+		console.log(pc.yellow("File watcher is not running"));
+	}
 };

package/src/commands/ccs/stop.ts CHANGED Viewed

@@ -1,12 +1,17 @@
 import pc from "picocolors";
 import {
-	CCS_PORTS,
+	getPortsToKill,
 	getRunningDaemonPid,
 	isProcessRunning,
 	killProcessByPort,
 	killProcessTree,
 	removePid,
+	removePorts,
 } from "../../utils/daemon.js";
+import {
+	getRunningWatcherPid,
+	stopWatcher,
+} from "../../utils/watcher-daemon.js";
 export type StopOptions = {
 	force?: boolean;
@@ -32,13 +37,27 @@ export const ccsStopCommand = async (options?: StopOptions): Promise<void> => {
 		stopped = true;
 	}
 	// Phase 2: Kill processes by port (especially important on Windows)
-	for (const port of CCS_PORTS) {
+	// Use saved ports or fallback to defaults
+	const ports = await getPortsToKill();
+	for (const port of ports) {
 		const killed = await killProcessByPort(port, options?.force ?? true);
 		if (killed) {
 			console.log(pc.dim(`Cleaned up process on port ${port}`));
 			stopped = true;
 		}
 	}
+	// Clean up ports file
+	removePorts();
+	// Stop file watcher
+	const watcherPid = await getRunningWatcherPid();
+	if (watcherPid !== null) {
+		const watcherStopped = await stopWatcher(options?.force);
+		if (watcherStopped) {
+			console.log(pc.dim(`File watcher stopped (PID: ${watcherPid})`));
+		}
+	}
 	if (!stopped) {
 		console.log(pc.yellow("CCS config daemon is not running"));
 	}

package/src/commands/import-profiles/ccs.ts CHANGED Viewed

@@ -7,7 +7,7 @@ import { deepMerge } from "../../utils/deep-merge.js";
 import { readJson, readJsonIfExists } from "../../utils/json.js";
 const defaultConfigsDir = (): string => path.join(homedir(), ".ccst");
-const ccsDir = (): string => path.join(homedir(), ".ccs");
+export const ccsDir = (): string => path.join(homedir(), ".ccs");
 const ensureDefaultConfig = async (
 	manager: ContextManager,
@@ -49,9 +49,10 @@ const importProfile = async (
 	profileName: string,
 	merged: Record<string, unknown>,
 ): Promise<void> => {
-	await manager.deleteContext(profileName).catch(() => undefined);
-	const input = `${JSON.stringify(merged, null, 2)}\n`;
-	await manager.importContextFromString(profileName, input);
+	// Write directly to the context file, overwriting if exists
+	const contextPath = path.join(manager.contextsDir, `${profileName}.json`);
+	const content = `${JSON.stringify(merged, null, 2)}\n`;
+	await Bun.write(contextPath, content);
 };
 const createDefaultProfileIfNeeded = async (
@@ -65,15 +66,19 @@ const createDefaultProfileIfNeeded = async (
 	await importProfile(manager, "default", defaultProfile);
 };
-export const importFromCcs = async (
+export type PerformCcsImportResult = {
+	importedCount: number;
+	profileNames: string[];
+};
+export const performCcsImport = async (
 	manager: ContextManager,
 	configsDir?: string,
-): Promise<void> => {
+): Promise<PerformCcsImportResult> => {
 	const ccsPath = ccsDir();
 	if (!existsSync(ccsPath)) {
 		throw new Error(`CCS directory not found: ${ccsPath}`);
 	}
-	console.log(`📥 Importing profiles from CCS settings...`);
 	const dir = configsDir ?? defaultConfigsDir();
 	const { created } = await ensureDefaultConfig(manager, dir);
 	const defaultConfig = await loadDefaultConfig(dir);
@@ -91,23 +96,34 @@ export const importFromCcs = async (
 	} catch {
 		entries = [];
 	}
-	let importedCount = 0;
+	const profileNames: string[] = [];
 	for (const fileName of entries) {
 		const settingsPath = path.join(ccsPath, fileName);
 		const profileName = fileName.replace(/\.settings\.json$/u, "");
-		console.log(`  📦 Importing '${colors.cyan(profileName)}'...`);
 		const settings = await readJson<Record<string, unknown>>(settingsPath);
 		const merged = deepMerge(defaultConfig, settings);
 		if (currentContext && currentContext === profileName) {
 			await manager.unsetContext();
 		}
 		await importProfile(manager, profileName, merged);
-		importedCount++;
+		profileNames.push(profileName);
 	}
 	if (currentContext) {
 		await manager.switchContext(currentContext);
 	}
+	return { importedCount: profileNames.length, profileNames };
+};
+export const importFromCcs = async (
+	manager: ContextManager,
+	configsDir?: string,
+): Promise<void> => {
+	console.log(`📥 Importing profiles from CCS settings...`);
+	const result = await performCcsImport(manager, configsDir);
+	for (const profileName of result.profileNames) {
+		console.log(`  📦 Imported '${colors.cyan(profileName)}'`);
+	}
 	console.log(
-		`✅ Imported ${colors.bold(colors.green(String(importedCount)))} profiles from CCS`,
+		`✅ Imported ${colors.bold(colors.green(String(result.importedCount)))} profiles from CCS`,
 	);
 };

package/src/index.ts CHANGED Viewed

@@ -1,7 +1,9 @@
 #!/usr/bin/env bun
 import { Command } from "commander";
 import pkg from "../package.json";
+import { ccsInstallCommand } from "./commands/ccs/install.js";
 import { ccsLogsCommand } from "./commands/ccs/logs.js";
+import { ccsSetupCommand } from "./commands/ccs/setup.js";
 import { ccsStartCommand } from "./commands/ccs/start.js";
 import { ccsStatusCommand } from "./commands/ccs/status.js";
 import { ccsStopCommand } from "./commands/ccs/stop.js";
@@ -188,8 +190,25 @@ const main = async (): Promise<void> => {
 		.command("start")
 		.description("Start CCS config as background daemon")
 		.option("-f, --force", "Force restart if already running")
+		.option("--keep-logs", "Keep existing log file (append)")
+		.option(
+			"-p, --port <number>",
+			"Dashboard port (auto-detect if not specified)",
+		)
+		.option("-W, --no-watch", "Skip file watcher")
+		.option(
+			"-t, --timeout <seconds>",
+			"Timeout in seconds for daemon startup (Windows only)",
+			"30",
+		)
 		.action(async (options) => {
-			await ccsStartCommand(options);
+			await ccsStartCommand({
+				force: options.force,
+				keepLogs: options.keepLogs,
+				port: options.port ? Number.parseInt(options.port, 10) : undefined,
+				noWatch: options.watch === false,
+				timeout: Number.parseInt(options.timeout, 10) * 1000,
+			});
 		});
 	ccsCommandGroup
 		.command("stop")
@@ -215,6 +234,19 @@ const main = async (): Promise<void> => {
 				lines: parseInt(options.lines, 10),
 			});
 		});
+	ccsCommandGroup
+		.command("setup")
+		.description("Run CCS initial setup")
+		.option("-f, --force", "Force setup even if already configured")
+		.action(async (options) => {
+			await ccsSetupCommand(options);
+		});
+	ccsCommandGroup
+		.command("install")
+		.description("Install CCS CLI tool")
+		.action(async () => {
+			await ccsInstallCommand();
+		});
 	try {
 		await program.parseAsync(process.argv);
 	} catch {

package/src/scripts/watcher.ts ADDED Viewed

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+import { existsSync, watch } from "node:fs";
+import { ccsDir, performCcsImport } from "../commands/import-profiles/ccs.js";
+import { ContextManager } from "../core/context-manager.js";
+import { getPaths } from "../utils/paths.js";
+const DEBOUNCE_MS = 1000;
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+let isImporting = false;
+const log = (message: string): void => {
+	const timestamp = new Date().toISOString();
+	console.log(`[${timestamp}] ${message}`);
+};
+const runImport = async (): Promise<void> => {
+	if (isImporting) {
+		log("Import already in progress, skipping");
+		return;
+	}
+	isImporting = true;
+	try {
+		const manager = new ContextManager(getPaths("user"));
+		const result = await performCcsImport(manager);
+		if (result.importedCount > 0) {
+			log(
+				`Imported ${result.importedCount} profiles: ${result.profileNames.join(", ")}`,
+			);
+		} else {
+			log("No profiles to import");
+		}
+	} catch (error) {
+		log(`Import error: ${error}`);
+	} finally {
+		isImporting = false;
+	}
+};
+const handleFileChange = (eventType: string, filename: string | null): void => {
+	if (!filename || !filename.endsWith(".settings.json")) {
+		return;
+	}
+	log(`Detected ${eventType} on ${filename}`);
+	// Debounce
+	if (debounceTimer) {
+		clearTimeout(debounceTimer);
+	}
+	debounceTimer = setTimeout(runImport, DEBOUNCE_MS);
+};
+const main = async (): Promise<void> => {
+	const ccsPath = ccsDir();
+	log(`CCS Settings Watcher - PID: ${process.pid}`);
+	log(`Watching directory: ${ccsPath}`);
+	if (!existsSync(ccsPath)) {
+		log(`ERROR: CCS directory not found: ${ccsPath}`);
+		log("Please run 'ccs setup' first to initialize CCS");
+		process.exit(1);
+	}
+	// Run initial import
+	log("Running initial import...");
+	await runImport();
+	// Start watching
+	const watcher = watch(ccsPath, { persistent: true }, handleFileChange);
+	// Graceful shutdown
+	const cleanup = (): void => {
+		log("Shutting down watcher");
+		if (debounceTimer) {
+			clearTimeout(debounceTimer);
+		}
+		watcher.close();
+		process.exit(0);
+	};
+	process.on("SIGINT", cleanup);
+	process.on("SIGTERM", cleanup);
+	log("Watcher started successfully");
+};
+await main();

package/src/utils/daemon.ts CHANGED Viewed

@@ -11,6 +11,11 @@ export const getPidPath = (): string => join(getDaemonDir(), "ccs-config.pid");
 // Log file path
 export const getLogPath = (): string => join(getDaemonDir(), "ccs-config.log");
+// Truncate a file (or create it empty if missing)
+export const truncateFile = async (filePath: string): Promise<void> => {
+	await Bun.write(filePath, "");
+};
 // Ensure daemon directory exists
 export const ensureDaemonDir = (): void => {
 	const dir = getDaemonDir();
@@ -82,8 +87,84 @@ export const getCcsExecutable = (): string => {
 	return "ccs";
 };
-// Known CCS daemon ports
-export const CCS_PORTS = [3000, 8317];
+// Default CCS daemon ports (fallback)
+export const DEFAULT_DASHBOARD_PORT = 3000;
+export const DEFAULT_CLIPROXY_PORT = 8317;
+// Ports file path
+export const getPortsPath = (): string => join(getDaemonDir(), "ports.json");
+// Type for daemon ports
+export type DaemonPorts = {
+	dashboard: number;
+	cliproxy: number;
+};
+// Read saved ports
+export const readPorts = async (): Promise<DaemonPorts | null> => {
+	const portsPath = getPortsPath();
+	if (!existsSync(portsPath)) {
+		return null;
+	}
+	try {
+		const content = await Bun.file(portsPath).text();
+		const ports = JSON.parse(content) as DaemonPorts;
+		if (
+			typeof ports.dashboard === "number" &&
+			typeof ports.cliproxy === "number"
+		) {
+			return ports;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+};
+// Write ports to file
+export const writePorts = async (ports: DaemonPorts): Promise<void> => {
+	ensureDaemonDir();
+	await Bun.write(getPortsPath(), JSON.stringify(ports, null, 2));
+};
+// Remove ports file
+export const removePorts = (): void => {
+	const portsPath = getPortsPath();
+	if (existsSync(portsPath)) {
+		unlinkSync(portsPath);
+	}
+};
+// Read CLIProxy port from config.yaml
+export const getCliproxyPort = async (): Promise<number> => {
+	const configPath = join(homedir(), ".ccs", "cliproxy", "config.yaml");
+	if (!existsSync(configPath)) {
+		return DEFAULT_CLIPROXY_PORT;
+	}
+	try {
+		const content = await Bun.file(configPath).text();
+		// Simple YAML parsing for "port: XXXX"
+		const match = content.match(/^port:\s*(\d+)/m);
+		if (match?.[1]) {
+			const port = Number.parseInt(match[1], 10);
+			if (Number.isFinite(port) && port > 0) {
+				return port;
+			}
+		}
+		return DEFAULT_CLIPROXY_PORT;
+	} catch {
+		return DEFAULT_CLIPROXY_PORT;
+	}
+};
+// Get ports to kill (from saved file or defaults)
+export const getPortsToKill = async (): Promise<number[]> => {
+	const saved = await readPorts();
+	if (saved) {
+		return [saved.dashboard, saved.cliproxy];
+	}
+	return [DEFAULT_DASHBOARD_PORT, DEFAULT_CLIPROXY_PORT];
+};
 // Kill process tree (on Windows, kills all child processes)
 export const killProcessTree = async (

package/src/utils/interactive.ts CHANGED Viewed

@@ -71,6 +71,9 @@ const readStdinLine = async (): Promise<string> => {
 		const cleanup = () => {
 			process.stdin.off("data", onData);
 			process.stdin.off("end", onEnd);
+			if (process.stdin.isTTY) {
+				process.stdin.pause();
+			}
 		};
 		if (process.stdin.isTTY) {
 			process.stdin.resume();

package/src/utils/watcher-daemon.ts ADDED Viewed

@@ -0,0 +1,191 @@
+import { existsSync, openSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+	ensureDaemonDir,
+	getDaemonDir,
+	isProcessRunning,
+	killProcessTree,
+	truncateFile,
+} from "./daemon.js";
+// Watcher PID file path
+export const getWatcherPidPath = (): string =>
+	join(getDaemonDir(), "watcher.pid");
+// Watcher log file path
+export const getWatcherLogPath = (): string =>
+	join(getDaemonDir(), "watcher.log");
+// Read watcher PID from file
+export const readWatcherPid = async (): Promise<number | null> => {
+	const pidPath = getWatcherPidPath();
+	if (!existsSync(pidPath)) {
+		return null;
+	}
+	try {
+		const content = await Bun.file(pidPath).text();
+		const pid = parseInt(content.trim(), 10);
+		return Number.isFinite(pid) ? pid : null;
+	} catch {
+		return null;
+	}
+};
+// Write watcher PID to file
+export const writeWatcherPid = async (pid: number): Promise<void> => {
+	ensureDaemonDir();
+	await Bun.write(getWatcherPidPath(), String(pid));
+};
+// Remove watcher PID file
+export const removeWatcherPid = (): void => {
+	const pidPath = getWatcherPidPath();
+	if (existsSync(pidPath)) {
+		unlinkSync(pidPath);
+	}
+};
+// Get running watcher PID (validates process is actually running)
+export const getRunningWatcherPid = async (): Promise<number | null> => {
+	const pid = await readWatcherPid();
+	if (pid === null) {
+		return null;
+	}
+	if (!isProcessRunning(pid)) {
+		// Stale PID file - clean it up
+		removeWatcherPid();
+		return null;
+	}
+	return pid;
+};
+// Get watcher script path
+const getWatcherScriptPath = (): string => {
+	// The script is in src/scripts/watcher.ts relative to the package
+	// When running as installed package, we need to find it
+	const scriptPath = join(import.meta.dir, "..", "scripts", "watcher.ts");
+	return scriptPath;
+};
+// Start watcher process
+export const startWatcher = async (): Promise<number | null> => {
+	const existingPid = await getRunningWatcherPid();
+	if (existingPid !== null) {
+		return existingPid;
+	}
+	ensureDaemonDir();
+	const logPath = getWatcherLogPath();
+	const scriptPath = getWatcherScriptPath();
+	// Truncate log file
+	await truncateFile(logPath);
+	if (process.platform === "win32") {
+		return startWatcherWindows(scriptPath, logPath);
+	}
+	return startWatcherUnix(scriptPath, logPath);
+};
+// Start watcher on Windows using VBScript to hide console
+const startWatcherWindows = async (
+	scriptPath: string,
+	logPath: string,
+): Promise<number | null> => {
+	const vbsPath = join(getDaemonDir(), "start-watcher.vbs");
+	const vbsContent = `
+Set WshShell = CreateObject("WScript.Shell")
+WshShell.Run "cmd /c bun run ""${scriptPath}"" >> ""${logPath}"" 2>&1", 0, False
+`.trim();
+	await Bun.write(vbsPath, vbsContent);
+	const proc = Bun.spawn(["wscript", "//Nologo", vbsPath], {
+		detached: true,
+		stdio: ["ignore", "ignore", "ignore"],
+	});
+	proc.unref();
+	// Clean up VBS file after short delay
+	setTimeout(() => {
+		try {
+			unlinkSync(vbsPath);
+		} catch {
+			// Ignore cleanup errors
+		}
+	}, 1000);
+	// Poll for log file to have content (indicating process started)
+	const maxWait = 5000;
+	const interval = 200;
+	let waited = 0;
+	while (waited < maxWait) {
+		await new Promise((resolve) => setTimeout(resolve, interval));
+		waited += interval;
+		// Check if log file has content
+		if (existsSync(logPath)) {
+			const file = Bun.file(logPath);
+			const size = file.size;
+			if (size > 0) {
+				// Try to find the PID by reading the log
+				const content = await file.text();
+				const match = content.match(/PID:\s*(\d+)/);
+				if (match?.[1]) {
+					const pid = Number.parseInt(match[1], 10);
+					if (Number.isFinite(pid) && pid > 0) {
+						await writeWatcherPid(pid);
+						return pid;
+					}
+				}
+			}
+		}
+	}
+	return null;
+};
+// Start watcher on Unix
+const startWatcherUnix = async (
+	scriptPath: string,
+	logPath: string,
+): Promise<number | null> => {
+	const logFd = openSync(logPath, "a");
+	const child = Bun.spawn(["bun", "run", scriptPath], {
+		detached: true,
+		stdio: ["ignore", logFd, logFd],
+	});
+	child.unref();
+	const pid = child.pid;
+	if (pid) {
+		await writeWatcherPid(pid);
+	}
+	return pid;
+};
+// Stop watcher process
+export const stopWatcher = async (force?: boolean): Promise<boolean> => {
+	const pid = await readWatcherPid();
+	if (pid === null) {
+		return false;
+	}
+	const killed = await killProcessTree(pid, force);
+	// Wait for process to terminate
+	const maxWait = force ? 1000 : 5000;
+	const interval = 100;
+	let waited = 0;
+	while (waited < maxWait && isProcessRunning(pid)) {
+		await new Promise((resolve) => setTimeout(resolve, interval));
+		waited += interval;
+	}
+	removeWatcherPid();
+	return killed || !isProcessRunning(pid);
+};