create-metamynd-agent 0.1.0 → 0.3.0

package/index.mjs

@@ -12,13 +12,13 @@
 //   npx create-metamynd-agent
 //   npx create-metamynd-agent --api http://localhost:9926/api/v1 --email you@x.com \
 //       --name "Support Bot" --scope flight-purchase --per-txn-max 500 --out ./support-bot --yes
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import readline from 'node:readline';
 import crypto from 'node:crypto';
 
 const GUARD_PKG = '@metamynd/agentsafe-guard';
-const GUARD_VERSION = '^0.1.0';
+const GUARD_VERSION = '^0.3.0';
 const DEFAULT_API = 'https://metamynd.ai/api/v1';
 
 // ---------- tiny ANSI ----------
@@ -39,6 +39,8 @@ function parseArgs(argv) {
     if (a === '-h' || a === '--help') { out.help = true; continue; }
     if (a === '-v' || a === '--version') { out.version = true; continue; }
     if (a === '-y' || a === '--yes' || a === '--non-interactive') { out.yes = true; continue; }
+    // Explicit, so `--force ./dir` cannot swallow the path as this flag's value.
+    if (a === '-f' || a === '--force') { out.force = true; continue; }
     if (a.startsWith('--')) {
       const eq = a.indexOf('=');
       if (eq !== -1) { out[a.slice(2, eq)] = a.slice(eq + 1); continue; }
@@ -62,6 +64,7 @@ ${c.b('Options')}
   --request            Delegated: request an agent for an owner's org (--owner <email>, +--byok)
   --claim [--watch]    Delegated: claim the config once the owner approves (reads metamynd-request.json)
   --owner <email>      Target owner's email (with --request)
+  --force, -f          Scaffold into a non-empty directory, overwriting existing files
   --api <url>          API base (default ${DEFAULT_API})
   --email <email>      Owner login email
   --password <pw>      Owner password (prefer the interactive prompt or METAMYND_PASSWORD)
@@ -186,6 +189,7 @@ function exampleIndex(scope, perTxnMax) {
 // Every governed tool call is checked (allow / block / escalate) before it runs.
 import { createGuardFromConfig } from '${GUARD_PKG}';
 
+// Loads agent.metamynd.json: the agent's DID, its signing key, and the gate to call.
 const guard = await createGuardFromConfig('./agent.metamynd.json'); // no env vars
 
 // --- Your real tool. Replace the body with your actual implementation. ---
@@ -205,22 +209,85 @@ const gatedBookFlight = guard.guardTool(
   }),
 );
 
-async function ask(label, args) {
+const dim = (t) => '\\x1b[2m' + t + '\\x1b[0m';
+const bold = (t) => '\\x1b[1m' + t + '\\x1b[0m';
+const rule = (n) => '  ' + '-'.repeat(n);
+
+// Plain-English meaning for the reason codes this demo can produce.
+const WHY = {
+  AUTHORIZED: 'inside the mandate and under the SOP spend cap',
+  SOP_SPEND_CAP: 'your SOP caps a single transaction at $${perTxnMax}',
+  RISK_REVIEW: 'your SOP sends high-risk actions to a human first',
+  MERCHANT_NOT_ALLOWED: 'the mandate lists which merchants this agent may pay',
+};
+
+// ---------------------------------------------------------------- 1. CONTEXT
+console.log('');
+console.log(bold('  What this simulation shows'));
+console.log('');
+console.log('  An agent should not be the thing that decides what it is allowed to do.');
+console.log('  This run makes that concrete: the SAME code path is attempted three times');
+console.log('  and produces three different outcomes, because the decision is made');
+console.log('  outside your program - and cannot be argued with from inside it.');
+
+// ---------------------------------------------------------------- 2. MECHANISM
+console.log('');
+console.log(bold('  How it does that'));
+console.log('');
+console.log(dim('   1. this project holds an agent identity (a DID) and its signing key'));
+console.log(dim('   2. that agent has a mandate - a scope it may act in, and a spend cap'));
+console.log(dim('   3. guardTool() wraps your tool, so nothing calls the raw handler'));
+console.log(dim('   4. each attempt is signed here, then decided by MetaMynd remotely'));
+console.log(dim('   5. your tool runs ONLY if that decision is ALLOW'));
+console.log('');
+console.log(dim('  scope  ${scope}'));
+console.log(dim('  cap    $${perTxnMax} per transaction, set by your SOP'));
+
+// ---------------------------------------------------------------- 3. THE STEPS
+async function attempt(n, intent, args) {
+  console.log('');
+  console.log(bold('  Step ' + n + ' of 3') + ' - ' + intent);
+  console.log(dim('     signing the request locally, then asking the gate to decide...'));
   try {
     const r = await gatedBookFlight(args);
-    console.log('  \\x1b[32m✅ ALLOW\\x1b[0m    ' + label.padEnd(26) + ' → booked ' + r.pnr);
+    console.log('\\x1b[32m     ALLOWED\\x1b[0m  your tool ran and returned ' + r.pnr);
+    console.log(dim('     ' + WHY.AUTHORIZED));
   } catch (e) {
     const g = e.governance ?? {};
-    const tag = g.decision === 'escalate' ? '\\x1b[33m⚠ ESCALATE\\x1b[0m' : '\\x1b[31m⛔ BLOCK\\x1b[0m';
-    console.log('  ' + tag + ' ' + label.padEnd(26) + ' → ' + (g.reasonCode ?? e.message));
+    const why = WHY[g.reasonCode] ?? e.message;
+    if (g.decision === 'escalate') {
+      console.log('\\x1b[33m     ESCALATED\\x1b[0m  held for a human - ' + g.reasonCode);
+      console.log(dim('     ' + why));
+      console.log(dim('     not a failure: approve it in the dashboard and the action resumes.'));
+    } else {
+      console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? 'refused'));
+      console.log(dim('     ' + why));
+      console.log(dim('     your tool never ran - the gate refused before execution.'));
+    }
   }
 }
 
