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

package/src/cli/skill-catalog.js

@@ -0,0 +1,241 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const systemSkillDefinitions = Object.freeze([
+  {
+    name: 'zan-saas',
+    type: 'entry',
+    dependsOn: ['zan-saas-shared']
+  },
+  {
+    name: 'zan-saas-shared',
+    type: 'shared',
+    dependsOn: []
+  }
+]);
+
+function regularFile(filename) {
+  return fs.lstatSync(filename).isFile();
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const fields = {};
+  for (const line of match?.[1]?.split(/\r?\n/) || []) {
+    const field = line.match(/^(name|description):[ \t]*(.*)$/);
+    if (!field) continue;
+    if (Object.hasOwn(fields, field[1])) {
+      throw new Error(`Duplicate skill frontmatter field: ${field[1]}`);
+    }
+    fields[field[1]] = field[2].trim();
+  }
+  return fields;
+}
+
+function validateSkillName(name) {
+  if (typeof name !== 'string' ||
+      !(name === 'zan-saas' || /^zan-saas-[a-z][a-z0-9-]*$/.test(name))) {
+    throw new Error(`Invalid skill name: ${name}`);
+  }
+}
+
+function safeRelativePath(relativePath) {
+  if (typeof relativePath !== 'string') throw new Error('Invalid skill path');
+  const parts = relativePath.split('/');
+  if (!relativePath.endsWith('.md') ||
+      !parts.length ||
+      parts.some(part => !part || part === '.' || part === '..' || part.includes('\\'))) {
+    throw new Error('Invalid skill path');
+  }
+}
+
+function skillDirectory(root, skill) {
+  validateSkillName(skill);
+  return path.join(root, skill);
+}
+
+function readSkillFile(root, skill, relativePath = 'SKILL.md') {
+  safeRelativePath(relativePath);
+  let current = skillDirectory(root, skill);
+  try {
+    for (const part of relativePath.split('/')) {
+      if (!fs.lstatSync(current).isDirectory()) throw new Error('Invalid skill path');
+      current = path.join(current, part);
+    }
+    if (!regularFile(current)) throw new Error('Invalid skill path');
+    return fs.readFileSync(current, 'utf8');
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error.code)) {
+      throw new Error(`Skill file not found: ${skill}/${relativePath}`);
+    }
+    throw error;
+  }
+}
+
+function markdownFiles(root, skill) {
+  const base = skillDirectory(root, skill);
+  const files = [];
+
+  function visit(current, relative = '') {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) =>
+      left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
+      const filename = path.join(current, entry.name);
+      const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) visit(filename, childRelative);
+      else if (entry.isFile()) {
+        if (!entry.name.endsWith('.md')) {
+          throw new Error(`Only Markdown files can be bundled in a skill: ${filename}`);
+        }
+        files.push(childRelative);
+      } else {
+        throw new Error(`Unsupported skill file: ${filename}`);
+      }
+    }
+  }
+
+  try {
+    if (!fs.lstatSync(base).isDirectory()) throw new Error(`Invalid skill directory: ${skill}`);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`Skill directory not found: ${skill}`);
+    throw error;
+  }
+  visit(base);
+  return files;
+}
+
+function validateSkillFrontmatter(root, definition) {
+  const content = readSkillFile(root, definition.name);
+  const frontmatter = parseFrontmatter(content);
+  if (frontmatter.name !== definition.name || !frontmatter.description) {
+    throw new Error(`Skill needs matching name and description: ${definition.name}`);
+  }
+  return {
+    ...definition,
+    description: frontmatter.description
+  };
+}
+
+function buildSkillCatalog(root, domains, businessCommands) {
+  const definitions = [
+    ...systemSkillDefinitions,
+    ...domains.map(domain => ({
+      name: domain.skill,
+      type: 'domain',
+      domain: domain.name,
+      dependsOn: ['zan-saas-shared']
+    }))
+  ];
+  const names = new Set(definitions.map(entry => entry.name));
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name === 'README.md') continue;
+    if (!entry.isDirectory() || !names.has(entry.name)) {
+      throw new Error(`Skill has no published registration: ${entry.name}`);
+    }
+  }
+  const catalog = definitions.map(definition => {
+    const loaded = validateSkillFrontmatter(root, definition);
+    const files = markdownFiles(root, definition.name);
+    const hash = crypto.createHash('sha256');
+    for (const filename of files) {
+      hash.update(filename);
+      hash.update('\0');
+      hash.update(readSkillFile(root, definition.name, filename));
+      hash.update('\0');
+    }
+    const domain = domains.find(entry => entry.name === definition.domain);
+    return {
+      name: loaded.name,
+      type: loaded.type,
+      ...(domain ? { domain: domain.name } : {}),
+      description: domain ? domain.description : loaded.description,
+      dependsOn: [...loaded.dependsOn],
+      commandRefs: businessCommands.filter(command => domain &&
+        command.path.startsWith(`${domain.name}.`)).map(command => command.path).sort(),
+      files,
+      fingerprint: hash.digest('hex')
+    };
+  });
+  validateSkillCatalog(catalog, domains, businessCommands);
+  return catalog;
+}
+
+function validateSkillCatalog(catalog, domains, businessCommands) {
+  if (!Array.isArray(catalog)) throw new Error('Skill catalog is missing');
+  const entries = new Map();
+  const domainMap = new Map(domains.map(domain => [domain.name, domain]));
+  const commands = new Set((businessCommands || []).map(command => command.path));
+  const validateCommandRefs = businessCommands !== undefined;
+  for (const entry of catalog) {
+    if (!entry || typeof entry !== 'object') throw new Error('Invalid skill catalog entry');
+    validateSkillName(entry.name);
+    const system = systemSkillDefinitions.find(candidate => candidate.name === entry.name);
+    const domain = domainMap.get(entry.domain);
+    const validOwner = system
+      ? entry.type === system.type && entry.domain === undefined
+      : entry.type === 'domain' && domain?.skill === entry.name;
+    const commandRefsInvalid = validateCommandRefs
+      ? !Array.isArray(entry.commandRefs) ||
+        new Set(entry.commandRefs).size !== entry.commandRefs.length ||
+        entry.commandRefs.some(key => !commands.has(key) ||
+          !domain || !key.startsWith(`${domain.name}.`))
+      : entry.commandRefs !== undefined &&
+        (!Array.isArray(entry.commandRefs) ||
+          new Set(entry.commandRefs).size !== entry.commandRefs.length);
+    if (!validOwner || entries.has(entry.name) ||
+        typeof entry.description !== 'string' || !entry.description.trim() ||
+        !Array.isArray(entry.dependsOn) || !entry.dependsOn.every(name => typeof name === 'string') ||
+        new Set(entry.dependsOn).size !== entry.dependsOn.length ||
+        commandRefsInvalid ||
+        !Array.isArray(entry.files) || !entry.files.includes('SKILL.md') ||
+        new Set(entry.files).size !== entry.files.length ||
+        !/^[a-f0-9]{64}$/.test(entry.fingerprint)) {
+      throw new Error(`Invalid skill catalog entry: ${entry.name}`);
+    }
+    for (const file of entry.files) safeRelativePath(file);
+    const required = system ? system.dependsOn : ['zan-saas-shared'];
+    if (required.some(name => !entry.dependsOn.includes(name))) {
+      throw new Error(`Skill dependency is missing: ${entry.name}`);
+    }
+    entries.set(entry.name, entry);
+  }
+  if (catalog.length && !entries.has('zan-saas')) {
+    throw new Error('Skill entry not published: zan-saas');
+  }
+  for (const domain of domains) {
+    if (!entries.has(domain.skill)) throw new Error(`Domain skill not published: ${domain.skill}`);
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(name) {
+    if (visiting.has(name)) throw new Error(`Skill dependency cycle: ${name}`);
+    if (visited.has(name)) return;
+    const entry = entries.get(name);
+    if (!entry) throw new Error(`Skill dependency not published: ${name}`);
+    visiting.add(name);
+    for (const dependency of entry.dependsOn) visit(dependency);
+    visiting.delete(name);
+    visited.add(name);
+  }
+  for (const name of entries.keys()) visit(name);
+}
+
+function readPublishedSkillFile(root, catalog, skill, relativePath = 'SKILL.md') {
+  const entry = catalog.find(candidate => candidate.name === skill);
+  if (!entry) throw new Error(`Skill not published: ${skill}`);
+  safeRelativePath(relativePath);
+  if (!entry.files.includes(relativePath)) {
+    throw new Error(`Skill file not published: ${skill}/${relativePath}`);
+  }
+  return readSkillFile(root, skill, relativePath);
+}
+
+module.exports = {
+  buildSkillCatalog,
+  readPublishedSkillFile,
+  readSkillFile,
+  validateSkillFrontmatter,
+  validateSkillCatalog
+};

package/src/commands/native/access/commands.index.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 3,
+  "domain": "access",
+  "businessCommands": [
+    {
+      "path": "access.role.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "access/role/list/command.js",
+      "fingerprint": "1f1a25bdb5f2252635920dd6f154e7692cefbe5c37bf5c164aff4c0c73a23313"
+    },
+    {
+      "path": "access.staff-perms.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "access/staff-perms/get/command.js",
+      "fingerprint": "65cb2c9fdefa0300d8a35f6d2951af997a1251f40f64172505898d56d9a810ce"
+    }
+  ]
+}

