@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/lib/scaffold/wizards/cms.js

@@ -9,6 +9,7 @@
  *   - wrangler.toml ready to deploy
  */
 
+import path from 'node:path';
 import {
   text,
   select,
@@ -23,8 +24,100 @@ import pc from 'picocolors';
 import { writeFileTree } from '../writer.js';
 import { cmsTemplates } from '../templates/cms/index.js';
 import { resolveCloudflareAccountId } from '../resolve-cloudflare-account.js';
+import { runApp } from '../../../commands/app.js';
+
+async function runCmsEditorWizard() {
+  note(
+    'Scaffold the reusable client-cms-editor app. SQLite and D1 are authorities; localStorage is cache-only.',
+    'CMS Editor app',
+  );
+
+  const projectName = await text({
+    message: 'Editor project name?',
+    placeholder: 'my-cms-editor',
+    validate(val) {
+      if (!val || val.trim().length === 0) return 'Required.';
+      if (!/^[a-z0-9-]+$/.test(val.trim())) return 'Lowercase letters, numbers, and hyphens only.';
+    },
+  });
+  if (isCancel(projectName)) { cancel('Cancelled.'); process.exit(0); }
+
+  const persistence = await select({
+    message: 'Primary persistence?',
+    options: [
+      {
+        value: 'sqlite',
+        label: 'SQLite — local authority',
+        hint: 'Desktop/offline authority; Local Studio/Tauri adapter target',
+      },
+      {
+        value: 'd1',
+        label: 'Cloudflare D1 — cloud authority',
+        hint: 'Existing /api/cms/* + D1 host path',
+      },
+      {
+        value: 'localStorage',
+        label: 'Browser localStorage — cache only',
+        hint: 'Draft/offline cache; never authoritative publish state',
+      },
+    ],
+  });
+  if (isCancel(persistence)) { cancel('Cancelled.'); process.exit(0); }
+
+  const targetDir = path.resolve(process.cwd(), projectName.trim());
+  const s = spinner();
+  s.start('Scaffolding CMS Editor...');
+  await runApp([
+    'scaffold',
+    'client-cms-editor',
+    targetDir,
+    '--persistence',
+    persistence,
+  ]);
+  s.stop(pc.green(`CMS Editor scaffolded at ${targetDir}`));
+
+  const next = persistence === 'sqlite'
+    ? [
+        `cd ${projectName}`,
+        'npm install',
+        'npm run dev',
+        'Open in Local Studio.app when the Tauri CMS adapter is enabled.',
+      ]
+    : persistence === 'd1'
+      ? [
+          `cd ${projectName}`,
+          'npm install',
+          'agentsam connections setup',
+          'npm run dev',
+        ]
+      : [
+          `cd ${projectName}`,
+          'npm install',
+          'npm run dev',
+          'Configure SQLite or D1 before publish; localStorage remains cache-only.',
+        ];
+  note(next.join('\n'), 'Next steps');
+}
 
 export async function runCmsWizard() {
+  const mode = await select({
+    message: 'What kind of CMS do you want to scaffold?',
+    options: [
+      {
+        value: 'site',
+        label: 'CMS Site',
+        hint: 'Cloudflare Worker + D1 + R2 with nav, pages, and reusable templates',
+      },
+      {
+        value: 'editor',
+        label: 'CMS Editor app',
+        hint: 'Full reusable client-cms-editor source with explicit persistence',
+      },
+    ],
+  });
+  if (isCancel(mode)) { cancel('Cancelled.'); process.exit(0); }
+  if (mode === 'editor') return runCmsEditorWizard();
+
   note('A Cloudflare Worker + D1 + R2 CMS site with reusable page templates.', 'CMS Site');
 
   // ── Step 1: Project name ──────────────────────────────────────────────────

package/src/lib/scaffold/wizards/mcp-server.js

@@ -0,0 +1,61 @@
+import {
+  text,
+  select,
+  confirm,
+  note,
+  isCancel,
+  cancel,
+} from '@clack/prompts';
+import pc from 'picocolors';
+import { createMcpServerProject } from '../mcp-server.js';
+import { listMcpServerPresets } from '../templates/mcp-server/presets.js';
+
+export async function runMcpServerWizard() {
+  const presets = listMcpServerPresets();
+  const preset = await select({
+    message: 'MCP server preset?',
+    options: presets.map((item) => ({
+      value: item.key,
+      label: item.display_name,
+      hint: item.description || 'Portable MCP Worker',
+    })),
+  });
+  if (isCancel(preset)) { cancel('Cancelled.'); process.exit(0); }
+
+  const projectName = await text({
+    message: 'Project name?',
+    placeholder: 'my-mcp-server',
+    validate(value) {
+      if (!String(value || '').trim()) return 'Required.';
+      if (!/^[a-z0-9-]+$/.test(String(value).trim())) {
+        return 'Lowercase letters, numbers, and hyphens only.';
+      }
+    },
+  });
+  if (isCancel(projectName)) { cancel('Cancelled.'); process.exit(0); }
+
+  const confirmed = await confirm({
+    message: `Generate ./${String(projectName).trim()}?`,
+  });
+  if (isCancel(confirmed) || !confirmed) {
+    cancel('Cancelled.');
+    process.exit(0);
+  }
+
+  const result = await createMcpServerProject({
+    projectName: String(projectName).trim(),
+    preset,
+  });
+
+  note([
+    `Generated ${result.file_count} files`,
+    `Manifest: ${result.manifest_path}`,
+    `Transport: ${result.transport} ${result.endpoint_path}`,
+    '',
+    `cd ${String(projectName).trim()}`,
+    'npm install',
+    'npm run dev',
+  ].join('\n'), pc.green('MCP server ready'));
+
+  return result;
+}

package/src/lib/setup/contract.js

@@ -0,0 +1,26 @@
+/**
+ * Agent Sam capability install planner — Homebrew-style orchestration.
+ * Agent Sam owns discover → plan → explain → approve → execute → verify + receipt.
+ * Native package managers own the actual install (brew / apt / winget / npm / …).
+ */
+
+export const SETUP_PLAN_SCHEMA = 'agentsam-setup-plan-v1';
+export const SETUP_RECEIPT_SCHEMA = 'agentsam-setup-receipt-v1';
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   displayName: string,
+ *   description: string,
+ *   risk: 'low'|'medium'|'high',
+ *   requiresApproval: boolean,
+ *   capabilityProvided: string[],
+ *   detect: (ctx: object) => Promise<{ ok: boolean, detail?: string, version?: string }>,
+ *   supportedPlatforms: string[],
+ *   installPlans: Record<string, { provider: string, packages?: string[], commands?: string[], notes?: string[] }>,
+ *   dependencies?: string[],
+ *   mutations?: string[],
+ *   verify: (ctx: object) => Promise<{ ok: boolean, detail?: string, version?: string }>,
+ *   uninstallHint?: () => string,
+ * }} InstallableCapability
+ */

