@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/lib/init-options.js

@@ -0,0 +1,192 @@
+/**
+ * Init / create pickers — real presets, scaffolds, and apps (not aspirational lanes).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listPresets } from '../presets/index.js';
+import { listAppManifests } from '../commands/app.js';
+
+const SDK_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const INSTALLABLE_PRODUCT_CACHE = path.join('registry', 'cms-rust-machine-20260928', 'installable-products.json');
+
+export const SCAFFOLD_WIZARDS = Object.freeze([
+  {
+    value: 'scaffold:cms',
+    kind: 'scaffold',
+    scaffold: 'cms',
+    label: 'CMS Site (Worker + D1 + R2)',
+    hint: 'Proven Cloudflare CMS scaffold with pages, nav, and templates',
+  },
+  {
+    value: 'scaffold:worker-api',
+    kind: 'scaffold',
+    scaffold: 'worker-api',
+    label: 'Worker API',
+    hint: 'Bare Cloudflare Worker with typed routes and D1',
+  },
+]);
+
+export const RUN_TARGET_OPTIONS = Object.freeze([
+  {
+    value: 'local',
+    label: 'This machine',
+    hint: 'SQLite + local API; no cloud account required',
+  },
+  {
+    value: 'cloudflare',
+    label: 'Cloudflare Workers',
+    hint: 'OAuth via Local Studio / agentsam connections — Workers, D1, R2',
+  },
+  {
+    value: 'tauri',
+    label: 'Local Studio desktop',
+    hint: 'Bundled Tauri app + local SQLite; offline-capable product runtime',
+  },
+  {
+    value: 'gcp',
+    label: 'Google Cloud',
+    hint: 'agentsam google-cloud OAuth / gcloud — VMs, Cloud Run, Workstations',
+  },
+  {
+    value: 'docker',
+    label: 'Docker',
+    hint: 'agentsam dockerize — proven compose/build/run on this host',
+  },
+]);
+
+function appReady(manifest = {}) {
+  const runtime = manifest.runtime || {};
+  return (
+    runtime.source_scaffold === 'ready'
+    || runtime.local_preview === 'ready'
+    || runtime.cloudflare === 'ready'
+  );
+}
+
+export function listInstallableProductCache(root = SDK_ROOT) {
+  const file = path.join(root || SDK_ROOT, INSTALLABLE_PRODUCT_CACHE);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(parsed?.products) ? parsed.products : [];
+  } catch {
+    return [];
+  }
+}
+
+function actionChoice(action = {}) {
+  if (action.kind === 'app' && action.id) return `app:${action.id}`;
+  if (action.kind === 'scaffold' && action.id) return `scaffold:${action.id}`;
+  return null;
+}
+
+export function getInstallableProductChoice(id, root = SDK_ROOT) {
+  return listInstallableProductCache(root).find((row) => row.slug === id) || null;
+}
+
+export function listInitProjectTypeOptions(root) {
+  const presets = listPresets().map((preset) => ({
+    value: `preset:${preset.id}`,
+    kind: 'preset',
+    presetId: preset.id,
+    lane: preset.lane || preset.id,
+    label: preset.id === 'cms' ? 'CMS app (local AgentSam)' : preset.id === 'prototype'
+      ? 'Prototype (minimal)'
+      : preset.id === 'data'
+        ? 'Data app'
+        : 'Full Stack app',
+    hint: preset.description || preset.id,
+  }));
+
+  const apps = listAppManifests(root)
+    .filter((row) => appReady(row.manifest || {}))
+    .map((row) => {
+      const runtime = row.manifest?.runtime || {};
+      const cf = runtime.cloudflare === 'ready' ? ' · Cloudflare ready' : '';
+      return {
+        value: `app:${row.id}`,
+        kind: 'app',
+        appId: row.id,
+        label: row.name || row.id,
+        hint: `agentsam app scaffold ${row.id}${cf}`,
+        hasScaffold: Boolean(row.commands?.scaffold || row.manifest?.commands?.scaffold),
+      };
+    });
+
+  const represented = new Set([
+    ...SCAFFOLD_WIZARDS.map((row) => row.value),
+    ...apps.map((row) => row.value),
+  ]);
+  const products = listInstallableProductCache(root || SDK_ROOT)
+    .filter((row) => row?.slug && row?.action)
+    .filter((row) => {
+      const action = actionChoice(row.action);
+      return !action || !represented.has(action);
+    })
+    .map((row) => ({
+      value: `product:${row.slug}`,
+      kind: 'product',
+      productId: row.slug,
+      label: row.label || row.slug,
+      hint: row.hint || `${row.kind || 'product'} · ${row.status || 'unknown'}`,
+      action: row.action,
+    }));
+
+  return [...presets, ...SCAFFOLD_WIZARDS, ...products, ...apps];
+}
+
+export function parseProjectTypeChoice(value) {
+  const raw = String(value || '').trim();
+  if (raw.startsWith('preset:')) {
+    return { kind: 'preset', id: raw.slice('preset:'.length) };
+  }
+  if (raw.startsWith('scaffold:')) {
+    return { kind: 'scaffold', id: raw.slice('scaffold:'.length) };
+  }
+  if (raw.startsWith('app:')) {
+    return { kind: 'app', id: raw.slice('app:'.length) };
+  }
+  if (raw.startsWith('product:')) {
+    return { kind: 'product', id: raw.slice('product:'.length) };
+  }
+  // Back-compat for --lane fullstack|cms|…
+  if (raw) return { kind: 'preset', id: raw };
+  return null;
+}
+
+/** Concrete next commands after init — not "decide later". */
+export function guidanceForRunTarget(runTarget, { projectName } = {}) {
+  const name = projectName || '.';
+  if (runTarget === 'cloudflare') {
+    return [
+      'agentsam connections setup          # Cloudflare OAuth callback + Local Studio connector',
+      'agentsam cloudflare                 # Workers / bindings capabilities',
+      `cd ${name} && npm run deploy        # Graduate this project to a Worker when ready`,
+    ];
+  }
+  if (runTarget === 'tauri') {
+    return [
+      'agentsam app doctor local-studio     # Verify the bundled desktop product contract',
+      `cd ${name} && npm install           # Install the scaffolded app workspace`,
+      'Open AgentSam Local Studio.app       # Desktop authority uses local SQLite when the adapter supports it',
+    ];
+  }
+  if (runTarget === 'gcp') {
+    return [
+      'agentsam google-cloud doctor        # OAuth + gcloud readiness',
+      'agentsam google-cloud auth          # Sign in / refresh Google user OAuth',
+      'agentsam compute                   # List VMs / Cloud Run / Workstations targets',
+    ];
+  }
+  if (runTarget === 'docker') {
+    return [
+      `cd ${name} && npx agentsam dockerize   # Generate Dockerfile + compose from proven templates`,
+      'docker compose up --build',
+    ];
+  }
+  return [
+    'npm install && npm run smoke && npm run dev',
+    'npx agentsam',
+    'Optional: npm run pty · npm run ollama:setup',
+  ];
+}

