@bovinphang/craft-common 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+[简体中文](CHANGELOG.zh-CN.md)
+
+Notable changes follow Keep a Changelog and Semantic Versioning. An **Unreleased** heading identifies prepared source, not an npm publication.
+
+## [2.0.0] - 2026-11-09
+
+### Added
+
+- Expand the shared catalog to 21 English/Simplified Chinese `cc-*` entries. TypeScript, Rust, Go, Java, Python, C and C++ have independent language foundations; Rust async, Go concurrency, Python async, Java runtime and native memory safety have focused entries. Tauri and Electron provide desktop adaptations.
+- Add bounded, read-only workspace inspection and task-scoped capability recommendations. Languages, application roles and framework evidence remain separate; discovery does not execute project code or install tools.
+- Add shared product lifecycle APIs for explicit planning sessions, 15-runtime target resolution, per-entry configuration ownership, cross-product locking and recoverable product/common transactions.
+- Add the sixth reusable method, engineering practices: eight core principles, 31 primary-source records with applicability limits, and local language/desktop decisions in 14 common entries. Guidance uses required/recommended/conditional levels and preserves project conventions.
+- Add isolated, paired behavior examples for seven languages and the IPC handler core. Preparation is explicit; missing tools, compilation failures and empty/skipped tests are distinguished from demonstrated behavior. GUI, signing, real databases and distributed guarantees are separate validation boundaries.
+
+### Changed
+
+- Keep common content authoritative in this package. Products generate complete bilingual snapshots, embedded methods and provenance locks from the same exact package version and bytes. Standalone skills retain their own references, examples and license.
+- Preserve frontend/backend product identities and adapters while sharing stable installation mechanics. No-Skill runtime references do not become native Skills or create shared Skill consumers.
+- Use the existing npm packer through `pnpm exec npm pack` for release archives: pnpm 12.4.1's pack command omits nested `pnpm-lock.yaml` files, even with an explicit files whitelist. Dependency management remains on pnpm 12.4.1.
+
+### Fixed
+
+- Replace seven-entry catalog reconstruction in method synchronization with bilingual preflight and incremental planning. Preserve all 21 entries, applicability, unknown fields and query bytes; support read-only checks and idempotent synchronization.
+- Reject invalid indexes, missing language resources, unsafe internal links and modified/unknown generated outputs before writing.
+- Retain the transaction recovery, Windows equivalent-path and fixed-line-ending repairs released in 1.0.1.
+
+## [1.0.1] - 2026-11-06
+
+### Fixed
+
+- Repair recovery of larger transaction journals, Windows equivalent-path handling and consistent line endings. Preserve modified or unknown files during recovery and shared-resource cleanup.
+
+## [1.0.0] - 2026-11-05
+
+### Added
+
+- Initial common package with seven shared methodology/diagram entries, bilingual resources, catalog/resource APIs and shared installation ownership, conflict detection and transaction recovery.

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,39 @@
+# 变更日志
+
+[English](CHANGELOG.md)
+
+采用 Keep a Changelog 分类和语义化版本。**未发布**表示源码已准备，不代表已上传 npm。
+
+## [2.0.0] - 2026-11-09
+
+### 新增
+
+- 公共目录扩展为21个英文/简体中文 `cc-*` 入口。TypeScript、Rust、Go、Java、Python、C、C++分别提供独立语言基础；另有Rust异步、Go并发、Python异步、Java运行时和原生内存安全专项，以及Tauri/Electron桌面适配。
+- 新增有界、只读的工程事实扫描和任务范围能力推荐。语言、应用角色和框架证据分别判断，不执行工程代码或安装工具。
+- 新增公共产品生命周期接口：显式规划会话、15宿主目标解析、配置条目所有权、跨产品锁，以及产品/公共资源可恢复事务。
+- 新增第六类通用方法“工程实践”：八项公共原则、31条带适用限制的一手来源，及14个公共入口的语言/桌面细则。采用required/recommended/conditional级别，尊重项目既有约定。
+- 新增七语言和IPC处理核心的隔离缺陷/修复配对案例。环境准备须显式执行，缺工具、编译失败、零用例及跳过与真实行为结果分开；GUI、签名、外部数据库和分布式保证另行验证。
+
+### 变更
+
+- 公共内容只在本包维护。产品从同一精确版本与字节生成完整双语快照、内嵌方法及来源锁；独立Skill保留自身参考、示例和许可证。
+- 产品身份和适配转换仍由前后端各自管理，稳定安装机制共同复用。无Skill宿主的参考资料不伪装为原生Skill，也不登记公共Skill消费者。
+- 发行归档使用现有npm打包器，通过`pnpm exec npm pack`执行；pnpm 12.4.1的pack会排除嵌套pnpm-lock.yaml，显式白名单也不能保留。依赖管理仍使用pnpm 12.4.1。
+
+### 修复
+
+- 方法同步由七项整表重建改为双语预检与增量规划，保留全部21入口、适用条件、未知字段与查询字节，支持只读检查及幂等同步。
+- 索引非法、语言资源缺失、内部链接不安全，以及生成目标被修改或存在未知内容时，在写入前拒绝。
+- 保留1.0.1已发布的事务恢复、Windows等价路径及固定换行修复。
+
+## [1.0.1] - 2026-11-06
+
+### 修复
+
+- 修复较大事务日志恢复、Windows等价路径及换行一致性；恢复和公共资源清理保留用户修改及未知文件。
+
+## [1.0.0] - 2026-11-05
+
+### 新增
+
+- 首个公共包，包含七个通用方法/图表入口、双语资源、目录/资源接口，以及共享安装所有权、冲突检查和事务恢复。

package/README.md

@@ -1,13 +1,27 @@
 # craft-common
 
-Craft AI Coding 的公共能力包，由 frontend-craft 和backend-craft 自动交付；用户无需手动安装第三个插件。
+Craft AI Coding 的公共能力包，由 frontend-craft 和 backend-craft 自动交付；用户无需手动安装第三个插件。
 
 公共能力使用 `cc-*` 标识。此仓库是公共 Skill、资源与方法的唯一维护来源，产品中的对应目录由固定版本生成并校验。
 
 开发要求 Node.js >=22 和 pnpm 12.4.1。使用 `pnpm install`、`pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build` 校验。
 
-提供可编辑 draw.io、结构化技术图表、源码核验、文档事实同步、诊断、行为保持重构和 TDD 七个公共入口，并包含对应的中英文内容及完整运行资源。
+提供 21 个双语公共入口：既有七个方法与图表入口、十二个跨领域语言入口，以及 Tauri/Electron 桌面专项。TypeScript、Rust、Go、Java、Python、C、C++ 可用于 UI、桌面核心、原生库、服务或 CLI；能力由工程证据和任务选择，不按产品名称限制语言。
 
-共享安装协议以真实 Skill 目标定位消费者，检查精确版本、语言和内容摘要，在事务中更新产品文件与公共账本；卸载保留其他消费者及用户修改。原生插件双产品去重需另外按 Runtime 验证。
+公共安装引擎统一十五宿主的路径、显式规划会话、共享配置所有权、跨产品配置锁及事务恢复。产品保留身份声明、历史清单编解码和内容转换。共享协议以真实 Skill 目标定位消费者，检查精确版本、语言和内容摘要；卸载保留其他消费者及用户修改。原生插件双产品去重需另外按 Runtime 验证。
 
 消费和维护约定见[消费指南](docs/consuming-common.md)。公共包和前端 3.0 的公开发布仍是独立发布步骤，仓库中的本地验证不代表 npm registry 已有可下载版本。
+
+[工程结构与维护入口](docs/consuming-common.md#工程结构与维护入口)说明公共源、方法同步和生成产物边界。frontend-craft 3.0.0 与 backend-craft 1.0.0 均精确依赖正式版本号 `2.0.0`，当前处于待发布阶段；公共包不提供独立 CLI。
+
+<!-- engineering-practices-20261108 -->
+
+## 分层工程实践
+
+公开企业经验和语言官方资料按“公共原则 → 语言 → 场景 → 验证证据”融入既有入口。公共八项原则、31条一手来源与适用限制由 [methods](methods/engineering-practices.md) 及其 [来源记录](methods/engineering-practices.sources.json) 唯一维护；不把企业内部偏好直接变为项目强制规则。14个公共入口增强，产品分别补8个前端及14个服务入口，总数仍为21/74/42。
+
+规则级别为required/recommended/conditional；项目兼容、安全及现有工具约定优先。每个增强入口的references/engineering-practices.md给出风险、条件、例外、正反示意和验证。代码/锁双语同字节，说明本地化；关联案例ID不证明该条全部语义。
+
+维护者显式运行`pnpm run verify:engineering`，缺工具按MISSING报告；`--prepare`才准备环境，Docker方式见脚本参数。八个公共案例覆盖七语言及IPC，另两例由产品拥有。真实运行、四组模型对照与结构完整性分别记录，均不代表GUI、数据库或分布式保证。
+
+[变更日志](CHANGELOG.zh-CN.md) · [English changelog](CHANGELOG.md) · [2.0.0发布步骤](docs/releases/2.0.0.md)。前端3.0.0、后端1.0.0继续保持未发布状态，发布本包不自动发布两产品。

package/dist/content/applicability.d.ts

@@ -0,0 +1,17 @@
+export declare const PROJECT_ROLES: readonly ["ui", "desktop-core", "native-library", "service", "cli", "unknown"];
+export declare const TASK_KINDS: readonly ["ui", "ipc", "native-memory", "api", "data", "build", "review"];
+export type ProjectRole = (typeof PROJECT_ROLES)[number];
+export type TaskKind = (typeof TASK_KINDS)[number];
+export interface CapabilityApplicability {
+    languages?: string[];
+    frameworks?: string[];
+    roles?: ProjectRole[];
+    taskKinds?: TaskKind[];
+}
+export interface CapabilityCandidate {
+    id: string;
+    sourcePackage: string;
+    applicability?: CapabilityApplicability;
+}
+/** Source identities come from the caller's verified catalog, never self-reported metadata. */
+export declare function readCapabilityCandidates(metadata: unknown, sources: Readonly<Record<string, string>>): CapabilityCandidate[];

package/dist/content/catalog.d.ts

@@ -1,4 +1,4 @@
 import type { ContentCatalog, InstallLanguage } from "./types.js";
-export type MethodName = "source-driven-development" | "doc-sync" | "debug" | "refactoring" | "tdd";
+export type MethodName = "source-driven-development" | "doc-sync" | "debug" | "refactoring" | "tdd" | "engineering-practices";
 export declare function readMethodResource(packageRoot: string, method: MethodName, language: InstallLanguage): Buffer;
 export declare function readContentCatalog(packageRoot: string, language: InstallLanguage): ContentCatalog;

package/dist/content/snapshot.d.ts

@@ -0,0 +1,32 @@
+import { type MethodName } from "./catalog.js";
+import type { ContentCatalog, InstallLanguage } from "./types.js";
+export interface CommonContentLock {
+    schemaVersion: 1;
+    packageName: "@bovinphang/craft-common";
+    packageVersion: string;
+    catalogs: Record<InstallLanguage, Omit<ContentCatalog, "root">>;
+    files: Array<{
+        relativePath: string;
+        hash: string;
+    }>;
+}
+export interface SnapshotDeclarations {
+    domainMethods: ReadonlyArray<{
+        target: string;
+        method: MethodName;
+    }>;
+    extraResources: ReadonlyArray<{
+        source: string;
+        target: string;
+    }>;
+    retiredIds: Readonly<Record<string, string>>;
+}
+export interface ProductSnapshotInput extends SnapshotDeclarations {
+    productRoot: string;
+    commonRoot: string;
+    check: boolean;
+}
+export declare function snapshotPath(root: string, relative: string): string;
+export declare const mixedIndex: (relative: string) => boolean;
+export declare function isSnapshotResource(relative: string, declarations: Pick<SnapshotDeclarations, "domainMethods" | "extraResources">): boolean;
+export declare function syncProductSnapshot(input: ProductSnapshotInput): void;

package/dist/index.d.ts

@@ -1,7 +1,25 @@
 export * from "./content/types.js";
+export * from "./content/applicability.js";
+export * from "./project/types.js";
+export * from "./project/evidence.js";
+export * from "./project/frameworks.js";
+export { inspectWorkspace } from "./project/discover.js";
+export * from "./content/snapshot.js";
 export { readContentCatalog, readMethodResource, type MethodName, } from "./content/catalog.js";
 export { collectSkillResources } from "./content/resources.js";
 export * from "./install/types.js";
+export * from "./install/product/types.js";
+export type { OwnedEntry } from "./install/product/shared-config/types.js";
+export { resolveRuntimeTargets, safeProductPath, productPathKey, type RuntimeTargetInput, type RuntimeTargets, } from "./install/product/paths.js";
+export { RUNTIME_DESCRIPTORS, type RuntimeId, } from "./install/product/runtime-descriptors.js";
+export { createInstallSession, type FileInstallSession, type InstallSession, type InstallSessionOptions, } from "./install/product/session.js";
+export { planConfigEntry, configEntryStatus, entryHash, hashBytes, validateConfigEntry, } from "./install/product/shared-config/index.js";
 export { resolveSharedIdentity } from "./install/identity.js";
+export { canonicalPath as canonicalProductPath } from "./install/identity.js";
+export { currentHash as currentProductHash } from "./install/planner.js";
+export { runProductLifecycle, type ProductLifecycleInput, type ProductInstallationSeed, } from "./install/product/lifecycle.js";
+export { withProductConfigurationLocks } from "./install/product/locks.js";
+export { executeProductPlan, recoverProductTransaction, type ProductTransactionInput, } from "./install/product/transaction.js";
 export { planSharedDeployment } from "./install/planner.js";
 export { executeSharedPlan, recoverSharedTransaction, } from "./install/transaction.js";
+export { recommendCapabilities, type CapabilityRecommendation, } from "./project/recommend.js";