create-nevex-agent 0.1.1 → 0.2.0

package/README.md

@@ -6,6 +6,18 @@ Genera un proyecto independiente a partir del template de Nevex:
 npx create-nevex-agent coagua --display-name "Coagua"
 ```
 
+Por defecto crea la instalación en modo Cloudflare (Worker + D1 + KV). Para
+VPS/Node:
+
+```bash
+npx create-nevex-agent coagua --mode node
+```
+
+El generador deja solo el modo elegido: borra los adapters, migraciones, tests y
+docs de deploy del otro (ADR-0005) y lo registra en `TEMPLATE.md`. Las
+dependencias del `pnpm-lock.yaml` se conservan completas para no romper
+`--frozen-lockfile`; el código que no corre ya no está.
+
 El CLI se publica en npm. El repositorio template que clona permanece privado
 y requiere acceso SSH a `nevex-labs/nevex-agent-template`.
 

package/bin/create-nevex-agent.mjs

@@ -15,6 +15,7 @@ import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 
 const args = parseArgs(process.argv.slice(2));
+
 const projectName = args._[0];
 
 if (!projectName || args.help) {
@@ -23,14 +24,22 @@ if (!projectName || args.help) {
 }
 
 const slug = normalizeSlug(projectName);
+
+const mode = normalizeMode(args.mode);
+
 const target = resolve(args.output ?? projectName);
+
 assertTargetIsSafe(target);
 
 const source = args["template-path"]
   ? resolve(args["template-path"])
-  : await materializeTemplate(args["template-repo"] ?? process.env.NEVEX_AGENT_TEMPLATE_REPO);
+  : await materializeTemplate(
+      args["template-repo"] ?? process.env.NEVEX_AGENT_TEMPLATE_REPO,
+      args["template-ref"],
+    );
 
 mkdirSync(target, { recursive: true });
+
 cpSync(source, target, {
   recursive: true,
   filter: (entry) => !shouldSkip(entry, source),
@@ -38,61 +47,253 @@ cpSync(source, target, {
 
 customizeProject(target, {
   slug,
+  mode,
   displayName: args["display-name"] ?? titleCase(slug),
+  templateRepo:
+    args["template-path"] ?? args["template-repo"] ?? process.env.NEVEX_AGENT_TEMPLATE_REPO ?? null,
+  templateRef: args["template-path"] ? null : (args["template-ref"] ?? null),
+  templateCommit: args["template-path"] ? null : readTemplateCommit(source),
 });
 
 if (!args["template-path"]) rmSync(source, { recursive: true, force: true });
 
 console.log(`\nProyecto creado en ${target}`);
+
 console.log("\nSiguientes pasos:\n");
+
 console.log(`  cd ${JSON.stringify(target)}`);
+
 console.log("  pnpm install");
+
 console.log("  cp .env.example .env.local");
+
 console.log("  pnpm dev\n");
 
-async function materializeTemplate(repository) {
+async function materializeTemplate(repository, ref) {
   const repo = repository ?? "git@github.com:nevex-labs/nevex-agent-template.git";
   const directory = join(tmpdir(), `nevex-agent-template-${randomUUID()}`);
-  execFileSync("git", ["clone", "--depth", "1", repo, directory], { stdio: "inherit" });
+  const refArgs = ref ? ["--branch", ref] : [];
+  execFileSync("git", ["clone", "--depth", "1", ...refArgs, repo, directory], {
+    stdio: "inherit",
+  });
+
   return directory;
 }
 
+function readTemplateCommit(directory) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: directory,
+      encoding: "utf8",
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
 function customizeProject(directory, values) {
+  applyMode(directory, values.mode);
+
   const packagePath = join(directory, "package.json");
   const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
   packageJson.name = values.slug;
   packageJson.private = true;
+  // The CLI smoke lives in the template only; installations must not keep
+  // a script pointing at the package the generator just excluded.
+  delete packageJson.scripts?.["test:cli"];
+
+  if (values.mode === "cloudflare") {
+    delete packageJson.scripts?.["build:node"];
+    delete packageJson.scripts?.start;
+  } else {
+    delete packageJson.scripts?.deploy;
+    delete packageJson.scripts?.["cf-typegen"];
+    packageJson.scripts.dev = "DEPLOY_TARGET=node dotenv -e .env.local -- vite dev";
+    packageJson.scripts.build = "DEPLOY_TARGET=node vite build";
+    packageJson.scripts.preview = "DEPLOY_TARGET=node vite preview";
+  }
+
   writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
 
+  replaceInFile(join(directory, ".github/workflows/ci.yml"), /^      - run: pnpm test:cli\n/m, "");
+
+  replaceInFile(join(directory, "pnpm-workspace.yaml"), /^\npackages:\n  - packages\/\*\n/m, "\n");
+
+  for (const file of ["README.md", "docs/workflow.md", "docs/README.md"]) {
+    stripTemplateOnly(join(directory, file));
+  }
+
   replaceInFile(
     join(directory, "src/lib/config.ts"),
-    /APP_NAME = "[^"]*"/,
-    `APP_NAME = ${JSON.stringify(values.displayName)}`,
-  );
-  replaceInFile(
-    join(directory, "wrangler.jsonc"),
-    /"name": "[^"]*"/,
-    `"name": ${JSON.stringify(values.slug)}`,
-  );
-  replaceInFile(
-    join(directory, "wrangler.jsonc"),
-    /"database_name": "[^"]*"/,
-    `"database_name": ${JSON.stringify(values.slug)}`,
+    /^export const APP_NAME = .*;$/m,
+    `export const APP_NAME = ${JSON.stringify(values.displayName)};`,
   );
+
+  if (values.mode === "cloudflare") {
+    replaceInFile(
+      join(directory, "wrangler.jsonc"),
+      /"name": "[^"]*"/,
+      `"name": ${JSON.stringify(values.slug)}`,
+    );
+    replaceInFile(
+      join(directory, "wrangler.jsonc"),
+      /"database_name": "[^"]*"/,
+      `"database_name": ${JSON.stringify(values.slug)}`,
+    );
+  }
+
   replaceInFile(
     join(directory, "README.md"),
     /^# Nevex Agent Template/m,
     `# ${values.displayName}`,
   );
