@4mica/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 4mica Network
+
+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,59 @@
+# @4mica/cli
+
+The command-line tool for the [4Mica](https://4mica.io) x402 payment network.
+Scaffold a trading agent or payment app, install it, run it, and manage your
+agents from a local dashboard.
+
+## Quick start
+
+```bash
+npx @4mica/cli
+# or
+npm create @4mica
+```
+
+Answer a few prompts and you'll have a running project in demo mode — no
+credentials required.
+
+## Commands
+
+```bash
+4mica init [dir]     # scaffold a new agent or app (default command)
+4mica dashboard      # open the dashboard to manage agents & transactions
+4mica dev            # run the current project's dev server
+```
+
+### `4mica init`
+
+Interactive by default. Every prompt has a matching flag for non-interactive /
+CI use:
+
+```bash
+4mica init my-app \
+  --type seller \        # agent | seller | buyer
+  --framework hono \     # express | hono | next   (seller/buyer)
+  --role seller \        # seller | buyer          (agent)
+  --pm pnpm \            # pnpm | npm | yarn | bun
+  --no-run \             # scaffold without starting the dev server
+  --yes                  # accept defaults, no prompts
+```
+
+## Templates
+
+| Type | Frameworks | Based on |
+| --- | --- | --- |
+| Trading agent | seller (Express) · buyer (Node) | seller/buyer agents |
+| Paywalled API (seller) | Express · Hono · Next | x402 paywall |
+| Buyer client | Express · Hono · Next targets | x402 handshake |
+
+Every template runs in **demo mode** with a mock verifier. To go live, copy
+`.env.example` → `.env`, fill in your `4MICA_*` credentials, and swap the mock
+verifier for `createClient()` from `@4mica/sdk-node`.
+
+## Dashboard
+
+`4mica dashboard` launches a local dashboard (Stripe test-mode style) to add and
+remove agents that can trade, view and publish an agent's profile (accuracy,
+uptime, pricing, policy, verification), inspect transactions, and manage the
+trade allow-list. It runs on mock data today; a hosted version with accounts and
+a sandbox→live switch is coming.

package/dist/index.js

