@tbox.cn/app-toolkit 0.1.0

package/src/core/module-schema.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+
+/**
+ * tbox.module.json schema v1（001 §3.6 字段名，003 §4.1 schema v1 定版）。
+ * app-toolkit 单一校验源（自 CLI module-schema.ts 迁入；CLI 经 re-export 消费）。
+ *
+ * 迁移改造（ai-build C2-5）：
+ * - resourceNeedContribSchema 的 type 由 `z.enum(RESOURCE_TYPE_IDS)` 放宽为 `z.string()`——
+ *   词汇校验移谓词、经 contracts 动态解析取 RESOURCE_TYPE_IDS（比静态 enum 更忠实应用版本）；
+ * - demand meta additive：serviceNeedContribSchema 增 title?/description?（服务展示元数据，
+ *   manifest demand 侧 additive 扩展，catalog 聚合顺带携带——api.md ServiceDemand 对齐）；
+ * - 安全钉子（H9b）：provider 名与 instance id 进凭据 stem 派生，字符集 pattern
+ *   `/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/` 为第一道防线（stem 派生处另有断言防线——纵深防御）。
+ */
+
+/** 输入字符集（安全钉子①）：provider 名 / instanceId 恒经此 pattern（进凭据 stem 派生的输入） */
+export const SAFE_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+const cardContribSchema = z.object({
+  cardType: z.string(),
+  schemaVersion: z.number().optional(),
+});
+
+export const pageContribSchema = z.object({
+  route: z.string(),
+  component: z.string(),
+});
+
+export const tabContribSchema = z.object({
+  route: z.string(),
+  label: z.string().optional(),
+  icon: z.string().optional(),
+  order: z.number().optional(),
+});
+
+export const moduleDependencySchema = z.object({
+  id: z.string(),
+  range: z.string().optional(),
+  required: z.boolean().default(true),
+});
+
+/** provider 供给槽声明（integrations v2：contributes.providers.slots 元素；
+ *  provider = 厂商名（catalog 嵌套第一轴）、implementation = 'id@version'（第二轴）） */
+export const providerSlotContribSchema = z.object({
+  service: z.string(),
+  provider: z.string().regex(SAFE_NAME_PATTERN, 'provider 名含非法字符（需 /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/）'),
+  implementation: z.string(),
+  credentialType: z.string(),
+  local: z.boolean().optional(),
+  configSchema: z.string().optional(),
+  credentialSchema: z.string().optional(),
+});
+
+/** 服务需求槽声明（contributes.services 元素；业务模块声明消费——catalog 需求侧聚合源） */
+export const serviceNeedContribSchema = z.object({
+  service: z.string(),
+  optional: z.boolean().default(true),
+  defaults: z
+    .array(
+      z.object({
+        provider: z.string().regex(SAFE_NAME_PATTERN, 'provider 名含非法字符（需 /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/）'),
+        implementation: z.string(),
+      }),
+    )
+    .default([]),
+  // demand meta additive（api.md ServiceDemand）：服务展示元数据，缺席 UI 回退 service id
+  title: z.string().optional(),
+  description: z.string().optional(),
+});
+
+/** 资源需求声明（contributes.resources 元素；type 放宽为 string——词汇校验移谓词经 resolver 取词表） */
+export const resourceNeedContribSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+});
+
+export const moduleDescriptorSchema = z
+  .object({
+    schemaVersion: z.number().default(1),
+    name: z.string(),
+    version: z.string().default('0.0.0'),
+    kind: z.enum(['platform', 'business', 'third-party']).default('business'),
+    risk: z
+      .object({
+        level: z.enum(['high', 'medium', 'low']).default('low'),
+        writeBoundary: z.enum(['sdk-enforced', 'source']).default('source'),
+      })
+      .default({}),
+    distribution: z
+      .object({
+        defaultMode: z.enum(['hybrid', 'sdk', 'codegen', 'local']).default('codegen'),
+      })
+      .default({}),
+    contributes: z
+      .object({
+        handlers: z.array(z.string()).default([]),
+        tools: z.array(z.string()).default([]),
+        cards: z.array(cardContribSchema).default([]),
+        routes: z.array(z.string()).default([]),
+        pages: z.array(pageContribSchema).default([]),
+        tabs: z.array(tabContribSchema).default([]),
+        providers: z
+          .object({
+            slots: z.array(providerSlotContribSchema).default([]),
+          })
+          .default({}),
+        services: z.array(serviceNeedContribSchema).default([]),
+        resources: z.array(resourceNeedContribSchema).default([]),
+      })
+      .default({}),
+    dependencies: z
+      .object({
+        modules: z.array(moduleDependencySchema).default([]),
+      })
+      .default({}),
+    env: z.array(z.string()).default([]),
+  })
+  .strict();
+
+export type ModuleDescriptor = z.infer<typeof moduleDescriptorSchema>;
+export type CardContrib = z.infer<typeof cardContribSchema>;
+export type ProviderSlotContrib = z.infer<typeof providerSlotContribSchema>;
+export type ServiceNeedContrib = z.infer<typeof serviceNeedContribSchema>;
+export type ResourceNeedContrib = z.infer<typeof resourceNeedContribSchema>;
+
+export type ParseModuleResult =
+  | { ok: true; value: ModuleDescriptor }
+  | { ok: false; errors: string[] };
+
+export function parseModuleDescriptor(raw: unknown): ParseModuleResult {
+  const result = moduleDescriptorSchema.safeParse(raw);
+  if (result.success) return { ok: true, value: result.data };
+  return {
+    ok: false,
+    errors: result.error.issues.map(
+      (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+    ),
+  };
+}

package/src/dto.ts

@@ -0,0 +1,298 @@
+/**
+ * DTO 全量（api.md §3 字段级单源落源——28 类型；演进 additive-only，铁律 #8）。
+ * agtcodingbox / tbox-ai-coding 经 `import type` 消费（L2 DTO 单源——API 层零类型镜像）。
+ * 词汇七概念：app / module / service / instance / provider / integration / resolution。
+ * 弃用词汇清单见 api.md §3 尾（component/slot/scope/configMode/…——防复活）。
+ */
+
+// ===== 词汇基线 =====
+
+/** contracts 求值五态原样（EffectiveServiceResolution.status） */
+export type ServiceStatus =
+  | 'ok'
+  | 'service-not-configured'
+  | 'instance-not-found'
+  | 'instance-disabled'
+  | 'binding-unresolved';
+
+/** 四配置层（instance 为 map 字段层） */
+export type BindingLayer = 'app' | 'module' | 'service' | 'instance';
+
+// ===== 需求轴（GET /modules · 静态）=====
+
+/** 纯模块清单（无 services——卡片展开走 /modules/:m） */
+export interface ModulesView {
+  modules: ModuleDeclaration[];
+}
+
+export interface ModuleDeclaration {
+  /** install id（packages/ 目录名 / .tbox/app.json entry.id） */
+  id: string;
+  /** 包名 */
+  name: string;
+  title: string;
+  description: string;
+}
+
+/** 服务需求声明（模块 demand 单元；defaults 唯一落位 ServiceDetail） */
+export interface ServiceDemand {
+  service: string;
+  /** manifest demand meta；缺席 UI 回退 service id */
+  title?: string;
+  description?: string;
+  /** demand optional !== false（多模块 OR 聚合见 resolution echo） */
+  required: boolean;
+}
+
+// ===== 静态单体视图 =====
+
+/** GET /modules/:module（模块静态一站式 · PUT 读对偶） */
+export interface ModuleDetailView {
+  /** domains[换算键] 节点原值；未配置 = null */
+  integration: ModuleIntegrationNode | null;
+  /** 本模块 demand（卡片展开 + 编辑器静态上下文自足） */
+  services: ServiceDemand[];
+}
+
+/** GET /app（应用静态视图：平台服务 + root 原值） */
+export interface AppView {
+  /** 平台服务 id（服务词汇 − 模块占用；owner/标题 UI 按首点段派生） */
+  services: string[];
+  /** root 节点原值；文件缺席 = null */
+  integration: AppIntegrationNode | null;
+}
+
+/** GET /services/:service（服务静态单体） */
+export interface ServiceDetail extends ServiceDemand {
+  /** manifest 预填（唯一落位） */
+  defaults: Array<{ provider: string; implementation: string }>;
+  /** 文件 services[s] 逐字原值（编辑预填源）；无声明 = null */
+  integration: ServiceIntegrationNode | null;
+  /** 供给该服务的厂商名单（catalog 静态切片——picker 数据源） */
+  suppliedBy: string[];
+}
+
+// ===== 求值轴 =====
+
+/** GET /service-resolutions（批量求值 · 唯一求值集合面） */
+export interface ServiceResolutionsView {
+  /** P6 contracts echo（仅求值轴两端点携带） */
+  contracts: ContractsResolution;
+  /** 键集 = 服务词汇 ∪ 已配置（模块/平台/孤儿全量） */
+  resolutions: Record<string, ServiceResolutionEntry>;
+  /** 谓词全量（doctor 同源；恒全量——subset 消费方客户端过滤） */
+  issues: IntegrationIssue[];
+}
+
+/** 求值摘要单元（行内嵌；P14 单一形状） */
+export interface ServiceResolutionEntry {
+  /** 默认实例口径（normalizeInstances 委托） */
+  status: ServiceStatus;
+  statusMessage?: string;
+  /** 最特异声明层厂商名（跨层事实） */
+  provider?: string;
+  /** provider 在场时在场：(provider, service) ∈ 供给关系 */
+  supplied?: boolean;
+  /** owner 模块 install id；平台服务/孤儿缺席 */
+  module?: string;
+  /** demand echo（OR 聚合）；平台/孤儿恒 false；集成就绪判定单源（§7） */
+  required?: boolean;
+}
+
+/** 求值完整结构（extends = 列表项 ⊂ 单体的编译期保证——P14） */
+export interface ServiceResolution extends ServiceResolutionEntry {
+  /** P4 枚举规则（全实例逐一；默认实例求值 = 摘要基，不重复头部） */
+  instances: ResolvedInstance[];
+  inheritance: Array<{ layer: BindingLayer; provider?: string; implementation?: string }>;
+}
+
+/** GET /service-resolutions/:service（求值单体） */
+export interface ServiceResolutionDetail {
+  contracts: ContractsResolution;
+  resolution: ServiceResolution;
+  /** service === :service 过滤子集 */
+  issues: IntegrationIssue[];
+}
+
+// ===== 集成节点（文件镜像 = PUT body）=====
+
+/** root 节点 */
+export interface AppIntegrationNode {
+  /** 恒字符串（app/module 级无内联形态） */
+  provider?: string;
+  config?: Record<string, unknown>;
+  configByInstance?: Record<string, Record<string, unknown>>;
+  credentialRef?: string;
+  credentialRefByInstance?: Record<string, string>;
+  /** 整组替换（id 字符集受输入约束①） */
+  instances?: Array<{ id: string; name: string; attributes?: Record<string, unknown> }>;
+  defaultInstanceId?: string | null;
+}
+
+/** AppIntegrationNode 键集单源（runtime const——write applyApp 全量替换白名单
+ *  （缺席根键删除；services/domains/modules 域不在其中）+ views/app 投影（GET 预填 ≡ PUT body，
+ *  D21/L1——文件含 services/domains 但 root 节点投影只含本键集）） */
+export const APP_INTEGRATION_NODE_KEYS = [
+  'provider',
+  'config',
+  'configByInstance',
+  'credentialRef',
+  'credentialRefByInstance',
+  'instances',
+  'defaultInstanceId',
+] as const;
+
+/** 模块域节点（恒字符串 provider——域层无凭据位，契约事实） */
+export interface ModuleIntegrationNode {
+  provider?: string;
+  config?: Record<string, unknown>;
+}
+
+/** services[s] 整节点 */
+export interface ServiceIntegrationNode {
+  /** 对象 = 自定义 API（仅槽级，P2） */
+  provider?: string | InlineVendorDeclaration;
+  /** 内联 provider 时必填 */
+  implementation?: string;
+  config?: Record<string, unknown>;
+  credentialRef?: string;
+  /** 键 = instanceId / '*'（随节点全量替换） */
+  instances?: Record<string, ServiceInstanceNode>;
+}
+
+/** services[s].instances[k] 节点 */
+export interface ServiceInstanceNode {
+  /** provider 恒字符串（内联仅槽级合法） */
+  provider?: string;
+  implementation?: string;
+  config?: Record<string, unknown>;
+  credentialRef?: string;
+  /** 缺省 true；false → instance-disabled */
+  enabled?: boolean;
+}
+
+export interface InlineVendorDeclaration {
+  provider: string;
+  credentialType: string;
+  configSchema?: string;
+}
+
+// ===== 凭据工件输入（唯一写侧扩展，不在文件节点内）=====
+
+export interface CredentialValues {
+  type: string;
+  values: Record<string, string>;
+}
+
+// ===== 解析产物条目 =====
+
+export interface ResolvedInstance {
+  /** 注册表 id；'*' = 通配 */
+  instanceId: string;
+  status: ServiceStatus;
+  /** 逐实例诊断（binding-unresolved 等直投） */
+  statusMessage?: string;
+  /** 该实例合并结果 */
+  effective?: EffectiveBinding;
+  /** 掩码回显 */
+  credential?: CredentialEcho;
+}
+
+// ===== 供给轴（静态）=====
+
+/** GET /providers：厂商基本信息 */
+export interface ProvidersView {
+  providers: ProviderEntry[];
+}
+
+export interface ProviderEntry {
+  provider: string;
+  /** Mock 旗标（provider 级聚合） */
+  local: boolean;
+  /** 供给声明来源包名 */
+  owner: string;
+}
+
+/** GET /providers/:provider：供给足迹 */
+export interface ProviderDetail {
+  provider: string;
+  local: boolean;
+  owner: string;
+  /** per (provider, service) 保真，同厂商异构合法；★ implementations 恒数组（H1——
+   *  多元素 = 升级窗口，UI 出 impl 选择器，PUT 显式钉版） */
+  services: Record<
+    string,
+    { implementations: Array<{ implementation: string; credentialType: string }> }
+  >;
+}
+
+/** GET /providers/:p/services/:s：表单 schema 唯一暴露面 */
+export interface ProviderServiceDetail {
+  provider: string;
+  service: string;
+  /** ★ 恒数组（通常 1） */
+  implementations: Array<{ implementation: string; credentialType: string }>;
+  /** 厂商集成该服务的表单 schema（integration 域专属） */
+  integrationSchemas: {
+    /** raw draft 2020-12 原文零转换；供给在场未声明 = null（mock 合法）；解析自默认 impl */
+    configSchema: object | null;
+    credentialSchema: object | null;
+  };
+}
+
+// ===== 通用 =====
+
+export interface EffectiveBinding {
+  /** custom 时 provider = 内联声明厂商名 */
+  provider: string;
+  implementation: string;
+  config?: Record<string, unknown>;
+  /** 'secret://{stem}' */
+  credentialRef?: string;
+  layer: BindingLayer;
+}
+
+/** GET 永无真值 */
+export interface CredentialEcho {
+  /** credentialType（manifest 对齐） */
+  type: string;
+  /** 'secret://{stem}' */
+  ref: string;
+  /** 'config/credentials/{stem}.json' */
+  file: string;
+  /** 前 2 字符 + '****'；≤4 字符全掩码；null = 缺字段 */
+  masked: Record<string, string | null>;
+}
+
+export interface ContractsResolution {
+  version: string | null;
+  evaluation: boolean;
+  strictValidation: boolean;
+  notes: string[];
+}
+
+/** 字段级真源 = 谓词结构化输出（H7） */
+export interface IntegrationIssue {
+  severity: 'error' | 'warning';
+  /** 枚举单源 = 谓词文件头检查族编号映射（additive-only） */
+  code: string;
+  message: string;
+  service?: string;
+  module?: string;
+  instance?: string;
+}
+
+// ===== 写响应（全族同型）=====
+
+export interface SaveResult {
+  /** no-diff / dryRun → false */
+  written: boolean;
+  /** 恒 false 当 dryRun / no-diff / 应用未运行（onApplied 协作点回填） */
+  restartScheduled: boolean;
+  /** 触碰文件清单（dryRun 恒 []） */
+  files: string[];
+  /** 凭据工件（0..n；dryRun = 将创建的工件——确定性 stem 派生预览） */
+  credentials: Array<{ stem: string; ref: string; overwrote: boolean }>;
+  /** 写后谓词复查全量（dryRun 假想态唯一暴露面；含 ORPHANED_CREDENTIAL 等） */
+  issues: IntegrationIssue[];
+}