@guanwenai/high-tech-project-cli 0.1.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@guanwenai/high-tech-project-cli",
+  "version": "0.1.0",
+  "description": "Gateway-only CLI for Chinese high-tech enterprise project declarations",
+  "type": "module",
+  "bin": {
+    "high-tech-project": "scripts/high-tech-project-cli.mjs"
+  },
+  "files": [
+    "scripts"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install/configure-gateway.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/cli/arguments.mjs

@@ -0,0 +1,54 @@
+import { CliError } from '../core/errors.mjs';
+
+const OPTION_NAMES = new Map([
+  ['--input', 'input'],
+  ['--base-dir', 'baseDir'],
+  ['--gateway-url', 'gatewayUrl'],
+  ['--tenant-code', 'tenantCode'],
+  ['--user-id', 'userId'],
+  ['--user-name', 'userName'],
+  ['--realname', 'realname'],
+  ['--context-id', 'contextId'],
+  ['--pretty', 'pretty'],
+]);
+
+function invalid(message, details = {}) {
+  throw new CliError('ARGUMENT_INVALID', message, details);
+}
+
+export function parseArguments(argv) {
+  const optionStart = argv.findIndex((token) => token.startsWith('--'));
+  const commandTokens = optionStart === -1 ? argv : argv.slice(0, optionStart);
+  const optionTokens = optionStart === -1 ? [] : argv.slice(optionStart);
+  if (commandTokens.length < 1 || commandTokens.length > 2) {
+    invalid('命令格式应为 <domain> <operation>');
+  }
+
+  const options = {};
+  for (let index = 0; index < optionTokens.length; index += 1) {
+    const token = optionTokens[index];
+    if (token === '--uuid') {
+      invalid('当前项目由 contextId 唯一绑定，禁止通过 --uuid 覆盖');
+    }
+    const optionName = OPTION_NAMES.get(token);
+    if (!optionName) {
+      invalid(token === '--kfcloud-auth' ? '认证令牌禁止通过命令行传入' : `未知参数: ${token}`);
+    }
+    if (Object.hasOwn(options, optionName)) {
+      invalid(`参数不可重复: ${token}`);
+    }
+    if (token === '--pretty') {
+      options[optionName] = true;
+      continue;
+    }
+
+    const value = optionTokens[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      invalid(`参数缺少值: ${token}`);
+    }
+    options[optionName] = value;
+    index += 1;
+  }
+
+  return { command: commandTokens.join('.'), options };
+}

package/scripts/cli/commandRegistry.mjs

@@ -0,0 +1,80 @@
+import { CliError } from '../core/errors.mjs';
+
+const METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'LOCAL']);
+const ALLOWED_PATHS = [
+  '/api/internal/v1/project-writing/',
+  '/api/project-writing/',
+  '/api/knowledge/',
+  '/api/v1/knowledge/',
+  '/api/file-storage/',
+];
+
+function invalidDefinition(message, details = {}) {
+  throw new CliError('CLI_INTERNAL_ERROR', message, details);
+}
+
+function validatePath(path) {
+  return typeof path === 'string'
+    && !path.includes('\\')
+    && !path.split('/').includes('..')
+    && ALLOWED_PATHS.some((prefix) => path.startsWith(prefix));
+}
+
+function isMutatingPath(path) {
+  const action = path.split('/').at(-1) ?? '';
+  return /^(?:create|update|save|save-or-update|batch-save|delete|delete-batch|generate|sort|upload|import|bind(?:-|$)|move|retry)/u
+    .test(action);
+}
+
+function validateDefinition(definition) {
+  if (!definition || typeof definition !== 'object') {
+    invalidDefinition('命令定义必须是对象');
+  }
+  if (!/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)?$/u.test(definition.name ?? '')) {
+    invalidDefinition('命令名称无效', { name: definition.name });
+  }
+  if (!METHODS.has(definition.method)) {
+    invalidDefinition('命令方法无效', { name: definition.name, method: definition.method });
+  }
+  if (definition.method === 'LOCAL') {
+    if (definition.path !== null) {
+      invalidDefinition('本地命令不能声明 gateway 路径', { name: definition.name });
+    }
+  } else if (!validatePath(definition.path)) {
+    invalidDefinition('命令路径无效', { name: definition.name, path: definition.path });
+  }
+  if (definition.idempotent === true && definition.method !== 'LOCAL'
+    && isMutatingPath(definition.path)) {
+    invalidDefinition('写命令不能标记为幂等', { name: definition.name });
+  }
+  if (!Array.isArray(definition.requiredContext)
+    || definition.requiredContext.some((field) => typeof field !== 'string')) {
+    invalidDefinition('requiredContext 必须是字符串数组', { name: definition.name });
+  }
+  if (typeof definition.validate !== 'function') {
+    invalidDefinition('命令缺少 validate', { name: definition.name });
+  }
+  if (typeof definition.handler !== 'function') {
+    invalidDefinition('命令缺少 handler', { name: definition.name });
+  }
+}
+
+export class CommandRegistry {
+  #commands = new Map();
+
+  register(definition) {
+    validateDefinition(definition);
+    if (this.#commands.has(definition.name)) {
+      invalidDefinition('命令不可重复注册', { name: definition.name });
+    }
+    this.#commands.set(definition.name, definition);
+  }
+
+  get(name) {
+    return this.#commands.get(name);
+  }
+
+  list() {
+    return [...this.#commands.values()];
+  }
+}

package/scripts/cli/output.mjs

@@ -0,0 +1,23 @@
+import { normalizeCliError } from '../core/errors.mjs';
+
+export function successEnvelope(command, data, meta) {
+  return { ok: true, command, data, meta };
+}
+
+export function failureEnvelope(command, error, meta) {
+  const normalized = normalizeCliError(error);
+  return {
+    ok: false,
+    command,
+    error: {
+      code: normalized.code,
+      message: normalized.message,
+      details: normalized.details ?? {},
+    },
+    meta,
+  };
+}
+
+export function serializeEnvelope(envelope, pretty = false) {
+  return JSON.stringify(envelope, null, pretty ? 2 : undefined);
+}

package/scripts/core/context.mjs

@@ -0,0 +1,35 @@
+const ENVIRONMENT_FIELDS = {
+  gatewayUrl: 'GUANWEN_PROJECT_WRITING_GATEWAY_URL',
+  tenantCode: 'GUANWEN_PROJECT_WRITING_TENANT_CODE',
+  userId: 'GUANWEN_PROJECT_WRITING_USER_ID',
+  userName: 'GUANWEN_PROJECT_WRITING_USER_NAME',
+  realname: 'GUANWEN_PROJECT_WRITING_REALNAME',
+  contextId: 'GUANWEN_PROJECT_WRITING_CONTEXT_ID',
+};
+
+function firstDefined(...values) {
+  const value = values.find((candidate) => (
+    candidate !== undefined && candidate !== null && String(candidate).trim() !== ''
+  ));
+  return value === undefined ? '' : String(value);
+}
+
+export function resolveProjectContext({
+  options = {}, input = {}, environment = {}, configuration = {},
+}) {
+  const context = {};
+  for (const [field, environmentName] of Object.entries(ENVIRONMENT_FIELDS)) {
+    context[field] = firstDefined(options[field], input[field], environment[environmentName]);
+  }
+
+  return {
+    gatewayUrl: firstDefined(context.gatewayUrl, configuration.gatewayUrl),
+    kfcloudAuth: firstDefined(environment.GUANWEN_PROJECT_WRITING_KFCLOUD_AUTH),
+    tenantCode: context.tenantCode,
+    userId: context.userId,
+    userName: context.userName,
+    realname: context.realname,
+    contextId: context.contextId,
+    uuid: context.contextId,
+  };
+}

package/scripts/core/errors.mjs

@@ -0,0 +1,37 @@
+const EXIT_CODES = new Map([
+  ['ARGUMENT_INVALID', 2],
+  ['CONFIG_MISSING', 2],
+  ['CONFIG_INVALID', 2],
+  ['AUTH_EXPIRED', 3],
+  ['AUTH_FORBIDDEN', 3],
+  ['BUSINESS_ERROR', 4],
+  ['NETWORK_ERROR', 5],
+  ['GATEWAY_TIMEOUT', 5],
+  ['FILE_NOT_FOUND', 6],
+  ['FILE_OUTSIDE_BASE', 6],
+  ['FILE_TOO_LARGE', 6],
+  ['FILE_WRITE_FAILED', 6],
+  ['CLI_INTERNAL_ERROR', 7],
+]);
+
+export function exitCodeForError(code) {
+  return EXIT_CODES.get(code) ?? 4;
+}
+
+export class CliError extends Error {
+  constructor(code, message, details = {}, exitCode = exitCodeForError(code)) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.details = details;
+    this.exitCode = exitCode;
+  }
+}
+
+export function normalizeCliError(error) {
+  if (error instanceof CliError) {
+    return error;
+  }
+
+  return new CliError('CLI_INTERNAL_ERROR', 'CLI 执行失败', {}, 7);
+}