-console.log('\\n  ${scope} — every action passes through the MetaMynd gate\\n  ' + '─'.repeat(58));
-await ask('$${under} low risk',  { amount: ${under}, merchant: 'skyward-air', riskLevel: 'low' });
-await ask('$${over} over cap',  { amount: ${over}, merchant: 'skyward-air', riskLevel: 'low' });
-await ask('$${under} high risk', { amount: ${under}, merchant: 'skyward-air', riskLevel: 'high' });
-console.log('\\n  Change the rules any time in the dashboard (Legal Entity → SOPs) — no redeploy.\\n');
+console.log('');
+console.log(rule(66));
+await attempt(1, 'a $${under} booking, low risk. Expected to pass.', { amount: ${under}, merchant: 'skyward-air', riskLevel: 'low' });
+await attempt(2, 'a $${over} booking, deliberately over the cap.', { amount: ${over}, merchant: 'skyward-air', riskLevel: 'low' });
+await attempt(3, 'a $${under} booking, but flagged high risk.', { amount: ${under}, merchant: 'skyward-air', riskLevel: 'high' });
+console.log('');
+console.log(rule(66));
+
+// ---------------------------------------------------------------- 4. RESULT
+console.log('');
+console.log(bold('  What this proved'));
+console.log('');
+console.log(dim('   - one code path, three outcomes. The rules decided, not this file'));
+console.log(dim('     and not the model driving it.'));
+console.log(dim('   - the blocked call never reached your tool at all.'));
+console.log(dim('   - every decision was recorded as tamper-evident evidence.'));
+console.log(dim('   - if the gate were unreachable the guard fails CLOSED: it blocks.'));
+console.log('');
+console.log('  Change the cap in the dashboard (Legal Entity -> SOPs) and run again.');
+console.log(dim('  The outcome changes. This file does not. That is the point.'));
+console.log('');
 `;
 }
 
@@ -272,22 +339,48 @@ function gitignore() {
   return `node_modules/\nagent.metamynd.json\n.env\n`;
 }
 
-function writeFileSafe(dir, name, content) {
+function writeFileSafe(dir, name, content, force = false) {
   const p = join(dir, name);
-  if (existsSync(p)) { console.log(`  ${c.yellow('skip')}  ${name} ${c.dim('(exists)')}`); return; }
+  const exists = existsSync(p);
+  if (exists && !force) { console.log(`  ${c.yellow('skip')}  ${name} ${c.dim('(exists)')}`); return; }
   writeFileSync(p, content);
-  console.log(`  ${c.green('create')} ${name}`);
+  console.log(`  ${exists ? c.yellow('overwrite') : c.green('create')} ${name}`);
+}
+
+/**
+ * Refuse to scaffold into a non-empty directory unless --force.
+ *
+ * Silently skipping an existing agent.metamynd.json is worse than it sounds:
+ * provisioning has already minted a NEW agent server-side, so the scaffold prints
+ * success while leaving the OLD config in place. Every later gate call then runs as
+ * the previous identity, against whatever apiBase that file happens to carry — which
+ * is exactly how a stale http:// base survived a re-scaffold and 404'd every call.
+ */
+function assertScaffoldTarget(outDir, force) {
+  if (force || !existsSync(outDir)) return;
+  const entries = readdirSync(outDir);
+  if (entries.length === 0) return;
+  const rel = outDir.replace(resolve('.'), '.').replace(/\\/g, '/');
+  fail(
+    `${rel} is not empty (${entries.length} item${entries.length === 1 ? '' : 's'}).\n\n` +
+      `  Scaffolding here would KEEP the existing files — including any agent.metamynd.json —\n` +
+      `  so this project would keep running as the identity in that file, against the apiBase\n` +
+      `  in that file, and the newly provisioned agent would go unused.\n\n` +
+      `  Scaffold somewhere new:        --out ./another-dir\n` +
+      `  or overwrite this one on purpose: --force`,
+  );
 }
 
 /** Write the scaffolded project + print next steps. Shared by the provision and sandbox paths. */
-function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox }) {
+function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox, force = false }) {
+  assertScaffoldTarget(outDir, force);
   console.log(`\n  ${c.b('Scaffolding')} ${c.dim(outDir)}`);
   if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
-  writeFileSafe(outDir, 'agent.metamynd.json', JSON.stringify(config, null, 2) + '\n');
-  writeFileSafe(outDir, 'index.mjs', exampleIndex(scope, perTxnMax));
-  writeFileSafe(outDir, 'package.json', examplePackageJson(slug));
-  writeFileSafe(outDir, '.gitignore', gitignore());
-  writeFileSafe(outDir, 'README.md', exampleReadme(slug, scope));
+  writeFileSafe(outDir, 'agent.metamynd.json', JSON.stringify(config, null, 2) + '\n', force);
+  writeFileSafe(outDir, 'index.mjs', exampleIndex(scope, perTxnMax), force);
+  writeFileSafe(outDir, 'package.json', examplePackageJson(slug), force);
+  writeFileSafe(outDir, '.gitignore', gitignore(), force);
+  writeFileSafe(outDir, 'README.md', exampleReadme(slug, scope), force);
 
   const rel = outDir.replace(resolve('.'), '.').replace(/\\/g, '/');
   console.log(`\n${c.green(c.b('  ✓ Done.'))} Your governed agent is ready.\n`);
@@ -307,6 +400,10 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox }) {
 async function runSandbox(args) {
   const apiRaw = (typeof args.api === 'string' ? args.api : undefined) ?? process.env.METAMYND_API ?? DEFAULT_API;
   const base = String(apiRaw).replace(/\/+$/, '');
+  // Check the target BEFORE provisioning: refusing afterwards would mint an agent
+  // server-side and then throw it away.
+  const outDir = resolve(String(args.out || './metamynd-sandbox'));
+  assertScaffoldTarget(outDir, !!args.force);
   console.log(c.dim(`  → requesting a sandbox agent from ${base} …`));
   const provisioned = await apiPost(base, '/onboarding/sandbox', {}, null);
   const config = provisioned?.data;
@@ -314,8 +411,7 @@ async function runSandbox(args) {
   console.log(`  ${c.green('✓')} sandbox agent ${c.b(config.agentDid)} ${c.dim('(shared test identity)')}`);
   const scope = config.mandate?.scope || 'flight-purchase';
   const perTxnMax = Number(config.perTxnMax) || 500;
-  const outDir = resolve(String(args.out || './metamynd-sandbox'));
-  scaffoldProject({ outDir, config, slug: 'metamynd-sandbox', scope, perTxnMax, sandbox: true });
+  scaffoldProject({ outDir, config, slug: 'metamynd-sandbox', scope, perTxnMax, sandbox: true, force: !!args.force });
 }
 
 // ---------- delegated issuance (#6) ----------
@@ -429,7 +525,7 @@ async function runClaim(args) {
 
   const slug = slugify(state.name || 'metamynd-agent');
   const outDir = resolve(String(args.out || `./${slug}`));
-  scaffoldProject({ outDir, config, slug, scope: state.scope || config.mandate?.scope || 'flight-purchase', perTxnMax: Number(state.perTxnMax) || 500, sandbox: false });
+  scaffoldProject({ outDir, config, slug, scope: state.scope || config.mandate?.scope || 'flight-purchase', perTxnMax: Number(state.perTxnMax) || 500, sandbox: false, force: !!args.force });
 }
 
 // ---------- main ----------
@@ -536,7 +632,7 @@ async function main() {
   }
 
   // 4. Scaffold + next steps
-  scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox: false });
+  scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox: false, force: !!args.force });
 }
 
 main().catch((e) => fail(e?.stack || e?.message || String(e)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Scaffold a MetaMynd/AgentSafe-governed AI agent in one command — logs in, provisions the agent (identity + mandate + SOP + Standards) in a single call, writes agent.metamynd.json, and drops a runnable example.",
   "type": "module",
   "bin": {