@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.3

package/src/launch-profiles.js

@@ -0,0 +1,292 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { get as httpGet } from "node:http";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { freePort } from "./serve.js";
+class LaunchProfileError extends Error {
+  constructor(message, status = 400, confirm) {
+    super(message);
+    this.status = status;
+    this.confirm = confirm;
+  }
+}
+const identifier = /^[a-z][a-z0-9-]{0,39}$/;
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const text = (value, max) => typeof value === "string" && !!value.trim() && value.length <= max && !value.includes("\0");
+const envPrefix = (id) => id.replace(/-/g, "_").toUpperCase();
+function directoryAllowed(path) {
+  return path === "." || typeof path === "string" && path.length <= 500 && !isAbsolute(path) && !/^[A-Za-z]:/.test(path) && !/[\\\x00-\x1f]/.test(path) && !path.split("/").some((part) => !part || part === "." || part === ".." || part === ".git");
+}
+function validateLaunchProfiles(value) {
+  if (!object(value) || value.version !== 1 || !Array.isArray(value.profiles) || value.profiles.length > 12 || Object.keys(value).some((key) => !["version", "profiles"].includes(key))) throw new LaunchProfileError("Expected version 1 launch configuration with at most 12 profiles.");
+  const profiles = value.profiles.map((raw) => {
+    if (!object(raw) || typeof raw.id !== "string" || !identifier.test(raw.id) || !text(raw.name, 120) || !Array.isArray(raw.services) || raw.services.length < 1 || raw.services.length > 6 || Object.keys(raw).some((key) => !["id", "name", "services"].includes(key))) throw new LaunchProfileError("Each named launch profile needs a valid ID and 1\u20136 services.");
+    const services = raw.services.map((entry) => {
+      if (!object(entry) || typeof entry.id !== "string" || !identifier.test(entry.id) || !text(entry.command, 4e3) || entry.name !== void 0 && !text(entry.name, 120) || !directoryAllowed(entry.cwd ?? ".") || Object.keys(entry).some((key) => !["id", "name", "command", "cwd", "dependsOn", "health", "env"].includes(key))) throw new LaunchProfileError("Services need a valid ID, bounded command and a safe relative working directory.");
+      const dependsOn = entry.dependsOn ?? [];
+      if (!Array.isArray(dependsOn) || dependsOn.length > 5 || dependsOn.some((id) => typeof id !== "string" || !identifier.test(id)) || new Set(dependsOn).size !== dependsOn.length) throw new LaunchProfileError(`${entry.id} has invalid dependencies.`);
+      let health = { path: "/", timeoutMs: 15e3 };
+      if (entry.health === false) health = false;
+      else if (entry.health !== void 0) {
+        if (!object(entry.health) || !text(entry.health.path, 500) || !entry.health.path.startsWith("/") || entry.health.path.startsWith("//") || /[\\#\x00-\x20\x7f]/.test(entry.health.path) || Object.keys(entry.health).some((key) => !["path", "timeoutMs"].includes(key))) throw new LaunchProfileError(`${entry.id} needs a local HTTP health path.`);
+        const timeoutMs = entry.health.timeoutMs ?? 15e3;
+        if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 12e4) throw new LaunchProfileError("Health timeout must be between 100 and 120,000 ms.");
+        health = { path: entry.health.path, timeoutMs };
+      }
+      if (entry.env !== void 0 && !object(entry.env)) throw new LaunchProfileError("Service environment must be an object.");
+      const env = {};
+      for (const [key, val] of Object.entries(entry.env ?? {})) {
+        if (!/^[A-Z_][A-Z0-9_]{0,99}$/.test(key) || key.startsWith("CODEFLOW_") || ["PORT", "HOST", "SERVICE_NAME"].includes(key) || typeof val !== "string" || val.length > 4e3 || val.includes("\0")) throw new LaunchProfileError(`Invalid or reserved service environment variable: ${key}`);
+        env[key] = val;
+      }
+      if (Object.keys(env).length > 40) throw new LaunchProfileError("Service environment is limited to 40 entries.");
+      return { id: entry.id, ...entry.name ? { name: entry.name } : {}, command: entry.command, cwd: entry.cwd ?? ".", dependsOn: [...dependsOn], health, env };
+    });
+    if (new Set(services.map((service) => service.id)).size !== services.length) throw new LaunchProfileError("Service IDs must be unique within a profile.");
+    const ordered = /* @__PURE__ */ new Set();
+    while (ordered.size < services.length) {
+      const ready = services.find((service) => !ordered.has(service.id) && service.dependsOn.every((id) => ordered.has(id)));
+      if (!ready) throw new LaunchProfileError("Service dependencies must name existing services and form an acyclic graph.");
+      ordered.add(ready.id);
+    }
+    const reserved = new Set(services.flatMap((service) => [`${envPrefix(service.id)}_URL`, `${envPrefix(service.id)}_PORT`]));
+    if (services.some((service) => Object.keys(service.env).some((key) => reserved.has(key)))) throw new LaunchProfileError("Generated peer URL and port variables cannot be overridden.");
+    const generated = /* @__PURE__ */ new Set([...reserved, "PORT", "HOST", "SERVICE_NAME"]);
+    for (const service of services) for (const value2 of Object.values(service.env)) for (const match of value2.matchAll(/\$\{([A-Z_][A-Z0-9_]*)\}/g)) if (!generated.has(match[1])) throw new LaunchProfileError(`Unknown generated environment variable: ${match[1]}`);
+    return { id: raw.id, name: raw.name, services };
+  });
+  if (new Set(profiles.map((profile) => profile.id)).size !== profiles.length) throw new LaunchProfileError("Launch profile IDs must be unique.");
+  return profiles;
+}
+async function launchDirectory(root, path) {
+  if (!directoryAllowed(path)) throw new LaunchProfileError("Choose a safe relative service working directory.");
+  if (!(await lstat(root)).isDirectory()) throw new LaunchProfileError("Launch root must be a regular worktree directory.");
+  const canonical = await realpath(root);
+  let current = canonical;
+  for (const part of path === "." ? [] : path.split("/")) {
+    current = join(current, part);
+    if (!(await lstat(current)).isDirectory()) throw new LaunchProfileError(`Service directory is missing or uses a symbolic link: ${path}`);
+  }
+  const resolved = await realpath(current);
+  const rel = relative(canonical, resolved);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new LaunchProfileError("Service working directory escapes the worktree.");
+  return resolved;
+}
+async function readLaunchProfiles(root) {
+  try {
+    const directory = await launchDirectory(root, ".codeflow");
+    const handle = await open(join(directory, "launch.json"), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const info = await handle.stat();
+      if (!info.isFile() || info.size > 128 * 1024) throw new LaunchProfileError("Launch configuration must be a regular file under 128 KiB.");
+      return { profiles: validateLaunchProfiles(JSON.parse(await handle.readFile("utf8"))), found: true };
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") return { profiles: [], found: false };
+    return { profiles: [], found: true, error: error.message };
+  }
+}
+function healthProbe(port, path, signal, budgetMs) {
+  if (signal.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (ok) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", aborted);
+      resolve(ok);
+    };
+    const request = httpGet({ hostname: "127.0.0.1", port, path, timeout: 1e3, agent: false }, (response) => {
+      const ok = (response.statusCode ?? 0) >= 200 && (response.statusCode ?? 0) < 300;
+      response.destroy();
+      done(ok);
+    });
+    const aborted = () => {
+      request.destroy();
+      done(false);
+    };
+    const timer = setTimeout(aborted, Math.max(1, Math.min(1e3, budgetMs)));
+    signal.addEventListener("abort", aborted, { once: true });
+    request.on("timeout", () => {
+      request.destroy();
+      done(false);
+    });
+    request.on("error", () => done(false));
+  });
+}
+const delay = (ms, signal) => new Promise((resolve) => {
+  if (signal.aborted) return resolve();
+  const finish = () => {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", finish);
+    resolve();
+  };
+  const timer = setTimeout(finish, ms);
+  signal.addEventListener("abort", finish, { once: true });
+});
+class LaunchProfiles {
+  constructor(servers) {
+    this.servers = servers;
+  }
+  sessions = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.sessions.get(key);
+    if (!entry) return void 0;
+    this.refresh(entry);
+    return structuredClone(entry.session);
+  }
+  refresh(entry) {
+    for (const service of entry.session.services) {
+      const live = this.servers.get(`${entry.session.key}/${service.id}`);
+      if (live) {
+        service.logs = live.logs.slice(-100).map((line) => line.slice(-2e3));
+        service.exitCode = live.exitCode;
+        if (live.status === "exited") service.status = "exited";
+      } else if (entry.session.status === "ready") service.status = "exited";
+    }
+    if (entry.session.status === "ready" && entry.session.services.some((service) => service.status === "exited")) {
+      const failed = entry.session.services.find((service) => service.status === "exited");
+      entry.session.status = "failed";
+      entry.session.error = `Service ${failed.name} exited; the stack was stopped.`;
+      this.cleanup(entry);
+    }
+  }
+  cleanup(entry) {
+    if (entry.monitor) clearInterval(entry.monitor);
+    for (const service of entry.session.services) {
+      const live = this.servers.get(`${entry.session.key}/${service.id}`);
+      if (live) {
+        service.logs = live.logs.slice(-100).map((line) => line.slice(-2e3));
+        service.exitCode = live.exitCode;
+        if (live.status === "exited") service.status = "exited";
+      }
+      if (service.status !== "exited") service.status = "stopped";
+    }
+    for (const key of [...entry.serviceKeys].reverse()) this.servers.stop(key);
+  }
+  stop(key) {
+    const entry = this.sessions.get(key);
+    if (!entry) return false;
+    this.refresh(entry);
+    entry.controller.abort();
+    entry.session.status = "stopped";
+    for (const service of entry.session.services) if (service.status !== "exited") service.status = "stopped";
+    this.cleanup(entry);
+    return true;
+  }
+  stopAll() {
+    for (const key of this.sessions.keys()) this.stop(key);
+  }
+  stopMatching(prefix) {
+    for (const key of this.sessions.keys()) if (key.startsWith(prefix)) this.stop(key);
+  }
+  async start(key, root, rawProfile, options = {}) {
+    if (options.lockdown && !options.allowUntrusted) throw new LaunchProfileError(`${options.lockdown}. Starting this profile executes repository commands on this machine.`, 409, "allowUntrusted");
+    const profile = validateLaunchProfiles({ version: 1, profiles: [rawProfile] })[0];
+    const previous = this.sessions.get(key);
+    if (previous && (previous.inFlight || ["starting", "ready"].includes(previous.session.status))) throw new LaunchProfileError("This launch profile is already active or still stopping. Wait for it to stop before starting another.", 409);
+    if (this.sessions.size >= 50) for (const [oldKey, entry2] of this.sessions) {
+      if (["stopped", "failed"].includes(entry2.session.status)) {
+        this.sessions.delete(oldKey);
+        if (this.sessions.size < 50) break;
+      }
+    }
+    if (!previous && this.sessions.size >= 50) throw new LaunchProfileError("Too many active launch profiles. Stop a stack before starting another.", 409);
+    const entry = { session: { key, root, profile: profile.id, status: "starting", startedAt: Date.now(), services: [] }, controller: new AbortController(), serviceKeys: [], inFlight: true };
+    this.sessions.set(key, entry);
+    const aborted = () => entry.controller.abort();
+    options.signal?.addEventListener("abort", aborted, { once: true });
+    if (options.signal?.aborted) entry.controller.abort();
+    const active = () => {
+      if (entry.controller.signal.aborted) throw new LaunchProfileError("Launch startup was cancelled.", 409);
+    };
+    const childrenActive = () => {
+      active();
+      this.refresh(entry);
+      for (const serviceKey of entry.serviceKeys) if (this.servers.get(serviceKey)?.status !== "running") throw new LaunchProfileError(`Service ${serviceKey.split("/").at(-1)} exited or was stopped during startup.`, 422);
+    };
+    try {
+      const ports = /* @__PURE__ */ new Set();
+      const generated = {};
+      for (const service of profile.services) {
+        active();
+        const cwd = await launchDirectory(root, service.cwd);
+        let port = await freePort();
+        for (let retry = 0; ports.has(port) && retry < 20; retry++) port = await freePort();
+        if (ports.has(port)) throw new LaunchProfileError("Could not allocate distinct service ports.", 409);
+        ports.add(port);
+        const url = `http://127.0.0.1:${port}`;
+        generated[`${envPrefix(service.id)}_URL`] = url;
+        generated[`${envPrefix(service.id)}_PORT`] = String(port);
+        entry.session.services.push({ id: service.id, name: service.name ?? service.id, command: service.command, cwd, port, url, status: "pending", healthChecked: false, logs: [] });
+      }
+      const ready = /* @__PURE__ */ new Set();
+      const deadline = Date.now() + 18e4;
+      while (ready.size < profile.services.length) {
+        childrenActive();
+        if (Date.now() >= deadline) throw new LaunchProfileError("The launch profile exceeded its startup deadline.", 422);
+        const service = profile.services.find((service2) => !ready.has(service2.id) && service2.dependsOn.every((id) => ready.has(id)));
+        const snapshot = entry.session.services.find((item) => item.id === service.id);
+        const serviceKey = `${key}/${service.id}`;
+        if (await launchDirectory(root, service.cwd) !== snapshot.cwd) throw new LaunchProfileError("A service directory changed during startup.", 409);
+        childrenActive();
+        const allocated = { ...generated, PORT: String(snapshot.port), HOST: "127.0.0.1", SERVICE_NAME: service.id };
+        const env = { ...allocated };
+        for (const [name, value] of Object.entries(service.env)) env[name] = value.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_, id) => {
+          if (allocated[id] === void 0) throw new LaunchProfileError(`Unknown generated environment variable: ${id}`);
+          return allocated[id];
+        });
+        snapshot.status = "starting";
+        entry.serviceKeys.push(serviceKey);
+        await this.servers.start(serviceKey, snapshot.cwd, service.command, snapshot.port, env, entry.controller.signal);
+        if (service.health !== false) {
+          const expires = Math.min(deadline, Date.now() + service.health.timeoutMs);
+          let healthy = false;
+          while (Date.now() < expires) {
+            childrenActive();
+            if (await healthProbe(snapshot.port, service.health.path, entry.controller.signal, expires - Date.now())) {
+              healthy = true;
+              break;
+            }
+            await delay(Math.min(100, Math.max(0, expires - Date.now())), entry.controller.signal);
+          }
+          if (!healthy) throw new LaunchProfileError(`Service ${snapshot.name} did not pass its HTTP health check before the startup deadline.`, 422);
+          snapshot.status = "healthy";
+          snapshot.healthChecked = true;
+        } else {
+          await delay(100, entry.controller.signal);
+          childrenActive();
+          snapshot.status = "running";
+        }
+        ready.add(service.id);
+      }
+      childrenActive();
+      entry.session.status = "ready";
+      entry.session.readyAt = Date.now();
+      entry.monitor = setInterval(() => this.refresh(entry), 1e3);
+      entry.monitor.unref?.();
+      return this.get(key);
+    } catch (error) {
+      this.refresh(entry);
+      if (entry.session.status !== "stopped") {
+        entry.session.status = "failed";
+        entry.session.error = error.message;
+      }
+      this.cleanup(entry);
+      throw error;
+    } finally {
+      entry.inFlight = false;
+      options.signal?.removeEventListener("abort", aborted);
+    }
+  }
+}
+export {
+  LaunchProfileError,
+  LaunchProfiles,
+  launchDirectory,
+  readLaunchProfiles,
+  validateLaunchProfiles
+};

