kc-beta 0.1.0

package/src/agent/tools/workspace-file.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BaseTool, ToolResult } from "./base.js";
+
+const MAX_READ = 50_000;
+
+/**
+ * Read, write, or list files in the workspace directory.
+ * All paths are resolved relative to the workspace root with
+ * traversal protection. VersionManager hooks into writes for automatic versioning.
+ */
+export class WorkspaceFileTool extends BaseTool {
+  /**
+   * @param {import('../workspace.js').Workspace} workspace
+   * @param {import('../version-manager.js').VersionManager} [versionManager]
+   */
+  constructor(workspace, versionManager) {
+    super();
+    this._workspace = workspace;
+    this._versionManager = versionManager || null;
+  }
+
+  get name() { return "workspace_file"; }
+
+  get description() {
+    return (
+      "Read, write, or list files in the workspace directory. " +
+      "Operations: read (returns file content), write (creates/overwrites a file), " +
+      "list (shows directory contents)."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["read", "write", "list"],
+          description: "The file operation to perform",
+        },
+        path: {
+          type: "string",
+          description: "Relative path within the workspace. Defaults to '.' for list.",
+        },
+        content: {
+          type: "string",
+          description: "File content to write (required for write operation)",
+        },
+      },
+      required: ["operation"],
+    };
+  }
+
+  async execute(input) {
+    const op = input.operation || "";
+    const filePath = input.path || ".";
+    const content = input.content || "";
+
+    try {
+      if (op === "read") return this._read(filePath);
+      if (op === "write") return this._write(filePath, content);
+      if (op === "list") return this._list(filePath);
+      return new ToolResult(`Unknown operation: ${op}`, true);
+    } catch (err) {
+      return new ToolResult(`File error: ${err.message}`, true);
+    }
+  }
+
+  _read(filePath) {
+    const resolved = this._workspace.resolvePath(filePath);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+      return new ToolResult(`File not found: ${filePath}`, true);
+    }
+    let text = fs.readFileSync(resolved, { encoding: "utf-8" });
+    if (text.length > MAX_READ) {
+      text = text.slice(0, MAX_READ) + "\n[truncated]";
+    }
+    return new ToolResult(text);
+  }
+
+  _write(filePath, content) {
+    if (!filePath || filePath === ".") {
+      return new ToolResult("Path required for write operation", true);
+    }
+    const resolved = this._workspace.resolvePath(filePath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, content, "utf-8");
+
+    // Version tracking (structural — cannot be bypassed)
+    let traceId = null;
+    if (this._versionManager) {
+      traceId = this._versionManager.onWrite(filePath, content);
+    }
+
+    let msg = `Wrote ${content.length} chars to ${filePath}`;
+    if (traceId) msg += ` [trace: ${traceId}]`;
+    return new ToolResult(msg);
+  }
+
+  _list(filePath) {
+    const resolved = this._workspace.resolvePath(filePath);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+      return new ToolResult(`Not a directory: ${filePath}`, true);
+    }
+    const entries = fs.readdirSync(resolved, { withFileTypes: true });
+    entries.sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+    if (entries.length === 0) {
+      return new ToolResult("(empty directory)");
+    }
+    const lines = entries.map((e) => {
+      const rel = path.relative(this._workspace.cwd, path.join(resolved, e.name));
+      const marker = e.isDirectory() ? "[dir] " : "      ";
+      return `${marker}${rel}`;
+    });
+    return new ToolResult(lines.join("\n"));
+  }
+}

