@cursor/july 0.1.2 → 0.1.3

package/src/internal/init-project.ts

@@ -2,14 +2,20 @@
  * Scaffold a minimal agent-serve project (`agent-serve init`).
  */
 
+import { spawn } from "node:child_process";
 import { mkdir, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import type { ModelSetting } from "../types.js";
 import {
   CLI_COMMAND_NAME,
   PACKAGE_NAME,
   packageVersion,
 } from "./distribution.js";
+import {
+  makePalette,
+  stdoutPalette,
+  type TerminalPalette,
+} from "./terminal-style.js";
 
 export interface InitProjectOptions {
   /** Directory to create (created if missing). */
@@ -20,9 +26,21 @@ export interface InitProjectOptions {
   model?: string;
 }
 
+export type InitFileAction = "create" | "exist";
+
+export interface InitFileEntry {
+  path: string;
+  action: InitFileAction;
+}
+
 export interface InitProjectResult {
   rootDir: string;
-  files: string[];
+  /** Scaffold files in write order, with create/exist for each. */
+  files: InitFileEntry[];
+  /** Paths newly written. */
+  created: string[];
+  /** Paths left alone because they already existed. */
+  skipped: string[];
 }
 
 const DEFAULT_MODEL: ModelSetting = {
@@ -33,6 +51,23 @@ const DEFAULT_MODEL: ModelSetting = {
   ],
 };
 
+/**
+ * Empty capability folders the scaffold creates (each gets a `.gitkeep`).
+ * `agent/tools/` is omitted — the demo `echo.ts` already keeps it in git.
+ */
+const SCAFFOLD_EMPTY_DIRS: readonly string[] = [
+  "agent/skills",
+  "agent/mcp-connections",
+  "agent/subagents",
+  "agent/channels",
+  "agent/hooks",
+  "agent/ab",
+  "agent/schedules",
+  "agent/sandbox/workspace",
+  "agent/lib",
+  "evals",
+];
+
 export async function initProject(
   options: InitProjectOptions
 ): Promise<InitProjectResult> {
@@ -42,52 +77,85 @@ export async function initProject(
   const agentDir = join(rootDir, "agent");
   await mkdir(agentDir, { recursive: true });
 
-  const written: string[] = [];
+  const files: InitFileEntry[] = [];
   const write = async (rel: string, contents: string): Promise<void> => {
     const abs = join(rootDir, rel);
     await mkdir(dirname(abs), { recursive: true });
-    await writeFile(abs, contents, { flag: "wx" });
-    written.push(rel);
+    try {
+      await writeFile(abs, contents, { flag: "wx" });
+      files.push({ path: rel, action: "create" });
+    } catch (error) {
+      if (isEexist(error)) {
+        // Rails generators leave existing files alone (`exist`).
+        files.push({ path: rel, action: "exist" });
+        return;
+      }
+      throw error;
+    }
   };
 
-  try {
-    await write(
-      "package.json",
-      `${JSON.stringify(
-        {
-          name,
-          private: true,
-          type: "module",
-          description: `agent project: ${name}`,
-          dependencies: {
-            [PACKAGE_NAME]: `^${packageVersion()}`,
-            zod: "^3.25.0",
-          },
+  await write(
+    "package.json",
+    `${JSON.stringify(
+      {
+        name,
+        private: true,
+        type: "module",
+        description: `agent project: ${name}`,
+        scripts: {
+          check: "tsc --noEmit",
+        },
+        dependencies: {
+          [PACKAGE_NAME]: `^${packageVersion()}`,
+          zod: "^3.25.0",
         },
-        null,
-        2
-      )}\n`
-    );
-    await write(
-      "agent/agent.ts",
-      `import { defineAgent } from "${PACKAGE_NAME}";
+        devDependencies: {
+          "@types/node": "^22.14.0",
+          typescript: "^5.8.0",
+        },
+      },
+      null,
+      2
+    )}\n`
+  );
+  await write(
+    "tsconfig.json",
+    `{
+  // Type-checking only (npm run check): the framework runs agent/ code
+  // directly through tsx, so nothing is compiled.
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}
+`
+  );
+  await write(
+    "agent/agent.ts",
+    `import { defineAgent } from "${PACKAGE_NAME}";
 
 export default defineAgent({
   model: ${model},
 });
 `
-    );
-    await write(
-      "agent/instructions.md",
-      `# ${name}
+  );
+  await write(
+    "agent/instructions.md",
+    `# ${name}
 
 You are a helpful agent. Prefer tools when they fit the request.
 Keep answers concise unless the user asks for detail.
 `
-    );
-    await write(
-      "agent/tools/echo.ts",
-      `import { defineTool } from "${PACKAGE_NAME}/tools";
+  );
+  await write(
+    "agent/tools/echo.ts",
+    `import { defineTool } from "${PACKAGE_NAME}/tools";
 import { z } from "zod";
 
 export default defineTool({
@@ -98,22 +166,99 @@ export default defineTool({
   },
 });
 `
-    );
-  } catch (error) {
-    if (
-      error !== null &&
-      typeof error === "object" &&
-      "code" in error &&
-      (error as { code: string }).code === "EEXIST"
-    ) {
-      throw new Error(
-        `Refusing to overwrite existing files under ${rootDir}. Pick an empty directory or remove the conflicting files.`
-      );
-    }
-    throw error;
+  );
+
+  for (const dir of SCAFFOLD_EMPTY_DIRS) {
+    await write(`${dir}/.gitkeep`, "");
   }
 
-  return { rootDir, files: written };
+  return {
+    rootDir,
+    files,
+    created: files
+      .filter((entry) => entry.action === "create")
+      .map((entry) => entry.path),
+    skipped: files
+      .filter((entry) => entry.action === "exist")
+      .map((entry) => entry.path),
+  };
+}
+
+function isEexist(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === "object" &&
+    "code" in error &&
+    (error as { code: string }).code === "EEXIST"
+  );
+}
+
+export interface InstallScaffoldDependenciesOptions {
+  /**
+   * `inherit` streams npm output to the terminal (human `init`);
+   * `pipe` captures it ( `--json` / tests).
+   */
+  stdio?: "inherit" | "pipe";
+  /** Test seam — replaces the real `npm install` spawn. */
+  runner?: (args: {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdio: "inherit" | "pipe";
+  }) => Promise<{ exitCode: number; stderr: string }>;
+}
+
+export interface InstallScaffoldDependenciesResult {
+  ok: boolean;
+  exitCode: number;
+  stderr: string;
+}
+
+/**
+ * Install the scaffold's npm dependencies so `dev` / `run` can resolve
+ * `@cursor/july` immediately after `init`.
+ */
+export async function installScaffoldDependencies(
+  rootDir: string,
+  options: InstallScaffoldDependenciesOptions = {}
+): Promise<InstallScaffoldDependenciesResult> {
+  const stdio = options.stdio ?? "inherit";
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const args = ["install", "--no-fund", "--no-audit"];
+  const runner = options.runner ?? defaultNpmInstallRunner;
+  const result = await runner({ command, args, cwd: rootDir, stdio });
+  return {
+    ok: result.exitCode === 0,
+    exitCode: result.exitCode,
+    stderr: result.stderr,
+  };
+}
+
+async function defaultNpmInstallRunner(args: {
+  command: string;
+  args: string[];
+  cwd: string;
+  stdio: "inherit" | "pipe";
+}): Promise<{ exitCode: number; stderr: string }> {
+  return await new Promise((resolvePromise, reject) => {
+    const child = spawn(args.command, args.args, {
+      cwd: args.cwd,
+      stdio: args.stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+    let stderr = "";
+    if (args.stdio === "pipe") {
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (chunk: string) => {
+        stderr += chunk;
+      });
+      child.stdout?.resume();
+    }
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolvePromise({ exitCode: code ?? 1, stderr });
+    });
+  });
 }
 
 function formatModelLiteral(model: string | ModelSetting): string {
@@ -137,6 +282,142 @@ ${model.params
   }`;
 }
 
+export interface InitScaffoldSummaryOptions {
+  /** Scaffolded project root (absolute). */
+  rootDir: string;
+  /** Scaffold files in write order (`create` / `exist`). */
+  files: InitFileEntry[];
+  /** Override TTY color detection (tests / `--json` callers). */
+  color?: boolean;
+}
+
+export interface InitNextStepsOptions {
+  /** Scaffolded project root (absolute). */
+  rootDir: string;
+  /** Directory the command ran from. */
+  cwd: string;
+  /**
+   * True when a Cursor credential resolves. When false, next steps include
+   * `login` (used for `--json` and when an interactive login attempt failed).
+   */
+  signedIn: boolean;
+  /** Override TTY color detection (tests / `--json` callers). */
+  color?: boolean;
+}
+
+export type InitSummaryOptions = InitScaffoldSummaryOptions &
+  InitNextStepsOptions;
+
+function initPalette(color?: boolean): TerminalPalette {
+  return color === undefined ? stdoutPalette() : makePalette(color);
+}
+
+/**
+ * Created/skipped files plus the project path. Printed before an interactive
+ * login so the scaffold is visible while the browser flow runs.
+ */
+export function formatInitScaffoldSummary(
+  options: InitScaffoldSummaryOptions
+): string {
+  const c = initPalette(options.color);
+  const name = basename(options.rootDir);
+  const lines: string[] = [];
+  lines.push(`Initialized agent ${name}`);
+  lines.push("");
+  for (const file of options.files) {
+    // Empty-dir placeholders stay on disk but clutter the summary.
+    if (file.path.endsWith("/.gitkeep") || file.path === ".gitkeep") {
+      continue;
+    }
+    // Thor/Rails status column is 12 chars, right-aligned.
+    lines.push(c.dim(`${file.action.padStart(12)}  ${file.path}`));
+  }
+  lines.push("");
+  lines.push(c.dim(`Project: ${options.rootDir}`));
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Numbered next steps after scaffold (and after login when init ran it).
+ * Includes `cd` when init did not already run inside the project.
+ */
+export function formatInitNextSteps(options: InitNextStepsOptions): string {
+  const c = initPalette(options.color);
+  const lines: string[] = [];
+  lines.push("Next steps:");
+  lines.push("");
+
+  const steps = initNextStepEntries(options);
+  const width = Math.max(...steps.map((step) => step.command.length));
+  for (const [index, step] of steps.entries()) {
+    const command =
+      step.note === undefined
+        ? step.command
+        : `${step.command.padEnd(width)}   ${c.dim(`# ${step.note}`)}`;
+    lines.push(`  ${index + 1}. ${command}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Full human-readable scaffold summary (scaffold + next steps).
+ */
+export function formatInitSummary(options: InitSummaryOptions): string {
+  return formatInitScaffoldSummary(options) + formatInitNextSteps(options);
+}
+
+/**
+ * `cd` into the scaffold when init did not already run inside it. Relative
+ * when the target sits under the invoking directory, absolute otherwise.
+ */
+export function formatCdCommand(
+  cwd: string,
+  rootDir: string
+): string | undefined {
+  const rel = relative(cwd, rootDir);
+  if (rel === "") {
+    return undefined;
+  }
+  const path = rel.startsWith("..") ? rootDir : rel;
+  const quoted = /\s/.test(path) ? JSON.stringify(path) : path;
+  return `cd ${quoted}`;
+}
+
+function initNextStepEntries(options: InitNextStepsOptions): Array<{
+  command: string;
+  note?: string;
+}> {
+  const steps: Array<{ command: string; note?: string }> = [];
+  const cd = formatCdCommand(options.cwd, options.rootDir);
+  if (cd !== undefined) {
+    steps.push({ command: cd });
+  }
+  if (!options.signedIn) {
+    steps.push({
+      command: `${CLI_COMMAND_NAME} login`,
+      note: "connect your Cursor account (powers model turns)",
+    });
+  }
+  steps.push({
+    command: `${CLI_COMMAND_NAME} dev`,
+    note: "start the local playground",
+  });
+  return steps;
+}
+
+/**
+ * Next-step commands for the `--json` scaffold summary (login omitted when
+ * the host already has a Cursor credential).
+ */
+export function initNextCommands(options: {
+  rootDir: string;
+  cwd: string;
+  signedIn: boolean;
+}): string[] {
+  return initNextStepEntries(options).map((step) => step.command);
+}
+
 /**
  * Coding-agent setup guide printed by `agent-serve init`
  * with no target directory (does not scaffold).
@@ -144,15 +425,16 @@ ${model.params
 export function printInitGuide(): void {
   process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
 
-Recommended loop:
+Scaffold a project, then open the playground:
+  ${CLI_COMMAND_NAME} init ./my-agent   # installs deps; signs you in when needed
+  cd ./my-agent && ${CLI_COMMAND_NAME} dev
+
+Recommended loop once the project exists:
   1. Edit agent/ + tools under agent/tools/
   2. ${CLI_COMMAND_NAME} info --dir . --json
   3. ${CLI_COMMAND_NAME} run --dir . --message "..."
   4. ${CLI_COMMAND_NAME} eval --dir .
 
-Scaffold a project:
-  ${CLI_COMMAND_NAME} init ./my-agent
-
 Evals:
   Create evals/**/*.eval.ts using defineEval from ${PACKAGE_NAME}/evals
   Case id is the path: evals/weather/nyc.eval.ts → weather/nyc