chainlesschain 0.45.10 → 0.45.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chainlesschain",
-  "version": "0.45.10",
+  "version": "0.45.11",
   "description": "CLI for ChainlessChain - install, configure, and manage your personal AI management system",
   "type": "module",
   "bin": {

package/src/commands/config.js

@@ -8,6 +8,7 @@ import {
 } from "../lib/config-manager.js";
 import { getConfigPath } from "../lib/paths.js";
 import logger from "../lib/logger.js";
+import { listFeatures, setFeature, getFlagInfo } from "../lib/feature-flags.js";
 
 export function registerConfigCommand(program) {
   const cmd = program
@@ -69,6 +70,49 @@ export function registerConfigCommand(program) {
       }
     });
 
+  // ── Feature Flags ──────────────────────────────────────────────────
+
+  const featuresCmd = cmd
+    .command("features")
+    .description("Manage feature flags");
+
+  featuresCmd
+    .command("list")
+    .alias("ls")
+    .description("Show all feature flags and their status")
+    .action(() => {
+      const flags = listFeatures();
+      logger.log(chalk.bold("\n  Feature Flags\n"));
+      for (const f of flags) {
+        const status = f.enabled ? chalk.green("● ON ") : chalk.gray("○ OFF");
+        const src = chalk.gray(`[${f.source}]`);
+        logger.log(`  ${status} ${chalk.cyan(f.name)} ${src}`);
+        logger.log(`         ${chalk.gray(f.description)}`);
+      }
+      logger.newline();
+    });
+
+  featuresCmd
+    .command("enable")
+    .description("Enable a feature flag")
+    .argument("<name>", "Flag name (e.g. CONTEXT_SNIP)")
+    .action((name) => {
+      setFeature(name, true);
+      const info = getFlagInfo(name);
+      logger.success(`Enabled ${name}${info ? ` — ${info.description}` : ""}`);
+    });
+
+  featuresCmd
+    .command("disable")
+    .description("Disable a feature flag")
+    .argument("<name>", "Flag name (e.g. CONTEXT_SNIP)")
+    .action((name) => {
+      setFeature(name, false);
+      logger.success(`Disabled ${name}`);
+    });
+
+  // ── Reset ──────────────────────────────────────────────────────────
+
   cmd
     .command("reset")
     .description("Reset configuration to defaults")

package/src/constants.js

