@oisheek_c/codeforge 1.0.1

package/packages/terminal/spinner.js

@@ -0,0 +1,9 @@
+import ora from "ora";
+
+export function createSpinner(text = "Loading...") {
+  return ora({
+    text,
+    spinner: "dots",
+    discardStdin: false
+  });
+}

package/packages/tools/editFile.js

@@ -0,0 +1,261 @@
+import fs from "node:fs/promises";
+
+import {
+  createToolError,
+  resolveProjectPath,
+} from "./filesystem.js";
+
+import {
+  defineTool,
+} from "../core/tool.js";
+
+function countOccurrences(
+  content,
+  search
+) {
+  let count = 0;
+  let position = 0;
+
+  while (true) {
+    const index =
+      content.indexOf(
+        search,
+        position
+      );
+
+    if (index === -1) {
+      return count;
+    }
+
+    count += 1;
+
+    position =
+      index + search.length;
+  }
+}
+
+export const editFileTool =
+  defineTool({
+    name: "edit_file",
+
+    description:
+  "Edit an existing UTF-8 text file inside the project by replacing exactly one occurrence of oldText with newText. Use this when the target file path and exact text to replace are known. The edit requires approval.",
+
+    source: "builtin",
+
+    capabilities: [
+      "filesystem.read",
+      "filesystem.write",
+    ],
+
+    sideEffect: "write",
+
+    approval: "policy",
+
+    inputSchema: {
+      type: "object",
+
+      properties: {
+        path: {
+          type: "string",
+          minLength: 1,
+          description:
+            "Path to the existing file relative to the project root.",
+        },
+
+        oldText: {
+          type: "string",
+          minLength: 1,
+          description:
+            "Exact existing text to replace. It must occur exactly once in the file.",
+        },
+
+        newText: {
+          type: "string",
+          description:
+            "Replacement text.",
+        },
+      },
+
+      required: [
+        "path",
+        "oldText",
+        "newText",
+      ],
+
+      additionalProperties: false,
+    },
+
+    async execute(
+      input,
+      context = {}
+    ) {
+      const filePath =
+        input?.path;
+
+      const oldText =
+        input?.oldText;
+
+      const newText =
+        input?.newText;
+
+      if (
+        typeof oldText !== "string" ||
+        oldText.length === 0
+      ) {
+        throw createToolError(
+          "invalid_old_text",
+          "oldText must be a non-empty string."
+        );
+      }
+
+      if (
+        typeof newText !== "string"
+      ) {
+        throw createToolError(
+          "invalid_new_text",
+          "newText must be a string."
+        );
+      }
+
+      const {
+        resolved,
+        relative,
+      } = resolveProjectPath(
+        context.projectRoot,
+        filePath
+      );
+
+      let stats;
+
+      try {
+        stats =
+          await fs.stat(
+            resolved
+          );
+      } catch (error) {
+        if (
+          error?.code === "ENOENT"
+        ) {
+          throw createToolError(
+            "file_not_found",
+            `File not found: ${relative}`
+          );
+        }
+
+        throw error;
+      }
+
+      if (!stats.isFile()) {
+        throw createToolError(
+          "path_not_file",
+          `Path is not a file: ${relative}`
+        );
+      }
+
+      let content;
+
+      try {
+        content =
+          await fs.readFile(
+            resolved,
+            "utf8"
+          );
+      } catch (error) {
+        throw createToolError(
+          "file_read_failed",
+          `Failed to read file: ${relative}`,
+          {
+            cause:
+              error?.message ??
+              String(error),
+          }
+        );
+      }
+
+      const occurrences =
+        countOccurrences(
+          content,
+          oldText
+        );
+
+      if (occurrences === 0) {
+        throw createToolError(
+          "edit_target_not_found",
+          `oldText was not found in file: ${relative}`
+        );
+      }
+
+      if (occurrences > 1) {
+        throw createToolError(
+          "edit_target_ambiguous",
+          `oldText occurs more than once in file: ${relative}`,
+          {
+            occurrences,
+          }
+        );
+      }
+
+      const updatedContent =
+        content.replace(
+          oldText,
+          newText
+        );
+
+      try {
+        await fs.writeFile(
+          resolved,
+          updatedContent,
+          {
+            encoding: "utf8",
+            flag: "w",
+          }
+        );
+      } catch (error) {
+        throw createToolError(
+          "file_write_failed",
+          `Failed to edit file: ${relative}`,
+          {
+            cause:
+              error?.message ??
+              String(error),
+          }
+        );
+      }
+
+      let after;
+
+      try {
+        after =
+          await fs.stat(
+            resolved
+          );
+      } catch (error) {
+        throw createToolError(
+          "file_verification_failed",
+          `Unable to verify edited file: ${relative}`,
+          {
+            cause:
+              error?.message ??
+              String(error),
+          }
+        );
+      }
+
+      if (!after.isFile()) {
+        throw createToolError(
+          "file_verification_failed",
+          `Edited path is not a file: ${relative}`
+        );
+      }
+
+      return {
+        path: relative,
+        previousSize:
+          stats.size,
+        size:
+          after.size,
+        replacements: 1,
+      };
+    },
+  });

