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

package/src/execution/command-io.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const { inputIssue } = require('./error-details');
+
+/**
+ * Shared CLI input parsing, response mapping and module validation.
+ *
+ * Default rules:
+ * - Base result is fixed for each command
+ * - Additional modules via --include when needed (cost, auth, volume differ)
+ * - Success requires all base + requested modules fulfilled
+ * - Structured query output: { data: {...} }
+ * - Unpromised modules omitted; requested must appear on success
+ * - null = queried and confirmed no value/no association
+ * - [] = successfully retrieved empty collection within declared scope
+ * - Empty string reserved for empty text; 0 and false preserved
+ */
+
+/**
+ * Parse --include parameter into normalized module set.
+ * @param {string} includeValue - comma-separated module names
+ * @param {string[]} allowedModules - valid module names for this command
+ * @returns {Set<string>} deduplicated, validated modules
+ */
+function parseIncludeModules(includeValue, allowedModules, diagnosticPath) {
+  function reject(message, reason = 'invalid_format') {
+    if (diagnosticPath) throw inputIssue(diagnosticPath, reason, {
+      type: 'array', items: { enum: allowedModules }
+    });
+    throw new Error(message);
+  }
+  if (includeValue === undefined) return new Set();
+  if (typeof includeValue !== 'string') reject('--include must be text');
+
+  const modules = includeValue
+    .split(',')
+    .map(m => m.trim());
+
+  if (modules.some(module => !module)) {
+    reject('--include must not contain empty values or module names');
+  }
+
+  const moduleSet = new Set(modules);
+  const allowedSet = new Set(allowedModules);
+  const invalid = [...moduleSet].filter(m => !allowedSet.has(m));
+
+  if (invalid.length > 0) {
+    reject(
+      `Unsupported --include modules: ${invalid.join(', ')}. ` +
+      `Allowed: ${allowedModules.join(', ')}`, 'invalid_choice'
+    );
+  }
+
+  return moduleSet;
+}
+
+/**
+ * Validate that requested modules are present in adapted result.
+ * @param {Object} adaptedData - data after upstream adaptation
+ * @param {Set<string>} requestedModules - modules that were requested
+ * @param {string[]} baseModules - modules included by default
+ * @throws {Error} if any required module is missing
+ */
+function validateRequiredModules(adaptedData, requestedModules, baseModules) {
+  const allRequired = new Set([...baseModules, ...requestedModules]);
+  const missing = [];
+
+  for (const module of allRequired) {
+    if (!(module in adaptedData)) {
+      missing.push(module);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Required modules missing from result: ${missing.join(', ')}. ` +
+      `All base and requested modules must be fulfilled for success.`
+    );
+  }
+}
+
+/**
+ * Adapt upstream response to unified model.
+ * Verifies structure and maps to expected modules.
+ * @param {Object} upstreamResult - raw upstream response
+ * @param {Object} moduleMapping - map of module names to upstream paths
+ * @param {Set<string>} requestedModules - explicitly requested modules
+ * @param {string[]} baseModules - default included modules
+ * @returns {Object} adapted data keyed by module names
+ */
+function adaptUpstreamToModel(upstreamResult, moduleMapping, requestedModules, baseModules) {
+  const adapted = {};
+  const allModules = new Set([...baseModules, ...requestedModules]);
+
+  for (const module of allModules) {
+    const mapping = moduleMapping[module];
+    if (!mapping) {
+      throw new Error(`No mapping defined for module: ${module}`);
+    }
+
+    const { upstreamPath, required } = mapping;
+    const value = getNestedValue(upstreamResult, upstreamPath);
+
+    if (value === undefined) {
+      if (required) {
+        throw new Error(
+          `Required module '${module}' not found at upstream path '${upstreamPath}'`
+        );
+      }
+      // Optional module not present - skip it (don't add to adapted)
+      continue;
+    }
+
+    adapted[module] = value;
+  }
+
+  return adapted;
+}
+
+/**
+ * Get nested value from object using dot-separated path.
+ * @param {Object} obj - source object
+ * @param {string} path - dot-separated path (e.g., "response.customer.tags")
+ * @returns {*} value at path, or undefined if not found
+ */
+function getNestedValue(obj, path) {
+  return path.split('.').reduce((current, key) => {
+    return current?.[key];
+  }, obj);
+}
+
+module.exports = {
+  parseIncludeModules,
+  validateRequiredModules,
+  adaptUpstreamToModel,
+  getNestedValue
+};

package/src/execution/command-policy.js

@@ -0,0 +1,41 @@
+'use strict';
+
+function validateAt(at) {
+  if (!['hq', 'shop', 'all'].includes(at)) {
+    throw new Error('Command at must be explicitly declared as hq, shop or all');
+  }
+  return at;
+}
+
+function isAvailable(at, context) {
+  return at === 'all' || at === context.orgType;
+}
+
+function assertAvailable(at, state, { dryRun = false, command, includeDetails = false,
+  contextStage = 'context' } = {}) {
+  function reject(message, category, reason) {
+    const error = new Error(message);
+    error.diagnosticReason = reason;
+    if (includeDetails) error.cliDetails = {
+      category, stage: contextStage, command, targetScope: {}, requestState: 'not_sent',
+      nextStep: state.status === 'missing'
+        ? '执行前需要登录并选择店铺：未登录先执行 `zan-saas auth login`；登录后执行 `zan-saas shop list` 和 `zan-saas shop use <kdtId>`。目标解析不证明凭证授权，不自动切换店铺或身份。'
+        : '检查当前用户上下文中的 userId、hq、shopId 和 orgType；不自动切换店铺或身份，权限由服务端校验。'
+    };
+    error.issues = [{ source: 'context', reason: 'constraint' }];
+    throw error;
+  }
+  if (state.status === 'missing' && dryRun) return;
+  if (state.status !== 'ready') {
+    reject(state.status === 'missing'
+      ? '执行前需要登录并选择店铺：未登录先执行 `zan-saas auth login`；登录后执行 `zan-saas shop list` 和 `zan-saas shop use <kdtId>`，也可以在受控环境提供 ZAN_SAAS_CONTEXT'
+      : '当前用户上下文无效，请检查 userId、hq、shopId 和 orgType', 'configuration', state.status === 'missing' ? 'context_missing' : 'context_invalid');
+  }
+  if (!isAvailable(at, state.context)) {
+    const position = state.context.orgType === 'hq' ? '总部' : '店铺';
+    const required = at === 'hq' ? '总部' : '店铺';
+    reject(`当前是${position}上下文，此命令只能在${required}上下文执行。`, 'permission', at === 'hq' ? 'requires_hq' : 'requires_shop');
+  }
+}
+
+module.exports = { validateAt, isAvailable, assertAvailable };

package/src/execution/command-schema.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('node:fs');
+const Ajv = require('ajv');
+const { validDateTime } = require('./datetime');
+const { CommandValueError } = require('./error-details');
+const { assertDiagnosticModel } = require('./error-model');
+
+const ajv = new Ajv({ allErrors: true, strict: true });
+ajv.addFormat('beijing-date-time', value => validDateTime(value));
+ajv.addFormat('beijing-date-time-ms', value => validDateTime(value, true));
+const compiled = new WeakMap();
+const commandSchemas = new WeakMap();
+const model = { type: 'object', minProperties: 1 };
+const validateDefinition = ajv.compile({
+  type: 'object',
+  required: ['schemaVersion', 'input', 'output'],
+  additionalProperties: false,
+  properties: {
+    schemaVersion: { const: 1 },
+    input: model,
+    output: model,
+    preview: model,
+    error: model,
+    definitions: { type: 'object' },
+    modules: {
+      type: 'object',
+      minProperties: 1,
+      propertyNames: { pattern: '^[a-z][a-z0-9_-]*$' },
+      additionalProperties: {
+        type: 'object',
+        required: ['base', 'upstreamPath', 'required', 'description'],
+        additionalProperties: false,
+        properties: {
+          base: { type: 'boolean' },
+          upstreamPath: { type: 'string', minLength: 1 },
+          required: { type: 'boolean' },
+          description: { type: 'string', minLength: 1 }
+        }
+      }
+    },
+    api: {
+      type: 'object',
+      required: ['method', 'path'],
+      additionalProperties: false,
+      properties: {
+        method: { const: 'POST' },
+        path: { type: 'string', minLength: 1 }
+      }
+    },
+    success: { type: 'object' },
+    errors: { type: 'object' },
+    notes: { type: 'array', items: { type: 'string' } }
+  }
+});
+
+function validators(schema) {
+  if (compiled.has(schema)) return compiled.get(schema);
+  assertDiagnosticModel(schema);
+  if (!validateDefinition(schema)) {
+    throw new Error(`Invalid command schema: ${ajv.errorsText(validateDefinition.errors)}`);
+  }
+  const result = {};
+  for (const section of ['input', 'output', 'preview', 'error']) {
+    if (schema[section]) {
+      result[section] = ajv.compile({
+        ...schema[section],
+        definitions: schema.definitions || {}
+      });
+    }
+  }
+  compiled.set(schema, result);
+  return result;
+}
+
+function validateCommandValue(schema, section, value) {
+  const validate = validators(schema)[section];
+  if (!validate) throw new Error(`Command schema has no ${section} model`);
+  if (!validate(value)) {
+    throw new CommandValueError(section, structuredClone(validate.errors), schema);
+  }
+}
+
+function validateCommandSchema(schema) {
+  validators(schema);
+}
+
+function loadCommandSchema(filename) {
+  if (!fs.existsSync(filename) || !fs.lstatSync(filename).isFile()) {
+    throw new Error(`Missing command schema: ${filename}`);
+  }
+  const schema = JSON.parse(fs.readFileSync(filename, 'utf8'));
+  validators(schema);
+  return schema;
+}
+
+function attachCommandSchema(command, schema) {
+  validators(schema);
+  commandSchemas.set(command, schema);
+}
+
+function commandSchema(command) {
+  return commandSchemas.get(command);
+}
+
+function queryDefinition(schema) {
+  validators(schema);
+  if (!schema.modules || !schema.api) {
+    throw new Error('Query schema requires modules and api');
+  }
+  const baseModules = [];
+  const includeModules = [];
+  const mapping = {};
+  for (const [name, definition] of Object.entries(schema.modules)) {
+    (definition.base ? baseModules : includeModules).push(name);
+    mapping[name] = {
+      upstreamPath: definition.upstreamPath,
+      required: definition.required
+    };
+  }
+  return { baseModules, includeModules, mapping };
+}
+
+module.exports = {
+  loadCommandSchema,
+  attachCommandSchema,
+  commandSchema,
+  validateCommandSchema,
+  validateCommandValue,
+  queryDefinition
+};

package/src/execution/datetime.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const OFFSET_MS = 8 * 60 * 60 * 1000;
+const INPUT_PATTERN = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,3})?$/;
+const OUTPUT_PATTERN = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/;
+
+function parseDateTime(value) {
+  if (typeof value !== 'string' || !INPUT_PATTERN.test(value.trim())) {
+    throw new Error('时间须为北京时间 YYYY-MM-DD HH:mm:ss，可追加 1 至 3 位毫秒');
+  }
+  const [calendar, fraction = ''] = value.trim().split('.');
+  const [year, month, day, hour, minute, second] = calendar.match(/\d+/g).map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  date.setUTCHours(hour, minute, second, Number(fraction.padEnd(3, '0')));
+  if (year < 1 || date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 ||
+      date.getUTCDate() !== day || date.getUTCHours() !== hour ||
+      date.getUTCMinutes() !== minute || date.getUTCSeconds() !== second) {
+    throw new Error('时间须为有效的实际日历时间');
+  }
+  return date.getTime() - OFFSET_MS;
+}
+
+function formatDateTime(milliseconds) {
+  if (!Number.isSafeInteger(milliseconds)) throw new Error('时间戳须为安全毫秒整数');
+  const date = new Date(milliseconds + OFFSET_MS);
+  const year = date.getUTCFullYear();
+  if (!Number.isFinite(date.getTime()) || year < 1 || year > 9999) {
+    throw new Error('时间超出 0001 至 9999 年的可表示范围');
+  }
+  return date.toISOString().slice(0, -1).replace('T', ' ');
+}
+
+function apiSeconds(value) {
+  const milliseconds = parseDateTime(value);
+  if (milliseconds % 1000 !== 0) throw new Error('此接口仅支持秒精度，不能传入非零毫秒');
+  return milliseconds / 1000;
+}
+
+function apiDateTime(value) {
+  return formatDateTime(apiSeconds(value) * 1000).slice(0, 19);
+}
+
+function validDateTime(value, output = false) {
+  try {
+    if (!(output ? OUTPUT_PATTERN : INPUT_PATTERN).test(value)) return false;
+    parseDateTime(value);
+    return true;
+  } catch { return false; }
+}
+
+function normalizeTimes(value, model, definitions = {}) {
+  if (model.$ref) {
+    return normalizeTimes(value, definitions[model.$ref.slice('#/definitions/'.length)], definitions);
+  }
+  if (value == null) return value;
+  if (model.$comment?.startsWith('upstream-time:')) {
+    const [, unit, ...sentinels] = model.$comment.split(':');
+    if ((value === '' && sentinels.includes('empty')) ||
+        (value === '永久有效' && sentinels.includes('permanent')) ||
+        (value === 0 && sentinels.includes('zero'))) return value;
+    if (unit === 'text') return formatDateTime(parseDateTime(value));
+    if (!Number.isSafeInteger(value)) throw new Error('上游时间戳须为安全整数');
+    if (unit === 'seconds') return formatDateTime(value * 1000);
+    if (unit === 'milliseconds') return formatDateTime(value);
+    throw new Error('未知的上游时间单位');
+  }
+  if (Array.isArray(value) && model.items) {
+    return value.map(entry => normalizeTimes(entry, model.items, definitions));
+  }
+  if (typeof value === 'object' && !Array.isArray(value) && model.properties) {
+    const result = { ...value };
+    for (const [key, child] of Object.entries(model.properties)) {
+      if (Object.hasOwn(value, key)) result[key] = normalizeTimes(value[key], child, definitions);
+    }
+    return result;
+  }
+  return value;
+}
+
+module.exports = {
+  parseDateTime, formatDateTime, apiSeconds, apiDateTime, validDateTime, normalizeTimes
+};