@ats-cx/cx-core 0.1.0

package/dist/apm/portal.js

@@ -0,0 +1,89 @@
+import { ApmRequestError } from "./errors.js";
+export async function resolveUserId(config, params, deps = {}) {
+    const url = `${config.baseUrl}/api/portal/get-user-id?email=${encodeURIComponent(params.value)}&host=${encodeURIComponent(params.host)}`;
+    const { text } = await requestPortal(config, url, deps);
+    const parsed = parseJson(text);
+    if (!isRecord(parsed)) {
+        throw new ApmRequestError("invalid_response", { message: "APM portal 返回了非 JSON 响应" });
+    }
+    if (parsed.success === false) {
+        throw new ApmRequestError("rejected", {
+            message: "无此邮箱/手机，或 portal 接口不可用",
+        });
+    }
+    if (parsed.success !== true || typeof parsed.userId !== "string") {
+        throw new ApmRequestError("invalid_response", { message: "APM portal 响应缺少有效的 userId" });
+    }
+    return parsed.userId;
+}
+export async function fetchLiveProject(config, params, deps = {}) {
+    const url = `${config.baseUrl}/api/portal/get-project-data?projectId=${encodeURIComponent(params.projectId)}&host=${encodeURIComponent(params.host)}`;
+    const { response, text } = await requestPortal(config, url, deps);
+    if (!isJsonContentType(response.headers.get("content-type"))) {
+        throw invalidProjectResponse();
+    }
+    const parsed = parseJson(text);
+    if (!isRecord(parsed)) {
+        throw invalidProjectResponse();
+    }
+    const project = isRecord(parsed.project) ? parsed.project : undefined;
+    return {
+        text,
+        parsed,
+        updatedDate: project?.updatedDate ?? null,
+        hasProject: "project" in parsed,
+    };
+}
+async function requestPortal(config, url, deps) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    try {
+        const response = await fetchImpl(url, {
+            method: "GET",
+            signal: AbortSignal.timeout(config.timeoutMs.portal),
+        });
+        if (!response.ok) {
+            throw new ApmRequestError("http", {
+                status: response.status,
+                message: `APM portal 请求失败（HTTP ${response.status}）`,
+            });
+        }
+        return { response, text: await response.text() };
+    }
+    catch (error) {
+        if (error instanceof ApmRequestError) {
+            throw error;
+        }
+        if (isAbortError(error)) {
+            throw new ApmRequestError("timeout", { message: "APM portal 请求超时" });
+        }
+        throw new ApmRequestError("http", {
+            message: `APM portal 请求失败：${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function isJsonContentType(value) {
+    return value !== null && /^application\/(?:[a-z0-9.+-]+\+)?json(?:\s*;|$)/i.test(value);
+}
+function invalidProjectResponse() {
+    return new ApmRequestError("invalid_response", {
+        message: "现网 project 接口返回无效响应：可能是项目不存在 / host 不对 / portal 登录失败",
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isAbortError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        (error.name === "AbortError" || error.name === "TimeoutError"));
+}
+//# sourceMappingURL=portal.js.map

package/dist/apm/values.d.ts

@@ -0,0 +1,13 @@
+export declare const LOG_TYPES: readonly ["error", "performance", "api", "paint", "user_behav", "network", "server_error", "footprint", "server_api"];
+export type LogType = (typeof LOG_TYPES)[number];
+export declare const ORDERS: readonly ["ASC", "DESC"];
+export type ApmOrder = (typeof ORDERS)[number];
+/** 请求体由客户端固定生成的键，不能经 where 透传覆盖。 */
+export declare const FIXED_REQUEST_KEYS: ReadonlySet<string>;
+/** 服务端把值直拼 SQL；客户端必须拒绝无法安全透传的字符。 */
+export declare function assertSafeValue(name: string, value: string): void;
+export declare function assertColumnName(value: string): void;
+/** APM portal 只接受带子域的完整站点 host。 */
+export declare function isSiteHost(value: string): boolean;
+/** 把 APM 的客户端本地钟输入归一化为接口接受的无时区格式。 */
+export declare function normalizeLogTime(input: string, edge: "start" | "end"): string;

package/dist/apm/values.js

@@ -0,0 +1,58 @@
+export const LOG_TYPES = [
+    "error",
+    "performance",
+    "api",
+    "paint",
+    "user_behav",
+    "network",
+    "server_error",
+    "footprint",
+    "server_api",
+];
+export const ORDERS = ["ASC", "DESC"];
+/** 请求体由客户端固定生成的键，不能经 where 透传覆盖。 */
+export const FIXED_REQUEST_KEYS = new Set(["type", "page", "pageSize", "order"]);
+/** 服务端把值直拼 SQL；客户端必须拒绝无法安全透传的字符。 */
+export function assertSafeValue(name, value) {
+    if (value.includes("'") || value.includes("\\")) {
+        throw new Error(`${name} 不能包含单引号或反斜杠`);
+    }
+}
+export function assertColumnName(value) {
+    if (!/^[a-z0-9_]+$/.test(value)) {
+        throw new Error(`列名 ${value || "<空>"} 无效，只允许小写字母、数字和下划线`);
+    }
+}
+/** APM portal 只接受带子域的完整站点 host。 */
+export function isSiteHost(value) {
+    return /^[^.]+(\.[^.]+){2,}$/.test(value);
+}
+/** 把 APM 的客户端本地钟输入归一化为接口接受的无时区格式。 */
+export function normalizeLogTime(input, edge) {
+    const value = input.trim();
+    if (/Z$|[+-]\d{2}:\d{2}$/.test(value)) {
+        throw new Error("log_time 是客户端本地钟，无时区语义，请不要携带 Z 或时区偏移");
+    }
+    const match = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}):(\d{2}))?$/.exec(value);
+    if (!match) {
+        throw new Error("时间格式无效，支持 YYYY-MM-DD、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DDTHH:mm:ss");
+    }
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText ?? (edge === "start" ? "00" : "23"));
+    const minute = Number(minuteText ?? (edge === "start" ? "00" : "59"));
+    const second = Number(secondText ?? (edge === "start" ? "00" : "59"));
+    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+    if (date.getUTCFullYear() !== year ||
+        date.getUTCMonth() !== month - 1 ||
+        date.getUTCDate() !== day ||
+        date.getUTCHours() !== hour ||
+        date.getUTCMinutes() !== minute ||
+        date.getUTCSeconds() !== second) {
+        throw new Error("时间值无效，请检查日期和时分秒");
+    }
+    return `${yearText}-${monthText}-${dayText} ${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}:${String(second).padStart(2, "0")}`;
+}
+//# sourceMappingURL=values.js.map

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedConfig } from "./types.js";
+/**
+ * 从配置目录加载并合并配置。
+ *
+ * 约定：
+ * - `<name>.json` 是声明（提交 git），`<name>.local.json` 是本机绑定（gitignore）
+ * - local 深合并覆盖声明
+ * - 声明与同目录 local 的相对路径相对 configDir；机器级 local 相对机器级目录，绝不相对 cwd
+ */
+export interface LoadConfigOptions {
+    /** 配置目录来源；仅 toolkit 来源叠加机器级 local。 */
+    source?: ConfigSource;
+    /**
+     * 语义表覆盖来源（工作区模式传工作区表路径）。
+     * 给定时只读这个路径、缺文件即报错——工作区表是唯一来源，不做两层查找（spec 组件 D）。
+     */
+    eventSemanticsPath?: string;
+}
+export type ConfigSource = "explicit" | "workspace" | "env" | "toolkit";
+/** cx-cli 的机器级配置与无工作区产物目录。 */
+export declare function machineConfigDir(): string;
+export declare function loadConfig(configDir: string, options?: LoadConfigOptions): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { ZodError } from "zod";
+import { parseApmProviderConfig } from "./apm/config.js";
+import { loadEventSemanticsTable } from "./semantics/table-loader.js";
+/** cx-cli 的机器级配置与无工作区产物目录。 */
+export function machineConfigDir() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cx-cli");
+}
+export function loadConfig(configDir, options = {}) {
+    const dir = resolve(configDir);
+    const machineDir = machineConfigDir();
+    const machineToolkit = options.source === "toolkit"
+        ? resolveToolkitPaths(readJsonIfExists(join(machineDir, "toolkit.local.json")), machineDir)
+        : {};
+    const toolkit = mergeLocal(mergeLocal(readJsonIfExists(join(dir, "toolkit.json")), machineToolkit), readJsonIfExists(join(dir, "toolkit.local.json")));
+    const apmProviderPaths = [
+        join(dir, "apm-provider.json"),
+        ...(options.source === "toolkit" ? [join(machineDir, "apm-provider.local.json")] : []),
+        join(dir, "apm-provider.local.json"),
+    ];
+    const apmProviderLayers = apmProviderPaths.map(readApmJsonIfExists);
+    const apmProviderFiles = apmProviderPaths.filter(existsSync);
+    const apmProviderRaw = mergeLocal(mergeLocal(apmProviderLayers[0]?.value ?? {}, apmProviderLayers[1]?.value ?? {}), apmProviderLayers[2]?.value ?? {});
+    const fillPath = options.source === "toolkit"
+        ? join(machineDir, "apm-provider.local.json")
+        : join(dir, "apm-provider.local.json");
+    let apmProvider = null;
+    let apmProviderState;
+    const apmJsonError = apmProviderLayers.find(layer => layer.error !== undefined)?.error;
+    if (apmJsonError !== undefined) {
+        apmProviderState = { kind: "invalid", fillPath, error: apmJsonError };
+    }
+    else if (!existsSync(join(dir, "apm-provider.json"))) {
+        apmProviderState = { kind: "missing", fillPath, configDir: dir };
+    }
+    else {
+        try {
+            const parsed = parseApmConfig(apmProviderRaw);
+            if (parsed.baseUrl === "" || parsed.defaults.host === "") {
+                apmProviderState = { kind: "unconfigured", fillPath };
+            }
+            else {
+                apmProvider = parsed;
+                apmProviderState = null;
+            }
+        }
+        catch (error) {
+            apmProviderState = {
+                kind: "invalid",
+                fillPath,
+                error: `${error instanceof Error ? error.message : String(error)}（配置文件：${apmProviderFiles.join("、")}）`,
+            };
+        }
+    }
+    const eventSemantics = loadEventSemanticsTable(options.eventSemanticsPath ?? join(dir, "event-semantics.json"), {
+        required: options.eventSemanticsPath !== undefined,
+    });
+    const rulesRaw = readJsonIfExists(join(dir, "diagnostic-rules.json"));
+    const resolvePath = (value) => (isAbsolute(value) ? value : join(dir, value));
+    const logSourceRaw = (toolkit.logSource ?? { type: "apm" });
+    const logSource = logSourceRaw.type === "file"
+        ? { type: "file", path: resolvePath(logSourceRaw.path) }
+        : { type: "apm" };
+    return {
+        configDir: dir,
+        runsDir: resolvePath(String(toolkit.runsDir ?? join(machineConfigDir(), "runs"))),
+        outDir: resolvePath(String(toolkit.outDir ?? join(machineConfigDir(), "out"))),
+        projectHistoryDir: resolvePath(String(toolkit.projectHistoryDir ?? join(machineConfigDir(), "data"))),
+        logSource,
+        apmProvider,
+        apmProviderState,
+        eventSemantics,
+        diagnosticRules: (rulesRaw.rules ?? []).map(normalizeRule),
+    };
+}
+/** 机器级 toolkit local 中的相对路径相对机器级目录，而不是声明目录解析。 */
+function resolveToolkitPaths(raw, baseDir) {
+    const result = { ...raw };
+    for (const key of ["runsDir", "outDir", "projectHistoryDir"]) {
+        const value = result[key];
+        if (typeof value === "string" && !isAbsolute(value)) {
+            result[key] = join(baseDir, value);
+        }
+    }
+    if (isPlainObject(result.logSource)) {
+        const path = result.logSource.path;
+        if (typeof path === "string" && !isAbsolute(path)) {
+            result.logSource = { ...result.logSource, path: join(baseDir, path) };
+        }
+    }
+    return result;
+}
+function parseApmConfig(raw) {
+    try {
+        return parseApmProviderConfig(raw);
+    }
+    catch (error) {
+        if (!(error instanceof ZodError)) {
+            throw error;
+        }
+        const details = error.issues.flatMap(issue => {
+            if (issue.code === "unrecognized_keys") {
+                return issue.keys.map(key => `${[...issue.path, key].join(".")} 不是允许的键`);
+            }
+            return [`${issue.path.join(".") || "<root>"} ${issue.message}`];
+        });
+        throw new Error(`apm-provider.json: ${details.join("；")}`);
+    }
+}
+/** 把配置里的原始规则对象补齐默认值，归一化为 DiagnosticRule。 */
+function normalizeRule(rule) {
+    return {
+        id: String(rule.id ?? rule.kind ?? "unknown_rule"),
+        enabled: rule.enabled !== false,
+        kind: String(rule.kind ?? "unknown"),
+        description: String(rule.description ?? ""),
+        severity: rule.severity ?? null,
+        maxGapSeconds: typeof rule.maxGapSeconds === "number" ? rule.maxGapSeconds : null,
+        lookahead: typeof rule.lookahead === "number" ? rule.lookahead : 8,
+        includePossibleStateChange: rule.includePossibleStateChange !== false,
+        severityByStateChange: rule.severityByStateChange ?? {},
+        reasonTemplates: rule.reasonTemplates ?? {},
+    };
+}
+function readJsonIfExists(filePath) {
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function readApmJsonIfExists(filePath) {
+    if (!existsSync(filePath)) {
+        return { value: {} };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!isPlainObject(parsed)) {
+            return { value: {}, error: `${filePath}: 顶层必须是 JSON 对象` };
+        }
+        return { value: parsed };
+    }
+    catch (error) {
+        return {
+            value: {},
+            error: `${filePath}: 不是合法 JSON（${error instanceof Error ? error.message : String(error)}）`,
+        };
+    }
+}
+/** local 深合并覆盖声明：对象递归合并，其余类型直接覆盖。 */
+function mergeLocal(base, local) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(local)) {
+        const existing = result[key];
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            result[key] = mergeLocal(existing, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=config.js.map

package/dist/db/client.d.ts

@@ -0,0 +1,23 @@
+export type DbRow = Record<string, unknown>;
+/** 占位参数：本仓库的查询只按 PROJECT_UID 过滤，标量足够。 */
+export type DbParam = string | number;
+/** 薄接口：provider 只依赖它，单测注入假实现即可覆盖 SQL 文本与参数。 */
+export interface DbClient {
+    query(sql: string, params: DbParam[]): Promise<DbRow[]>;
+    close(): Promise<void>;
+}
+export interface MysqlClientConfig {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port: number;
+}
+/**
+ * mysql2/promise 单连接实现。
+ *
+ * 不设 timezone / charset 等自定义项：CREATE_TIME 按本地时区转 Date 后格式化成文件名，
+ * 与存量快照文件名连续，避免配置漂移让同一条记录生成不同文件名。
+ * mysql2 用动态 import：诊断命令不碰 DB，不该为它付驱动加载成本。
+ */
+export declare function createMysqlClient(config: MysqlClientConfig): Promise<DbClient>;

package/dist/db/client.js

@@ -0,0 +1,21 @@
+/**
+ * mysql2/promise 单连接实现。
+ *
+ * 不设 timezone / charset 等自定义项：CREATE_TIME 按本地时区转 Date 后格式化成文件名，
+ * 与存量快照文件名连续，避免配置漂移让同一条记录生成不同文件名。
+ * mysql2 用动态 import：诊断命令不碰 DB，不该为它付驱动加载成本。
+ */
+export async function createMysqlClient(config) {
+    const { createConnection } = await import("mysql2/promise");
+    const connection = await createConnection(config);
+    return {
+        async query(sql, params) {
+            const [rows] = await connection.execute(sql, params);
+            return Array.isArray(rows) ? rows : [];
+        },
+        async close() {
+            await connection.end();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/diff/project-diff.d.ts

@@ -0,0 +1,125 @@
+import type { ProjectElement, ProjectPage } from "../types.js";
+export interface FieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+export interface ChangedElementDiff {
+    lookupKey: string;
+    id: string | null;
+    type: string;
+    pagePath: string;
+    fieldsChanged: FieldChange[];
+}
+export interface SectionItemRecord {
+    lookupKey: string;
+    id: string | null;
+    path: string;
+    sectionKey: string;
+    sectionLabel: string;
+    itemIndex: number;
+    itemLabel: string | null;
+    type: unknown;
+    width: unknown;
+    height: unknown;
+    bgColor: unknown;
+    bgImageUrl: unknown;
+    sheetLocation: unknown;
+    elementCount: number;
+    bleed: Record<string, unknown> | null;
+    backend: Record<string, unknown> | null;
+    template: Record<string, unknown> | null;
+    flysheetParams: Record<string, unknown> | null;
+}
+export interface ChangedSectionItemDiff {
+    lookupKey: string;
+    id: string | null;
+    path: string;
+    sectionKey: string;
+    sectionLabel: string;
+    itemLabel: string | null;
+    type: unknown;
+    fieldsChanged: FieldChange[];
+}
+export interface CollectionSectionDiff {
+    key: string;
+    label: string;
+    beforeExists: boolean;
+    afterExists: boolean;
+    beforeCount: number;
+    afterCount: number;
+    addedItems: SectionItemRecord[];
+    removedItems: SectionItemRecord[];
+    changedItems: ChangedSectionItemDiff[];
+    summary: {
+        addedItemCount: number;
+        removedItemCount: number;
+        changedItemCount: number;
+    };
+}
+export interface CoverSectionDiff extends Omit<CollectionSectionDiff, "summary"> {
+    changedFields: FieldChange[];
+    summary: {
+        changedFieldCount: number;
+        addedItemCount: number;
+        removedItemCount: number;
+        changedItemCount: number;
+    };
+}
+export interface PageSectionDiffs {
+    pages: CollectionSectionDiff;
+    cover: CoverSectionDiff;
+    frontFlysheet: CollectionSectionDiff;
+    backFlysheet: CollectionSectionDiff;
+    edge: CollectionSectionDiff;
+}
+export interface SnapshotSummary {
+    projectMeta: Record<string, unknown>;
+    imageCount: number;
+    pageCount: number;
+    elementCount: number;
+    pageCollectionCounts: Record<string, number>;
+    logicalPageCollectionCounts: Record<string, number>;
+    elementTypeCounts: Record<string, number>;
+}
+export interface ProjectDiffResult {
+    generatedAt: string;
+    beforeSummary: SnapshotSummary;
+    afterSummary: SnapshotSummary;
+    pageSectionDiffs: PageSectionDiffs;
+    changedProjectMeta: FieldChange[];
+    addedPages: EnrichedPage[];
+    removedPages: EnrichedPage[];
+    addedElements: ProjectElement[];
+    removedElements: ProjectElement[];
+    changedElements: ChangedElementDiff[];
+    summary: {
+        addedPageCount: number;
+        removedPageCount: number;
+        addedElementCount: number;
+        removedElementCount: number;
+        changedElementCount: number;
+        changedProjectMetaCount: number;
+    };
+}
+interface EnrichedPage extends ProjectPage {
+    logicalCollectionName: string;
+    logicalCollectionLabel: string;
+    logicalItemLabel: string | null;
+}
+interface DiffProjectSnapshotsOptions {
+    maxChanges?: number;
+}
+/**
+ * 对比两个 project 快照。
+ *
+ * 输出重点不是“全文 diff”，而是诊断最关心的三类变化：
+ * - 页面增删
+ * - 元素增删
+ * - 元素几何 / crop / 图片引用变化
+ *
+ * 这样一来，日志里看到 `clickCropImage`、`transformElement`、`saveProject`
+ * 之后，就能直接检查这些动作是否真的改变了 project 状态。
+ */
+export declare function diffProjectSnapshots(beforeRaw: unknown, afterRaw: unknown, options?: DiffProjectSnapshotsOptions): ProjectDiffResult;
+export {};