@gokulvenkatareddy/cortex 0.1.7

package/apps/octogent/apps/api/src/projectPersistence.ts

@@ -0,0 +1,377 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  appendFileSync,
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+export const GLOBAL_OCTOGENT_DIR = join(homedir(), ".octogent");
+export const PROJECTS_FILE = join(GLOBAL_OCTOGENT_DIR, "projects.json");
+export const PROJECT_CONFIG_RELATIVE_PATH = join(".octogent", "project.json");
+
+type ProjectConfigDocument = {
+  version: 1;
+  projectId: string;
+  displayName: string;
+  createdAt: string;
+};
+
+export type ProjectRegistryEntry = {
+  id: string;
+  name: string;
+  path: string;
+  createdAt: string;
+  lastOpenedAt?: string;
+};
+
+type LegacyProjectRegistryEntry = {
+  name?: unknown;
+  path?: unknown;
+  createdAt?: unknown;
+};
+
+export type ProjectsRegistry = { projects: ProjectRegistryEntry[] };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const toProjectRegistryEntry = (
+  value: unknown,
+  workspaceCwd?: string,
+): ProjectRegistryEntry | null => {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  if (
+    typeof value.id === "string" &&
+    value.id.trim().length > 0 &&
+    typeof value.name === "string" &&
+    value.name.trim().length > 0 &&
+    typeof value.path === "string" &&
+    value.path.trim().length > 0 &&
+    typeof value.createdAt === "string" &&
+    value.createdAt.trim().length > 0
+  ) {
+    return {
+      id: value.id,
+      name: value.name,
+      path: value.path,
+      createdAt: value.createdAt,
+      ...(typeof value.lastOpenedAt === "string" && value.lastOpenedAt.trim().length > 0
+        ? { lastOpenedAt: value.lastOpenedAt }
+        : {}),
+    };
+  }
+
+  if (
+    workspaceCwd &&
+    typeof value.name === "string" &&
+    value.name.trim().length > 0 &&
+    typeof value.path === "string" &&
+    value.path === workspaceCwd
+  ) {
+    return {
+      id: `legacy-${randomUUID()}`,
+      name: value.name,
+      path: value.path,
+      createdAt:
+        typeof value.createdAt === "string" && value.createdAt.trim().length > 0
+          ? value.createdAt
+          : new Date().toISOString(),
+    };
+  }
+
+  return null;
+};
+
+const toProjectConfigDocument = (value: unknown): ProjectConfigDocument | null => {
+  if (
+    !isRecord(value) ||
+    value.version !== 1 ||
+    typeof value.projectId !== "string" ||
+    value.projectId.trim().length === 0 ||
+    typeof value.displayName !== "string" ||
+    value.displayName.trim().length === 0 ||
+    typeof value.createdAt !== "string" ||
+    value.createdAt.trim().length === 0
+  ) {
+    return null;
+  }
+
+  return {
+    version: 1,
+    projectId: value.projectId,
+    displayName: value.displayName,
+    createdAt: value.createdAt,
+  };
+};
+
+const readJsonFile = (filePath: string): unknown | null => {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+  } catch {
+    return null;
+  }
+};
+
+export const ensureGlobalOctogentDir = () => {
+  if (!existsSync(GLOBAL_OCTOGENT_DIR)) {
+    mkdirSync(GLOBAL_OCTOGENT_DIR, { recursive: true });
+  }
+};
+
+export const loadProjectsRegistry = (): ProjectsRegistry => {
+  ensureGlobalOctogentDir();
+
+  if (!existsSync(PROJECTS_FILE)) {
+    return { projects: [] };
+  }
+
+  const parsed = readJsonFile(PROJECTS_FILE);
+  if (!isRecord(parsed) || !Array.isArray(parsed.projects)) {
+    return { projects: [] };
+  }
+
+  return {
+    projects: parsed.projects
+      .map((entry) => toProjectRegistryEntry(entry))
+      .filter((entry): entry is ProjectRegistryEntry => entry !== null),
+  };
+};
+
+export const saveProjectsRegistry = (registry: ProjectsRegistry) => {
+  ensureGlobalOctogentDir();
+  writeFileSync(PROJECTS_FILE, `${JSON.stringify(registry, null, 2)}\n`, "utf8");
+};
+
+export const resolveProjectConfigPath = (workspaceCwd: string) =>
+  join(workspaceCwd, PROJECT_CONFIG_RELATIVE_PATH);
+
+export const deriveProjectIdFromWorkspace = (workspaceCwd: string) =>
+  `workspace-${createHash("sha1").update(workspaceCwd).digest("hex").slice(0, 16)}`;
+
+const inferLegacyProjectName = (workspaceCwd: string): string | null => {
+  const parsed = readJsonFile(PROJECTS_FILE);
+  if (!isRecord(parsed) || !Array.isArray(parsed.projects)) {
+    return null;
+  }
+
+  for (const legacyEntry of parsed.projects as LegacyProjectRegistryEntry[]) {
+    if (legacyEntry.path === workspaceCwd && typeof legacyEntry.name === "string") {
+      return legacyEntry.name;
+    }
+  }
+
+  return null;
+};
+
+export const loadProjectConfig = (workspaceCwd: string): ProjectConfigDocument | null => {
+  const configPath = resolveProjectConfigPath(workspaceCwd);
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  return toProjectConfigDocument(readJsonFile(configPath));
+};
+
+export const ensureProjectConfig = (
+  workspaceCwd: string,
+  preferredName?: string,
+  preferredProjectId?: string,
+): ProjectConfigDocument => {
+  const existing = loadProjectConfig(workspaceCwd);
+  if (existing) {
+    return existing;
+  }
+
+  const displayName =
+    preferredName?.trim() ||
+    inferLegacyProjectName(workspaceCwd) ||
+    basename(workspaceCwd) ||
+    "octogent-project";
+  const config: ProjectConfigDocument = {
+    version: 1,
+    projectId: preferredProjectId?.trim() || randomUUID(),
+    displayName,
+    createdAt: new Date().toISOString(),
+  };
+
+  const configPath = resolveProjectConfigPath(workspaceCwd);
+  mkdirSync(join(workspaceCwd, ".octogent"), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return config;
+};
+
+export const registerProject = (
+  workspaceCwd: string,
+  preferredName?: string,
+): ProjectRegistryEntry => {
+  const projectConfig = ensureProjectConfig(workspaceCwd, preferredName);
+  const registry = loadProjectsRegistry();
+  const lastOpenedAt = new Date().toISOString();
+  const existing = registry.projects.find((entry) => entry.id === projectConfig.projectId);
+
+  if (existing) {
+    existing.name = projectConfig.displayName;
+    existing.path = workspaceCwd;
+    existing.lastOpenedAt = lastOpenedAt;
+    saveProjectsRegistry(registry);
+    return existing;
+  }
+
+  const nextEntry: ProjectRegistryEntry = {
+    id: projectConfig.projectId,
+    name: projectConfig.displayName,
+    path: workspaceCwd,
+    createdAt: projectConfig.createdAt,
+    lastOpenedAt,
+  };
+
+  const filteredProjects = registry.projects.filter(
+    (entry) => entry.path !== workspaceCwd && entry.id !== projectConfig.projectId,
+  );
+  filteredProjects.push(nextEntry);
+  saveProjectsRegistry({ projects: filteredProjects });
+  return nextEntry;
+};
+
+export const resolveGlobalProjectDir = (projectId: string) =>
+  join(GLOBAL_OCTOGENT_DIR, "projects", projectId);
+
+export const resolveEphemeralProjectStateDir = (workspaceCwd: string) =>
+  resolveGlobalProjectDir(deriveProjectIdFromWorkspace(workspaceCwd));
+
+export const resolveProjectStateDir = (workspaceCwd: string, preferredName?: string): string => {
+  const entry = registerProject(workspaceCwd, preferredName);
+  const projectDir = resolveGlobalProjectDir(entry.id);
+  mkdirSync(join(projectDir, "state"), { recursive: true });
+  return projectDir;
+};
+
+export const ensureProjectScaffold = (
+  workspaceCwd: string,
+  preferredName?: string,
+  preferredProjectId?: string,
+) => {
+  const octogentDir = join(workspaceCwd, ".octogent");
+  for (const subdirectory of ["tentacles", "worktrees"]) {
+    mkdirSync(join(octogentDir, subdirectory), { recursive: true });
+  }
+
+  return ensureProjectConfig(workspaceCwd, preferredName, preferredProjectId);
+};
+
+export const hasOctogentGitignoreEntry = (workspaceCwd: string) => {
+  const gitignorePath = join(workspaceCwd, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    return false;
+  }
+
+  const content = readFileSync(gitignorePath, "utf-8");
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .includes(".octogent");
+};
+
+export const ensureOctogentGitignoreEntry = (workspaceCwd: string) => {
+  const gitignorePath = join(workspaceCwd, ".gitignore");
+  const entry = ".octogent";
+
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    if (
+      content
+        .split("\n")
+        .map((line) => line.trim())
+        .includes(entry)
+    ) {
+      return { changed: false };
+    }
+
+    appendFileSync(gitignorePath, `\n${entry}\n`, "utf-8");
+    return { changed: true };
+  }
+
+  writeFileSync(gitignorePath, `${entry}\n`, "utf-8");
+  return { changed: true };
+};
+
+export const migrateStateToGlobal = (workspaceCwd: string, projectStateDir: string) => {
+  const fallbackProjectDir = join(workspaceCwd, ".octogent");
+  if (projectStateDir === fallbackProjectDir) {
+    return;
+  }
+
+  const currentConfig = loadProjectConfig(workspaceCwd);
+  const legacyProjectName = inferLegacyProjectName(workspaceCwd);
+  const legacyGlobalProjectDir =
+    legacyProjectName && currentConfig
+      ? join(GLOBAL_OCTOGENT_DIR, "projects", legacyProjectName)
+      : null;
+  const oldStateDir = join(fallbackProjectDir, "state");
+  const newStateDir = join(projectStateDir, "state");
+
+  mkdirSync(newStateDir, { recursive: true });
+
+  const stateFiles = [
+    "tentacles.json",
+    "deck.json",
+    "monitor-config.json",
+    "monitor-cache.json",
+    "code-intel-events.jsonl",
+    "claude-usage-snapshot.json",
+    "runtime.json",
+  ];
+
+  let migrated = 0;
+  for (const file of stateFiles) {
+    const destination = join(newStateDir, file);
+    if (existsSync(destination)) {
+      continue;
+    }
+
+    const localSource = join(oldStateDir, file);
+    if (existsSync(localSource)) {
+      copyFileSync(localSource, destination);
+      migrated += 1;
+      continue;
+    }
+
+    if (!legacyGlobalProjectDir) {
+      continue;
+    }
+
+    const legacySource = join(legacyGlobalProjectDir, "state", file);
+    if (existsSync(legacySource)) {
+      copyFileSync(legacySource, destination);
+      migrated += 1;
+    }
+  }
+
+  const transcriptDestination = join(newStateDir, "transcripts");
+  if (!existsSync(transcriptDestination)) {
+    const localTranscriptSource = join(oldStateDir, "transcripts");
+    if (existsSync(localTranscriptSource)) {
+      cpSync(localTranscriptSource, transcriptDestination, { recursive: true });
+      migrated += 1;
+    } else if (legacyGlobalProjectDir) {
+      const legacyTranscriptSource = join(legacyGlobalProjectDir, "state", "transcripts");
+      if (existsSync(legacyTranscriptSource)) {
+        cpSync(legacyTranscriptSource, transcriptDestination, { recursive: true });
+        migrated += 1;
+      }
+    }
+  }
+
+  if (migrated > 0) {
+    console.log(`  Migrated state to ${projectStateDir}`);
+  }
+};

