@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/commands/billing.js

@@ -0,0 +1,127 @@
+/**
+ * Billing relationships — not --billing-project (quota attribution).
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+async function runGcloud(args, env) {
+  try {
+    const { stdout, stderr } = await execFileAsync('gcloud', args, {
+      timeout: 30000,
+      env,
+      maxBuffer: 1024 * 1024,
+    });
+    return { ok: true, stdout: String(stdout || ''), stderr: String(stderr || '') };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: String(error?.stdout || ''),
+      stderr: String(error?.stderr || error?.message || ''),
+    };
+  }
+}
+
+function printHelp(write) {
+  writeLine(write, '');
+  writeLine(write, '  agentsam billing');
+  writeLine(write, '  agentsam billing accounts');
+  writeLine(write, '  agentsam billing project [PROJECT_ID]');
+  writeLine(write, '  agentsam billing budgets --account XXXXXX-XXXXXX-XXXXXX');
+  writeLine(write, '');
+  writeLine(write, '  Note: gcloud --billing-project only attributes quota for one CLI call.');
+  writeLine(write, '  It does not show historical spend. Use Cloud Billing reports / BigQuery export for costs.');
+  writeLine(write, '  Future: agentsam costs gcp|cloudflare|models');
+  writeLine(write, '');
+}
+
+export async function runBilling(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const env = options.env || process.env;
+  const json = argv.includes('--json');
+  const args = argv.filter((a) => a !== '--json');
+
+  if (!args.length || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+    printHelp(write);
+    if (!args.length) {
+      // Default: accounts list
+      args.push('accounts');
+    } else {
+      return 0;
+    }
+  }
+
+  if (args[0] === 'accounts') {
+    const result = await runGcloud(['billing', 'accounts', 'list', '--format=table(name,displayName,open)'], env);
+    if (!result.ok) {
+      write(result.stderr || result.stdout);
+      return 1;
+    }
+    if (json) write(JSON.stringify({ ok: true, stdout: result.stdout }, null, 2) + '\n');
+    else {
+      writeLine(write, '');
+      writeLine(write, '  Agent Sam · billing accounts');
+      writeLine(write, '  (relationship inventory — not a spend dashboard)');
+      writeLine(write, '');
+      write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    }
+    return 0;
+  }
+
+  if (args[0] === 'project') {
+    let project = args[1] || '';
+    if (!project) {
+      const cfg = await runGcloud(['config', 'get-value', 'project'], env);
+      project = cfg.stdout.trim();
+    }
+    if (!project || project === '(unset)') {
+      writeLine(write, '  ✕ Pass a project id or set gcloud config project.');
+      return 1;
+    }
+    const result = await runGcloud(['billing', 'projects', 'describe', project, '--format=yaml(billingAccountName,billingEnabled,projectId)'], env);
+    if (!result.ok) {
+      write(result.stderr || result.stdout);
+      return 1;
+    }
+    write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    return 0;
+  }
+
+  if (args[0] === 'budgets') {
+    let account = '';
+    for (let i = 1; i < args.length; i += 1) {
+      if (args[i] === '--account') account = args[++i] || '';
+      else if (args[i].startsWith('--account=')) account = args[i].slice('--account='.length);
+      else if (!args[i].startsWith('-') && !account) account = args[i];
+    }
+    if (!account || account.includes('XXXX')) {
+      writeLine(write, '  ✕ Pass a real billing account id from: agentsam billing accounts');
+      writeLine(write, '    Example: agentsam billing budgets --account 017E01-4426EF-21356F');
+      return 1;
+    }
+    const name = account.startsWith('billingAccounts/') ? account : `billingAccounts/${account}`;
+    const result = await runGcloud(['billing', 'budgets', 'list', '--billing-account', name.replace(/^billingAccounts\//, ''), '--format=table(displayName,amount,budgetFilter)'], env);
+    // gcloud wants the id without prefix sometimes; try both on failure
+    if (!result.ok) {
+      const retry = await runGcloud(['billing', 'budgets', 'list', `--billing-account=${account.replace(/^billingAccounts\//, '')}`], env);
+      if (!retry.ok) {
+        write(retry.stderr || result.stderr || retry.stdout);
+        writeLine(write, '');
+        writeLine(write, '  Tip: copy ACCOUNT_ID from `agentsam billing accounts` — not the placeholder XXXXXX-XXXXXX-XXXXXX.');
+        return 1;
+      }
+      write(retry.stdout.endsWith('\n') ? retry.stdout : `${retry.stdout}\n`);
+      return 0;
+    }
+    write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    return 0;
+  }
+
+  printHelp(write);
+  return 1;
+}

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,12 +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;
@@ -66,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;
     }
@@ -98,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) => {
@@ -122,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);
@@ -136,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;
@@ -151,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;
@@ -182,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 });
@@ -200,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);
       }
     }
@@ -218,26 +249,18 @@ async function runBrandPlanInner({ scan, resolved, opts }) {
     const world = brandWorldFromPlan(plan);
     const goal = brandGoalFromPlan(plan);
     const actions = brandGoapActions();
-    const sequence = [];
-    const state = { ...world };
-    // greedy applicable actions by cost until goal satisfied or stuck
-    for (let guard = 0; guard < 20; guard += 1) {
-      const done = Object.entries(goal).every(([k, v]) => state[k] === v);
-      if (done) break;
-      const candidates = actions
-        .filter((a) => Object.entries(a.preconditions || {}).every(([k, v]) => state[k] === v))
-        .filter((a) => !sequence.includes(a.id))
-        .sort((a, b) => (a.cost || 1) - (b.cost || 1));
-      if (!candidates.length) break;
-      const next = candidates[0];
-      sequence.push(next.id);
-      Object.assign(state, next.effects || {});
-    }
+    const planned = planGoap({
+      initialState: world,
+      goal,
+      actions,
+      maxExpansions: 10_000,
+    });
     goap = {
-      ok: sequence.length > 0,
-      plan: sequence,
-      cost: sequence.reduce((n, id) => n + (actions.find((a) => a.id === id)?.cost || 0), 0),
-      engine: 'brand-goap-greedy',
+      ok: planned.ok,
+      plan: planned.plan,
+      cost: planned.total_cost ?? planned.cost,
+      engine: planned.engine || GOAP_ENGINE,
+      status: planned.status,
     };
   }
   const enriched = attachProgression('brand.plan', plan, opts.json);
@@ -252,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}`);
     }
@@ -265,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,154 @@
+/**
+ * Canonical Agent Sam cheat-sheet — gcloud-like command groups.
+ * Old top-level commands remain as compatibility aliases.
+ */
+
+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'],
+      ['recon', 'Bounded-worker finding packets'],
+      ['codebaseindex', 'AST ingest + optional embeddings'],
+      ['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', 'agentsam --version'],
+    ],
+  },
+]);
+
+export function listCheatSheetGroups() {
+  return GROUPS.map((group) => ({
+    id: group.id,
+    label: group.label,
+    commands: group.commands.map(([cmd, summary]) => ({ cmd, summary })),
+  }));
+}
+
+export function renderCheatSheet(version) {
+  const lines = [
+    '',
+    `  Agent Sam cheat-sheet${version ? ` · v${version}` : ''}`,
+    '  Organized hierarchy · old top-level commands remain compatibility aliases.',
+    '',
+  ];
+  for (const group of GROUPS) {
+    lines.push(`  ${group.label}`);
+    for (const [cmd, summary] of group.commands) {
+      lines.push(`    ${String(cmd).padEnd(42)}  ${summary}`);
+    }
+    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;
+}