@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/src/cli/diagnostic-command.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { Command } = require('commander');
+const { InputIssueError, bindError, modelAt, constraints } = require('../execution/error-details');
+
+class DiagnosticCommand extends Command {
+  constructor(name, { path, schema, optionPaths = {}, parameterCategory = 'validation' }) {
+    super(name);
+    this.diagnosticContext = { command: this, path, schema, optionPaths, parameterCategory };
+    this.exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw this.issue('constraint');
+    });
+  }
+
+  issue(reason, option) {
+    const context = this.diagnosticContext;
+    const attribute = option?.attributeName();
+    const mapped = Object.entries(context.optionPaths).find(([, value]) => value === attribute)?.[0];
+    const path = mapped || (attribute && modelAt(context.schema, 'input', `/${attribute}`) ? `/${attribute}` : undefined);
+    const expected = option?.argChoices ? { enum: [...option.argChoices] } :
+      path ? constraints(modelAt(context.schema, 'input', path)) : undefined;
+    return bindError(new InputIssueError([{ source: 'argv', reason,
+      ...(option ? { option: option.long || option.short } : {}),
+      ...(path ? { path } : {}), ...(expected ? { expected } : {}) }]), context);
+  }
+
+  addOption(option) {
+    const parse = option.parseArg;
+    if (parse) option.argParser((value, previous) => {
+      try { return parse.call(option, value, previous); }
+      catch (error) {
+        if (error.code === 'commander.invalidArgument') throw this.issue('invalid_choice', option);
+        throw error;
+      }
+    });
+    return super.addOption(option);
+  }
+
+  missingMandatoryOptionValue(option) { throw this.issue('required', option); }
+  optionMissingArgument(option) { throw this.issue('missing_value', option); }
+  missingArgument() { throw this.issue('required'); }
+  unknownOption() { throw this.issue('unknown_option'); }
+  unknownCommand() { throw this.issue('unknown_command'); }
+  _excessArguments() {
+    if (!this._allowExcessArguments) throw this.issue('excess_arguments');
+  }
+
+  action(handler) {
+    return super.action(async (...args) => {
+      try { return await handler.apply(this, args); }
+      catch (error) { throw bindError(error, this.diagnosticContext); }
+    });
+  }
+}
+
+module.exports = { DiagnosticCommand };

package/src/cli/domain-catalog.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { validateSkillFrontmatter } = require('./skill-catalog');
+
+const skillsRoot = path.join(__dirname, '..', '..', 'skills');
+const namePattern = /^[a-z][a-z0-9-]*$/;
+const reservedNames = new Set(['api', 'auth', 'doctor', 'help', 'schema', 'shop', 'skills', 'shared']);
+
+function validDomainName(name) {
+  return namePattern.test(name) && !reservedNames.has(name);
+}
+
+function domainSkillName(domain) {
+  return `zan-saas-${domain}`;
+}
+
+function regularFile(filename) {
+  return fs.lstatSync(filename).isFile();
+}
+
+function loadDomain(root, domain, rootSkills = skillsRoot) {
+  if (!validDomainName(domain)) throw new Error(`Invalid native domain: ${domain}`);
+  const filename = path.join(root, domain, 'domain.json');
+  try {
+    if (!regularFile(filename)) throw new Error(`Invalid domain descriptor: ${domain}`);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`Missing domain descriptor: ${domain}/domain.json`);
+    throw error;
+  }
+  const descriptor = JSON.parse(fs.readFileSync(filename, 'utf8'));
+  if (typeof descriptor.description !== 'string' || !descriptor.description.trim() ||
+      Object.keys(descriptor).some(key => key !== 'description')) {
+    throw new Error(`Invalid domain descriptor: ${domain}`);
+  }
+  const skill = domainSkillName(domain);
+  validateSkillFrontmatter(rootSkills, { name: skill });
+  return { name: domain, description: descriptor.description.trim(), skill };
+}
+
+module.exports = { skillsRoot, validDomainName, domainSkillName, loadDomain };

