@inneranimalmedia/agentsam-sdk 1.2.0 → 1.5.1

package/README.md

@@ -22,24 +22,42 @@ It is not a wrapper around a chat API. It is a command fabric with a conversatio
 
 ---
 
-## Quickstart
+## Quickstart (local-first — Node only)
 
 ```bash
 npx @inneranimalmedia/agentsam-sdk init
 ```
 
-Non-interactive (CI / scripts):
+Default path: **localhost**. No IAM login, no Cloudflare OAuth, no accounts. Under 2 minutes with Node 20+ installed.
+
+```bash
+cd my-project
+npm install
+npm run smoke
+npx agentsam start-local   # local PTY on ws://127.0.0.1:3099
+npm run dev                # http://127.0.0.1:8787
+npm run db:migrate         # local D1 schema
+```
+
+When you're ready to ship to **your** Cloudflare account:
+
+```bash
+npx agentsam deploy
+```
+
+Cloudflare OAuth is prompted **only at deploy** — not at init.
+
+Non-interactive init:
 
 ```bash
 npx @inneranimalmedia/agentsam-sdk init \
   --name my-agent \
   --lane fullstack \
-  --provider cloudflare \
-  --agent orchestrator \
+  --run-target local \
   --yes
 ```
 
-Scaffolded workers expose `GET /health` and `POST /chat` immediately (stub mode without an API key).
+Run targets at init: `local` (default) · `cloudflare` · `gcp` — all scaffold locally first; cloud credentials come at deploy.
 
 See [DEVELOPMENT.md](./DEVELOPMENT.md) for linking the SDK into Inner Animal Media locally.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "1.2.0",
+  "version": "1.5.1",
   "description": "Agent Sam is a full-stack AI agent SDK for autonomous task execution — covering data management, creative workflows, design commands, and multi-step agentic pipelines.",
   "type": "module",
   "main": "./src/index.js",
@@ -13,6 +13,7 @@
   },
   "files": [
     "src",
+    "templates",
     "docs",
     "examples",
     "test",
@@ -28,6 +29,10 @@
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 
-import readline from 'readline';
 import pkg from '../package.json' with { type: 'json' };
-import { scaffoldProject } from './lib/scaffold.js';
+import readline from 'readline';
+import { buildLocalScaffoldMeta, LANE_KEYS, RUN_TARGETS } from './lib/local-scaffold.js';
+import { writeScaffoldFiles } from './lib/write-files.js';
+import { copyGorillaTemplate } from './lib/gorilla-template.js';
+import { printContextSummary } from './lib/detect-context.js';
+import { promptOptionalByokKeys } from './lib/prompt-byok.js';
+import { runStartLocal } from './commands/start-local.js';
+import { runDeploy } from './commands/deploy.js';
 import { SLASH_COMMANDS, SHELL_PHASES } from './lib/slash-commands.js';
 
 const VERSION = pkg.version;
@@ -15,150 +21,96 @@ function createPrompt() {
   };
 }
 