+
+  replaceInFile(
+    join(directory, "AGENTS.md"),
+    /^This repo is a template\..*$/m,
+    "This repo is a Nevex agent installation: its own repo, database, secrets, and WhatsApp number.",
+  );
+
+  if (values.mode === "node") {
+    replaceInFile(
+      join(directory, "AGENTS.md"),
+      /## Cloudflare resources[\s\S]*$/m,
+      `## Node resources
+
+- **Host**: VPS or container, Node 22+.
+- **Postgres**: database owned by the installation.
+- **Redis**: claims and pauses with TTL.
+- **Cron triggers**: systemd timer or the host scheduler; Cloudflare \`scheduled\` does not exist in this mode.
+- **Backups**: owned by the host; document the policy once provisioned.
+`,
+    );
+  }
+
+  const lines = [
+    "# Template origin",
+    "",
+    `- Template: ${values.templateRepo ?? "git@github.com:nevex-labs/nevex-agent-template.git"}`,
+  ];
+
+  if (values.templateRef) lines.push(`- Ref: ${values.templateRef}`);
+
+  if (values.templateCommit) lines.push(`- Commit: ${values.templateCommit}`);
+  lines.push(
+    `- Mode: ${values.mode}`,
+    `- Infrastructure: ${heldInfrastructure(values.mode)}`,
+    `- Generated: ${new Date().toISOString().slice(0, 10)}`,
+    "",
+  );
+  writeFileSync(join(directory, "TEMPLATE.md"), `${lines.join("\n")}`);
+}
+
+function heldInfrastructure(mode) {
+  return mode === "cloudflare" ? "Cloudflare Worker + D1 + KV" : "Node + Postgres + Redis";
+}
+
+function normalizeMode(value) {
+  if (value === undefined) return "cloudflare";
+
+  if (value !== "cloudflare" && value !== "node") {
+    throw new Error(`Modo inválido: ${value}. Usá "cloudflare" o "node".`);
+  }
+
+  return value;
+}
+
+function modeDrop(mode) {
+  return {
+    cloudflare: [
+      "compose.yaml",
+      "docs/node-deploy.md",
+      "migrations/postgres",
+      "src/adapters/storage/postgres-conversations.ts",
+      "src/adapters/storage/postgres-conversations.test.ts",
+      "src/adapters/storage/postgres-conversations.integration.test.ts",
+      "src/adapters/storage/redis.ts",
+      "src/adapters/storage/redis.test.ts",
+      "src/infrastructure/migrations.postgres.test.ts",
+      "src/infrastructure/node",
+      "src/infrastructure/runtime.node.ts",
+      "src/infrastructure/runtime.node.test.ts",
+    ],
+    node: [
+      "docs/cloudflare-deploy.md",
+      "wrangler.jsonc",
+      "worker-configuration.d.ts",
+      "src/adapters/storage/cloudflare-kv.test.ts",
+      "src/adapters/storage/cloudflare-kv.ts",
+      "src/adapters/storage/d1.ts",
+      "src/adapters/storage/d1-conversations.test.ts",
+      "src/adapters/storage/d1-conversations.ts",
+      "src/infrastructure/cloudflare",
+      "src/infrastructure/migrations.d1.test.ts",
+      "src/infrastructure/runtime.resolution.test.ts",
+      "src/lib/env.test.ts",
+      "src/test/helpers/local-d1.ts",
+    ],
+  }[mode];
+}
+
+function applyMode(directory, mode) {
+  for (const relative of modeDrop(mode)) {
+    rmSync(join(directory, relative), { recursive: true, force: true });
+  }
+
+  if (mode !== "node") return;
+
+  for (const file of readdirSync(join(directory, "migrations"))) {
+    if (file.endsWith(".sql")) rmSync(join(directory, "migrations", file), { force: true });
+  }
+
+  writeFileSync(
+    join(directory, "src/infrastructure/runtime.ts"),
+    'export * from "./runtime.node";\n',
+  );
+  writeFileSync(
+    join(directory, "src/server.ts"),
+    `import handler from "@tanstack/react-start/server-entry";
+import { withSecurityHeaders } from "#/lib/security-headers";
+
+export default {
+  async fetch(request: Request) {
+    return withSecurityHeaders(request, await handler.fetch(request));
+  },
+};
+`,
+  );
 }
 
 function replaceInFile(path, pattern, replacement) {
   const content = readFileSync(path, "utf8");
+
+  if (!pattern.test(content)) {
+    throw new Error(`El patrón ${pattern} no matcheó en ${path}.`);
+  }
+
   writeFileSync(path, content.replace(pattern, replacement));
 }
 
