cortad 0.3.1-rc.9 → 0.3.2

package/lib/runner.mjs

@@ -0,0 +1,85 @@
+// The one process holding a project's app up, and the app's state as that process last wrote it.
+// ~/.cortad/<project>/runner.json is both the lock and the record:
+//   { pid, startedAt, by, version, state: "starting" | "up" | "failed", at, port?, host?, app?, error? }
+// It exists only while its runner lives, so "stopped" is the absence of one. The runner is the only
+// writer; every reader takes the app's state from here and never works it out again.
+import { execFileSync } from "node:child_process";
+import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homeOf } from "./home.mjs";
+import { elapsedMs } from "./proc.mjs";
+
+const fileOf = (project, base) => join(homeOf(project, base), "runner.json");
+const read = (file) => { try { const r = JSON.parse(readFileSync(file, "utf8")); return Number.isInteger(r?.pid) ? r : null; } catch { return null; } };
+const same = (a, b) => a?.pid === b?.pid && a?.startedAt === b?.startedAt;
+
+// When a process started, to the second: with the pid, what tells a runner from a later process that
+// was handed the same pid.
+export function startedAtOf(pid = process.pid) {
+  if (pid === process.pid) return new Date(Date.now() - process.uptime() * 1000).toISOString();
+  try { return new Date(Date.now() - elapsedMs(execFileSync("ps", ["-o", "etime=", "-p", String(pid)], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim())).toISOString(); } catch { return null; }
+}
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+// The pid is alive and is still the process that wrote the record; ps rounds to the second.
+// ponytail: a machine with no ps is taken at the pid alone, as before this check existed.
+function isLive(runner) {
+  if (!alive(runner.pid)) return false;
+  if (runner.pid === process.pid) return true;
+  const now = startedAtOf(runner.pid);
+  return now === null || Math.abs(Date.parse(now) - Date.parse(runner.startedAt)) < 3000;
+}
+
+export function readRunner(project, base) {
+  const runner = read(fileOf(project, base));
+  return runner && isLive(runner) ? runner : null;
+}
+
+// Takes the lock for this process and returns null, or returns the live runner that holds it. A
+// record left by a runner that has ended is taken over. The record is written whole and then linked
+// into place, which fails if the file exists: two processes asking at once never both get it.
+// ponytail: two processes finding the same stale record in the same millisecond can race on its
+// removal; each re-reads it first, which leaves a window of one file operation.
+export function claimRunner(project, record, base) {
+  const file = fileOf(project, base);
+  const mine = `${file}.${record.pid}`;
+  mkdirSync(homeOf(project, base), { recursive: true, mode: 0o700 });
+  writeFileSync(mine, JSON.stringify(record), { mode: 0o600 });
+  try {
+    for (let tries = 0; tries < 5; tries++) {
+      try { linkSync(mine, file); return null; } catch (e) { if (e.code !== "EEXIST") throw e; }
+      const held = read(file);
+      if (held && isLive(held)) return held;
+      if (same(read(file), held)) { try { rmSync(file); } catch { /* taken first; asked again */ } }
+    }
+    throw new Error("could not take this project's lock: another process keeps rewriting it");
+  } finally { rmSync(mine, { force: true }); }
+}
+
+// The runner's own record, rewritten whole with each change of state and renamed into place, so a
+// reader never sees half of it.
+export function writeRunner(project, record, base) {
+  const file = fileOf(project, base);
+  writeFileSync(`${file}.${record.pid}`, JSON.stringify(record), { mode: 0o600 });
+  renameSync(`${file}.${record.pid}`, file);
+}
+
+// Removed only by the process that holds it: a runner ending late never takes its successor's lock.
+export function releaseRunner(project, base, pid = process.pid) {
+  if (read(fileOf(project, base))?.pid === pid) rmSync(fileOf(project, base), { force: true });
+}
+
+const until = async (done, ms) => { for (const end = Date.now() + ms; !done() && Date.now() < end;) await new Promise((r) => setTimeout(r, 100)); return done(); };
+
+// Ends the runner holding this project: asked, then made to, and its app waited out, so the next
+// start never meets the old app on its port. A runner killed outright has its app stopped by the
+// watchdog lib/proc.mjs ties to it.
+export async function replaceRunner(held, { askMs = 15_000, appMs = 10_000 } = {}) {
+  try { process.kill(held.pid, "SIGTERM"); } catch { /* ended on its own */ }
+  if (!(await until(() => !alive(held.pid), askMs))) {
+    try { process.kill(held.pid, "SIGKILL"); } catch { /* ended */ }
+    await until(() => !alive(held.pid), 2000);
+  }
+  if (Number.isInteger(held.app)) await until(() => !alive(held.app), appMs);
+  return !alive(held.pid);
+}

package/lib/service.mjs

@@ -3,11 +3,36 @@
 // apps/api. A recipe that names such a service (src/setup/road-identities.ts) is minted against
 // that service instead, so nobody is asked to send a message by hand. Cookies set on localhost
 // apply to every port, which is what makes the session work on the AI service after.
+import { existsSync, readFileSync } from "node:fs";
 import { relative, join } from "node:path";
 import { startPlan } from "./start.mjs";
 
 export const serviceBase = (port) => `http://127.0.0.1:${port}`;
 
+const PORT_IN_SCRIPT = /(?:^|\s)(?:PORT=|-p[ =]|--port[ =])(\d{2,5})\b/;
+// The port a framework serves on when nobody names one. sveltekit and astro before vite: both bring
+// vite with them and neither uses its port.
+const FRAMEWORK_PORT = [["next", 3000], ["nuxt", 3000], ["@remix-run/serve", 3000], ["@remix-run/dev", 3000], ["@sveltejs/kit", 5173], ["astro", 4321], ["vite", 5173]];
+// No scan of the usual ports: whatever answers on 3000 or 8080 on this machine is very often not
+// this workspace, and a test account made against somebody else's service is the worst kind of
+// wrong. Only the port this workspace itself names, and if nothing is there, it is started.
+
+// What a workspace serves on: its own script says so, or the framework it is written in does.
+export function servicePort(cwd) {
+  let pkg = null;
+  try { pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")); } catch { /* not a Node workspace */ }
+  const script = ["dev", "develop", "start:dev", "serve", "start"].map((s) => pkg?.scripts?.[s]).find(Boolean) ?? "";
+  const named = Number(PORT_IN_SCRIPT.exec(script)?.[1]);
+  if (named) return named;
+  const deps = Object.keys({ ...pkg?.dependencies, ...pkg?.devDependencies });
+  const framework = FRAMEWORK_PORT.find(([dep]) => deps.includes(dep))?.[1];
+  if (framework) return framework;
+  if (existsSync(join(cwd, "manage.py"))) return 8000;
+  if (existsSync(join(cwd, "Gemfile"))) return 3000;
+  const py = ["requirements.txt", "pyproject.toml"].map((f) => { try { return readFileSync(join(cwd, f), "utf8"); } catch { return ""; } }).join("\n");
+  return /\bdjango\b/i.test(py) ? 8000 : /\bflask\b/i.test(py) ? 5000 : null;
+}
+
 // The recipes to mint against a service other than the running app, grouped by that service's
 // workspace, each with how it starts itself. A recipe whose service is the app's own dir stays with
 // the app and is not returned here.

package/lib/spec.mjs

@@ -3,14 +3,17 @@ import { isAbsolute } from "node:path";
 
 // Which cortad the coding agents on this machine start, and the skill and stick name: the
 // CORTAD_CLI_SPEC the connect ran with (cortad@next, or an absolute folder for an unpublished
-// build), else cortad@next while this package is a prerelease, else cortad@latest. The spec ends up
-// in a shell line in the repository (lib/stick.mjs), so anything else in the variable is ignored.
+// build), else this very version: under cortad@next the agents ran rc.15 while the connector they
+// talked to was the rc.14 the connect command pinned. The spec ends up in a shell line in the
+// repository (lib/stick.mjs), so anything else in the variable is ignored.
 export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-const SAFE = /^(?:cortad(?:@[A-Za-z0-9._-]+)?|\/[A-Za-z0-9._/-]+)$/;
+// Also how lib/stick.mjs tells a line of its own from another tool's.
+export const SPEC = "(?:cortad(?:@[A-Za-z0-9._-]+)?|/[A-Za-z0-9._/-]+)";
+const SAFE = new RegExp(`^${SPEC}$`);
 
 export function cliSpec({ env = process.env, version = VERSION } = {}) {
   if (env.CORTAD_CLI_SPEC && SAFE.test(env.CORTAD_CLI_SPEC)) return env.CORTAD_CLI_SPEC;
-  return version.includes("-") ? "cortad@next" : "cortad@latest";
+  return `cortad@${version}`;
 }
 
 // npx needs -y to fetch a package without asking; a local folder is not fetched.

package/lib/start.mjs

@@ -119,6 +119,8 @@ function pythonStart(dir, onPath) {
 const BOUND_APP = /^(app|application)\s*=\s*[\w.]+\(/m;
 const IMPORTED_APP = /^from\s+[\w.]+\s+import\s+(?:\(\s*[^)]*?\b(app|application)\b[^)]*\)|[^\n(]*\b(app|application)\b)/m;
 const KNOWN = ["package.json", "pyproject.toml", "requirements.txt", "manage.py", "Pipfile", "uv.lock"];
+// A folder whose app the hooks can load into: Node, Bun or Python. Any other is seen through lib/proxy.mjs.
+export const hookable = (dir) => KNOWN.some((f) => existsSync(join(dir, f)));
 
 const startOf = (dir, onPath) => nodeStart(dir, onPath) ?? pythonStart(dir, onPath);
 
@@ -132,6 +134,32 @@ function weight(dir, name) {
   return (model ? 4 : 0) + (server ? 2 : 0) + (/back|api|server|service/i.test(name) ? 1 : 0) - (!model && /front|web|client|ui|mobile|docs|site|landing|admin/i.test(name) ? 3 : 0);
 }
 
+// A folder whose start only bundles a page for the browser: the AI is never behind it, whatever it
+// imports (wecom-sales-agent's console/ imports hono for its client's types). A framework that also
+// serves routes is not a page.
+const PAGE_BUNDLER = /\b(?:vite|webpack(?:-dev-server)?|react-scripts|parcel|rsbuild|storybook)\b/;
+const FULLSTACK = /^(?:next|nuxt|@remix-run\/.+|@react-router\/dev|@sveltejs\/kit|astro|@solidjs\/start|@tanstack\/(?:react-)?start|vinxi|@analogjs\/platform|@builder\.io\/qwik-city)$/;
+function pageOnly(dir) {
+  const pkg = json(join(dir, "package.json"));
+  if (!pkg?.scripts) return false;
+  const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
+  const command = String(pkg.scripts[serverScript(pkg.scripts, deps)] ?? "");
+  return PAGE_BUNDLER.test(command) && !RUNS_SERVER.test(command.replace(PAGE_BUNDLER, "")) && !deps.some((d) => FULLSTACK.test(d));
+}
+const weighed = (dir, name) => weight(dir, name) - (pageOnly(dir) ? 4 : 0);
+
+// A monorepo root that serves the AI itself: its start runs a file of its own, not one inside a
+// workspace or a helper under scripts/. A root's dependencies are often every workspace's, hoisted,
+// so they say nothing about whether the root serves: TavernHeadless's root lists fastify and the AI
+// SDK and its dev only runs a menu script.
+function servesItself(root, members) {
+  const pkg = json(join(root, "package.json"));
+  const deps = Object.keys({ ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) });
+  const command = String(pkg?.scripts?.[serverScript(pkg?.scripts, deps)] ?? "");
+  return [...command.matchAll(/(?:^|\s)(?:\.\/)?([\w./-]+\.(?:[cm]?[jt]s|py))\b/g)].map((m) => join(root, m[1]))
+    .some((file) => existsSync(file) && !/\/(?:scripts|tools|bin)\//.test(file.slice(root.length)) && !members.some((dir) => file.startsWith(`${dir}/`)));
+}
+
 const SKIP = /^(?:node_modules|\.git|dist|build|\.next|coverage|\.venv|venv|__pycache__|\.turbo|\.cache)$/;
 export function workspaces(root) {
   const found = [];
@@ -160,9 +188,12 @@ export function startPlan({ root, typed, onPath }) {
   const pythonFirst = Boolean(rootPkg) && PY_MODEL.test(rootPy) && !Object.keys({ ...(rootPkg.dependencies ?? {}), ...(rootPkg.devDependencies ?? {}) }).some((d) => MODEL_SDK.test(d));
   const own = mono ? null : pythonFirst ? (pythonStart(root, onPath) ?? nodeStart(root, onPath)) : startOf(root, onPath);
   if (own) return { cmd: own.cmd, cwd: root };
-  const ranked = workspaces(root).map((dir) => ({ dir, start: startOf(dir, onPath), weight: weight(dir, relative(root, dir)) })).filter((w) => w.start).sort((a, b) => b.weight - a.weight);
+  // A monorepo root can serve the AI itself (wecom-sales-agent's root runs src/server.ts), so it is
+  // weighed beside its workspaces.
+  const members = workspaces(root);
+  const ranked = [...(mono && servesItself(root, members) ? [root] : []), ...members].map((dir) => ({ dir, start: startOf(dir, onPath), weight: weighed(dir, relative(root, dir)) })).filter((w) => w.start).sort((a, b) => b.weight - a.weight);
   const best = ranked[0];
-  const at = (w) => ({ cmd: w.start.cmd, cwd: w.dir, within: relative(root, w.dir) });
+  const at = (w) => ({ cmd: w.start.cmd, cwd: w.dir, ...(w.dir === root ? {} : { within: relative(root, w.dir) }) });
   if (best && best.weight > 0 && (ranked.length === 1 || best.weight > ranked[1].weight)) return at(best);
   // A root that does have a start of its own after all (a monorepo whose root script runs everything).
   const rootStart = startOf(root, onPath);

package/lib/stick.mjs

@@ -1,47 +1,81 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
-import { cliSpec, npxName } from "./spec.mjs";
+import { cliSpec, npxName, SPEC } from "./spec.mjs";
 
 // `npx cortad stick`: one line in each coding agent's own instructions file in this repository, and
 // a hook in the two clients that run one after an edit. `unstick` takes out exactly what stick put
 // in. Both are idempotent, print what they changed, and never touch git.
 //
-// The hook command carries --hook: Claude Code and Codex both drop plain stdout from a PostToolUse
-// hook, and read only hookSpecificOutput.additionalContext. The command follows lib/spec.mjs, and
-// unstick knows the line and the hook under any spec.
+// Two hooks: after an edit, the changed prompt and tool files and any news; on the person's next
+// prompt, the news alone (a run that ended while the agent was not listening), with no call to the
+// server. Both carry --hook: Claude Code and Codex drop plain stdout from a hook and read only
+// hookSpecificOutput.additionalContext. The commands follow lib/spec.mjs. A hook is ours when npx
+// runs a package named cortad, at any version, or the very spec this command runs under: another
+// tool started from a folder (`npx /opt/acme/notes news --hook`) is never taken for ours.
 export const lineFor = (name) => `After changing prompts, tools, models or retrieval, check with Cortad before committing: npx ${name} status`;
 export const hookFor = (name) => `npx ${name} status --changed --hook`;
-const IS_LINE = /^After changing prompts, tools, models or retrieval, check with Cortad before committing: npx \S+ status$/;
-const IS_HOOK = /^npx \S+ status --changed --hook$/;
+export const newsHookFor = (name) => `npx ${name} news --hook`;
+const IS_LINE = new RegExp(`^After changing prompts, tools, models or retrieval, check with Cortad before committing: npx ${SPEC} status$`);
+const IS_HOOK = /^npx cortad(?:@[A-Za-z0-9._-]+)? (?:status --changed|news) --hook$/;
+const HOOK_EVENTS = ["PostToolUse", "UserPromptSubmit"];
 const hasLine = (text) => text.split("\n").some((l) => IS_LINE.test(l.trim()));
-const ours = (entry) => entry?.hooks?.some((h) => IS_HOOK.test(h.command ?? ""));
+const mineFor = (spec) => {
+  const own = new Set([hookFor(npxName(spec)), newsHookFor(npxName(spec))]);
+  return (command) => IS_HOOK.test(command ?? "") || own.has(command);
+};
+// A settings file whose hooks are not the lists a client writes is left alone, said as such.
+const SHAPE = Symbol("shape");
+const listsOf = (config) => {
+  const hooks = config.hooks ?? {};
+  if (typeof hooks !== "object" || Array.isArray(hooks)) return null;
+  const lists = HOOK_EVENTS.map((event) => hooks[event] ?? []);
+  return lists.every((l) => Array.isArray(l) && l.every((e) => e && typeof e === "object" && (e.hooks === undefined || Array.isArray(e.hooks)))) ? lists : null;
+};
 const LINE_FILES = ["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"];
 const HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
 const RULE_FILE = ".cursor/rules/cortad.mdc";
 
-export const hookOutput = (text) => JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text } });
+export const hookOutput = (text, event = "PostToolUse") => JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } });
 
 export function stick(root, { spec = cliSpec() } = {}) {
   const line = lineFor(npxName(spec));
   const hook = hookFor(npxName(spec));
+  const news = newsHookFor(npxName(spec));
+  const mine = mineFor(spec);
+  const ours = (entry) => (entry.hooks ?? []).some((h) => mine(h.command));
   const rule = `---\ndescription: Checking AI behavior with Cortad\nalwaysApply: true\n---\n${line}\n`;
   const said = LINE_FILES.map((rel, i) => write(root, rel, (text) => {
     if (hasLine(text)) return null;
     return `${text}${text && !text.endsWith("\n") ? "\n" : ""}${text ? "\n" : ""}${line}\n`;
   }, i === 0 ? `added "${line}"` : "added the same line"));
   said.push(write(root, RULE_FILE, (text) => (hasLine(text) ? null : rule), "written, with the same line, applied always"));
-  said.push(...HOOK_FILES.map((rel, i) => write(root, rel, (text) => {
-    const config = parse(text);
-    if (config === undefined) return undefined;
-    const list = config.hooks?.PostToolUse ?? [];
-    if (list.some(ours)) return null;
-    config.hooks = { ...config.hooks, PostToolUse: [...list, { matcher: "Edit|Write", hooks: [{ type: "command", command: hook }] }] };
-    return `${JSON.stringify(config, null, 2)}\n`;
-  }, i === 0 ? `added a PostToolUse hook on Edit|Write that runs ${hook}` : "added the same hook")));
+  said.push(...HOOK_FILES.map((rel) => {
+    let added = [];
+    return write(root, rel, (text) => {
+      const config = parse(text);
+      if (config === undefined) return undefined;
+      const lists = listsOf(config);
+      if (!lists) return SHAPE;
+      const [edits, prompts] = lists;
+      added = [
+        ...(edits.some(ours) ? [] : [`a PostToolUse hook on Edit|Write that runs ${hook}`]),
+        ...(prompts.some(ours) ? [] : [`a UserPromptSubmit hook that runs ${news}`]),
+      ];
+      if (!added.length) return null;
+      config.hooks = {
+        ...config.hooks,
+        PostToolUse: edits.some(ours) ? edits : [...edits, { matcher: "Edit|Write", hooks: [{ type: "command", command: hook }] }],
+        UserPromptSubmit: prompts.some(ours) ? prompts : [...prompts, { hooks: [{ type: "command", command: news }] }],
+      };
+      return `${JSON.stringify(config, null, 2)}\n`;
+    }, () => `added ${added.join(", and ")}`);
+  }));
   return said;
 }
 
