@pactor-app/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pactor Contributors
+
+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/README.md

@@ -0,0 +1,47 @@
+# @pactor-app/cli
+
+[Pactor](https://github.com/426-330/pactor) 的命令行工具（bin `pactor`）：本地 DSL 开发工具链，覆盖校验、结构摘要、静态检查、Schema 导出、编译为 Runtime Envelope JSON 与脚手架生成。
+
+## 安装
+
+```bash
+npm install -g @pactor-app/cli
+# 或
+pnpm add -g @pactor-app/cli
+```
+
+要求 Node.js >= 18；零 React 依赖。
+
+## 命令
+
+```text
+pactor validate <files...>      校验 DSL 文件（page 走 Schema 校验，fragment 宽松检查 dsl + body）
+pactor inspect <file>           输出 DSL 结构摘要（状态 / 数据源 / 组件计数 / 动作 / 权限 / 表达式）
+pactor lint <paths...>          校验 + 静态检查规则（目录递归 .page/.fragment.yaml/.yml）
+pactor schema [-o <file>]       输出 Page DSL JSON Schema（含 node / action 关联 Schema）
+pactor build <src> -o <dir>     递归编译 DSL 为 Runtime Envelope JSON（<out>/<id>.json）
+pactor create <name> [-t app]   从模板生成业务工程（vite + react + @pactor-app/app + @pactor-app/ui）
+pactor --help                   命令清单
+```
+
+退出码语义：
+
+- `0`：成功（lint 仅 warning 也算成功）
+- `1`：校验或 lint 失败（lint 存在 error）
+- `2`：用法错误（缺参数、文件不存在、目标目录非空等）
+
+lint 规则：
+
+- `expression-syntax`（error）：解析 DSL 中所有 `${...}` 模板与整体表达式
+- `component-naming`（warning）：组件 type 应为 PascalCase
+- `permission-format`（warning）：权限码应为 `resource:action` 形态
+
+`preview` 命令在 V1 未实现（见设计文档第 84 节裁剪说明）。
+
+## 文档
+
+完整文档见 <https://github.com/426-330/pactor/tree/main/docs>（`pnpm docs:dev` 本地启动文档站）。
+
+## License
+
+[MIT](../../LICENSE)

package/dist/cli.js

@@ -0,0 +1,713 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { pathToFileURL } from "url";
+
+// src/args.ts
+var SHORT_VALUE_FLAGS = /* @__PURE__ */ new Set(["o", "t"]);
+var UsageError = class extends Error {
+};
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith("--")) {
+      const body = token.slice(2);
+      const eq = body.indexOf("=");
+      if (eq >= 0) {
+        flags[body.slice(0, eq)] = body.slice(eq + 1);
+      } else {
+        flags[body] = true;
+      }
+      continue;
+    }
+    if (token.startsWith("-") && token.length > 1) {
+      const name = token.slice(1);
+      if (SHORT_VALUE_FLAGS.has(name)) {
+        const value = argv[i + 1];
+        if (value === void 0) {
+          throw new UsageError(`\u9009\u9879 -${name} \u7F3A\u5C11\u503C`);
+        }
+        flags[name] = value;
+        i += 1;
+      } else {
+        flags[name] = true;
+      }
+      continue;
+    }
+    positionals.push(token);
+  }
+  return { positionals, flags };
+}
+function flagValue(args, name) {
+  const value = args.flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/commands/build.ts
+import { existsSync as existsSync2, mkdirSync, statSync as statSync2, writeFileSync } from "fs";
+import { join as join2 } from "path";
+
+// src/dsl-io.ts
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { validatePageDsl } from "@pactor-app/schema";
+import { parseDocument } from "yaml";
+var DSL_FILE_RE = /\.(page|fragment)\.(yaml|yml)$/;
+var FRAGMENT_FILE_RE = /\.fragment\.(yaml|yml)$/;
+function isDslFile(path) {
+  return DSL_FILE_RE.test(path);
+}
+function isFragmentFile(path) {
+  return FRAGMENT_FILE_RE.test(path);
+}
+function readDslFile(file) {
+  const source = readFileSync(file, "utf8");
+  const doc = parseDocument(source);
+  if (doc.errors.length > 0) {
+    return {
+      ok: false,
+      errors: doc.errors.map((error) => {
+        const pos = error.linePos?.[0];
+        const where = pos ? `\u884C ${pos.line} \u5217 ${pos.col}` : "\u672A\u77E5\u4F4D\u7F6E";
+        return { path: "/", message: `${where}: ${error.message}`, keyword: "yaml" };
+      })
+    };
+  }
+  return { ok: true, data: doc.toJS() };
+}
+function validateDsl(data, isFragment) {
+  if (isFragment) {
+    const fragment = data;
+    if (fragment === null || typeof fragment !== "object" || !("dsl" in fragment) || !("body" in fragment)) {
+      return [{ path: "/", message: "\u5FC5\u987B\u5B58\u5728 dsl \u4E0E body \u5B57\u6BB5", keyword: "required" }];
+    }
+    return [];
+  }
+  const result = validatePageDsl(data);
+  return result.errors;
+}
+function collectDslFiles(paths) {
+  const files = [];
+  const missing = [];
+  const walk = (target) => {
+    if (!existsSync(target)) {
+      missing.push(target);
+      return;
+    }
+    const stat = statSync(target);
+    if (stat.isDirectory()) {
+      for (const entry of readdirSync(target)) {
+        walk(join(target, entry));
+      }
+      return;
+    }
+    if (isDslFile(target)) {
+      files.push(target);
+    }
+  };
+  for (const path of paths) {
+    walk(path);
+  }
+  files.sort();
+  return { files, missing };
+}
+function collectStrings(data, basePath = "") {
+  const entries = [];
+  const walk = (value, path) => {
+    if (typeof value === "string") {
+      entries.push({ path: path === "" ? "/" : path, value });
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(item, `${path}/${index}`));
+      return;
+    }
+    if (value !== null && typeof value === "object") {
+      for (const [key, item] of Object.entries(value)) {
+        walk(item, `${path}/${key}`);
+      }
+    }
+  };
+  walk(data, basePath);
+  return entries;
+}
+function extractTemplateExpressions(value) {
+  const sources = [];
+  let i = 0;
+  let unterminated = false;
+  while (i < value.length) {
+    if (value[i] === "$" && value[i + 1] === "{") {
+      i += 2;
+      let depth = 1;
+      let quote;
+      let source = "";
+      let closed = false;
+      while (i < value.length) {
+        const c = value[i];
+        if (quote !== void 0) {
+          source += c;
+          if (c === "\\" && i + 1 < value.length) {
+            source += value[i + 1];
+            i += 2;
+            continue;
+          }
+          if (c === quote) {
+            quote = void 0;
+          }
+          i += 1;
+          continue;
+        }
+        if (c === "'" || c === '"') {
+          quote = c;
+          source += c;
+          i += 1;
+          continue;
+        }
+        if (c === "{") {
+          depth += 1;
+          source += c;
+          i += 1;
+          continue;
+        }
+        if (c === "}") {
+          depth -= 1;
+          if (depth === 0) {
+            closed = true;
+            i += 1;
+            break;
+          }
+          source += c;
+          i += 1;
+          continue;
+        }
+        source += c;
+        i += 1;
+      }
+      if (!closed) {
+        unterminated = true;
+        break;
+      }
+      sources.push(source);
+      continue;
+    }
+    i += 1;
+  }
+  return { sources, unterminated };
+}
+function walkDslTree(root, visit, basePath = "/body") {
+  if (root === void 0 || root === null || typeof root !== "object") return;
+  visit(root, basePath);
+  if (Array.isArray(root.children)) {
+    root.children.forEach((child, index) => {
+      walkDslTree(child, visit, `${basePath}/children/${index}`);
+    });
+  }
+}
+
+// src/commands/build.ts
+function runBuild(args, io) {
+  const src = args.positionals[0];
+  const outDir = flagValue(args, "o");
+  if (src === void 0 || outDir === void 0 || outDir === "") {
+    io.err("\u7528\u6CD5: pactor build <src> -o <dir>");
+    return 2;
+  }
+  if (!existsSync2(src) || !statSync2(src).isDirectory()) {
+    io.err(`\u6E90\u76EE\u5F55\u4E0D\u5B58\u5728: ${src}`);
+    return 2;
+  }
+  const { files } = collectDslFiles([src]);
+  if (files.length === 0) {
+    io.err(`\u672A\u627E\u5230 DSL \u6587\u4EF6: ${src}\uFF08.page/.fragment.yaml/.yml\uFF09`);
+    return 1;
+  }
+  const compiled = [];
+  let failed = false;
+  for (const file of files) {
+    const read = readDslFile(file);
+    const errors = read.ok ? validateDsl(read.data, isFragmentFile(file)) : read.errors;
+    if (errors.length > 0) {
+      failed = true;
+      for (const error of errors) {
+        io.err(`${file}: ${error.path}: ${error.message} (${error.keyword})`);
+      }
+      continue;
+    }
+    if (!read.ok) continue;
+    const isFragment = isFragmentFile(file);
+    const data = read.data;
+    const id = isFragment ? data.fragment.id : data.page.id;
+    compiled.push({
+      id,
+      envelope: {
+        id,
+        resourceType: isFragment ? "fragment" : "page",
+        version: 1,
+        dslVersion: data.dsl,
+        schema: data
+      }
+    });
+  }
+  if (failed) {
+    io.err("\u6784\u5EFA\u4E2D\u6B62: \u5B58\u5728\u6821\u9A8C\u5931\u8D25\u7684 DSL \u6587\u4EF6");
+    return 1;
+  }
+  mkdirSync(outDir, { recursive: true });
+  for (const { id, envelope } of compiled) {
+    const target = join2(outDir, `${id}.json`);
+    writeFileSync(target, `${JSON.stringify(envelope, null, 2)}
+`, "utf8");
+    io.out(`\u5DF2\u751F\u6210: ${target}`);
+  }
+  io.out(`\u6784\u5EFA\u5B8C\u6210: ${compiled.length} \u4E2A\u8D44\u6E90`);
+  return 0;
+}
+
+// src/commands/create.ts
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync2,
+  statSync as statSync3,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { basename, dirname, join as join3, resolve } from "path";
+import { fileURLToPath } from "url";
+var APP_NAME_PLACEHOLDER = /__APP_NAME__/g;
+function defaultTemplatesDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [
+    join3(here, "../templates/app"),
+    join3(here, "../../templates/app")
+  ]) {
+    if (existsSync3(candidate)) return candidate;
+  }
+  return join3(here, "../templates/app");
+}
+function copyTemplate(src, dest, appName) {
+  mkdirSync2(dest, { recursive: true });
+  for (const entry of readdirSync2(src)) {
+    const from = join3(src, entry);
+    const to = join3(dest, entry);
+    if (statSync3(from).isDirectory()) {
+      copyTemplate(from, to, appName);
+      continue;
+    }
+    const content = readFileSync2(from, "utf8").replace(APP_NAME_PLACEHOLDER, appName);
+    writeFileSync2(to, content, "utf8");
+  }
+}
+function runCreate(args, io, templatesDir = defaultTemplatesDir()) {
+  const name = args.positionals[0];
+  if (name === void 0) {
+    io.err("\u7528\u6CD5: pactor create <name> [-t app]");
+    return 2;
+  }
+  const template = flagValue(args, "t") ?? "app";
+  if (template !== "app") {
+    io.err(`\u672A\u77E5\u6A21\u677F: ${template}\uFF08\u5F53\u524D\u4EC5\u652F\u6301 app\uFF09`);
+    return 2;
+  }
+  const target = resolve(name);
+  const appName = basename(target);
+  if (existsSync3(target)) {
+    if (!statSync3(target).isDirectory()) {
+      io.err(`\u76EE\u6807\u5DF2\u5B58\u5728\u4E14\u4E0D\u662F\u76EE\u5F55: ${target}`);
+      return 2;
+    }
+    if (readdirSync2(target).length > 0) {
+      io.err(`\u76EE\u6807\u76EE\u5F55\u975E\u7A7A\uFF0C\u62D2\u7EDD\u8986\u76D6: ${target}`);
+      return 2;
+    }
+  }
+  copyTemplate(templatesDir, target, appName);
+  io.out(`\u5DF2\u521B\u5EFA\u5DE5\u7A0B: ${target}`);
+  io.out("\u4E0B\u4E00\u6B65:");
+  io.out(`  cd ${name}`);
+  io.out("  pnpm install");
+  io.out("  pnpm dev");
+  return 0;
+}
+
+// src/commands/inspect.ts
+import { existsSync as existsSync4, statSync as statSync4 } from "fs";
+function permissionCodes(permission) {
+  if (permission === void 0) return [];
+  if (typeof permission === "string") return [permission];
+  if (Array.isArray(permission)) return permission;
+  return Array.isArray(permission.code) ? permission.code : [permission.code];
+}
+function actionList(config) {
+  if (config === void 0) return [];
+  return Array.isArray(config) ? config : [config];
+}
+function runInspect(args, io) {
+  if (args.positionals.length !== 1) {
+    io.err("\u7528\u6CD5: pactor inspect <file>");
+    return 2;
+  }
+  const file = args.positionals[0];
+  if (!existsSync4(file) || !statSync4(file).isFile()) {
+    io.err(`\u6587\u4EF6\u4E0D\u5B58\u5728: ${file}`);
+    return 2;
+  }
+  const read = readDslFile(file);
+  if (!read.ok) {
+    for (const error of read.errors) {
+      io.err(`${file}: ${error.path}: ${error.message} (${error.keyword})`);
+    }
+    return 1;
+  }
+  const isFragment = isFragmentFile(file);
+  const data = read.data;
+  const lines = [];
+  if (isFragment) {
+    lines.push(`fragment: ${data.fragment?.id ?? "(\u672A\u77E5)"}`);
+    if (data.fragment?.title !== void 0) lines.push(`\u6807\u9898: ${data.fragment.title}`);
+  } else {
+    lines.push(`page: ${data.page?.id ?? "(\u672A\u77E5)"}`);
+    if (data.page?.title !== void 0) lines.push(`\u6807\u9898: ${data.page.title}`);
+    if (data.page?.type !== void 0) lines.push(`\u7C7B\u578B: ${data.page.type}`);
+  }
+  lines.push(`dslVersion: ${data.dsl ?? "(\u672A\u77E5)"}`);
+  const stateKeys = Object.keys(data.state ?? {});
+  lines.push(`\u72B6\u6001\u952E: ${stateKeys.length > 0 ? stateKeys.join(", ") : "(\u65E0)"}`);
+  const dataSources = Object.entries(data.dataSources ?? {});
+  lines.push(`\u6570\u636E\u6E90: ${dataSources.length} \u4E2A`);
+  for (const [name, config] of dataSources) {
+    const service = config.service !== void 0 ? `, service=${config.service}` : "";
+    lines.push(`  - ${name} (type=${config.type}${service})`);
+  }
+  const componentCounts = /* @__PURE__ */ new Map();
+  const actions = [];
+  const permissions = [];
+  walkDslTree(data.body, (node, path) => {
+    componentCounts.set(node.type, (componentCounts.get(node.type) ?? 0) + 1);
+    for (const [event, config] of Object.entries(node.events ?? {})) {
+      for (const action of actionList(config)) {
+        actions.push(`  - ${path} events.${event} \u2192 ${action.action}`);
+      }
+    }
+    for (const code of permissionCodes(node.permission)) {
+      permissions.push(`  - ${path} \u2192 ${code}`);
+    }
+  });
+  lines.push(`\u7EC4\u4EF6: ${[...componentCounts.values()].reduce((a, b) => a + b, 0)} \u4E2A`);
+  for (const [type, count] of [...componentCounts.entries()].sort()) {
+    lines.push(`  - ${type} x${count}`);
+  }
+  for (const [event, config] of Object.entries(data.lifecycle ?? {})) {
+    for (const action of actionList(config)) {
+      actions.push(`  - lifecycle.${event} \u2192 ${action.action}`);
+    }
+  }
+  for (const code of permissionCodes(data.page?.permission)) {
+    permissions.push(`  - /page \u2192 ${code}`);
+  }
+  lines.push(`\u52A8\u4F5C: ${actions.length} \u4E2A`);
+  lines.push(...actions.length > 0 ? actions : ["  (\u65E0)"]);
+  lines.push(`\u6743\u9650: ${permissions.length} \u4E2A`);
+  lines.push(...permissions.length > 0 ? permissions : ["  (\u65E0)"]);
+  const expressions = [];
+  for (const entry of collectStrings(data)) {
+    const { sources } = extractTemplateExpressions(entry.value);
+    for (const source of sources) {
+      expressions.push(`  - ${entry.path}: \${${source}}`);
+    }
+  }
+  lines.push(`\u8868\u8FBE\u5F0F: ${expressions.length} \u4E2A`);
+  lines.push(...expressions.length > 0 ? expressions : ["  (\u65E0)"]);
+  for (const line of lines) {
+    io.out(line);
+  }
+  return 0;
+}
+
+// src/commands/lint.ts
+import { ExpressionError, hasExpression, parseExpression } from "@pactor-app/expression";
+function permissionCodes2(permission) {
+  if (permission === void 0) return [];
+  if (typeof permission === "string") return [permission];
+  if (Array.isArray(permission)) return permission;
+  return Array.isArray(permission.code) ? permission.code : [permission.code];
+}
+function actionList2(config) {
+  if (config === void 0) return [];
+  return Array.isArray(config) ? config : [config];
+}
+var PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
+var PERMISSION_CODE_RE = /^[^:]+:[^:]+$/;
+function lintExpressions(data, findings) {
+  for (const entry of collectStrings(data)) {
+    const bareExpression = entry.path.endsWith("/expression") && !hasExpression(entry.value);
+    if (!hasExpression(entry.value) && !bareExpression) continue;
+    if (bareExpression) {
+      try {
+        parseExpression(entry.value);
+      } catch (error) {
+        findings.push({
+          level: "error",
+          rule: "expression-syntax",
+          path: entry.path,
+          message: error instanceof ExpressionError ? error.message : String(error)
+        });
+      }
+      continue;
+    }
+    const { sources, unterminated } = extractTemplateExpressions(entry.value);
+    if (unterminated) {
+      findings.push({
+        level: "error",
+        rule: "expression-syntax",
+        path: entry.path,
+        message: '\u672A\u95ED\u5408\u7684 "${"'
+      });
+      continue;
+    }
+    for (const source of sources) {
+      try {
+        parseExpression(source);
+      } catch (error) {
+        findings.push({
+          level: "error",
+          rule: "expression-syntax",
+          path: entry.path,
+          message: `\u8868\u8FBE\u5F0F \${${source}} \u89E3\u6790\u5931\u8D25: ${error instanceof ExpressionError ? error.message : String(error)}`
+        });
+      }
+    }
+  }
+}
+function lintComponentNaming(body, findings) {
+  walkDslTree(body, (node, path) => {
+    if (typeof node.type !== "string" || !PASCAL_CASE_RE.test(node.type)) {
+      findings.push({
+        level: "warning",
+        rule: "component-naming",
+        path: `${path}/type`,
+        message: `\u7EC4\u4EF6\u7C7B\u578B "${String(node.type)}" \u4E0D\u662F PascalCase`
+      });
+    }
+  });
+}
+function lintPermissionFormat(data, findings) {
+  const check = (codes, path) => {
+    for (const code of codes) {
+      if (!PERMISSION_CODE_RE.test(code)) {
+        findings.push({
+          level: "warning",
+          rule: "permission-format",
+          path,
+          message: `\u6743\u9650\u7801 "${code}" \u4E0D\u662F resource:action \u5F62\u6001`
+        });
+      }
+    }
+  };
+  check(permissionCodes2(data.page?.permission), "/page/permission");
+  walkDslTree(data.body, (node, path) => {
+    check(permissionCodes2(node.permission), `${path}/permission`);
+    for (const [event, config] of Object.entries(node.events ?? {})) {
+      for (const action of actionList2(config)) {
+        check(permissionCodes2(action.permission), `${path}/events/${event}/permission`);
+      }
+    }
+  });
+  for (const [event, config] of Object.entries(data.lifecycle ?? {})) {
+    for (const action of actionList2(config)) {
+      check(permissionCodes2(action.permission), `/lifecycle/${event}/permission`);
+    }
+  }
+}
+function lintDslData(data, isFragment) {
+  const findings = [];
+  for (const error of validateDsl(data, isFragment)) {
+    findings.push({
+      level: "error",
+      rule: "schema",
+      path: error.path,
+      message: `${error.message} (${error.keyword})`
+    });
+  }
+  lintExpressions(data, findings);
+  const typed = data;
+  lintComponentNaming(typed.body, findings);
+  lintPermissionFormat(typed, findings);
+  return findings;
+}
+function runLint(args, io) {
+  if (args.positionals.length === 0) {
+    io.err("\u7528\u6CD5: pactor lint <paths...>");
+    return 2;
+  }
+  const { files, missing } = collectDslFiles(args.positionals);
+  for (const path of missing) {
+    io.err(`\u8DEF\u5F84\u4E0D\u5B58\u5728: ${path}`);
+  }
+  if (missing.length > 0) {
+    return 2;
+  }
+  if (files.length === 0) {
+    io.err("\u672A\u627E\u5230 DSL \u6587\u4EF6\uFF08.page/.fragment.yaml/.yml\uFF09");
+    return 2;
+  }
+  let errors = 0;
+  let warnings = 0;
+  for (const file of files) {
+    const read = readDslFile(file);
+    const findings = read.ok ? lintDslData(read.data, isFragmentFile(file)) : read.errors.map((error) => ({
+      level: "error",
+      rule: "yaml",
+      path: error.path,
+      message: error.message
+    }));
+    if (findings.length === 0) continue;
+    io.out(`${file}:`);
+    for (const finding of findings) {
+      io.out(`  [${finding.level}] ${finding.rule} ${finding.path}: ${finding.message}`);
+      if (finding.level === "error") errors += 1;
+      else warnings += 1;
+    }
+  }
+  io.out(`lint \u5B8C\u6210: ${files.length} \u4E2A\u6587\u4EF6\uFF0C${errors} \u4E2A error\uFF0C${warnings} \u4E2A warning`);
+  return errors > 0 ? 1 : 0;
+}
+
+// src/commands/schema.ts
+import { writeFileSync as writeFileSync3 } from "fs";
+import {
+  ACTION_CONFIG_SCHEMA_ID,
+  actionConfigSchema,
+  DSL_NODE_SCHEMA_ID,
+  dslNodeSchema,
+  PAGE_DSL_SCHEMA_ID,
+  pageDslSchema
+} from "@pactor-app/schema";
+function runSchema(args, io) {
+  const document = {
+    [PAGE_DSL_SCHEMA_ID]: pageDslSchema,
+    [DSL_NODE_SCHEMA_ID]: dslNodeSchema,
+    [ACTION_CONFIG_SCHEMA_ID]: actionConfigSchema
+  };
+  const json = JSON.stringify(document, null, 2);
+  const output = flagValue(args, "o");
+  if (output !== void 0) {
+    if (output === "") {
+      io.err("\u7528\u6CD5: pactor schema [-o <file>]");
+      return 2;
+    }
+    writeFileSync3(output, `${json}
+`, "utf8");
+    io.out(`\u5DF2\u5199\u5165: ${output}`);
+    return 0;
+  }
+  io.out(json);
+  return 0;
+}
+
+// src/commands/validate.ts
+import { existsSync as existsSync5, statSync as statSync5 } from "fs";
+function runValidate(args, io) {
+  if (args.positionals.length === 0) {
+    io.err("\u7528\u6CD5: pactor validate <files...>");
+    return 2;
+  }
+  for (const file of args.positionals) {
+    if (!existsSync5(file) || !statSync5(file).isFile()) {
+      io.err(`\u6587\u4EF6\u4E0D\u5B58\u5728: ${file}`);
+      return 2;
+    }
+  }
+  let failed = 0;
+  for (const file of args.positionals) {
+    const read = readDslFile(file);
+    if (!read.ok) {
+      failed += 1;
+      for (const error of read.errors) {
+        io.err(`${file}: ${error.path}: ${error.message} (${error.keyword})`);
+      }
+      continue;
+    }
+    const errors = validateDsl(read.data, isFragmentFile(file));
+    if (errors.length > 0) {
+      failed += 1;
+      for (const error of errors) {
+        io.err(`${file}: ${error.path}: ${error.message} (${error.keyword})`);
+      }
+    }
+  }
+  const passed = args.positionals.length - failed;
+  if (failed > 0) {
+    io.err(`\u6821\u9A8C\u5931\u8D25: ${failed} \u4E2A\u6587\u4EF6\u672A\u901A\u8FC7\uFF0C${passed} \u4E2A\u901A\u8FC7`);
+    return 1;
+  }
+  io.out(`\u6821\u9A8C\u901A\u8FC7: \u5171 ${passed} \u4E2A\u6587\u4EF6`);
+  return 0;
+}
+
+// src/cli.ts
+var HELP_TEXT = `pactor \u2014 Pactor DSL \u547D\u4EE4\u884C\u5DE5\u5177
+
+\u7528\u6CD5: pactor <command> [options]
+
+\u547D\u4EE4:
+  pactor validate <files...>      \u6821\u9A8C DSL \u6587\u4EF6\uFF08page \u5B8C\u6574\u6821\u9A8C\uFF0Cfragment \u5BBD\u677E\u68C0\u67E5\uFF09
+  pactor inspect <file>           \u8F93\u51FA DSL \u7ED3\u6784\u6458\u8981\uFF08\u7EC4\u4EF6\u8BA1\u6570 / \u52A8\u4F5C / \u6743\u9650 / \u8868\u8FBE\u5F0F\uFF09
+  pactor lint <paths...>          \u6821\u9A8C + \u9759\u6001\u68C0\u67E5\uFF08\u76EE\u5F55\u9012\u5F52 .page/.fragment.yaml\uFF09
+  pactor schema [-o <file>]       \u8F93\u51FA Page DSL JSON Schema
+  pactor build <src> -o <dir>     \u7F16\u8BD1 DSL \u4E3A Runtime Envelope JSON
+  pactor create <name> [-t app]   \u4ECE\u6A21\u677F\u751F\u6210\u4E1A\u52A1\u5DE5\u7A0B
+
+\u9000\u51FA\u7801: 0 \u6210\u529F\uFF1B1 \u6821\u9A8C/lint \u5931\u8D25\uFF1B2 \u7528\u6CD5\u9519\u8BEF
+`;
+function runCli(argv, io) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "--help" || command === "-h") {
+    io.out(HELP_TEXT);
+    return 0;
+  }
+  let args;
+  try {
+    args = parseArgs(rest);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.err(`\u53C2\u6570\u9519\u8BEF: ${error.message}`);
+      return 2;
+    }
+    throw error;
+  }
+  switch (command) {
+    case "validate":
+      return runValidate(args, io);
+    case "inspect":
+      return runInspect(args, io);
+    case "lint":
+      return runLint(args, io);
+    case "schema":
+      return runSchema(args, io);
+    case "build":
+      return runBuild(args, io);
+    case "create":
+      return runCreate(args, io);
+    default:
+      io.err(`\u672A\u77E5\u547D\u4EE4: ${command}`);
+      io.err(HELP_TEXT);
+      return 2;
+  }
+}
+var isMain = process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  const io = {
+    out: (line) => process.stdout.write(`${line}
+`),
+    err: (line) => process.stderr.write(`${line}
+`)
+  };
+  process.exit(runCli(process.argv.slice(2), io));
+}
+export {
+  HELP_TEXT,
+  runCli
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pactor-app/cli",
+  "version": "0.1.0",
+  "description": "Pactor CLI: local DSL toolchain (validate / inspect / lint / schema / build / create)",
+  "keywords": [
+    "pactor",
+    "dsl",
+    "server-driven-ui",
+    "cli",
+    "toolchain"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/426-330/pactor.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/426-330/pactor/tree/main/packages/cli",
+  "bugs": "https://github.com/426-330/pactor/issues",
+  "type": "module",
+  "bin": {
+    "pactor": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "@pactor-app/core": "0.1.0",
+    "@pactor-app/schema": "0.1.0",
+    "@pactor-app/expression": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/templates/app/README.md

@@ -0,0 +1,18 @@
+# __APP_NAME__
+
+由 `pactor create` 生成的 Pactor 业务工程：vite + react + @pactor-app/app + @pactor-app/ui + @pactor-app/vite-plugin。
+
+```bash
+pnpm install
+pnpm dev
+```
+
+- `src/pages/home.page.yaml`：示例 Page DSL，经 @pactor-app/vite-plugin 在构建期转换为 JS 模块
+- `src/main.tsx`：`createPactorApplication` + `StaticDslLoader`（本地 DSL 开发）；接入服务端后改用 `api: { baseURL: '/api/runtime' }`
+- 默认 UI kit 为 shadcn，`@pactor-app/ui/styles.css` 样式导入为必需步骤
+
+## 说明
+
+- 依赖版本为语义化占位（`^0.1.0` 等），请在 Pactor 发布后按实际版本对齐。
+- 如需 `*.page.yaml` 的 TypeScript 类型声明，按 @pactor-app/vite-plugin 文档添加 `src/dsl-modules.d.ts`。
+- 常用命令：`pactor validate src/pages/*.page.yaml`、`pactor lint src`、`pactor build src/pages -o dist/runtime`。

package/templates/app/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/app/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@pactor-app/app": "^0.1.0",
+    "@pactor-app/core": "^0.1.0",
+    "@pactor-app/resource": "^0.1.0",
+    "@pactor-app/ui": "^0.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@pactor-app/vite-plugin": "^0.1.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11"
+  }
+}

package/templates/app/src/main.tsx

@@ -0,0 +1,22 @@
+import { createPactorApplication } from '@pactor-app/app';
+import { StaticDslLoader } from '@pactor-app/resource';
+// 默认 UI kit 为 shadcn（@pactor-app/ui），样式表导入为必需步骤
+import '@pactor-app/ui/styles.css';
+
+import homePage from './pages/home.page.yaml';
+
+// 本地 DSL 开发：静态加载器直接喂入构建期 import 的页面；
+// 接入服务端后改回 api: { baseURL: '/api/runtime' }（HttpDslResourceLoader）
+const loader = new StaticDslLoader({
+  pages: { home: homePage },
+  bootstrap: {
+    app: { name: '__APP_NAME__' },
+    menus: [{ id: 'home', title: '首页', path: '/', pageId: 'home' }],
+    pageVersions: { home: 1 },
+  },
+});
+
+createPactorApplication({
+  appId: '__APP_NAME__',
+  loader,
+}).mount('#root');

package/templates/app/src/pages/home.page.yaml

@@ -0,0 +1,23 @@
+dsl: '1.0'
+page:
+  id: home
+  title: __APP_NAME__
+  type: custom
+state:
+  keyword: ''
+body:
+  type: Page
+  props:
+    title: __APP_NAME__
+  children:
+    - type: Alert
+      props:
+        type: info
+        message: 欢迎使用 Pactor！当前 keyword：${state.keyword}
+    - type: Card
+      props:
+        title: 示例卡片
+      children:
+        - type: Button
+          props:
+            text: 开始使用

package/templates/app/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}

package/templates/app/vite.config.ts

@@ -0,0 +1,7 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import pactor from '@pactor-app/vite-plugin';
+
+export default defineConfig({
+  plugins: [react(), pactor()],
+});