@cursor/july 0.1.55 → 0.1.61

package/src/internal/init-interview.ts

@@ -0,0 +1,384 @@
+/**
+ * Template `init.json`: questions `init` asks, and string replacements
+ * it applies while copying the scaffold.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { parseCursorGithubRepoScope } from "../channels/github/cursor-account.js";
+import { describeError } from "./describe-error.js";
+
+export const TEMPLATE_INIT_FILE = "init.json";
+
+export interface TemplateQuestion {
+  id: string;
+  prompt: string;
+  hint?: string;
+  placeholder?: string;
+  default?: string;
+  choices?: readonly string[];
+  parse?: "owner-repo-list";
+}
+
+export interface TemplateReplace {
+  file: string;
+  find: string;
+  answer: string;
+  as?: "json-array" | "first";
+  template?: string;
+}
+
+export interface TemplateInitSpec {
+  questions: TemplateQuestion[];
+  replace: TemplateReplace[];
+}
+
+export function posixRel(rel: string): string {
+  return rel.replaceAll("\\", "/");
+}
+
+export function isTemplateMetaPath(rel: string): boolean {
+  const normalized = posixRel(rel);
+  const top = normalized.split("/")[0];
+  if (top === "overlays") {
+    return true;
+  }
+  return (
+    normalized === TEMPLATE_INIT_FILE ||
+    normalized.endsWith(`/${TEMPLATE_INIT_FILE}`)
+  );
+}
+
+export function templateFileHasReplacements(
+  spec: TemplateInitSpec,
+  rel: string
+): boolean {
+  const file = posixRel(rel);
+  return spec.replace.some((rule) => posixRel(rule.file) === file);
+}
+
+export async function loadTemplateInitSpec(
+  templateDir: string
+): Promise<TemplateInitSpec | undefined> {
+  try {
+    const text = await readFile(join(templateDir, TEMPLATE_INIT_FILE), "utf8");
+    return parseTemplateInitSpec(JSON.parse(text));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export function parseTemplateInitSpec(value: unknown): TemplateInitSpec {
+  if (!isRecord(value) || !Array.isArray(value.questions)) {
+    throw new Error(`${TEMPLATE_INIT_FILE} must have a questions array`);
+  }
+  const questions = value.questions.map((item, index) =>
+    parseQuestion(item, index)
+  );
+  const replace = Array.isArray(value.replace)
+    ? value.replace.map((item, index) => parseReplace(item, index))
+    : [];
+  return { questions, replace };
+}
+
+export function parseInitVars(
+  flags: readonly string[] | undefined
+): Record<string, string> {
+  const vars: Record<string, string> = {};
+  if (flags === undefined) {
+    return vars;
+  }
+  for (const flag of flags) {
+    const eq = flag.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`--var must be id=value (got ${JSON.stringify(flag)})`);
+    }
+    vars[flag.slice(0, eq)] = flag.slice(eq + 1);
+  }
+  return vars;
+}
+
+export type ParseAnswersResult =
+  | { ok: true; answers: Record<string, string> }
+  | { ok: false; error: string };
+
+export type RunTemplateInitResult =
+  | { ok: true; spec?: TemplateInitSpec; answers?: Record<string, string> }
+  | { ok: false; error: string };
+
+/** Load `init.json`, apply `--var`, and prompt on a TTY. */
+export async function runTemplateInit(input: {
+  templateDir: string;
+  vars?: readonly string[];
+  interactive: boolean;
+}): Promise<RunTemplateInitResult> {
+  try {
+    const spec = await loadTemplateInitSpec(input.templateDir);
+    if (spec === undefined) {
+      return { ok: true };
+    }
+    const collected = await collectTemplateAnswers({
+      spec,
+      vars: parseInitVars(input.vars),
+      interactive: input.interactive,
+    });
+    if (!collected.ok) {
+      return collected;
+    }
+    return { ok: true, spec, answers: collected.answers };
+  } catch (error) {
+    return { ok: false, error: describeError(error) };
+  }
+}
+
+export function parseTemplateAnswers(
+  spec: TemplateInitSpec,
+  raw: Record<string, string>
+): ParseAnswersResult {
+  const answers: Record<string, string> = {};
+  for (const question of spec.questions) {
+    if (!(question.id in raw)) {
+      continue;
+    }
+    const parsed = parseQuestionValue(question, raw[question.id] ?? "");
+    if (!parsed.ok) {
+      return parsed;
+    }
+    answers[question.id] = parsed.value;
+  }
+  return { ok: true, answers };
+}
+
+export interface CollectAnswersInput {
+  spec: TemplateInitSpec;
+  vars?: Record<string, string>;
+  interactive: boolean;
+  ask?: (question: TemplateQuestion) => Promise<string>;
+  out?: (text: string) => void;
+}
+
+export async function collectTemplateAnswers(
+  input: CollectAnswersInput
+): Promise<ParseAnswersResult> {
+  const vars = input.vars ?? {};
+  const answers: Record<string, string> = {};
+  const ask = input.ask ?? promptTemplateQuestion;
+  const out = input.out ?? ((text) => process.stdout.write(text));
+
+  for (const question of input.spec.questions) {
+    if (question.id in vars) {
+      const parsed = parseQuestionValue(question, vars[question.id] ?? "");
+      if (!parsed.ok) {
+        return parsed;
+      }
+      answers[question.id] = parsed.value;
+      continue;
+    }
+    if (!input.interactive) {
+      continue;
+    }
+    for (;;) {
+      const line = await ask(question);
+      const value =
+        line.trim() === "" && question.default !== undefined
+          ? question.default
+          : line;
+      const parsed = parseQuestionValue(question, value);
+      if (parsed.ok) {
+        answers[question.id] = parsed.value;
+        break;
+      }
+      out(`${parsed.error}\n`);
+    }
+  }
+
+  return { ok: true, answers };
+}
+
+export function applyInitReplacements(
+  contents: string,
+  rel: string,
+  spec: TemplateInitSpec,
+  answers: Record<string, string>
+): string {
+  const file = posixRel(rel);
+  let next = contents;
+  for (const rule of spec.replace) {
+    if (posixRel(rule.file) !== file) {
+      continue;
+    }
+    const value = formatReplaceValue(rule, answers);
+    if (value === undefined) {
+      continue;
+    }
+    if (!next.includes(rule.find)) {
+      throw new Error(
+        `${TEMPLATE_INIT_FILE}: ${rule.find} not found in ${rel}`
+      );
+    }
+    next = replaceLiteral(next, rule.find, value);
+  }
+  return next;
+}
+
+export async function promptTemplateQuestion(
+  question: TemplateQuestion,
+  options: {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+  } = {}
+): Promise<string> {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const rl = createInterface({ input, output });
+  const suffix = promptSuffix(question);
+  try {
+    if (question.hint !== undefined) {
+      output.write(`  ${question.hint}\n`);
+    }
+    return await new Promise<string>((resolve) => {
+      rl.question(`${question.prompt}${suffix} `, resolve);
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+function replaceLiteral(haystack: string, find: string, value: string): string {
+  return haystack.replaceAll(find, () => value);
+}
+
+function promptSuffix(question: TemplateQuestion): string {
+  if (question.choices !== undefined && question.choices.length > 0) {
+    return ` [${question.choices.join("/")}]`;
+  }
+  if (question.default !== undefined) {
+    return ` [${question.default}]`;
+  }
+  if (question.placeholder !== undefined) {
+    return ` (${question.placeholder})`;
+  }
+  return "";
+}
+
+function parseQuestionValue(
+  question: TemplateQuestion,
+  raw: string
+): { ok: true; value: string } | { ok: false; error: string } {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    return { ok: false, error: `${question.id} is required.` };
+  }
+  if (question.choices !== undefined && question.choices.length > 0) {
+    if (!question.choices.includes(trimmed)) {
+      return {
+        ok: false,
+        error: `${question.id} must be one of ${question.choices.join(", ")}.`,
+      };
+    }
+    return { ok: true, value: trimmed };
+  }
+  if (question.parse === "owner-repo-list") {
+    try {
+      const scope = parseCursorGithubRepoScope(
+        trimmed.split(",").map((repo) => repo.trim())
+      );
+      return { ok: true, value: scope.repos.join(", ") };
+    } catch (error) {
+      return { ok: false, error: describeError(error) };
+    }
+  }
+  return { ok: true, value: trimmed };
+}
+
+function formatReplaceValue(
+  rule: TemplateReplace,
+  answers: Record<string, string>
+): string | undefined {
+  const raw = answers[rule.answer];
+  if (raw === undefined || raw === "") {
+    return undefined;
+  }
+  const parts = raw.split(",").map((part) => part.trim());
+  let value = raw;
+  if (rule.as === "json-array") {
+    value = `[${parts.map((part) => JSON.stringify(part)).join(", ")}]`;
+  } else if (rule.as === "first") {
+    const first = parts[0];
+    if (first === undefined || first === "") {
+      return undefined;
+    }
+    value = first;
+  }
+  if (rule.template !== undefined) {
+    return replaceLiteral(rule.template, "{{value}}", value);
+  }
+  return value;
+}
+
+function parseQuestion(value: unknown, index: number): TemplateQuestion {
+  if (!isRecord(value) || typeof value.id !== "string" || value.id === "") {
+    throw new Error(`${TEMPLATE_INIT_FILE} questions[${index}] needs an id`);
+  }
+  if (typeof value.prompt !== "string" || value.prompt === "") {
+    throw new Error(
+      `${TEMPLATE_INIT_FILE} questions[${value.id}] needs a prompt`
+    );
+  }
+  const question: TemplateQuestion = {
+    id: value.id,
+    prompt: value.prompt,
+  };
+  if (typeof value.hint === "string") {
+    question.hint = value.hint;
+  }
+  if (typeof value.placeholder === "string") {
+    question.placeholder = value.placeholder;
+  }
+  if (typeof value.default === "string") {
+    question.default = value.default;
+  }
+  if (Array.isArray(value.choices)) {
+    question.choices = value.choices.map((choice) => String(choice));
+  }
+  if (value.parse === "owner-repo-list") {
+    question.parse = "owner-repo-list";
+  }
+  return question;
+}
+
+function parseReplace(value: unknown, index: number): TemplateReplace {
+  if (
+    !isRecord(value) ||
+    typeof value.file !== "string" ||
+    value.file === "" ||
+    typeof value.find !== "string" ||
+    value.find === "" ||
+    typeof value.answer !== "string" ||
+    value.answer === ""
+  ) {
+    throw new Error(
+      `${TEMPLATE_INIT_FILE} replace[${index}] needs file, find, and answer`
+    );
+  }
+  const rule: TemplateReplace = {
+    file: value.file,
+    find: value.find,
+    answer: value.answer,
+  };
+  if (value.as === "json-array" || value.as === "first") {
+    rule.as = value.as;
+  }
+  if (typeof value.template === "string") {
+    rule.template = value.template;
+  }
+  return rule;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/internal/init-project.ts

@@ -13,6 +13,14 @@ import {
   packageRootDir,
   packageVersion,
 } from "./distribution.js";
+import {
+  applyInitReplacements,
+  isTemplateMetaPath,
+  loadTemplateInitSpec,
+  posixRel,
+  type TemplateInitSpec,
+  templateFileHasReplacements,
+} from "./init-interview.js";
 import {
   makePalette,
   stdoutPalette,
@@ -29,6 +37,9 @@ export interface InitProjectOptions {
   templateDir?: string;
   overlayDir?: string;
   templateName?: string;
+  /** Answers collected from `init.json` / `--var`. */
+  answers?: Record<string, string>;
+  initSpec?: TemplateInitSpec;
 }
 
 export type InitFileAction = "create" | "exist";
@@ -48,9 +59,18 @@ export interface InitProjectResult {
   skipped: string[];
 }
 
-const TRIAGE_OVERLAYS: Readonly<Record<string, string>> = {
-  "triage-linear": "linear",
-  "triage-jira": "jira",
+type TemplateEntry = {
+  dir: string;
+  overlay?: string;
+};
+
+const TEMPLATES: Readonly<Record<string, TemplateEntry>> = {
+  "agentic-owners": { dir: "agentic-owners" },
+  demo: { dir: "demo" },
+  "pr-autofixer": { dir: "pr-autofixer" },
+  "security-reviewer": { dir: "security-reviewer" },
+  "triage-linear": { dir: "triage", overlay: "linear" },
+  "triage-jira": { dir: "triage", overlay: "jira" },
 };
 
 function canonicalTemplateName(name: string): string {
@@ -58,7 +78,7 @@ function canonicalTemplateName(name: string): string {
 }
 
 export function availableTemplates(): string[] {
-  return Object.keys(TRIAGE_OVERLAYS).sort();
+  return Object.keys(TEMPLATES).sort();
 }
 
 export type TemplateResolution =
@@ -73,19 +93,22 @@ export function resolveTemplate(name: string): TemplateResolution {
     };
   }
   const resolved = canonicalTemplateName(name);
-  const overlay = TRIAGE_OVERLAYS[resolved];
-  if (overlay !== undefined) {
-    const dir = join(packageRootDir(), "templates", "triage");
+  const entry = TEMPLATES[resolved];
+  if (entry === undefined) {
     return {
-      ok: true,
-      name: resolved,
-      dir,
-      overlayDir: join(dir, "overlays", overlay),
+      ok: false,
+      message: `unknown template "${name}" (available: ${availableTemplates().join(", ")})`,
     };
   }
+  const dir = join(packageRootDir(), "templates", entry.dir);
   return {
-    ok: false,
-    message: `unknown template "${name}" (available: ${availableTemplates().join(", ")})`,
+    ok: true,
+    name: resolved,
+    dir,
+    overlayDir:
+      entry.overlay === undefined
+        ? undefined
+        : join(dir, "overlays", entry.overlay),
   };
 }
 
@@ -207,6 +230,9 @@ export async function initProject(
       (rel) => !overlaySet.has(rel)
     );
     const templateName = options.templateName ?? basename(templateDir);
+    const initSpec =
+      options.initSpec ?? (await loadTemplateInitSpec(templateDir));
+    const answers = options.answers ?? {};
     for (const rel of corePaths) {
       await writeTemplateFile({
         write,
@@ -214,6 +240,8 @@ export async function initProject(
         rel,
         projectName,
         templateName,
+        initSpec,
+        answers,
       });
     }
     if (overlayDir !== undefined) {
@@ -224,6 +252,8 @@ export async function initProject(
           rel,
           projectName,
           templateName,
+          initSpec,
+          answers,
         });
       }
     }
@@ -362,8 +392,10 @@ async function listTemplateFiles(root: string): Promise<string[]> {
   });
   return entries
     .filter((entry) => entry.isFile())
-    .map((entry) => relative(root, join(entry.parentPath, entry.name)))
-    .filter((rel) => rel.split(/[\\/]/)[0] !== "overlays")
+    .map((entry) =>
+      posixRel(relative(root, join(entry.parentPath, entry.name)))
+    )
+    .filter((rel) => !isTemplateMetaPath(rel))
     .sort();
 }
 
@@ -373,6 +405,8 @@ async function writeTemplateFile(input: {
   rel: string;
   projectName: string;
   templateName: string;
+  initSpec?: TemplateInitSpec;
+  answers: Record<string, string>;
 }): Promise<void> {
   const source = join(input.sourceDir, input.rel);
   if (input.rel === "package.json") {
@@ -387,6 +421,21 @@ async function writeTemplateFile(input: {
     await input.write(input.rel, `${JSON.stringify(packageJson, null, 2)}\n`);
     return;
   }
+  if (
+    input.initSpec !== undefined &&
+    templateFileHasReplacements(input.initSpec, input.rel)
+  ) {
+    await input.write(
+      input.rel,
+      applyInitReplacements(
+        await readFile(source, "utf8"),
+        input.rel,
+        input.initSpec,
+        input.answers
+      )
+    );
+    return;
+  }
   await input.write(input.rel, await readFile(source));
 }
 
@@ -784,8 +833,14 @@ export function printInitGuide(): void {
 
 Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
+  npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
+  npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
   npx ${PACKAGE_NAME} init ./my-triage --template triage-linear   # comment on Linear issues
   npx ${PACKAGE_NAME} init ./my-triage --template triage-jira     # comment on Jira issues
+  npx ${PACKAGE_NAME} init ./my-owners --template agentic-owners  # review PRs via owners policies
+  npx ${PACKAGE_NAME} init ./pr-autofixer --template pr-autofixer # fix PRs on a cloud VM
+  # TTY asks for GitHub repos. Scripts pass --var:
+  #   --var repos=acme/widgets,acme/api
   cd ./my-agent && agent-sdk dev        # or: npx ${PACKAGE_NAME} dev
 
 Recommended loop once the project exists (from the project directory):

package/src/internal/mcp-endpoint.ts

@@ -82,6 +82,13 @@ interface ConnectableMcpServer {
  * transport per POST, JSON response mode, spec-compliant 405 on other
  * methods. Shared by the per-agent MCP endpoint and the Cursor account
  * bridge so the subtle transport/error plumbing exists once.
+ *
+ * Origin MCP in `backend/server/src/origin/mcp/originMcpHttpHandler.ts`
+ * is not a 1:1 copy: it races `request.signal` so a tool that ignores abort
+ * cannot hang, while this helper has no such backstop and still leaks an
+ * unsettled promise. backend/server cannot import `@cursor/july` internals,
+ * so Origin diverges on purpose. Do not extract a shared package, and do
+ * not port the abort race here, in that stack.
  */
 export async function handleStatelessMcpRequest(args: {
   request: Request;