create-fetch-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anishkancherla-fetchai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# create-fetch-agent
+
+Scaffold a **runnable Fetch.ai [uAgents](https://uagents.fetch.ai) project** with
+one command, then layer in context for your AI coding tool.
+
+```bash
+npx create-fetch-agent my-app
+# or
+npm create fetch-agent@latest my-app
+```
+
+The generated project runs immediately — seeds are pre-filled, addresses are
+derived from them, ports are assigned, and a `Makefile` starts every agent. The
+only things left as `TODO` are the workflow functions where *your* logic goes.
+
+---
+
+## What you get
+
+An interactive wizard asks a few questions and then:
+
+1. **Generates a runnable uAgents project** (single agent, or an orchestrator +
+   workers system).
+2. **Pre-generates unique seeds** for every agent and wires up addresses + ports.
+3. **Installs AI-editor context** (optional) so Cursor / Claude Code / Antigravity
+   / `AGENTS.md` know how to extend the project correctly.
+4. **Bootstraps the Python environment** (optional) with `uv`, `poetry`, or `pip`.
+5. **Prints honest Agentverse guidance** for connecting your agents to ASI:One.
+
+---
+
+## Wizard options
+
+| Prompt | Choices |
+| --- | --- |
+| **Project name** | directory created under the current folder (or pass it as an argument) |
+| **What are you building?** | `Single agent` · `Chat agent (ASI:One ready)` · `Orchestrator + workers` · `Payment agent (FET + Stripe)` |
+| **Worker count & names** | only for orchestrator + workers (defaults `alice`, `bob`) |
+| **Python setup** | `uv` (default) · `poetry` · `pip + venv` |
+| **AI-editor context** | any of `Cursor` · `Claude Code` · `Antigravity` · `AGENTS.md` (or none) |
+| **Register on Agentverse** | `Later` · `Yes` (prints inspector steps) |
+| **Install dependencies now?** | yes / no |
+
+> **v1 scope:** `Single agent` and `Orchestrator + workers` are fully implemented.
+> `Chat agent` builds on the single-agent base (already chat/ASI:One ready) plus
+> the `chat-protocol` skill. `Payment agent` builds the single-agent base plus the
+> payment skills as context — the full payment code path is documented future
+> work, not half-built code.
+
+---
+
+## The two project shapes
+
+### Single agent (`Single agent` / `Chat agent`)
+
+A flat, self-contained, chat-enabled agent that's ASI:One ready out of the box:
+
+```
+my-app/
+  agent.py          # speaks the chat protocol; agent_workflow(query) is your hook
+  .env              # AGENT_SEED_PHRASE (pre-generated)
+  requirements.txt
+  Makefile          # make run
+  README.md
+```
+
+### Orchestrator + workers (`Orchestrator + workers`)
+
+A hub-and-spoke system around one shared message contract. The **orchestrator** is
+the sole ASI:One bridge: it owns the chat protocol, routes each message to a worker
+by name, and relays the worker's result back to the user. **Workers** run a
+`<name>_workflow(state)` and send the state back.
+
+```
+my-app/
+  agents/
+    models/
+      models.py       # SharedAgentState (the message contract)
+      config.py       # <NAME>_SEED + <NAME>_ADDRESS per agent (no hardcoded addresses)
+    services/
+      state_service.py  # InMemoryStateService (swap for Redis/Postgres)
+    orchestrator/
+      orchestrator_agent.py  # chat bridge + /health + /message REST stubs
+      chat_protocol.py       # routing branches, one per worker
+    <worker>/
+      <worker>_agent.py      # <worker>_workflow(state) — your extension point
+  .env                # one <NAME>_SEED_PHRASE per agent (pre-generated)
+  Makefile            # make orchestrator + make <worker>
+  requirements.txt
+  README.md
+```
+
+Ports are deterministic: the orchestrator owns `8003`; workers fill
+`8001, 8002, 8004, 8005, …` (skipping `8003`).
+
+---
+
+## The three-layer model
+
+`create-fetch-agent` deliberately separates three concerns:
+
+1. **`create-fetch-agent` (this tool)** — owns project structure, runnable starter
+   code, seed generation, dependency install, and Agentverse guidance.
+2. **The [`fetch-help`](https://github.com/harvest7777/fetch-help) template** — the
+   canonical orchestrator + workers architecture this tool stamps out and
+   parameterizes (names, counts, ports, seeds).
+3. **[`fetch-skills`](https://www.npmjs.com/package/fetch-skills)** — a context
+   installer that writes `SKILL.md` instruction files for AI coding tools. It
+   writes *no code*; this tool delegates the "AI-editor context" step to it
+   instead of reinventing thousands of lines of skill markdown.
+
+**Design philosophy — hybrid:** emit a *minimal runnable skeleton* (works on the
+first run with no AI tool) whose extension points are pre-marked, then install
+fetch-skills context so your AI tool can flesh those points out correctly.
+
+### Where AI-editor context lands
+
+| Tool | Path |
+| --- | --- |
+| Cursor | `.cursor/skills/<skill>/SKILL.md` |
+| Claude Code | `.claude/skills/<skill>/SKILL.md` |
+| Antigravity | `.agent/skills/<skill>/SKILL.md` |
+| AGENTS.md | `AGENTS.md` (skills concatenated) |
+
+---
+
+## Talking to your agents (Agentverse / ASI:One)
+
+Every generated agent sets `mailbox=True` and `publish_agent_details=True`, so
+"registration" is the browser inspector + mailbox connect flow. Each agent logs
+its exact inspector URL on startup. The CLI prints the step-by-step flow; for the
+orchestrator system you only chat with the orchestrator — it routes to the workers.
+
+Programmatic registration (`AGENTVERSE_API_KEY`) is documented future work, not v1.
+
+---
+
+## Development
+
+```bash
+npm install
+npm test                 # fast unit + integration tests
+CFA_PACK=1 npm test      # also verify the published file set via `npm pack`
+CFA_SMOKE=1 npm test     # also boot a generated orchestrator and curl /health (needs Python)
+```
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import chalk from "chalk";
+
+import { runWizard } from "../src/wizard.js";
+import { scaffold } from "../src/scaffold.js";
+import { installSkills } from "../src/skills.js";
+import { bootstrap, manualInstallCommands } from "../src/env.js";
+import { printAgentverseGuidance } from "../src/agentverse.js";
+
+function parseArgs(argv) {
+  return argv.filter((a) => !a.startsWith("-"));
+}
+
+function runPrefix(pythonManager) {
+  if (pythonManager === "uv") return "uv run ";
+  if (pythonManager === "poetry") return "poetry run ";
+  return "";
+}
+
+function printBanner(logger) {
+  logger.log("");
+  logger.log(chalk.bold.hex("#1A6FE8")("  create-fetch-agent"));
+  logger.log(chalk.dim("  Scaffold a runnable Fetch.ai uAgents project."));
+  logger.log("");
+}
+
+function printNextSteps(logger, { answers, targetDir, skillPaths }) {
+  const rel = path.relative(process.cwd(), targetDir) || ".";
+  const prefix = runPrefix(answers.pythonManager);
+
+  logger.log("");
+  logger.log(chalk.bold.green("✔ Project ready: ") + chalk.cyan(rel));
+  logger.log("");
+  logger.log(chalk.bold("Next steps:"));
+  logger.log(`  ${chalk.cyan(`cd ${rel}`)}`);
+
+  if (!answers.installNow) {
+    for (const c of manualInstallCommands(answers.pythonManager)) {
+      logger.log(`  ${chalk.cyan(c)}`);
+    }
+  }
+
+  logger.log("");
+  if (answers.buildType === "orchestrator_workers") {
+    logger.log(chalk.dim("  Start each agent in its own terminal (orchestrator first):"));
+    logger.log(`  ${chalk.cyan(`${prefix}make orchestrator`)}`);
+    for (const n of answers.workers) {
+      logger.log(`  ${chalk.cyan(`${prefix}make ${n}`)}`);
+    }
+  } else {
+    logger.log(`  ${chalk.cyan(`${prefix}make run`)}`);
+  }
+
+  if (skillPaths && skillPaths.length) {
+    logger.log("");
+    logger.log(chalk.bold("AI-editor context ") + chalk.dim("(via fetch-skills)") + chalk.bold(" installed at:"));
+    for (const p of skillPaths) logger.log(`  ${chalk.cyan(p)}`);
+  }
+
+  logger.log("");
+}
+
+async function main() {
+  const logger = console;
+  printBanner(logger);
+
+  const positionals = parseArgs(process.argv.slice(2));
+  const answers = await runWizard({ argv: positionals, logger });
+
+  const { targetDir } = await scaffold(answers);
+  logger.log(chalk.green(`\n✔ Generated project files in ${path.basename(targetDir)}/`));
+
+  let skillPaths = [];
+  if (answers.aiTargets && answers.aiTargets.length) {
+    logger.log(chalk.bold("\n◆  Installing AI-editor context ") + chalk.dim("(via fetch-skills)"));
+    logger.log(chalk.dim("─".repeat(40)));
+    const { paths } = await installSkills(answers, { targetRoot: targetDir, logger });
+    skillPaths = paths;
+  }
+
+  if (answers.installNow) {
+    logger.log(chalk.bold("\n◆  Installing dependencies"));
+    logger.log(chalk.dim("─".repeat(40)));
+    await bootstrap(answers, { cwd: targetDir, logger });
+  }
+
+  printAgentverseGuidance(answers, { logger });
+  printNextSteps(logger, { answers, targetDir, skillPaths });
+}
+
+main().catch((err) => {
+  if (err && (err.name === "ExitPromptError" || err.name === "AbortPromptError")) {
+    console.log("");
+    console.log(chalk.dim("Aborted."));
+    process.exit(130);
+  }
+  console.error("");
+  console.error(chalk.red(`create-fetch-agent failed: ${err && err.message ? err.message : err}`));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "create-fetch-agent",
+  "version": "0.1.0",
+  "description": "Scaffold runnable Fetch.ai uAgent projects with one command, then layer in AI-coding-tool context.",
+  "type": "module",
+  "bin": {
+    "create-fetch-agent": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "fetch.ai",
+    "fetchai",
+    "uagents",
+    "agents",
+    "ai-agents",
+    "asi",
+    "asi-one",
+    "scaffold",
+    "create",
+    "generator",
+    "cli"
+  ],
+  "author": "Fetch.ai",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
+    "chalk": "^5.3.0",
+    "execa": "^9.5.0",
+    "fetch-skills": "2.0.3",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anishkancherla-fetchai/create-fetch-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/anishkancherla-fetchai/create-fetch-agent/issues"
+  },
+  "homepage": "https://github.com/anishkancherla-fetchai/create-fetch-agent#readme"
+}

package/src/agentverse.js

@@ -0,0 +1,63 @@
+import chalk from "chalk";
+
+/**
+ * Print honest Agentverse registration guidance.
+ *
+ * There is no programmatic registration in v1. The generated agents already set
+ * mailbox=True and publish_agent_details=True, so "registration" is the browser
+ * inspector + mailbox connect flow. Each agent logs its exact inspector URL on
+ * startup; we print the steps and the URL pattern here.
+ */
+export function printAgentverseGuidance(answers, { logger = console } = {}) {
+  const isOrchestrator = answers.buildType === "orchestrator_workers";
+  const now = answers.registerNow;
+
+  logger.log("");
+  logger.log(chalk.bold.cyan("◆  Register on Agentverse"));
+  logger.log(chalk.dim("─".repeat(40)));
+
+  if (now) {
+    logger.log("Let's connect your agent(s) to Agentverse now.");
+  } else {
+    logger.log("When you're ready to connect your agent(s) to Agentverse:");
+  }
+  logger.log("");
+
+  const steps = [
+    "Sign in at https://agentverse.ai (and https://asi1.ai to chat via ASI:One).",
+    "Start your agent(s) — each logs its Agentverse inspector URL on startup.",
+    isOrchestrator
+      ? "Open EACH agent's inspector URL in the browser (one per agent)."
+      : "Open the inspector URL in the browser.",
+    'Click "Connect", then choose "Mailbox".',
+    isOrchestrator
+      ? 'On the ORCHESTRATOR inspector, click "Go to Agent Profile" → "Chat with Agent".'
+      : 'Click "Go to Agent Profile" → "Chat with Agent".',
+  ];
+
+  steps.forEach((s, i) => logger.log(`  ${chalk.cyan(`${i + 1}.`)} ${s}`));
+
+  logger.log("");
+  logger.log(chalk.dim("  Inspector URL pattern (the agent logs the exact one):"));
+  logger.log(
+    chalk.dim(
+      "  https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A<PORT>&address=<AGENT_ADDRESS>",
+    ),
+  );
+
+  if (isOrchestrator) {
+    logger.log("");
+    logger.log(
+      chalk.dim(
+        "  Tip: only the orchestrator needs ASI:One chat — it routes to the workers.",
+      ),
+    );
+  }
+
+  logger.log("");
+  logger.log(
+    chalk.dim(
+      "  Programmatic registration (AGENTVERSE_API_KEY) is documented future work, not v1.",
+    ),
+  );
+}

package/src/env.js

@@ -0,0 +1,158 @@
+import { execa } from "execa";
+import ora from "ora";
+import chalk from "chalk";
+
+/**
+ * Convert a pinned requirements.txt into a Poetry pyproject.toml.
+ *
+ * @param {string} projectName
+ * @param {string} requirementsText contents of requirements.txt
+ * @returns {string} pyproject.toml contents
+ */
+export function renderPyproject(projectName, requirementsText) {
+  const pkgName = String(projectName)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "fetch-agent";
+
+  const deps = [];
+  for (const rawLine of requirementsText.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^([A-Za-z0-9._-]+)\s*==\s*(.+)$/);
+    if (m) {
+      deps.push(`${m[1]} = "${m[2]}"`);
+    } else {
+      const name = line.split(/[<>=!~ ]/)[0];
+      if (name) deps.push(`${name} = "*"`);
+    }
+  }
+
+  return `[tool.poetry]
+name = "${pkgName}"
+version = "0.1.0"
+description = "A Fetch.ai uAgents project."
+authors = []
+package-mode = false
+
+[tool.poetry.dependencies]
+python = "^3.12"
+${deps.join("\n")}
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+`;
+}
+
+/**
+ * Manual commands to print when an automated install can't run.
+ */
+export function manualInstallCommands(pythonManager) {
+  switch (pythonManager) {
+    case "uv":
+      return ["uv venv", "uv pip install -r requirements.txt"];
+    case "poetry":
+      return ["poetry install"];
+    default:
+      return [
+        "python3.12 -m venv .venv",
+        "source .venv/bin/activate",
+        "pip install -r requirements.txt",
+      ];
+  }
+}
+
+async function runStep({ label, cmd, args, cwd, logger }) {
+  const interactive = logger === console && Boolean(process.stdout.isTTY);
+  const spinner = interactive ? ora({ text: label, color: "cyan" }).start() : null;
+  if (!spinner) logger.log(`  ${label}`);
+  try {
+    await execa(cmd, args, { cwd, all: true });
+    if (spinner) spinner.succeed(label);
+    else logger.log(`  ✔ ${label}`);
+    return true;
+  } catch (err) {
+    if (spinner) spinner.fail(label);
+    else logger.log(`  ✖ ${label}`);
+    const detail = (err.all || err.shortMessage || err.message || "").trim();
+    if (detail) logger.log(chalk.dim(detail.split("\n").slice(-12).join("\n")));
+    throw err;
+  }
+}
+
+async function commandExists(cmd) {
+  try {
+    await execa(cmd, ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Bootstrap the Python environment + dependencies for a generated project.
+ *
+ * Branches on the chosen package manager. Never throws on a missing tool —
+ * instead prints the exact manual commands so the user can finish by hand.
+ *
+ * @returns {Promise<{ok: boolean, manual?: string[]}>}
+ */
+export async function bootstrap(answers, { cwd, logger = console } = {}) {
+  const pm = answers.pythonManager;
+  const manual = manualInstallCommands(pm);
+
+  try {
+    if (pm === "uv") {
+      if (!(await commandExists("uv"))) {
+        return printManual(logger, manual, "`uv` was not found on your PATH.");
+      }
+      await runStep({ label: "Creating virtual environment (uv venv)", cmd: "uv", args: ["venv"], cwd, logger });
+      await runStep({
+        label: "Installing dependencies (uv pip install)",
+        cmd: "uv",
+        args: ["pip", "install", "-r", "requirements.txt"],
+        cwd,
+        logger,
+      });
+      return { ok: true };
+    }
+
+    if (pm === "poetry") {
+      if (!(await commandExists("poetry"))) {
+        return printManual(logger, manual, "`poetry` was not found on your PATH.");
+      }
+      await runStep({ label: "Installing dependencies (poetry install)", cmd: "poetry", args: ["install"], cwd, logger });
+      return { ok: true };
+    }
+
+    // pip (default fallback)
+    const python = (await commandExists("python3.12"))
+      ? "python3.12"
+      : (await commandExists("python3"))
+        ? "python3"
+        : null;
+    if (!python) {
+      return printManual(logger, manual, "No `python3.12` / `python3` found on your PATH.");
+    }
+    await runStep({ label: `Creating virtual environment (${python} -m venv .venv)`, cmd: python, args: ["-m", "venv", ".venv"], cwd, logger });
+    await runStep({
+      label: "Installing dependencies (.venv/bin/pip install)",
+      cmd: ".venv/bin/pip",
+      args: ["install", "-r", "requirements.txt"],
+      cwd,
+      logger,
+    });
+    return { ok: true };
+  } catch (err) {
+    logger.log(chalk.yellow("\nAutomated install did not complete. Run these manually:"));
+    for (const c of manual) logger.log(chalk.cyan(`  ${c}`));
+    return { ok: false, manual };
+  }
+}
+
+function printManual(logger, manual, reason) {
+  logger.log(chalk.yellow(`\n${reason} Run these manually:`));
+  for (const c of manual) logger.log(chalk.cyan(`  ${c}`));
+  return { ok: false, manual };
+}