package/src/agent/version-manager.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const VERSIONED_DIRS = new Set(["workflows", "rule_skills", "rules"]);
+const VERSIONED_EXTS = new Set([".py", ".json", ".md", ".txt"]);
+
+/**
+ * Structural component: every write to versioned directories gets tracked.
+ * - Immutable version copies tracked in manifest
+ * - Manifest at versions.json: tracks lineage, timestamps, change reasons
+ * - Trace ID generation: {timestamp}_{rule_id}_{version}
+ * Cannot be bypassed — hooks into WorkspaceFileTool.
+ */
+export class VersionManager {
+  /**
+   * @param {string} workspacePath
+   */
+  constructor(workspacePath) {
+    this._workspace = workspacePath;
+    this._manifestPath = path.join(workspacePath, "versions.json");
+    this._manifest = this._loadManifest();
+  }
+
+  _loadManifest() {
+    if (fs.existsSync(this._manifestPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(this._manifestPath, "utf-8"));
+      } catch {
+        // fall through
+      }
+    }
+    return { version: "0.1.0", entries: [] };
+  }
+
+  _saveManifest() {
+    fs.writeFileSync(
+      this._manifestPath,
+      JSON.stringify(this._manifest, null, 2),
+      "utf-8",
+    );
+  }
+
+  /**
+   * Check if a path falls within versioned directories.
+   * @param {string} relPath
+   * @returns {boolean}
+   */
+  shouldVersion(relPath) {
+    const parts = relPath.split(path.sep);
+    if (parts.length === 0) return false;
+    const topDir = parts[0];
+    const ext = path.extname(relPath);
+    return VERSIONED_DIRS.has(topDir) && VERSIONED_EXTS.has(ext);
+  }
+
+  /**
+   * Called on file write. Returns trace ID if versioned, null otherwise.
+   * @param {string} relPath
+   * @param {string} content
+   * @returns {string|null}
+   */
+  onWrite(relPath, content) {
+    if (!this.shouldVersion(relPath)) return null;
+
+    const version = this._nextVersion(relPath);
+    const now = new Date().toISOString().replace(/[-:T]/g, (m) =>
+      m === "T" ? "_" : ""
+    ).slice(0, 15);
+
+    // Extract rule_id from path if possible (e.g., rule_skills/R001/SKILL.md → R001)
+    const parts = relPath.split(path.sep);
+    const ruleId = parts.length > 1 ? parts[1] : "global";
+
+    const traceId = `${now}_${ruleId}_v${version}`;
+
+    const entry = {
+      file: relPath,
+      version,
+      trace_id: traceId,
+      timestamp: new Date().toISOString(),
+      rule_id: ruleId,
+      size_chars: content.length,
+    };
+
+    this._manifest.entries.push(entry);
+    this._saveManifest();
+
+    return traceId;
+  }
+
+  _nextVersion(relPath) {
+    const existing = this._manifest.entries
+      .filter((e) => e.file === relPath)
+      .map((e) => e.version);
+    return Math.max(0, ...existing) + 1;
+  }
+
+  /**
+   * Get all version entries for a file.
+   * @param {string} relPath
+   * @returns {Array<object>}
+   */
+  getVersions(relPath) {
+    return this._manifest.entries.filter((e) => e.file === relPath);
+  }
+
+  /**
+   * Get the most recent version entry for a file.
+   * @param {string} relPath
+   * @returns {object|null}
+   */
+  latestVersion(relPath) {
+    const versions = this.getVersions(relPath);
+    return versions.length > 0 ? versions[versions.length - 1] : null;
+  }
+
+  /**
+   * Generate a standalone trace ID for results, QC records, etc.
+   * @param {string} ruleId
+   * @param {string} [label]
+   * @returns {string}
+   */
+  generateTraceId(ruleId, label = "") {
+    const now = new Date().toISOString().replace(/[-:T]/g, (m) =>
+      m === "T" ? "_" : ""
+    ).slice(0, 15);
+    const suffix = label ? `_${label}` : "";
+    return `${now}_${ruleId}${suffix}`;
+  }
+}

