@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/src/commands/app.js

@@ -4,14 +4,34 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const FORBIDDEN_STRING_APP = /\bconst\s+APP\s*=\s*["'`][^"'`]+["'`]/;
+const HOST_PRODUCT_FIELDS = new Set([
+  'id',
+  'name',
+  'package',
+  'bin',
+  'commands',
+  'routes',
+  'surfaces',
+  'capabilities',
+  'entrypoints',
+  'version',
+  'kind',
+  'product_id',
+]);
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
 }
 
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
 function readManifest(manifestPath, fallbackId) {
   try {
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const manifest = readJson(manifestPath);
     return {
       id: manifest.id || fallbackId,
       name: manifest.name || fallbackId,
@@ -74,6 +94,264 @@ function runAppBin(app, args, options = {}) {
   if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
 }
 
+function walkFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.output' || entry.name === 'target') {
+      continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkFiles(full, out);
+    else if (/\.(js|mjs|cjs|ts|tsx)$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+function walkPackageJsonFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (['node_modules', 'dist', '.output', 'target', '.git'].includes(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkPackageJsonFiles(full, out);
+    else if (entry.name === 'package.json') out.push(full);
+  }
+  return out;
+}
+
+function npmDistributionWarnings(app) {
+  const warnings = [];
+  const installCommand = clean(app.manifest?.install?.command);
+  const declaresNpmInstall = /^npm\s+(?:i|install)\b/.test(installCommand);
+  if (!declaresNpmInstall) return warnings;
+
+  const rootPackagePath = path.join(app.dir, 'package.json');
+  if (!fs.existsSync(rootPackagePath)) {
+    return [`${app.id}: distribution: install.command advertises npm but package.json is missing`];
+  }
+
+  let rootPackage;
+  try {
+    rootPackage = readJson(rootPackagePath);
+  } catch (error) {
+    return [`${app.id}: distribution: package.json is invalid JSON: ${error.message}`];
+  }
+
+  if (app.manifest.package && rootPackage.name !== app.manifest.package) {
+    warnings.push(`${app.id}: distribution: manifest package ${app.manifest.package} does not match package.json name ${rootPackage.name || '(missing)'}`);
+  }
+  if (rootPackage.private === true) {
+    warnings.push(`${app.id}: distribution: package.json private=true but install.command advertises npm installation`);
+  }
+
+  const expectedBin = clean(app.manifest.bin || app.manifest?.entrypoints?.cli);
+  const packageBins = typeof rootPackage.bin === 'string'
+    ? [rootPackage.bin]
+    : Object.values(rootPackage.bin || {}).map(clean).filter(Boolean);
+  if (expectedBin && !packageBins.includes(expectedBin)) {
+    warnings.push(`${app.id}: distribution: package.json does not expose manifest CLI bin ${expectedBin}`);
+  }
+  if (!Array.isArray(rootPackage.files) || rootPackage.files.length === 0) {
+    warnings.push(`${app.id}: distribution: package.json has no explicit files allowlist`);
+  }
+
+  const escaping = [];
+  for (const packageFile of walkPackageJsonFiles(app.dir)) {
+    let nested;
+    try { nested = readJson(packageFile); } catch { continue; }
+    for (const group of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+      for (const [name, spec] of Object.entries(nested[group] || {})) {
+        if (typeof spec !== 'string' || !spec.startsWith('file:')) continue;
+        const target = path.resolve(path.dirname(packageFile), spec.slice(5));
+        const insideApp = target === app.dir || target.startsWith(`${app.dir}${path.sep}`);
+        if (!insideApp) {
+          escaping.push(`${path.relative(app.dir, packageFile)}:${group}:${name}=${spec}`);
+        }
+      }
+    }
+  }
+  if (escaping.length) {
+    warnings.push(`${app.id}: distribution: ${escaping.length} repo-local file: dependencies escape the app package (${escaping.join(', ')})`);
+  }
+
+  return warnings;
+}
+
+function validateOneApp(app, knownIds, root) {
+  const errors = [];
+  const warnings = [];
+  const m = app.manifest;
+
+  if (m.schema !== 'agentsam.app.v1') {
+    errors.push(`${app.id}: schema must be "agentsam.app.v1"`);
+  }
+  if (!KEBAB.test(app.id)) {
+    errors.push(`${app.id}: id must be kebab-case (^[a-z][a-z0-9]*(-[a-z0-9]+)*$)`);
+  }
+  const dirId = path.basename(app.dir);
+  if (dirId !== app.id && !m.directory_id_exception) {
+    errors.push(`${app.id}: directory basename "${dirId}" must equal id (set directory_id_exception if intentional)`);
+  }
+  if (m.kind !== 'app') {
+    errors.push(`${app.id}: kind must be "app"`);
+  }
+  if (m.product_id != null && !KEBAB.test(m.product_id)) {
+    errors.push(`${app.id}: product_id must be kebab-case`);
+  }
+  if (m.package && m.package === app.id) {
+    errors.push(`${app.id}: package must not equal APP.id (PACKAGE namespace is separate)`);
+  }
+  if (typeof m.package === 'string' && m.package.startsWith('@') === false && m.package.includes('/')) {
+    warnings.push(`${app.id}: package looks unusual: ${m.package}`);
+  }
+
+  const caps = m.capabilities;
+  if (caps == null) {
+    warnings.push(`${app.id}: capabilities not declared`);
+  } else if (!Array.isArray(caps) && (typeof caps !== 'object' || caps === null)) {
+    errors.push(`${app.id}: capabilities must be an array or boolean map`);
+  }
+
+  if (!m.entrypoints && !m.bin) {
+    warnings.push(`${app.id}: neither entrypoints nor bin declared`);
+  }
+
+  warnings.push(...npmDistributionWarnings(app));
+
+  const hostPath = path.join(app.dir, '.agentsam', 'app.json');
+  if (fs.existsSync(hostPath)) {
+    let host;
+    try {
+      host = readJson(hostPath);
+    } catch (err) {
+      errors.push(`${app.id}: .agentsam/app.json invalid JSON: ${err.message}`);
+      host = null;
+    }
+    if (host) {
+      if (host.schema === 'agentsam.app.v1' || host.id) {
+        errors.push(
+          `${app.id}: .agentsam/app.json must be host/install state (agentsam.host-install.v1 with app_id), not a second product definition`,
+        );
+      }
+      if (host.schema !== 'agentsam.host-install.v1') {
+        errors.push(`${app.id}: .agentsam/app.json schema must be "agentsam.host-install.v1"`);
+      }
+      if (!host.app_id) {
+        errors.push(`${app.id}: .agentsam/app.json missing app_id`);
+      } else if (!knownIds.has(host.app_id)) {
+        errors.push(`${app.id}: .agentsam/app.json app_id "${host.app_id}" does not resolve to a known APP`);
+      } else if (host.app_id !== app.id) {
+        errors.push(`${app.id}: .agentsam/app.json app_id "${host.app_id}" must match this APP.id`);
+      }
+      for (const field of HOST_PRODUCT_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(host, field)) {
+          errors.push(`${app.id}: .agentsam/app.json must not redefine product field "${field}"`);
+        }
+      }
+    }
+  }
+
+  for (const file of walkFiles(path.join(app.dir, 'backend'))) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (FORBIDDEN_STRING_APP.test(text)) {
+      const rel = path.relative(root, file);
+      errors.push(`${app.id}: forbidden string APP identity in ${rel} — import agentsam.app.json instead`);
+    }
+  }
+
+  return { id: app.id, errors, warnings };
+}
+
+function validateDesktopManifests(root, knownIds) {
+  const errors = [];
+  const warnings = [];
+  const dir = path.join(root, 'packages/agentsam-desktop-shell/manifests');
+  if (!fs.existsSync(dir)) return { errors, warnings };
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json') || name === 'schema.json' || name === 'example.json') continue;
+    const file = path.join(dir, name);
+    let manifest;
+    try {
+      manifest = readJson(file);
+    } catch (err) {
+      errors.push(`desktop ${name}: invalid JSON: ${err.message}`);
+      continue;
+    }
+    const appId = manifest.app_id;
+    if (!appId) {
+      errors.push(`desktop ${name}: missing app_id`);
+      continue;
+    }
+    if (!KEBAB.test(appId)) {
+      errors.push(`desktop ${name}: app_id must be kebab-case`);
+    }
+    // Brand shells (meauxbility, etc.) may not be APP products — only fail when
+    // the filename suggests a product APP or when app_id is a known near-miss.
+    const productish = ['cad-creator', 'client-cms-editor', 'local-studio', 'cms-editor'].includes(appId)
+      || ['cad-creator', 'client-cms-editor', 'cms-editor', 'local-studio'].some((n) => name.startsWith(n));
+    if (productish && !knownIds.has(appId)) {
+      errors.push(`desktop ${name}: app_id "${appId}" does not resolve to a known APP manifest`);
+    }
+    const included = Array.isArray(manifest.included_apps) ? manifest.included_apps : [];
+    for (const bundledId of included) {
+      if (!KEBAB.test(bundledId)) {
+        errors.push(`desktop ${name}: included_apps entry "${bundledId}" must be kebab-case`);
+        continue;
+      }
+      if (!knownIds.has(bundledId)) {
+        errors.push(
+          `desktop ${name}: included_apps entry "${bundledId}" does not resolve to a known APP manifest`,
+        );
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+export function validateApps(options = {}) {
+  const root = options.root || REPO_ROOT;
+  const filterId = options.appId || null;
+  const apps = listAppManifests(root);
+  const knownIds = new Set(apps.map((a) => a.id));
+  const selected = filterId ? apps.filter((a) => a.id === filterId || path.basename(a.dir) === filterId) : apps;
+
+  if (filterId && selected.length === 0) {
+    throw new Error(`unknown AgentSam app: ${filterId}`);
+  }
+
+  const idCounts = new Map();
+  for (const app of apps) {
+    idCounts.set(app.id, (idCounts.get(app.id) || 0) + 1);
+  }
+
+  const results = [];
+  const allErrors = [];
+  const allWarnings = [];
+
+  for (const [id, count] of idCounts) {
+    if (count > 1) allErrors.push(`duplicate APP.id across manifests: ${id}`);
+  }
+
+  for (const app of selected) {
+    const result = validateOneApp(app, knownIds, root);
+    results.push(result);
+    allErrors.push(...result.errors);
+    allWarnings.push(...result.warnings);
+  }
+
+  if (!filterId) {
+    const desktop = validateDesktopManifests(root, knownIds);
+    allErrors.push(...desktop.errors);
+    allWarnings.push(...desktop.warnings);
+  }
+
+  return {
+    ok: allErrors.length === 0,
+    apps: results,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}
+
 export async function runApp(argv = [], options = {}) {
   const write = options.write || ((text) => process.stdout.write(text));
   const [command = 'list', appId, ...rest] = argv;
@@ -81,6 +359,8 @@ export async function runApp(argv = [], options = {}) {
     write([
       'agentsam app list',
       'agentsam app info <id>',
+      'agentsam app inspect <id>',
+      'agentsam app validate [--all|<id>]',
       'agentsam app install <id>',
       'agentsam app doctor <id>',
       'agentsam app preview <id>',
@@ -100,10 +380,34 @@ export async function runApp(argv = [], options = {}) {
     return apps;
   }
 
+  if (command === 'validate') {
+    const target = appId === '--all' || appId == null ? null : appId;
+    const report = validateApps({ root: options.root || REPO_ROOT, appId: target });
+    if (report.warnings.length) {
+      write('\n  Warnings\n');
+      for (const w of report.warnings) write(`  • ${w}\n`);
+    }
+    if (report.errors.length) {
+      write('\n  Errors\n');
+      for (const e of report.errors) write(`  ✗ ${e}\n`);
+      write('\n');
+      if (!options.noExit) process.exitCode = 1;
+      return report;
+    }
+    write(`\n  ✓ agentsam app validate${target ? ` ${target}` : ' --all'} (${report.apps.length} app(s))\n\n`);
+    return report;
+  }
+
   if (!appId) throw new Error('agentsam app requires an app id');
   const app = resolveApp(appId, options.root || REPO_ROOT);
 
-  if (command === 'info') {
+  if (command === 'info' || command === 'inspect') {
+    if (command === 'inspect') {
+      const report = validateApps({ root: options.root || REPO_ROOT, appId: app.id });
+      write(`${JSON.stringify({ manifest: app.manifest, validation: report }, null, 2)}\n`);
+      if (!report.ok && !options.noExit) process.exitCode = 1;
+      return { manifest: app.manifest, validation: report };
+    }
     write(`${JSON.stringify(app.manifest, null, 2)}\n`);
     return app.manifest;
   }
@@ -132,7 +436,7 @@ export async function runApp(argv = [], options = {}) {
 }
 
 export function appCommandHelp() {
-  return 'agentsam app list|info|install|doctor|preview|scaffold';
+  return 'agentsam app list|info|inspect|validate|install|doctor|preview|scaffold';
 }
 
 export { clean };

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;
+}