-export function unstick(root) {
+export function unstick(root, { spec = cliSpec() } = {}) {
+  const mine = mineFor(spec);
+  const ours = (entry) => (entry.hooks ?? []).some((h) => mine(h.command));
   const said = LINE_FILES.map((rel) => write(root, rel, (text) => {
     if (!hasLine(text)) return null;
     return text.split("\n").filter((l) => !IS_LINE.test(l.trim())).join("\n").replace(/\n+$/, "\n");
@@ -50,14 +84,19 @@ export function unstick(root) {
   said.push(...HOOK_FILES.map((rel) => write(root, rel, (text) => {
     const config = parse(text);
     if (config === undefined) return undefined;
-    const list = config.hooks?.PostToolUse;
-    if (!list?.some(ours)) return null;
-    const kept = list.map((e) => ({ ...e, hooks: (e.hooks ?? []).filter((h) => !IS_HOOK.test(h.command ?? "")) })).filter((e) => e.hooks.length);
-    if (kept.length) config.hooks.PostToolUse = kept;
-    else delete config.hooks.PostToolUse;
+    const lists = listsOf(config);
+    if (!lists) return SHAPE;
+    if (!lists.some((list) => list.some(ours))) return null;
+    for (const event of HOOK_EVENTS) {
+      const list = config.hooks?.[event];
+      if (!list?.some(ours)) continue;
+      const kept = list.map((e) => (ours(e) ? { ...e, hooks: e.hooks.filter((h) => !mine(h.command)) } : e)).filter((e) => !Array.isArray(e.hooks) || e.hooks.length);
+      if (kept.length) config.hooks[event] = kept;
+      else delete config.hooks[event];
+    }
     if (!Object.keys(config.hooks).length) delete config.hooks;
     return Object.keys(config).length ? `${JSON.stringify(config, null, 2)}\n` : "";
-  }, "removed the hook")));
+  }, "removed the hooks")));
   return said;
 }
 
@@ -70,15 +109,16 @@ function write(root, rel, change, done) {
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
   const next = change(text);
   if (next === undefined) return `${rel}: left alone, it is not valid JSON`;
+  if (next === SHAPE) return `${rel}: left alone, its hooks are not the lists a client writes`;
   if (next === null) return `${rel}: nothing to change`;
   if (next.trim() === "") {
     rmSync(file);
     for (let dir = dirname(file); dir.startsWith(`${resolve(root)}${sep}`) && !readdirSync(dir).length; dir = dirname(dir)) rmdirSync(dir);
-    return `${rel}: removed, it held only what stick wrote`;
+    return `${rel}: removed, it had only what stick wrote`;
   }
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, next);
-  return `${rel}: ${done}`;
+  return `${rel}: ${typeof done === "function" ? done() : done}`;
 }
 
 function inside(root, file) {