package/apps/octogent/apps/api/src/prompts/index.ts

@@ -0,0 +1,10 @@
+export {
+  interpolatePrompt,
+  readPromptTemplate,
+  resolvePrompt,
+  listPromptTemplates,
+  listAllPrompts,
+  readPromptFromDirs,
+  writeUserPrompt,
+  deleteUserPrompt,
+} from "./promptResolver";

package/apps/octogent/apps/api/src/prompts/promptResolver.ts

@@ -0,0 +1,145 @@
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Interpolate `{{key}}` placeholders in a template string with values from the
+ * provided variables map. Unknown placeholders are left as-is.
+ */
+export const interpolatePrompt = (template: string, variables: Record<string, string>): string =>
+  template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => variables[key] ?? match);
+
+/**
+ * Read a prompt template from `<promptsDir>/<name>.md` and return the raw
+ * template string. Returns `undefined` if the file does not exist.
+ */
+export const readPromptTemplate = async (
+  promptsDir: string,
+  name: string,
+): Promise<string | undefined> => {
+  // Guard against path traversal.
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+    return undefined;
+  }
+
+  const filePath = join(promptsDir, `${name}.md`);
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return content.trimEnd();
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Read and resolve a prompt template, interpolating the given variables.
+ * Returns `undefined` if the template does not exist.
+ */
+export const resolvePrompt = async (
+  promptsDir: string,
+  name: string,
+  variables: Record<string, string>,
+): Promise<string | undefined> => {
+  const template = await readPromptTemplate(promptsDir, name);
+  if (template === undefined) {
+    return undefined;
+  }
+  return interpolatePrompt(template, variables);
+};
+
+/**
+ * List all available prompt template names (file basenames without `.md`).
+ */
+export const listPromptTemplates = async (promptsDir: string): Promise<string[]> => {
+  try {
+    const entries = await readdir(promptsDir);
+    return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(/\.md$/, ""));
+  } catch {
+    return [];
+  }
+};
+
+// ─── Multi-directory helpers (builtin + user) ─────────────────────────────
+
+type PromptEntry = { name: string; source: "builtin" | "user" };
+
+/**
+ * List prompts from both built-in and user directories.
+ * User prompts shadow built-in prompts with the same name.
+ */
+export const listAllPrompts = async (
+  builtinDir: string,
+  userDir: string,
+): Promise<PromptEntry[]> => {
+  const [builtinNames, userNames] = await Promise.all([
+    listPromptTemplates(builtinDir),
+    listPromptTemplates(userDir),
+  ]);
+
+  const seen = new Set<string>();
+  const result: PromptEntry[] = [];
+
+  for (const name of userNames) {
+    seen.add(name);
+    result.push({ name, source: "user" });
+  }
+  for (const name of builtinNames) {
+    if (!seen.has(name)) {
+      result.push({ name, source: "builtin" });
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Read a prompt from user dir first, falling back to builtin dir.
+ */
+export const readPromptFromDirs = async (
+  builtinDir: string,
+  userDir: string,
+  name: string,
+): Promise<{ name: string; source: "builtin" | "user"; content: string } | undefined> => {
+  const userContent = await readPromptTemplate(userDir, name);
+  if (userContent !== undefined) {
+    return { name, source: "user", content: userContent };
+  }
+  const builtinContent = await readPromptTemplate(builtinDir, name);
+  if (builtinContent !== undefined) {
+    return { name, source: "builtin", content: builtinContent };
+  }
+  return undefined;
+};
+
+const VALID_PROMPT_NAME = /^[\w][\w.-]*$/;
+
+/**
+ * Write a user prompt to the user prompts directory.
+ */
+export const writeUserPrompt = async (
+  userDir: string,
+  name: string,
+  content: string,
+): Promise<boolean> => {
+  if (!VALID_PROMPT_NAME.test(name) || name.includes("..")) {
+    return false;
+  }
+  await mkdir(userDir, { recursive: true });
+  await writeFile(join(userDir, `${name}.md`), content, "utf-8");
+  return true;
+};
+
+/**
+ * Delete a user prompt from the user prompts directory.
+ */
+export const deleteUserPrompt = async (userDir: string, name: string): Promise<boolean> => {
+  if (!VALID_PROMPT_NAME.test(name) || name.includes("..")) {
+    return false;
+  }
+  try {
+    await rm(join(userDir, `${name}.md`));
+    return true;
+  } catch {
+    return false;
+  }
+};

package/apps/octogent/apps/api/src/runtimeMetadata.ts

@@ -0,0 +1,69 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type RuntimeMetadata = {
+  apiBaseUrl: string;
+  host: string;
+  port: number;
+  pid: number;
+  startedAt: string;
+  workspaceCwd: string;
+};
+
+const RUNTIME_METADATA_FILENAME = "runtime.json";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const resolveRuntimeMetadataPath = (projectStateDir: string) =>
+  join(projectStateDir, "state", RUNTIME_METADATA_FILENAME);
+
+export const readRuntimeMetadata = (projectStateDir: string): RuntimeMetadata | null => {
+  const filePath = resolveRuntimeMetadataPath(projectStateDir);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+    if (
+      !isRecord(parsed) ||
+      typeof parsed.apiBaseUrl !== "string" ||
+      typeof parsed.host !== "string" ||
+      typeof parsed.port !== "number" ||
+      !Number.isFinite(parsed.port) ||
+      typeof parsed.pid !== "number" ||
+      !Number.isFinite(parsed.pid) ||
+      typeof parsed.startedAt !== "string" ||
+      typeof parsed.workspaceCwd !== "string"
+    ) {
+      return null;
+    }
+
+    return {
+      apiBaseUrl: parsed.apiBaseUrl,
+      host: parsed.host,
+      port: parsed.port,
+      pid: parsed.pid,
+      startedAt: parsed.startedAt,
+      workspaceCwd: parsed.workspaceCwd,
+    };
+  } catch {
+    return null;
+  }
+};
+
+export const writeRuntimeMetadata = (projectStateDir: string, metadata: RuntimeMetadata) => {
+  const filePath = resolveRuntimeMetadataPath(projectStateDir);
+  mkdirSync(join(projectStateDir, "state"), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+};
+
+export const clearRuntimeMetadata = (projectStateDir: string) => {
+  const filePath = resolveRuntimeMetadataPath(projectStateDir);
+  if (!existsSync(filePath)) {
+    return;
+  }
+
+  rmSync(filePath, { force: true });
+};

package/apps/octogent/apps/api/src/server.ts

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { createApiServer } from "./createApiServer";
+
+const parsePort = (value: string | undefined, fallback: number) => {
+  if (!value) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+    return fallback;
+  }
+  return parsed;
+};
+
+const host = process.env.HOST ?? "127.0.0.1";
+const port = parsePort(process.env.OCTOGENT_API_PORT ?? process.env.PORT, 8787);
+const allowRemoteAccess = process.env.OCTOGENT_ALLOW_REMOTE_ACCESS === "1";
+const workspaceCwd = process.env.OCTOGENT_WORKSPACE_CWD ?? process.cwd();
+const projectStateDir = process.env.OCTOGENT_PROJECT_STATE_DIR;
+const promptsDir = process.env.OCTOGENT_PROMPTS_DIR;
+const webDistDir = process.env.OCTOGENT_WEB_DIST_DIR;
+
+// Validate startup environment
+const validateStartupEnv = () => {
+  const rawPort = process.env.OCTOGENT_API_PORT ?? process.env.PORT;
+  if (rawPort !== undefined) {
+    const parsed = Number.parseInt(rawPort, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+      console.error(`Invalid port "${rawPort}": must be an integer between 1 and 65535.`);
+      process.exit(1);
+    }
+  }
+
+  if (process.env.OCTOGENT_WORKSPACE_CWD && !existsSync(process.env.OCTOGENT_WORKSPACE_CWD)) {
+    console.error(
+      `OCTOGENT_WORKSPACE_CWD directory does not exist: ${process.env.OCTOGENT_WORKSPACE_CWD}`,
+    );
+    process.exit(1);
+  }
+
+  if (process.env.OCTOGENT_WEB_DIST_DIR && !existsSync(process.env.OCTOGENT_WEB_DIST_DIR)) {
+    console.warn(
+      `OCTOGENT_WEB_DIST_DIR directory does not exist: ${process.env.OCTOGENT_WEB_DIST_DIR} — web UI will be unavailable.`,
+    );
+  }
+};
+
+validateStartupEnv();
+
+const apiServer = createApiServer({
+  workspaceCwd,
+  projectStateDir,
+  promptsDir,
+  webDistDir,
+  allowRemoteAccess,
+});
+
+const shutdown = async () => {
+  await apiServer.stop();
+  process.exit(0);
+};
+
+process.on("SIGINT", () => {
+  void shutdown();
+});
+
+process.on("SIGTERM", () => {
+  void shutdown();
+});
+
+apiServer
+  .start(port, host)
+  .then(({ port: activePort }) => {
+    console.log(`Octogent API listening on http://${host}:${activePort}`);
+  })
+  .catch((error: unknown) => {
+    console.error(error);
+    process.exit(1);
+  });