package/src/lib/setup/discover.js

@@ -0,0 +1,116 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+
+async function which(bin) {
+  try {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    const { stdout } = await execFileAsync(cmd, [bin], { timeout: 5000 });
+    const path = String(stdout || '').trim().split(/\r?\n/)[0];
+    return path || null;
+  } catch {
+    return null;
+  }
+}
+
+async function versionOf(bin, args = ['--version']) {
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, { timeout: 8000 });
+    const text = `${stdout || ''}${stderr || ''}`.trim().split(/\n/)[0];
+    return text.slice(0, 120) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover host environment for setup planning.
+ */
+export async function discoverEnvironment(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || os.arch();
+  const hostname = os.hostname().replace(/\.local$/i, '');
+
+  const nodeVersion = process.versions.node;
+  const brew = platform === 'darwin' || platform === 'linux' ? await which('brew') : null;
+  const git = await which('git');
+  const docker = await which('docker');
+  const gcloud = await which('gcloud');
+  const wrangler = await which('wrangler');
+  const magick = (await which('magick')) || (await which('convert'));
+  const potrace = await which('potrace');
+  const ffmpeg = await which('ffmpeg');
+  const svgo = await which('svgo');
+
+  let wranglerVersion = null;
+  if (wrangler) wranglerVersion = await versionOf(wrangler, ['--version']);
+  else {
+    try {
+      wranglerVersion = require('wrangler/package.json').version;
+    } catch {
+      wranglerVersion = null;
+    }
+  }
+
+  const hostLabel =
+    platform === 'darwin' ? 'Mac'
+      : platform === 'win32' ? 'PC'
+        : 'host';
+
+  return {
+    schema_version: 'agentsam-setup-environment-v1',
+    hostname,
+    host_label: hostLabel,
+    platform,
+    arch,
+    os_release: os.release(),
+    node: nodeVersion,
+    tools: {
+      brew: brew ? { path: brew, version: await versionOf('brew', ['--version']) } : null,
+      git: git ? { path: git, version: await versionOf('git', ['--version']) } : null,
+      docker: docker ? { path: docker, version: await versionOf('docker', ['--version']) } : null,
+      gcloud: gcloud ? { path: gcloud, version: await versionOf('gcloud', ['--version']) } : null,
+      wrangler: wrangler || wranglerVersion
+        ? { path: wrangler, version: wranglerVersion }
+        : null,
+      magick: magick ? { path: magick, version: await versionOf(magick, ['--version']) } : null,
+      potrace: potrace ? { path: potrace, version: await versionOf('potrace', ['-v']) } : null,
+      ffmpeg: ffmpeg ? { path: ffmpeg, version: await versionOf('ffmpeg', ['-version']) } : null,
+      svgo: svgo ? { path: svgo, version: await versionOf('svgo', ['--version']) } : null,
+    },
+    env_flags: {
+      AGENTSAM_API_KEY: Boolean(String(env.AGENTSAM_API_KEY || '').trim()),
+      GOOGLE_CLIENT_ID: Boolean(String(env.GOOGLE_CLIENT_ID || '').trim()),
+      GOOGLE_DESKTOP_CLIENT_ID: Boolean(String(env.GOOGLE_DESKTOP_CLIENT_ID || '').trim()),
+    },
+  };
+}
+
+export function renderEnvironment(env) {
+  const lines = [
+    '',
+    '  Environment',
+    `    ${env.host_label} · ${env.hostname}`,
+    `    ${env.platform} ${env.arch} · Node ${env.node}`,
+  ];
+  const rows = [
+    ['Homebrew', env.tools.brew],
+    ['Git', env.tools.git],
+    ['Docker', env.tools.docker],
+    ['Google Cloud CLI', env.tools.gcloud],
+    ['Wrangler', env.tools.wrangler],
+    ['ImageMagick', env.tools.magick],
+    ['Potrace', env.tools.potrace],
+    ['ffmpeg', env.tools.ffmpeg],
+  ];
+  for (const [label, tool] of rows) {
+    lines.push(`    ${tool ? '✓' : '○'} ${label}${tool?.version ? ` · ${String(tool.version).slice(0, 40)}` : ''}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/src/lib/setup/execute.js

@@ -0,0 +1,205 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SETUP_RECEIPT_SCHEMA } from './contract.js';
+import { getCapabilityRecipe } from './recipes.js';
+
+const execFileAsync = promisify(execFile);
+
+function homeDir(options = {}) {
+  return path.resolve(options.home || options.env?.HOME || os.homedir());
+}
+
+export function setupReceiptsDir(options = {}) {
+  return path.join(homeDir(options), '.agentsam', 'receipts');
+}
+
+function runStreaming(command, args, { cwd, env, write } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (buf) => {
+      const text = String(buf);
+      stdout += text;
+      write?.(text);
+    });
+    child.stderr.on('data', (buf) => {
+      const text = String(buf);
+      stderr += text;
+      write?.(text);
+    });
+    child.on('error', (error) => {
+      resolve({ ok: false, code: 1, stdout, stderr: error.message });
+    });
+    child.on('close', (code) => {
+      resolve({ ok: code === 0, code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * Execute approved install plan steps via native providers.
+ */
+export async function executeSetupPlan(plan, options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const env = options.env || process.env;
+  const results = [];
+
+  for (const step of plan.would_install || []) {
+    write(`\n  Installing ${step.capability} via ${step.provider}\n`);
+    let result;
+    if (step.provider === 'homebrew') {
+      if (!plan.platform || (plan.platform !== 'darwin' && plan.platform !== 'linux')) {
+        result = { ok: false, error: 'homebrew_unsupported_platform' };
+      } else {
+        const pkgs = step.packages || [];
+        // Support ["--cask", "gcloud-cli"] style.
+        result = await runStreaming('brew', ['install', ...pkgs], { env, write });
+      }
+    } else if (step.provider === 'npm') {
+      const pkgs = step.packages || [];
+      result = await runStreaming('npm', ['install', '-g', ...pkgs], { env, write });
+    } else if (step.provider === 'winget') {
+      const pkgs = step.packages || [];
+      result = await runStreaming('winget', ['install', '-e', '--id', ...pkgs], { env, write });
+    } else if (step.provider === 'manual') {
+      write('  Manual install required:\n');
+      for (const cmd of step.commands || []) write(`    ${cmd}\n`);
+      for (const note of step.notes || []) write(`    ${note}\n`);
+      result = { ok: false, error: 'manual_required', notes: step.notes || [] };
+    } else {
+      result = { ok: false, error: `unsupported_provider:${step.provider}` };
+    }
+
+    const recipe = getCapabilityRecipe(step.capability);
+    let verified = null;
+    if (result.ok && recipe?.verify) {
+      verified = await recipe.verify({ env });
+      write(verified.ok
+        ? `  ✓ verified ${step.capability}${verified.version ? ` · ${verified.version}` : ''}\n`
+        : `  ✕ verify failed for ${step.capability}\n`);
+    }
+
+    results.push({
+      capability: step.capability,
+      provider: step.provider,
+      packages: step.packages || null,
+      ok: Boolean(result.ok) && (verified ? verified.ok : true),
+      code: result.code ?? null,
+      error: result.error || null,
+      verified,
+    });
+  }
+
+  const receipt = {
+    schema_version: SETUP_RECEIPT_SCHEMA,
+    generated_at: new Date().toISOString(),
+    hostname: plan.hostname,
+    platform: plan.platform,
+    results,
+    ok: results.every((r) => r.ok) || results.length === 0,
+  };
+
+  const dir = setupReceiptsDir(options);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = path.join(dir, `setup-${stamp}.json`);
+  fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+  receipt.path = file;
+  return receipt;
+}
+
+/**
+ * Read-only Google Cloud permission inventory (for setup google.cloud / doctor).
+ */
+export async function collectGooglePermissionInventory(options = {}) {
+  const env = options.env || process.env;
+  const out = {
+    schema_version: 'agentsam-gcp-permission-inventory-v1',
+    generated_at: new Date().toISOString(),
+    auth_list: null,
+    config: null,
+    user_token_scopes: null,
+    projects: null,
+    billing_accounts: null,
+    iam_roles_for_active_user: null,
+    errors: [],
+  };
+
+  try {
+    const { stdout } = await execFileAsync('gcloud', ['auth', 'list', '--format=json'], { env, timeout: 20000 });
+    out.auth_list = JSON.parse(stdout || '[]');
+  } catch (error) {
+    out.errors.push(`auth_list: ${error.message}`);
+  }
+
+  try {
+    const { stdout } = await execFileAsync(
+      'gcloud',
+      ['config', 'list', '--format=json'],
+      { env, timeout: 15000 },
+    );
+    out.config = JSON.parse(stdout || '{}');
+  } catch (error) {
+    out.errors.push(`config: ${error.message}`);
+  }
+
+  try {
+    const { stdout: token } = await execFileAsync('gcloud', ['auth', 'print-access-token'], { env, timeout: 15000 });
+    const t = String(token || '').trim();
+    if (t) {
+      const info = await fetch(`https://oauth2.googleapis.com/tokeninfo?access_token=${encodeURIComponent(t)}`);
+      out.user_token_scopes = await info.json();
+    }
+  } catch (error) {
+    out.errors.push(`tokeninfo: ${error.message}`);
+  }
+
+  try {
+    const { stdout } = await execFileAsync('gcloud', ['projects', 'list', '--format=json'], { env, timeout: 45000 });
+    out.projects = JSON.parse(stdout || '[]');
+  } catch (error) {
+    out.errors.push(`projects: ${error.message}`);
+  }
+
+  try {
+    const { stdout } = await execFileAsync('gcloud', ['billing', 'accounts', 'list', '--format=json'], { env, timeout: 30000 });
+    out.billing_accounts = JSON.parse(stdout || '[]');
+  } catch (error) {
+    out.errors.push(`billing: ${error.message}`);
+  }
+
+  const project = out.config?.core?.project;
+  const account = out.config?.core?.account;
+  if (project && account && !String(account).includes('.gserviceaccount.com')) {
+    try {
+      const { stdout } = await execFileAsync(
+        'gcloud',
+        [
+          'projects', 'get-iam-policy', project,
+          '--flatten=bindings[].members',
+          `--filter=bindings.members:user:${account}`,
+          '--format=json',
+        ],
+        { env, timeout: 45000 },
+      );
+      const rows = JSON.parse(stdout || '[]');
+      out.iam_roles_for_active_user = {
+        project,
+        account,
+        roles: [...new Set((rows || []).map((r) => r.bindings?.role).filter(Boolean))],
+      };
+    } catch (error) {
+      out.errors.push(`iam: ${error.message}`);
+    }
+  }
+
+  return out;
+}

