ubume 0.1.0

package/src/core/workspace/launchContext.ts

@@ -0,0 +1,259 @@
+import { statSync } from "fs";
+import { basename, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { resolveWorkspacePath } from "./workspaceGuard.js";
+import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
+import { UBUME_CHANNEL_ENV, LOCAL_DEV_CHANNEL, isLocalDevChannel } from "../version/channel.js";
+
+export type LaunchKind = "installed-bin" | "dev-run";
+
+export interface LaunchContext {
+  workspaceRoot: string;
+  packageRoot: string;
+  launchKind: LaunchKind;
+  launcherScriptPath?: string;
+  relaunchExecutable: string;
+  relaunchArgs: string[];
+}
+
+export interface ResolveLaunchContextOptions {
+  env?: NodeJS.ProcessEnv;
+  workspaceRoot?: string;
+  packageRoot?: string;
+  execPath?: string;
+  hasBunRuntime?: boolean;
+  forwardArgs?: string[];
+}
+
+export interface WorkspaceCommandContext {
+  root: string;
+  summaryMessage: string;
+}
+
+export interface WorkspaceRelaunchPlan {
+  executable: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  targetWorkspaceRoot: string;
+}
+
+export type WorkspaceRelaunchPlanResult =
+  | { ok: true; plan: WorkspaceRelaunchPlan }
+  | { ok: false; message: string };
+
+const ENV_KEYS = {
+  workspaceRoot: "CODEX_WORKSPACE_ROOT",
+  launchKind: "UBUME_LAUNCH_KIND",
+  packageRoot: "UBUME_PACKAGE_ROOT",
+  launcherScript: "UBUME_LAUNCHER_SCRIPT",
+  relaunchExecutable: "UBUME_RELAUNCH_EXECUTABLE",
+  relaunchArgs: "UBUME_RELAUNCH_ARGS",
+} as const;
+
+function getDefaultPackageRoot(): string {
+  return normalizeWorkspaceRoot(resolve(fileURLToPath(new URL(".", import.meta.url)), "..", ".."));
+}
+
+function parseRelaunchArgs(raw: string | undefined): string[] | null {
+  const value = raw?.trim();
+  if (!value) return null;
+
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
+      return null;
+    }
+
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function isBunExecutable(execPath: string): boolean {
+  return basename(execPath).toLowerCase().startsWith("bun");
+}
+
+function getDevRelaunchExecutable(execPath: string, hasBunRuntime: boolean): string {
+  if (hasBunRuntime || isBunExecutable(execPath)) {
+    return execPath;
+  }
+
+  return "bun";
+}
+
+function buildInstalledRelaunchArgs(launcherScriptPath: string, forwardArgs: readonly string[]): string[] {
+  return [launcherScriptPath, ...forwardArgs];
+}
+
+function buildDevRelaunchArgs(packageRoot: string, forwardArgs: readonly string[]): string[] {
+  const args = ["run", "--silent", join(packageRoot, "src", "index.tsx")];
+  if (forwardArgs.length > 0) {
+    args.push("--", ...forwardArgs);
+  }
+  return args;
+}
+
+export function resolveLaunchContext(options: ResolveLaunchContextOptions = {}): LaunchContext {
+  const env = options.env ?? process.env;
+  const workspaceRoot = normalizeWorkspaceRoot(
+    options.workspaceRoot ?? env[ENV_KEYS.workspaceRoot] ?? process.cwd(),
+  );
+  const packageRoot = normalizeWorkspaceRoot(
+    env[ENV_KEYS.packageRoot] ?? options.packageRoot ?? getDefaultPackageRoot(),
+  );
+  const launchKind = env[ENV_KEYS.launchKind] === "installed-bin" ? "installed-bin" : "dev-run";
+  const launcherScriptPath = env[ENV_KEYS.launcherScript]?.trim() || undefined;
+  const envRelaunchExecutable = env[ENV_KEYS.relaunchExecutable]?.trim();
+  const envRelaunchArgs = parseRelaunchArgs(env[ENV_KEYS.relaunchArgs]);
+  const execPath = options.execPath ?? process.execPath;
+  const hasBunRuntime = options.hasBunRuntime ?? Boolean(process.versions.bun);
+  const forwardArgs = options.forwardArgs ?? process.argv.slice(2);
+
+  if (launchKind === "installed-bin") {
+    const resolvedLauncherScript = launcherScriptPath ?? join(packageRoot, "bin", "ubume.js");
+
+    return {
+      workspaceRoot,
+      packageRoot,
+      launchKind,
+      launcherScriptPath: resolvedLauncherScript,
+      relaunchExecutable: envRelaunchExecutable || execPath,
+      relaunchArgs: envRelaunchArgs && envRelaunchArgs.length > 0
+        ? envRelaunchArgs
+        : buildInstalledRelaunchArgs(resolvedLauncherScript, forwardArgs),
+    };
+  }
+
+  return {
+    workspaceRoot,
+    packageRoot,
+    launchKind: "dev-run",
+    launcherScriptPath,
+    relaunchExecutable: envRelaunchExecutable || getDevRelaunchExecutable(execPath, hasBunRuntime),
+    relaunchArgs: envRelaunchArgs && envRelaunchArgs.length > 0
+      ? envRelaunchArgs
+      : buildDevRelaunchArgs(packageRoot, forwardArgs),
+  };
+}
+
+export function buildWorkspaceCommandContext(launchContext: LaunchContext): WorkspaceCommandContext {
+  return {
+    root: launchContext.workspaceRoot,
+    summaryMessage: buildWorkspaceStatusMessage(launchContext),
+  };
+}
+
+export function buildWorkspaceStatusMessage(launchContext: LaunchContext): string {
+  const lines = [
+    "Active workspace:",
+    `  ${launchContext.workspaceRoot}`,
+    "",
+    `Launch mode: ${launchContext.launchKind === "installed-bin" ? "installed ubume" : "dev/repo launch"}`,
+    "",
+  ];
+
+  if (launchContext.launchKind === "dev-run") {
+    lines.push(
+      "This session was started from a local dev launch.",
+      "Recommended setup:",
+      "  npm run install:dev-bin",
+      "  which ubume-dev",
+      "  cd <target-folder>",
+      "  ubume-dev",
+      "",
+      "Quick recovery from here:",
+      "  /workspace relaunch <path>",
+    );
+  } else {
+    lines.push(
+      "This session is locked to the folder where you launched ubume.",
+      "Use /workspace relaunch <path> to restart into another folder from inside this UI.",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function buildDevLaunchNotice(launchContext: LaunchContext): string | null {
+  if (launchContext.launchKind !== "dev-run") {
+    return null;
+  }
+
+  return [
+    "Ready. Type a prompt, run !shell, or use /command.",
+    "Tip: /workspace relaunch <path>",
+  ].join("\n");
+}
+
+export function guardWorkspaceRelaunch(busy: boolean): { allowed: boolean; message?: string } {
+  if (!busy) {
+    return { allowed: true };
+  }
+
+  return {
+    allowed: false,
+    message: "Finish the current run before relaunching into another workspace.",
+  };
+}
+
+function buildRelaunchEnv(
+  launchContext: LaunchContext,
+  targetWorkspaceRoot: string,
+  baseEnv: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+  return {
+    ...baseEnv,
+    [ENV_KEYS.workspaceRoot]: targetWorkspaceRoot,
+    [ENV_KEYS.launchKind]: launchContext.launchKind,
+    [ENV_KEYS.packageRoot]: launchContext.packageRoot,
+    [ENV_KEYS.launcherScript]: launchContext.launcherScriptPath ?? "",
+    [ENV_KEYS.relaunchExecutable]: launchContext.relaunchExecutable,
+    [ENV_KEYS.relaunchArgs]: JSON.stringify(launchContext.relaunchArgs),
+    [UBUME_CHANNEL_ENV]: isLocalDevChannel(baseEnv) ? LOCAL_DEV_CHANNEL : baseEnv[UBUME_CHANNEL_ENV],
+  };
+}
+
+export function createWorkspaceRelaunchPlan(
+  targetInput: string,
+  launchContext: LaunchContext,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): WorkspaceRelaunchPlanResult {
+  const trimmedTarget = targetInput.trim();
+  if (!trimmedTarget) {
+    return { ok: false, message: "Usage: /workspace relaunch <path>" };
+  }
+
+  const targetWorkspaceRoot = normalizeWorkspaceRoot(
+    resolveWorkspacePath(trimmedTarget, launchContext.workspaceRoot),
+  );
+
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(targetWorkspaceRoot);
+  } catch {
+    return {
+      ok: false,
+      message: `Workspace relaunch failed: ${targetWorkspaceRoot} does not exist.`,
+    };
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      ok: false,
+      message: `Workspace relaunch failed: ${targetWorkspaceRoot} is not a directory.`,
+    };
+  }
+
+  return {
+    ok: true,
+    plan: {
+      executable: launchContext.relaunchExecutable,
+      args: launchContext.relaunchArgs,
+      cwd: targetWorkspaceRoot,
+      env: buildRelaunchEnv(launchContext, targetWorkspaceRoot, baseEnv),
+      targetWorkspaceRoot,
+    },
+  };
+}

package/src/core/workspace/planStorage.ts

@@ -0,0 +1,135 @@
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { isNoiseLine } from "../providers/codexTranscript.js";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import { resolveUbumeDataDir } from "./appData.js";
+
+type Platform = "win32" | "darwin" | "linux" | string;
+
+const SECTION_LINE_RE = /^\s*(?:#{1,3}\s+)?(?:\*\*)?([A-Za-z][A-Za-z0-9 /&-]{0,48})(?:\*\*)?:?\s*$/;
+const ABSOLUTE_WINDOWS_PATH_RE = /[A-Za-z]:[\\/][^\s`),;\]]+/g;
+
+function normalizePathSeparators(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+function replaceAllLiteral(value: string, search: string, replacement: string): string {
+  if (!search) return value;
+  return value.split(search).join(replacement);
+}
+
+/**
+ * Strips absolute filesystem paths from plan text, replacing them with
+ * relative paths or truncated versions to protect user privacy.
+ */
+export function hidePlanReviewFilesystemDetails(planText: string, workspaceRoot?: string | null): string {
+  let output = planText;
+  const normalizedRoot = workspaceRoot?.trim() ? normalizePathSeparators(workspaceRoot.trim()).replace(/\/+$/, "") : "";
+
+  if (normalizedRoot) {
+    output = replaceAllLiteral(output, workspaceRoot!.replace(/\\+$/, ""), "");
+    output = replaceAllLiteral(normalizePathSeparators(output), normalizedRoot, "");
+    output = output.replace(/(^|[\s(`])\/+([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+)/g, "$1$2");
+  }
+
+  return output.replace(ABSOLUTE_WINDOWS_PATH_RE, (match) => {
+    const normalized = normalizePathSeparators(match);
+    const srcIndex = normalized.search(/(?:^|\/)(src|test|tests|docs|scripts|bin)\//);
+    if (srcIndex >= 0) {
+      return normalized.slice(normalized[srcIndex] === "/" ? srcIndex + 1 : srcIndex);
+    }
+    const parts = normalized.split("/").filter(Boolean);
+    return parts.slice(-2).join("/") || match;
+  });
+}
+
+/**
+ * Normalizes plan markdown for consistent rendering, converting bold labels
+ * into proper headings and hiding filesystem details.
+ */
+export function normalizePlanReviewMarkdown(planText: string, workspaceRoot?: string | null): string {
+  const sanitized = sanitizeTerminalOutput(hidePlanReviewFilesystemDetails(planText, workspaceRoot), {
+    preserveTabs: false,
+    tabSize: 2,
+  })
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/\n{4,}/g, "\n\n\n")
+    .split("\n")
+    .filter((line) => !isNoiseLine(line))
+    .join("\n");
+
+  return sanitized
+    .split("\n")
+    .map((line) => {
+      const trimmed = line.trim();
+      const sectionMatch = SECTION_LINE_RE.exec(trimmed);
+      if (sectionMatch && !/^[-*]\s+/.test(trimmed) && !/^\d+\.\s+/.test(trimmed)) {
+        return `## ${sectionMatch[1]!.trim()}`;
+      }
+      return line;
+    })
+    .join("\n");
+}
+
+/**
+ * Resolve the directory where plan files are stored.
+ * Uses platform-appropriate app-data locations instead of the workspace.
+ */
+export function resolvePlanDir(platformOverride?: Platform): string {
+  const envDir = process.env["UBUME_PLAN_DIR"] || process.env["CODEXA_PLAN_DIR"];
+  if (envDir) return envDir;
+
+  const platform = platformOverride ?? process.platform;
+
+  if (platform === "win32") {
+    const localAppData = process.env["LOCALAPPDATA"];
+    if (localAppData) return join(localAppData, "Ubume", "plans");
+    const appData = process.env["APPDATA"];
+    if (appData) return join(appData, "Ubume", "plans");
+    return join(homedir(), "AppData", "Local", "Ubume", "plans");
+  }
+
+  return join(resolveUbumeDataDir(platform), "plans");
+}
+
+// SHA-256 of the workspace path ensures filename uniqueness across projects with the same name.
+function workspaceHash(workspaceRoot: string): string {
+  return createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 8);
+}
+
+function safeTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Save plan content to the app-data plan directory.
+ * Returns the written file path, or null on failure.
+ */
+export function savePlan(content: string, workspaceRoot: string): string | null {
+  try {
+    const dir = resolvePlanDir();
+    mkdirSync(dir, { recursive: true });
+    const filename = `plan-${safeTimestamp()}-${workspaceHash(workspaceRoot)}.md`;
+    const filePath = join(dir, filename);
+    writeFileSync(filePath, content, "utf-8");
+    return filePath;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read plan content from a file path.
+ * Returns the content string, or null on failure.
+ */
+export function readPlan(filePath: string): string | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}

package/src/core/workspace/projectInstructions.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+export interface ProjectInstructions {
+  path: string;
+  content: string;
+}
+
+export type ProjectInstructionsLoadResult =
+  | { status: "loaded"; instructions: ProjectInstructions }
+  | { status: "missing" }
+  | { status: "error"; path: string; message: string };
+
+const PROJECT_INSTRUCTION_CANDIDATES = [
+  "AGENTS.md",
+  join(".codex", "AGENTS.md"),
+] as const;
+
+export function loadProjectInstructions(workspaceRoot: string): ProjectInstructionsLoadResult {
+  let firstError: Extract<ProjectInstructionsLoadResult, { status: "error" }> | null = null;
+
+  for (const relativePath of PROJECT_INSTRUCTION_CANDIDATES) {
+    const candidatePath = join(workspaceRoot, relativePath);
+    if (!existsSync(candidatePath)) {
+      continue;
+    }
+
+    try {
+      const content = readFileSync(candidatePath, "utf8").trim();
+      if (!content) {
+        continue;
+      }
+      return {
+        status: "loaded",
+        instructions: {
+          path: candidatePath,
+          content,
+        },
+      };
+    } catch (error) {
+      firstError ??= {
+        status: "error",
+        path: candidatePath,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  if (firstError) {
+    return firstError;
+  }
+
+  return { status: "missing" };
+}

package/src/core/workspace/scratchDir.ts

@@ -0,0 +1,64 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Workspace-relative home for agent throwaway files (test harnesses, probe scripts, logs). */
+export const SCRATCH_RELATIVE_DIR = ".ubume/scratch";
+export const LEGACY_SCRATCH_RELATIVE_DIR = ".codexa/scratch";
+
+const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const SAFE_SESSION_ID = /^[A-Za-z0-9_-]+$/;
+
+export interface SessionScratchDir {
+  absolutePath: string;
+  relativePath: string;
+}
+
+export function resolveScratchRoot(workspaceRoot: string): string {
+  return join(workspaceRoot, ".ubume", "scratch");
+}
+
+export function resolveLegacyScratchRoot(workspaceRoot: string): string {
+  return join(workspaceRoot, ".codexa", "scratch");
+}
+
+/**
+ * Create `.ubume/scratch/<sessionId>` inside the workspace. The scratch root
+ * carries its own `*` .gitignore so git ignores it without touching the
+ * project's ignore rules. It lives in the workspace (not the OS temp dir)
+ * because sandboxed shells only get a persistent writable workspace.
+ */
+export function ensureSessionScratchDir(workspaceRoot: string, sessionId: string): SessionScratchDir {
+  if (!SAFE_SESSION_ID.test(sessionId)) throw new Error(`Unsafe scratch session id: ${sessionId}`);
+  const root = resolveScratchRoot(workspaceRoot);
+  mkdirSync(root, { recursive: true });
+  const gitignore = join(root, ".gitignore");
+  if (!existsSync(gitignore)) writeFileSync(gitignore, "*\n", "utf8");
+  const absolutePath = join(root, sessionId);
+  mkdirSync(absolutePath, { recursive: true });
+  return { absolutePath, relativePath: `${SCRATCH_RELATIVE_DIR}/${sessionId}` };
+}
+
+/** Best-effort removal of session scratch folders older than `maxAgeMs`. */
+export function pruneStaleScratchDirs(
+  workspaceRoot: string,
+  options: { keep?: string; maxAgeMs?: number; now?: number } = {},
+): void {
+  for (const root of [resolveScratchRoot(workspaceRoot), resolveLegacyScratchRoot(workspaceRoot)]) {
+    const cutoff = (options.now ?? Date.now()) - (options.maxAgeMs ?? DEFAULT_MAX_AGE_MS);
+    let entries;
+    try {
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === options.keep) continue;
+      const dir = join(root, entry.name);
+      try {
+        if (statSync(dir).mtimeMs < cutoff) rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // A locked or vanished folder must not break the run that triggered pruning.
+      }
+    }
+  }
+}