package/src/cli/help-text.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { Help } = require('commander');
+
+const headings = {
+  Usage: '用法', Arguments: '参数', Options: '选项',
+  'Global Options': '全局选项', Commands: '命令'
+};
+const annotations = { choices: '可选值', default: '默认值', preset: '预设值', env: '环境变量' };
+const positionLabels = { hq: '总部', shop: '店铺', all: '总部、店铺' };
+const riskLabels = { read: '只读', low: '低', medium: '中', high: '高' };
+
+function localizeAnnotations(description) {
+  return description.replace(/(\(|, )(choices|default|preset|env): /g,
+    (_match, separator, name) => `${separator}${annotations[name]}：`);
+}
+
+const chineseHelp = {
+  formatHelp(command, helper) {
+    return Help.prototype.formatHelp.call(this, command, helper)
+      .replace(/^(Usage|Arguments|Options|Global Options|Commands):/gm,
+        (_match, name) => `${headings[name]}：`);
+  },
+  optionDescription(option) {
+    return localizeAnnotations(Help.prototype.optionDescription.call(this, option));
+  },
+  argumentDescription(argument) {
+    return localizeAnnotations(Help.prototype.argumentDescription.call(this, argument));
+  }
+};
+
+module.exports = { chineseHelp, positionLabels, riskLabels };

package/src/cli/native-loader.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  addAtomicCommand, addTaskCommand, registerDomain, publishedDomains, validateAvailability
+} = require('./command-paths');
+const { loadDomain, skillsRoot, validDomainName } = require('./domain-catalog');
+const { loadCommandSchema, attachCommandSchema } = require('../execution/command-schema');
+const { nativeCommandLocation } = require('./native-path');
+const { isDeepStrictEqual } = require('node:util');
+
+const nativeRoot = path.join(__dirname, '..', 'commands', 'native');
+const namePattern = /^[a-z][a-z0-9-]*$/;
+const taskPattern = /^\+[a-z][a-z0-9-]*$/;
+
+function directories(root) {
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .sort();
+}
+
+function discoverNative(root = nativeRoot) {
+  const domains = directories(root);
+  const modules = [];
+  for (const domain of domains) {
+    if (!validDomainName(domain)) {
+      throw new Error(`Invalid native domain: ${domain}`);
+    }
+    const groups = directories(path.join(root, domain));
+    for (const group of groups) {
+      if (group === 'shared') continue;
+      if (taskPattern.test(group)) {
+        modules.push(`${domain}/${group}/command.js`);
+      } else if (namePattern.test(group)) {
+        const actions = directories(path.join(root, domain, group));
+        if (!actions.length) throw new Error(`Native resource has no actions: ${domain}/${group}`);
+        for (const action of actions) {
+          if (!namePattern.test(action)) throw new Error(`Invalid native action: ${action}`);
+          modules.push(`${domain}/${group}/${action}/command.js`);
+        }
+      } else {
+        throw new Error(`Invalid native command group: ${group}`);
+      }
+    }
+  }
+  for (const modulePath of modules) {
+    if (!fs.existsSync(path.join(root, modulePath)) ||
+        !fs.statSync(path.join(root, modulePath)).isFile()) {
+      throw new Error(`Missing native command entry: ${modulePath}`);
+    }
+  }
+  return { domains, modules };
+}
+
+function registerNativeDomains(program, domains) {
+  const registeredDomains = new Set();
+  for (const entry of domains) {
+    if (!validDomainName(entry.name) || registeredDomains.has(entry.name)) {
+      throw new Error(`Invalid native domain manifest entry: ${entry.name}`);
+    }
+    registerDomain(program, entry);
+    registeredDomains.add(entry.name);
+  }
+
+  return registeredDomains;
+}
+
+function registerNativeDomain(program, domain, businessCommands, root = nativeRoot,
+  rootSkills = skillsRoot, context) {
+  const definition = loadDomain(root, domain.name, rootSkills);
+  if (definition.description !== domain.description || definition.skill !== domain.skill) {
+    throw new Error(`Native domain differs from manifest: ${domain.name}`);
+  }
+  if (!publishedDomains(program).some(entry => entry.name === domain.name)) {
+    throw new Error(`Native command has no registered domain: ${domain.name}`);
+  }
+
+  const seen = new Set();
+  for (const entry of businessCommands) {
+    const parts = entry.module.split('/');
+    const location = nativeCommandLocation(entry.module, entry.resourcePath);
+    // A generated manifest is still validated before loading any module.
+    if (!location || entry.path !== location.path || entry.kind !== location.kind || seen.has(entry.path)) {
+      throw new Error(`Invalid native command manifest entry: ${entry.path}`);
+    }
+    seen.add(entry.path);
+    if (parts[0] !== domain.name) {
+      throw new Error(`Native command is in the wrong domain index: ${entry.path}`);
+    }
+    const definition = require(path.join(root, entry.module));
+    const { kind } = location;
+    if (Object.hasOwn(definition, 'mutationRisk') ||
+        !isDeepStrictEqual(definition.resourcePath, entry.resourcePath) ||
+        definition.kind !== kind || definition.risk !== entry.risk ||
+        definition.at !== entry.at ||
+        validateAvailability(definition.availability) !== validateAvailability(entry.availability) ||
+        typeof definition.createCommand !== 'function') {
+      throw new Error(`Native command contract differs from manifest: ${entry.path}`);
+    }
+    const command = definition.createCommand({ context });
+    if (command.name() !== parts[kind === 'task' ? 1 : 2]) {
+      throw new Error(`Native command name differs from directory: ${entry.path}`);
+    }
+    if (!command.description().trim()) {
+      throw new Error(`Native command needs a help description: ${entry.path}`);
+    }
+    attachCommandSchema(command, loadCommandSchema(
+      path.join(root, ...parts.slice(0, -1), 'schema.json')
+    ));
+    if (kind === 'task') {
+      addTaskCommand(program, parts[0], command, entry.risk, entry.at, entry.availability);
+    } else {
+      addAtomicCommand(program, parts[0], location.resources, command, entry.risk, entry.at, entry.availability);
+    }
+  }
+}
+
+module.exports = { nativeRoot, discoverNative, registerNativeDomains, registerNativeDomain };

