@starpak/config 0.0.0-stage → 1.0.6

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-present Spak Team
+Copyright (c) 2019-present Shigma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/errors.d.ts

@@ -0,0 +1,13 @@
+import { SpakError, type FormatKind } from '@starpak/error';
+export interface ConfigErrorOptions {
+    cause?: unknown;
+    where?: string;
+    context?: Record<string, unknown>;
+}
+/** 构造一个带错误码的配置错误，message 保留本次发生的具体细节。 */
+export declare function spakError(code: string, message: string, options?: ConfigErrorOptions): SpakError;
+/** 任意异常归一成 `SpakError`，保留原始 cause。 */
+export declare function normalizeError(error: unknown, code?: string, message?: string): SpakError;
+/** 渲染成文本 / JSON / HTML / Markdown；调用方决定往哪儿写。 */
+export declare function renderError(error: unknown, kind?: FormatKind): string;
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAMA,OAAO,EAAS,SAAS,EAAuB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEvF,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,yCAAyC;AACzC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,SAAS,CAEpG;AAED,sCAAsC;AACtC,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,MAA6B,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAI/G;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,UAAmB,GAAG,MAAM,CAE7E"}

package/lib/errors.js

@@ -0,0 +1,27 @@
+"use strict";
+// ===== config — @starpak/error bridge =====
+//
+// 配置文件读写失败一律带稳定错误码（SPAK-xxxx）。抛出用 `spakError()`，
+// 输出用 `renderError()`（内部只走 `format()`），这样 CLI / 日志 / SpakOS
+// 面板拿到的是同一份 `ErrorInfo`。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spakError = spakError;
+exports.normalizeError = normalizeError;
+exports.renderError = renderError;
+const error_1 = require("@starpak/error");
+/** 构造一个带错误码的配置错误，message 保留本次发生的具体细节。 */
+function spakError(code, message, options = {}) {
+    return new error_1.SpakError(code, { message, ...options });
+}
+/** 任意异常归一成 `SpakError`，保留原始 cause。 */
+function normalizeError(error, code = error_1.CODES.CONFIG_INVALID, message) {
+    if ((0, error_1.isSpakError)(error))
+        return error;
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return new error_1.SpakError(code, { message: message ?? cause.message, cause });
+}
+/** 渲染成文本 / JSON / HTML / Markdown；调用方决定往哪儿写。 */
+function renderError(error, kind = 'text') {
+    return (0, error_1.format)(normalizeError(error).toInfo(), kind);
+}
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA,6CAA6C;AAC7C,EAAE;AACF,iDAAiD;AACjD,4DAA4D;AAC5D,yBAAyB;;AAWzB,8BAEC;AAGD,wCAIC;AAGD,kCAEC;AAvBD,0CAAuF;AAQvF,yCAAyC;AACzC,SAAgB,SAAS,CAAC,IAAY,EAAE,OAAe,EAAE,UAA8B,EAAE;IACvF,OAAO,IAAI,iBAAS,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;AACrD,CAAC;AAED,sCAAsC;AACtC,SAAgB,cAAc,CAAC,KAAc,EAAE,OAAe,aAAK,CAAC,cAAc,EAAE,OAAgB;IAClG,IAAI,IAAA,mBAAW,EAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACpC,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IACvE,OAAO,IAAI,iBAAS,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;AAC1E,CAAC;AAED,gDAAgD;AAChD,SAAgB,WAAW,CAAC,KAAc,EAAE,OAAmB,MAAM;IACnE,OAAO,IAAA,cAAM,EAAC,cAAc,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,CAAA;AACrD,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+export interface SpakConfig {
+    plugins: Record<string, any>;
+    cpc?: {
+        enabled?: boolean;
+        sandbox?: {
+            enabled?: boolean;
+        };
+        processIsolation?: {
+            enabled?: boolean;
+        };
+        ssetps?: {
+            enabled?: boolean;
+            /** Memory limit in MB for SSetPS RSS monitoring; 80% of this trips the warning + circuit breaker. */
+            memoryLimitMB?: number;
+        };
+    };
+}
+export declare function loadConfig(): SpakConfig;
+export declare function saveConfig(config: SpakConfig): void;
+export declare function getConfig(key: string): any;
+export declare function setConfig(key: string, value: any): SpakConfig;
+export { renderError, spakError } from './errors';
+declare const _default: {
+    loadConfig: typeof loadConfig;
+    saveConfig: typeof saveConfig;
+    getConfig: typeof getConfig;
+    setConfig: typeof setConfig;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAA;QAC/B,gBAAgB,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAA;QACxC,MAAM,CAAC,EAAE;YACP,OAAO,CAAC,EAAE,OAAO,CAAA;YACjB,qGAAqG;YACrG,aAAa,CAAC,EAAE,MAAM,CAAA;SACvB,CAAA;KACF,CAAA;CACF;AAwBD,wBAAgB,UAAU,IAAI,UAAU,CAgBvC;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAwBnD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAS1C;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,UAAU,CAW7D;AAED,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;;;;;;;AACjD,wBAA+D"}

package/lib/index.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spakError = exports.renderError = void 0;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.getConfig = getConfig;
+exports.setConfig = setConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const util_1 = require("@starpak/util");
+const error_1 = require("@starpak/error");
+const errors_1 = require("./errors");
+// 数据目录 = 项目源码根下的 data/（尊重 SPAK_DATA_DIR 覆盖，不写 ~/.spak）
+const CONFIG_DIR = (0, util_1.projectDataDir)();
+const CONFIG_FILE = (0, path_1.resolve)(CONFIG_DIR, 'config.json');
+const defaultConfig = {
+    plugins: {},
+};
+/** 调试时把配置错误按统一格式打到 stderr（只走 format，不裸写 message）。 */
+function diagnose(error) {
+    if (!process.env.SPAK_DEBUG)
+        return;
+    process.stderr.write((0, errors_1.renderError)(error) + '\n');
+}
+function ensureConfigDir() {
+    if ((0, fs_1.existsSync)(CONFIG_DIR))
+        return;
+    try {
+        (0, fs_1.mkdirSync)(CONFIG_DIR, { recursive: true });
+    }
+    catch (error) {
+        throw (0, errors_1.spakError)(error_1.CODES.OUTPUT_NOT_WRITABLE, `无法创建配置目录：${CONFIG_DIR}`, {
+            cause: error,
+            where: CONFIG_DIR,
+        });
+    }
+}
+function loadConfig() {
+    ensureConfigDir();
+    if (!(0, fs_1.existsSync)(CONFIG_FILE)) {
+        saveConfig(defaultConfig);
+        return { ...defaultConfig };
+    }
+    try {
+        const data = (0, fs_1.readFileSync)(CONFIG_FILE, 'utf-8');
+        return { ...defaultConfig, ...JSON.parse(data) };
+    }
+    catch (error) {
+        diagnose((0, errors_1.spakError)(error_1.CODES.CONFIG_INVALID, `配置读取失败，已回退默认值：${CONFIG_FILE}`, {
+            cause: error,
+            where: CONFIG_FILE,
+        }));
+        return { ...defaultConfig };
+    }
+}
+function saveConfig(config) {
+    ensureConfigDir();
+    // Atomic write: write to a temp file first, then rename into place.
+    // This prevents half-written JSON when the process crashes mid-write, and
+    // reduces the race window between two concurrent setConfig() calls.
+    const tmpFile = CONFIG_FILE + '.tmp.' + process.pid.toString(36);
+    try {
+        (0, fs_1.writeFileSync)(tmpFile, JSON.stringify(config, null, 2), 'utf-8');
+        // rename() is atomic on POSIX filesystems; on Windows we fallback to
+        // replace via copy+unlink if rename fails.
+        try {
+            (0, fs_1.renameSync)(tmpFile, CONFIG_FILE);
+        }
+        catch (error) {
+            diagnose((0, errors_1.spakError)(error_1.CODES.FS_RENAME_UNSUPPORTED, `rename 失败，改用 copy+unlink：${tmpFile}`, { cause: error }));
+            (0, fs_1.copyFileSync)(tmpFile, CONFIG_FILE);
+            (0, fs_1.unlinkSync)(tmpFile);
+        }
+    }
+    catch (error) {
+        try {
+            (0, fs_1.unlinkSync)(tmpFile);
+        }
+        catch { /* ignore */ }
+        throw (0, errors_1.spakError)(error_1.CODES.OUTPUT_NOT_WRITABLE, `配置写入失败：${CONFIG_FILE}`, {
+            cause: error,
+            where: CONFIG_FILE,
+        });
+    }
+}
+function getConfig(key) {
+    const config = loadConfig();
+    const parts = key.split('.');
+    let value = config;
+    for (const part of parts) {
+        if (value === undefined || value === null)
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+function setConfig(key, value) {
+    const config = loadConfig();
+    const parts = key.split('.');
+    let obj = config;
+    for (let i = 0; i < parts.length - 1; i++) {
+        if (!obj[parts[i]])
+            obj[parts[i]] = {};
+        obj = obj[parts[i]];
+    }
+    obj[parts[parts.length - 1]] = value;
+    saveConfig(config);
+    return config;
+}
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "renderError", { enumerable: true, get: function () { return errors_2.renderError; } });
+Object.defineProperty(exports, "spakError", { enumerable: true, get: function () { return errors_2.spakError; } });
+exports.default = { loadConfig, saveConfig, getConfig, setConfig };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@starpak/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Spak Config - Central configuration manager",
+  "version": "1.0.6",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "author": "Spak Team",
+  "license": "MIT",
+  "dependencies": {
+    "@starpak/util": "^1.0.5",
+    "@starpak/error": "^0.1.4"
+  }
 }

package/src/errors.ts

@@ -0,0 +1,30 @@
+// ===== config — @starpak/error bridge =====
+//
+// 配置文件读写失败一律带稳定错误码（SPAK-xxxx）。抛出用 `spakError()`，
+// 输出用 `renderError()`（内部只走 `format()`），这样 CLI / 日志 / SpakOS
+// 面板拿到的是同一份 `ErrorInfo`。
+
+import { CODES, SpakError, format, isSpakError, type FormatKind } from '@starpak/error'
+
+export interface ConfigErrorOptions {
+  cause?: unknown
+  where?: string
+  context?: Record<string, unknown>
+}
+
+/** 构造一个带错误码的配置错误，message 保留本次发生的具体细节。 */
+export function spakError(code: string, message: string, options: ConfigErrorOptions = {}): SpakError {
+  return new SpakError(code, { message, ...options })
+}
+
+/** 任意异常归一成 `SpakError`，保留原始 cause。 */
+export function normalizeError(error: unknown, code: string = CODES.CONFIG_INVALID, message?: string): SpakError {
+  if (isSpakError(error)) return error
+  const cause = error instanceof Error ? error : new Error(String(error))
+  return new SpakError(code, { message: message ?? cause.message, cause })
+}
+
+/** 渲染成文本 / JSON / HTML / Markdown；调用方决定往哪儿写。 */
+export function renderError(error: unknown, kind: FormatKind = 'text'): string {
+  return format(normalizeError(error).toInfo(), kind)
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, copyFileSync, unlinkSync } from 'fs'
+import { resolve } from 'path'
+import { projectDataDir } from '@starpak/util'
+import { CODES } from '@starpak/error'
+import { renderError, spakError } from './errors'
+
+// 数据目录 = 项目源码根下的 data/（尊重 SPAK_DATA_DIR 覆盖，不写 ~/.spak）
+const CONFIG_DIR = projectDataDir()
+const CONFIG_FILE = resolve(CONFIG_DIR, 'config.json')
+
+export interface SpakConfig {
+  plugins: Record<string, any>
+  cpc?: {
+    enabled?: boolean
+    sandbox?: { enabled?: boolean }
+    processIsolation?: { enabled?: boolean }
+    ssetps?: {
+      enabled?: boolean
+      /** Memory limit in MB for SSetPS RSS monitoring; 80% of this trips the warning + circuit breaker. */
+      memoryLimitMB?: number
+    }
+  }
+}
+
+const defaultConfig: SpakConfig = {
+  plugins: {},
+}
+
+/** 调试时把配置错误按统一格式打到 stderr（只走 format，不裸写 message）。 */
+function diagnose(error: unknown) {
+  if (!process.env.SPAK_DEBUG) return
+  process.stderr.write(renderError(error) + '\n')
+}
+
+function ensureConfigDir() {
+  if (existsSync(CONFIG_DIR)) return
+  try {
+    mkdirSync(CONFIG_DIR, { recursive: true })
+  } catch (error) {
+    throw spakError(CODES.OUTPUT_NOT_WRITABLE, `无法创建配置目录：${CONFIG_DIR}`, {
+      cause: error,
+      where: CONFIG_DIR,
+    })
+  }
+}
+
+export function loadConfig(): SpakConfig {
+  ensureConfigDir()
+  if (!existsSync(CONFIG_FILE)) {
+    saveConfig(defaultConfig)
+    return { ...defaultConfig }
+  }
+  try {
+    const data = readFileSync(CONFIG_FILE, 'utf-8')
+    return { ...defaultConfig, ...JSON.parse(data) }
+  } catch (error) {
+    diagnose(spakError(CODES.CONFIG_INVALID, `配置读取失败，已回退默认值：${CONFIG_FILE}`, {
+      cause: error,
+      where: CONFIG_FILE,
+    }))
+    return { ...defaultConfig }
+  }
+}
+
+export function saveConfig(config: SpakConfig): void {
+  ensureConfigDir()
+  // Atomic write: write to a temp file first, then rename into place.
+  // This prevents half-written JSON when the process crashes mid-write, and
+  // reduces the race window between two concurrent setConfig() calls.
+  const tmpFile = CONFIG_FILE + '.tmp.' + process.pid.toString(36)
+  try {
+    writeFileSync(tmpFile, JSON.stringify(config, null, 2), 'utf-8')
+    // rename() is atomic on POSIX filesystems; on Windows we fallback to
+    // replace via copy+unlink if rename fails.
+    try {
+      renameSync(tmpFile, CONFIG_FILE)
+    } catch (error) {
+      diagnose(spakError(CODES.FS_RENAME_UNSUPPORTED, `rename 失败，改用 copy+unlink：${tmpFile}`, { cause: error }))
+      copyFileSync(tmpFile, CONFIG_FILE)
+      unlinkSync(tmpFile)
+    }
+  } catch (error) {
+    try { unlinkSync(tmpFile) } catch { /* ignore */ }
+    throw spakError(CODES.OUTPUT_NOT_WRITABLE, `配置写入失败：${CONFIG_FILE}`, {
+      cause: error,
+      where: CONFIG_FILE,
+    })
+  }
+}
+
+export function getConfig(key: string): any {
+  const config = loadConfig()
+  const parts = key.split('.')
+  let value: any = config
+  for (const part of parts) {
+    if (value === undefined || value === null) return undefined
+    value = value[part]
+  }
+  return value
+}
+
+export function setConfig(key: string, value: any): SpakConfig {
+  const config = loadConfig()
+  const parts = key.split('.')
+  let obj: any = config
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!obj[parts[i]]) obj[parts[i]] = {}
+    obj = obj[parts[i]]
+  }
+  obj[parts[parts.length - 1]] = value
+  saveConfig(config)
+  return config
+}
+
+export { renderError, spakError } from './errors'
+export default { loadConfig, saveConfig, getConfig, setConfig }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.