-const LANES = {
-  '1': 'Full Stack',
-  '2': 'CMS',
-  '3': 'Data Solutions',
-  '4': 'Customer Management',
-  '5': 'Creative & Design',
-};
-
-const LANE_BY_SLUG = {
-  fullstack: 'Full Stack',
-  cms: 'CMS',
-  data: 'Data Solutions',
-  crm: 'Customer Management',
-  creative: 'Creative & Design',
-};
-
-const PROVIDERS = {
-  '1': 'Cloudflare Workers',
-  '2': 'GitHub + Cloudflare',
-  '3': 'Local / Self-hosted',
-};
-
-const PROVIDER_BY_SLUG = {
-  cloudflare: 'Cloudflare Workers',
-  github: 'GitHub + Cloudflare',
-  local: 'Local / Self-hosted',
-};
-
-const AGENTS = {
-  '1': 'orchestrator',
-  '2': 'cms',
-  '3': 'data',
-  '4': 'crm',
-  '5': 'creative',
-};
-
-function laneKeyFromLabel(label) {
-  const entry = Object.entries(LANES).find(([, v]) => v === label);
-  return entry?.[0] ?? '1';
-}
-
 function printHelp() {
   console.log(`
   Agent Sam SDK — CLI v${VERSION}
 
   Usage:
-    agentsam init [options]     Scaffold a new Agent Sam project
-    agentsam shell              CLI shell UX info + slash commands (Gorilla Shell)
-    agentsam --version          Print version
-    agentsam --help             Show this help
-
-  Init options (non-interactive):
-    --name <name>               Project directory name
+    agentsam init              Local-first project scaffold (default: localhost, no accounts)
+    agentsam start-local       Local PTY on ws://127.0.0.1:3099 (no tunnel, no Cloudflare)
+    agentsam deploy            Graduate to Cloudflare / GCP when ready
+    agentsam shell             Slash commands + shell UX info
+    agentsam --version
+    agentsam --help
+
+  Init is completable with Node only — no IAM login, no OAuth, no Cloudflare.
+  Prove locally first; deploy prompts for accounts only when you choose to ship.
+
+  Init options:
+    --name <name>              Project directory name
     --lane <fullstack|cms|data|crm|creative>
-    --provider <cloudflare|github|local>
-    --agent <orchestrator|cms|data|crm|creative>
-    --cf-account <id>           Cloudflare account ID
-    --yes                       Skip confirmation prompt
+    --run-target <local|cloudflare|gcp>   Default: local
+    --yes                      Skip confirmation
   `);
 }
 
 function parseInitArgs(argv) {
   const opts = {
     projectName: '',
-    lane: '',
-    provider: '',
-    agent: '',
-    cfAccountId: '',
+    lane: 'fullstack',
+    runTarget: 'local',
     yes: false,
   };
-
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--yes' || arg === '-y') opts.yes = true;
     else if (arg === '--name') opts.projectName = argv[++i] || '';
-    else if (arg === '--lane') {
-      const slug = argv[++i] || '';
-      opts.lane = LANE_BY_SLUG[slug] || slug;
-    } else if (arg === '--provider') {
-      const slug = argv[++i] || '';
-      opts.provider = PROVIDER_BY_SLUG[slug] || slug;
-    } else if (arg === '--agent') opts.agent = argv[++i] || '';
-    else if (arg === '--cf-account') opts.cfAccountId = argv[++i] || '';
+    else if (arg === '--lane') opts.lane = argv[++i] || 'fullstack';
+    else if (arg === '--run-target' || arg === '--target') opts.runTarget = argv[++i] || 'local';
   }
+  return opts;
+}
 
+function parseDeployArgs(argv) {
+  const opts = { target: '', accountId: '' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--target') opts.target = argv[++i] || '';
+    else if (arg === '--account-id') opts.accountId = argv[++i] || '';
+  }
   return opts;
 }
 
