@besile/scm-cli 2026.3.29

package/src/internal/errors/scm-errors.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * SCM 错误类型定义
+ *
+ * 所有与认证/授权/API 调用相关的错误类型集中在此文件。
+ */
+
+// ---------------------------------------------------------------------------
+// SCM Error Codes
+// ---------------------------------------------------------------------------
+export const SCM_ERROR = {
+    // 认证错误
+    AUTH_FAILED: 401,
+    AUTH_TOKEN_EXPIRED: 40101,
+    AUTH_TOKEN_INVALID: 40102,
+    AUTH_PERMISSION_DENIED: 403,
+
+    // API 错误
+    API_REQUEST_FAILED: 500,
+    API_TIMEOUT: 50001,
+    API_NETWORK_ERROR: 50002,
+    API_PARAM_ERROR: 400,
+
+    // 业务错误
+    USER_NOT_LOGGED_IN: 10001,
+    USER_LOGIN_EXPIRED: 10002,
+    TOKEN_REFRESH_FAILED: 10003,
+};
+
+// ---------------------------------------------------------------------------
+// Error Classes
+// ---------------------------------------------------------------------------
+
+/**
+ * 基础 SCM 错误类
+ */
+export class ScmError extends Error {
+    constructor(message, code, details = {}) {
+        super(message);
+        this.name = 'ScmError';
+        this.code = code;
+        this.details = details;
+    }
+}
+
+/**
+ * 认证错误 - 登录失败或凭据无效
+ */
+export class ScmAuthError extends ScmError {
+    constructor(message, code = SCM_ERROR.AUTH_FAILED, details = {}) {
+        super(message, code, details);
+        this.name = 'ScmAuthError';
+    }
+}
+
+/**
+ * Token 过期错误 - 需要重新登录
+ */
+export class ScmTokenExpiredError extends ScmAuthError {
+    constructor(message = 'Token 已过期，需要重新登录', details = {}) {
+        super(message, SCM_ERROR.AUTH_TOKEN_EXPIRED, details);
+        this.name = 'ScmTokenExpiredError';
+    }
+}
+
+/**
+ * Token 无效错误 - Token 格式错误或被撤销
+ */
+export class ScmTokenInvalidError extends ScmAuthError {
+    constructor(message = 'Token 无效', details = {}) {
+        super(message, SCM_ERROR.AUTH_TOKEN_INVALID, details);
+        this.name = 'ScmTokenInvalidError';
+    }
+}
+
+/**
+ * 用户未登录错误
+ */
+export class ScmUserNotLoggedInError extends ScmAuthError {
+    constructor(openId, details = {}) {
+        super(`用户 ${openId} 未登录，请先调用 scm_login 工具`, SCM_ERROR.USER_NOT_LOGGED_IN, {
+            openId,
+            ...details,
+        });
+        this.name = 'ScmUserNotLoggedInError';
+    }
+}
+
+/**
+ * API 调用错误
+ */
+export class ScmApiError extends ScmError {
+    constructor(message, code = SCM_ERROR.API_REQUEST_FAILED, details = {}) {
+        super(message, code, details);
+        this.name = 'ScmApiError';
+    }
+}
+
+/**
+ * API 超时错误
+ */
+export class ScmTimeoutError extends ScmApiError {
+    constructor(message = 'API 请求超时', details = {}) {
+        super(message, SCM_ERROR.API_TIMEOUT, details);
+        this.name = 'ScmTimeoutError';
+    }
+}
+
+/**
+ * 网络错误
+ */
+export class ScmNetworkError extends ScmApiError {
+    constructor(message = '网络错误', details = {}) {
+        super(message, SCM_ERROR.API_NETWORK_ERROR, details);
+        this.name = 'ScmNetworkError';
+    }
+}
+
+/**
+ * 参数错误
+ */
+export class ScmParamError extends ScmApiError {
+    constructor(message, details = {}) {
+        super(message, SCM_ERROR.API_PARAM_ERROR, details);
+        this.name = 'ScmParamError';
+    }
+}
+
+/**
+ * 权限不足错误
+ */
+export class ScmPermissionDeniedError extends ScmAuthError {
+    constructor(message = '权限不足', details = {}) {
+        super(message, SCM_ERROR.AUTH_PERMISSION_DENIED, details);
+        this.name = 'ScmPermissionDeniedError';
+    }
+}

