@serveryyswys/opm 0.0.0-stage → 0.1.0

package/NOTICE

@@ -0,0 +1,15 @@
+@serveryyswys/opm
+Copyright 2026 serveryyswys
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# @serveryyswys/opm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 Operit 插件工程打成 `.toolpkg` 的构建器。**脱离 Operit 生态** —— 在普通的 Node 环境、
+普通的编辑器里就能用，不依赖 Operit 运行时，也不依赖 AI 编程环境。
+
+## 安装
+
+```bash
+npm i -D @serveryyswys/opm @serveryyswys/node.operit
+```
+
+两个都要装：`opm` 是构建器本身，`node.operit` 提供 `BUILTINS.json` 契约表 ——
+重写规则的**唯一真源**，opm 不自带副本（副本一定会过期，而过期的契约会把构建带偏）。
+
+## 用法
+
+### 先把工程准备起来（可选，但推荐）
+
+```bash
+opm init                      # 在当前目录
+opm init ./my-plugin          # 或指定目录
+opm init --no-install         # 只写文件，不跑 npm install
+```
+
+它只管三件最容易写错的事：
+
+1. `package.json` 补上 `scripts.build = "opm build"`，以及 `@serveryyswys/opm` /
+   `@serveryyswys/node.operit` 两个 devDependency（**不覆盖**已有值）；
+2. 没有 `manifest.json` 就生成一个骨架（toolpkg 的身份靠它；`toolpkg_id` 记得改成你自己的）；
+3. 工程里有 `.ts` 才补 `tsconfig.json`，且 `outDir` 与 `manifest.main` 对齐。
+
+默认会跑一次 `npm install`。**不指定 registry** —— 包从哪个源来，由你自己的 npm 配置决定
+（用私有源的团队，装的就是私有源里的 `node.operit`）。
+
+### 然后构建
+
+两种完全等价：
+
+```bash
+opm build                      # 直接调
+```
+
+```json
+// 工程的 package.json
+"scripts": { "build": "opm build" }
+```
+
+```bash
+npm run build                  # npm 会把 node_modules/.bin/opm 放进 PATH
+```
+
+其他命令：
+
+```bash
+opm build [项目目录] --out <名字> --dry-run [--no-install]
+opm verify [项目目录] [--no-install]          # 出包前干跑校验，**不写任何文件**
+opm version [项目目录]                        # 列版本：opm / 工程 / node.operit / toolpkg
+opm help
+```
+
+`verify` 与 `build` 跑同一条流水线，区别是**完全不落盘**，所以适合放进 CI 当门禁。
+它检查：manifest 字段（含 toolpkg_id 是否还是 `com.example.` 占位）、子包入口、
+依赖与裸名归宿、资产齐全度，并给出归档文件数／体积／引入的包／node.operit 版本。
+
+项目目录默认为当前目录。产物放在**项目目录的上一级**，名为 `<项目目录名>.toolpkg`。
+
+## 它做什么
+
+0. **补齐依赖**：`dependencies` 里声明了却没装的包，以及 `node.operit` 本身，先跑一次
+   `npm install`（同样不指定 registry）。缺依赖硬做的结果是一句"解析不到"，
+   对使用者没有指导性。要跳过自动安装用 `--no-install`（它会明确告诉你缺什么）。
+1. 读 `manifest.json`，取可达种子：`main` + 每个 `subpackages[].entry`
+2. 顺 `require` 链递归收集被引用的文件（**可达性裁剪** —— 只有真被引用到的才进包）
+3. **裸名重写**为归档内的显式 `.js` 相对路径
+4. **契约拦截**：`planned` / `unsupported` 的依赖直接让构建失败，不把问题带到运行期
+5. 入口注入 `process` / `Buffer` 全局（Operit 沙盒没有这两个全局）
+6. 压成 zip，写 `.toolpkg`
+
+### 哪些文件会进包
+
+| 类别 | 处理 |
+| --- | --- |
+| `manifest.json` | 原样 |
+| **JS**（入口 / 子包 / UI / 依赖） | 顺 `require` 链裁剪 + 裸名重写；**不可达的 JS 是死代码，不带** |
+| `resources/` `i18n/` `modules/` | **无条件整目录保留**，即使里面是 `.js` |
+| 其它非 JS 文件 | 原样带上（运行期数据，静态追不出来） |
+| 工程元数据（`package.json`/`tsconfig.json`/`.npmrc`…）与打包产物（`*.tgz`/`*.zip`） | 不带 |
+
+> 为什么要专门列这条：这三个规范目录**不在 require 链里**。只按 require 收集会把插件的
+> logo、多语言文件、WASM 模块**静默丢掉**且不报错。`i18n/*.js` 尤其容易被"不可达 JS 裁剪"
+> 误伤 —— 它是被 i18n 机制加载的**数据**，不是 require 出来的模块。
+
+### 裸名重写的三条规则
+
+| 请求 | 重写为 |
+| --- | --- |
+| `lodash` / `uuid` / `axios` | **保持原样**（运行时已内建） |
+| Node 内建（`path`、`fs`…） | `<rel>/node_modules/@serveryyswys/node.operit/dist/<subpath>.js` |
+| 第三方 npm 包 | 该包入口文件（解析 `main` / `exports`），归档内相对路径 |
+
+**为什么必须显式带 `.js`**：Operit 运行时的 `buildCandidatePaths` 对命中 `/\.[a-z0-9]+$/i` 的名字
+只试一个候选、不补扩展名。包名里的 `.operit` 正好命中那个正则，所以 `.../node.operit` 会被当成
+完整路径而解析失败 —— 必须写成 `.../node.operit/dist/index.js`。
+
+## 归档结构
+
+`.toolpkg` 就是 zip，**文件直接放在归档根**（没有顶层目录），路径完全照 `manifest.json` 里写的来：
+
+```
+manifest.json
+main.js
+ui/xxx/index.ui.js
+packages/*.js
+node_modules/<被引用到的包>/**/*.js
+node_modules/@serveryyswys/node.operit/dist/**/*.js
+```
+
+## 与 Operit 内那个 OPM 的关系
+
+Operit 生态里也有一个 OPM（`com.operit.serveryyswys.opm`，ToolPkg 形态），提供
+init / search / install / remove / manager / build / verify 七个工具。
+
+本包是其中 **`build` / `version` 的"脱离 Operit"版本**：同样一条流水线、
+同样读 `node.operit` 的契约表，但宿主是普通 Node（`fs` / `child_process`），
+没有 `Tools.*` 依赖，因此可以在传统开发环境里跑。
+
+## 许可
+
+Apache-2.0。见 `LICENSE` 与 `NOTICE`。

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * opm 命令行入口。
+ *
+ * 两种用法等价：
+ *   opm build            —— 直接调
+ *   npm run build        —— 工程的 package.json 里写 "build": "opm build"
+ *                           （npm 会把 node_modules/.bin/opm 放进 PATH）
+ *
+ * 失败一律走 process.exitCode，不调 process.exit()：后者会和 stdout 刷新竞态，
+ * 把最后的报错截掉（node.operit 上踩过这个坑）。
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const build_1 = require("./lib/build");
+const version_1 = require("./lib/version");
+const init_1 = require("./lib/init");
+const verify_1 = require("./lib/verify");
+function ownVersion() {
+    try {
+        const manifest = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function usage() {
+    return [
+        '@serveryyswys/opm ' + ownVersion() + ' —— 把 Operit 插件工程打成 .toolpkg',
+        '',
+        '用法：',
+        '  opm init [项目目录] [--no-install] [--overwrite]',
+        '      把工程准备到能 build：补 scripts.build 与依赖声明、生成 manifest.json 骨架、',
+        '      TS 工程补 tsconfig.json。默认跑一次 npm install（不指定 registry，走你自己的 npm 源）。',
+        '',
+        '  opm build [项目目录] [--out <名字>] [--dry-run] [--no-install]',
+        '      计算可达性、重写裸名、拦截不支持的依赖，压成 .toolpkg',
+        '      产物放在项目目录的上一级，名为 <项目目录名>.toolpkg',
+        '',
+        '  opm verify [项目目录] [--no-install]',
+        '      出包前干跑校验：manifest 字段、入口、依赖、裸名归宿、资产齐全度、统计。',
+        '      **完全不写文件**，所以可以在 CI 里当门禁用。',
+        '',
+        '  opm version [项目目录]',
+        '      列出版本：opm 自身、目标工程、node.operit、toolpkg manifest',
+        '',
+        '  opm help | --version',
+        '',
+        '项目目录默认为当前目录。构建需要项目里已安装 @serveryyswys/node.operit —— ',
+        '它的 BUILTINS.json 是重写规则的唯一真源。'
+    ].join('\n');
+}
+function parseArgs(argv) {
+    const positional = [];
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg.startsWith('--')) {
+            const name = arg.slice(2);
+            const next = argv[index + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                flags.set(name, next);
+                index += 1;
+            }
+            else {
+                flags.set(name, 'true');
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags };
+}
+function main(argv) {
+    const command = argv[0];
+    const { positional, flags } = parseArgs(argv.slice(1));
+    if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+        console.log(usage());
+        return 0;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(ownVersion());
+        return 0;
+    }
+    if (command === 'init') {
+        const projectDir = (0, node_path_1.resolve)(positional[0] === undefined ? process.cwd() : positional[0]);
+        const result = (0, init_1.initProject)({
+            projectDir,
+            install: !flags.has('no-install'),
+            overwrite: flags.has('overwrite')
+        });
+        for (const item of result.created) {
+            console.log('  + ' + item);
+        }
+        for (const item of result.updated) {
+            console.log('  ~ ' + item);
+        }
+        for (const item of result.unchanged) {
+            console.log('  = ' + item + '（已存在，未改动）');
+        }
+        for (const note of result.notes) {
+            console.log('  · ' + note);
+        }
+        if (!result.ok) {
+            console.error('');
+            console.error('init 未能完成：');
+            for (const error of result.errors) {
+                console.error('  ✗ ' + error);
+            }
+            return 1;
+        }
+        console.log('');
+        console.log('下一步：');
+        for (const step of result.nextSteps) {
+            console.log('  ' + step);
+        }
+        return 0;
+    }
+    if (command === 'build') {
+        const projectDir = (0, node_path_1.resolve)(positional[0] === undefined ? process.cwd() : positional[0]);
+        const result = (0, build_1.buildProject)({
+            projectDir,
+            outName: flags.get('out'),
+            dryRun: flags.has('dry-run'),
+            install: !flags.has('no-install')
+        });
+        for (const note of result.notes) {
+            console.log('  · ' + note);
+        }
+        if (result.diagnostics.length > 0) {
+            const byKind = new Map();
+            for (const item of result.diagnostics) {
+                byKind.set(item.kind, (byKind.get(item.kind) ?? 0) + 1);
+            }
+            const summary = Array.from(byKind.entries()).map(([kind, count]) => kind + ' ' + count).join(' / ');
+            console.log('  重写 ' + result.diagnostics.length + ' 处（' + summary + '）');
+        }
+        if (!result.ok) {
+            console.error('');
+            console.error('构建失败（' + result.errors.length + ' 个问题）：');
+            for (const error of result.errors) {
+                console.error('  ✗ ' + error);
+            }
+            return 1;
+        }
+        console.log('');
+        console.log('✓ 已打包 ' + result.fileCount + ' 个文件');
+        console.log('  ' + result.toolpkgPath);
+        return 0;
+    }
+    if (command === 'verify') {
+        const projectDir = (0, node_path_1.resolve)(positional[0] === undefined ? process.cwd() : positional[0]);
+        const report = (0, verify_1.verifyProject)({ projectDir, install: !flags.has('no-install') });
+        console.log('检查项：');
+        for (const check of report.checks) {
+            console.log('  ' + (check.ok ? '✓' : '✗') + ' ' + check.name + ' —— ' + check.detail);
+        }
+        const stats = report.stats;
+        console.log('');
+        console.log('统计：');
+        console.log('  归档文件   ' + stats.archiveFiles + ' 个（其中资产 ' + stats.assets + ' 个），共 ' + stats.totalBytes + ' 字节');
+        console.log('  重写      内建 ' + stats.builtin + ' / npm 包 ' + stats.package + ' / 相对 ' + stats.relative + ' / 保持原样 ' + stats.untouched);
+        console.log('  引入的包  ' + (stats.packages.length === 0 ? '（无）' : stats.packages.join(', ')));
+        console.log('  node.operit ' + stats.nodeOperitVersion);
+        for (const note of report.notes) {
+            console.log('  · ' + note);
+        }
+        for (const warning of report.warnings) {
+            console.log('  ! ' + warning);
+        }
+        if (!report.ok) {
+            console.error('');
+            console.error('校验未通过（' + report.errors.length + ' 个问题）：');
+            for (const error of report.errors) {
+                console.error('  ✗ ' + error);
+            }
+            return 1;
+        }
+        console.log('');
+        console.log('✓ 校验通过（未写任何文件）');
+        return 0;
+    }
+    if (command === 'version') {
+        const report = (0, version_1.describeVersions)(positional[0], ownVersion());
+        for (const line of report.lines) {
+            console.log(line);
+        }
+        for (const error of report.errors) {
+            console.error('  ! ' + error);
+        }
+        return report.errors.length > 0 ? 1 : 0;
+    }
+    console.error('未知命令：' + command);
+    console.error('');
+    console.error(usage());
+    return 1;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 库入口：给想在 Node 里直接调用（不走命令行）的场景。
+ */
+export { buildProject } from './lib/build';
+export type { BuildOptions, BuildResult } from './lib/build';
+export { describeVersions } from './lib/version';
+export { verifyProject } from './lib/verify';
+export type { VerifyReport, VerifyCheck, VerifyStats } from './lib/verify';
+export { initProject, OPM_PACKAGE } from './lib/init';
+export type { InitOptions, InitResult } from './lib/init';
+export { auditDependencies, installDependencies } from './lib/dependencies';
+export type { DependencyAudit } from './lib/dependencies';
+export type { VersionReport } from './lib/version';
+export { createZip, readZip } from './lib/zip';
+export type { ZipEntry } from './lib/zip';
+export { findRequires } from './lib/js-requires';
+export type { RequireSite } from './lib/js-requires';
+export { findNodeOperitDir, loadContract, NODE_OPERIT_DIR, NODE_OPERIT_PACKAGE, RUNTIME_BUILTINS } from './lib/contract';
+export type { Contract, BuiltinEntry, BuiltinStatus } from './lib/contract';
+export { rewriteModule, resolveRelative } from './lib/rewrite';
+export type { Diagnostic, RewriteEnv, RewriteOutcome } from './lib/rewrite';

package/dist/index.js

@@ -0,0 +1,32 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRelative = exports.rewriteModule = exports.RUNTIME_BUILTINS = exports.NODE_OPERIT_PACKAGE = exports.NODE_OPERIT_DIR = exports.loadContract = exports.findNodeOperitDir = exports.findRequires = exports.readZip = exports.createZip = exports.installDependencies = exports.auditDependencies = exports.OPM_PACKAGE = exports.initProject = exports.verifyProject = exports.describeVersions = exports.buildProject = void 0;
+/**
+ * 库入口：给想在 Node 里直接调用（不走命令行）的场景。
+ */
+var build_1 = require("./lib/build");
+Object.defineProperty(exports, "buildProject", { enumerable: true, get: function () { return build_1.buildProject; } });
+var version_1 = require("./lib/version");
+Object.defineProperty(exports, "describeVersions", { enumerable: true, get: function () { return version_1.describeVersions; } });
+var verify_1 = require("./lib/verify");
+Object.defineProperty(exports, "verifyProject", { enumerable: true, get: function () { return verify_1.verifyProject; } });
+var init_1 = require("./lib/init");
+Object.defineProperty(exports, "initProject", { enumerable: true, get: function () { return init_1.initProject; } });
+Object.defineProperty(exports, "OPM_PACKAGE", { enumerable: true, get: function () { return init_1.OPM_PACKAGE; } });
+var dependencies_1 = require("./lib/dependencies");
+Object.defineProperty(exports, "auditDependencies", { enumerable: true, get: function () { return dependencies_1.auditDependencies; } });
+Object.defineProperty(exports, "installDependencies", { enumerable: true, get: function () { return dependencies_1.installDependencies; } });
+var zip_1 = require("./lib/zip");
+Object.defineProperty(exports, "createZip", { enumerable: true, get: function () { return zip_1.createZip; } });
+Object.defineProperty(exports, "readZip", { enumerable: true, get: function () { return zip_1.readZip; } });
+var js_requires_1 = require("./lib/js-requires");
+Object.defineProperty(exports, "findRequires", { enumerable: true, get: function () { return js_requires_1.findRequires; } });
+var contract_1 = require("./lib/contract");
+Object.defineProperty(exports, "findNodeOperitDir", { enumerable: true, get: function () { return contract_1.findNodeOperitDir; } });
+Object.defineProperty(exports, "loadContract", { enumerable: true, get: function () { return contract_1.loadContract; } });
+Object.defineProperty(exports, "NODE_OPERIT_DIR", { enumerable: true, get: function () { return contract_1.NODE_OPERIT_DIR; } });
+Object.defineProperty(exports, "NODE_OPERIT_PACKAGE", { enumerable: true, get: function () { return contract_1.NODE_OPERIT_PACKAGE; } });
+Object.defineProperty(exports, "RUNTIME_BUILTINS", { enumerable: true, get: function () { return contract_1.RUNTIME_BUILTINS; } });
+var rewrite_1 = require("./lib/rewrite");
+Object.defineProperty(exports, "rewriteModule", { enumerable: true, get: function () { return rewrite_1.rewriteModule; } });
+Object.defineProperty(exports, "resolveRelative", { enumerable: true, get: function () { return rewrite_1.resolveRelative; } });

package/dist/lib/build.d.ts

@@ -0,0 +1,25 @@
+import { Diagnostic } from './rewrite';
+export interface BuildOptions {
+    projectDir: string;
+    /** 产物名（不含 .toolpkg），默认取项目目录名 */
+    outName?: string;
+    /** 只分析不产包 */
+    dryRun?: boolean;
+    /** 缺依赖时是否自动 npm install（默认 true；--no-install 关掉） */
+    install?: boolean;
+}
+export interface BuildResult {
+    ok: boolean;
+    toolpkgPath: string;
+    fileCount: number;
+    /** 会进归档的归档路径清单 */
+    files: string[];
+    /** 这些文件的正文总字节数（未压缩） */
+    totalBytes: number;
+    /** 原样带上的非 JS 资产（归档路径） */
+    assets: string[];
+    diagnostics: Diagnostic[];
+    errors: string[];
+    notes: string[];
+}
+export declare function buildProject(options: BuildOptions): BuildResult;