-async function runInit(config) {
-  const {
-    projectName,
-    lane,
-    provider,
-    agent,
-    cfAccountId = '',
-    yes = false,
-    prompt = null,
-  } = config;
+async function runLocalInit(config) {
+  const { projectName, lane, runTarget, prompt } = config;
+
+  const meta = buildLocalScaffoldMeta(
+    { projectName, lane, runTarget },
+    VERSION,
+  );
 
-  const safeDir = projectName.trim();
   console.log(`
   ┌─────────────────────────────────────┐
-  │  Agent Sam Project Config           │
+  │  Agent Sam — local-first scaffold   │
   ├─────────────────────────────────────┤
-  │  Project:   ${safeDir.padEnd(25)}│
-  │  Lane:      ${lane.padEnd(25)}│
-  │  Provider:  ${provider.padEnd(25)}│
-  │  Agent:     ${agent.padEnd(25)}│
-  │  CF Acct:   ${(cfAccountId || 'not set').padEnd(25)}│
+  │  Name:     ${meta.projectName.padEnd(25)}│
+  │  Lane:     ${meta.laneKey.padEnd(25)}│
+  │  Run:      ${meta.runTarget.padEnd(25)}│
   └─────────────────────────────────────┘
   `);
 
-  let confirm = 'y';
-  if (!yes && prompt) {
-    confirm = await prompt.ask('  Scaffold project? (y/n): ');
-  }
+  const dir = writeScaffoldFiles(meta.projectName, meta.files);
+  copyGorillaTemplate(dir, meta);
 
-  if (confirm.toLowerCase() === 'y') {
-    try {
-      const dir = scaffoldProject({
-        projectName: safeDir,
-        lane,
-        provider,
-        agent,
-        cfAccountId,
-        sdkVersion: VERSION,
-      });
-      console.log(`
-  ✓ Project created at ${dir}
+  console.log(`
+  ✓ Project ready: ${dir}
+  ✓ Gorilla Mode UI → gorilla/ (http://localhost:5173 after npm run dev)
 
-  Next steps:
-    cd ${dir.split('/').pop()}
-    cp .env.example .env
-    npm install
-    npm run smoke
-    npm run dev
-    `);
-    } catch (error) {
-      console.error(`\n  ✗ ${error.message}\n`);
-      process.exitCode = 1;
-    }
-  } else {
-    console.log('\n  Cancelled.\n');
+  Next steps:`);
+  for (const step of meta.next_steps) {
+    console.log(`    ${step}`);
+  }
+
+  if (prompt && process.env.AGENTSAM_SDK_TOKEN) {
+    console.log('\n  Optional — BYOK keys for IAM dashboard Agent Sam (skip with Enter):\n');
+    await promptOptionalByokKeys(process.env.AGENTSAM_SDK_TOKEN, prompt);
   }
+
+  console.log(`
+  Local in ~60 seconds:
+    cd ${meta.projectName} && npm install && npm run smoke && npm run dev
+    open http://localhost:5173
+  `);
 }
 
 async function initInteractive(partial = {}) {
@@ -166,66 +118,41 @@ async function initInteractive(partial = {}) {
 
   console.log(`
   ╔═══════════════════════════════════╗
-  ║       Agent Sam SDK — Init        ║
+  ║   Agent Sam SDK — Init            ║
+  ║   Local-first · Node only         ║
   ╚═══════════════════════════════════╝
   `);
 
-  const projectName = partial.projectName || (await prompt.ask('  Project name: '));
+  printContextSummary(await import('./lib/detect-context.js').then((m) => m.detectContext()));
+
+  const projectName =
+    partial.projectName ||
+    (await prompt.ask('  1) Project name: '));
 
   if (!partial.lane) {
     console.log(`
-  Select a lane:
-    1) Full Stack
-    2) CMS
-    3) Data Solutions
-    4) Customer Management
-    5) Creative & Design
+  2) Lane:
+    1) Full Stack   2) CMS   3) Data   4) CRM   5) Creative
   `);
   }
-  const laneKey = partial.lane ? laneKeyFromLabel(partial.lane) : await prompt.ask('  Lane [1-5]: ');
-  const lane = partial.lane || LANES[laneKey] || 'Full Stack';
-
-  console.log(`
-  Select a provider:
-    1) Cloudflare Workers
-    2) GitHub + Cloudflare
-    3) Local / Self-hosted
-  `);
-  const providerKey = partial.provider
-    ? Object.entries(PROVIDERS).find(([, v]) => v === partial.provider)?.[0] || '1'
-    : await prompt.ask('  Provider [1-3]: ');
-  const provider = partial.provider || PROVIDERS[providerKey] || 'Cloudflare Workers';
+  const laneKey = partial.lane
+    ? partial.lane
+    : LANE_KEYS[await prompt.ask('  Pick lane [1-5]: ')]?.key || 'fullstack';
 
-  if (!partial.agent) {
+  if (!partial.runTarget) {
     console.log(`
-  Select your default Agent Sam:
-    1) Orchestrator    — general purpose, routes to all lanes
-    2) CMS Agent       — pages, sections, assets, publishing workflows
-    3) Data Agent      — database ops, migrations, queries
-    4) CRM Agent       — customer management, contacts, billing
-    5) Creative Agent  — design, 3D, media, content
+  3) Where do you want to run your project?
+
+    1) Local (localhost — start here, no accounts needed)
+    2) Cloudflare (Workers, D1, R2 — deploy when ready)
+    3) GCP (your own Google Cloud project)
   `);
   }
-  const agentKey = partial.agent
-    ? Object.entries(AGENTS).find(([, v]) => v === partial.agent)?.[0] || '1'
-    : await prompt.ask('  Agent [1-5]: ');
-  const agent = partial.agent || AGENTS[agentKey] || 'orchestrator';
-
-  const cfAccountId =
-    partial.cfAccountId !== undefined && partial.cfAccountId !== ''
-      ? partial.cfAccountId
-      : await prompt.ask('  Cloudflare Account ID (enter to skip): ');
-
-  await runInit({
-    projectName,
-    lane,
-    provider,
-    agent,
-    cfAccountId,
-    yes: partial.yes,
-    prompt,
-  });
+  const runTarget = partial.runTarget
+    ? partial.runTarget
+    : RUN_TARGETS[await prompt.ask('  Select [1]: ')] || 'local';
 
+  await runLocalInit({ projectName, lane: laneKey, runTarget, prompt });
   prompt.close();
 }
 
@@ -235,15 +162,7 @@ async function initFromArgs(argv) {
     console.error('\n  ✗ --name is required for non-interactive init.\n');
     process.exit(1);
   }
-  await runInit({
-    projectName: opts.projectName,
-    lane: opts.lane || 'Full Stack',
-    provider: opts.provider || 'Cloudflare Workers',
-    agent: opts.agent || 'orchestrator',
-    cfAccountId: opts.cfAccountId,
-    yes: true,
-    prompt: null,
-  });
+  await runLocalInit({ ...opts, prompt: null });
 }
 
 async function runShellInfo() {
@@ -253,21 +172,14 @@ async function runShellInfo() {
   ║     Agent Sam Shell (Gorilla)     ║
   ╚═══════════════════════════════════╝
 
-  Game-feel terminal UX for SDK installs — HUD, themes, slash commands, PTY bridge.
-
-  Phase 0 prototype: examples/gorilla-shell/
-  Docs:              docs/CLI_SHELL.md
-  Next milestone:    ${next?.label ?? 'PTY connection'}
+  Local PTY: agentsam start-local (ws://127.0.0.1:3099)
+  Next milestone: ${next?.label ?? 'dashboard bridge after deploy'}
 
   Slash commands (${SLASH_COMMANDS.length} registered):
 `);
   for (const row of SLASH_COMMANDS) {
     console.log(`    ${row.cmd.padEnd(14)} ${row.description}`);
   }
-  console.log(`
-  Run the visual prototype:
-    cd examples/gorilla-shell && npm install && npm run dev
-  `);
 }
 
 const command = process.argv[2];
@@ -279,6 +191,15 @@ if (command === '--version' || command === '-v') {
   printHelp();
 } else if (command === 'shell') {
   await runShellInfo();
+} else if (command === 'start-local') {
+  await runStartLocal({});
+} else if (command === 'deploy') {
+  try {
+    await runDeploy(parseDeployArgs(rest));
+  } catch (e) {
+    console.error(`\n  ✗ ${e?.message || e}\n`);
+    process.exit(1);
+  }
 } else if (command === 'init') {
   const hasFlags = rest.some((a) => a.startsWith('--'));
   if (hasFlags) {

package/src/commands/deploy.js

@@ -0,0 +1,146 @@
+/**
+ * Graduate local project to Cloudflare (or GCP hints) — OAuth only here, not at init.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { authenticateViaBrowser } from '../lib/auth.js';
+import { getJson, streamScaffold } from '../lib/core-client.js';
+
+function readConfig(cwd) {
+  const configPath = path.join(cwd, '.agentsam', 'config.json');
+  if (!fs.existsSync(configPath)) {
+    throw new Error('Not an Agent Sam project — run agentsam init first.');
+  }
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+function writeConfig(cwd, config) {
+  const configPath = path.join(cwd, '.agentsam', 'config.json');
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+}
+
+function patchWranglerToml(cwd, cf) {
+  const tomlPath = path.join(cwd, 'wrangler.toml');
+  if (!fs.existsSync(tomlPath)) return;
+  let text = fs.readFileSync(tomlPath, 'utf8');
+  if (cf.account_id) {
+    if (/^account_id\s*=/m.test(text)) {
+      text = text.replace(/^account_id\s*=.*$/m, `account_id = "${cf.account_id}"`);
+    } else {
+      text = text.replace(/(compatibility_date\s*=.*\n)/, `$1account_id = "${cf.account_id}"\n`);
+    }
+  }
+  if (cf.d1_database_id) {
+    text = text.replace(/^database_id\s*=.*$/m, `database_id = "${cf.d1_database_id}"`);
+  }
+  if (cf.kv_namespace_id) {
+    text = text.replace(/^id\s*=.*$/m, `id = "${cf.kv_namespace_id}"`);
+  }
+  fs.writeFileSync(tomlPath, text, 'utf8');
+}
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function runCloudflareDeploy(cwd, config, accountId) {
+  console.log('\n  Cloudflare deploy — browser sign-in + resource provisioning…\n');
+
+  let token = process.env.AGENTSAM_SDK_TOKEN || '';
+  if (!token) {
+    const session = await authenticateViaBrowser();
+    token = session.access_token;
+    console.log(`\n  ✓ Signed in (${session.user_id})\n`);
+  }
+
+  const ctx = await getJson('/api/sdk/context', token);
+  if (!ctx?.cloudflare?.ok) {
+    throw new Error('Connect Cloudflare in IAM Integrations during browser sign-in, then retry.');
+  }
+
+  let complete = null;
+  await streamScaffold(
+    {
+      project_name: config.project,
+      lane: config.lane,
+      hosting: 'cloudflare',
+      provision_only: true,
+      account_id: accountId || undefined,
+      workspace_id: ctx.workspace_id,
+    },
+    token,
+    async (evt) => {
+      if (evt.type === 'log') console.log(`  · ${evt.message}`);
+      else if (evt.type === 'warn') console.log(`  ⚠ ${evt.message}`);
+      else if (evt.type === 'account_selection_required') {
+        console.log('\n  Multiple Cloudflare accounts — re-run with: agentsam deploy --account-id <id>\n');
+        for (const a of evt.accounts || []) console.log(`    ${a.id}  ${a.name || ''}`);
+        throw new Error('cloudflare_account_selection_required');
+      } else if (evt.type === 'error') throw new Error(evt.error || 'deploy failed');
+      else if (evt.type === 'complete') complete = evt;
+    },
+  );
+
+  if (!complete?.cloudflare) throw new Error('deploy incomplete — no cloudflare ids returned');
+
+  patchWranglerToml(cwd, complete.cloudflare);
+  writeConfig(cwd, {
+    ...config,
+    deploy_target: 'cloudflare',
+    cloudflare: complete.cloudflare,
+    deployed_at: new Date().toISOString(),
+  });
+
+  console.log(`
+  ✓ Cloudflare resources provisioned in YOUR account
+  ✓ wrangler.toml updated
+
+  Next:
+    npx wrangler deploy
+    npm run db:migrate -- --remote   # when ready for remote D1
+  `);
+}
+
+/**
+ * @param {{ cwd?: string, target?: string, accountId?: string }} [opts]
+ */
+export async function runDeploy(opts = {}) {
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  const config = readConfig(cwd);
+
+  let target = opts.target || config.deploy_target || 'cloudflare';
+  if (!opts.target && !config.deploy_target) {
+    console.log(`
+  Where do you want to deploy?
+
+    1) Cloudflare (Workers, D1, R2)
+    2) GCP (your Google Cloud project — manual wrangler/container step after)
+  `);
+    const pick = (await ask('  Select [1]: ')).trim() || '1';
+    target = pick === '2' ? 'gcp' : 'cloudflare';
+  }
+
+  if (target === 'gcp') {
+    console.log(`
+  GCP deploy path:
+
+    gcloud auth login --no-browser
+    gcloud config set project YOUR_PROJECT_ID
+    export USER_GCP_PROJECT=YOUR_PROJECT_ID
+
+  Your local project keeps running with npm run dev.
+  Container/Worker deploy scripts are project-specific — add when ready.
+  `);
+    writeConfig(cwd, { ...config, deploy_target: 'gcp' });
+    return;
+  }
+
+  await runCloudflareDeploy(cwd, config, opts.accountId || '');
+}

package/src/commands/start-local.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { startLocalPtyServer } from '../local-pty/server.js';
+
+function readConfig(cwd) {
+  const configPath = path.join(cwd, '.agentsam', 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 12; i += 1) {
+    if (fs.existsSync(path.join(dir, '.agentsam', 'config.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(startDir);
+}
+
+/**
+ * @param {{ cwd?: string, port?: number }} [opts]
+ */
+export async function runStartLocal(opts = {}) {
+  const root = findProjectRoot(opts.cwd || process.cwd());
+  const config = readConfig(root);
+  const port = opts.port ?? config?.pty_port ?? 3099;
+
+  console.log(`
+  Agent Sam — local PTY
+  No Cloudflare · no tunnel · no IAM login
+  `);
+
+  const server = await startLocalPtyServer({ cwd: root, port });
+
+  console.log(`  ✓ PTY listening  ${server.url}`);
+  console.log(`  ✓ Health         ${server.healthUrl}`);
+  console.log(`  ✓ Project root   ${server.cwd}`);
+  console.log(`  ✓ Shell          ${server.shell}`);
+  console.log(`
+  Next:
+    npm run dev          → http://127.0.0.1:${config?.dev_port ?? 8787}
+    npm run db:migrate   → local D1 schema (first run)
+
+  Press Ctrl+C to stop.
+  `);
+
+  const shutdown = async () => {
+    await server.close().catch(() => {});
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  await new Promise(() => {});
+}