package/src/learnings.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CODEFLOW_HOME } from "./config.js";
+import { git } from "./git.js";
+const CONVENTION_FILES = [".codeflow/conventions.md", "AGENTS.md", "CLAUDE.md", "GEMINI.md", ".github/copilot-instructions.md", ".cursorrules"];
+const MAX_CONVENTIONS = 6e3;
+async function readConventions(repo, ref) {
+  const parts = [];
+  let size = 0;
+  for (const path of CONVENTION_FILES) {
+    const res = await git(["show", `${ref}:${path}`], repo);
+    const text = res.code === 0 ? res.stdout.trim() : "";
+    if (!text) continue;
+    const room = MAX_CONVENTIONS - size;
+    if (room < 200) break;
+    const body = text.length > room ? `${text.slice(0, room)}
+\u2026 (${path} is longer; read the file for the rest)` : text;
+    parts.push(`### ${path}
+${body}`);
+    size += body.length;
+  }
+  return parts.join("\n\n");
+}
+const DIR = join(CODEFLOW_HOME, "learnings");
+const MAX_LESSONS = 200;
+const RECURRING = 2;
+const fileFor = (repo) => join(DIR, `${createHash("sha1").update(repo).digest("hex").slice(0, 16)}.json`);
+async function load(repo) {
+  const file = fileFor(repo);
+  if (!existsSync(file)) return [];
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return [];
+  }
+}
+const words = (s) => new Set(s.toLowerCase().match(/[a-z0-9_]{3,}/g) ?? []);
+function similar(a, b) {
+  const x = words(a);
+  const y = words(b);
+  if (!x.size || !y.size) return false;
+  let shared = 0;
+  for (const w of x) if (y.has(w)) shared++;
+  return shared / (x.size + y.size - shared) >= 0.6;
+}
+let saving = Promise.resolve();
+function recordFindings(repo, runId, findings) {
+  const worth = findings.filter((f) => f.severity === "high" || f.severity === "medium").filter((f) => f.problem?.trim());
+  if (!worth.length) return saving;
+  saving = saving.then(async () => {
+    const lessons = await load(repo);
+    for (const f of worth) {
+      const problem = f.problem.trim().slice(0, 300);
+      const match = lessons.find((l) => similar(l.problem, problem));
+      if (match) {
+        if (!match.runs.includes(runId)) match.runs.push(runId);
+        match.at = Date.now();
+      } else {
+        lessons.push({ problem, file: f.file ?? "", runs: [runId], at: Date.now() });
+      }
+    }
+    lessons.sort((a, b) => b.at - a.at);
+    await mkdir(DIR, { recursive: true });
+    const file = fileFor(repo);
+    await writeFile(`${file}.tmp`, JSON.stringify(lessons.slice(0, MAX_LESSONS), null, 1));
+    await rename(`${file}.tmp`, file);
+  }).catch(() => void 0);
+  return saving;
+}
+async function recurringLessons(repo, limit = 8) {
+  await saving;
+  return (await load(repo)).filter((l) => l.runs.length >= RECURRING).sort((a, b) => b.runs.length - a.runs.length || b.at - a.at).slice(0, limit);
+}
+export {
+  readConventions,
+  recordFindings,
+  recurringLessons
+};

