@cursor/july 0.1.2 → 0.1.4

package/src/internal/update-check.ts

@@ -0,0 +1,552 @@
+/**
+ * Outdated-version warning + `agentkit update`.
+ *
+ * Every CLI run of a published install compares its own version against the
+ * npm registry's `latest` dist-tag and warns on stderr when behind. The
+ * registry lookup is cached under the config dir
+ * (`~/.config/agent-serve/update-check.json`) so most runs never touch the
+ * network; a stale cache refreshes inline under a short timeout, and any
+ * network failure is silent (the warning is best-effort, never a blocker).
+ *
+ * `agentkit update` re-runs the lookup fresh, figures out how this copy was
+ * installed (global npm/pnpm/yarn/bun, or a project dependency), and runs the
+ * matching install command.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { z } from "zod";
+import { configDirPath } from "./cursor/credentials.js";
+import { describeError } from "./describe-error.js";
+import {
+  CLI_COMMAND_NAME,
+  isCompiledDistribution,
+  PACKAGE_NAME,
+  packageRootDir,
+  packageVersion,
+} from "./distribution.js";
+import { stderrPalette } from "./terminal-style.js";
+
+const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+
+/** Refresh the registry lookup at most this often. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** Inline refresh budget; a slow registry must not stall the command. */
+const WARN_FETCH_TIMEOUT_MS = 1500;
+
+/** `agentkit update` runs interactively, so it can afford a real timeout. */
+const UPDATE_FETCH_TIMEOUT_MS = 10_000;
+
+// ============================================================================
+// Version comparison (plain semver triples + prerelease, no ranges)
+// ============================================================================
+
+interface ParsedVersion {
+  release: [number, number, number];
+  prerelease: string[];
+}
+
+function parseVersion(version: string): ParsedVersion | undefined {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(
+    version.trim()
+  );
+  if (match === null) {
+    return undefined;
+  }
+  return {
+    release: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] === undefined ? [] : match[4].split("."),
+  };
+}
+
+/**
+ * Semver-style ordering: negative when `a < b`, 0 when equal, positive when
+ * `a > b`. Unparseable versions compare equal (never warn on garbage).
+ */
+export function compareVersions(a: string, b: string): number {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (pa === undefined || pb === undefined) {
+    return 0;
+  }
+  for (let i = 0; i < 3; i++) {
+    const diff = pa.release[i]! - pb.release[i]!;
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  // A release outranks any prerelease of the same triple.
+  if (pa.prerelease.length === 0 || pb.prerelease.length === 0) {
+    return pb.prerelease.length - pa.prerelease.length;
+  }
+  const len = Math.max(pa.prerelease.length, pb.prerelease.length);
+  for (let i = 0; i < len; i++) {
+    const ia = pa.prerelease[i];
+    const ib = pb.prerelease[i];
+    // A longer prerelease list outranks its prefix (1.0.0-a.1 > 1.0.0-a).
+    if (ia === undefined) {
+      return -1;
+    }
+    if (ib === undefined) {
+      return 1;
+    }
+    const na = /^\d+$/.test(ia) ? Number(ia) : undefined;
+    const nb = /^\d+$/.test(ib) ? Number(ib) : undefined;
+    if (na !== undefined && nb !== undefined) {
+      if (na !== nb) {
+        return na - nb;
+      }
+    } else if (na !== undefined) {
+      return -1; // numeric identifiers sort before alphanumeric ones
+    } else if (nb !== undefined) {
+      return 1;
+    } else if (ia !== ib) {
+      return ia < ib ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+// ============================================================================
+// Registry lookup
+// ============================================================================
+
+const distTagResponseSchema = z.object({ version: z.string() });
+
+/**
+ * Latest published version of the package, from the registry's `latest`
+ * dist-tag. Returns undefined on any failure (offline, 404 pre-publish, …).
+ */
+export async function fetchLatestPublishedVersion(options?: {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  packageName?: string;
+}): Promise<string | undefined> {
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const packageName = options?.packageName ?? PACKAGE_NAME;
+  // Scoped names keep the `@` but encode the `/` for the registry path.
+  const url = `${NPM_REGISTRY_URL}/${packageName.replace("/", "%2F")}/latest`;
+  try {
+    const response = await fetchImpl(url, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(options?.timeoutMs ?? WARN_FETCH_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      return undefined;
+    }
+    const body = distTagResponseSchema.safeParse(await response.json());
+    if (!body.success || parseVersion(body.data.version) === undefined) {
+      return undefined;
+    }
+    return body.data.version;
+  } catch {
+    return undefined;
+  }
+}
+
+// ============================================================================
+// Cache (one JSON file next to credentials.json)
+// ============================================================================
+
+const cacheSchema: z.ZodObject<
+  { checkedAt: z.ZodNumber; latestVersion: z.ZodOptional<z.ZodString> },
+  "strip"
+> = z.object({
+  /** Epoch ms of the last registry lookup attempt (success or not). */
+  checkedAt: z.number(),
+  /** Last version the registry reported; absent when lookups keep failing. */
+  latestVersion: z.string().optional(),
+});
+
+export type UpdateCheckCache = z.infer<typeof cacheSchema>;
+
+export function updateCheckCachePath(configDir?: string): string {
+  return join(configDir ?? configDirPath(), "update-check.json");
+}
+
+export async function readUpdateCheckCache(
+  configDir?: string
+): Promise<UpdateCheckCache | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(updateCheckCachePath(configDir), "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    const parsed = cacheSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeUpdateCheckCache(
+  cache: UpdateCheckCache,
+  configDir?: string
+): Promise<void> {
+  const path = updateCheckCachePath(configDir);
+  try {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`);
+  } catch {
+    // Best-effort; a read-only config dir just means re-checking next run.
+  }
+}
+
+// ============================================================================
+// The per-run warning
+// ============================================================================
+
+export interface WarnIfOutdatedOptions {
+  /** Defaults to the running package's own version. */
+  currentVersion?: string;
+  /** Test seam; defaults to the shared config dir. */
+  configDir?: string;
+  fetchImpl?: typeof fetch;
+  /** Test seam; defaults to Date.now(). */
+  now?: number;
+  env?: NodeJS.ProcessEnv;
+  /** Defaults to process.stderr.write. */
+  err?: (text: string) => void;
+  /** Skip the source-checkout guard (tests exercise the full path). */
+  force?: boolean;
+}
+
+/**
+ * Print an outdated-version warning to stderr when a newer release exists.
+ *
+ * Never throws and never blocks longer than {@link WARN_FETCH_TIMEOUT_MS}.
+ * Suppressed on source-checkout runs (there is no installed copy to update),
+ * in CI, and via NO_UPDATE_NOTIFIER / AGENT_SERVE_NO_UPDATE_CHECK.
+ */
+export async function warnIfOutdated(
+  options?: WarnIfOutdatedOptions
+): Promise<void> {
+  const env = options?.env ?? process.env;
+  if (
+    isTruthyEnv(env.AGENT_SERVE_NO_UPDATE_CHECK) ||
+    isTruthyEnv(env.NO_UPDATE_NOTIFIER) ||
+    isTruthyEnv(env.CI)
+  ) {
+    return;
+  }
+  if (options?.force !== true && !isCompiledDistribution()) {
+    return;
+  }
+  const now = options?.now ?? Date.now();
+  const currentVersion = options?.currentVersion ?? packageVersion();
+
+  const cached = await readUpdateCheckCache(options?.configDir);
+  let latestVersion = cached?.latestVersion;
+  const fresh =
+    cached !== undefined && now - cached.checkedAt < CHECK_INTERVAL_MS;
+  if (!fresh) {
+    const fetched = await fetchLatestPublishedVersion({
+      fetchImpl: options?.fetchImpl,
+      timeoutMs: WARN_FETCH_TIMEOUT_MS,
+    });
+    latestVersion = fetched ?? latestVersion;
+    // checkedAt always advances so a flaky registry backs off to one
+    // attempt per interval instead of one per command.
+    await writeUpdateCheckCache(
+      { checkedAt: now, latestVersion },
+      options?.configDir
+    );
+  }
+
+  if (
+    latestVersion === undefined ||
+    compareVersions(currentVersion, latestVersion) >= 0
+  ) {
+    return;
+  }
+  const c = stderrPalette();
+  const err =
+    options?.err ?? ((text: string) => void process.stderr.write(text));
+  err(
+    `${c.yellow("warning:")} ${CLI_COMMAND_NAME} ${currentVersion} is outdated (latest is ${latestVersion}). Run \`${CLI_COMMAND_NAME} update\` to upgrade.\n`
+  );
+}
+
+function isTruthyEnv(value: string | undefined): boolean {
+  return value !== undefined && value !== "" && value !== "0";
+}
+
+// ============================================================================
+// `agentkit update`
+// ============================================================================
+
+export interface UpdateCommand {
+  cmd: string;
+  args: string[];
+  /** Working directory for local project installs. */
+  cwd?: string;
+  /** One-line human description of what will run and why. */
+  reason: string;
+}
+
+/**
+ * Figure out how the running copy was installed and which command upgrades
+ * it. Detection is path-shape based (global stores have recognizable
+ * layouts), then falls back to walking up to the project that declares the
+ * dependency. Returns undefined for layouts we cannot safely upgrade
+ * (npx cache, unrecognized stores).
+ */
+export async function detectUpdateCommand(args: {
+  packageRoot: string;
+  packageName?: string;
+}): Promise<UpdateCommand | undefined> {
+  const packageName = args.packageName ?? PACKAGE_NAME;
+  const spec = `${packageName}@latest`;
+  const posixRoot = args.packageRoot.split(sep).join("/");
+
+  // npx / pnpm dlx caches are ephemeral; a fresh `npx agentkit` already
+  // resolves latest, and upgrading the cache entry in place helps nobody.
+  if (posixRoot.includes("/_npx/") || posixRoot.includes("/.pnpm-store/")) {
+    return undefined;
+  }
+  if (posixRoot.includes("/pnpm/global/")) {
+    return {
+      cmd: "pnpm",
+      args: ["add", "-g", spec],
+      reason: "installed with pnpm --global",
+    };
+  }
+  if (posixRoot.includes("/.bun/install/global/")) {
+    return {
+      cmd: "bun",
+      args: ["add", "-g", spec],
+      reason: "installed with bun --global",
+    };
+  }
+  if (
+    posixRoot.includes("/yarn/global/") ||
+    posixRoot.includes("/.config/yarn/global/")
+  ) {
+    return {
+      cmd: "yarn",
+      args: ["global", "add", spec],
+      reason: "installed with yarn global",
+    };
+  }
+
+  // A project that depends on the package: upgrade the dependency there,
+  // with whichever package manager the lockfile says the project uses.
+  const projectDir = await findDependingProjectDir(
+    args.packageRoot,
+    packageName
+  );
+  if (projectDir !== undefined) {
+    const pm = await detectProjectPackageManager(projectDir);
+    const command =
+      pm === "pnpm"
+        ? { cmd: "pnpm", args: ["add", spec] }
+        : pm === "yarn"
+          ? { cmd: "yarn", args: ["add", spec] }
+          : pm === "bun"
+            ? { cmd: "bun", args: ["add", spec] }
+            : { cmd: "npm", args: ["install", spec] };
+    return {
+      ...command,
+      cwd: projectDir,
+      reason: `project dependency in ${projectDir}`,
+    };
+  }
+
+  // Global npm layout: <prefix>/lib/node_modules/<name> (or <prefix>\
+  // node_modules\<name> on Windows), with no depending project above it.
+  if (posixRoot.includes("/node_modules/")) {
+    return {
+      cmd: "npm",
+      args: ["install", "-g", spec],
+      reason: "installed with npm --global",
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Nearest ancestor with a package.json that declares `packageName` as a
+ * dependency. Skips directories inside node_modules (pnpm's virtual store
+ * nests package.json files that are not the user's project).
+ */
+async function findDependingProjectDir(
+  packageRoot: string,
+  packageName: string
+): Promise<string | undefined> {
+  let dir = dirname(packageRoot);
+  for (let depth = 0; depth < 30; depth++) {
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    const inNodeModules = dir
+      .split(sep)
+      .some((part) => part === "node_modules" || part === ".pnpm");
+    if (!inNodeModules && (await declaresDependency(dir, packageName))) {
+      return dir;
+    }
+    dir = parent;
+  }
+  return undefined;
+}
+
+async function declaresDependency(
+  dir: string,
+  packageName: string
+): Promise<boolean> {
+  let raw: string;
+  try {
+    raw = await readFile(join(dir, "package.json"), "utf8");
+  } catch {
+    return false;
+  }
+  const manifestSchema = z.object({
+    dependencies: z.record(z.string()).optional(),
+    devDependencies: z.record(z.string()).optional(),
+  });
+  try {
+    const parsed = manifestSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+      return false;
+    }
+    return (
+      parsed.data.dependencies?.[packageName] !== undefined ||
+      parsed.data.devDependencies?.[packageName] !== undefined
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function detectProjectPackageManager(
+  projectDir: string
+): Promise<"pnpm" | "yarn" | "bun" | "npm"> {
+  const exists = async (file: string): Promise<boolean> => {
+    try {
+      await stat(join(projectDir, file));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (await exists("pnpm-lock.yaml")) {
+    return "pnpm";
+  }
+  if (await exists("yarn.lock")) {
+    return "yarn";
+  }
+  if ((await exists("bun.lock")) || (await exists("bun.lockb"))) {
+    return "bun";
+  }
+  return "npm";
+}
+
+export interface UpdateCliOptions {
+  /** Test seams. */
+  fetchImpl?: typeof fetch;
+  currentVersion?: string;
+  packageRoot?: string;
+  configDir?: string;
+  runCommand?: (command: UpdateCommand) => Promise<number>;
+  compiled?: boolean;
+  out?: (text: string) => void;
+  err?: (text: string) => void;
+}
+
+/** `agentkit update` — upgrade this install to the latest published version. */
+export async function cmdUpdate(options?: UpdateCliOptions): Promise<number> {
+  const c = stderrPalette();
+  const out =
+    options?.out ?? ((text: string) => void process.stdout.write(text));
+  const err =
+    options?.err ?? ((text: string) => void process.stderr.write(text));
+  const compiled = options?.compiled ?? isCompiledDistribution();
+  if (!compiled) {
+    err(
+      `${CLI_COMMAND_NAME} is running from a source checkout, not an installed package; update it with git instead.\n`
+    );
+    return 1;
+  }
+
+  const currentVersion = options?.currentVersion ?? packageVersion();
+  const latestVersion = await fetchLatestPublishedVersion({
+    fetchImpl: options?.fetchImpl,
+    timeoutMs: UPDATE_FETCH_TIMEOUT_MS,
+  });
+  if (latestVersion === undefined) {
+    err(
+      `Could not reach the npm registry to look up the latest ${PACKAGE_NAME} version. Check your network and retry.\n`
+    );
+    return 1;
+  }
+  if (compareVersions(currentVersion, latestVersion) >= 0) {
+    out(
+      `${CLI_COMMAND_NAME} ${currentVersion} is already the latest version.\n`
+    );
+    await writeUpdateCheckCache(
+      { checkedAt: Date.now(), latestVersion },
+      options?.configDir
+    );
+    return 0;
+  }
+
+  const command = await detectUpdateCommand({
+    packageRoot: options?.packageRoot ?? packageRootDir(),
+  });
+  if (command === undefined) {
+    err(
+      `${CLI_COMMAND_NAME} ${currentVersion} is outdated (latest is ${latestVersion}), but this install's layout was not recognized.\nUpgrade it yourself, e.g. \`npm install -g ${PACKAGE_NAME}@latest\` for a global install, or bump the ${PACKAGE_NAME} dependency in your project.\n`
+    );
+    return 1;
+  }
+
+  const rendered = [command.cmd, ...command.args].join(" ");
+  err(
+    c.dim(
+      `Updating ${CLI_COMMAND_NAME} ${currentVersion} → ${latestVersion} (${command.reason}):\n  ${rendered}\n`
+    )
+  );
+  const run = options?.runCommand ?? runUpdateCommand;
+  let code: number;
+  try {
+    code = await run(command);
+  } catch (error) {
+    err(`\`${rendered}\` failed: ${describeError(error)}\n`);
+    return 1;
+  }
+  if (code !== 0) {
+    err(`\`${rendered}\` exited with code ${code}.\n`);
+    return code;
+  }
+  await writeUpdateCheckCache(
+    { checkedAt: Date.now(), latestVersion },
+    options?.configDir
+  );
+  out(
+    `Updated ${CLI_COMMAND_NAME} to ${latestVersion}. New commands run the new version.\n`
+  );
+  return 0;
+}
+
+function runUpdateCommand(command: UpdateCommand): Promise<number> {
+  return new Promise((resolve, reject) => {
+    // Windows-only shell: npm/pnpm/yarn/bun are .cmd shims there, and Node
+    // refuses to spawn .cmd files without a shell (EINVAL, CVE-2024-27980
+    // hardening). Injection-safe: cmd and args are module-level constants
+    // from detectUpdateCommand (never user or registry input).
+    // nosemgrep: javascript.lang.security.audit.spawn-shell-true.spawn-shell-true
+    const child = spawn(command.cmd, command.args, {
+      stdio: "inherit",
+      cwd: command.cwd,
+      shell: process.platform === "win32",
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/internal/workspace.ts

@@ -15,6 +15,7 @@ import type {
   ResolvedAgent,
 } from "../types.js";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+import { buildIdentitySection } from "./prompt-context.js";
 
 export interface MaterializeWorkspaceOptions {
   agent: ResolvedAgent;
@@ -31,6 +32,41 @@ export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;
 }
 
+/**
+ * Always-on identity line prepended when composing instructions. Sourced from
+ * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
+ * so agents know who they are without restating it in authored prose.
+ */
+export function buildIdentityPreamble(name: string): string {
+  const trimmed = name.trim();
+  if (trimmed === "") {
+    return "";
+  }
+  return `You are ${trimmed}. That is your name; use it when people ask who you are.`;
+}
+
+/**
+ * Prepend {@link buildIdentityPreamble} to authored instructions. Used when
+ * loading `instructions.md` / `.ts` / dir into {@link ResolvedAgent.instructions}.
+ */
+export function withIdentityPreamble(
+  name: string,
+  instructions: string | undefined
+): string | undefined {
+  const preamble = buildIdentityPreamble(name);
+  const body = instructions?.trim() ?? "";
+  if (preamble === "" && body === "") {
+    return undefined;
+  }
+  if (preamble === "") {
+    return body === "" ? undefined : body;
+  }
+  if (body === "") {
+    return preamble;
+  }
+  return `${preamble}\n\n${body}`;
+}
+
 /**
  * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
  *
@@ -96,12 +132,14 @@ export async function materializeWorkspace(
   const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
     includeScripts: false,
   });
-  const agentsMd = [agent.instructions?.trim() ?? "", agentToolsSection]
+  const agentsMd = [
+    agent.instructions?.trim() ?? "",
+    buildIdentitySection(agent),
+    agentToolsSection,
+  ]
     .filter((part) => part !== "")
     .join("\n\n");
-  if (agentsMd !== "") {
-    await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
-  }
+  await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
 
   for (const tool of agent.tools) {
     if (tool.execution !== "agent" || tool.script === undefined) {