@leeoohoo/ui-apps-devkit 0.1.0 → 0.1.2

package/src/commands/install.js

@@ -4,52 +4,53 @@ import path from 'path';
 import { copyDir, ensureDir, isDirectory, rmForce, sanitizeDirComponent } from '../lib/fs.js';
 import { loadDevkitConfig } from '../lib/config.js';
 import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
-
+import { STATE_ROOT_DIRNAME } from '../lib/state-constants.js';
+
 function defaultStateDir(hostApp) {
   const app = typeof hostApp === 'string' && hostApp.trim() ? hostApp.trim() : 'chatos';
-  return path.join(os.homedir(), '.deepseek_cli', app);
-}
-
-function copyPluginDir(srcDir, destDir) {
-  ensureDir(path.dirname(destDir));
-  rmForce(destDir);
-  copyDir(srcDir, destDir, {
-    filter: (src) => {
-      const base = path.basename(src);
-      if (base === 'node_modules') return false;
-      if (base === '.git') return false;
-      if (base === '.DS_Store') return false;
-      if (base.endsWith('.map')) return false;
-      return true;
-    },
-  });
+  return path.join(os.homedir(), STATE_ROOT_DIRNAME, app);
 }
-
-export async function cmdInstall({ flags }) {
-  const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-  const { pluginId, name, version } = loadPluginManifest(pluginDir);
-
-  const hostApp = String(flags['host-app'] || flags.hostApp || 'chatos').trim() || 'chatos';
-  const stateDir = String(flags['state-dir'] || flags.stateDir || defaultStateDir(hostApp)).trim();
-  if (!stateDir) throw new Error('stateDir is required');
-
-  const pluginsRoot = path.join(stateDir, 'ui_apps', 'plugins');
-  ensureDir(pluginsRoot);
-
-  const dirName = sanitizeDirComponent(pluginId);
-  if (!dirName) throw new Error(`Invalid plugin id: ${pluginId}`);
-
-  const destDir = path.join(pluginsRoot, dirName);
-  const replaced = isDirectory(destDir);
-  copyPluginDir(pluginDir, destDir);
-
-  // eslint-disable-next-line no-console
-  console.log(
-    `Installed: ${pluginId} (${name}@${version})\n` +
-      `  -> ${destDir}\n` +
-      `  replaced: ${replaced}\n\n` +
-      `Open ChatOS -> 应用 -> 刷新（同 id 覆盖生效）。`
-  );
-}
-
+
+function copyPluginDir(srcDir, destDir) {
+  ensureDir(path.dirname(destDir));
+  rmForce(destDir);
+  copyDir(srcDir, destDir, {
+    filter: (src) => {
+      const base = path.basename(src);
+      if (base === 'node_modules') return false;
+      if (base === '.git') return false;
+      if (base === '.DS_Store') return false;
+      if (base.endsWith('.map')) return false;
+      return true;
+    },
+  });
+}
+
+export async function cmdInstall({ flags }) {
+  const { config } = loadDevkitConfig(process.cwd());
+  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+  const { pluginId, name, version } = loadPluginManifest(pluginDir);
+
+  const hostApp = String(flags['host-app'] || flags.hostApp || 'chatos').trim() || 'chatos';
+  const stateDir = String(flags['state-dir'] || flags.stateDir || defaultStateDir(hostApp)).trim();
+  if (!stateDir) throw new Error('stateDir is required');
+
+  const pluginsRoot = path.join(stateDir, 'ui_apps', 'plugins');
+  ensureDir(pluginsRoot);
+
+  const dirName = sanitizeDirComponent(pluginId);
+  if (!dirName) throw new Error(`Invalid plugin id: ${pluginId}`);
+
+  const destDir = path.join(pluginsRoot, dirName);
+  const replaced = isDirectory(destDir);
+  copyPluginDir(pluginDir, destDir);
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `Installed: ${pluginId} (${name}@${version})\n` +
+      `  -> ${destDir}\n` +
+      `  replaced: ${replaced}\n\n` +
+      `Open ChatOS -> 应用 -> 刷新（同 id 覆盖生效）。`
+  );
+}
+

