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

package/src/execution/shop-query.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const {
+  QueryError, readApiEnvelope, assertApiSuccess, object
+} = require('./query-api');
+const { snapshotApiEnvironment } = require('../transport/api');
+
+const bindingPath = 'youzan.shop.basic.get/3.0.0';
+const nextStep = '核对原店铺、对象标识和服务端授权；店铺核验失败时业务请求未发送，不自动切换店铺、身份或重试。';
+
+function failure(command, category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  return new QueryError(category, stage, scope, facts, requestState, command, nextStep);
+}
+
+async function createBoundShopQuery(target, command, bindingStage = 'shop-binding', { onResponse, transportOptions } = {}) {
+  const scope = Object.freeze({ kdtId: target.kdtId });
+  if (!Number.isSafeInteger(scope.kdtId) || scope.kdtId < 1) {
+    throw failure(command, 'validation', 'scope');
+  }
+  let env;
+  try {
+    env = await snapshotApiEnvironment(undefined, scope.kdtId);
+  } catch (error) {
+    const rejected = failure(command, 'configuration', 'configuration', scope);
+    rejected.diagnosticReason = error.diagnosticReason;
+    throw rejected;
+  }
+  async function read(path, body, stage, successCodes = [200]) {
+    const { result, facts, rawBody, responseBytes } = await readApiEnvelope(path, body,
+      (category, details, state, at) => failure(command, category,
+        at === 'configuration' || category === transportOptions?.limitCategory ? at : stage,
+        scope, state, details), env, onResponse, transportOptions);
+    assertApiSuccess(result, category => {
+      throw failure(command, category, stage, scope, 'sent', facts);
+    }, successCodes);
+    return { data: result.data, facts, envelope: result, rawBody, responseBytes };
+  }
+  const binding = await read(bindingPath, {}, bindingStage);
+  const { data, facts } = binding;
+  if (!object(data) || !Number.isSafeInteger(data.sid) || data.sid < 1) {
+    throw failure(command, 'protocol', bindingStage, scope, 'sent', facts);
+  }
+  if (data.sid !== scope.kdtId) {
+    throw failure(command, 'scope_unresolved', bindingStage, scope, 'sent', facts);
+  }
+  return { read, binding };
+}
+
+async function createShopQuery(target, command, options = {}) {
+  const { read } = await createBoundShopQuery(target, command, 'shop-binding', options);
+  return read;
+}
+
+module.exports = { createShopQuery, createBoundShopQuery, failure, bindingPath };

package/src/execution/target-shop-default.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { readContext } = require('../identity/context');
+
+// Complete only the CLI option, before the leaf validates its normalized business input.
+// The invocation context is captured when its command is built; authorization stays in the leaf.
+function withTargetShopDefault(createCommand) {
+  return function createCommandWithTargetShopDefault(options = {}) {
+    const state = readContext(options.context);
+    const command = createCommand(options);
+    const target = command.options.find(option => option.long === '--kdt-id');
+    if (!target) return command;
+    target.makeOptionMandatory(false);
+    command.hook('preAction', () => {
+      if (!Object.hasOwn(command.opts(), 'kdtId') && state.status === 'ready') {
+        command.setOptionValueWithSource('kdtId', state.context.shopId, 'context');
+      }
+    });
+    return command;
+  };
+}
+
+module.exports = { withTargetShopDefault };

