@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/commands/api-key.js

@@ -0,0 +1,244 @@
+import os from 'node:os';
+import { getJson, postJson } from '../lib/core-client.js';
+import { resolveAccountAuthority } from '../lib/auth.js';
+import { setProviderCredential, ensureAgentEnvLoader } from '../lib/provider-credentials.js';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+function parseArgs(argv = []) {
+  const out = {
+    command: 'help',
+    name: '',
+    id: '',
+    store: 'keychain',
+    activate: false,
+    active: false,
+    json: false,
+    positionals: [],
+  };
+  const [command = 'help', ...rest] = argv;
+  out.command = command;
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--name') out.name = String(rest[++i] || '').trim();
+    else if (arg === '--id') out.id = String(rest[++i] || '').trim();
+    else if (arg === '--store') out.store = String(rest[++i] || 'keychain').trim().toLowerCase();
+    else if (arg === '--activate') out.activate = true;
+    else if (arg === '--active') out.active = true;
+    else if (arg === '--json') out.json = true;
+    else if (String(arg).startsWith('-')) throw new Error(`unexpected api-key argument: ${arg}`);
+    else out.positionals.push(arg);
+  }
+  if (!out.id && out.positionals[0]) out.id = out.positionals[0];
+  if (!out.name) {
+    try {
+      out.name = os.hostname() || 'local';
+    } catch {
+      out.name = 'local';
+    }
+  }
+  return out;
+}
+
+async function requireAuthority(options = {}) {
+  const authority = await (options.authorityLoader || resolveAccountAuthority)({
+    env: options.env || process.env,
+    home: options.home,
+    explicit: options.token || '',
+    fetchImpl: options.fetchImpl,
+    refreshImpl: options.refreshImpl,
+    nowMs: options.nowMs,
+    skewMs: options.skewMs,
+    signal: options.signal,
+  });
+  if (!authority?.value) {
+    throw new Error(authority?.error || 'Run agentsam login first (OAuth session required to mint API keys).');
+  }
+  return authority;
+}
+
+function storeSecretLocally(secret, options = {}) {
+  const store = String(options.store || 'keychain').toLowerCase();
+  if (store === 'none' || store === 'print') {
+    return { storage: 'none', source_command: null };
+  }
+  // keychain | vault — setSecureProviderKey tries OS keychain then encrypted vault
+  const result = setProviderCredential('inneranimalmedia', secret, {
+    ...options,
+    exportProfile: false,
+    writeEnvProfile: false,
+  });
+  ensureAgentEnvLoader(options);
+  return {
+    storage: store === 'vault' ? 'local_vault' : 'os_keychain',
+    provider: result.provider,
+    source_command: 'source ~/.agentsam/load-agent-env.sh',
+  };
+}
+
+function renderCreate(result) {
+  const lines = [
+    '',
+    '  ✓ AgentSam API credential created',
+    '',
+    `  Name        ${result.credential?.name || ''}`,
+    `  Prefix      ${result.credential?.prefix || ''}`,
+    `  Owner       current account`,
+    `  Storage     ${result.storage_label || 'not stored'}`,
+    `  Status      active`,
+    '',
+  ];
+  if (result.activated) {
+    lines.push('  ✓ AGENTSAM_API_KEY is available to AgentSam environments');
+    lines.push('');
+    lines.push('  source ~/.agentsam/load-agent-env.sh');
+    lines.push('  agentsam whoami');
+    lines.push('');
+  } else if (result.secret_once) {
+    lines.push('  Copy this key now. It cannot be displayed again.');
+    lines.push(`  ${result.secret_once}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export async function runApiKey(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const parsed = parseArgs(argv);
+  const env = options.env || process.env;
+
+  if (parsed.command === 'help' || parsed.command === '--help' || parsed.command === '-h') {
+    writeLine(write, 'agentsam api-key create [--name <label>] [--store keychain|vault|none] [--activate]');
+    writeLine(write, 'agentsam api-key list [--json]');
+    writeLine(write, 'agentsam api-key rotate [--id <credential_id>|--active] [--store keychain] [--activate]');
+    writeLine(write, 'agentsam api-key revoke --id <credential_id>');
+    return;
+  }
+
+  if (parsed.command === 'create') {
+    const authority = await requireAuthority(options);
+    const post = options.postJsonImpl || postJson;
+    const response = await post(
+      '/api/sdk/api-keys',
+      { action: 'create', name: parsed.name, client_type: 'cli' },
+      { env, home: options.home, bearer: authority.value, fetchImpl: options.fetchImpl, refreshImpl: options.refreshImpl },
+    );
+    const secret = response?.secret_once;
+    if (!secret) throw new Error('host_did_not_return_secret_once');
+
+    let storage = { storage: 'none' };
+    let activated = false;
+    if (parsed.activate || parsed.store !== 'none') {
+      storage = storeSecretLocally(secret, { ...options, store: parsed.store });
+      activated = parsed.activate || parsed.store !== 'none';
+    }
+
+    const result = {
+      ok: true,
+      credential: response.credential,
+      secret_once: activated ? undefined : secret,
+      storage: storage.storage,
+      storage_label:
+        storage.storage === 'os_keychain'
+          ? process.platform === 'darwin'
+            ? 'macOS Keychain'
+            : process.platform === 'win32'
+              ? 'Windows Credential Manager'
+              : 'OS credential store'
+          : storage.storage === 'local_vault'
+            ? 'local encrypted vault'
+            : 'not stored',
+      activated,
+    };
+    if (parsed.json) writeLine(write, JSON.stringify({ ...result, secret_once: secret }, null, 2));
+    else write(renderCreate(result));
+    return result;
+  }
+
+  if (parsed.command === 'list') {
+    const authority = await requireAuthority(options);
+    const get = options.getJsonImpl || getJson;
+    const response = await get('/api/sdk/api-keys', {
+      env,
+      home: options.home,
+      bearer: authority.value,
+      fetchImpl: options.fetchImpl,
+      refreshImpl: options.refreshImpl,
+    });
+    const rows = response?.credentials || [];
+    if (parsed.json) {
+      writeLine(write, JSON.stringify({ ok: true, credentials: rows }, null, 2));
+    } else {
+      writeLine(write, '');
+      writeLine(write, '  AgentSam API keys');
+      if (!rows.length) writeLine(write, '  (none)');
+      for (const row of rows) {
+        writeLine(
+          write,
+          `  ${(row.name || row.id || '').padEnd(28)} ${(row.prefix || '').padEnd(14)} ${row.status || 'unknown'}`,
+        );
+      }
+      writeLine(write, '');
+    }
+    return { ok: true, credentials: rows };
+  }
+
+  if (parsed.command === 'rotate') {
+    const authority = await requireAuthority(options);
+    let id = parsed.id;
+    if (!id || parsed.active) {
+      const get = options.getJsonImpl || getJson;
+      const listed = await get('/api/sdk/api-keys', {
+        env,
+        home: options.home,
+        bearer: authority.value,
+        fetchImpl: options.fetchImpl,
+        refreshImpl: options.refreshImpl,
+      });
+      const active = (listed?.credentials || []).find((row) => row.status === 'active');
+      if (!active?.id) throw new Error('no_active_credential_to_rotate');
+      id = active.id;
+    }
+    const post = options.postJsonImpl || postJson;
+    const response = await post(
+      '/api/sdk/api-keys',
+      { action: 'rotate', id, name: parsed.name || undefined },
+      { env, home: options.home, bearer: authority.value, fetchImpl: options.fetchImpl, refreshImpl: options.refreshImpl },
+    );
+    const secret = response?.secret_once;
+    if (!secret) throw new Error('host_did_not_return_secret_once');
+    const storage = storeSecretLocally(secret, { ...options, store: parsed.store === 'none' ? 'keychain' : parsed.store });
+    const result = {
+      ok: true,
+      credential: response.credential,
+      storage: storage.storage,
+      storage_label: 'OS keychain / vault',
+      activated: true,
+    };
+    if (parsed.json) writeLine(write, JSON.stringify({ ...result, secret_once: secret }, null, 2));
+    else write(renderCreate({ ...result, secret_once: undefined }));
+    return result;
+  }
+
+  if (parsed.command === 'revoke') {
+    if (!parsed.id) throw new Error('api-key revoke requires --id <credential_id>');
+    const authority = await requireAuthority(options);
+    const post = options.postJsonImpl || postJson;
+    const response = await post(
+      '/api/sdk/api-keys',
+      { action: 'revoke', id: parsed.id },
+      { env, home: options.home, bearer: authority.value, fetchImpl: options.fetchImpl, refreshImpl: options.refreshImpl },
+    );
+    if (parsed.json) writeLine(write, JSON.stringify(response, null, 2));
+    else {
+      writeLine(write, '');
+      writeLine(write, response?.ok ? '  ✓ credential revoked' : '  revoke failed');
+      writeLine(write, '');
+    }
+    return response;
+  }
+
+  throw new Error(`unknown api-key command: ${parsed.command}`);
+}

package/src/commands/app.js

@@ -4,43 +4,81 @@ 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 = readJson(manifestPath);
+    return {
+      id: manifest.id || fallbackId,
+      name: manifest.name || fallbackId,
+      dir: path.dirname(manifestPath),
+      manifestPath,
+      bin: manifest.bin || null,
+      commands: manifest.commands || {},
+      manifest,
+    };
+  } catch {
+    return null;
+  }
+}
+
 export function listAppManifests(root = REPO_ROOT) {
-  const appsRoot = path.join(root, 'apps');
-  if (!fs.existsSync(appsRoot)) return [];
-  return fs.readdirSync(appsRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => {
-      const dir = path.join(appsRoot, entry.name);
-      const manifestPath = path.join(dir, 'agentsam.app.json');
-      if (!fs.existsSync(manifestPath)) return null;
-      try {
-        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-        return {
-          id: manifest.id || entry.name,
-          name: manifest.name || entry.name,
-          dir,
-          manifestPath,
-          bin: manifest.bin || null,
-          commands: manifest.commands || {},
-          manifest,
-        };
-      } catch {
-        return null;
-      }
-    })
-    .filter(Boolean)
-    .sort((a, b) => a.id.localeCompare(b.id));
+  const out = [];
+  const seen = new Set();
+
+  function addFromDir(parent, entryName) {
+    const dir = path.join(parent, entryName);
+    const manifestPath = path.join(dir, 'agentsam.app.json');
+    if (!fs.existsSync(manifestPath)) return;
+    const row = readManifest(manifestPath, entryName);
+    if (!row || seen.has(row.id)) return;
+    seen.add(row.id);
+    out.push(row);
+  }
+
+  for (const parentName of ['apps', 'packages']) {
+    const parent = path.join(root, parentName);
+    if (!fs.existsSync(parent)) continue;
+    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      addFromDir(parent, entry.name);
+    }
+  }
+
+  return out.sort((a, b) => a.id.localeCompare(b.id));
 }
 
 function resolveApp(id, root = REPO_ROOT) {
   const apps = listAppManifests(root);
   const hit = apps.find((row) => row.id === id || path.basename(row.dir) === id);
-  if (!hit) throw new Error(`unknown AgentSam app: ${id}`);
+  if (!hit) {
+    const available = apps.map((a) => a.id).join(', ') || '(none)';
+    throw new Error(`unknown AgentSam app: ${id}. Available: ${available}`);
+  }
   return hit;
 }
 
@@ -56,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;
@@ -63,6 +359,9 @@ 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>',
       'agentsam app scaffold <id> <dir>',
@@ -75,19 +374,56 @@ export async function runApp(argv = [], options = {}) {
     const apps = listAppManifests(options.root || REPO_ROOT);
     write('\n  AgentSam apps\n\n');
     for (const app of apps) {
-      write(`  • ${app.id.padEnd(20)} ${app.name}\n`);
+      write(`  • ${app.id.padEnd(24)} ${app.name}\n`);
     }
     write('\n');
     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;
   }
+  if (command === 'install') {
+    const curl =
+      app.manifest?.install?.curl ||
+      `curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --app-id ${app.id}`;
+    const npmCmd =
+      app.manifest?.install?.command ||
+      (app.manifest?.package ? `npm install ${app.manifest.package}` : null);
+    write(`\n  Install ${app.id}\n\n`);
+    if (npmCmd) write(`  ${npmCmd}\n`);
+    write(`  ${curl}\n\n`);
+    write('  app_id is stable product identity. Pass --app-id explicitly; no AGENTSAM_DEFAULT_APP.\n\n');
+    return { id: app.id, curl, command: npmCmd };
+  }
   if (command === 'doctor' || command === 'preview') {
     runAppBin(app, [command, ...rest], options);
     return;
@@ -100,7 +436,7 @@ export async function runApp(argv = [], options = {}) {
 }
 
 export function appCommandHelp() {
-  return 'agentsam app list|info|doctor|preview|scaffold';
+  return 'agentsam app list|info|inspect|validate|install|doctor|preview|scaffold';
 }
 
 export { clean };