package/src/commands/pack.js

@@ -1,72 +1,72 @@
-import os from 'os';
-import path from 'path';
-import { spawnSync } from 'child_process';
-
-import { copyDir, ensureDir, rmForce } from '../lib/fs.js';
-import { loadDevkitConfig } from '../lib/config.js';
-import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
-
-function hasCmd(cmd) {
-  const res = spawnSync('sh', ['-lc', `command -v ${cmd} >/dev/null 2>&1`], { stdio: 'ignore' });
-  return res.status === 0;
-}
-
-function packWithZip({ cwd, srcDir, outFile }) {
-  // zip -r out.zip .  (from within srcDir)
-  const res = spawnSync('zip', ['-r', outFile, '.'], { cwd: srcDir, stdio: 'inherit' });
-  if (res.status !== 0) throw new Error('zip failed');
-}
-
-function packWithPowershell({ srcDir, outFile }) {
-  const script = `Compress-Archive -Path "${srcDir}\\*" -DestinationPath "${outFile}" -Force`;
-  const res = spawnSync('powershell', ['-NoProfile', '-Command', script], { stdio: 'inherit' });
-  if (res.status !== 0) throw new Error('powershell Compress-Archive failed');
-}
-
-export async function cmdPack({ flags }) {
-  const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-  const { pluginId, version } = loadPluginManifest(pluginDir);
-
-  const outArg = String(flags.out || '').trim();
-  const outDir = outArg ? path.dirname(path.resolve(process.cwd(), outArg)) : path.join(process.cwd(), 'dist');
-  ensureDir(outDir);
-
-  const outFile = outArg
-    ? path.resolve(process.cwd(), outArg)
-    : path.join(outDir, `${pluginId.replace(/[^a-zA-Z0-9._-]+/g, '-')}-${version || '0.0.0'}.zip`);
-
-  rmForce(outFile);
-
-  const stagingBase = path.join(os.tmpdir(), `chatos-uiapp-pack-${Date.now()}-${Math.random().toString(16).slice(2)}`);
-  ensureDir(stagingBase);
-  try {
-    // mimic ChatOS importer: exclude node_modules/.git/*.map/.DS_Store
-    copyDir(pluginDir, stagingBase, {
-      filter: (src) => {
-        const base = path.basename(src);
-        if (base === 'node_modules') return false;
-        if (base === '.git') return false;
-        if (base === '.DS_Store') return false;
-        if (base.endsWith('.map')) return false;
-        return true;
-      },
-    });
-
-  const platform = process.platform;
-  if (hasCmd('zip')) {
-      packWithZip({ cwd: process.cwd(), srcDir: stagingBase, outFile });
-  } else if (platform === 'win32') {
-      packWithPowershell({ srcDir: stagingBase, outFile });
-  } else {
-    throw new Error('zip command not found (install "zip" or run on Windows with powershell)');
-  }
-
-  // eslint-disable-next-line no-console
-  console.log(`Packed: ${outFile}
-
-ChatOS -> 应用 -> 导入应用包 -> 选择该 zip`);
-  } finally {
-    rmForce(stagingBase);
-  }
-}
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+import { copyDir, ensureDir, rmForce } from '../lib/fs.js';
+import { loadDevkitConfig } from '../lib/config.js';
+import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
+
+function hasCmd(cmd) {
+  const res = spawnSync('sh', ['-lc', `command -v ${cmd} >/dev/null 2>&1`], { stdio: 'ignore' });
+  return res.status === 0;
+}
+
+function packWithZip({ cwd, srcDir, outFile }) {
+  // zip -r out.zip .  (from within srcDir)
+  const res = spawnSync('zip', ['-r', outFile, '.'], { cwd: srcDir, stdio: 'inherit' });
+  if (res.status !== 0) throw new Error('zip failed');
+}
+
+function packWithPowershell({ srcDir, outFile }) {
+  const script = `Compress-Archive -Path "${srcDir}\\*" -DestinationPath "${outFile}" -Force`;
+  const res = spawnSync('powershell', ['-NoProfile', '-Command', script], { stdio: 'inherit' });
+  if (res.status !== 0) throw new Error('powershell Compress-Archive failed');
+}
+
+export async function cmdPack({ flags }) {
+  const { config } = loadDevkitConfig(process.cwd());
+  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+  const { pluginId, version } = loadPluginManifest(pluginDir);
+
+  const outArg = String(flags.out || '').trim();
+  const outDir = outArg ? path.dirname(path.resolve(process.cwd(), outArg)) : path.join(process.cwd(), 'dist');
+  ensureDir(outDir);
+
+  const outFile = outArg
+    ? path.resolve(process.cwd(), outArg)
+    : path.join(outDir, `${pluginId.replace(/[^a-zA-Z0-9._-]+/g, '-')}-${version || '0.0.0'}.zip`);
+
+  rmForce(outFile);
+
+  const stagingBase = path.join(os.tmpdir(), `chatos-uiapp-pack-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  ensureDir(stagingBase);
+  try {
+    // mimic ChatOS importer: exclude node_modules/.git/*.map/.DS_Store
+    copyDir(pluginDir, stagingBase, {
+      filter: (src) => {
+        const base = path.basename(src);
+        if (base === 'node_modules') return false;
+        if (base === '.git') return false;
+        if (base === '.DS_Store') return false;
+        if (base.endsWith('.map')) return false;
+        return true;
+      },
+    });
+
+  const platform = process.platform;
+  if (hasCmd('zip')) {
+      packWithZip({ cwd: process.cwd(), srcDir: stagingBase, outFile });
+  } else if (platform === 'win32') {
+      packWithPowershell({ srcDir: stagingBase, outFile });
+  } else {
+    throw new Error('zip command not found (install "zip" or run on Windows with powershell)');
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`Packed: ${outFile}
+
+ChatOS -> 应用 -> 导入应用包 -> 选择该 zip`);
+  } finally {
+    rmForce(stagingBase);
+  }
+}

package/src/commands/validate.js

@@ -1,15 +1,15 @@
-import fs from 'fs';
-import path from 'path';
-
-import { isFile } from '../lib/fs.js';
-import { loadDevkitConfig } from '../lib/config.js';
-import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
-import { resolveInsideDir } from '../lib/path-boundary.js';
-
-function assert(cond, message) {
-  if (!cond) throw new Error(message);
-}
-
+import fs from 'fs';
+import path from 'path';
+
+import { isFile } from '../lib/fs.js';
+import { loadDevkitConfig } from '../lib/config.js';
+import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
+import { resolveInsideDir } from '../lib/path-boundary.js';
+
+function assert(cond, message) {
+  if (!cond) throw new Error(message);
+}
+
 function statSizeSafe(filePath) {
   try {
     return fs.statSync(filePath).size;
@@ -18,84 +18,142 @@ function statSizeSafe(filePath) {
   }
 }
 
+function collectSymlinks(rootDir) {
+  const root = typeof rootDir === 'string' ? rootDir.trim() : '';
+  if (!root) return [];
+  const out = [];
+  const walk = (dir) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.forEach((entry) => {
+      if (!entry || !entry.name) return;
+      const fullPath = path.join(dir, entry.name);
+      let stat;
+      try {
+        stat = fs.lstatSync(fullPath);
+      } catch {
+        return;
+      }
+      if (stat.isSymbolicLink()) {
+        out.push(fullPath);
+        return;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      }
+    });
+  };
+  walk(root);
+  return out;
+}
+
 export async function cmdValidate({ flags }) {
   const { config } = loadDevkitConfig(process.cwd());
   const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
 
   const { manifestPath, manifest } = loadPluginManifest(pluginDir);
+  const warnings = [];
+  const warn = (message) => warnings.push(message);
+
+  const symlinks = collectSymlinks(pluginDir);
+  if (symlinks.length > 0) {
+    const rel = symlinks.map((entry) => path.relative(pluginDir, entry) || entry);
+    warn(`Symlink detected inside plugin dir (may bypass path boundaries): ${rel.join(', ')}`);
+  }
 
   const manifestSize = statSizeSafe(manifestPath);
   assert(manifestSize <= 256 * 1024, `plugin.json too large (>256KiB): ${manifestSize} bytes`);
-
-  assert(Number(manifest?.manifestVersion || 1) === 1, 'manifestVersion must be 1');
-  assert(typeof manifest?.id === 'string' && manifest.id.trim(), 'plugin.id is required');
-  assert(typeof manifest?.name === 'string' && manifest.name.trim(), 'plugin.name is required');
-
-  if (manifest?.backend?.entry) {
-    const backendAbs = resolveInsideDir(pluginDir, manifest.backend.entry);
-    assert(isFile(backendAbs), `backend.entry must be a file: ${manifest.backend.entry}`);
+
+  assert(Number(manifest?.manifestVersion || 1) === 1, 'manifestVersion must be 1');
+  assert(typeof manifest?.id === 'string' && manifest.id.trim(), 'plugin.id is required');
+  assert(typeof manifest?.name === 'string' && manifest.name.trim(), 'plugin.name is required');
+
+  if (manifest?.backend?.entry) {
+    const backendAbs = resolveInsideDir(pluginDir, manifest.backend.entry);
+    assert(isFile(backendAbs), `backend.entry must be a file: ${manifest.backend.entry}`);
+  }
+
+  const apps = Array.isArray(manifest?.apps) ? manifest.apps : [];
+  assert(apps.length > 0, 'plugin.apps[] is required (>=1)');
+  const ids = new Set();
+  for (const app of apps) {
+    const appId = typeof app?.id === 'string' ? app.id.trim() : '';
+    assert(appId, 'apps[i].id is required');
+    assert(!ids.has(appId), `duplicate app.id: ${appId}`);
+    ids.add(appId);
+
+    assert(typeof app?.name === 'string' && app.name.trim(), `apps[${appId}].name is required`);
+    assert(app?.entry?.type === 'module', `apps[${appId}].entry.type must be "module"`);
+    const entryPath = typeof app?.entry?.path === 'string' ? app.entry.path.trim() : '';
+    assert(entryPath, `apps[${appId}].entry.path is required`);
+    const entryAbs = resolveInsideDir(pluginDir, entryPath);
+    assert(isFile(entryAbs), `apps[${appId}].entry.path must be a file: ${entryPath}`);
+
+    const compactType = app?.entry?.compact?.type;
+    if (compactType && compactType !== 'module') {
+      assert(false, `apps[${appId}].entry.compact.type must be "module"`);
+    }
+    const compactPath = typeof app?.entry?.compact?.path === 'string' ? app.entry.compact.path.trim() : '';
+    if (compactPath) {
+      const compactAbs = resolveInsideDir(pluginDir, compactPath);
+      assert(isFile(compactAbs), `apps[${appId}].entry.compact.path must be a file: ${compactPath}`);
+    }
+
+    // Basic ai path boundary checks (full schema is defined in docs; this validates the security boundary).
+    const ai = app?.ai;
+    const aiObj =
+      typeof ai === 'string'
+        ? { config: ai }
+        : ai && typeof ai === 'object'
+          ? ai
+          : null;
+
+    if (aiObj?.config) {
+      const abs = resolveInsideDir(pluginDir, aiObj.config);
+      assert(isFile(abs), `apps[${appId}].ai.config must be a file: ${aiObj.config}`);
+      const size = statSizeSafe(abs);
+      assert(size <= 128 * 1024, `ai.config too large (>128KiB): ${aiObj.config}`);
+    }
+
+    if (aiObj?.mcp?.entry) {
+      const abs = resolveInsideDir(pluginDir, aiObj.mcp.entry);
+      assert(isFile(abs), `apps[${appId}].ai.mcp.entry must be a file: ${aiObj.mcp.entry}`);
+    }
+
+    const mcpPrompt = aiObj?.mcpPrompt;
+    const collectPromptPaths = () => {
+      if (!mcpPrompt) return [];
+      if (typeof mcpPrompt === 'string') return [mcpPrompt];
+      if (typeof mcpPrompt !== 'object') return [];
+      const zh = mcpPrompt.zh;
+      const en = mcpPrompt.en;
+      const out = [];
+      const pushSource = (src) => {
+        if (!src) return;
+        if (typeof src === 'string') out.push(src);
+        else if (typeof src === 'object' && typeof src.path === 'string') out.push(src.path);
+      };
+      pushSource(zh);
+      pushSource(en);
+      return out;
+    };
+    for (const rel of collectPromptPaths()) {
+      const abs = resolveInsideDir(pluginDir, rel);
+      assert(isFile(abs), `apps[${appId}].ai.mcpPrompt path must be a file: ${rel}`);
+      const size = statSizeSafe(abs);
+      assert(size <= 128 * 1024, `mcpPrompt too large (>128KiB): ${rel}`);
+    }
   }
 
-  const apps = Array.isArray(manifest?.apps) ? manifest.apps : [];
-  assert(apps.length > 0, 'plugin.apps[] is required (>=1)');
-  const ids = new Set();
-  for (const app of apps) {
-    const appId = typeof app?.id === 'string' ? app.id.trim() : '';
-    assert(appId, 'apps[i].id is required');
-    assert(!ids.has(appId), `duplicate app.id: ${appId}`);
-    ids.add(appId);
-
-    assert(typeof app?.name === 'string' && app.name.trim(), `apps[${appId}].name is required`);
-    assert(app?.entry?.type === 'module', `apps[${appId}].entry.type must be "module"`);
-    const entryPath = typeof app?.entry?.path === 'string' ? app.entry.path.trim() : '';
-    assert(entryPath, `apps[${appId}].entry.path is required`);
-    const entryAbs = resolveInsideDir(pluginDir, entryPath);
-    assert(isFile(entryAbs), `apps[${appId}].entry.path must be a file: ${entryPath}`);
-
-    // Basic ai path boundary checks (full schema is defined in docs; this validates the security boundary).
-    const ai = app?.ai;
-    const aiObj =
-      typeof ai === 'string'
-        ? { config: ai }
-        : ai && typeof ai === 'object'
-          ? ai
-          : null;
-
-    if (aiObj?.config) {
-      const abs = resolveInsideDir(pluginDir, aiObj.config);
-      assert(isFile(abs), `apps[${appId}].ai.config must be a file: ${aiObj.config}`);
-      const size = statSizeSafe(abs);
-      assert(size <= 128 * 1024, `ai.config too large (>128KiB): ${aiObj.config}`);
-    }
-
-    if (aiObj?.mcp?.entry) {
-      const abs = resolveInsideDir(pluginDir, aiObj.mcp.entry);
-      assert(isFile(abs), `apps[${appId}].ai.mcp.entry must be a file: ${aiObj.mcp.entry}`);
-    }
-
-    const mcpPrompt = aiObj?.mcpPrompt;
-    const collectPromptPaths = () => {
-      if (!mcpPrompt) return [];
-      if (typeof mcpPrompt === 'string') return [mcpPrompt];
-      if (typeof mcpPrompt !== 'object') return [];
-      const zh = mcpPrompt.zh;
-      const en = mcpPrompt.en;
-      const out = [];
-      const pushSource = (src) => {
-        if (!src) return;
-        if (typeof src === 'string') out.push(src);
-        else if (typeof src === 'object' && typeof src.path === 'string') out.push(src.path);
-      };
-      pushSource(zh);
-      pushSource(en);
-      return out;
-    };
-    for (const rel of collectPromptPaths()) {
-      const abs = resolveInsideDir(pluginDir, rel);
-      assert(isFile(abs), `apps[${appId}].ai.mcpPrompt path must be a file: ${rel}`);
-      const size = statSizeSafe(abs);
-      assert(size <= 128 * 1024, `mcpPrompt too large (>128KiB): ${rel}`);
-    }
+  if (warnings.length > 0) {
+    warnings.forEach((message) => {
+      // eslint-disable-next-line no-console
+      console.warn(`WARN: ${message}`);
+    });
   }
 
   // eslint-disable-next-line no-console

package/src/lib/args.js

@@ -1,49 +1,49 @@
-export function parseArgs(argv) {
-  const raw = Array.isArray(argv) ? argv.slice(2) : [];
-  const flags = {};
-  const positionals = [];
-
-  for (let i = 0; i < raw.length; i += 1) {
-    const token = raw[i];
-    if (!token) continue;
-
-    if (token === '--') {
-      positionals.push(...raw.slice(i + 1));
-      break;
-    }
-
-    if (token.startsWith('--')) {
-      const eq = token.indexOf('=');
-      const key = (eq >= 0 ? token.slice(2, eq) : token.slice(2)).trim();
-      const value = eq >= 0 ? token.slice(eq + 1) : raw[i + 1];
-      if (!key) continue;
-
-      if (eq < 0 && value && !value.startsWith('-')) {
-        flags[key] = value;
-        i += 1;
-      } else if (eq >= 0) {
-        flags[key] = value;
-      } else {
-        flags[key] = true;
-      }
-      continue;
-    }
-
-    if (token.startsWith('-') && token.length > 1) {
-      const key = token.slice(1).trim();
-      const value = raw[i + 1];
-      if (value && !value.startsWith('-')) {
-        flags[key] = value;
-        i += 1;
-      } else {
-        flags[key] = true;
-      }
-      continue;
-    }
-
-    positionals.push(token);
-  }
-
-  return { positionals, flags };
-}
-
+export function parseArgs(argv) {
+  const raw = Array.isArray(argv) ? argv.slice(2) : [];
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < raw.length; i += 1) {
+    const token = raw[i];
+    if (!token) continue;
+
+    if (token === '--') {
+      positionals.push(...raw.slice(i + 1));
+      break;
+    }
+
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      const key = (eq >= 0 ? token.slice(2, eq) : token.slice(2)).trim();
+      const value = eq >= 0 ? token.slice(eq + 1) : raw[i + 1];
+      if (!key) continue;
+
+      if (eq < 0 && value && !value.startsWith('-')) {
+        flags[key] = value;
+        i += 1;
+      } else if (eq >= 0) {
+        flags[key] = value;
+      } else {
+        flags[key] = true;
+      }
+      continue;
+    }
+
+    if (token.startsWith('-') && token.length > 1) {
+      const key = token.slice(1).trim();
+      const value = raw[i + 1];
+      if (value && !value.startsWith('-')) {
+        flags[key] = value;
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  return { positionals, flags };
+}
+

package/src/lib/config.js

@@ -1,29 +1,29 @@
-import fs from 'fs';
-import path from 'path';
-
-import { isFile, readJson } from './fs.js';
-
-export function loadDevkitConfig(cwd) {
-  const root = typeof cwd === 'string' ? cwd : process.cwd();
-  const cfgPath = path.join(root, 'chatos.config.json');
-  if (!isFile(cfgPath)) return { path: cfgPath, config: null };
-  try {
-    const cfg = readJson(cfgPath);
-    return { path: cfgPath, config: cfg };
-  } catch {
-    return { path: cfgPath, config: null };
-  }
-}
-
-export function readOptionalJson(filePath) {
-  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
-  if (!normalized) return null;
-  if (!fs.existsSync(normalized)) return null;
-  try {
-    const raw = fs.readFileSync(normalized, 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
+import fs from 'fs';
+import path from 'path';
+
+import { isFile, readJson } from './fs.js';
+
+export function loadDevkitConfig(cwd) {
+  const root = typeof cwd === 'string' ? cwd : process.cwd();
+  const cfgPath = path.join(root, 'chatos.config.json');
+  if (!isFile(cfgPath)) return { path: cfgPath, config: null };
+  try {
+    const cfg = readJson(cfgPath);
+    return { path: cfgPath, config: cfg };
+  } catch {
+    return { path: cfgPath, config: null };
+  }
+}
+
+export function readOptionalJson(filePath) {
+  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
+  if (!normalized) return null;
+  if (!fs.existsSync(normalized)) return null;
+  try {
+    const raw = fs.readFileSync(normalized, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+