create-fetch-agent 0.1.0

package/src/scaffold.js

@@ -0,0 +1,316 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "fs-extra";
+
+import {
+  workerPorts,
+  renderWorker,
+  renderConfig,
+  renderChatProtocol,
+  renderOrchestratorAgent,
+  renderMakefile,
+  renderEnv,
+  renderSingleAgent,
+  renderSingleEnv,
+  renderSingleMakefile,
+  SINGLE_AGENT_PORT,
+  ORCHESTRATOR_PORT,
+} from "./workers.js";
+import { renderPyproject } from "./env.js";
+import { seed } from "./seeds.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const PACKAGE_ROOT = path.resolve(__dirname, "..");
+export const TEMPLATES_DIR = path.join(PACKAGE_ROOT, "templates");
+
+/** Build types that share the single-agent base. */
+const SINGLE_BASE_TYPES = new Set(["single_agent", "chat_agent", "payment_agent"]);
+
+/**
+ * Turn a project name into a python-identifier-safe agent name.
+ */
+export function toAgentName(raw) {
+  const cleaned = String(raw)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/^([0-9])/, "agent_$1");
+  return cleaned || "agent";
+}
+
+async function writeFile(targetDir, relPath, contents, written) {
+  const dest = path.join(targetDir, relPath);
+  await fs.ensureDir(path.dirname(dest));
+  await fs.writeFile(dest, contents, "utf8");
+  written.push(relPath);
+}
+
+async function copyFile(srcAbs, targetDir, relPath, written) {
+  const dest = path.join(targetDir, relPath);
+  await fs.ensureDir(path.dirname(dest));
+  await fs.copy(srcAbs, dest);
+  written.push(relPath);
+}
+
+/**
+ * Scaffold a project from a wizard answers object.
+ *
+ * @param {object} answers
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] directory the project dir is created under
+ * @param {() => string} [opts.seedFn] injectable seed generator (tests)
+ * @returns {Promise<{targetDir: string, written: string[], buildType: string}>}
+ */
+export async function scaffold(answers, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const seedFn = opts.seedFn || seed;
+  const targetDir = path.resolve(cwd, answers.projectName);
+  await fs.ensureDir(targetDir);
+
+  const written = [];
+
+  if (answers.buildType === "orchestrator_workers") {
+    await scaffoldOrchestratorWorkers(answers, { targetDir, seedFn, written });
+  } else if (SINGLE_BASE_TYPES.has(answers.buildType)) {
+    await scaffoldSingleAgent(answers, { targetDir, seedFn, written });
+  } else {
+    throw new Error(`Unknown build type: ${answers.buildType}`);
+  }
+
+  written.sort();
+  return { targetDir, written, buildType: answers.buildType };
+}
+
+async function scaffoldOrchestratorWorkers(answers, ctx) {
+  const { targetDir, seedFn, written } = ctx;
+  const names = answers.workers;
+  const ports = workerPorts(names.length);
+  const staticDir = path.join(TEMPLATES_DIR, "orchestrator-workers");
+
+  // Static, copied verbatim.
+  await copyFile(path.join(staticDir, "agents/__init__.py"), targetDir, "agents/__init__.py", written);
+  await copyFile(path.join(staticDir, "agents/models/__init__.py"), targetDir, "agents/models/__init__.py", written);
+  await copyFile(path.join(staticDir, "agents/models/models.py"), targetDir, "agents/models/models.py", written);
+  await copyFile(path.join(staticDir, "agents/services/__init__.py"), targetDir, "agents/services/__init__.py", written);
+  await copyFile(path.join(staticDir, "agents/services/state_service.py"), targetDir, "agents/services/state_service.py", written);
+  await copyFile(path.join(staticDir, "agents/orchestrator/__init__.py"), targetDir, "agents/orchestrator/__init__.py", written);
+  await copyFile(path.join(staticDir, "requirements.txt"), targetDir, "requirements.txt", written);
+  await copyFile(path.join(TEMPLATES_DIR, "gitignore"), targetDir, ".gitignore", written);
+
+  // Generated (name/count-driven).
+  await writeFile(targetDir, "agents/models/config.py", renderConfig(names), written);
+  await writeFile(targetDir, "agents/orchestrator/orchestrator_agent.py", renderOrchestratorAgent(), written);
+  await writeFile(targetDir, "agents/orchestrator/chat_protocol.py", renderChatProtocol(names), written);
+
+  for (let i = 0; i < names.length; i += 1) {
+    const name = names[i];
+    const port = ports[i];
+    await writeFile(targetDir, `agents/${name}/__init__.py`, "", written);
+    await writeFile(targetDir, `agents/${name}/${name}_agent.py`, renderWorker(name, port), written);
+  }
+
+  await writeFile(targetDir, ".env", renderEnv(names, seedFn), written);
+  await writeFile(targetDir, ".env.example", renderEnvExample(names), written);
+  await writeFile(targetDir, "Makefile", renderMakefile(names), written);
+
+  if (answers.pythonManager === "poetry") {
+    const reqs = await fs.readFile(path.join(staticDir, "requirements.txt"), "utf8");
+    await writeFile(targetDir, "pyproject.toml", renderPyproject(answers.projectName, reqs), written);
+  }
+
+  await writeFile(targetDir, "README.md", renderOrchestratorReadme(answers, names, ports), written);
+}
+
+async function scaffoldSingleAgent(answers, ctx) {
+  const { targetDir, seedFn, written } = ctx;
+  const name = toAgentName(answers.projectName);
+  const staticDir = path.join(TEMPLATES_DIR, "single-agent");
+
+  await copyFile(path.join(staticDir, "requirements.txt"), targetDir, "requirements.txt", written);
+  await copyFile(path.join(TEMPLATES_DIR, "gitignore"), targetDir, ".gitignore", written);
+
+  await writeFile(targetDir, "agent.py", renderSingleAgent(name, SINGLE_AGENT_PORT), written);
+  await writeFile(targetDir, ".env", renderSingleEnv(seedFn), written);
+  await writeFile(targetDir, ".env.example", "AGENT_SEED_PHRASE=\n", written);
+  await writeFile(targetDir, "Makefile", renderSingleMakefile(), written);
+
+  if (answers.pythonManager === "poetry") {
+    const reqs = await fs.readFile(path.join(staticDir, "requirements.txt"), "utf8");
+    await writeFile(targetDir, "pyproject.toml", renderPyproject(answers.projectName, reqs), written);
+  }
+
+  await writeFile(targetDir, "README.md", renderSingleReadme(answers, name), written);
+}
+
+function renderEnvExample(names) {
+  return [
+    "# Set a unique, random seed phrase per agent (no spaces).",
+    "# `create-fetch-agent` pre-fills these in .env for you.",
+    "",
+    "ORCHESTRATOR_SEED_PHRASE=",
+    ...names.map((n) => `${n.toUpperCase()}_SEED_PHRASE=`),
+    "",
+  ].join("\n");
+}
+
+function runHints(pythonManager) {
+  if (pythonManager === "uv") {
+    return {
+      install: ["uv venv", "uv pip install -r requirements.txt"],
+      prefix: "uv run",
+    };
+  }
+  if (pythonManager === "poetry") {
+    return {
+      install: ["poetry install"],
+      prefix: "poetry run",
+    };
+  }
+  return {
+    install: ["python3.12 -m venv .venv", "source .venv/bin/activate", "pip install -r requirements.txt"],
+    prefix: "",
+  };
+}
+
+function renderOrchestratorReadme(answers, names, ports) {
+  const hints = runHints(answers.pythonManager);
+  const installBlock = hints.install.map((c) => c).join("\n");
+  const mk = (target) => (hints.prefix ? `${hints.prefix} make ${target}` : `make ${target}`);
+  const workerRows = names
+    .map((n, i) => `| ${n} | ${ports[i]} | \`agents/${n}/${n}_agent.py\` | \`${mk(n)}\` |`)
+    .join("\n");
+
+  return `# ${answers.projectName}
+
+A Fetch.ai multi-agent system: an **orchestrator** (the sole ASI:One bridge) that
+routes incoming chat messages to specialized **worker** agents. Generated with
+[create-fetch-agent](https://github.com/anishkancherla-fetchai/create-fetch-agent).
+
+## Architecture
+
+\`\`\`
+ASI:One / Agentverse
+        │  (chat protocol)
+        ▼
+  orchestrator  (port ${ORCHESTRATOR_PORT})  ──►  routes SharedAgentState by name
+        ▲                                   │
+        └──────── result ◄──────────────────┘
+                                            ▼
+                              ${names.join(", ")}
+\`\`\`
+
+All agents share one message contract (\`SharedAgentState\` in
+\`agents/models/models.py\`). The orchestrator owns the chat protocol and relays
+the worker's \`result\` back to the user. State persists per session via
+\`InMemoryStateService\` (swap it for Redis/Postgres without touching the pipeline).
+Addresses are derived from seeds in \`agents/models/config.py\`, so there are no
+hardcoded addresses.
+
+## Agents
+
+| Agent | Port | File | Run |
+| ----- | ---- | ---- | --- |
+| orchestrator | ${ORCHESTRATOR_PORT} | \`agents/orchestrator/orchestrator_agent.py\` | \`${mk("orchestrator")}\` |
+${workerRows}
+
+## Setup
+
+Seeds are already generated for you in \`.env\`. Install dependencies:
+
+\`\`\`bash
+${installBlock}
+\`\`\`
+
+## Run
+
+Each agent runs in its own terminal. Start the orchestrator first:
+
+\`\`\`bash
+${mk("orchestrator")}
+\`\`\`
+
+${names.map((n) => `\`\`\`bash\n${mk(n)}\n\`\`\``).join("\n\n")}
+
+## Where to add your logic
+
+Each worker has a \`<name>_workflow(state)\` function — the single extension point.
+Read \`state.query\`, do the work, write \`state.result\`. For example, in
+\`agents/${names[0]}/${names[0]}_agent.py\`:
+
+\`\`\`python
+def ${names[0]}_workflow(state: SharedAgentState) -> SharedAgentState:
+    state.result = my_llm_or_rag_call(state.query)
+    return state
+\`\`\`
+
+## Talk to it on ASI:One
+
+The agents set \`mailbox=True\` and \`publish_agent_details=True\`, so you can
+connect them through the Agentverse inspector and chat via ASI:One. See
+"Register on Agentverse" output from the scaffolder, or the
+[Agentverse docs](https://agentverse.ai). The inspector URL is logged on startup.
+
+## REST hooks (custom frontend)
+
+The orchestrator exposes \`/health\` and \`/message\` on port ${ORCHESTRATOR_PORT}:
+
+\`\`\`bash
+curl http://localhost:${ORCHESTRATOR_PORT}/health
+curl -X POST http://localhost:${ORCHESTRATOR_PORT}/message -H "Content-Type: application/json" -d '{"content":"hi"}'
+\`\`\`
+`;
+}
+
+function renderSingleReadme(answers, name) {
+  const hints = runHints(answers.pythonManager);
+  const installBlock = hints.install.join("\n");
+  const runCmd = hints.prefix ? `${hints.prefix} make run` : "make run";
+  const typeLabel =
+    answers.buildType === "chat_agent"
+      ? "chat agent (ASI:One ready)"
+      : answers.buildType === "payment_agent"
+        ? "payment agent base"
+        : "single agent";
+
+  return `# ${answers.projectName}
+
+A Fetch.ai ${typeLabel} built on the uAgents framework. It speaks the chat
+protocol, so it's ASI:One ready out of the box. Generated with
+[create-fetch-agent](https://github.com/anishkancherla-fetchai/create-fetch-agent).
+
+## Setup
+
+The agent's seed is already generated in \`.env\`. Install dependencies:
+
+\`\`\`bash
+${installBlock}
+\`\`\`
+
+## Run
+
+\`\`\`bash
+${runCmd}
+\`\`\`
+
+The agent starts on port ${SINGLE_AGENT_PORT} and logs its address and an
+Agentverse inspector URL.
+
+## Where to add your logic
+
+\`agent.py\` has an \`agent_workflow(query)\` function — the single extension point.
+Return the response string for a given user query:
+
+\`\`\`python
+def agent_workflow(query: str) -> str:
+    return my_llm_call(query)
+\`\`\`
+
+## Talk to it on ASI:One
+
+\`mailbox=True\` and \`publish_agent_details=True\` are set, so connect \`${name}\`
+through the Agentverse inspector and chat with it via ASI:One. The inspector URL
+is logged on startup.
+`;
+}