package/src/cli/native-path.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const namePattern = /^[a-z][a-z0-9-]*$/;
+const taskPattern = /^\+[a-z][a-z0-9-]*$/;
+
+function nativeCommandLocation(modulePath, resourcePath) {
+  if (typeof modulePath !== 'string') return null;
+  const parts = modulePath.split('/');
+  if (!namePattern.test(parts[0]) || parts.at(-1) !== 'command.js') return null;
+  if (parts.length === 3 && taskPattern.test(parts[1]) && resourcePath === undefined) {
+    return { domain: parts[0], kind: 'task', action: parts[1], path: `${parts[0]}.${parts[1]}` };
+  }
+  if (parts.length !== 4 || !namePattern.test(parts[1]) || !namePattern.test(parts[2])) return null;
+  const resources = resourcePath === undefined ? [parts[1]] : resourcePath;
+  if (!Array.isArray(resources) || !resources.length ||
+      !resources.every(value => typeof value === 'string' && namePattern.test(value)) ||
+      resources.join('-') !== parts[1]) return null;
+  return { domain: parts[0], kind: 'atomic', action: parts[2], resources,
+    path: [parts[0], ...resources, parts[2]].join('.') };
+}
+
+module.exports = { nativeCommandLocation };

package/src/cli/parser-policy.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const { Command } = require('commander');
+const { commandPath } = require('./command-paths');
+const { commandSchema } = require('../execution/command-schema');
+const { modelAt, constraints } = require('../execution/error-details');
+const { ParserError } = require('../execution/parser-error');
+
+const parserReasons = {
+  'commander.unknownCommand': 'unknown_command',
+  'commander.unknownOption': 'unknown_option',
+  'commander.missingArgument': 'required',
+  'commander.missingMandatoryOptionValue': 'required',
+  'commander.optionMissingArgument': 'missing_value',
+  'commander.invalidArgument': 'invalid_choice',
+  'commander.excessArguments': 'excess_arguments',
+  'commander.conflictingOption': 'constraint'
+};
+const messages = {
+  unknown_command: '未知命令，请查看帮助或候选命令',
+  unknown_option: '命令中有不支持的选项，请查看此命令 --help',
+  excess_arguments: '命令中有多余的位置参数，请查看此命令 --help',
+  required: '缺少必填参数，请查看此命令 --help',
+  missing_value: '请为参数提供值',
+  invalid_choice: '参数值不在允许范围内，请查看此命令 --help',
+  constraint: '参数组合不符合要求，请查看此命令 --help'
+};
+const safeName = /^(?:[a-z][a-z0-9-]*|\+[a-z][a-z0-9-]*)$/;
+
+function distance(left, right) {
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let i = 0; i < left.length; i++) {
+    const row = [i + 1];
+    for (let j = 0; j < right.length; j++) {
+      row.push(Math.min(row[j] + 1, previous[j + 1] + 1,
+        previous[j] + (left[i] === right[j] ? 0 : 1)));
+    }
+    previous = row;
+  }
+  return previous[right.length];
+}
+
+function suggestedArgv(command, token) {
+  if (typeof token !== 'string' || token.length < 3 || token.length > 64 || !safeName.test(token)) return [];
+  const prefix = commandPath(command).split('.').filter(Boolean);
+  const names = command.createHelp().visibleCommands(command)
+    .flatMap(child => [child.name(), ...child.aliases()]).filter(name => safeName.test(name));
+  const candidates = [...new Set(names)].map(name => ({ name, distance: distance(token, name) }))
+    .filter(candidate => candidate.distance <= (token.length > 5 ? 2 : 1))
+    .sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name, 'en'));
+  return candidates.filter(candidate => candidate.distance === candidates[0].distance)
+    .slice(0, 3).map(candidate => [...prefix, candidate.name]);
+}
+
+function parserFailure(command, reason, { option, argument, token } = {}) {
+  const path = commandPath(command);
+  const helpArgv = [...path.split('.').filter(Boolean), '--help'];
+  const issue = { source: 'argv', reason };
+  const schema = commandSchema(command);
+  const attribute = option?.attributeName() || argument?.name();
+  const modelPath = attribute && `/${attribute}`;
+  const model = schema && modelPath && modelAt(schema, 'input', modelPath);
+  if (option) issue.option = option.long || option.short;
+  if (model) issue.path = modelPath;
+  if (option?.argChoices) issue.expected = { enum: [...option.argChoices] };
+  else if (model && Object.keys(constraints(model)).length) issue.expected = constraints(model);
+  const suggestions = reason === 'unknown_command' ? suggestedArgv(command, token) : [];
+  const message = option && reason === 'required' ? `请提供 ${issue.option}` :
+    option && reason === 'missing_value' ? `请为 ${issue.option} 提供值` :
+    option?.argChoices && reason === 'invalid_choice' ?
+      `${issue.option} 只能使用：${option.argChoices.join('、')}` :
+    argument && reason === 'required' ? `请提供参数 <${argument.name()}>` : messages[reason];
+  return new ParserError(message, {
+    command: path, issues: [issue], helpArgv,
+    ...(suggestions.length ? { suggestions } : {}),
+    nextStep: `${suggestions.length ? `你可能想执行 zan-saas ${suggestions[0].join(' ')}；` : ''}` +
+      `查看帮助：zan-saas ${helpArgv.join(' ')}`
+  });
+}
+
+function configureParserPolicy(prepareHelp) {
+  const installed = new WeakSet();
+  const options = new WeakSet();
+  function install(command) {
+    if (!installed.has(command)) {
+      installed.add(command);
+      const help = command.help;
+      command.help = function(context) {
+        const navigation = context?.error && !this._actionHandler &&
+          !this._defaultCommandName && this.args.length === 0;
+        return help.call(this, navigation ? { error: false } : context);
+      };
+      const error = command.error;
+      command.error = function(message, settings) {
+        const reason = parserReasons[settings?.code];
+        if (reason) throw parserFailure(this, reason);
+        return error.call(this, message, settings);
+      };
+      const methods = {
+        missingMandatoryOptionValue(option) { throw parserFailure(this, 'required', { option }); },
+        optionMissingArgument(option) { throw parserFailure(this, 'missing_value', { option }); },
+        missingArgument(name) {
+          throw parserFailure(this, 'required', {
+            argument: this.registeredArguments.find(argument => argument.name() === name)
+          });
+        },
+        unknownOption() {
+          if (!this._allowUnknownOption) throw parserFailure(this, 'unknown_option');
+        },
+        unknownCommand() {
+          prepareHelp(this);
+          throw parserFailure(this, 'unknown_command', { token: this.args[0] });
+        },
+        _excessArguments() {
+          if (!this._allowExcessArguments) throw parserFailure(this, 'excess_arguments');
+        }
+      };
+      for (const [name, handler] of Object.entries(methods)) {
+        if (command[name] === Command.prototype[name]) command[name] = handler;
+      }
+    }
+    for (const option of command.options) {
+      if (options.has(option)) continue;
+      options.add(option);
+      const parse = option.parseArg;
+      if (parse) option.argParser(function(...args) {
+        try { return parse.apply(this, args); }
+        catch (error) {
+          if (error.code === 'commander.invalidArgument') {
+            throw parserFailure(command, 'invalid_choice', { option });
+          }
+          throw error;
+        }
+      });
+    }
+    for (const child of command.commands) install(child);
+  }
+  return install;
+}
+
+module.exports = { configureParserPolicy, parserFailure };