package/scripts/core/files.mjs

@@ -0,0 +1,143 @@
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { CliError } from './errors.mjs';
+
+export const MAX_INPUT_BYTES = 10 * 1024 * 1024;
+
+function pathDetails(relativePath, baseDir, resolvedPath) {
+  return { relativePath, baseDir, resolvedPath };
+}
+
+export function resolveWithinBase(relativePath, baseDir) {
+  const resolvedBase = resolve(baseDir);
+  const resolvedPath = resolve(resolvedBase, relativePath);
+  const relation = relative(resolvedBase, resolvedPath);
+  const outside = isAbsolute(relativePath)
+    || relation === '..'
+    || relation.startsWith(`..${sep}`)
+    || isAbsolute(relation);
+
+  if (outside) {
+    throw new CliError(
+      'FILE_OUTSIDE_BASE',
+      '文件路径超出工作目录',
+      pathDetails(relativePath, baseDir, resolvedPath),
+    );
+  }
+
+  return resolvedPath;
+}
+
+function skipWhitespace(source, state) {
+  while (/\s/u.test(source[state.index] ?? '')) {
+    state.index += 1;
+  }
+}
+
+function readString(source, state) {
+  const start = state.index;
+  state.index += 1;
+  while (state.index < source.length) {
+    if (source[state.index] === '\\') {
+      state.index += 2;
+      continue;
+    }
+    if (source[state.index] === '"') {
+      state.index += 1;
+      return JSON.parse(source.slice(start, state.index));
+    }
+    state.index += 1;
+  }
+  return '';
+}
+
+function scanValue(source, state) {
+  skipWhitespace(source, state);
+  if (source[state.index] === '{') {
+    scanObject(source, state);
+    return;
+  }
+  if (source[state.index] === '[') {
+    state.index += 1;
+    skipWhitespace(source, state);
+    while (source[state.index] !== ']') {
+      scanValue(source, state);
+      skipWhitespace(source, state);
+      if (source[state.index] === ',') {
+        state.index += 1;
+        skipWhitespace(source, state);
+      }
+    }
+    state.index += 1;
+    return;
+  }
+  if (source[state.index] === '"') {
+    readString(source, state);
+    return;
+  }
+  while (state.index < source.length && !/[\s,}\]]/u.test(source[state.index])) {
+    state.index += 1;
+  }
+}
+
+function scanObject(source, state) {
+  const keys = new Set();
+  state.index += 1;
+  skipWhitespace(source, state);
+  while (source[state.index] !== '}') {
+    const key = readString(source, state);
+    if (keys.has(key)) {
+      throw new CliError('ARGUMENT_INVALID', `JSON 对象包含重复字段: ${key}`);
+    }
+    keys.add(key);
+    skipWhitespace(source, state);
+    state.index += 1;
+    scanValue(source, state);
+    skipWhitespace(source, state);
+    if (source[state.index] === ',') {
+      state.index += 1;
+      skipWhitespace(source, state);
+    }
+  }
+  state.index += 1;
+}
+
+function rejectDuplicateKeys(source) {
+  scanValue(source, { index: 0 });
+}
+
+export async function readJsonInput(relativePath, baseDir) {
+  const resolvedPath = resolveWithinBase(relativePath, baseDir);
+  const details = pathDetails(relativePath, baseDir, resolvedPath);
+  let fileStat;
+  try {
+    fileStat = await stat(resolvedPath);
+  } catch {
+    throw new CliError('FILE_NOT_FOUND', '输入文件不存在', details);
+  }
+
+  if (!fileStat.isFile()) {
+    throw new CliError('FILE_NOT_FOUND', '输入路径不是文件', details);
+  }
+  if (fileStat.size > MAX_INPUT_BYTES) {
+    throw new CliError('FILE_TOO_LARGE', '输入文件超过 10 MiB', details);
+  }
+
+  const source = await readFile(resolvedPath, 'utf8');
+  let value;
+  try {
+    value = JSON.parse(source);
+    rejectDuplicateKeys(source);
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+    throw new CliError('ARGUMENT_INVALID', '输入文件不是合法 JSON', details);
+  }
+
+  if (value === null || Array.isArray(value) || typeof value !== 'object') {
+    throw new CliError('ARGUMENT_INVALID', '输入 JSON 根节点必须是对象', details);
+  }
+  return value;
+}