package/src/seeds.js

@@ -0,0 +1,12 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Generate a unique, high-entropy seed for an agent.
+ *
+ * Each uAgent derives its on-network identity (and therefore its address) from
+ * its seed via `Identity.from_seed`. Generating these for the user means the
+ * scaffolded project runs immediately — nobody has to invent seed phrases.
+ *
+ * @returns {string} a 32-char hex string (16 random bytes)
+ */
+export const seed = () => randomBytes(16).toString("hex");

package/src/skills.js

@@ -0,0 +1,115 @@
+import {
+  getAvailableSkills,
+  partitionSkills,
+  installSkillToCopyTarget,
+  installAgentsMd,
+  createSummary,
+} from "fetch-skills/bin/install.js";
+
+const PACKAGE_SKILL_BY_MANAGER = {
+  uv: "uv-package",
+  poetry: "poetry-package",
+  pip: "python-venv-package",
+};
+
+const COPY_TARGET_DIRS = {
+  cursor: ".cursor/skills",
+  claude: ".claude/skills",
+  antigravity: ".agent/skills",
+};
+
+// Auto-confirm stub: a freshly scaffolded project has no pre-existing skill
+// files, but this guarantees we never block on a prompt in non-interactive runs.
+const autoPrompts = { confirm: async () => true };
+
+/**
+ * Resolve the fetch-skills skill names implied by the wizard answers.
+ *
+ * @returns {string[]} skill names (package skill first, then protocol skills)
+ */
+export function selectedSkillNames(answers) {
+  const names = [];
+  const pkg = PACKAGE_SKILL_BY_MANAGER[answers.pythonManager];
+  if (pkg) names.push(pkg);
+
+  if (answers.buildType === "chat_agent" || answers.buildType === "orchestrator_workers") {
+    names.push("chat-protocol");
+  } else if (answers.buildType === "payment_agent") {
+    names.push("payment-protocol", "fet-payment-protocol", "stripe-payment-protocol");
+  }
+
+  return names;
+}
+
+/**
+ * Compute the paths fetch-skills will write for the chosen targets + skills,
+ * so the CLI's final summary shows the real locations (NOT .cursor/rules/).
+ */
+export function expectedSkillPaths(answers) {
+  const skillNames = selectedSkillNames(answers);
+  const paths = [];
+  for (const target of answers.aiTargets || []) {
+    if (target === "agents") {
+      paths.push("AGENTS.md");
+    } else if (COPY_TARGET_DIRS[target]) {
+      for (const name of skillNames) {
+        paths.push(`${COPY_TARGET_DIRS[target]}/${name}/SKILL.md`);
+      }
+    }
+  }
+  return paths;
+}
+
+/**
+ * Install the selected fetch-skills context into the generated project.
+ *
+ * Calls the fetch-skills install functions directly with the pre-collected
+ * answers (no re-prompting, no shelling out to `npx fetch-skills`).
+ *
+ * @returns {Promise<{summary: object, paths: string[]}>}
+ */
+export async function installSkills(answers, { targetRoot, logger = console } = {}) {
+  const targets = answers.aiTargets || [];
+  const summary = createSummary();
+
+  if (targets.length === 0 || (targets.length === 1 && targets[0] === "none")) {
+    return { summary, paths: [] };
+  }
+
+  const wantedNames = new Set(selectedSkillNames(answers));
+  const available = await getAvailableSkills();
+  const skills = available.filter((s) => wantedNames.has(s.name));
+
+  // Keep partition import meaningful (and surface package vs protocol if needed).
+  partitionSkills(skills);
+
+  if (skills.length === 0) {
+    return { summary, paths: [] };
+  }
+
+  for (const target of targets) {
+    if (target === "none") continue;
+    if (target === "agents") {
+      await installAgentsMd({
+        skills,
+        targetRoot,
+        summary,
+        prompts: autoPrompts,
+        logger,
+      });
+    } else if (COPY_TARGET_DIRS[target]) {
+      for (const skill of skills) {
+        await installSkillToCopyTarget({
+          target,
+          skill,
+          targetRoot,
+          summary,
+          prompts: autoPrompts,
+          logger,
+        });
+      }
+    }
+  }
+
+  return { summary, paths: expectedSkillPaths(answers) };
+}