package/src/execution/target-shop.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { readContext } = require('../identity/context');
+
+function resolveTargetShop(options, context, command) {
+  const state = readContext(context);
+  const explicit = Object.hasOwn(options, 'kdtId');
+  function reject(message, category, stage, targetScope = {}, reason) {
+    const error = new Error(message);
+    error.diagnosticReason = reason;
+    error.cliDetails = {
+      category, stage, command, targetScope, requestState: 'not_sent',
+      nextStep: '执行前需要登录并选择店铺：未登录先执行 `zan-saas auth login`；登录后执行 `zan-saas shop list` 和 `zan-saas shop use <kdtId>`。目标解析不证明凭证授权，不自动切换店铺或身份。'
+    };
+    error.issues = [{
+      source: stage === 'validation' ? 'argv' : 'context',
+      reason: stage === 'validation' ? 'invalid_format' : 'constraint',
+      ...(stage === 'validation' ? { option: '--kdt-id' } : {})
+    }];
+    throw error;
+  }
+
+  if (state.status === 'invalid') {
+    reject('当前用户上下文无效，请检查 userId、hq、shopId 和 orgType',
+      'configuration', 'context', {}, 'context_invalid');
+  }
+  if (!explicit && state.status === 'missing') {
+    reject('缺少目标店铺；请先登录选店，或在 --dry-run 中显式提供 --kdt-id',
+      'configuration', 'context', {}, 'target_missing');
+  }
+
+  const raw = explicit ? options.kdtId : state.context.shopId;
+  if (typeof raw !== 'string' || !/^[1-9]\d*$/.test(raw) ||
+      !Number.isSafeInteger(Number(raw))) {
+    reject(`${explicit ? '--kdt-id' : 'context.shopId'} must be a positive safe integer`,
+      explicit ? 'validation' : 'configuration', explicit ? 'validation' : 'context');
+  }
+  const scope = Object.freeze({ kdtId: Number(raw) });
+  if (state.status === 'missing' && options.dryRun !== true) {
+    reject('真实执行前需要登录并选择店铺', 'configuration', 'context', scope, 'context_missing');
+  }
+  if (state.status === 'ready' && state.context.orgType === 'shop' &&
+      String(scope.kdtId) !== state.context.shopId) {
+    reject('--kdt-id must match context.shopId in shop context', 'permission', 'scope', scope);
+  }
+  return scope;
+}
+
+module.exports = { resolveTargetShop };

package/src/identity/context-store.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { oauthConfig } = require('../auth/config');
+const { readStore, storePath, writeStore } = require('../auth/credential-store');
+const { createContext, readContext } = require('./context');
+
+const fileName = 'context.json';
+
+function contextPath(env = process.env) {
+  return storePath(fileName, env);
+}
+
+// The selected shop is kept per oauth origin, like the credential it was chosen with.
+function readSavedContext(env = process.env) {
+  const entry = readStore(fileName, env)[oauthConfig(env).server];
+  const state = readContext(entry?.context);
+  if (state.status !== 'ready') return null;
+  return Object.freeze({
+    context: state.context,
+    shopName: typeof entry.shopName === 'string' ? entry.shopName : null,
+    savedAt: typeof entry.savedAt === 'string' ? entry.savedAt : null
+  });
+}
+
+function saveContext(input, { shopName } = {}, env = process.env) {
+  const context = createContext(input);
+  const { server } = oauthConfig(env);
+  const data = readStore(fileName, env);
+  data[server] = { context, ...(shopName ? { shopName } : {}), savedAt: new Date().toISOString() };
+  writeStore(fileName, data, env);
+  return context;
+}
+
+function deleteContext(env = process.env) {
+  const { server } = oauthConfig(env);
+  const data = readStore(fileName, env);
+  if (!Object.hasOwn(data, server)) return false;
+  delete data[server];
+  writeStore(fileName, data, env);
+  return true;
+}
+
+// ZAN_SAAS_CONTEXT wins, even when invalid; otherwise the shop chosen with `shop use`.
+function contextInput(env = process.env) {
+  if (env.ZAN_SAAS_CONTEXT) return env.ZAN_SAAS_CONTEXT;
+  try {
+    return readSavedContext(env)?.context;
+  } catch {
+    // Unreadable files or bad oauth configuration behave like no saved shop.
+    return undefined;
+  }
+}
+
+module.exports = { contextInput, contextPath, deleteContext, readSavedContext, saveContext };

package/src/identity/context.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const fields = ['userId', 'hq', 'shopId', 'orgType'];
+const shopId = /^[1-9]\d*$/;
+
+function createContext(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) ||
+      Object.keys(input).some(key => !fields.includes(key)) ||
+      fields.some(key => !Object.hasOwn(input, key) ||
+        typeof input[key] !== 'string' || !input[key].trim())) {
+    throw new Error('User context requires only userId, hq, shopId and orgType strings');
+  }
+  const { userId, hq, shopId: selectedShop, orgType } = input;
+  if (!shopId.test(hq) || !shopId.test(selectedShop)) {
+    throw new Error('Context hq and shopId must be positive integer ID strings');
+  }
+  if (!['hq', 'shop'].includes(orgType)) {
+    throw new Error('Context orgType must be hq or shop');
+  }
+  if (orgType === 'hq' && hq !== selectedShop) {
+    throw new Error('Context orgType conflicts with hq and shopId');
+  }
+  return Object.freeze({ userId, hq, shopId: selectedShop, orgType });
+}
+
+function readContext(input) {
+  if (input === undefined || input === null || input === '') {
+    return Object.freeze({ status: 'missing' });
+  }
+  try {
+    const value = typeof input === 'string' ? JSON.parse(input) : input;
+    return Object.freeze({ status: 'ready', context: createContext(value) });
+  } catch {
+    return Object.freeze({ status: 'invalid' });
+  }
+}
+
+module.exports = { createContext, readContext };