@@ -0,0 +1,628 @@
+#!/usr/bin/env node
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { readFile, access, readdir, mkdir, writeFile } from 'fs/promises';
+import { join, resolve, dirname, relative, isAbsolute } from 'path';
+import { execa } from 'execa';
+import { fileURLToPath } from 'url';
+import { findUp } from 'find-up';
+import ora from 'ora';
+import pc from 'picocolors';
+import { intro, outro, confirm, cancel, select, text, note, isCancel } from '@clack/prompts';
+import terminalLink from 'terminal-link';
+
+function bundledTemplatesDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "templates");
+}
+async function resolveRunContext(cwd = process.cwd()) {
+  const workspaceFile = await findUp("pnpm-workspace.yaml", { cwd });
+  if (workspaceFile) {
+    const root = dirname(workspaceFile);
+    try {
+      const pkg = JSON.parse(
+        await readFile(join(root, "package.json"), "utf8")
+      );
+      if (pkg.name === "4mica") {
+        return {
+          inMonorepo: true,
+          monorepoRoot: root,
+          templatesDir: bundledTemplatesDir()
+        };
+      }
+    } catch {
+    }
+  }
+  return { inMonorepo: false, templatesDir: bundledTemplatesDir() };
+}
+var LOCKFILES = {
+  "pnpm-lock.yaml": "pnpm",
+  "package-lock.json": "npm",
+  "yarn.lock": "yarn",
+  "bun.lockb": "bun",
+  "bun.lock": "bun"
+};
+function fromUserAgent() {
+  const ua = process.env.npm_config_user_agent;
+  if (!ua) return void 0;
+  const name = ua.split("/")[0];
+  if (name === "pnpm" || name === "npm" || name === "yarn" || name === "bun") {
+    return name;
+  }
+  return void 0;
+}
+async function fromLockfile(cwd) {
+  const found = await findUp(Object.keys(LOCKFILES), { cwd });
+  if (!found) return void 0;
+  const file = found.slice(found.lastIndexOf("/") + 1);
+  return LOCKFILES[file];
+}
+async function detectPackageManager(cwd, override) {
+  return override ?? fromUserAgent() ?? await fromLockfile(cwd) ?? "pnpm";
+}
+function installArgs(_pm) {
+  return ["install"];
+}
+function runArgs(pm, script) {
+  return pm === "yarn" ? [script] : ["run", script];
+}
+async function install(pm, cwd) {
+  await execa(pm, installArgs(), { cwd, stdio: "pipe" });
+}
+async function runScript(pm, script, cwd) {
+  await execa(pm, runArgs(pm, script), { cwd, stdio: "inherit" });
+}
+async function gitInit(cwd) {
+  try {
+    await execa("git", ["init", "-q"], { cwd });
+    await execa("git", ["add", "-A"], { cwd });
+  } catch {
+  }
+}
+async function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    await execa(cmd, [url], { stdio: "ignore", detached: true });
+  } catch {
+  }
+}
+var brand = (s) => pc.cyan(pc.bold(s));
+var dim = (s) => pc.dim(s);
+var ok = (s) => pc.green(s);
+var warn = (s) => pc.yellow(s);
+var err = (s) => pc.red(s);
+function spinner(text2) {
+  return ora({ text: text2, color: "cyan" }).start();
+}
+async function step(text2, fn, doneText) {
+  const s = spinner(text2);
+  try {
+    const result = await fn();
+    s.succeed(ok(doneText ?? text2));
+    return result;
+  } catch (error) {
+    s.fail(err(`${text2} \u2014 ${error.message}`));
+    throw error;
+  }
+}
+
+// src/commands/dashboard.ts
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function launchDashboard(opts = {}) {
+  const context = await resolveRunContext();
+  if (!context.inMonorepo || !context.monorepoRoot) {
+    process.stdout.write(
+      `
+  ${warn("Dashboard")} runs from the 4Mica monorepo in this release.
+  Clone ${pc.cyan("github.com/4mica-Network/homepage")} and run ${pc.bold("pnpm --filter @4mica/dashboard dev")},
+  or use the hosted dashboard (coming soon). ${dim("More: 4mica.io/docs")}
+
+`
+    );
+    return;
+  }
+  const dashboardDir = join(context.monorepoRoot, "apps", "dashboard");
+  if (!await exists(dashboardDir)) {
+    process.stdout.write(
+      `
+  ${warn("apps/dashboard not found in this checkout.")}
+
+`
+    );
+    return;
+  }
+  const pm = await detectPackageManager(context.monorepoRoot);
+  const args = pm === "yarn" ? ["workspace", "@4mica/dashboard", "dev"] : ["--filter", "@4mica/dashboard", "dev"];
+  process.stdout.write(`
+  ${ok("Starting the 4Mica dashboard\u2026")}
+
+`);
+  if (opts.background) {
+    const child2 = execa(pm, args, {
+      cwd: context.monorepoRoot,
+      stdio: "ignore",
+      detached: true
+    });
+    child2.unref();
+    if (opts.open) {
+      setTimeout(() => void openBrowser("http://localhost:4173"), 2500);
+    }
+    return;
+  }
+  const child = execa(pm, args, {
+    cwd: context.monorepoRoot,
+    stdio: "inherit"
+  });
+  if (opts.open) {
+    setTimeout(() => void openBrowser("http://localhost:4173"), 2500);
+  }
+  await child;
+}
+
+// src/commands/dev.ts
+async function devCommand(script = "dev") {
+  const cwd = process.cwd();
+  const pm = await detectPackageManager(cwd);
+  await runScript(pm, script, cwd);
+}
+var cache = null;
+async function loadSnapshot() {
+  if (cache) return cache;
+  const here = dirname(fileURLToPath(import.meta.url));
+  const path = join(here, "..", "snapshot.json");
+  try {
+    cache = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    cache = { catalog: {}, catalogs: {}, fourMica: {} };
+  }
+  return cache;
+}
+function resolveCatalog(snap, spec, name) {
+  const named = spec.slice("catalog:".length).trim();
+  const table = named ? snap.catalogs[named] ?? {} : snap.catalog;
+  return table[name] ?? "latest";
+}
+function resolveWorkspace(snap, name) {
+  const version = snap.fourMica[name];
+  return version ? `^${version}` : "latest";
+}
+function rewriteBlock(block, snap, keepWorkspace) {
+  if (!block) return;
+  for (const [name, spec] of Object.entries(block)) {
+    if (spec.startsWith("workspace:")) {
+      block[name] = keepWorkspace ? spec : resolveWorkspace(snap, name);
+    } else if (spec.startsWith("catalog:")) {
+      block[name] = resolveCatalog(snap, spec, name);
+    }
+  }
+}
+async function rewritePackageJson(pkg, opts) {
+  const snap = await loadSnapshot();
+  rewriteBlock(
+    pkg.dependencies,
+    snap,
+    opts.keepWorkspace
+  );
+  rewriteBlock(
+    pkg.devDependencies,
+    snap,
+    opts.keepWorkspace
+  );
+  if (!opts.keepWorkspace) {
+    pkg.private = void 0;
+  }
+  return pkg;
+}
+
+// src/core/substitute.ts
+function substitute(body, tokens) {
+  const table = tokens;
+  return body.replace(/__([A-Z_]+)__/g, (match, key) => {
+    const value = table[key];
+    return value === void 0 ? match : value;
+  });
+}
+function toPackageName(input) {
+  const cleaned = input.trim().toLowerCase().replace(/[^a-z0-9-~._]+/g, "-").replace(/^[-_.]+|[-_.]+$/g, "");
+  return cleaned || "my-4mica-app";
+}
+
+// src/core/copy-engine.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".next", ".turbo", ".git"]);
+var TEXT_EXT = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".json",
+  ".md",
+  ".css",
+  ".html",
+  ".svg",
+  ".txt",
+  ".yaml",
+  ".yml",
+  ""
+]);
+function targetName(name) {
+  if (name === "_gitignore") return ".gitignore";
+  if (name === "_npmrc") return ".npmrc";
+  return name;
+}
+function extOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot);
+}
+async function copyTemplate(opts) {
+  await walk(opts.templateDir, opts);
+}
+async function walk(dir, opts) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await walk(join(dir, entry.name), opts);
+      continue;
+    }
+    await copyFile(join(dir, entry.name), opts);
+  }
+}
+async function copyFile(srcPath, opts) {
+  const rel = relative(opts.templateDir, srcPath);
+  const parts = rel.split("/");
+  parts[parts.length - 1] = targetName(parts[parts.length - 1]);
+  const destPath = join(opts.targetDir, ...parts);
+  await mkdir(join(destPath, ".."), { recursive: true });
+  const base = parts[parts.length - 1];
+  if (base === "package.json") {
+    await writePackageJson(srcPath, destPath, opts);
+    return;
+  }
+  if (TEXT_EXT.has(extOf(base))) {
+    const body = await readFile(srcPath, "utf8");
+    await writeFile(destPath, substitute(body, opts.tokens));
+    return;
+  }
+  const raw = await readFile(srcPath);
+  await writeFile(destPath, raw);
+}
+async function writePackageJson(srcPath, destPath, opts) {
+  const body = substitute(await readFile(srcPath, "utf8"), opts.tokens);
+  const pkg = JSON.parse(body);
+  const rewritten = await rewritePackageJson(pkg, {
+    keepWorkspace: opts.keepWorkspace
+  });
+  await writeFile(destPath, `${JSON.stringify(rewritten, null, 2)}
+`);
+}
+
+// src/core/template-registry.ts
+function resolveTemplate(opts) {
+  if (opts.type === "agent") {
+    return opts.agentRole === "seller" ? {
+      dir: "agent-seller-express",
+      port: 4100,
+      tmpfile: "4mica-agent.url",
+      runScript: "dev",
+      description: "Trading seller agent: sells information, paywalls the premium result with dynamic per-request pricing"
+    } : {
+      dir: "agent-buyer-node",
+      port: 4100,
+      tmpfile: "4mica-agent.url",
+      runScript: "start",
+      description: "Trading buyer agent: pursues a goal under a budget, pays sellers over x402, and adapts its strategy"
+    };
+  }
+  const ports = {
+    express: 3e3,
+    hono: 3001,
+    next: 3002
+  };
+  const tmpfile = `4mica-${opts.framework}.url`;
+  if (opts.type === "seller") {
+    return {
+      dir: `seller-${opts.framework}`,
+      port: ports[opts.framework],
+      tmpfile,
+      runScript: "dev",
+      description: `Seller (recipient): gate a ${opts.framework} route behind a 4Mica x402 paywall`
+    };
+  }
+  return {
+    dir: `buyer-${opts.framework}`,
+    port: ports[opts.framework],
+    tmpfile,
+    runScript: "start",
+    description: `Buyer (payer): perform the x402 handshake against a ${opts.framework} seller`
+  };
+}
+function bail() {
+  cancel("Scaffolding cancelled.");
+  process.exit(0);
+}
+function unwrap(value) {
+  if (isCancel(value)) bail();
+  return value;
+}
+async function runInitFlow(flags, defaultPm) {
+  if (flags.type === void 0) {
+    const fromScratch = unwrap(
+      await confirm({
+        message: "Generate a new 4Mica project from scratch?",
+        initialValue: true
+      })
+    );
+    if (!fromScratch) {
+      cancel(
+        "No problem \u2014 add 4Mica to an existing app with `npm i @4mica/sdk @4mica/sdk-node`, then wrap a route with a paywall. Docs: https://4mica.io/docs"
+      );
+      process.exit(0);
+    }
+  }
+  const type = flags.type ?? unwrap(
+    await select({
+      message: "What are you building?",
+      options: [
+        {
+          value: "agent",
+          label: "Trading agent",
+          hint: "buys/sells over x402"
+        },
+        { value: "seller", label: "Paywalled API (seller)" },
+        { value: "buyer", label: "Buyer client" }
+      ]
+    })
+  );
+  let agentRole = flags.agentRole ?? "seller";
+  let framework = flags.framework ?? "express";
+  if (type === "agent") {
+    if (flags.agentRole === void 0) {
+      agentRole = unwrap(
+        await select({
+          message: "Which side does your agent play?",
+          options: [
+            {
+              value: "seller",
+              label: "Seller agent",
+              hint: "earns by selling info"
+            },
+            {
+              value: "buyer",
+              label: "Buyer agent",
+              hint: "spends to reach a goal"
+            }
+          ]
+        })
+      );
+    }
+  } else if (flags.framework === void 0) {
+    framework = unwrap(
+      await select({
+        message: "Which framework?",
+        options: [
+          { value: "express", label: "Express" },
+          { value: "hono", label: "Hono" },
+          { value: "next", label: "Next.js" }
+        ]
+      })
+    );
+  }
+  const defaultName = type === "agent" ? `my-${agentRole}-agent` : `my-${type}-${framework}`;
+  const name = flags.name ?? toPackageName(
+    unwrap(
+      await text({
+        message: "Project name?",
+        placeholder: defaultName,
+        defaultValue: defaultName
+      })
+    )
+  );
+  const packageManager = flags.packageManager ?? unwrap(
+    await select({
+      message: "Install with which package manager?",
+      initialValue: defaultPm,
+      options: [
+        { value: "pnpm", label: "pnpm" },
+        { value: "npm", label: "npm" },
+        { value: "yarn", label: "yarn" },
+        { value: "bun", label: "bun" }
+      ]
+    })
+  );
+  const openDashboard = flags.openDashboard ?? unwrap(
+    await confirm({
+      message: "Open the 4Mica dashboard to manage agents & transactions?",
+      initialValue: true
+    })
+  );
+  return {
+    dir: flags.dir ?? name,
+    name,
+    type,
+    framework,
+    agentRole,
+    packageManager,
+    install: flags.install ?? true,
+    run: flags.run ?? true,
+    openDashboard
+  };
+}
+
+// src/commands/init.ts
+async function exists2(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isInside(child, parent) {
+  const rel = relative(parent, child);
+  return !rel.startsWith("..") && !isAbsolute(rel);
+}
+async function initCommand(flags) {
+  intro(brand("4mica"));
+  const context = await resolveRunContext();
+  const defaultPm = await detectPackageManager(
+    process.cwd(),
+    flags.packageManager
+  );
+  const opts = await runInitFlow(flags, defaultPm);
+  const template = resolveTemplate(opts);
+  const templateDir = join(context.templatesDir, template.dir);
+  const targetDir = resolve(process.cwd(), opts.dir);
+  if (!await exists2(templateDir)) {
+    throw new Error(`Template not found: ${template.dir}`);
+  }
+  if (await exists2(targetDir)) {
+    throw new Error(
+      `Directory already exists: ${opts.dir} \u2014 choose another name.`
+    );
+  }
+  const keepWorkspace = context.inMonorepo && context.monorepoRoot !== void 0 && isInside(targetDir, context.monorepoRoot);
+  await step(
+    `Scaffolding ${pc.bold(opts.name)}`,
+    () => copyTemplate({
+      templateDir,
+      targetDir,
+      tokens: {
+        PROJECT_NAME: opts.name,
+        DESCRIPTION: template.description,
+        PORT: String(template.port),
+        TMPFILE: template.tmpfile
+      },
+      keepWorkspace
+    })
+  );
+  await gitInit(targetDir);
+  if (opts.install) {
+    await step(
+      `Installing dependencies with ${opts.packageManager}`,
+      () => install(opts.packageManager, targetDir),
+      "Dependencies installed"
+    );
+  }
+  printNextSteps(opts, template.runScript);
+  outro(ok("Done \u2014 happy building!"));
+  if (opts.openDashboard) {
+    await launchDashboard({ open: true, background: true });
+  }
+  if (opts.install && opts.run) {
+    await runScript(opts.packageManager, template.runScript, targetDir);
+  }
+}
+function printNextSteps(opts, script) {
+  const docs = terminalLink("4mica.io/docs", "https://4mica.io/docs");
+  const lines = [`cd ${opts.dir}`];
+  if (!opts.install) lines.push(`${opts.packageManager} install`);
+  lines.push(`${opts.packageManager} run ${script}`);
+  lines.push("");
+  lines.push(`${dim("Demo mode needs no config. Going live?")} ${docs}`);
+  lines.push(`${dim("Env template:")} ${warn(join(opts.dir, ".env.example"))}`);
+  note(lines.join("\n"), "Next steps");
+}
+
+// src/cli.ts
+var BUILD_TYPES = ["agent", "seller", "buyer"];
+var FRAMEWORKS = ["express", "hono", "next"];
+var AGENT_ROLES = ["seller", "buyer"];
+var PMS = ["pnpm", "npm", "yarn", "bun"];
+function flagsFromArgv(argv) {
+  const flags = {};
+  if (argv.dir) flags.dir = String(argv.dir);
+  if (argv.name) flags.name = String(argv.name);
+  if (argv.type) flags.type = argv.type;
+  if (argv.framework) flags.framework = argv.framework;
+  if (argv.role) flags.agentRole = argv.role;
+  if (argv.pm) flags.packageManager = argv.pm;
+  if (argv.install === false) flags.install = false;
+  if (argv.run === false) flags.run = false;
+  if (argv.dashboard !== void 0)
+    flags.openDashboard = Boolean(argv.dashboard);
+  if (argv.yes) {
+    flags.type ??= "agent";
+    if (flags.type === "agent") flags.agentRole ??= "seller";
+    else flags.framework ??= "express";
+    flags.packageManager ??= "pnpm";
+    flags.install ??= true;
+    flags.run ??= false;
+    flags.openDashboard ??= false;
+    flags.name ??= flags.type === "agent" ? `my-${flags.agentRole}-agent` : `my-${flags.type}-${flags.framework}`;
+  }
+  return flags;
+}
+async function run() {
+  const cli = yargs(hideBin(process.argv)).scriptName("4mica").usage("$0 <command> [options]").command(
+    ["init [dir]", "$0 [dir]"],
+    "Scaffold a new 4Mica agent or payment app",
+    (y) => y.positional("dir", { type: "string", describe: "Target directory" }).option("type", { choices: BUILD_TYPES, describe: "What to build" }).option("framework", {
+      choices: FRAMEWORKS,
+      describe: "Framework (seller/buyer)"
+    }).option("role", {
+      choices: AGENT_ROLES,
+      describe: "Trading role (agent)"
+    }).option("name", { type: "string", describe: "Project name" }).option("pm", { choices: PMS, describe: "Package manager" }).option("install", {
+      type: "boolean",
+      default: true,
+      describe: "Install dependencies"
+    }).option("run", {
+      type: "boolean",
+      default: true,
+      describe: "Start the dev server after scaffolding"
+    }).option("dashboard", {
+      type: "boolean",
+      describe: "Open the dashboard after scaffolding"
+    }).option("yes", {
+      alias: "y",
+      type: "boolean",
+      describe: "Accept defaults; no prompts (CI)"
+    }),
+    async (argv) => {
+      await initCommand(flagsFromArgv(argv));
+    }
+  ).command(
+    "dashboard",
+    "Launch the 4Mica dashboard (manage agents, transactions, whitelist)",
+    (y) => y.option("open", {
+      type: "boolean",
+      default: true,
+      describe: "Open a browser"
+    }),
+    async (argv) => {
+      await launchDashboard({ open: Boolean(argv.open) });
+    }
+  ).command(
+    "dev",
+    "Run the current project's dev server",
+    (y) => y,
+    async () => {
+      await devCommand();
+    }
+  ).demandCommand(0).strict().help().alias("help", "h").version().alias("version", "v").fail((msg, error) => {
+    process.stderr.write(err(`
+${msg || error?.message || "Error"}
+`));
+    process.exit(1);
+  });
+  await cli.parse();
+}
+
+// src/index.ts
+run().catch((error) => {
+  process.stderr.write(err(`
+${error.message}
+`));
+  process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map