package/src/wizard.js

@@ -0,0 +1,155 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { input, select, checkbox, confirm, number } from "@inquirer/prompts";
+
+export const defaultPrompts = { input, select, checkbox, confirm, number };
+
+const DEFAULT_WORKER_NAMES = ["alice", "bob", "carol", "dave", "erin", "frank"];
+
+/**
+ * Validate a project name: no spaces, and not pointing at an existing non-empty
+ * directory. Returns true or an error string (inquirer validate convention).
+ */
+export function validateProjectName(name, cwd = process.cwd()) {
+  if (!name || !name.trim()) return "Project name is required.";
+  if (/\s/.test(name)) return "Project name cannot contain spaces.";
+  if (name === "." || name === "..") return "Pick a real directory name.";
+  if (/[/\\]/.test(name)) return "Project name cannot contain path separators.";
+  const target = path.resolve(cwd, name);
+  if (fs.existsSync(target)) {
+    const entries = fs.readdirSync(target);
+    if (entries.length > 0) return `Directory "${name}" already exists and is not empty.`;
+  }
+  return true;
+}
+
+/**
+ * Normalize a worker name to a python-identifier-safe token.
+ */
+export function normalizeWorkerName(raw) {
+  return String(raw)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/^([0-9])/, "w_$1");
+}
+
+/**
+ * Run the interactive wizard. All I/O is injectable so it can run headlessly
+ * in tests (pass a `prompts` object whose methods return canned answers).
+ *
+ * @returns {Promise<object>} the answers object consumed by scaffold/skills/env
+ */
+export async function runWizard({
+  argv = [],
+  prompts = defaultPrompts,
+  logger = console,
+  cwd = process.cwd(),
+} = {}) {
+  let projectName = argv[0];
+  if (projectName) {
+    const valid = validateProjectName(projectName, cwd);
+    if (valid !== true) {
+      logger.log(valid);
+      projectName = undefined;
+    }
+  }
+  if (!projectName) {
+    projectName = await prompts.input({
+      message: "Project name:",
+      default: "my-fetch-agent",
+      validate: (v) => validateProjectName(v, cwd),
+    });
+  }
+
+  const buildType = await prompts.select({
+    message: "What are you building?",
+    choices: [
+      { name: "Single agent", value: "single_agent" },
+      { name: "Chat agent (ASI:One ready)", value: "chat_agent" },
+      { name: "Orchestrator + workers", value: "orchestrator_workers" },
+      { name: "Payment agent (FET + Stripe)", value: "payment_agent" },
+    ],
+  });
+
+  let workers = [];
+  if (buildType === "orchestrator_workers") {
+    const count = await prompts.number({
+      message: "How many worker agents?",
+      default: 2,
+      min: 1,
+      max: 10,
+    });
+    const n = Number(count) || 2;
+    const taken = new Set(["orchestrator"]);
+    for (let i = 0; i < n; i += 1) {
+      const fallback = DEFAULT_WORKER_NAMES[i] || `worker${i + 1}`;
+      // Find a default that isn't already taken.
+      let def = fallback;
+      let bump = i;
+      while (taken.has(def)) {
+        bump += 1;
+        def = DEFAULT_WORKER_NAMES[bump] || `worker${bump + 1}`;
+      }
+      const raw = await prompts.input({
+        message: `Worker ${i + 1} name:`,
+        default: def,
+        validate: (v) => {
+          const norm = normalizeWorkerName(v);
+          if (!norm) return "Enter a valid name (letters/numbers).";
+          if (norm === "orchestrator") return '"orchestrator" is reserved.';
+          if (taken.has(norm)) return `"${norm}" is already used.`;
+          return true;
+        },
+      });
+      const norm = normalizeWorkerName(raw);
+      taken.add(norm);
+      workers.push(norm);
+    }
+  }
+
+  const pythonManager = await prompts.select({
+    message: "Python setup:",
+    choices: [
+      { name: "uv (fast, recommended)", value: "uv" },
+      { name: "poetry", value: "poetry" },
+      { name: "pip + venv", value: "pip" },
+    ],
+    default: "uv",
+  });
+
+  const aiTargets = await prompts.checkbox({
+    message: "Add AI-editor context? (Space to select, Enter to confirm; none = skip)",
+    choices: [
+      { name: "Cursor", value: "cursor" },
+      { name: "Claude Code", value: "claude" },
+      { name: "Antigravity", value: "antigravity" },
+      { name: "AGENTS.md", value: "agents" },
+    ],
+    required: false,
+  });
+
+  const registerNow = await prompts.select({
+    message: "Register on Agentverse now?",
+    choices: [
+      { name: "Later (just show me the steps)", value: false },
+      { name: "Yes, show me now", value: true },
+    ],
+    default: false,
+  });
+
+  const installNow = await prompts.confirm({
+    message: "Install Python dependencies now?",
+    default: true,
+  });
+
+  return {
+    projectName,
+    buildType,
+    workers,
+    pythonManager,
+    aiTargets: aiTargets || [],
+    registerNow,
+    installNow,
+  };
+}