package/src/local-app-url.js

@@ -0,0 +1,19 @@
+const LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function localAppUrl(value, ownAddress) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" || !LOOPBACK.has(url.hostname) || !url.port || url.username || url.password) return;
+    if (ownAddress && url.port === new URL(ownAddress).port) return;
+    return url.href;
+  } catch {
+    return;
+  }
+}
+function localAppUrls(text, ownAddress) {
+  const found = [...text.matchAll(/http:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+(?:[/?#][^\s<>"'`()\[\]]*)?/gi)];
+  return [...new Set(found.map(([value]) => localAppUrl(value.replace(/[.,;!]+$/, ""), ownAddress)).filter((url) => !!url))];
+}
+export {
+  localAppUrl,
+  localAppUrls
+};

package/src/log.js

@@ -0,0 +1,39 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { CODEFLOW_HOME } from "./config.js";
+const LOG_FILE = join(CODEFLOW_HOME, "server.log");
+const MAX_BYTES = 5 * 1024 * 1024;
+let writes = 0;
+function write(level, message, detail) {
+  try {
+    mkdirSync(CODEFLOW_HOME, { recursive: true });
+    if (writes++ % 50 === 0) {
+      const size = statSync(LOG_FILE, { throwIfNoEntry: false })?.size ?? 0;
+      if (size > MAX_BYTES) renameSync(LOG_FILE, `${LOG_FILE}.1`);
+    }
+    appendFileSync(LOG_FILE, `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), level, message, ...detail })}
+`);
+  } catch {
+  }
+}
+function describe(err) {
+  if (err instanceof Error) return { error: err.message, stack: err.stack?.split("\n").slice(0, 12).join("\n") };
+  return { error: String(err) };
+}
+function logInfo(message, detail) {
+  write("info", message, detail);
+}
+function logWarn(message, detail) {
+  write("warn", message, detail);
+}
+function logError(message, err, detail) {
+  const info = err === void 0 ? {} : describe(err);
+  write("error", message, { ...info, ...detail });
+  console.error(`code-flow: ${message}${info.error ? `: ${info.error}` : ""}`);
+}
+export {
+  LOG_FILE,
+  logError,
+  logInfo,
+  logWarn
+};