package/src/lib/local-scaffold.js

@@ -1,6 +1,5 @@
 /**
- * Local-first scaffold — no IAM, no Cloudflare, no OAuth.
- * Prove the project locally; `agentsam deploy` adds cloud adapters only when requested.
+ * Local-first scaffold — prove locally, then graduate with real Cloudflare / GCP / Docker tooling.
  */
 
 import pkg from '../../package.json' with { type: 'json' };
@@ -40,9 +39,11 @@ const RUN_TARGETS = {
   '1': 'local',
   '2': 'cloudflare',
   '3': 'gcp',
+  '4': 'docker',
   local: 'local',
   cloudflare: 'cloudflare',
   gcp: 'gcp',
+  docker: 'docker',
 };
 
 export { LANE_KEYS, LANE_LABELS, RUN_TARGETS };
@@ -184,10 +185,13 @@ npm run ollama:status           # probe local Ollama + models
 
 The local SQLite database lives at \`.agentsam/data/agentsam.sqlite\` and is initialized from \`db/schema.sql\`.
 
-When you're intentionally ready to add cloud infrastructure:
+When you're ready to run on Cloudflare, GCP, or Docker (all supported end-to-end):
 
 \`\`\`bash
-npx agentsam deploy
+npx agentsam connections setup   # Cloudflare OAuth (Local Studio)
+npx agentsam google-cloud doctor # GCP OAuth / gcloud
+npx agentsam dockerize           # Containerize this project
+npx agentsam deploy              # Cloudflare Worker graduation
 \`\`\`
 `,
     },