package/scripts/core/gatewayClient.mjs

@@ -0,0 +1,275 @@
+import { CliError } from './errors.mjs';
+
+const ALLOWED_PATHS = [
+  '/api/internal/v1/project-writing/',
+  '/api/project-writing/',
+  '/api/knowledge/',
+  '/api/v1/knowledge/',
+  '/api/file-storage/',
+];
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+const FORBIDDEN_AGENT_PATH = ['/api', 'agent/'].join('/');
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_FILE_TIMEOUT_MS = 120_000;
+
+function validateGatewayUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new CliError('ARGUMENT_INVALID', 'gateway URL 无效');
+  }
+  if (!['http:', 'https:'].includes(url.protocol)
+    || url.username
+    || url.password
+    || url.hash) {
+    throw new CliError('ARGUMENT_INVALID', 'gateway URL 必须是安全的 HTTP(S) 基础地址');
+  }
+  return url;
+}
+
+function validatePath(path) {
+  if (typeof path !== 'string'
+    || !path.startsWith('/')
+    || path.startsWith('//')
+    || path.includes('\\')) {
+    throw new CliError('ARGUMENT_INVALID', 'gateway 路径无效');
+  }
+
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(path);
+  } catch {
+    throw new CliError('ARGUMENT_INVALID', 'gateway 路径编码无效');
+  }
+  if (decodedPath.split('/').includes('..')
+    || decodedPath.startsWith(FORBIDDEN_AGENT_PATH)
+    || !ALLOWED_PATHS.some((prefix) => decodedPath.startsWith(prefix))) {
+    throw new CliError('ARGUMENT_INVALID', 'gateway 路径不在允许范围内');
+  }
+}
+
+function normalizeTimeout(value, fallback) {
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function headerValue(value) {
+  const text = String(value ?? '').trim();
+  return /^[\x20-\xFF]*$/u.test(text) ? text : encodeURIComponent(text);
+}
+
+function contextHeaders(context) {
+  const headers = {};
+  const fields = [
+    ['kfcloud-auth', 'kfcloudAuth'],
+    ['tenant-code', 'tenantCode'],
+    ['user-id', 'userId'],
+    ['user-name', 'userName'],
+    ['realname', 'realname'],
+    ['context-id', 'contextId'],
+  ];
+  for (const [header, field] of fields) {
+    if (context[field]) {
+      headers[header] = headerValue(context[field]);
+    }
+  }
+  return headers;
+}
+
+function buildUrl(gatewayUrl, path, query = {}) {
+  const url = new URL(path, gatewayUrl);
+  for (const [key, rawValue] of Object.entries(query)) {
+    if (rawValue === undefined || rawValue === null) {
+      continue;
+    }
+    const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+    for (const value of values) {
+      url.searchParams.append(key, String(value));
+    }
+  }
+  return url.toString();
+}
+
+function redact(text, secret) {
+  const value = String(text ?? '');
+  return secret ? value.split(secret).join('[REDACTED]') : value;
+}
+
+function safeMessage(payload, fallback, secret) {
+  const raw = payload?.msg ?? payload?.message ?? fallback;
+  const message = typeof raw === 'string' ? raw : JSON.stringify(raw);
+  return redact(message, secret);
+}
+
+function authError(status) {
+  return status === 401
+    ? new CliError('AUTH_EXPIRED', '登录状态已过期', { httpStatus: status })
+    : new CliError('AUTH_FORBIDDEN', '当前账户无权执行此操作', { httpStatus: status });
+}
+
+async function parseJsonResponse(response, secret) {
+  const text = await response.text();
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    const responseSummary = redact(text.slice(0, 500), secret);
+    const code = RETRYABLE_STATUS.has(response.status) ? 'NETWORK_ERROR' : 'BUSINESS_ERROR';
+    throw new CliError(code, 'gateway 返回了非 JSON 响应', {
+      httpStatus: response.status,
+      responseSummary,
+      retryable: RETRYABLE_STATUS.has(response.status),
+    });
+  }
+
+  const rawCode = payload?.code;
+  const numericCode = rawCode === undefined || rawCode === null || rawCode === ''
+    ? undefined
+    : Number(rawCode);
+  const authStatus = response.status === 401 || response.status === 403
+    ? response.status
+    : numericCode === 401 || numericCode === 403 ? numericCode : undefined;
+  if (authStatus) {
+    throw authError(authStatus);
+  }
+  if (RETRYABLE_STATUS.has(response.status)) {
+    throw new CliError('NETWORK_ERROR', safeMessage(payload, 'gateway 暂时不可用', secret), {
+      httpStatus: response.status,
+      retryable: true,
+    });
+  }
+
+  const successCode = rawCode === undefined || rawCode === null || rawCode === ''
+    || numericCode === 0
+    || numericCode === 200;
+  if (!response.ok || !successCode) {
+    const code = successCode ? 'BUSINESS_ERROR' : String(rawCode);
+    throw new CliError(code, safeMessage(payload, '业务请求失败', secret), {
+      httpStatus: response.status,
+      backendCode: rawCode,
+    });
+  }
+  return Object.hasOwn(payload, 'data') ? payload.data : payload;
+}
+
+export class GatewayClient {
+  constructor({
+    context,
+    fetchImpl = globalThis.fetch,
+    logger = console,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fileTimeoutMs = DEFAULT_FILE_TIMEOUT_MS,
+  }) {
+    this.context = context ?? {};
+    this.gatewayUrl = validateGatewayUrl(this.context.gatewayUrl);
+    this.fetchImpl = fetchImpl;
+    this.logger = logger;
+    this.timeoutMs = normalizeTimeout(timeoutMs, DEFAULT_TIMEOUT_MS);
+    this.fileTimeoutMs = normalizeTimeout(fileTimeoutMs, DEFAULT_FILE_TIMEOUT_MS);
+  }
+
+  async request({ method = 'GET', path, query, body, idempotent = false }) {
+    const normalizedMethod = method.toUpperCase();
+    const retryable = idempotent;
+    return await this.#withRetry({
+      method: normalizedMethod,
+      path,
+      query,
+      body,
+      timeoutMs: this.timeoutMs,
+      retryable,
+      responseHandler: (response) => parseJsonResponse(response, this.context.kfcloudAuth),
+    });
+  }
+
+  async upload({ path, formData }) {
+    return await this.#withRetry({
+      method: 'POST',
+      path,
+      body: formData,
+      timeoutMs: this.fileTimeoutMs,
+      retryable: false,
+      responseHandler: (response) => parseJsonResponse(response, this.context.kfcloudAuth),
+    });
+  }
+
+  async download({ path, query, method = 'POST', body }) {
+    return await this.#withRetry({
+      method: method.toUpperCase(),
+      path,
+      query,
+      body,
+      timeoutMs: this.fileTimeoutMs,
+      retryable: false,
+      responseHandler: async (response) => {
+        if (!response.ok) {
+          return await parseJsonResponse(response, this.context.kfcloudAuth);
+        }
+        const length = Number(response.headers.get('content-length'));
+        return {
+          body: response.body,
+          contentType: response.headers.get('content-type') ?? '',
+          contentLength: Number.isFinite(length) ? length : null,
+          disposition: response.headers.get('content-disposition') ?? '',
+        };
+      },
+    });
+  }
+
+  async #withRetry(input) {
+    validatePath(input.path);
+    const attempts = input.retryable ? 2 : 1;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        const response = await this.#fetch(input);
+        return await input.responseHandler(response);
+      } catch (error) {
+        const canRetry = attempt < attempts
+          && (error instanceof TypeError || error?.details?.retryable === true);
+        if (canRetry) {
+          this.logger?.warn?.({ event: 'gateway_retry', path: input.path, attempt });
+          continue;
+        }
+        if (error instanceof CliError) {
+          throw error;
+        }
+        if (error?.name === 'AbortError') {
+          throw new CliError('GATEWAY_TIMEOUT', 'gateway 请求超时', { path: input.path });
+        }
+        throw new CliError('NETWORK_ERROR', '无法连接 gateway', { path: input.path });
+      }
+    }
+    throw new CliError('NETWORK_ERROR', '无法连接 gateway', { path: input.path });
+  }
+
+  async #fetch({ method, path, query, body, timeoutMs }) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    const headers = contextHeaders(this.context);
+    let requestBody = body;
+    if (body !== undefined && body !== null && !(body instanceof FormData)) {
+      headers['content-type'] = 'application/json';
+      requestBody = JSON.stringify(body);
+    }
+
+    try {
+      return await this.fetchImpl(buildUrl(this.gatewayUrl, path, query), {
+        method,
+        headers,
+        body: requestBody,
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (timedOut) {
+        throw new CliError('GATEWAY_TIMEOUT', 'gateway 请求超时', { path });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}