package/packages/tools/filesystem.js

@@ -0,0 +1,82 @@
+import path from "node:path";
+
+export function createToolError(
+  code,
+  message,
+  details = null
+) {
+  const error = new Error(message);
+
+  error.code = code;
+  error.details = details;
+
+  return error;
+}
+
+export function resolveProjectPath(
+  projectRoot,
+  targetPath
+) {
+  if (
+    typeof projectRoot !== "string" ||
+    projectRoot.trim().length === 0
+  ) {
+    throw createToolError(
+      "project_root_required",
+      "Project root is required."
+    );
+  }
+
+  if (
+    typeof targetPath !== "string" ||
+    targetPath.trim().length === 0
+  ) {
+    throw createToolError(
+      "invalid_path",
+      "Path must be a non-empty string."
+    );
+  }
+
+  const root =
+    path.resolve(projectRoot);
+
+  const resolved =
+    path.resolve(
+      root,
+      targetPath
+    );
+
+  const relative =
+    path.relative(
+      root,
+      resolved
+    );
+
+  if (
+    relative === ".." ||
+    relative.startsWith(
+      `..${path.sep}`
+    ) ||
+    path.isAbsolute(relative)
+  ) {
+    throw createToolError(
+      "path_outside_project",
+      "Path is outside the project root."
+    );
+  }
+
+  return {
+    root,
+    resolved,
+    relative:
+      relative || ".",
+  };
+}
+
+export function normalizeProjectPath(
+  filePath
+) {
+  return filePath
+    .split(path.sep)
+    .join("/");
+}

package/packages/tools/index.js

@@ -0,0 +1,24 @@
+export {
+  readFileTool,
+} from "./readFile.js";
+
+export {
+  searchFilesTool,
+} from "./searchFiles.js";
+
+export {
+  writeFileTool,
+} from "./writeFile.js";
+
+export {
+  ToolRegistry,
+  createToolRegistry,
+} from "./registry.js";
+
+export {
+  editFileTool,
+} from "./editFile.js";
+
+export {
+  shellTool,
+} from "./shell.js";

package/packages/tools/readFile.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+
+import {
+  defineTool,
+} from "../core/tool.js";
+
+import {
+  createToolError,
+  normalizeProjectPath,
+  resolveProjectPath,
+} from "./filesystem.js";
+
+export const readFileTool = defineTool({
+  name: "read_file",
+
+  description:
+  "Read the contents of a UTF-8 text file inside the current project. Use this tool directly when the file path is already known; do not search for the filename with search_files first.",
+
+  source: "builtin",
+
+  capabilities: [
+    "filesystem.read",
+  ],
+
+  sideEffect: "none",
+
+  approval: "never",
+
+  inputSchema: {
+    type: "object",
+
+    properties: {
+      path: {
+        type: "string",
+        description:
+          "Path to the file relative to the project root.",
+      },
+    },
+
+    required: [
+      "path",
+    ],
+
+    additionalProperties: false,
+  },
+
+  async execute(
+    input,
+    context = {}
+  ) {
+    const {
+      resolved,
+      relative,
+    } = resolveProjectPath(
+      context.projectRoot,
+      input?.path
+    );
+
+    let stats;
+
+    try {
+      stats =
+        await fs.stat(
+          resolved
+        );
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        throw createToolError(
+          "file_not_found",
+          `File not found: ${input.path}`
+        );
+      }
+
+      throw error;
+    }
+
+    if (!stats.isFile()) {
+      throw createToolError(
+        "not_a_file",
+        `Path is not a file: ${input.path}`
+      );
+    }
+
+    const content =
+      await fs.readFile(
+        resolved,
+        "utf8"
+      );
+
+    return {
+      path:
+        normalizeProjectPath(
+          relative
+        ),
+
+      content,
+
+      size: stats.size,
+    };
+  },
+});