package/src/agent/workspace.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * Per-session workspace directory with path traversal protection.
+ * Each agent session gets its own directory under the workspace root.
+ * All file operations by tools must go through resolvePath().
+ */
+export class Workspace {
+  /**
+   * @param {string} root - Workspace root directory
+   * @param {string} [sessionId] - Session identifier (auto-generated if omitted)
+   */
+  constructor(root, sessionId) {
+    this.root = path.resolve(root);
+    this.sessionId = sessionId || crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+    this.path = path.resolve(this.root, this.sessionId);
+    fs.mkdirSync(this.path, { recursive: true });
+  }
+
+  /** @returns {string} Current workspace directory */
+  get cwd() {
+    return this.path;
+  }
+
+  /**
+   * Resolve a user-supplied relative path against the workspace.
+   * Rejects absolute paths and any path that escapes the workspace via .. or symlinks.
+   * @param {string} userPath
+   * @returns {string}
+   */
+  resolvePath(userPath) {
+    if (path.isAbsolute(userPath)) {
+      throw new Error(`Absolute paths not allowed: ${userPath}`);
+    }
+    const resolved = path.resolve(this.path, userPath);
+    const base = path.resolve(this.path);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+      throw new Error(`Path escapes workspace: ${userPath}`);
+    }
+    return resolved;
+  }
+
+  /**
+   * Rename the workspace folder. Returns the new sessionId.
+   * @param {string} newName
+   * @returns {string}
+   */
+  rename(newName) {
+    newName = newName.trim().replace(/ /g, "_").replace(/\//g, "_");
+    if (!newName) throw new Error("Name cannot be empty");
+    const newPath = path.join(this.root, newName);
+    if (fs.existsSync(newPath) && path.resolve(newPath) !== path.resolve(this.path)) {
+      throw new Error(`Session '${newName}' already exists`);
+    }
+    if (path.resolve(newPath) !== path.resolve(this.path)) {
+      fs.renameSync(this.path, newPath);
+      this.path = path.resolve(newPath);
+      this.sessionId = newName;
+    }
+    return this.sessionId;
+  }
+
+  /**
+   * List all workspace sessions with names.
+   * @param {string} root
+   * @returns {Array<{id: string}>}
+   */
+  static listSessions(root) {
+    root = path.resolve(root);
+    if (!fs.existsSync(root)) return [];
+    const sessions = [];
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.isDirectory() && !entry.name.startsWith(".")) {
+        sessions.push({ id: entry.name });
+      }
+    }
+    return sessions;
+  }
+}

package/src/cli/components.js