package/src/lib/setup/planner.js

@@ -0,0 +1,134 @@
+import { SETUP_PLAN_SCHEMA } from './contract.js';
+import { getCapabilityRecipe, listCapabilityRecipes } from './recipes.js';
+
+function platformKey(platform) {
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'win32') return 'win32';
+  return 'linux';
+}
+
+/**
+ * Build an install plan for requested capability IDs (or all known recipes).
+ */
+export async function buildSetupPlan(options = {}) {
+  const environment = options.environment;
+  if (!environment) throw new Error('environment_required');
+  const requested = Array.isArray(options.capabilityIds) && options.capabilityIds.length
+    ? options.capabilityIds
+    : listCapabilityRecipes().map((r) => r.id);
+
+  const capabilities = [];
+  const wouldInstall = [];
+  const providers = new Set();
+  const mutations = new Set();
+  let blocked = false;
+
+  for (const id of requested) {
+    const recipe = getCapabilityRecipe(id);
+    if (!recipe) {
+      capabilities.push({ id, ok: false, error: 'unknown_capability' });
+      continue;
+    }
+    const detection = await recipe.detect({ environment });
+    const plan = recipe.installPlans[platformKey(environment.platform)] || null;
+    const entry = {
+      id: recipe.id,
+      displayName: recipe.displayName,
+      description: recipe.description,
+      risk: recipe.risk,
+      requiresApproval: recipe.requiresApproval !== false,
+      capabilityProvided: recipe.capabilityProvided || [],
+      detected: detection,
+      installPlan: plan,
+      mutations: recipe.mutations || [],
+      uninstallHint: recipe.uninstallHint?.() || null,
+    };
+    capabilities.push(entry);
+    if (detection.ok) continue;
+    if (!plan) {
+      blocked = true;
+      entry.error = 'no_install_plan_for_platform';
+      continue;
+    }
+    providers.add(plan.provider);
+    for (const m of entry.mutations) mutations.add(m);
+    if (plan.packages?.length) {
+      wouldInstall.push({
+        capability: recipe.id,
+        provider: plan.provider,
+        packages: plan.packages,
+        notes: plan.notes || [],
+      });
+    } else if (plan.commands?.length) {
+      wouldInstall.push({
+        capability: recipe.id,
+        provider: plan.provider,
+        commands: plan.commands,
+        notes: plan.notes || [],
+      });
+    }
+  }
+
+  return {
+    schema_version: SETUP_PLAN_SCHEMA,
+    ok: !blocked,
+    hostname: environment.hostname,
+    host_label: environment.host_label,
+    platform: environment.platform,
+    capabilities,
+    would_install: wouldInstall,
+    providers: [...providers],
+    mutations: [...mutations],
+    trust_notes: [
+      'Agent Sam will not silently trust third-party package taps/repos.',
+      'No shell profiles, project files, or provider credentials are modified unless a recipe explicitly lists them and you approve.',
+    ],
+  };
+}
+
+export function renderSetupPlan(plan) {
+  const lines = [
+    '',
+    '  Agent Sam Setup',
+    '  ────────────────────────────────────────',
+    '',
+    `  Host  ${plan.host_label} · ${plan.hostname} · ${plan.platform}`,
+    '',
+    '  Capabilities',
+  ];
+  for (const cap of plan.capabilities) {
+    const mark = cap.detected?.ok ? '✓' : '○';
+    const ver = cap.detected?.version ? ` · ${String(cap.detected.version).slice(0, 36)}` : '';
+    lines.push(`    ${mark} ${cap.displayName || cap.id}${ver}`);
+    if (!cap.detected?.ok && cap.detected?.detail) {
+      lines.push(`      ${cap.detected.detail}`);
+    }
+  }
+  lines.push('');
+  if (!plan.would_install.length) {
+    lines.push('  Suggested installation');
+    lines.push('    Nothing missing from the requested set.');
+    lines.push('');
+    return lines.join('\n');
+  }
+  lines.push('  Suggested installation');
+  lines.push(`    Would install ${plan.would_install.length} capability package group(s):`);
+  for (const row of plan.would_install) {
+    const pkgs = (row.packages || row.commands || []).join(' ');
+    lines.push(`      ${row.provider.padEnd(12)} ${pkgs}`);
+  }
+  lines.push('');
+  lines.push('  Would use');
+  for (const p of plan.providers) lines.push(`    ${p}`);
+  lines.push('');
+  lines.push('  Would modify');
+  if (!plan.mutations.length) {
+    lines.push('    no project files / shell profiles / credentials (package install only)');
+  } else {
+    for (const m of plan.mutations) lines.push(`    • ${m}`);
+  }
+  lines.push('');
+  for (const note of plan.trust_notes || []) lines.push(`  Note  ${note}`);
+  lines.push('');
+  return lines.join('\n');
+}