package/src/internal/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * internal/ barrel export — re-export all internal modules
+ */
+
+// Client
+export { scmClient, ScmClient } from './client/scm-client.js';
+
+// Errors
+export {
+    ScmError,
+    ScmAuthError,
+    ScmTokenExpiredError,
+    ScmTokenInvalidError,
+    ScmUserNotLoggedInError,
+    ScmApiError,
+    ScmTimeoutError,
+    ScmNetworkError,
+    ScmParamError,
+    ScmPermissionDeniedError,
+    SCM_ERROR,
+} from './errors/scm-errors.js';
+
+// Output
+export { scmLogger, setRuntimeLoggerFactory, setLogLevel, getLogLevel } from './output/logger.js';
+export { coreLogger, tokenLogger, clientLogger, loginLogger, ordersLogger } from './output/logger.js';
+export { formatOutput } from './output/formatter.js';
+
+// Config
+export { loadConfig, createLogger } from './config/config.js';
+
+// Auth / Token Store
+export {
+    getCachedToken,
+    checkToken,
+    TOKEN_FILE_PATH,
+    printLoginHint,
+    promptLogin,
+    withAuth,
+} from './auth/token-store.js';

package/src/internal/output/formatter.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * Output formatter — json, table, pretty, ndjson, csv
+ */
+
+const TAB = '  ';
+
+/**
+ * Format data as JSON
+ */
+function formatJson(data) {
+    return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Format data as pretty (human-readable)
+ */
+function formatPretty(data) {
+    if (typeof data === 'string') return data;
+    return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Format data as ndjson (newline-delimited JSON)
+ */
+function formatNdjson(data) {
+    if (Array.isArray(data)) {
+        return data.map(item => JSON.stringify(item)).join('\n');
+    }
+    return JSON.stringify(data);
+}
+
+/**
+ * Format data as CSV (arrays of objects only)
+ */
+function formatCsv(data) {
+    const rows = Array.isArray(data) ? data : [data];
+    if (rows.length === 0) return '';
+
+    const keys = Object.keys(rows[0]);
+    const header = keys.join(',');
+    const body = rows.map(row =>
+        keys.map(k => {
+            const val = String(row[k] ?? '');
+            // Escape quotes and wrap if contains comma/quote
+            if (val.includes(',') || val.includes('"') || val.includes('\n')) {
+                return `"${val.replace(/"/g, '""')}"`;
+            }
+            return val;
+        }).join(',')
+    ).join('\n');
+
+    return [header, body].join('\n');
+}
+
+/**
+ * Format orders list as ASCII table
+ */
+function formatTable(data) {
+    const rows = Array.isArray(data) ? data : (data?.list || [data]);
+    if (!rows || rows.length === 0) {
+        return 'No results found.';
+    }
+
+    const keys = Object.keys(rows[0]);
+    const colWidths = {};
+    for (const key of keys) {
+        colWidths[key] = Math.max(
+            key.length,
+            ...rows.map(r => String(r[key] ?? '').length)
+        );
+    }
+
+    const totalWidth = Object.values(colWidths).reduce((a, b) => a + b, 0) + keys.length * 3 + 1;
+    const sep = '─'.repeat(Math.min(totalWidth, 120));
+
+    const lines = [];
+    lines.push('┌' + sep + '┐');
+    lines.push('│ ' + keys.map(k => String(k).padEnd(colWidths[k])).join(' │ ') + ' │');
+    lines.push('├' + sep + '┤');
+
+    for (const row of rows) {
+        const vals = keys.map(k => String(row[k] ?? '').padEnd(colWidths[k]));
+        lines.push('│ ' + vals.join(' │ ') + ' │');
+    }
+
+    lines.push('└' + sep + '┘');
+
+    if (data?.total !== undefined) {
+        lines.push(`Total: ${data.total}`);
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format output based on format type
+ *
+ * @param {*} data - Data to format
+ * @param {string} format - Format: 'json' | 'table' | 'pretty' | 'ndjson' | 'csv'
+ * @returns {string} Formatted output
+ */
+export function formatOutput(data, format = 'table') {
+    switch (format) {
+        case 'json':
+            return formatJson(data);
+        case 'pretty':
+            return formatPretty(data);
+        case 'ndjson':
+            return formatNdjson(data);
+        case 'csv':
+            return formatCsv(data);
+        case 'table':
+        default:
+            return formatTable(data);
+    }
+}

package/src/internal/output/logger.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * SCM 统一日志模块
+ *
+ * 基于 openclaw-lark 的 lark-logger 模式实现，
+ * 支持 PluginRuntime 日志和 console 回退。
+ */
+
+// ---------------------------------------------------------------------------
+// Console fallback (with ANSI colors)
+// ---------------------------------------------------------------------------
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const GRAY = '\x1b[90m';
+const RESET = '\x1b[0m';
+
+function consoleFallback(subsystem) {
+    const tag = `scm/${subsystem}`;
+    /* eslint-disable no-console -- logger底层实现，console 是最终输出目标 */
+    return {
+        debug: (msg, meta) => console.debug(`${GRAY}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+        info: (msg, meta) => console.log(`${CYAN}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+        warn: (msg, meta) => console.warn(`${YELLOW}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+        error: (msg, meta) => console.error(`${RED}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+    };
+    /* eslint-enable no-console */
+}
+
+// ---------------------------------------------------------------------------
+// Runtime logger storage
+// ---------------------------------------------------------------------------
+let _runtimeLoggerFactory = null;
+
+/**
+ * 设置运行时日志工厂
+ * @param {Function} factory - LarkClient.runtime.logging.getChildLogger
+ */
+export function setRuntimeLoggerFactory(factory) {
+    _runtimeLoggerFactory = factory;
+}
+
+function resolveRuntimeLogger(subsystem) {
+    if (!_runtimeLoggerFactory) {
+        return null;
+    }
+    try {
+        return _runtimeLoggerFactory({ subsystem: `scm/${subsystem}` });
+    } catch {
+        return null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Log level control
+// ---------------------------------------------------------------------------
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+
+let _currentLevel = LOG_LEVELS.info;
+
+export function setLogLevel(level) {
+    if (LOG_LEVELS[level] !== undefined) {
+        _currentLevel = LOG_LEVELS[level];
+    }
+}
+
+export function getLogLevel() {
+    return Object.keys(LOG_LEVELS).find(key => LOG_LEVELS[key] === _currentLevel) || 'info';
+}
+
+// ---------------------------------------------------------------------------
+// Logger implementation
+// ---------------------------------------------------------------------------
+function createScmLogger(subsystem) {
+    let cachedLogger = null;
+    let resolved = false;
+
+    function getLogger() {
+        if (!resolved) {
+            cachedLogger = resolveRuntimeLogger(subsystem);
+            if (cachedLogger) {
+                resolved = true;
+            }
+        }
+        return cachedLogger ?? consoleFallback(subsystem);
+    }
+
+    function formatMessage(message, meta) {
+        if (!meta || Object.keys(meta).length === 0) {
+            return `${subsystem}: ${message}`;
+        }
+        const parts = Object.entries(meta)
+            .map(([k, v]) => {
+                if (v === undefined || v === null) return null;
+                if (typeof v === 'object') return `${k}=${JSON.stringify(v)}`;
+                return `${k}=${v}`;
+            })
+            .filter(Boolean);
+        return parts.length > 0
+            ? `${subsystem}: ${message} (${parts.join(', ')})`
+            : `${subsystem}: ${message}`;
+    }
+
+    function shouldLog(level) {
+        return LOG_LEVELS[level] >= _currentLevel;
+    }
+
+    return {
+        subsystem,
+        debug(message, meta) {
+            if (shouldLog('debug')) {
+                getLogger().debug?.(formatMessage(message, meta), meta);
+            }
+        },
+        info(message, meta) {
+            if (shouldLog('info')) {
+                getLogger().info(formatMessage(message, meta), meta);
+            }
+        },
+        warn(message, meta) {
+            if (shouldLog('warn')) {
+                getLogger().warn(formatMessage(message, meta), meta);
+            }
+        },
+        error(message, meta) {
+            if (shouldLog('error')) {
+                getLogger().error(formatMessage(message, meta), meta);
+            }
+        },
+        child(name) {
+            return createScmLogger(`${subsystem}/${name}`);
+        },
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * 创建 SCM 模块日志器
+ * @param {string} subsystem - 子系统名称，如 'core/client', 'tools/login'
+ * @returns {Object} 日志器对象 { debug, info, warn, error, child }
+ *
+ * @example
+ * const log = scmLogger('core/client');
+ * log.info('Client initialized', { baseUrl: 'http://localhost:48080' });
+ * log.error('Request failed', { error: err.message });
+ */
+export function scmLogger(subsystem) {
+    return createScmLogger(subsystem);
+}
+
+// ---------------------------------------------------------------------------
+// Pre-configured loggers
+// ---------------------------------------------------------------------------
+export const coreLogger = scmLogger('core');
+export const tokenLogger = scmLogger('core/token');
+export const clientLogger = scmLogger('core/client');
+export const loginLogger = scmLogger('cmd/auth');
+export const ordersLogger = scmLogger('cmd/orders');

package/src/shortcuts/common/runner.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * Shortcut runner — execution pipeline
+ *
+ * Inspired by lark-cli's shortcuts/common/runner.go
+ *
+ * Responsibilities:
+ * - Parse flag values from runtime (supports @file and stdin input)
+ * - Inject --format flag and route output
+ * - Call shortcut.execute() with context
+ * - Handle errors with structured output
+ */
+
+import { createReadStream } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { formatOutput } from '../../internal/output/formatter.js';
+
+/**
+ * Resolve flag input — supports plain value, @file path, or stdin '-'
+ *
+ * @param {string} value - Flag value from CLI
+ * @returns {Promise<string>} Resolved value
+ */
+export async function resolveFlagInput(value) {
+    if (!value || typeof value !== 'string') {
+        return value;
+    }
+
+    const trimmed = value.trim();
+
+    if (trimmed === '-') {
+        // Read from stdin
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks).toString('utf-8').trim();
+    }
+
+    if (trimmed.startsWith('@')) {
+        // Read from file
+        const filePath = trimmed.slice(1);
+        return await readFile(filePath, 'utf-8');
+    }
+
+    return value;
+}
+
+/**
+ * Build runtime context for shortcut execution
+ *
+ * @param {Object} shortcut - Shortcut definition
+ * @param {Object} flags - Parsed flag values from CLI
+ * @param {Object} internalCtx - Internal context (client, config, etc.)
+ * @returns {Object} Runtime context
+ */
+export async function buildRuntime(shortcut, flags, internalCtx) {
+    const resolvedFlags = {};
+
+    for (const flag of (shortcut.flags || [])) {
+        const rawValue = flags[flag.name] ?? flags[flag.name.replace(/-/g, '')] ?? flag.default;
+        if (rawValue !== undefined) {
+            resolvedFlags[flag.name] = await resolveFlagInput(String(rawValue));
+        }
+    }
+
+    // Handle --format from flags or default to 'table'
+    const format = resolvedFlags.format || flags.format || 'table';
+
+    return {
+        flags: resolvedFlags,
+        format,
+        internal: internalCtx,
+        log: internalCtx.log || console,
+    };
+}
+
+/**
+ * Run a shortcut
+ *
+ * @param {Object} shortcut - Shortcut definition
+ * @param {Object} runtime - Runtime context from buildRuntime
+ * @returns {Promise<Object>} Execution result
+ */
+export async function runShortcut(shortcut, runtime) {
+    // Validate
+    if (shortcut.validate) {
+        const err = shortcut.validate(runtime.internal, runtime);
+        if (err) {
+            return { success: false, error: err.message || String(err) };
+        }
+    }
+
+    // Execute
+    let result;
+    try {
+        result = await shortcut.execute(runtime.internal, runtime);
+    } catch (err) {
+        return { success: false, error: err.message || String(err) };
+    }
+
+    // Format output
+    const formatted = formatOutput(result, runtime.format);
+
+    return {
+        success: true,
+        data: result,
+        formatted,
+        format: runtime.format,
+    };
+}
+
+/**
+ * Create CLI action handler for a shortcut
+ *
+ * @param {Object} shortcut - Shortcut definition
+ * @param {Object} internalCtx - Internal context (client, config)
+ * @returns {Function} Commander action handler
+ */
+export function shortcutAction(shortcut, internalCtx) {
+    return async function (opts) {
+        try {
+            const runtime = await buildRuntime(shortcut, opts, internalCtx);
+            const result = await runShortcut(shortcut, runtime);
+
+            if (!result.success) {
+                console.error(`Error: ${result.error}`);
+                process.exit(1);
+            }
+
+            if (result.formatted) {
+                console.log(result.formatted);
+            }
+
+            return result;
+        } catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+    };
+}

package/src/shortcuts/common/types.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * Shortcut type definitions
+ *
+ * Inspired by lark-cli's shortcuts/common/types.go
+ * Shortcuts are user-friendly commands with `+` prefix.
+ */
+
+/**
+ * @typedef {Object} Flag
+ * @property {string} name - Flag name (e.g., 'open-id', becomes --open-id)
+ * @property {string} type - Flag type: 'string', 'number', 'boolean', 'array'
+ * @property {boolean} [required] - Whether the flag is required
+ * @property {*} [default] - Default value if not provided
+ * @property {string} [description] - Help text for the flag
+ */
+
+/**
+ * @typedef {Object} Shortcut
+ * @property {string} service - Domain: 'production-orders' | 'material-orders' | 'qc-orders' | 'auth'
+ * @property {string} command - Command name with + prefix: '+list' | '+query'
+ * @property {string} description - Human-readable description
+ * @property {string} risk - 'read' | 'write' | 'high-risk-write'
+ * @property {string[]} scopes - Required OAuth scopes (for API calls)
+ * @property {Flag[]} flags - Declarative flag definitions
+ * @property {string[]} [tips] - Help tips shown to user
+ * @property {boolean} [hasFormat] - Whether to auto-inject --format flag
+ * @property {Function} [validate] - Pre-execution validation function (ctx, runtime) => error
+ * @property {Function} execute - Execution logic (ctx, runtime) => result
+ */
+
+export { };

package/src/shortcuts/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * All shortcuts — collected map for registration
+ */
+import { Shortcuts as ProductionOrdersShortcuts } from './production-orders/index.js';
+import { Shortcuts as MaterialOrdersShortcuts } from './material-orders/index.js';
+import { Shortcuts as QcOrdersShortcuts } from './qc-orders/index.js';
+
+/**
+ * Get all shortcuts as a domain -> Shortcut[] map
+ */
+export function getShortcutsMap() {
+    return {
+        'production-orders': ProductionOrdersShortcuts(),
+        'material-orders': MaterialOrdersShortcuts(),
+        'qc-orders': QcOrdersShortcuts(),
+    };
+}
+
+export { registerShortcuts } from './register.js';

package/src/shortcuts/material-orders/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Copyright (c) 2026 WFS
+ * SPDX-License-Identifier: MIT
+ *
+ * Material Orders shortcuts
+ */
+import { MaterialOrdersList } from './list.js';
+
+export function Shortcuts() {
+    return [MaterialOrdersList];
+}