+// Sections wrapped in template-only markers describe the generator itself.
+// They make no sense in an installation, so the generator cuts them out.
+function stripTemplateOnly(path) {
+  const content = readFileSync(path, "utf8");
+
+  const stripped = content.replace(
+    /<!-- template-only:start -->[\s\S]*?<!-- template-only:end -->\n?/g,
+    "",
+  );
+
+  if (stripped.includes("template-only:")) {
+    throw new Error(`Bloque template-only sin cerrar en ${path}.`);
+  }
+
+  writeFileSync(path, stripped);
+}
+
 function shouldSkip(entry, source) {
   const relative = entry.slice(source.length + 1);
+
   return (
     relative === ".git" ||
     relative.startsWith(".git/") ||
@@ -110,6 +311,7 @@ function shouldSkip(entry, source) {
 
 function assertTargetIsSafe(directory) {
   if (!existsSync(directory)) return;
+
   if (readdirSync(directory).length > 0) {
     throw new Error(`El directorio ${directory} ya existe y no está vacío.`);
   }
@@ -120,7 +322,9 @@ function normalizeSlug(value) {
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-|-$/g, "");
+
   if (!slug) throw new Error("El nombre del proyecto no es válido.");
+
   return slug;
 }
 
@@ -130,12 +334,15 @@ function titleCase(value) {
 
 function parseArgs(argv) {
   const result = { _: [] };
+
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
+
     if (value === "--help" || value === "-h") result.help = true;
     else if (value.startsWith("--")) result[value.slice(2)] = argv[++index];
     else result._.push(value);
   }
+
   return result;
 }
 
@@ -144,8 +351,10 @@ function printHelp() {
 
 Opciones:
   --display-name <nombre>   Nombre visible del agente
+  --mode <cloudflare|node>  Infraestructura de la instalación (default: cloudflare)
   --output <directorio>     Directorio de destino
   --template-path <path>    Usar un template local, útil para desarrollo
   --template-repo <repo>    URL o ruta del repositorio template
+  --template-ref <ref>      Rama o tag del template (default: rama por defecto)
   -h, --help                Mostrar esta ayuda`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevex-agent",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Create a custom Nevex WhatsApp agent project",
   "bin": {
     "create-nevex-agent": "bin/create-nevex-agent.mjs"