@@ -416,7 +420,16 @@ No Worker or cloud account is required for local development.
 npm run deploy
 \`\`\`
 
-Selected future deploy target: **${runTarget}**. Cloud-specific adapters and credentials belong to deploy time, not local init.
+Selected run target: **${runTarget}**.
+
+| Target | Proven path |
+| --- | --- |
+| local | SQLite + local API on this host |
+| cloudflare | Local Studio CF OAuth · \`agentsam connections\` · \`agentsam deploy\` |
+| gcp | \`agentsam google-cloud\` OAuth / gcloud |
+| docker | \`agentsam dockerize\` compose/build/run |
+
+Cloud adapters and credentials are configured with those commands — not left as aspirational flags.
 `,
     },
   ];
@@ -432,6 +445,35 @@ export function buildLocalScaffoldMeta(body, sdkVersion = pkg.version) {
   const laneLabel = LANE_LABELS[laneKey] || 'Full Stack';
   const agent = AGENT_FOR_LANE[laneKey] || 'orchestrator';
   const runTarget = normalizeRunTarget(body.runTarget || body.run_target || 'local');
+  const nextByTarget = {
+    local: [
+      'npm install',
+      'npm run smoke',
+      'npm run status',
+      'npm run dev',
+      'npx agentsam',
+      'Optional: npm run pty · npm run ollama:setup',
+    ],
+    cloudflare: [
+      'npm install',
+      'npm run smoke',
+      'agentsam connections setup',
+      'agentsam cloudflare',
+      'npm run deploy',
+    ],
+    gcp: [
+      'npm install',
+      'npm run smoke',
+      'agentsam google-cloud doctor',
+      'agentsam google-cloud auth',
+      'agentsam compute',
+    ],
+    docker: [
+      'npm install',
+      'npx agentsam dockerize',
+      'docker compose up --build',
+    ],
+  };
 
   return {
     projectName,
@@ -440,16 +482,6 @@ export function buildLocalScaffoldMeta(body, sdkVersion = pkg.version) {
     agent,
     runTarget,
     files: buildLocalScaffoldFiles({ projectName, laneKey, laneLabel, agent, runTarget, sdkVersion }),
-    next_steps: [
-      'npm install',
-      'npm run smoke',
-      'npm run status',
-      'npm run dev',
-      'npx agentsam',
-      'npm run db:status',
-      'Optional free/local models: npm run ollama:setup',
-      'Optional: npm run pty',
-      'When ready for cloud: npm run deploy',
-    ],
+    next_steps: nextByTarget[runTarget] || nextByTarget.local,
   };
 }

package/src/lib/provider-command-remediation.js

@@ -0,0 +1,308 @@
+/**
+ * Deterministic provider-command remediation — no LLM.
+ * Turns provider-native failures into next-step cards with copyable commands.
+ */
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function argvLine(argv = []) {
+  return argv.map((part) => (/\s/.test(String(part)) ? JSON.stringify(String(part)) : String(part))).join(' ');
+}
+
+/** @typedef {{ id: string, title: string, command?: string, recommended?: boolean, docs_url?: string }} RemediationAction */
+
+/**
+ * @typedef {object} RemediationCard
+ * @property {string} schema_version
+ * @property {string} provider
+ * @property {string} kind
+ * @property {string} title
+ * @property {string} summary
+ * @property {string[]} ran
+ * @property {string[]} [notes]
+ * @property {RemediationAction[]} actions
+ * @property {{ enter?: string, h?: string, o?: string, c?: string, p?: string, esc?: string }} keys
+ */
+
+/**
+ * Google Distributed Cloud Edge ≠ Compute Engine IAM.
+ * Acceptance fixture from the Mac ExecOS failure.
+ * @param {{ argv?: string[], projectId?: string, instance?: string, zone?: string }} [ctx]
+ * @returns {RemediationCard|null}
+ */
+export function remediateGcloudEdgeServiceAccountKey(ctx = {}) {
+  const argv = Array.isArray(ctx.argv) ? ctx.argv.map(String) : [];
+  const joined = argv.join(' ').toLowerCase();
+  const looksLike =
+    /edge-cloud/.test(joined) &&
+    /service-accounts?/.test(joined) &&
+    /\bkeys?\b/.test(joined) &&
+    /\bcreate\b/.test(joined);
+  if (!looksLike && !ctx.force) return null;
+
+  const projectId = clean(ctx.projectId) || clean(ctx.env?.CLOUDSDK_CORE_PROJECT) || '$PROJECT_ID';
+  const instance = clean(ctx.instance) || 'iam-tunnel';
+  const zone = clean(ctx.zone) || 'us-central1-f';
+  const saEmail = clean(ctx.serviceAccount) || `agentsam-env-controller@${projectId === '$PROJECT_ID' ? 'PROJECT_ID' : projectId}.iam.gserviceaccount.com`;
+
+  return Object.freeze({
+    schema_version: 'agentsam-remediation-v1',
+    provider: 'google_cloud',
+    kind: 'command_incomplete_wrong_family',
+    title: 'Command incomplete',
+    summary:
+      'This command belongs to Google Distributed Cloud Edge. Your current runtime is a Compute Engine VM / standard GCP project.',
+    ran: Object.freeze([argvLine(argv.length ? argv : ['gcloud', 'edge-cloud', 'service-accounts', 'keys', 'create'])]),
+    notes: Object.freeze([
+      'edge-cloud manages GDCE resources, not project IAM service accounts.',
+      'Prefer OAuth / ADC for Local Studio connections over downloadable JSON keys.',
+    ]),
+    actions: Object.freeze([
+      Object.freeze({
+        id: 'inspect_vm_sa',
+        title: "Inspect the VM's current service account",
+        recommended: true,
+        command: `gcloud compute instances describe ${instance} --zone=${zone} --project=${projectId} --format='yaml(serviceAccounts,name,status)'`,
+      }),
+      Object.freeze({
+        id: 'list_iam_sas',
+        title: 'List normal Google IAM service accounts',
+        command: `gcloud iam service-accounts list --project=${projectId} --format='table(email,displayName,disabled)'`,
+      }),
+      Object.freeze({
+        id: 'create_iam_key',
+        title: 'Create a standard service-account key (avoid when ADC works)',
+        command: `gcloud iam service-accounts keys create ./sa-key.json --iam-account=${saEmail} --project=${projectId}`,
+      }),
+      Object.freeze({
+        id: 'oauth_connection',
+        title: 'Use OAuth instead (recommended for Local Studio)',
+        command: 'agentsam connections',
+        docs_url: 'https://cloud.google.com/docs/authentication',
+      }),
+    ]),
+    keys: Object.freeze({
+      enter: 'recommended',
+      h: 'help',
+      o: 'open provider docs',
+      c: 'copy command',
+      esc: 'cancel',
+    }),
+  });
+}
+
+/**
+ * @param {{ operation?: string, connection?: string, projectId?: string, permission?: string }} [ctx]
+ * @returns {RemediationCard}
+ */
+export function remediateGcloudPermissionDenied(ctx = {}) {
+  const operation = clean(ctx.operation) || 'compute.instances.list';
+  const connection = clean(ctx.connection) || 'Google Cloud';
+  const projectId = clean(ctx.projectId) || '$PROJECT_ID';
+  const permission = clean(ctx.permission) || operation;
+
+  return Object.freeze({
+    schema_version: 'agentsam-remediation-v1',
+    provider: 'google_cloud',
+    kind: 'permission_denied',
+    title: 'Permission missing',
+    summary: `Operation ${operation} was denied for the active Google Cloud connection.`,
+    ran: Object.freeze([]),
+    notes: Object.freeze([
+      `Connection: ${connection}`,
+      `Required permission (when known): ${permission}`,
+    ]),
+    actions: Object.freeze([
+      Object.freeze({
+        id: 'reauth',
+        title: 'Re-authorize Google Cloud',
+        recommended: true,
+        command: 'gcloud auth login',
+      }),
+      Object.freeze({
+        id: 'show_permission',
+        title: 'Show required permission',
+        command: `gcloud projects get-iam-policy ${projectId} --flatten='bindings[].members' --filter='bindings.role:roles/' --format='table(bindings.role)'`,
+      }),
+      Object.freeze({
+        id: 'open_iam',
+        title: 'Open IAM / consent page',
+        docs_url: `https://console.cloud.google.com/iam-admin/iam?project=${encodeURIComponent(projectId)}`,
+        command: `open "https://console.cloud.google.com/iam-admin/iam?project=${projectId}"`,
+      }),
+      Object.freeze({
+        id: 'copy_probe',
+        title: 'Copy read-only probe command',
+        command: `gcloud compute instances list --project=${projectId} --format='table(name,zone,status,machineType)'`,
+      }),
+    ]),
+    keys: Object.freeze({
+      enter: 'Re-authorize Google Cloud',
+      p: 'Show required permission',
+      o: 'Open IAM/consent page',
+      c: 'Copy gcloud command',
+      esc: 'cancel',
+    }),
+  });
+}
+
+/**
+ * GitHub env token shadows healthy keyring OAuth.
+ * @param {{ envTokenPresent?: boolean, keyringHealthy?: boolean, scopes?: string[] }} [ctx]
+ * @returns {RemediationCard|null}
+ */
+export function remediateGithubTokenShadow(ctx = {}) {
+  if (!ctx.envTokenPresent || ctx.keyringHealthy !== true) return null;
+  return Object.freeze({
+    schema_version: 'agentsam-remediation-v1',
+    provider: 'github',
+    kind: 'credential_shadow',
+    title: 'Stale GITHUB_TOKEN shadows working keyring login',
+    summary:
+      'macOS keyring OAuth is healthy, but GITHUB_TOKEN / GH_TOKEN in the environment takes precedence and returns HTTP 401.',
+    ran: Object.freeze([]),
+    notes: Object.freeze([
+      ...(Array.isArray(ctx.scopes) && ctx.scopes.length
+        ? [`Keyring scopes: ${ctx.scopes.join(', ')}`]
+        : []),
+      'Prefer GitHub App installation for customer products; developer Macs may keep gh OAuth.',
+    ]),
+    actions: Object.freeze([
+      Object.freeze({
+        id: 'unset',
+        title: 'Remove stale shell override for this session',
+        recommended: true,
+        command: 'unset GITHUB_TOKEN GH_TOKEN',
+      }),
+      Object.freeze({
+        id: 'status',
+        title: 'Confirm keyring auth',
+        command: 'gh auth status',
+      }),
+      Object.freeze({
+        id: 'whoami',
+        title: 'Confirm API identity',
+        command: "gh api user --jq '{login: .login, type: .type}'",
+      }),
+      Object.freeze({
+        id: 'find_source',
+        title: 'Inspect where the override originates',
+        command: "rg -n 'GITHUB_TOKEN|GH_TOKEN' ~/.zshrc ~/.zprofile ~/.profile ~/.agentsam 2>/dev/null",
+      }),
+    ]),
+    keys: Object.freeze({
+      enter: 'inspect source',
+      c: 'copy command',
+      esc: 'cancel',
+    }),
+  });
+}
+
+/**
+ * Classify a failed argv / stderr blob into a remediation card when possible.
+ * @param {{ argv?: string[], stderr?: string, stdout?: string, env?: NodeJS.ProcessEnv, projectId?: string }} input
+ * @returns {RemediationCard|null}
+ */
+export function remediateProviderFailure(input = {}) {
+  const argv = Array.isArray(input.argv) ? input.argv.map(String) : [];
+  const text = `${argv.join(' ')}\n${clean(input.stderr)}\n${clean(input.stdout)}`;
+
+  const edge = remediateGcloudEdgeServiceAccountKey({
+    argv,
+    projectId: input.projectId,
+    env: input.env,
+    force: /edge-cloud/.test(text) && /service-account/.test(text),
+  });
+  if (edge) return edge;
+
+  if (/PERMISSION_DENIED|permission.?denied|403 Forbidden/i.test(text)) {
+    const opMatch = text.match(/\b([a-z]+(?:\.[a-z]+){1,4})\b/i);
+    return remediateGcloudPermissionDenied({
+      operation: opMatch?.[1],
+      projectId: input.projectId,
+      connection: 'Google Cloud',
+    });
+  }
+
+  if (/GITHUB_TOKEN|GH_TOKEN/i.test(text) && /401|invalid|Bad credentials/i.test(text)) {
+    return remediateGithubTokenShadow({
+      envTokenPresent: true,
+      keyringHealthy: true,
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Human-readable card (never prints secrets).
+ * @param {RemediationCard} card
+ * @returns {string}
+ */
+export function renderRemediationCard(card) {
+  if (!card) return '';
+  const lines = [
+    '',
+    `  Agent Sam · ${providerLabel(card.provider)}`,
+    '',
+    `  ✕ ${card.title}`,
+    '',
+  ];
+  if (card.ran?.length) {
+    lines.push('  You ran:');
+    for (const ran of card.ran) lines.push(`    ${ran}`);
+    lines.push('');
+  }
+  if (card.summary) {
+    lines.push(`  ${card.summary}`);
+    lines.push('');
+  }
+  if (card.notes?.length) {
+    for (const note of card.notes) lines.push(`  ${note}`);
+    lines.push('');
+  }
+  if (card.actions?.length) {
+    lines.push('  Likely intent');
+    lines.push('');
+    card.actions.forEach((action, index) => {
+      const mark = action.recommended ? '★' : ' ';
+      lines.push(`  ${mark} ${index + 1}  ${action.title}`);
+      if (action.command) lines.push(`       ${action.command}`);
+      if (action.docs_url) lines.push(`       docs: ${action.docs_url}`);
+      lines.push('');
+    });
+  }
+  const keys = card.keys || {};
+  const keyBits = [];
+  if (keys.enter) keyBits.push(`[enter] ${keys.enter}`);
+  if (keys.h) keyBits.push(`[h] ${keys.h}`);
+  if (keys.p) keyBits.push(`[p] ${keys.p}`);
+  if (keys.o) keyBits.push(`[o] ${keys.o}`);
+  if (keys.c) keyBits.push(`[c] ${keys.c}`);
+  if (keys.esc) keyBits.push(`[esc] ${keys.esc}`);
+  if (keyBits.length) {
+    lines.push(`  ${keyBits.join('  ')}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function providerLabel(provider) {
+  switch (clean(provider)) {
+    case 'google_cloud':
+      return 'Google Cloud';
+    case 'github':
+      return 'GitHub';
+    case 'cloudflare':
+      return 'Cloudflare';
+    default:
+      return clean(provider) || 'Provider';
+  }
+}
+
+export function recommendedCommand(card) {
+  const hit = (card?.actions || []).find((row) => row.recommended && row.command);
+  return hit?.command || (card?.actions || []).find((row) => row.command)?.command || null;
+}