package/src/cli/program.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const { Command } = require('commander');
+const { version } = require('../../package.json');
+const { createSchemaCommand } = require('../commands/system/schema');
+const { createDoctorCommand } = require('../commands/system/doctor');
+const { createApiCommand } = require('../commands/system/api');
+const { createSkillsCommand } = require('../commands/system/skills');
+const { createInstallCommand } = require('../commands/system/install');
+const { createAuthCommand } = require('../commands/system/auth');
+const { createShopCommand } = require('../commands/system/shop');
+const {
+  registerNativeDomains, registerNativeDomain, nativeRoot
+} = require('./native-loader');
+const { skillsRoot } = require('./domain-catalog');
+const { validateSkillCatalog } = require('./skill-catalog');
+const { openRegistry } = require('../../internal/registry');
+const { readContext } = require('../identity/context');
+const { contextInput } = require('../identity/context-store');
+const { assertAvailable } = require('../execution/command-policy');
+const { commandSchema } = require('../execution/command-schema');
+const { commandContract, commandPath } = require('./command-paths');
+const { configureContextHelp, isContextHelp } = require('./context-help');
+const { configureParserPolicy } = require('./parser-policy');
+
+function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills = skillsRoot,
+  eagerDomains = false, context = contextInput(process.env) } = {}) {
+  const { domains, skills, businessCommandCount } = catalog.manifest;
+  const domainNames = new Set(domains.map(domain => domain.name));
+  const loadedDomains = new Set();
+  const program = new Command();
+  const contextState = readContext(context);
+  const installParsing = configureParserPolicy(prepareHelp);
+  const installHelp = configureContextHelp(program, contextState, loadDomain);
+
+  function loadDomain(name) {
+    if (loadedDomains.has(name)) return;
+    const domain = domains.find(entry => entry.name === name);
+    if (!domain) return;
+    const index = catalog.loadDomain(name);
+    registerNativeDomain(program, domain, index.businessCommands, root, rootSkills,
+      contextState.context);
+    loadedDomains.add(name);
+    installHelp();
+    installParsing(program);
+  }
+
+  program.name('zan-saas')
+    .description('有赞 SaaS 命令行工具')
+    .version(version, '-V, --version', '显示版本号')
+    .exitOverride()
+    .configureOutput({ writeErr: () => {} });
+
+  program.addCommand(createSchemaCommand(() => program, path => {
+    if (!path) {
+      for (const domain of domains) loadDomain(domain.name);
+      return;
+    }
+    const name = path.split('.')[0];
+    if (domainNames.has(name)) loadDomain(name);
+  }));
+  program.addCommand(createDoctorCommand(businessCommandCount));
+  program.addCommand(createApiCommand());
+  program.addCommand(createAuthCommand());
+  program.addCommand(createShopCommand());
+  program.addCommand(createSkillsCommand(skills, rootSkills));
+  program.addCommand(createInstallCommand());
+  function configureSystemErrors(command) {
+    command.exitOverride().configureOutput({ writeErr: program.configureOutput().writeErr });
+    for (const child of command.commands) configureSystemErrors(child);
+  }
+  for (const command of program.commands) configureSystemErrors(command);
+  registerNativeDomains(program, domains);
+  validateSkillCatalog(skills, domains);
+  installHelp();
+  installParsing(program);
+
+  program.hook('preSubcommand', (parent, command) => {
+    if (parent === program && domainNames.has(command.name())) loadDomain(command.name());
+    installHelp(command);
+    installParsing(command);
+  });
+  program.hook('preAction', (_parent, command) => {
+    if (isContextHelp(command)) return;
+    const contract = commandContract(commandPath(command), command);
+    if (['atomic', 'task'].includes(contract.kind)) {
+      const details = commandSchema(command)?.error?.properties?.details;
+      const stages = details?.properties?.stage?.enum;
+      assertAvailable(contract.at, contextState, {
+        dryRun: command.opts().dryRun === true, command: commandPath(command),
+        includeDetails: Boolean(details),
+        contextStage: stages?.includes('configuration') && !stages.includes('context')
+          ? 'configuration' : 'context'
+      });
+    }
+  });
+  function prepareHelp(target) {
+    if (target === program) {
+      for (const domain of domains) loadDomain(domain.name);
+      return;
+    }
+    let command = target;
+    while (command.parent && command.parent !== program) command = command.parent;
+    if (command.parent === program && domainNames.has(command.name())) {
+      loadDomain(command.name());
+    }
+  }
+  program.on('beforeAllHelp', helpContext => prepareHelp(helpContext.command));
+
+  if (skills.some(skill => skill.type === 'entry')) {
+    program.addHelpText('after', `
+快速开始：
+  1. 登录：zan-saas auth login，按提示在浏览器完成授权
+  2. 查看当前店铺：zan-saas shop current；已有有效上下文时沿用
+  3. 需要选店时：zan-saas shop list，按用户指定的店名或选择执行 zan-saas shop use <kdtId>
+  4. 阅读使用指引：zan-saas skills read zan-saas
+
+查询命令：
+  zan-saas help auth login
+  zan-saas help <domain> <resource> <action>
+  zan-saas schema <path>
+命令路径中的各部分须分别传参；也可使用各层命令的 --help。
+
+领域业务命令需要登录凭证和店铺上下文；--dry-run 仅预览，不访问业务接口。
+当前领域业务命令均为只读查询；api 为独立的原始接口入口，调用前查看 zan-saas help api。
+使用指引解释操作方式，可执行命令以当前安装版的 help 和 schema 为准。`);
+  }
+  if (eagerDomains) {
+    for (const domain of domains) loadDomain(domain.name);
+  }
+  return program;
+}
+
+module.exports = { createProgram };