package/src/installation/install.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { createInterface } = require('node:readline/promises');
+const { hosts, stat, selectedHosts, detectedHosts, readTemplate, prepareSkill, writeSkill } = require('./skill');
+const { npmFailure } = require('./npm-error');
+
+const packageName = '@youzan-cloud/zan-saas-cli';
+const root = path.resolve(__dirname, '../..');
+const skillNextStep = '请在 Agent 技能列表中确认 zan-saas 已启用，再重新加载技能或打开新会话。未发现时，核对宿主的 Skill 根目录，再用 --directory <目录> 安装入口。';
+
+function npmRunner(env) {
+  let npmCli = env.npm_execpath;
+  if (!npmCli || !stat(npmCli)?.isFile() || !/npm-cli\.js$/i.test(npmCli)) {
+    npmCli = process.platform === 'win32'
+      ? path.join(path.dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js') : undefined;
+  }
+  return args => {
+    const result = spawnSync(npmCli ? process.execPath : 'npm', npmCli ? [npmCli, ...args] : args,
+      { encoding: 'utf8', env, timeout: 180000, maxBuffer: 2 * 1024 * 1024, shell: false });
+    if (result.error || result.status !== 0) {
+      throw npmFailure(result, args, env);
+    }
+    return result.stdout.trim();
+  };
+}
+
+function readPackage(directory) {
+  try { return JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+async function chooseHosts(options, { home, cwd, input, output }) {
+  if (options.directory !== undefined) {
+    if (!options.directory.trim() || options.host !== undefined) {
+      throw new Error('--directory 与 --host 二选一。');
+    }
+    return [];
+  }
+  if (options.host !== undefined) return selectedHosts(options.host);
+  const detected = detectedHosts(home, cwd);
+  if (options.yes) {
+    if (detected.length === 0) throw new Error('未检测到 Agent；请用 --host 指定，例如 --host workbuddy。');
+    return detected;
+  }
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error('非交互安装请指定宿主，例如 zan-saas install --yes --host workbuddy。');
+  }
+  output.write('安装有赞 SaaS CLI 与 Agent Skill，默认使用个人目录。\n');
+  hosts.forEach((host, index) => output.write(`  ${index + 1}. ${host.label}${detected.includes(host) ? '（已检测到）' : ''}\n`));
+  const defaults = detected.map(host => hosts.indexOf(host) + 1).join(',');
+  const readline = createInterface({ input, output });
+  try {
+    const answer = (await readline.question(`选择 Agent，多个用逗号分隔${defaults ? `，回车使用 ${defaults}` : ''}：`)).trim() || defaults;
+    const choices = answer.split(',').map(value => value.trim());
+    if (choices.some(value => !/^[1-9]\d*$/.test(value) || Number(value) > hosts.length)) {
+      throw new Error('未选择有效宿主，安装已停止。');
+    }
+    return [...new Set(choices.map(value => hosts[Number(value) - 1]))];
+  } finally { readline.close(); }
+}
+
+function globalState(npm, source) {
+  const prefix = npm(['prefix', '-g']);
+  const modules = npm(['root', '-g']);
+  if (!path.isAbsolute(prefix) || !path.isAbsolute(modules)) throw new Error('npm 未返回有效全局目录。');
+  const directory = path.join(modules, '@youzan-cloud/zan-saas-cli');
+  const launcher = path.join(directory, 'bin/zan-saas-cli.js');
+  const executable = path.join(prefix, process.platform === 'win32' ? 'zan-saas.cmd' : 'bin/zan-saas');
+  const installed = readPackage(directory);
+  let legacyPackage;
+  if (stat(executable)) {
+    let owns;
+    if (process.platform === 'win32') {
+      const shim = fs.readFileSync(executable, 'utf8').replaceAll('\\', '/');
+      owns = name => readPackage(path.join(modules, name))?.name === name &&
+        shim.includes(`node_modules/${name}/bin/zan-saas-cli.js`);
+    } else {
+      const actual = fs.realpathSync(executable);
+      owns = name => {
+        const directory = path.join(modules, name);
+        const entry = path.join(directory, 'bin/zan-saas-cli.js');
+        return readPackage(directory)?.name === name && stat(entry) && actual === fs.realpathSync(entry);
+      };
+    }
+    if (!owns(packageName)) {
+      legacyPackage = ['zan-saas-cli', '@youzan-cloud/zan-saas'].find(owns);
+      if (!legacyPackage) throw new Error(`现有 zan-saas 命令不属于本项目，已保留：${executable}`);
+    }
+  }
+  const reuse = installed?.name === packageName && installed.version === source.version &&
+    source.name === packageName && stat(launcher)?.isFile() && Boolean(stat(executable)) && !legacyPackage;
+  return { directory, launcher, legacyPackage, reuse };
+}
+
+async function install(options, { env = process.env, home = os.homedir(), cwd = process.cwd(),
+  input = process.stdin, output = process.stderr, packageRoot = root, npm = npmRunner(env) } = {}) {
+  const scope = options.scope || 'user';
+  if (!['user', 'project'].includes(scope)) throw new Error('--scope 仅支持 user 或 project。');
+  const selected = await chooseHosts(options, { home, cwd, input, output });
+  const source = readPackage(packageRoot);
+  if (!source) throw new Error('当前 npm 包缺少版本信息。');
+  let packageSource = `${packageName}@${source.name === packageName ? source.version : 'latest'}`;
+  if (options.package !== undefined) {
+    packageSource = path.resolve(cwd, options.package);
+    if (!packageSource.endsWith('.tgz') || !stat(packageSource)?.isFile()) {
+      throw new Error('--package 须指定本地 npm .tgz 文件。');
+    }
+  }
+  const state = globalState(npm, source);
+  const template = readTemplate(packageRoot);
+  const targets = options.directory !== undefined
+    ? [{ host: 'custom', filename: path.join(path.resolve(cwd, options.directory), 'zan-saas/SKILL.md') }]
+    : selected.map(host => ({ host: host.name,
+      filename: path.join(scope === 'user' ? home : cwd,
+        scope === 'project' ? host.projectDirectory || host.directory : host.directory,
+        'skills/zan-saas/SKILL.md') }));
+  const context = { node: process.execPath, launcher: state.launcher };
+  let plans = targets.map(target => ({ ...target, ...prepareSkill(target.filename, template, context) }));
+  const preview = { cli: { action: state.reuse ? 'reuse' : 'install', package: packageSource },
+    scope, skills: plans.map(plan => ({ host: plan.host, path: plan.filename, action: plan.action })) };
+  if (options.dryRun) return { success: true, ...preview, dryRun: true };
+  if (!state.reuse) {
+    if (state.legacyPackage) {
+      npm(['uninstall', '-g', state.legacyPackage, '--ignore-scripts', '--no-audit', '--no-fund']);
+    }
+    npm(['install', '-g', packageSource, '--ignore-scripts', '--engine-strict', '--no-audit', '--no-fund',
+      '--registry=https://registry.npmjs.org/']);
+  }
+  const installed = readPackage(state.directory);
+  if (installed?.name !== packageName ||
+      (source.name === packageName && installed.version !== source.version)) {
+    throw new Error('全局安装结果与本次 npm 包不一致，Skill 尚未写入。');
+  }
+  const verified = spawnSync(process.execPath, [state.launcher, '--version'],
+    { env, encoding: 'utf8', timeout: 30000 });
+  if (verified.status !== 0 || verified.stdout.trim() !== installed.version || verified.stderr) {
+    throw new Error('全局 CLI 版本验证失败，Skill 尚未写入。');
+  }
+  const installedTemplate = readTemplate(state.directory);
+  plans = targets.map(target => ({ ...target, ...prepareSkill(target.filename, installedTemplate, context) }));
+  try {
+    for (const plan of new Map(plans.map(plan => [plan.filename, plan])).values()) writeSkill(plan);
+  } catch (error) {
+    throw new Error(`入口安装未完成：${error.message}。已完成的安装会保留，修复后可重复执行。`);
+  }
+  return { success: true, version: installed.version, launcher: state.launcher, scope,
+    skills: plans.map(plan => ({ host: plan.host, path: plan.filename, action: plan.action })),
+    cliAction: state.reuse ? 'reuse' : 'install', skillLoading: 'not_verified', nextStep: skillNextStep };
+}
+
+module.exports = { install, chooseHosts, globalState, npmRunner };

package/src/installation/npm-error.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const path = require('node:path');
+
+// Only structured npm codes and rename paths are retained. Free-form npm output can contain credentials.
+const codes = new Set([
+  'ENOTEMPTY', 'EEXIST', 'EACCES', 'EPERM', 'ENOENT', 'ETIMEDOUT', 'ESOCKETTIMEDOUT',
+  'ECONNRESET', 'ECONNREFUSED', 'EAI_AGAIN', 'ENOTFOUND', 'ENETUNREACH', 'EHOSTUNREACH',
+  'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'SELF_SIGNED_CERT_IN_CHAIN',
+  'DEPTH_ZERO_SELF_SIGNED_CERT', 'ERR_TLS_CERT_ALTNAME_INVALID', 'EBADENGINE',
+  'E404', 'E401', 'E403', 'EUSAGE', 'ENOSPC', 'EROFS', 'EINTEGRITY', 'ERR_INVALID_URL',
+  'ENOBUFS', 'EPIPE', 'EMFILE', 'ENFILE', 'EBUSY'
+]);
+const operations = {
+  prefix: '读取 npm 全局前缀失败', root: '读取 npm 全局模块目录失败',
+  uninstall: '卸载旧版本失败', install: '安装 CLI 失败'
+};
+const networkCodes = new Set(['ECONNRESET', 'ECONNREFUSED', 'EAI_AGAIN', 'ENOTFOUND', 'ENETUNREACH', 'EHOSTUNREACH']);
+const certificateCodes = new Set(['CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'SELF_SIGNED_CERT_IN_CHAIN', 'DEPTH_ZERO_SELF_SIGNED_CERT', 'ERR_TLS_CERT_ALTNAME_INVALID']);
+
+function npmField(stderr, name) {
+  const match = new RegExp(`^npm (?:error|ERR!) ${name} (.+)$`, 'm').exec(stderr);
+  return match?.[1].trim();
+}
+
+function diagnosticPath(value, env) {
+  if (!value || value.length > 1024 || /[\x00-\x1f\x7f?&#]/.test(value) ||
+      /(?:https?|file):|(?:token|secret|password|authorization|_auth)\s*[:=]/i.test(value) ||
+      (!path.isAbsolute(value) && !path.win32.isAbsolute(value))) return undefined;
+  for (const [name, secret] of Object.entries(env)) {
+    if (/(?:token|secret|password|authorization|credential|(?:^|_)key$)/i.test(name) &&
+        typeof secret === 'string' && secret.length >= 4) value = value.replaceAll(secret, '[REDACTED]');
+  }
+  return value;
+}
+
+function advice(code, failedToStart) {
+  if (code === 'ENOTEMPTY') return [
+    '目标目录非空，npm 无法完成操作。',
+    '核对 npm 的冲突路径；确认目标是旧安装残留后，先备份并移走，再重新运行安装器。安装器不会自动删除目录。'
+  ];
+  if (code === 'EEXIST') return ['目标文件或目录已存在。',
+    '核对 npm 日志中的冲突路径及归属，保留其他程序的文件；处理冲突后再重新运行安装器。'];
+  if (code === 'EACCES' || code === 'EPERM') return ['npm 访问文件或目录时权限不足。',
+    '核对 npm 日志中的路径及写入权限；全局安装应使用当前用户可写的 npm prefix，不要强制覆盖。'];
+  if (code === 'ENOENT') return failedToStart
+    ? ['无法启动 npm。', '确认 npm 已安装且当前进程的 PATH 可以找到它，再重新运行安装器。']
+    : ['npm 找不到所需文件或目录。', '查看 npm 日志中的缺失路径，检查本地安装包或安装目录是否存在，再重新运行安装器。'];
+  if (code === 'ETIMEDOUT' || code === 'ESOCKETTIMEDOUT') return ['npm 操作超时。',
+    '检查网络和代理，并核对当前安装状态；确认后再重新运行安装器。'];
+  if (networkCodes.has(code)) return ['npm 网络连接失败。',
+    '检查网络、代理和 registry 的连接；恢复后再重新运行安装器。'];
+  if (certificateCodes.has(code)) return ['npm 无法验证连接证书。',
+    '检查系统时间、代理证书和 npm 证书配置；不要关闭证书校验。'];
+  if (code === 'ENOBUFS') return ['npm 输出超过安装器的读取上限。',
+    '查看 npm 日志并核对当前安装状态，确认失败步骤后再重新运行安装器。'];
+  if (code === 'ENOSPC') return ['安装所需的磁盘空间不足。', '检查磁盘空间，释放足够空间后再重新运行安装器。'];
+  if (code === 'EROFS') return ['安装目录所在文件系统只读。', '改用可写的 npm prefix，再重新运行安装器。'];
+  if (code === 'EBADENGINE') return ['当前 Node.js 或 npm 版本不符合安装要求。',
+    '按安装指南使用支持的 Node.js 和 npm 版本，再重新运行安装器。'];
+  if (code === 'E401' || code === 'E403') return ['npm registry 拒绝访问。',
+    '检查 npm registry 的登录状态及包的访问权限；这不是 CLI 的业务登录错误。'];
+  if (code === 'E404') return ['npm registry 中找不到指定包或版本。',
+    '核对包名、版本和 registry；尚未发布的候选包请使用 --package 指定本地 tgz。'];
+  if (code === 'EINTEGRITY') return ['npm 包完整性校验失败。',
+    '检查安装包、缓存和 registry 返回内容；不要跳过完整性校验。'];
+  return ['npm 未能完成操作。', '查看 npm 日志，核对失败步骤和当前安装状态后再处理；不要直接强制覆盖或删除全局目录。'];
+}
+
+function npmFailure(result, args, env = {}) {
+  const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+  const reportedCode = result.error?.code || npmField(stderr, 'code');
+  const npmCode = codes.has(reportedCode) ? reportedCode : null;
+  const operation = Object.hasOwn(operations, args[0]) ? args[0] : 'other';
+  const [reason, nextStep] = advice(npmCode, Boolean(result.error));
+  const error = new Error(`${operations[operation] || '执行 npm 失败'}${npmCode ? `（${npmCode}）` : ''}：${reason}`);
+  error.cliDetails = {
+    category: 'installation', stage: 'npm', operation, npmCode,
+    exitCode: Number.isInteger(result.status) && result.status >= 0 ? result.status : null,
+    signal: typeof result.signal === 'string' && /^SIG[A-Z0-9]{1,12}$/.test(result.signal) ? result.signal : null,
+    nextStep
+  };
+  if (npmCode === 'ENOTEMPTY' && npmField(stderr, 'syscall') === 'rename') {
+    for (const [name, field] of [['conflictPath', 'path'], ['destinationPath', 'dest']]) {
+      const value = diagnosticPath(npmField(stderr, field), env);
+      if (value !== undefined) error.cliDetails[name] = value;
+    }
+  }
+  return error;
+}
+
+module.exports = { npmFailure };

package/src/installation/skill.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash, randomUUID } = require('node:crypto');
+
+const hosts = [
+  { name: 'workbuddy', label: 'WorkBuddy', directory: '.workbuddy', projectDirectory: '.codebuddy',
+    detect: ['.workbuddy'], projectDetect: [] },
+  { name: 'codebuddy', label: 'CodeBuddy', directory: '.codebuddy', detect: ['.codebuddy'] },
+  { name: 'codex', label: 'Codex', directory: '.agents', detect: ['.codex'] },
+  { name: 'claude-code', label: 'Claude Code', directory: '.claude', detect: ['.claude'] },
+  { name: 'cursor', label: 'Cursor', directory: '.cursor', detect: ['.cursor'] },
+  { name: 'trae', label: 'Trae（中国版）', directory: '.trae-cn',
+    projectDirectory: '.trae', detect: ['.trae-cn'] }
+];
+
+function stat(filename) {
+  try { return fs.lstatSync(filename); }
+  catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function sha256(text) {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function selectedHosts(value) {
+  const names = value.split(',').map(name => name.trim());
+  if (names.some(name => !name)) throw new Error('--host 使用逗号分隔宿主名称。');
+  return [...new Set(names.map(name => name === 'claude' ? 'claude-code' : name))].map(name => {
+    const host = hosts.find(host => host.name === name);
+    if (!host) throw new Error(`不支持宿主 ${name}；请查看 zan-saas install --help。`);
+    return host;
+  });
+}
+
+function detectedHosts(home, cwd) {
+  return hosts.filter(host => host.detect.some(name => stat(path.join(home, name))?.isDirectory()) ||
+    (host.projectDetect || [host.projectDirectory || host.directory])
+      .some(name => stat(path.join(cwd, name))?.isDirectory()));
+}
+
+function readTemplate(root) {
+  const document = fs.readFileSync(path.join(root, 'skills/zan-saas/references/host-entry.md'), 'utf8')
+    .replaceAll('\r\n', '\n');
+  const blocks = [...document.matchAll(/```markdown\n([\s\S]*?)\n```/g)];
+  const text = blocks.length === 1 ? `${blocks[0][1].trim()}\n` : '';
+  if (!/^---\nname: zan-saas\ndescription: [^\n]+\n---\n/.test(text) ||
+      !text.includes('zan-saas --version') || !text.includes('zan-saas skills read zan-saas')) {
+    throw new Error('当前包未提供有效的宿主入口模板。');
+  }
+  return text;
+}
+
+function shellArgument(value, platform) {
+  if (/[\r\n`]/.test(value)) throw new Error('CLI 安装路径包含不支持的字符。');
+  if (platform === 'win32') {
+    return `'${value.replaceAll("'", "''")}'`;
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function prepareSkill(filename, template, { node, launcher, platform = process.platform }) {
+  const invocation = `${platform === 'win32' ? '& ' : ''}${shellArgument(node, platform)} ${shellArgument(launcher, platform)}`;
+  const text = template.replaceAll('`zan-saas --version`', `\`${invocation} --version\``)
+    .replaceAll('`zan-saas skills read zan-saas`', `\`${invocation} skills read zan-saas\``) +
+    '\n后续指引中的 `zan-saas` 均使用上述 Node.js 与 CLI 入口调用。\n' +
+    (platform === 'win32' ? 'Windows 使用 PowerShell 执行上述命令。\n' : '');
+  const content = `${text}\n<!-- zan-saas-cli host-entry sha256:${sha256(text)} -->\n`;
+  const directory = path.dirname(filename);
+  const folder = stat(directory);
+  if (folder && (!folder.isDirectory() || folder.isSymbolicLink())) {
+    throw new Error(`目标不是普通目录，已保留：${directory}`);
+  }
+  const existing = stat(filename);
+  if (existing && !existing.isFile()) throw new Error(`目标不是普通文件，已保留：${filename}`);
+  const previous = existing ? fs.readFileSync(filename, 'utf8') : undefined;
+  if (previous !== undefined && previous !== content && previous !== template) {
+    const owned = /^([\s\S]*)\n<!-- zan-saas-cli host-entry sha256:([a-f0-9]{64}) -->\n$/.exec(previous);
+    if (!owned || sha256(owned[1]) !== owned[2]) {
+      throw new Error(`同名 Skill 不属于本安装器或已被修改，已保留：${filename}`);
+    }
+  }
+  if (!existing && folder && fs.readdirSync(directory).length > 0) {
+    throw new Error(`同名目录包含其他文件，已保留：${directory}`);
+  }
+  return { filename, content, previous, mode: existing ? existing.mode & 0o777 : 0o644,
+    action: previous === content ? 'unchanged' : existing ? 'update' : 'create' };
+}
+
+function writeSkill(plan) {
+  if (plan.action === 'unchanged') return;
+  const { filename, content, previous, mode } = plan;
+  const directory = path.dirname(filename);
+  fs.mkdirSync(directory, { recursive: true });
+  if (previous === undefined) {
+    fs.writeFileSync(filename, content, { flag: 'wx', mode });
+    return;
+  }
+  const temporary = path.join(directory, `.SKILL-${randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, content, { flag: 'wx', mode });
+    if (!stat(filename)?.isFile() || fs.readFileSync(filename, 'utf8') !== previous) {
+      throw new Error(`安装期间目标发生变化，已保留：${filename}`);
+    }
+    fs.renameSync(temporary, filename);
+  } finally { fs.rmSync(temporary, { force: true }); }
+}
+
+module.exports = { hosts, stat, selectedHosts, detectedHosts, readTemplate, prepareSkill, writeSkill };