@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/src/commands/brand.js

@@ -1,5 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import {
+  cancel,
+  confirm,
+  intro,
+  isCancel,
+  note,
+  outro,
+  select,
+  text,
+} from '@clack/prompts';
 import { repositorySnapshot } from '../capabilities/index.js';
 import {
   brandScan,
@@ -9,13 +19,41 @@ import {
   brandGoapActions,
   brandWorldFromPlan,
   brandGoalFromPlan,
+  runBrandAssetCommand,
+  runBrandPromoteWizard,
 } from '../../packages/agentsam-brand/src/index.js';
 import { planGoap, GOAP_ENGINE } from '../sam/planning/goap.js';
 import { suggestNextActions } from '../progression/index.js';
 import { createRuntimeActivity } from '../ui/runtime-activity.js';
 
+const ASSET_ACTIONS = new Set([
+  'inspect',
+  'derive',
+  'assets',
+  'promote',
+  'publish',
+  'verify',
+  'presets',
+  'pack',
+  'preview',
+  'ingest',
+  'build',
+  'templates',
+  'roles',
+  'optimize',
+  'processors',
+]);
+
 function parseArgs(argv = []) {
-  const out = { json: false, cwd: process.cwd(), dryRun: false, goap: false, write: false, positionals: [] };
+  const out = {
+    json: false,
+    cwd: process.cwd(),
+    dryRun: false,
+    goap: false,
+    write: false,
+    positionals: [],
+    passthrough: [...argv],
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--json') out.json = true;
@@ -67,25 +105,44 @@ export async function runBrand(argv = []) {
   const action = sub || 'summary';
 
   if (action === 'help' || action === '--help') {
-    console.log(`usage: agentsam brand [summary|scan|resolve|inspect|plan|apply|verify] [options]
+    console.log(`usage: agentsam brand [summary|scan|resolve|inspect|plan|apply|assets|promote|ingest|build|pack|preview|publish|verify|derive|optimize|processors|presets|templates|roles]
 
-  summary (default)   Short brand intelligence overview
-  scan                Deterministic evidence extraction (no model)
-  resolve             Cluster tokens into inferred roles
-  inspect [conflicts] Show conflicts / component families
-  plan [--goap]       Normalization plan (preserve → improve)
-  apply --dry-run     Mutation stub (writes require future approval)
-  verify              Stub verification gate
+Brand intelligence:
+  summary|scan|resolve|inspect|plan|apply
 
-Options:
-  --json --cwd <path> --snapshot-file <file> --write
+Brand compiler (v2 — brand.pack.json is source of truth):
+  agentsam brand ingest ./exports --brand acme --template product-saas
+  agentsam brand build --from .agentsam/brand/packs/acme
+  agentsam brand preview --from .agentsam/brand/dist/acme
+  agentsam brand optimize ./hero.png --role hero.landscape --target web
+  agentsam brand processors
+  agentsam brand templates
+  agentsam brand roles
+
+Legacy single-asset (still valid):
+  agentsam brand pack --brand acme --asset app-icon --source ./master.png --preset app-icon --out ./acme.zip
+  agentsam brand promote --brand acme --asset logo --source - --preset logo
+  agentsam brand presets
+
+Encoders (sharp / squoosh binary / native / CF) are processors — never the CLI contract.
+ZIP / studio / production publish are compiled representations of brand.pack.json.
 `);
     return;
   }
 
+  // Asset/promote surface → shared controller (also used by agentsam-brand bin)
+  if (ASSET_ACTIONS.has(action)) {
+    const code = await runBrandAssetCommand(argv, {
+      runWizard: runBrandPromoteWizard,
+      prompts: { intro, outro, cancel, isCancel, select, text, confirm, note },
+    });
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+    return;
+  }
+
   if (action === 'apply') {
     if (!opts.dryRun) {
-      console.error('brand apply requires --dry-run until mutations are gated (side_effects: repository-write)');
+      console.error('brand apply requires --dry-run until mutations are gated');
       process.exitCode = 2;
       return;
     }
@@ -99,17 +156,6 @@ Options:
     return;
   }
 
-  if (action === 'verify') {
-    const out = {
-      capability: 'brand.verify',
-      status: 'stub',
-      message: 'Verify will re-scan and diff against .agentsam/brand/contract.json',
-    };
-    if (opts.json) console.log(JSON.stringify(out, null, 2));
-    else console.log(out.message);
-    return;
-  }
-
   const tty = process.stdout.isTTY && !opts.json;
   const activity = tty ? createRuntimeActivity({ label: 'Brand intelligence' }) : null;
   const onEvent = (ev) => {
@@ -123,11 +169,7 @@ Options:
     const snapshot = await loadSnapshot(opts);
 
     if (action === 'summary' || action === 'scan' || action === 'resolve' || action === 'inspect' || action === 'plan') {
-      const scan = await brandScan({
-        cwd: opts.cwd,
-        snapshot,
-        onEvent,
-      });
+      const scan = await brandScan({ cwd: opts.cwd, snapshot, onEvent });
 
       if (action === 'scan') {
         const enriched = attachProgression('brand.scan', scan, opts.json);
@@ -137,8 +179,6 @@ Options:
           console.log(`\nBrand scan complete · ${scan.repository.snapshot_id}`);
           console.log(`  colors     ${scan.tokens.colors.length}`);
           console.log(`  conflicts  ${scan.conflicts.length}`);
-          console.log(`  css files  ${scan.sources.css}`);
-          console.log(`  components ${scan.sources.components}`);
           console.log(`  hash       ${scan.content_hash}`);
         }
         return;
@@ -152,28 +192,21 @@ Options:
         else {
           console.log(`\nBrand resolve · ${Object.keys(resolved.resolved.colors).length} color roles`);
           console.log(`  ambiguities ${resolved.ambiguities.length}`);
-          for (const a of resolved.ambiguities.slice(0, 5)) {
-            console.log(`  ? ${a.question}`);
-          }
         }
         return;
       }
 
       if (action === 'inspect') {
+        // brand intelligence inspect (conflicts) — asset inspect is ASSET_ACTIONS
         const focus = rest[0] || 'conflicts';
         const payload = focus === 'components'
           ? { capability: 'brand.inspect', focus, components: scan.components, patterns: scan.patterns }
           : { capability: 'brand.inspect', focus, conflicts: scan.conflicts, colors: scan.tokens.colors.slice(0, 20) };
         if (opts.json) console.log(JSON.stringify(payload, null, 2));
-        else if (focus === 'components') {
-          console.log('\nComponent families');
-          for (const [k, v] of Object.entries(scan.components).slice(0, 20)) {
-            console.log(`  ${k} ×${v.count}`);
-          }
-        } else {
+        else {
           console.log(`\nConflicts (${scan.conflicts.length})`);
           for (const c of scan.conflicts.slice(0, 15)) {
-            console.log(`  ${c.values?.join(' ≈ ')} · d=${c.distance} · n=${c.occurrences}`);
+            console.log(`  ${c.values?.join(' ≈ ')} · d=${c.distance}`);
           }
         }
         return;
@@ -183,7 +216,6 @@ Options:
         return runBrandPlanInner({ scan, resolved, opts });
       }
 
-      // summary
       const contract = buildBrandContractDraft({ scan, resolved });
       const plan = brandPlan({ scan, resolved, contract });
       const { next_actions } = suggestNextActions({ capability: 'brand.scan', result: scan });
@@ -201,8 +233,6 @@ Options:
       else {
         console.log(`\nBrand · ${scan.repository.snapshot_id}`);
         console.log(`  ${plan.summary.colors} colors · ${plan.summary.near_duplicate_pairs} near-duplicates`);
-        console.log(`  ${plan.summary.button_families} button families · ${plan.summary.header_families} header/nav families`);
-        console.log(`  confidence colors=${resolved.confidence.colors} typography=${resolved.confidence.typography}`);
         printNext(next_actions);
       }
     }
@@ -231,11 +261,6 @@ async function runBrandPlanInner({ scan, resolved, opts }) {
       cost: planned.total_cost ?? planned.cost,
       engine: planned.engine || GOAP_ENGINE,
       status: planned.status,
-      expanded_states: planned.expanded_states,
-      generated_states: planned.generated_states,
-      frontier_peak: planned.frontier_peak,
-      elapsed_ms: planned.elapsed_ms,
-      error: planned.error,
     };
   }
   const enriched = attachProgression('brand.plan', plan, opts.json);
@@ -250,8 +275,6 @@ async function runBrandPlanInner({ scan, resolved, opts }) {
   else {
     console.log('\nBrand coherence plan');
     console.log(`  philosophy  ${plan.philosophy}`);
-    console.log(`  colors      ${plan.summary.colors} (${plan.summary.near_duplicate_pairs} near-dup pairs)`);
-    console.log('  steps');
     for (const [i, s] of plan.steps.entries()) {
       console.log(`    ${i + 1}. [${s.action}] ${s.title}`);
     }
@@ -263,16 +286,7 @@ export async function runPlan(argv = []) {
   const opts = parseArgs(argv);
   const [domain, ...rest] = opts.positionals;
   if (!domain || domain === 'help') {
-    console.log(`usage: agentsam plan <domain>
-
-Domains:
-  brand [--goap] [--json] [--write]
-  security   (use: agentsam security scan)
-  repository (use: agentsam inspect)
-  release    (use: agentsam status / package verify)
-
-Composable grammar: agentsam plan brand
-`);
+    console.log(`usage: agentsam plan <domain>\n\nDomains:\n  brand [--goap] [--json] [--write]\n`);
     return;
   }
   if (domain === 'brand') {

package/src/commands/cheat-sheet.js

@@ -0,0 +1,179 @@
+/**
+ * Canonical Agent Sam cheat-sheet — gcloud-like command groups.
+ * Old top-level commands remain as compatibility aliases.
+ * Every row shows a copy-pasteable `agentsam …` invocation.
+ */
+
+const GROUPS = Object.freeze([
+  {
+    id: 'work',
+    label: 'Work',
+    commands: [
+      ['project / create', 'Scaffold or enter a project'],
+      ['work / goap', 'Goals, blackboard, plans'],
+      ['brand / plan', 'Brand intelligence and composable plans'],
+      ['artifacts', 'Receipts and deploy evidence'],
+    ],
+  },
+  {
+    id: 'repository',
+    label: 'Repository',
+    commands: [
+      ['inspect', 'Bounded repository authority view'],
+      ['machine', 'Deterministic local perception + asset discovery'],
+      ['machine inspect', 'Inspect a path (file or directory)'],
+      ['recon', 'Bounded-worker finding packets'],
+      ['codebaseindex', 'AST ingest + optional embeddings'],
+      ['index', 'Project inventory + knowledge index commands'],
+      ['index status', 'Show knowledge index freshness'],
+      ['search', 'Retrieve from the local knowledge index'],
+      ['merkle', 'Integrity snapshots'],
+      ['security', 'Dependency + trust-boundary scan'],
+    ],
+  },
+  {
+    id: 'runtime',
+    label: 'Runtime',
+    commands: [
+      ['terminal / shell', 'Interactive slash-command shell'],
+      ['connections', 'Account, terminal, Worker, Cloudflare evidence'],
+      ['tunnel', 'Real Cloudflare Tunnels via Wrangler'],
+      ['go', 'Go product discover/build/deploy'],
+      ['dockerize', 'Supported containers'],
+      ['compute', 'Google Cloud VM / IAM helpers'],
+      ['gcloud auth login', 'Desktop PKCE Google Cloud connection (auto callback)'],
+      ['gcloud auth login --web', 'Hosted Local Studio identity (openid/email/profile)'],
+      ['gcloud auth login --sdk', 'Native Google Cloud SDK OAuth (optional)'],
+      ['google-cloud', 'Projects · compute · IAM SAs · billing · doctor'],
+    ],
+  },
+  {
+    id: 'providers',
+    label: 'Providers',
+    commands: [
+      ['setup', 'Discover → plan → approve → install (brew-style)'],
+      ['providers', 'Configure / verify model + infra credentials'],
+      ['models', 'Provider-verified model catalog'],
+      ['cloudflare', 'Wrangler reads + Worker profiles'],
+      ['google-cloud', 'Customer GCP connection inventory'],
+      ['gcloud auth login', 'Desktop PKCE Google Cloud (auto callback)'],
+      ['credentials audit', 'Configured · verified · drift (names only)'],
+      ['plugins', 'Install and manage plugins'],
+    ],
+  },
+  {
+    id: 'data',
+    label: 'Data',
+    commands: [
+      ['db', 'Project-local SQLite'],
+      ['knowledge / search', 'Indexed retrieval'],
+      ['autorag', 'AutoRAG helpers'],
+    ],
+  },
+  {
+    id: 'ai',
+    label: 'AI',
+    commands: [
+      ['models', 'Hosted + local model probes'],
+      ['skills', 'Portable skill vocabulary'],
+      ['context', 'Context economics + git bridge'],
+      ['usage / session', 'Spend and resume receipts'],
+    ],
+  },
+  {
+    id: 'identity',
+    label: 'Identity',
+    commands: [
+      ['whoami', 'Account + safe credential status'],
+      ['login / logout', 'Browser OAuth session'],
+      ['env', 'Vault/keychain shell loader'],
+      ['api-key', 'Create/rotate aak_* keys'],
+      ['identity', 'Portable OAuth portal surfaces'],
+    ],
+  },
+  {
+    id: 'apps',
+    label: 'Apps',
+    commands: [
+      ['app / local-studio', 'Bundled Local Studio launcher'],
+      ['cad', 'CAD project tools'],
+      ['brand', 'Brand intelligence'],
+    ],
+  },
+  {
+    id: 'system',
+    label: 'System',
+    commands: [
+      ['status', 'Account · models · terminal · live deploy'],
+      ['doctor / credentials audit --verify', 'Auth + drift health'],
+      ['update', 'Component update preview (gcloud-like)'],
+      ['billing', 'Billing account relationships (not --billing-project)'],
+      ['cheat-sheet', 'This page'],
+      ['version', 'Print CLI version'],
+    ],
+  },
+]);
+
+/** Expand "a / b" rows into copy-pasteable `agentsam …` invocations. */
+export function agentsamInvocations(cmd) {
+  const raw = String(cmd || '').trim();
+  if (!raw) return [];
+  if (raw.includes(' / ')) {
+    return raw.split(' / ').map((part) => `agentsam ${part.trim()}`);
+  }
+  return [`agentsam ${raw}`];
+}
+
+export function listCheatSheetGroups() {
+  return GROUPS.map((group) => ({
+    id: group.id,
+    label: group.label,
+    commands: group.commands.map(([cmd, summary]) => ({
+      cmd,
+      summary,
+      invocations: agentsamInvocations(cmd),
+    })),
+  }));
+}
+
+export function renderCheatSheet(version) {
+  const lines = [
+    '',
+    `  Agent Sam cheat-sheet${version ? ` · v${version}` : ''}`,
+    '  Organized hierarchy · each row shows a runnable `agentsam …` command.',
+    '',
+  ];
+  for (const group of GROUPS) {
+    lines.push(`  ${group.label}`);
+    for (const [cmd, summary] of group.commands) {
+      const invocations = agentsamInvocations(cmd);
+      const primary = invocations[0] || `agentsam ${cmd}`;
+      lines.push(`    ${primary.padEnd(52)}  ${summary}`);
+      for (const extra of invocations.slice(1)) {
+        lines.push(`    ${extra.padEnd(52)}  (same group)`);
+      }
+    }
+    lines.push('');
+  }
+  lines.push('  Failure follow-through');
+  lines.push('    agentsam credentials remediate -- gcloud edge-cloud service-accounts keys create');
+  lines.push('    agentsam credentials audit --verify --drift --names-only');
+  lines.push('');
+  lines.push('  Docs');
+  lines.push('    docs/contracts/environment-vocabulary.md');
+  lines.push('    docs/AUTH_IDENTITY_CONTRACT.md');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function runCheatSheet(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const json = argv.includes('--json');
+  const version = options.version || '';
+  if (json) {
+    write(JSON.stringify({ schema_version: 'agentsam-cheat-sheet-v1', version, groups: listCheatSheetGroups() }, null, 2) + '\n');
+    return 0;
+  }
+  write(renderCheatSheet(version));
+  return 0;
+}

package/src/commands/cloudflare-login.js

@@ -0,0 +1,222 @@
+/**
+ * agentsam_cf_browser_oauth — authorize Cloudflare API scopes via browser OAuth.
+ *
+ * Feature packs expand to scoped OAuth requests so users never scroll 300+ CF
+ * permissions. Flow: IAM-authenticated CLI → ENTER → open authorize URL → CF consent.
+ */
+import { resolveAccountAuthority } from '../lib/auth.js';
+import { promptToOpenUrl } from '../lib/open-url.js';
+import {
+  LOCAL_STUDIO_APP_ID,
+  resolveLocalStudioHostOrigin,
+  resolvePlatformAccountIssuer,
+} from '../lib/app-authority.js';
+import {
+  listCloudflareFeaturePacks,
+  getCloudflareFeaturePack,
+  scopesForFeaturePacks,
+  scopesForCapabilities,
+} from '../../packages/connectors/cloudflare/src/index.js';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+function parseLoginArgs(argv = []) {
+  const out = {
+    packs: [],
+    capabilities: [],
+    json: false,
+    listPacks: false,
+    help: false,
+    open: true,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') out.json = true;
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg === '--list-packs' || arg === 'packs') out.listPacks = true;
+    else if (arg === '--no-open') out.open = false;
+    else if (arg === '--pack' || arg === '--packs') {
+      const raw = argv[++i] || '';
+      out.packs.push(...raw.split(',').map((s) => s.trim()).filter(Boolean));
+    } else if (arg.startsWith('--pack=')) {
+      out.packs.push(...arg.slice('--pack='.length).split(',').map((s) => s.trim()).filter(Boolean));
+    } else if (arg === '--capability' || arg === '--capabilities') {
+      const raw = argv[++i] || '';
+      out.capabilities.push(...raw.split(',').map((s) => s.trim()).filter(Boolean));
+    } else if (arg.startsWith('--capability=')) {
+      out.capabilities.push(...arg.slice('--capability='.length).split(',').map((s) => s.trim()).filter(Boolean));
+    } else if (!arg.startsWith('-') && getCloudflareFeaturePack(arg)) {
+      out.packs.push(arg);
+    } else {
+      throw new Error(`unknown cloudflare login option: ${arg}`);
+    }
+  }
+  return out;
+}
+
+const LOGIN_HELP = `Agent Sam · Cloudflare browser OAuth (agentsam_cf_browser_oauth)
+
+Authorize Cloudflare API access without picking from 300+ scopes.
+Feature packs expand to OAuth scopes on the Local Studio APP host.
+
+Namespaces (do not collapse):
+  APP.id              local-studio
+  HOST.origin         from apps/local-studio/agentsam.app.json hosts[]
+  PLATFORM issuer     IAM_OAUTH_ISSUER (account API — separate)
+
+  agentsam cloudflare login --pack agentsam
+  agentsam cloudflare login --pack data,ai
+  agentsam cloudflare login --capability cloudflare.d1,cloudflare.hyperdrive
+  agentsam cloudflare login --list-packs
+  agentsam cloudflare authorize --pack data   # alias
+
+Flow
+  1. Account auth: AGENTSAM_API_KEY + IAM_OAUTH_ISSUER (PLATFORM).
+  2. CLI prints Local Studio HOST authorize URL; press ENTER to open.
+  3. Cloudflare consent for that pack only (AgentSam Local Studio OAuth client).
+`;
+
+/**
+ * Build Cloudflare connection OAuth start URL from local-studio APP HOST.
+ * Packs expand client-side; HOST serves /api/connections/cloudflare/start.
+ */
+export function buildCloudflareBrowserOAuthStartUrl(options = {}) {
+  const packs = (options.packs || []).map((p) => String(p).trim().toLowerCase()).filter(Boolean);
+  const capabilities = (options.capabilities || []).map((c) => String(c).trim()).filter(Boolean);
+
+  for (const id of packs) {
+    if (id !== 'baseline' && !getCloudflareFeaturePack(id)) {
+      const err = new Error(`unknown Cloudflare feature pack: ${id}`);
+      err.code = 'unknown_feature_pack';
+      throw err;
+    }
+  }
+
+  const effectivePacks = packs.length ? packs : ['agentsam'];
+  const scopes = scopesForFeaturePacks(effectivePacks, capabilities);
+  const hostOrigin = resolveLocalStudioHostOrigin({
+    root: options.root,
+    role: options.hostRole || 'production',
+    hostId: options.hostId,
+  });
+  const startPath = options.startPath
+    || '/api/connections/cloudflare/start';
+  const start = new URL(startPath, `${hostOrigin}/`);
+  start.searchParams.set('packs', effectivePacks.join(','));
+  if (capabilities.length) start.searchParams.set('capabilities', capabilities.join(','));
+  if (options.returnTo) start.searchParams.set('return_to', options.returnTo);
+
+  return {
+    kind: 'agentsam_cf_browser_oauth',
+    app_id: LOCAL_STUDIO_APP_ID,
+    host_origin: hostOrigin,
+    platform_issuer: resolvePlatformAccountIssuer(options.env || process.env, options.issuer || ''),
+    authorize_url: start.toString(),
+    path_kind: 'app_host_connections',
+    packs: effectivePacks,
+    capabilities,
+    scope_count: scopes.length,
+    scopes,
+    packs_detail: effectivePacks.map((id) => {
+      const pack = getCloudflareFeaturePack(id);
+      return pack
+        ? { id: pack.id, label: pack.label, description: pack.description, capabilities: pack.capabilities }
+        : { id, label: id };
+    }),
+    note: 'OAuth client + scopes authorize on local-studio HOST; account identity stays on PLATFORM IAM_OAUTH_ISSUER.',
+  };
+}
+
+export async function runCloudflareBrowserOAuthLogin(argv = [], options = {}) {
+  const args = parseLoginArgs(argv);
+  const write = options.write || ((text) => process.stdout.write(text));
+  const env = options.env || process.env;
+
+  if (args.help) {
+    write(LOGIN_HELP);
+    return { ok: true, help: true };
+  }
+
+  if (args.listPacks) {
+    const packs = listCloudflareFeaturePacks().map((pack) => ({
+      id: pack.id,
+      label: pack.label,
+      description: pack.description,
+      capabilities: pack.capabilities,
+      scope_count: scopesForCapabilities({ capabilities: pack.capabilities, includeBaseline: true }).length,
+    }));
+    const payload = {
+      schema: 'agentsam.cloudflare.feature_packs.v1',
+      kind: 'agentsam_cf_browser_oauth',
+      mitigation: 'Authorize by pack (product need), not by scrolling 300+ Cloudflare scopes. Upgrade later with another --pack.',
+      packs,
+    };
+    write(args.json ? `${JSON.stringify(payload, null, 2)}\n` : LOGIN_HELP);
+    return payload;
+  }
+
+  const authority = await (options.authorityLoader || resolveAccountAuthority)({
+    env,
+    home: options.home,
+    fetchImpl: options.fetchImpl,
+    refreshImpl: options.refreshImpl,
+  });
+  if (!authority.value) {
+    const err = new Error(
+      authority.error
+        || 'Sign in first: agentsam login  (or export AGENTSAM_API_KEY)',
+    );
+    err.code = 'account_auth_required';
+    throw err;
+  }
+
+  const plan = buildCloudflareBrowserOAuthStartUrl({
+    env,
+    packs: args.packs,
+    capabilities: args.capabilities,
+    issuer: options.issuer,
+  });
+
+  if (args.json && !args.open) {
+    write(`${JSON.stringify(plan, null, 2)}\n`);
+    return plan;
+  }
+
+  writeLine(write, '');
+  writeLine(write, '  Agent Sam · Cloudflare browser OAuth');
+  writeLine(write, `  kind           agentsam_cf_browser_oauth`);
+  writeLine(write, `  packs          ${plan.packs.join(', ')}`);
+  writeLine(write, `  scopes         ${plan.scope_count} (pack-expanded; not the full CF catalog)`);
+  for (const pack of plan.packs_detail) {
+    writeLine(write, `  · ${pack.id.padEnd(12)} ${pack.description || pack.label || ''}`);
+  }
+  writeLine(write, '');
+
+  if (args.open !== false) {
+    const promptImpl = options.promptToOpenUrlImpl || promptToOpenUrl;
+    await promptImpl(plan.authorize_url, {
+      heading: 'Authorize Cloudflare for AgentSam at:',
+      prompt: 'Press ENTER to open Cloudflare consent in your browser.',
+      input: options.input,
+      output: options.output || process.stdout,
+      openImpl: options.openImpl,
+    });
+    writeLine(write, '  After approving scopes in the browser, return here.');
+    writeLine(write, '  Next: agentsam cloudflare status --json');
+    writeLine(write, '        agentsam whoami --json');
+    writeLine(write, '');
+  }
+
+  if (args.json) write(`${JSON.stringify(plan, null, 2)}\n`);
+  return { ok: true, ...plan };
+}
+
+export function isCloudflareLoginFamily(family) {
+  return family === 'login' || family === 'authorize' || family === 'oauth' || family === 'packs';
+}