gx-code-agent 0.0.0-stage → 0.1.0

package/src/store/backupStore.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { ensureDir, removeFile } from "./localStore.js";
+
+/**
+ * 创建备份根目录：`.gx/backup/<ISO timestamp>`。
+ *
+ * @param {string} dir
+ * @returns {string}
+ */
+export function createBackupRoot(dir) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return path.join(dir, ".gx", "backup", stamp);
+}
+
+/**
+ * 把文件安全地映射到备份目录内。
+ *
+ * @param {string} dir
+ * @param {string} file
+ * @returns {string}
+ */
+function backupRelativePath(dir, file) {
+  const relative = path.relative(dir, file);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return path.join("_external", path.basename(file));
+  }
+  return relative;
+}
+
+/**
+ * 初始化写入事务：写入前备份原文件，失败时可回滚。
+ */
+export class InitTransaction {
+  /**
+   * @param {string} dir 项目目录
+   * @param {string} backupRoot 备份根目录
+   */
+  constructor(dir, backupRoot) {
+    this.dir = dir;
+    this.backupRoot = backupRoot;
+    /** @type {{file: string, existed: boolean, backupPath: string | null}[]} */
+    this.entries = [];
+    this.seen = new Set();
+  }
+
+  /**
+   * 记录即将写入的文件，并在需要时备份。
+   *
+   * @param {string} file
+   * @returns {string | null} 备份路径
+   */
+  record(file) {
+    if (this.seen.has(file)) {
+      const existing = this.entries.find((entry) => entry.file === file);
+      return existing ? existing.backupPath : null;
+    }
+    this.seen.add(file);
+
+    const existed = fs.existsSync(file);
+    let backupPath = null;
+    if (existed) {
+      backupPath = path.join(this.backupRoot, backupRelativePath(this.dir, file));
+      ensureDir(path.dirname(backupPath));
+      fs.copyFileSync(file, backupPath);
+    }
+    this.entries.push({ file, existed, backupPath });
+    return backupPath;
+  }
+
+  /**
+   * 回滚所有已记录文件。
+   */
+  rollback() {
+    for (const entry of [...this.entries].reverse()) {
+      if (entry.existed && entry.backupPath) {
+        ensureDir(path.dirname(entry.file));
+        fs.copyFileSync(entry.backupPath, entry.file);
+      } else if (!entry.existed) {
+        removeFile(entry.file);
+      }
+    }
+  }
+}
+
+/**
+ * 只保留最近 N 次备份。
+ *
+ * @param {string} dir
+ * @param {number} keep
+ */
+export function pruneBackups(dir, keep = 5) {
+  const root = path.join(dir, ".gx", "backup");
+  if (!fs.existsSync(root)) {
+    return;
+  }
+  const entries = fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .reverse();
+  for (const name of entries.slice(keep)) {
+    fs.rmSync(path.join(root, name), { recursive: true, force: true });
+  }
+}

package/src/store/localStore.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 读取 JSON；文件不存在或为空时返回 fallback。
+ *
+ * @param {string} file
+ * @param {unknown} fallback
+ * @returns {unknown}
+ */
+export function readJson(file, fallback) {
+  if (!fs.existsSync(file)) {
+    return fallback;
+  }
+  const content = fs.readFileSync(file, "utf8").trim();
+  if (!content) {
+    return fallback;
+  }
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`无法解析 ${file}，请先确保它是合法 JSON。原因：${error.message}`);
+  }
+}
+
+/**
+ * 读取文本；不存在时返回空字符串。
+ *
+ * @param {string} file
+ * @returns {string}
+ */
+export function readText(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+}
+
+/**
+ * 写入文本。
+ *
+ * @param {string} file
+ * @param {string} content
+ */
+export function writeText(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, "utf8");
+}
+
+/**
+ * 写入 JSON。
+ *
+ * @param {string} file
+ * @param {unknown} data
+ */
+export function writeJson(file, data) {
+  writeText(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+/**
+ * 删除文件；不存在时忽略。
+ *
+ * @param {string} file
+ */
+export function removeFile(file) {
+  try {
+    fs.unlinkSync(file);
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+}
+
+/**
+ * 确保目录存在。
+ *
+ * @param {string} dir
+ */
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}

package/templates/platform-rules.md

@@ -0,0 +1,29 @@
+# GX 高代码平台：MCP 使用纪律
+
+你正在通过 `gx-code` MCP Server 访问 GX 高代码平台。请遵守：
+
+## 1. 结构变更只走 MCP
+- 加表、加字段、改关系、加索引、改查询视图：必须调用 MCP 工具。
+- 禁止直接编辑平台生成的 Entity / DTO / VO / QBean / Repository 等生成层文件。
+- 写工具默认 `dryRun=true`；先看影响面，再显式 `apply`。
+
+## 2. 行为代码写在扩展层
+- 业务逻辑写 `XxxServiceImpl`、`XxxHook`、自定义 Controller / DTO。
+- 扩展方法优先加 `@ExtMethod(entity, intent, triggers)`，便于平台对账与检索。
+- 修改扩展层后运行 `gx scan` 上报；提交前运行 `gx audit --strict` 检查缺注解、失效引用与 manifest 漂移。
+- 平台再生代码时不会覆盖扩展层文件。
+
+## 3. 技术栈约束
+- 持久层只使用 JPA + QueryDSL，禁止 MyBatis / MyBatis-Plus。
+- 禁止物理外键，关联使用逻辑关联 + QueryDSL Join。
+- ID 统一 `Long`，跨端序列化注意精度；基础字段 `isDeleted` / `createdDate` / `lastModifiedDate` 由基类维护。
+- 避免 `@OneToMany(mappedBy=...)` 隐式加载，优先显式投影 / fetch join，防 N+1。
+
+## 4. 回答与修改要求
+- 先读元数据与源文件，再给结论；不确定时先调用查询工具。
+- 修改前说明「结构变更」还是「行为变更」，并列出受影响文件。
+- 不要臆造字段、表名、接口；以 MCP 返回结果为准。
+
+## 5. 安全
+- 不要输出、记录或提交 API Token。
+- 生成层文件头带 checksum；发现不一致时先报告漂移，不要直接覆盖。