openyida 2026.7.21 → 2026.7.23-1

package/lib/app/services/form-compiler.js

@@ -509,6 +509,9 @@ const SUPPORTED_FIELD_TYPES = Object.freeze([
 ]);
 
 function normalizeFieldType(fieldType) {
+  if (fieldType === undefined || fieldType === null || fieldType === '') {
+    return '';
+  }
   return FIELD_TYPE_ALIAS[fieldType] || fieldType;
 }
 
@@ -520,6 +523,57 @@ function isOptionFieldType(fieldType) {
   return OPTION_FIELD_TYPES.indexOf(normalizeFieldType(fieldType)) !== -1;
 }
 
+function readFieldDefinitionType(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    return '';
+  }
+  if (field.type !== undefined && field.type !== null && field.type !== '') {
+    return String(field.type).trim();
+  }
+  if (field.componentType !== undefined && field.componentType !== null && field.componentType !== '') {
+    return String(field.componentType).trim();
+  }
+  if (field.componentName !== undefined && field.componentName !== null && field.componentName !== '') {
+    return String(field.componentName).trim();
+  }
+  return '';
+}
+
+function assertSupportedFieldDefinition(field, details) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    throw createFormCompilerError(
+      '字段定义必须是对象',
+      'FORM_COMPILER_INVALID_DEFINITION',
+      details
+    );
+  }
+  const rawType = readFieldDefinitionType(field);
+  const componentName = normalizeFieldType(rawType);
+  if (!componentName) {
+    throw createFormCompilerError(
+      '字段定义缺少 type/componentType/componentName',
+      'FORM_COMPILER_FIELD_TYPE_MISSING',
+      Object.assign({
+        label: field.label,
+        title: field.title,
+      }, details)
+    );
+  }
+  if (!isSupportedFieldType(componentName)) {
+    throw createFormCompilerError(
+      '不支持的字段类型: ' + componentName,
+      'FORM_COMPILER_UNSUPPORTED_FIELD_TYPE',
+      Object.assign({
+        label: field.label,
+        title: field.title,
+        type: rawType,
+        componentName,
+      }, details)
+    );
+  }
+  return componentName;
+}
+
 const COMPONENT_ALIAS_META = Symbol('openyida.componentAlias');
 
 function normalizeComponentAlias(field) {
@@ -544,7 +598,9 @@ function normalizeComponentAlias(field) {
 
 function buildFieldComponent(field, options) {
   const compilerOptions = createCompilerOptions(options);
-  const componentName = normalizeFieldType(field.type);
+  const componentName = assertSupportedFieldDefinition(field, {
+    semanticPath: compilerOptions.semanticPath,
+  });
   const semanticKey = normalizeSemanticKey(field);
   if (semanticKey && compilerOptions.requireParentSemanticPath && !compilerOptions.semanticPath) {
     throw createFormCompilerError(
@@ -1139,10 +1195,16 @@ function buildFieldComponent(field, options) {
 function collectComponentNames(fields) {
   const names = new Set(['Page', 'RootHeader', 'RootContent', 'RootFooter', 'FooterYida', 'FormContainer']);
   fields.forEach(function (field) {
-    names.add(field.type);
-    if (field.type === 'TableField' && field.children) {
+    const componentName = normalizeFieldType(readFieldDefinitionType(field));
+    if (componentName) {
+      names.add(componentName);
+    }
+    if (componentName === 'TableField' && field.children) {
       field.children.forEach(function (child) {
-        names.add(child.type);
+        const childComponentName = normalizeFieldType(readFieldDefinitionType(child));
+        if (childComponentName) {
+          names.add(childComponentName);
+        }
       });
     }
   });

package/lib/core/agent-capabilities.js

@@ -24,6 +24,247 @@ function compactLogin(login) {
   };
 }
 
+function isTruthyEnv(value) {
+  return ['1', 'true', 'yes', 'on'].includes(String(value || '').trim().toLowerCase());
+}
+
+function hasEnvTokenCredential(env = process.env) {
+  return !!(
+    String(env.OPENYIDA_ACCESS_TOKEN || '').trim() ||
+    String(env.OPENYIDA_REFRESH_TOKEN || '').trim()
+  );
+}
+
+const BUILDER_CORE_COMMAND_IDS = Object.freeze([
+  'agent-capabilities',
+  'commands',
+  'app-list',
+  'list-forms',
+  'get-schema',
+  'create-app',
+  'create-form.create',
+  'create-page',
+  'publish',
+]);
+
+function commandBriefs(manifest, commandIds) {
+  const byId = new Map((manifest.commands || []).map(entry => [entry.id, entry]));
+  return commandIds
+    .map(id => byId.get(id))
+    .filter(Boolean)
+    .map(entry => ({
+      id: entry.id,
+      usage: entry.usage,
+      requires_login: entry.requires_login,
+      output: entry.output,
+      permission_mode: entry.permission && entry.permission.mode,
+      side_effect_kind: entry.side_effect && entry.side_effect.kind,
+    }));
+}
+
+function forbiddenAliasBriefs(manifest) {
+  return (manifest.forbidden_aliases || []).map(entry => ({
+    pattern: entry.pattern,
+    matcher: entry.matcher,
+    suggested_command_id: entry.suggested_command_id,
+    suggested_usage: entry.suggested_usage,
+    alternative_command_ids: entry.alternative_command_ids || [],
+    alternative_usages: entry.alternative_usages || [],
+    message_key: entry.message_key,
+    message_args: entry.message_args || [],
+    message: entry.message,
+  }));
+}
+
+function buildAuthFastPath(login, env = process.env) {
+  const hostInjectedTokenMode = isTruthyEnv(env.YIDA_AUTH_ENABLED);
+  const envTokenPresent = hasEnvTokenCredential(env);
+  const authSource = login.auth_source || (hostInjectedTokenMode || envTokenPresent ? 'env' : 'token_session');
+  const hostTokenEnvDetected = hostInjectedTokenMode || envTokenPresent || authSource === 'env';
+
+  return {
+    mode: login.auth_mode || 'token',
+    source: authSource,
+    can_auto_use: login.can_auto_use === true,
+    host_injected_token_mode: hostInjectedTokenMode,
+    host_token_env_detected: hostTokenEnvDetected,
+    env_token_present: envTokenPresent,
+    interactive_login_allowed: !hostTokenEnvDetected,
+    browser_session_auth_allowed: false,
+    auth_runtime: 'token_oauth_session',
+    cookie_auth_supported: false,
+    cookie_check_required: false,
+    playwright_cookie_check_required: false,
+    qr_login_required: false,
+    prohibited_legacy_checks: [
+      'browser_cookie',
+      'playwright_cookie',
+      'qr_login',
+      'cookie_cache',
+    ],
+    missing_token_action: hostInjectedTokenMode
+      ? 'STOP_AND_REQUEST_HOST_TOKEN'
+      : 'RUN_OPENYIDA_LOGIN_IF_USER_APPROVES',
+  };
+}
+
+function buildBuilderFastPath(login, projectRoot, manifest, env = process.env) {
+  const auth = buildAuthFastPath(login, env);
+  const canTrustSummaryPreflight = auth.can_auto_use === true || auth.host_injected_token_mode === true;
+
+  return {
+    schema_version: 1,
+    preflight: {
+      recommended_command: 'openyida agent-capabilities --summary-json',
+      run_once: true,
+      additional_env_check_default: false,
+      additional_login_check_default: false,
+      trust_summary_json_as_builder_preflight: true,
+      full_capabilities_command: 'openyida agent-capabilities --json',
+      full_capabilities_only_when: 'Need full command_manifest.commands, forbidden_aliases, or detailed environment diagnostics.',
+    },
+    auth,
+    environment_check_simplification: {
+      contract_role: 'machine_readable_fast_path_for_builder_runtime_not_yida_agent_business_logic',
+      minimal_probe_commands: [
+        'which openyida',
+        'openyida agent-capabilities --summary-json',
+      ],
+      can_skip_default_exploration_when_summary_ok: canTrustSummaryPreflight,
+      skip_default_command_patterns: [
+        'openyida --help',
+        'openyida <command> --help',
+        'openyida env --json',
+        'openyida login --check-only --json',
+        'browser login',
+        'qr login',
+        'Playwright cookie inspection',
+        'cookie cache inspection',
+        'openyida app-list',
+      ],
+      skip_help_discovery_default: true,
+      skip_env_noise_default: true,
+      skip_login_check_only_default: canTrustSummaryPreflight,
+      skip_browser_login_default: auth.host_token_env_detected,
+      skip_cookie_or_playwright_checks_default: true,
+      default_app_list_policy: 'skip_when_bound_app_type_unique',
+      stop_when_host_token_missing: auth.host_injected_token_mode && !auth.env_token_present,
+    },
+    command_contract: {
+      command_prefix: manifest.command_prefix,
+      supported_command_count: manifest.commands.length,
+      supported_command_ids: manifest.commands.map(entry => entry.id),
+      canonical_builder_commands: commandBriefs(manifest, BUILDER_CORE_COMMAND_IDS),
+      forbidden_aliases_available_in: 'openyida commands --json',
+      forbidden_alias_count: manifest.forbidden_aliases.length,
+      forbidden_aliases: forbiddenAliasBriefs(manifest),
+      unknown_command_policy: 'deny_with_manifest_suggestion_before_asking_user',
+    },
+    bound_context: {
+      existing_app_type_policy: 'do_not_call_app_list_by_default',
+      skip_app_list_when: [
+        'appType is already provided by the user',
+        'a bound app context is already available',
+      ],
+      call_app_list_only_when: [
+        'name_search',
+        'target_conflict',
+        'failure_diagnosis',
+      ],
+    },
+    resource_context_resolution: {
+      contract_role: 'structured_runtime_hint_not_skill_stage_rewrite',
+      if_bound_app_type_unique: {
+        action: 'reuse_bound_app_type',
+        command: null,
+        skip_command_ids: ['app-list'],
+      },
+      app_name_search: {
+        command_id: 'app-list',
+        usage: 'openyida app-list [--size N]',
+      },
+      app_forms_or_pages_lookup: {
+        command_id: 'list-forms',
+        usage: 'openyida list-forms <appType> [--keyword <text>]',
+      },
+      schema_or_field_lookup: {
+        command_id: 'get-schema',
+        usages: [
+          'openyida get-schema <appType> <formUuid> --summary-json',
+          'openyida get-schema <appType> --all --summary-json --keyword <text> --output-dir .cache/openyida/<task>/schemas',
+        ],
+      },
+      preflight_context: {
+        command_id: 'agent-capabilities',
+        usage: 'openyida agent-capabilities --summary-json',
+      },
+    },
+    paths: {
+      workdir: projectRoot,
+      page_source_cli_path_policy: 'If builder Bash cwd is the project/ directory, pass page source paths as pages/src/<file>.',
+      page_source_examples: [
+        'pages/src/home.canvas.jsx',
+        'pages/src/dashboard.oyd.jsx',
+      ],
+    },
+  };
+}
+
+function compactBuilderFastPath(builderFastPath) {
+  const environment = builderFastPath.environment_check_simplification;
+  const commandContract = builderFastPath.command_contract;
+  const resourceContext = builderFastPath.resource_context_resolution;
+  const paths = builderFastPath.paths;
+
+  return {
+    schema_version: builderFastPath.schema_version,
+    preflight: builderFastPath.preflight,
+    auth: {
+      mode: builderFastPath.auth.mode,
+      source: builderFastPath.auth.source,
+      can_auto_use: builderFastPath.auth.can_auto_use,
+      host_injected_token_mode: builderFastPath.auth.host_injected_token_mode,
+      host_token_env_detected: builderFastPath.auth.host_token_env_detected,
+      env_token_present: builderFastPath.auth.env_token_present,
+      interactive_login_allowed: builderFastPath.auth.interactive_login_allowed,
+      browser_session_auth_allowed: builderFastPath.auth.browser_session_auth_allowed,
+      auth_runtime: builderFastPath.auth.auth_runtime,
+      cookie_auth_supported: builderFastPath.auth.cookie_auth_supported,
+      cookie_check_required: builderFastPath.auth.cookie_check_required,
+      playwright_cookie_check_required: builderFastPath.auth.playwright_cookie_check_required,
+      qr_login_required: builderFastPath.auth.qr_login_required,
+      missing_token_action: builderFastPath.auth.missing_token_action,
+    },
+    environment_check_simplification: {
+      minimal_probe_commands: environment.minimal_probe_commands,
+      can_skip_default_exploration_when_summary_ok: environment.can_skip_default_exploration_when_summary_ok,
+      skip_login_check_only_default: environment.skip_login_check_only_default,
+      skip_browser_login_default: environment.skip_browser_login_default,
+      skip_cookie_or_playwright_checks_default: environment.skip_cookie_or_playwright_checks_default,
+      stop_when_host_token_missing: environment.stop_when_host_token_missing,
+      default_app_list_policy: environment.default_app_list_policy,
+    },
+    command_contract: {
+      command_prefix: commandContract.command_prefix,
+      supported_command_count: commandContract.supported_command_count,
+      canonical_builder_command_ids: commandContract.canonical_builder_commands.map(entry => entry.id),
+      forbidden_aliases_available_in: commandContract.forbidden_aliases_available_in,
+      forbidden_alias_count: commandContract.forbidden_alias_count,
+      unknown_command_policy: commandContract.unknown_command_policy,
+    },
+    bound_context: {
+      existing_app_type_policy: builderFastPath.bound_context.existing_app_type_policy,
+    },
+    resource_context_resolution: {
+      if_bound_app_type_unique: resourceContext.if_bound_app_type_unique,
+      full_contract_in: 'openyida agent-capabilities --json',
+    },
+    paths: {
+      page_source_cli_path_policy: paths.page_source_cli_path_policy,
+    },
+  };
+}
+
 function canonicalize(value) {
   if (Array.isArray(value)) {
     return value.map(canonicalize);
@@ -47,10 +288,16 @@ function buildCommandManifestDigest(manifest) {
     summary: {
       command_count: manifest.summary.command_count,
       group_count: manifest.summary.group_count,
+      forbidden_alias_count: manifest.summary.forbidden_alias_count,
       side_effect_counts: manifest.summary.side_effect_counts,
       permission_mode_counts: manifest.summary.permission_mode_counts,
       core_workflows: manifest.summary.core_workflows,
     },
+    forbidden_aliases: (manifest.forbidden_aliases || []).map(entry => ({
+      pattern: entry.pattern,
+      suggested_command_id: entry.suggested_command_id,
+      suggested_usage: entry.suggested_usage,
+    })),
     commands: manifest.commands.map(entry => ({
       id: entry.id,
       usage: entry.usage,
@@ -73,6 +320,9 @@ function buildAgentCapabilitiesSummary() {
   const manifest = buildCommandManifest({ t, version });
   const projectRoot = envSnapshot.active.projectRoot;
   const loginStatus = getAuthStatus({ projectRoot, includeSecrets: false });
+  const builderFastPath = compactBuilderFastPath(
+    buildBuilderFastPath(loginStatus, projectRoot, manifest)
+  );
 
   return {
     schema_version: 1,
@@ -87,6 +337,7 @@ function buildAgentCapabilitiesSummary() {
     command_manifest_digest_algorithm: 'sha256',
     command_count: manifest.summary.command_count,
     full_capabilities_command: 'openyida agent-capabilities --json',
+    builder_fast_path: builderFastPath,
   };
 }
 
@@ -95,6 +346,7 @@ function buildAgentCapabilities() {
   const manifest = buildCommandManifest({ t, version });
   const projectRoot = envSnapshot.active.projectRoot;
   const loginStatus = redactLogin(getAuthStatus({ projectRoot, includeSecrets: false }));
+  const builderFastPath = buildBuilderFastPath(loginStatus, projectRoot, manifest);
 
   return {
     schema_version: 1,
@@ -116,6 +368,7 @@ function buildAgentCapabilities() {
       openyida_task_cache_dir: path.join(projectRoot, '.cache', 'openyida'),
       default_full_app_workflow: manifest.summary.core_workflows.full_app_fast_build,
     },
+    builder_fast_path: builderFastPath,
     skills: {
       index_file: 'skills-index.json',
       entry: 'openyida',
@@ -134,6 +387,8 @@ function buildAgentCapabilities() {
       ask_command_ids: manifest.summary.ask_command_ids,
       deny_command_ids: manifest.summary.deny_command_ids,
       core_workflows: manifest.summary.core_workflows,
+      forbidden_alias_count: manifest.summary.forbidden_alias_count,
+      forbidden_alias_patterns: manifest.summary.forbidden_alias_patterns,
     },
     sideEffects: {
       read_only_preflight: [
@@ -153,6 +408,8 @@ function buildAgentCapabilities() {
       groups: manifest.groups,
       side_effect_schema: manifest.side_effect_schema,
       permission_schema: manifest.permission_schema,
+      forbidden_alias_schema: manifest.forbidden_alias_schema,
+      forbidden_aliases: manifest.forbidden_aliases,
       summary: manifest.summary,
       commands: manifest.commands,
     },
@@ -173,6 +430,7 @@ async function run(args = []) {
 module.exports = {
   buildAgentCapabilities,
   buildAgentCapabilitiesSummary,
+  compactBuilderFastPath,
   buildCommandManifestDigest,
   run,
 };

package/lib/core/command-manifest.js

@@ -77,6 +77,26 @@ const PERMISSION_SCHEMA = Object.freeze({
   },
 });
 
+const FORBIDDEN_ALIAS_SCHEMA = Object.freeze({
+  version: 1,
+  fields: {
+    pattern: 'Human-readable forbidden argv pattern. Match against arguments after openyida/yida.',
+    matcher: 'Structured matcher for agents that need deterministic deny decisions.',
+    suggested_command_id: 'Canonical command id to run instead.',
+    suggested_usage: 'Concrete canonical OpenYida usage to show or execute after parameter correction.',
+    alternative_command_ids: 'Optional extra command ids when the alias is ambiguous.',
+    alternative_usages: 'Optional concrete usages for alternative command ids.',
+    message_key: 'i18n key for the explanation suitable for a CLI hint or agent denial reason.',
+    message_args: 'Arguments for message_key interpolation.',
+    message: 'Localized explanation generated from message_key when a translator is available.',
+  },
+  matcher_types: {
+    argv_prefix: 'Deny when the invocation argv begins with matcher.tokens.',
+    command_has_option: 'Deny when matcher.command is the command root and matcher.option appears anywhere in argv.',
+  },
+  agent_policy: 'Deny forbidden aliases before asking the user; return suggested_command_id and suggested_usage as the repair hint.',
+});
+
 function sideEffect(kind, overrides = {}) {
   if (!SIDE_EFFECT_BASES[kind]) {
     throw new Error('Unknown side effect kind: ' + kind);
@@ -142,6 +162,46 @@ function clonePermissionSchema() {
   return JSON.parse(JSON.stringify(PERMISSION_SCHEMA));
 }
 
+function cloneForbiddenAliasSchema() {
+  return JSON.parse(JSON.stringify(FORBIDDEN_ALIAS_SCHEMA));
+}
+
+function cloneMatcher(matcher) {
+  if (!matcher || typeof matcher !== 'object') {
+    return matcher;
+  }
+  const cloned = { ...matcher };
+  if (Array.isArray(matcher.tokens)) {
+    cloned.tokens = [...matcher.tokens];
+  }
+  return cloned;
+}
+
+function cloneForbiddenAlias(entry) {
+  const cloned = {
+    ...entry,
+    matcher: cloneMatcher(entry.matcher),
+  };
+  if (Array.isArray(entry.alternative_command_ids)) {
+    cloned.alternative_command_ids = [...entry.alternative_command_ids];
+  }
+  if (Array.isArray(entry.alternative_usages)) {
+    cloned.alternative_usages = [...entry.alternative_usages];
+  }
+  if (Array.isArray(entry.message_args)) {
+    cloned.message_args = [...entry.message_args];
+  }
+  return cloned;
+}
+
+function localizeForbiddenAlias(entry, translate) {
+  const localized = cloneForbiddenAlias(entry);
+  if (localized.message_key) {
+    localized.message = translate(localized.message_key, ...(localized.message_args || []));
+  }
+  return localized;
+}
+
 function normalizePermission(metadata, sideEffectMetadata) {
   const normalized = { ...metadata };
   if (sideEffectMetadata && sideEffectMetadata.kind === 'mixed') {
@@ -185,6 +245,114 @@ function listCommandPermissionIds() {
   return [...COMMAND_PERMISSIONS.keys()].sort();
 }
 
+function normalizeInvocationArgv(argv = []) {
+  const normalized = (Array.isArray(argv) ? argv : [])
+    .map(value => String(value || '').trim())
+    .filter(Boolean);
+  if (normalized[0] === 'openyida' || normalized[0] === 'yida') {
+    return normalized.slice(1);
+  }
+  return normalized;
+}
+
+function matcherMatchesArgv(argv, matcher) {
+  const normalized = normalizeInvocationArgv(argv);
+  if (!matcher || typeof matcher !== 'object' || normalized.length === 0) {
+    return false;
+  }
+
+  if (matcher.type === 'argv_prefix') {
+    const tokens = Array.isArray(matcher.tokens) ? matcher.tokens : [];
+    return tokens.length > 0 && tokens.every((token, index) => normalized[index] === token);
+  }
+
+  if (matcher.type === 'command_has_option') {
+    return normalized[0] === matcher.command && normalized.includes(matcher.option);
+  }
+
+  return false;
+}
+
+function findForbiddenAliasSuggestion(argv = []) {
+  const match = FORBIDDEN_ALIASES.find(entry => matcherMatchesArgv(argv, entry.matcher));
+  return match ? cloneForbiddenAlias(match) : null;
+}
+
+function levenshteinDistance(left, right) {
+  const a = String(left || '');
+  const b = String(right || '');
+  const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) {
+    dp[i][0] = i;
+  }
+  for (let j = 0; j <= b.length; j++) {
+    dp[0][j] = j;
+  }
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+function findNearestCommandSuggestion(argv = []) {
+  const normalized = normalizeInvocationArgv(argv);
+  const root = normalized[0];
+  if (!root) {
+    return null;
+  }
+
+  const candidates = new Map();
+  for (const entry of flattenCommandManifest()) {
+    if (!entry.hidden && entry.path && entry.path[0] && !candidates.has(entry.path[0])) {
+      candidates.set(entry.path[0], entry);
+    }
+    for (const alias of entry.aliases || []) {
+      const aliasRoot = String(alias || '').trim().split(/\s+/)[0];
+      if (aliasRoot && !candidates.has(aliasRoot)) {
+        candidates.set(aliasRoot, entry);
+      }
+    }
+  }
+
+  if (candidates.has(root)) {
+    return null;
+  }
+
+  let best = null;
+  for (const [candidate, entry] of candidates) {
+    const distance = levenshteinDistance(root, candidate);
+    if (!best || distance < best.distance) {
+      best = { candidate, entry, distance };
+    }
+  }
+
+  const threshold = Math.max(2, Math.floor(root.length / 3));
+  if (!best || best.distance > threshold) {
+    return null;
+  }
+
+  return {
+    id: `nearest.${root}`,
+    pattern: root,
+    matcher: { type: 'argv_prefix', tokens: [root] },
+    suggested_command_id: best.entry.id,
+    suggested_usage: `openyida ${best.entry.usage}`,
+    message_key: 'cli.nearest_command_suggestion',
+    message_args: [root, best.candidate],
+  };
+}
+
+function findCommandSuggestion(argv = []) {
+  return findForbiddenAliasSuggestion(argv) || findNearestCommandSuggestion(argv);
+}
+
 const COMMAND_SIDE_EFFECTS = new Map([
   ...sideEffectEntries([
     'agent-capabilities',
@@ -723,6 +891,68 @@ const COMMAND_PERMISSIONS = new Map([
   })),
 ]);
 
+const FORBIDDEN_ALIASES = Object.freeze([
+  Object.freeze({
+    id: 'forbidden-alias.list-apps',
+    pattern: 'list-apps',
+    matcher: { type: 'argv_prefix', tokens: ['list-apps'] },
+    suggested_command_id: 'app-list',
+    suggested_usage: 'openyida app-list [--size N]',
+    message_key: 'cli.forbidden_alias_list_apps',
+    message_args: ['list-apps', 'app-list'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.get-app',
+    pattern: 'get-app',
+    matcher: { type: 'argv_prefix', tokens: ['get-app'] },
+    suggested_command_id: 'app-list',
+    suggested_usage: 'openyida app-list [--size N]',
+    alternative_command_ids: ['get-schema', 'agent-capabilities'],
+    alternative_usages: [
+      'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+      'openyida agent-capabilities --summary-json',
+    ],
+    message_key: 'cli.forbidden_alias_get_app',
+    message_args: ['get-app', 'app-list', 'get-schema', 'agent-capabilities'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.create-app-json',
+    pattern: 'create-app --json',
+    matcher: { type: 'command_has_option', command: 'create-app', option: '--json' },
+    suggested_command_id: 'create-app',
+    suggested_usage: 'openyida create-app "<name>"|--name <name> [options] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]',
+    message_key: 'cli.forbidden_alias_create_app_json',
+    message_args: ['create-app --json', 'create-app'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.create-page-app-type-option',
+    pattern: 'create-page --app-type',
+    matcher: { type: 'command_has_option', command: 'create-page', option: '--app-type' },
+    suggested_command_id: 'create-page',
+    suggested_usage: 'openyida create-page <appType> "<name>" [--mode dashboard] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]',
+    message_key: 'cli.forbidden_alias_create_page_app_type_option',
+    message_args: ['create-page', '--app-type'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.get-schema-app-type-option',
+    pattern: 'get-schema --app-type',
+    matcher: { type: 'command_has_option', command: 'get-schema', option: '--app-type' },
+    suggested_command_id: 'get-schema',
+    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+    message_key: 'cli.forbidden_alias_get_schema_app_type_option',
+    message_args: ['get-schema', '--app-type'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.get-schema-form-uuid-option',
+    pattern: 'get-schema --form-uuid',
+    matcher: { type: 'command_has_option', command: 'get-schema', option: '--form-uuid' },
+    suggested_command_id: 'get-schema',
+    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+    message_key: 'cli.forbidden_alias_get_schema_form_uuid_option',
+    message_args: ['get-schema', '--form-uuid'],
+  }),
+]);
+
 function command(id, path, usage, descriptionKey, options = {}) {
   const commandSideEffect = COMMAND_SIDE_EFFECTS.get(id);
   if (!commandSideEffect) {
@@ -1069,6 +1299,8 @@ function summarizeLocalizedCommands(commands) {
   return {
     command_count: commands.length,
     group_count: COMMAND_GROUPS.length,
+    forbidden_alias_count: FORBIDDEN_ALIASES.length,
+    forbidden_alias_patterns: FORBIDDEN_ALIASES.map(entry => entry.pattern),
     side_effect_counts: sideEffectCounts,
     ids_by_side_effect: idsBySideEffect,
     read_only_command_ids: readOnlyCommandIds,
@@ -1138,6 +1370,8 @@ function buildCommandManifest(options = {}) {
     })),
     side_effect_schema: cloneSideEffectSchema(),
     permission_schema: clonePermissionSchema(),
+    forbidden_alias_schema: cloneForbiddenAliasSchema(),
+    forbidden_aliases: FORBIDDEN_ALIASES.map(entry => localizeForbiddenAlias(entry, translate)),
     summary: summarizeLocalizedCommands(localizedCommands),
     commands: localizedCommands,
   };
@@ -1146,6 +1380,8 @@ function buildCommandManifest(options = {}) {
 module.exports = {
   COMMAND_GROUPS,
   buildCommandManifest,
+  findCommandSuggestion,
+  findForbiddenAliasSuggestion,
   flattenCommandManifest,
   listCommandPermissionIds,
   listCommandSideEffectIds,