package/src/commands/native/access/domain.json

@@ -0,0 +1,3 @@
+{
+  "description": "访问控制：店铺角色定义与员工权限点"
+}

package/src/commands/native/access/role/list/command.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { readContext } = require('../../../../../identity/context');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { readApiEnvelope, assertApiSuccess, object } = require('../../../../../execution/query-api');
+const { failure, bindingPath } = require('../../../../../execution/shop-query');
+const { snapshotApiEnvironment } = require('../../../../../transport/api');
+const schema = require('./schema.json');
+
+const command = 'access.role.list';
+const organizationPath = 'youzan.shop.chain.descendent.organization.list/1.0.1';
+const maxOrganizationPages = 20;
+const pageSize = 50;
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function organizationBody(pageNo) {
+  return { page_num: pageNo, page_size: pageSize, with_dept_info: false,
+    with_shop_status_and_lifecycle_end_time: false, with_crm_shop: false };
+}
+
+function previewFor(input, context) {
+  const crossShop = context && String(input.kdtId) !== context.shopId;
+  const requests = [{ stage: 'shop-binding', method: 'POST', path: bindingPath, body: {} }];
+  if (crossShop) requests.push({ stage: 'target-membership', method: 'POST',
+    path: organizationPath, body: organizationBody(1) });
+  requests.push({ stage: 'roles', method: 'POST', path: schema.api.path,
+    body: { third_tenant_id: String(input.kdtId), third_user_id: '-1',
+      namespace: 'np_yz_shop', filter: { biz_key_group: 'shop_ability' } } });
+  return { scope: input, requests, maxOrganizationPages };
+}
+
+async function verifyMembership(read, input) {
+  const seen = new Set();
+  let total;
+  for (let pageNo = 1; pageNo <= maxOrganizationPages; pageNo += 1) {
+    const { data, facts } = await read(organizationPath, organizationBody(pageNo), 'target-membership');
+    const invalid = category => reject(category, 'target-membership', input, 'sent', facts);
+    if (!object(data) || !Array.isArray(data.organization_list) ||
+        data.page_num !== pageNo || data.page_size !== pageSize ||
+        !Number.isSafeInteger(data.total) || data.total < 0 ||
+        data.organization_list.length !== Math.min(pageSize, Math.max(0, data.total - seen.size)) ||
+        (total !== undefined && total !== data.total)) throw invalid('protocol');
+    total = data.total;
+    for (const unit of data.organization_list) {
+      if (!object(unit) || !Number.isSafeInteger(unit.kdt_id) || unit.kdt_id < 1 ||
+          !Number.isSafeInteger(unit.role) || unit.role < 0 || unit.role === 9 ||
+          seen.has(unit.kdt_id)) throw invalid('protocol');
+      seen.add(unit.kdt_id);
+    }
+    if (seen.has(input.kdtId)) return;
+    if (seen.size === total || pageNo === maxOrganizationPages) throw invalid('scope_unresolved');
+  }
+}
+
+async function execute(input, context, preview) {
+  let env;
+  try { env = await snapshotApiEnvironment(undefined, context.shopId); }
+  catch { throw reject('configuration', 'configuration', input, 'not_sent'); }
+  async function read(path, body, stage) {
+    const { result, facts } = await readApiEnvelope(path, body,
+      (category, details, state, at) => reject(category,
+        at === 'configuration' ? at : stage, input, state, details), env);
+    assertApiSuccess(result, category => { throw reject(category, stage, input, 'sent', facts); });
+    return { data: result.data, facts };
+  }
+  const binding = await read(bindingPath, {}, 'shop-binding');
+  if (!object(binding.data) || !Number.isSafeInteger(binding.data.sid) || binding.data.sid < 1) {
+    throw reject('protocol', 'shop-binding', input, 'sent', binding.facts);
+  }
+  if (String(binding.data.sid) !== context.shopId) {
+    throw reject('scope_unresolved', 'shop-binding', input, 'sent', binding.facts);
+  }
+  if (String(input.kdtId) !== context.shopId) {
+    if (context.orgType !== 'hq' || String(binding.data.sid) !== context.hq || binding.data.role !== 1) {
+      throw reject('scope_unresolved', 'shop-binding', input, 'sent', binding.facts);
+    }
+    await verifyMembership(read, input);
+  }
+  const request = preview.requests.at(-1);
+  const { data, facts } = await read(request.path, request.body, request.stage);
+  try {
+    if (!Array.isArray(data)) throw new TypeError('Invalid roles');
+    const roles = data.map(source => {
+      if (!object(source)) throw new TypeError('Invalid role');
+      const role = { roleId: source.role_id, name: source.name };
+      for (const [field, upstream] of Object.entries({ bizCode: 'biz_code',
+        roleType: 'role_type_value', remark: 'remark' })) {
+        if (source[upstream] !== undefined && source[upstream] !== null) role[field] = source[upstream];
+      }
+      return role;
+    });
+    const output = { data: { roles } };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch {
+    throw reject('protocol', 'roles-model', input, 'sent', facts);
+  }
+}
+
+function createCommand({ context } = {}) {
+  return new Command('list')
+    .description('查询目标店铺本次返回的角色定义目录，不查询员工角色或有效权限')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取上下文 shopId，非总部不可跨店')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '零网络预览，不读取凭证，不声称已核实归属')
+    .addHelpText('after', `
+输出 data.roles，核心 roleId、name；可选 bizCode、roleType、remark 仅按返回映射。
+可选字符串字段缺失或为 null 时省略，空字符串保留。
+roleType 保留原始整数码，不推导 system/custom。空目录只表示本次查询为空。
+保留原顺序，不排序、去重、分页或截断角色，不承诺返回全系统角色。
+先核实凭证主体与当前店铺；总部跨店另查下级组织，每页 50 条、最多 20 页。
+归属未核实、分页异常或达到核验预算时停止，不发角色请求，不换凭证或重试。
+筛选项均不发送；目录和组织角色不证明店铺员工授权或权限隔离验收通过。
+契约：zan-saas schema access.role.list --format json
+示例：zan-saas access role list --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const input = resolveTargetShop(options, context, command);
+      const state = readContext(context);
+      const rawTarget = Object.hasOwn(options, 'kdtId') ? options.kdtId : state.context?.shopId;
+      if (String(input.kdtId) !== rawTarget) throw reject('validation', 'input', input);
+      validateCommandValue(schema, 'input', input);
+      const preview = previewFor(input, state.context);
+      validateCommandValue(schema, 'preview', preview);
+      const output = options.dryRun ? preview : await execute(input, state.context, preview);
+      console.log(JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0));
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };