transone-cli 0.6.3 → 0.10.0

package/README.md

@@ -20,20 +20,23 @@ Requires Bun >= 1.3.0.
 ```text
 Usage:
   transone create
-  transone dev [--host <host>] [--port <port>] [--base <path>] [--no-watch]
+  transone dev [--target <web|web-mobile|web-pc>] [--host <host>] [--port <port>] [--base <path>] [--no-watch]
   transone build [--target <target>] [--out-dir <path>] [--base <path>] [--library]
 
-Targets: web, mp-weixin, mp-alipay, mp-bytedance, mp-xiaohongshu, app-ios, app-android, app-harmony (default: web)
+Targets: web, web-mobile, web-pc, miniprogram-weixin, miniprogram-alipay, miniprogram-bytedance, miniprogram-xiaohongshu, app-ios, app-android, app-harmony
+Legacy mp-* / app-* aliases remain supported (default: web).
 ```
 
 ### `transone create`
 
-Scaffolds a new TransOne project in the current directory (refuses to overwrite existing project files).
+Scaffolds a new TransOne project with a shared Card business component and generic Web, mini-program and App implementations, plus mobile, PC, Weixin, Alipay, iOS and Android implementations. The page references only `CardComponent`; the compiler selects a subclass. The generated scripts cover all ten platforms. Existing template files, including nested component files, are protected from overwriting.
 
 ### `transone dev`
 
 Starts the development server (Web target only) with optional watch mode (`--no-watch` to disable), custom `--host` / `--port`, and a `--base` path.
 
+`--target web-mobile` and `--target web-pc` choose the implementation marked by `@WebMobile()` / `@WebPc()`. Framework `Platform` values and decorators are shared with the CLI. `target` in configuration sets a default; command options take priority. Legacy `mp-*` target names remain aliases for canonical `miniprogram-*` values; `app-*` names are canonical values.
+
 Development bundles are written to `dist/dev/h5/<session>/<generation>`. After a successful rebuild, superseded generations and their resource URLs are removed after a five-second grace period; an in-flight page render delays that period until it finishes. Failed builds discard their temporary output and keep the last successful bundle. Stopping or restarting the server cleans up its own session directory.
 
 ### `transone build`
@@ -52,6 +55,12 @@ transone build --target mp-xiaohongshu # Xiaohongshu mini-program project (XHSML
 - `--base` sets the deployment base path (e.g. a GitHub Pages sub-path).
 - `--library` builds in library mode (no page entry required).
 
+Web `dev` and `build` emit fixed component `initStyles()` rules that can be resolved safely and document styles as static CSS files, loaded through `<link rel="stylesheet">`. Component extraction supports literal values and immutable module constants, including hover, media queries and rpx conversion. Methods that depend on props/state, mutate their style manager later, or contain unsupported statements keep runtime styling. When selectors or inheritance cannot be resolved safely, the bundle retains runtime component styling. Identified document `<style>` elements and sheets with relative resource URLs stay inline to preserve their behavior. Use component-specific selectors: extracted rules are available before component mount and follow a stable source-file order.
+
+Web production entry and chunk JavaScript filenames contain a content hash (for example `main-<hash>.js`); HTML references the emitted filenames. Unchanged content keeps its hash. Mini-program and library entry filenames follow their existing platform/package contracts.
+
+Platform selection uses real class identities, follows inheritance and preserves parent-module constants/helpers. Only the selected implementation and shared dependencies enter an application bundle. Exact platform matches win, followed by the matching `@Web()`, `@Miniprogram()` or `@App()` family implementation, then a concrete business base; conflicting implementations or a consumed abstract base without a match fail explicitly. Generic mini-program and App markers are not standalone build targets; specify a concrete platform. `components.include` / `exclude` extend source discovery. See the [component implementation guide](../../docs/platform-components.md) for enum/decorator mappings, native static composition limits and explicit implementation references.
+
 The iOS, Android, and Harmony native app targets are implemented. A generated project should still be opened in its platform IDE for runtime/device validation.
 
 ## Targets
@@ -176,3 +185,11 @@ Native app builds write `{ host }` to `transone.config.json` in the platform res
 Native request compilation is not yet supported; this file is configuration for future integration.
 
 Weixin builds default to `lazyCodeLoading: "requiredComponents"` in `app.json` (component injection on demand). Override it through `mp.appExtra.lazyCodeLoading` or the platform-specific `appExtra`.
+
+## Component diagnostics and recoverable output
+
+Run `transone build --target web-pc --report-components` to print discovered logical-component mappings, source locations, exact/family/base/missing reasons, and candidates. This is a static mapping report, not runtime reachability analysis; it cannot be combined with `--library`.
+Use `reportComponents(options)` and `formatComponentSelectionReport(report)` from `transone-cli` for structured data and text without evaluating component modules or writing build output.
+
+Web, Mini Program, App and library builds complete their staging output before replacing the destination. Failures preserve previous output, publication failures attempt rollback, and cleanup only removes paths owned by that build.
+See the [diagnostics and cleanup guide](../../docs/reliability.md).

package/README.zh-CN.md

@@ -21,12 +21,35 @@ app-*          原生应用代码生成（app-ios / app-android / app-harmony，
 
 ```bash
 transone build --target web           # 产出 H5 站点
+transone build --target web-mobile    # 选择 @WebMobile() 实现
+transone build --target web-pc        # 选择 @WebPc() 实现
+transone build --target miniprogram-weixin # 选择 @MiniprogramWeixin() 实现
+transone build --target app-ios       # 选择 @AppIos()，生成原生工程
 transone build --target mp-weixin     # 生成微信小程序原生工程
 transone build --target mp-xiaohongshu # 生成小红书小程序原生工程（XHSML / CSS）
 transone dev                          # 开发服务（仅 web）
+transone dev --target web-mobile       # 移动 Web 开发服务
 transone create                       # 脚手架
 ```
 
+框架 `Platform` 枚举与装饰器为端定义的唯一来源。配置可使用 `target: Platform.WebMobile`，
+命令参数优先；旧的 `mp-*`、`app-*` 命令和平台配置键继续兼容。
+`web-mobile`、`web-pc` 默认分别输出到 `dist/build/web-mobile`、`dist/build/web-pc`。
+
+业务组件 `CardComponent extends BaseComponent` 提供共享状态和方法，端类继承它并使用
+`@WebMobile()`、`@WebPc()`、`@MiniprogramWeixin()`、`@AppIos()` 等装饰器。
+页面只引用 CardComponent。精确端优先，再回退同族通用实现 `@Web()` / `@Miniprogram()` / `@App()`，最后回退可实例化基类；
+冲突和已使用的抽象基类缺少实现时明确报错。通用小程序和 App 层不是独立构建目标，仍需指定微信、iOS 等具体端。
+默认扫描 src 的 TS/TSX，`components.include` / `exclude` 可调整源码范围。
+
+`transone create` 生成共享 Card、三类通用实现和六个具体端实现、配置及脚本，保留任一模板文件已存在即拒绝覆盖的保护。
+需要框架 0.5.0 与 CLI 0.8.0。完整枚举、继承、显式引用和原生静态子集见
+[业务组件与端实现](../../docs/platform-components.md)。
+
+Web 的 `dev`、`build` 会将可安全静态确定的组件 `initStyles()` 样式与文档样式输出为静态 CSS，通过 `<link rel="stylesheet">` 加载。组件提取支持字面量、不可变模块常量、hover、media 与 rpx 换算；依赖 props/state、后续修改 StyleManager 或含不支持语句的方法继续在运行时处理。无法安全确定选择器或跨模块继承关系时，当前 bundle 的组件样式保留在运行时。带标识的文档 `<style>` 和含相对资源 URL 的样式保留内联，以维持原有行为。组件应使用专属选择器：提取的规则在挂载前就已生效，并按稳定的源文件顺序排列。
+
+Web 生产入口与分块 JS 文件名包含内容 hash，例如 `main-<hash>.js`，HTML 自动引用实际文件名；内容不变时 hash 不变。小程序及库入口保留平台与包约定的文件名。
+
 ```bash
 bun test          # 测试
 bun run build     # 构建 dist（CLI bundle + .d.ts）
@@ -48,3 +71,11 @@ bun run --cwd playground/counter build:xiaohongshu
 - 在线文档（CLI 子站）：<https://geektech-team.github.io/transone/cli/>
 - 主文档站：<https://geektech-team.github.io/transone/>
 - 仓库：<https://github.com/geektech-team/transone>
+
+## 组件诊断与输出恢复
+
+`transone build --target web-pc --report-components` 输出静态组件选择报告，包含来源位置、精确匹配/通用平台族/基类回退以及候选实现。报告覆盖发现的逻辑组件，不代表运行时可达性，不与 `--library` 组合。
+CLI 包的 `reportComponents(options)` 可单独读取结构化报告，`formatComponentSelectionReport(report)` 提供文本格式；只读检查不会执行组件模块或写入产物。
+
+Web、小程序、App 与库构建在临时目录完整生成成功后再切换输出。失败保留旧产物，切换失败尝试回滚；只清理本次拥有的工作目录。
+详见[诊断与清理](../../docs/reliability.md)。

package/dist/app/analyze.d.ts

@@ -1,2 +1,3 @@
+import type { ResolvedConfig } from '../types';
 import type { NativeScreen } from './types';
-export declare function analyzeNativeScreen(entry: string): Promise<NativeScreen>;
+export declare function analyzeNativeScreen(entry: string, config?: ResolvedConfig, onSourcePaths?: (paths: readonly string[]) => void): Promise<NativeScreen>;

package/dist/app/components.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedConfig } from '../types';
+import type { NativeScreen } from './types';
+/** Returns undefined only for the legacy plain-class fixture format. */
+export declare function composeNativeScreen(entry: string, config: ResolvedConfig, onSourcePaths?: (paths: readonly string[]) => void): NativeScreen | undefined;

package/dist/app/types.d.ts

@@ -24,6 +24,9 @@ export type NativeTextPart = {
     key: string;
 };
 export type NativeAction = {
+    kind: 'sequence';
+    actions: NativeAction[];
+} | {
     kind: 'increment';
     key: string;
     by: number;