@@ -0,0 +1,164 @@
+import React, { useState, useEffect, useRef, useCallback } from "react";
+import { Box, Text, useInput, useApp, useStdout } from "ink";
+
+const h = React.createElement;
+
+// --- Cooking spinner ---
+
+const COOKING_WORDS = [
+  "Baking", "Blanching", "Brewing", "Caramelizing", "Cooking",
+  "Fermenting", "Flambéing", "Julienning", "Kneading", "Leavening",
+  "Marinating", "Proofing", "Sautéing", "Seasoning", "Simmering",
+  "Stewing", "Tempering", "Whisking", "Zesting", "Garnishing", "Drizzling",
+];
+
+export function CookingSpinner() {
+  const [idx, setIdx] = useState(Math.floor(Math.random() * COOKING_WORDS.length));
+
+  useEffect(() => {
+    const timer = setInterval(() => setIdx((i) => (i + 1) % COOKING_WORDS.length), 2000);
+    return () => clearInterval(timer);
+  }, []);
+
+  return h(Box, null,
+    h(Text, { color: "yellow" }, "  * "),
+    h(Text, { dimColor: true }, `${COOKING_WORDS[idx]}...`),
+  );
+}
+
+// --- Status bar ---
+
+const LENAT_QUOTE = "Intelligence is ten million rules.";
+
+export function StatusBar({ sessionId, phase }) {
+  return h(Box, { marginTop: 0 },
+    h(Text, { dimColor: true }, "  ⏵⏵  KC Agent CLI "),
+    h(Text, { dimColor: true }, sessionId ? `[${sessionId}]` : ""),
+    phase ? h(Text, { color: "cyan" }, ` ${phase.toUpperCase()}`) : null,
+    h(Text, { color: "green" }, "  ●  "),
+    h(Text, { dimColor: true }, `· ${LENAT_QUOTE}`),
+  );
+}
+
+// --- Welcome banner ---
+
+export function WelcomeBanner() {
+  return h(Box, { flexDirection: "column", marginBottom: 1 },
+    h(Text, null, ""),
+    h(Box, { justifyContent: "center" },
+      h(Text, { bold: true }, "KC AGENT CLI"),
+      h(Text, { dimColor: true }, "  (beta)"),
+    ),
+    h(Text, null, ""),
+    h(Text, { dimColor: true }, "        Hope you never know what KC was."),
+    h(Text, null, ""),
+    h(Text, { dimColor: true }, "        Product of Memium"),
+    h(Text, { dimColor: true }, "        kitchen-engineer42"),
+  );
+}
+
+// --- Tool block ---
+
+export function ToolBlock({ name, input, output, isError, isRunning }) {
+  const borderColor = isRunning ? "yellow" : isError ? "red" : "green";
+
+  return h(Box, { flexDirection: "column", marginLeft: 2 },
+    h(Box, null,
+      h(Text, { color: borderColor }, "┃ "),
+      h(Text, { dimColor: true }, name),
+      input ? h(Text, { dimColor: true }, ` ${JSON.stringify(input)}`) : null,
+    ),
+    output ? h(Box, { flexDirection: "column" },
+      ...output.split("\n").slice(0, 20).map((line, i) =>
+        h(Box, { key: i },
+          h(Text, { color: borderColor }, "┃ "),
+          h(Text, null, line),
+        ),
+      ),
+      output.split("\n").length > 20
+        ? h(Box, null,
+            h(Text, { color: borderColor }, "┃ "),
+            h(Text, { dimColor: true }, `... ${output.split("\n").length - 20} more lines`),
+          )
+        : null,
+    ) : null,
+  );
+}
+
+// --- Message display ---
+
+export function MessageBlock({ role, content, toolName, toolInput, toolOutput, toolIsError }) {
+  if (role === "user") {
+    return h(Box, null,
+      h(Text, { dimColor: true }, "❯ "),
+      h(Text, null, content),
+    );
+  }
+  if (role === "agent") {
+    return h(Box, null,
+      h(Text, null, content),
+    );
+  }
+  if (role === "tool") {
+    return h(ToolBlock, {
+      name: toolName,
+      input: toolInput,
+      output: toolOutput,
+      isError: toolIsError,
+      isRunning: false,
+    });
+  }
+  if (role === "system") {
+    return h(Box, null,
+      h(Text, { dimColor: true }, content),
+    );
+  }
+  return null;
+}
+
+// --- Horizontal rule ---
+
+export function HRule() {
+  const { stdout } = useStdout();
+  const cols = stdout?.columns || 80;
+  return h(Text, { dimColor: true }, "─".repeat(cols));
+}
+
+// --- Messages list ---
+
+export function MessagesList({ messages }) {
+  return h(Box, { flexDirection: "column" },
+    ...messages.map((msg, i) =>
+      h(MessageBlock, { key: i, ...msg }),
+    ),
+  );
+}
+
+// --- Input prompt ---
+
+export function InputPrompt({ value, onChange, onSubmit, isActive }) {
+  useInput((input, key) => {
+    if (!isActive) return;
+
+    if (key.return) {
+      onSubmit(value);
+      return;
+    }
+    if (key.backspace || key.delete) {
+      onChange(value.slice(0, -1));
+      return;
+    }
+    // Skip control characters
+    if (key.ctrl || key.meta || key.escape) return;
+    // Append printable characters
+    if (input) {
+      onChange(value + input);
+    }
+  }, { isActive });
+
+  return h(Box, null,
+    h(Text, { dimColor: true }, "❯ "),
+    h(Text, null, value),
+    isActive ? h(Text, { color: "gray" }, "█") : null,
+  );
+}