package/packages/tools/registry.js

@@ -0,0 +1,227 @@
+import {
+  isTool,
+} from "../core/tool.js";
+
+export class ToolRegistry {
+  constructor() {
+    this.tools = new Map();
+  }
+
+  /**
+   * Register a canonical CodeForge tool.
+   */
+  register(tool) {
+    if (!isTool(tool)) {
+      throw new TypeError(
+        "Invalid tool. Tools must be created with defineTool()."
+      );
+    }
+
+    if (this.tools.has(tool.name)) {
+      throw new Error(
+        `Tool already registered: ${tool.name}`
+      );
+    }
+
+    this.tools.set(tool.name, tool);
+
+    return tool;
+  }
+
+  /**
+   * Register multiple tools.
+   */
+  registerMany(tools) {
+    if (!Array.isArray(tools)) {
+      throw new TypeError(
+        "Tools must be an array."
+      );
+    }
+
+    for (const tool of tools) {
+      this.register(tool);
+    }
+
+    return this;
+  }
+
+  /**
+   * Resolve a tool by its canonical name.
+   */
+  get(name) {
+    if (typeof name !== "string") {
+      return null;
+    }
+
+    return this.tools.get(name) ?? null;
+  }
+
+  /**
+   * Check whether a tool exists.
+   */
+  has(name) {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Remove a registered tool.
+   */
+  unregister(name) {
+    return this.tools.delete(name);
+  }
+
+  /**
+   * Remove all registered tools.
+   */
+  clear() {
+    this.tools.clear();
+  }
+
+  /**
+   * Return every registered tool.
+   */
+  values() {
+    return [...this.tools.values()];
+  }
+
+  /**
+   * Return all registered tool names.
+   */
+  names() {
+    return [...this.tools.keys()];
+  }
+
+  /**
+   * Number of registered tools.
+   */
+  size() {
+    return this.tools.size;
+  }
+
+  /**
+   * Find tools exposing a capability.
+   */
+  findByCapability(capability) {
+    if (typeof capability !== "string") {
+      return [];
+    }
+
+    return this.values().filter(
+      (tool) =>
+        tool.capabilities.includes(
+          capability
+        )
+    );
+  }
+
+  /**
+   * Find tools originating from a source.
+   *
+   * Examples:
+   * builtin
+   * plugin
+   * mcp
+   */
+  findBySource(source) {
+    if (typeof source !== "string") {
+      return [];
+    }
+
+    return this.values().filter(
+      (tool) => tool.source === source
+    );
+  }
+
+  /**
+   * Create a restricted view of the registry.
+   *
+   * This becomes important for sub-agents,
+   * approval scopes, plugins, and autonomous
+   * workflows.
+   */
+  select({
+    names = null,
+    capabilities = null,
+    sources = null,
+  } = {}) {
+    let tools = this.values();
+
+    if (Array.isArray(names)) {
+      const allowed =
+        new Set(names);
+
+      tools = tools.filter(
+        (tool) =>
+          allowed.has(tool.name)
+      );
+    }
+
+    if (Array.isArray(capabilities)) {
+      const required =
+        new Set(capabilities);
+
+      tools = tools.filter(
+        (tool) =>
+          [...required].every(
+            (capability) =>
+              tool.capabilities.includes(
+                capability
+              )
+          )
+      );
+    }
+
+    if (Array.isArray(sources)) {
+      const allowed =
+        new Set(sources);
+
+      tools = tools.filter(
+        (tool) =>
+          allowed.has(tool.source)
+      );
+    }
+
+    return tools;
+  }
+
+  /**
+   * Metadata suitable for model/tool discovery.
+   *
+   * execute() is intentionally excluded.
+   */
+  describe() {
+    return this.values().map(
+      (tool) => ({
+        name: tool.name,
+        description:
+          tool.description,
+        version:
+          tool.version,
+        source:
+          tool.source,
+        inputSchema:
+          tool.inputSchema,
+        capabilities:
+          [...tool.capabilities],
+        sideEffect:
+          tool.sideEffect,
+        approval:
+          tool.approval,
+      })
+    );
+  }
+}
+
+/**
+ * Factory.
+ */
+export function createToolRegistry(
+  tools = []
+) {
+  const registry =
+    new ToolRegistry();
+
+  registry.registerMany(tools);
+
+  return registry;
+}