@@ -135,6 +135,7 @@ export const DEFAULT_CONFIG = {
   setupCompleted: false,
   completedAt: null,
   edition: "personal",
+  features: {},
   paths: {
     projectRoot: null,
     database: null,

package/src/lib/background-task-manager.js

@@ -0,0 +1,305 @@
+/**
+ * Background Task Manager — daemon task queue with completion notifications.
+ *
+ * Tasks run in child_process.fork() for isolation.
+ * Queue persisted to .chainlesschain/tasks/queue.jsonl.
+ * Completion notifications delivered to REPL callback.
+ *
+ * Feature-flag gated: BACKGROUND_TASKS
+ */
+
+import { fork } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  appendFileSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { getHomeDir } from "./paths.js";
+
+function getTasksDir() {
+  const dir = join(getHomeDir(), "tasks");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function queuePath() {
+  return join(getTasksDir(), "queue.jsonl");
+}
+
+// ── Task Status ─────────────────────────────────────────────────────────
+
+export const TaskStatus = {
+  PENDING: "pending",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  TIMEOUT: "timeout",
+};
+
+// ── BackgroundTaskManager ───────────────────────────────────────────────
+
+export class BackgroundTaskManager extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {number} [options.maxConcurrent=3] — Max parallel background tasks
+   * @param {number} [options.heartbeatTimeout=60000] — Task heartbeat timeout (ms)
+   */
+  constructor(options = {}) {
+    super();
+    this.maxConcurrent = options.maxConcurrent || 3;
+    this.heartbeatTimeout = options.heartbeatTimeout || 60000;
+    this.tasks = new Map(); // id -> task object
+    this.processes = new Map(); // id -> child process
+    this._checkInterval = null;
+  }
+
+  /**
+   * Create and queue a new background task.
+   * @param {object} spec
+   * @param {string} spec.type — Task type (e.g. "shell", "agent", "script")
+   * @param {string} spec.command — Command or script to execute
+   * @param {string} [spec.cwd] — Working directory
+   * @param {string} [spec.description] — Human-readable description
+   * @returns {object} Created task
+   */
+  create(spec) {
+    if (this._runningCount() >= this.maxConcurrent) {
+      throw new Error(
+        `Max concurrent tasks reached (${this.maxConcurrent}). Wait for a task to finish.`,
+      );
+    }
+
+    const id = `task-${Date.now()}-${createHash("sha256").update(Math.random().toString()).digest("hex").slice(0, 6)}`;
+
+    const task = {
+      id,
+      type: spec.type || "shell",
+      command: spec.command,
+      cwd: spec.cwd || process.cwd(),
+      description: spec.description || spec.command,
+      status: TaskStatus.PENDING,
+      createdAt: Date.now(),
+      startedAt: null,
+      completedAt: null,
+      lastHeartbeat: null,
+      result: null,
+      error: null,
+    };
+
+    this.tasks.set(id, task);
+    this._persistTask(task);
+    return task;
+  }
+
+  /**
+   * Start a pending task (runs in child process).
+   */
+  start(taskId) {
+    const task = this.tasks.get(taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+    if (task.status !== TaskStatus.PENDING)
+      throw new Error(`Task ${taskId} is not pending (status: ${task.status})`);
+
+    task.status = TaskStatus.RUNNING;
+    task.startedAt = Date.now();
+    task.lastHeartbeat = Date.now();
+
+    // Create a wrapper script that executes the command
+    const child = fork(
+      join(import.meta.dirname || ".", "background-task-worker.js"),
+      [task.command, task.cwd, task.type],
+      {
+        cwd: task.cwd,
+        silent: true,
+        env: { ...process.env, CC_TASK_ID: taskId },
+      },
+    );
+
+    this.processes.set(taskId, child);
+
+    child.on("message", (msg) => {
+      if (msg.type === "heartbeat") {
+        task.lastHeartbeat = Date.now();
+      } else if (msg.type === "result") {
+        this._complete(taskId, TaskStatus.COMPLETED, msg.data, null);
+      } else if (msg.type === "error") {
+        this._complete(taskId, TaskStatus.FAILED, null, msg.error);
+      }
+    });
+
+    child.on("exit", (code) => {
+      if (task.status === TaskStatus.RUNNING) {
+        if (code === 0) {
+          this._complete(
+            taskId,
+            TaskStatus.COMPLETED,
+            "Process exited (0)",
+            null,
+          );
+        } else {
+          this._complete(
+            taskId,
+            TaskStatus.FAILED,
+            null,
+            `Process exited with code ${code}`,
+          );
+        }
+      }
+      this.processes.delete(taskId);
+    });
+
+    child.on("error", (err) => {
+      this._complete(taskId, TaskStatus.FAILED, null, err.message);
+      this.processes.delete(taskId);
+    });
+
+    this._persistTask(task);
+    this._ensureHeartbeatChecker();
+    return task;
+  }
+
+  /**
+   * Create and immediately start a task.
+   */
+  run(spec) {
+    const task = this.create(spec);
+    this.start(task.id);
+    return task;
+  }
+
+  /**
+   * Get a task by ID.
+   */
+  get(taskId) {
+    return this.tasks.get(taskId) || null;
+  }
+
+  /**
+   * List all tasks.
+   */
+  list(filter = {}) {
+    let tasks = [...this.tasks.values()];
+    if (filter.status) {
+      tasks = tasks.filter((t) => t.status === filter.status);
+    }
+    return tasks.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  /**
+   * Stop a running task.
+   */
+  stop(taskId) {
+    const child = this.processes.get(taskId);
+    if (child) {
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (child.exitCode === null) child.kill("SIGKILL");
+      }, 2000);
+    }
+    this._complete(taskId, TaskStatus.FAILED, null, "Stopped by user");
+  }
+
+  /**
+   * Clean up completed/failed tasks older than maxAge.
+   * @param {number} [maxAge=3600000] — Max age in ms (default 1 hour)
+   */
+  cleanup(maxAge = 3600000) {
+    const cutoff = Date.now() - maxAge;
+    let removed = 0;
+    for (const [id, task] of this.tasks) {
+      if (
+        (task.status === TaskStatus.COMPLETED ||
+          task.status === TaskStatus.FAILED ||
+          task.status === TaskStatus.TIMEOUT) &&
+        task.completedAt &&
+        task.completedAt < cutoff
+      ) {
+        this.tasks.delete(id);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  /**
+   * Destroy the manager (kill all running tasks, clear intervals).
+   */
+  destroy() {
+    if (this._checkInterval) {
+      clearInterval(this._checkInterval);
+      this._checkInterval = null;
+    }
+    for (const [id] of this.processes) {
+      this.stop(id);
+    }
+    this.tasks.clear();
+    this.processes.clear();
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────
+
+  _complete(taskId, status, result, error) {
+    const task = this.tasks.get(taskId);
+    if (!task) return;
+
+    task.status = status;
+    task.completedAt = Date.now();
+    task.result = result;
+    task.error = error;
+
+    this._persistTask(task);
+    this.emit("task:complete", task);
+  }
+
+  _runningCount() {
+    let count = 0;
+    for (const task of this.tasks.values()) {
+      if (task.status === TaskStatus.RUNNING) count++;
+    }
+    return count;
+  }
+
+  _persistTask(task) {
+    try {
+      const line = JSON.stringify(task) + "\n";
+      appendFileSync(queuePath(), line, "utf-8");
+    } catch (_e) {
+      // Non-critical
+    }
+  }
+
+  _ensureHeartbeatChecker() {
+    if (this._checkInterval) return;
+
+    this._checkInterval = setInterval(
+      () => {
+        const now = Date.now();
+        for (const [id, task] of this.tasks) {
+          if (
+            task.status === TaskStatus.RUNNING &&
+            task.lastHeartbeat &&
+            now - task.lastHeartbeat > this.heartbeatTimeout
+          ) {
+            this._complete(id, TaskStatus.TIMEOUT, null, "Heartbeat timeout");
+            const child = this.processes.get(id);
+            if (child) {
+              child.kill("SIGKILL");
+              this.processes.delete(id);
+            }
+          }
+        }
+      },
+      Math.min(this.heartbeatTimeout / 2, 10000),
+    );
+
+    // Don't keep process alive for the checker
+    if (this._checkInterval.unref) {
+      this._checkInterval.unref();
+    }
+  }
+}

package/src/lib/background-task-worker.js

@@ -0,0 +1,50 @@
+/**
+ * Background Task Worker — child process that executes a command.
+ *
+ * Args: [command, cwd, type]
+ * Sends messages to parent: { type: "heartbeat"|"result"|"error", ... }
+ */
+
+import { execSync } from "node:child_process";
+
+const [command, cwd, type] = process.argv.slice(2);
+
+// Heartbeat every 5 seconds
+const heartbeat = setInterval(() => {
+  if (process.send) process.send({ type: "heartbeat" });
+}, 5000);
+
+try {
+  let result;
+
+  if (type === "shell") {
+    result = execSync(command, {
+      cwd: cwd || process.cwd(),
+      encoding: "utf-8",
+      timeout: 300000, // 5 min max
+      maxBuffer: 10 * 1024 * 1024,
+    });
+  } else {
+    // Default: treat as shell
+    result = execSync(command, {
+      cwd: cwd || process.cwd(),
+      encoding: "utf-8",
+      timeout: 300000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+  }
+
+  if (process.send) {
+    process.send({ type: "result", data: result || "Done" });
+  }
+} catch (err) {
+  if (process.send) {
+    process.send({
+      type: "error",
+      error: err.stderr || err.message || String(err),
+    });
+  }
+  process.exitCode = 1;
+} finally {
+  clearInterval(heartbeat);
+}

package/src/lib/feature-flags.js

@@ -0,0 +1,182 @@
+/**
+ * Feature Flag System — runtime feature gating for gradual rollout.
+ *
+ * Flags are stored in .chainlesschain/config.json under "features" key.
+ * Each flag can be:
+ *   - boolean (true/false)
+ *   - number 0-100 (percentage rollout, hashed by machine-id)
+ *   - object { enabled, variant, description }
+ *
+ * Usage:
+ *   import { feature, featureVariant, listFeatures } from "./feature-flags.js";
+ *   if (feature("CONTEXT_SNIP")) { ... }
+ */
+
+import { loadConfig, getConfigValue, saveConfig } from "./config-manager.js";
+import { createHash } from "node:crypto";
+import { hostname } from "node:os";
+
+// ── Flag Registry (source of truth for known flags) ────────────────────
+
+const FLAG_REGISTRY = {
+  BACKGROUND_TASKS: {
+    description: "Enable background task queue with daemon execution",
+    default: false,
+  },
+  WORKTREE_ISOLATION: {
+    description: "Enable git worktree isolation for agent tasks",
+    default: false,
+  },
+  CONTEXT_SNIP: {
+    description: "Enable snipCompact strategy in context compression",
+    default: false,
+  },
+  CONTEXT_COLLAPSE: {
+    description: "Enable contextCollapse strategy in context compression",
+    default: false,
+  },
+  JSONL_SESSION: {
+    description: "Use JSONL append-only format for session persistence",
+    default: false,
+  },
+  PROMPT_COMPRESSOR: {
+    description: "Enable CLI prompt compressor (auto/snip/collapse)",
+    default: true,
+  },
+};
+
+// ── Core API ────────────────────────────────────────────────────────────
+
+/**
+ * Check if a feature flag is enabled.
+ * @param {string} name - Flag name (e.g. "CONTEXT_SNIP")
+ * @returns {boolean}
+ */
+export function feature(name) {
+  const value = _resolve(name);
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return _percentageCheck(name, value);
+  if (value && typeof value === "object") return Boolean(value.enabled);
+  return _getDefault(name);
+}
+
+/**
+ * Get the variant string for a feature (for A/B style flags).
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function featureVariant(name) {
+  const value = _resolve(name);
+  if (value && typeof value === "object" && value.variant) {
+    return value.variant;
+  }
+  return null;
+}
+
+/**
+ * List all known feature flags with their current values.
+ * @returns {Array<{name, enabled, description, source, raw}>}
+ */
+export function listFeatures() {
+  const config = loadConfig();
+  const features = config.features || {};
+  const result = [];
+
+  for (const [name, meta] of Object.entries(FLAG_REGISTRY)) {
+    const raw = features[name];
+    const enabled = feature(name);
+    const source =
+      raw !== undefined
+        ? "config"
+        : process.env[`CC_FLAG_${name}`] !== undefined
+          ? "env"
+          : "default";
+
+    result.push({
+      name,
+      enabled,
+      description: meta.description,
+      source,
+      raw: raw !== undefined ? raw : meta.default,
+    });
+  }
+
+  // Include unknown flags from config (user-defined)
+  for (const [name, raw] of Object.entries(features)) {
+    if (!FLAG_REGISTRY[name]) {
+      result.push({
+        name,
+        enabled: Boolean(raw),
+        description: "(user-defined)",
+        source: "config",
+        raw,
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Set a feature flag value in config.
+ * @param {string} name
+ * @param {boolean|number|string} value
+ */
+export function setFeature(name, value) {
+  const config = loadConfig();
+  if (!config.features) config.features = {};
+  config.features[name] = value;
+  saveConfig(config);
+}
+
+/**
+ * Get the registry entry for a known flag (or null).
+ * @param {string} name
+ * @returns {{description: string, default: boolean}|null}
+ */
+export function getFlagInfo(name) {
+  return FLAG_REGISTRY[name] || null;
+}
+
+// ── Internal helpers ───────────────────────────────���────────────────────
+
+function _resolve(name) {
+  // Priority: env var > config > default
+  const envKey = `CC_FLAG_${name}`;
+  if (process.env[envKey] !== undefined) {
+    const envVal = process.env[envKey];
+    if (envVal === "true" || envVal === "1") return true;
+    if (envVal === "false" || envVal === "0") return false;
+    const num = Number(envVal);
+    if (!isNaN(num)) return num;
+    return envVal;
+  }
+
+  const configVal = getConfigValue(`features.${name}`);
+  if (configVal !== undefined) return configVal;
+
+  return undefined; // let caller fall to default
+}
+
+function _getDefault(name) {
+  const meta = FLAG_REGISTRY[name];
+  return meta ? meta.default : false;
+}
+
+function _percentageCheck(name, percentage) {
+  if (percentage <= 0) return false;
+  if (percentage >= 100) return true;
+  const hash = createHash("md5")
+    .update(`${name}:${_machineId()}`)
+    .digest("hex");
+  const bucket = parseInt(hash.slice(0, 8), 16) % 100;
+  return bucket < percentage;
+}
+
+let _cachedMachineId = null;
+function _machineId() {
+  if (!_cachedMachineId) {
+    _cachedMachineId = hostname() || "unknown";
+  }
+  return _cachedMachineId;
+}