@mjh-odoo/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @mjh-odoo/cli
 
-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.
+跨平台 Odoo 20 开发管理 CLI，命令名为 `odoo`。用于 mjh-odoo 社区版 base 及基于它建立的项目。
+
+## 安装
+
+需要 Node.js 24+、Docker Engine/Desktop、Docker Compose 和 Buildx。Windows 可在 PowerShell 中使用，无需 Make 或 Bash。Odoo/Python/PostgreSQL 在容器内运行。
+
+```sh
+npm install -g @mjh-odoo/cli
+odoo --help
+odoo --version
+```
+
+CLI 不附带 Odoo 源码，也不会创建完整项目。现阶段需先准备兼容的 base 仓库：根目录包含 `.env.example`、`compose.yaml`、`odoo/`、`addons/`、`scripts/runtime.py`、`scripts/backup_utils.py` 和 `config/`。Base 当前独立验收，尚未公开发布。
+
+进入项目后运行：
+
+```sh
+odoo init
+odoo doctor
+odoo up
+odoo status
+```
+
+从子目录运行也能找到项目。指定其他目录时，全局参数放在命令前：
+
+```sh
+odoo --project /path/to/erp status --json
+# Windows
+odoo --project "C:\Code\my-erp" status
+```
+
+## 常用命令
+
+```sh
+odoo up                              # 构建开发镜像并后台启动，等待健康
+odoo up --no-build --pull never       # 使用已有镜像离线启动
+odoo restart                         # 重启 Odoo
+odoo restart all                      # 重启 Odoo 和数据库
+odoo down                            # 停止并移除容器，保留持久卷
+odoo down -v --dry-run                # 预览本项目卷删除操作
+odoo down -v                         # 删除本项目数据库和附件卷
+odoo build --pull                    # 构建当前 Compose 开发镜像
+odoo config                          # 脱敏配置和默认存档目录
+
+odoo module list --json
+odoo module install module_a module_b
+odoo module update module_a module_b
+odoo module update --all              # 已安装的项目扩展，不含官方核心
+odoo module update module_a -d test_db --no-restart
+
+odoo db list --json
+odoo db backup
+odoo db backup -d odoo --file ./before-sale.zip
+odoo db restore --file ./before-sale.zip -d sale_test
+odoo db restore --file ./before-sale.zip -d sale_test --force
+
+odoo logs
+odoo logs all --since 10m --level error --context 3 --json
+odoo logs odoo --match sale_module --tail 1000
+odoo logs all --since 30m --json --file .local/logs/diagnostic.json
+odoo logs -f
+
+odoo image build --help
+odoo image build --platform amd64 --file ./runtime-amd64.tar
+odoo image build --platform amd64,arm64 --tag registry.example/team/runtime:v1 --push
+odoo image build --target production --tag my-erp:v1
+
+odoo exec -- --version                # 容器内官方 Odoo CLI
+odoo exec -- --help
+odoo exec -- shell -c /etc/odoo/odoo.conf
+odoo help exec                        # 查看管理工具的转发说明
+```
+
+每个命令支持 `--help`，官方命令转发 `exec` 的说明使用 `odoo help exec`。
+
+## 配置与数据
+
+项目使用 `.env + compose.yaml + config/`。`init` 只在缺少 `.env` 时生成独立项目身份、可用端口和随机密码；重复运行保留已有文件。不同代码目录（包括 Git 工作树）默认使用不同身份、端口和数据卷。手动复制 `.env` 时需自行调整这些值。
+
+`module install/update` 先停止 Odoo，使用一次性维护容器，再启动服务；失败时保留停止状态供排查。`-d` 只覆盖本次维护的目标库，不修改 `.env`。
+
+备份包含数据库和 filestore，使用 Odoo 标准 ZIP；默认保存到用户数据目录的 `mjh-odoo/backups/<PROJECT_NAME>/`，位于代码目录之外，`config` 可查看实际路径。现有文件不会被覆盖。备份时应避免并发业务写入，保证数据库和附件的一致性。
+
+恢复先校验 ZIP 路径、CRC、清单及 Odoo 20.0 主版本，再停止服务。默认中和外发任务；已有目标库需要显式 `--force`。恢复新库不会自动切换项目，切换时修改 `.env` 中的 `PGDATABASE`。
+
+日志默认读取最近 200 行有限快照；筛选保留相邻事件与异常堆栈。`--json` 和 `--file` 不能与 `-f` 同用。已知 `.env` 密码值会被遮盖，业务内容仍需自行判断。临时模块维护容器的失败信息以维护命令本身的输出为准。
+
+本版本包含环境、模块、ZIP 备份恢复、日志、镜像管理。桌面 App、存档目录索引、工作树自动克隆数据库和定时备份尚未实现。
+
+## 开发与验收
+
+```sh
+npm ci
+npm run check
+npm test
+npm pack --dry-run
+```
+
+测试覆盖跨平台参数解析、中文及空格路径、帮助无副作用、批量模块维护、日志和镜像计划。真实 Docker 验收范围见 [验证记录](docs/validation.md)。LGPL-3.0-only，见 LICENSE 和 COPYRIGHT。

package/bin/odoo.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { createProgram } from '../src/cli.mjs';
+
+const {version} = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+try {
+  await createProgram({version}).parseAsync(process.argv);
+} catch (error) {
+  console.error('错误: ' + error.message);
+  process.exitCode = error.exitCode || 1;
+}

package/docs/validation.md

@@ -0,0 +1,35 @@
+# 0.1.0 验证记录
+
+日期：2026-11-03。
+
+## 本机与包
+
+macOS ARM64，Node 26.8.1、Docker 29.7.2、Compose 5.4.0；容器 Odoo 20.0、Python 3.12、PostgreSQL 17。
+
+32 项 Node 测试通过，覆盖环境隔离、重复初始化、中文和空格路径、全量帮助、参数校验、批量模块维护、日志事件与遮盖、镜像计划与离线文件。npm pack 后安装到独立临时前缀，实际 odoo --version、--help 及所有以下 Docker 检查均使用安装后的可执行文件。
+
+发布包约 31 KB，files 白名单仅含 bin、src、docs、README、package.json 与许可；逐项检查无 Odoo 源码、真实环境文件、数据库、附件、node_modules 或本机绝对路径。
+
+## 隔离 Docker 验收
+
+- 全新临时项目使用本机已构建的基础镜像启动并通过健康检查。
+- 单条命令安装两个模块，列出安装状态；批量升级及 --no-restart 保持停止通过。
+- 通过官方 shell 写入真实 raw 附件，先验证 raw.content 和 filestore 文件。
+- ZIP 同时包含 manifest.json、dump.sql、filestore；已有备份文件拒绝覆盖。
+- 恢复到独立新库，列表正确区分 current；恢复后逐字节读取附件一致。
+- module update -d 维护新库，原 .env 字节未改。
+- 有限 JSON 日志快照读取真实 Docker 日志事件。
+- 普通 down 保留两个卷，重新 up 后数据库仍在；显式 down -v 删除两个测试卷。
+- 所有临时容器、卷和网络已清理，原 base .env 字节未改，原有运行容器继续运行。
+
+本机 Docker 默认地址池已满，验收专门创建独立、无冲突的临时内部网络，结束后删除。此测试安排没有写入通用 base 配置，也没有清理其他项目网络。
+
+复查脚本 test/docker-acceptance.py 仅用于可丢弃的新项目，在 macOS 实测；需要 Python 3、本机已有兼容 base 和 mjh-odoo/odoo-runtime:20.0-v0.1.0 镜像：
+
+```sh
+python3 test/docker-acceptance.py /absolute/path/to/base /absolute/path/to/installed/odoo
+```
+
+## 平台边界
+
+GitHub CI 在 Windows、macOS、Linux 的 Node 24 上运行单元测试及打包安装检查；最终结果以发布提交的 Actions 为准。Windows 原生 Docker、WSL 及 Linux Docker 尚未实测。基础镜像与完整 base 均未在本次 CLI 发布中上传。

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@mjh-odoo/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cross-platform Odoo development CLI: environments, modules, database archives, logs and images",
+  "type": "module",
+  "bin": {
+    "odoo": "bin/odoo.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "LGPL-3.0-only",
+  "author": "MaJianhang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjh-odoo/odoo-cli.git"
+  },
+  "homepage": "https://github.com/mjh-odoo/odoo-cli#readme",
+  "bugs": {
+    "url": "https://github.com/mjh-odoo/odoo-cli/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "LICENSE",
+    "COPYRIGHT"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check bin/odoo.mjs && node --check src/cli.mjs && node --check src/commands.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "dependencies": {
+    "commander": "15.0.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,101 @@
+import { Command, Option, InvalidArgumentError } from 'commander';
+import { findProject, openProject, databaseName, runDocker, projectVersion } from './project.mjs';
+import { readEnv } from './lib/environment.mjs';
+import { parseLogOptions, executeLogs } from './lib/logs.mjs';
+import { imageBuildPlan, executeImageBuild } from './lib/image.mjs';
+import * as commands from './commands.mjs';
+
+function integer(value) {
+  if (!/^\d+$/.test(value) || +value > 3600) throw new InvalidArgumentError('请输入 0..3600 的整数。');
+  return +value;
+}
+function positive(value) {
+  const n = integer(value);
+  if (!n) throw new InvalidArgumentError('等待时间必须大于 0。');
+  return n;
+}
+function argumentsFor(options, names) {
+  return names.flatMap(name => {
+    const key = name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const value = options[key];
+    return value === true ? ['--' + name] : value === undefined || value === false ? [] : ['--' + name, String(value)];
+  });
+}
+
+export function createProgram({version, cwd = process.cwd(), runner = runDocker} = {}) {
+  const program = new Command();
+  program.name('odoo').description('Odoo 项目开发管理：环境、模块、数据库、日志与镜像。').version(version, '-V, --version', '显示管理 CLI 版本')
+    .option('-C, --project <directory>', '指定项目目录；默认从当前目录向上查找')
+    .enablePositionalOptions().addHelpCommand('help [command...]', '查看命令帮助').showHelpAfterError('(运行 odoo --help 查看命令)').showSuggestionAfterError(true);
+  program.addHelpText('after', '\n示例:\n  odoo up\n  odoo logs all --since 10m --json\n  odoo module update my_module\n  odoo db backup\n  odoo image build --help\n\n全局 --project 放在命令前，例如 odoo --project /path/to/erp status。');
+  const root = () => findProject(program.opts().project || cwd);
+  const context = initialize => openProject(root(), {initialize, runner});
+  const waitOption = command => command.option('--wait-timeout <seconds>', '健康检查等待秒数', positive, 300);
+  const databaseOption = command => command.option('-d, --database <name>', '目标数据库，默认 PGDATABASE', databaseName);
+
+  program.command('version').description('显示管理 CLI 版本').action(() => console.log(version));
+  program.command('init').description('为当前 base 项目准备本机 .env').option('--json', '输出脱敏 JSON').action(async options => commands.initialize(await context(true), options));
+  program.command('doctor').description('检查 Docker、Compose、源码和配置').option('--json', '输出 JSON').action(async options => commands.doctor(await context(false), options));
+  program.command('config').description('输出项目脱敏配置及存档位置').action(async () => commands.configuration(await context(false)));
+  waitOption(program.command('up').description('后台启动项目并等待健康').option('--build', '构建开发镜像后启动（默认）', true).option('--no-build', '直接使用已有镜像，不构建')
+    .addOption(new Option('--pull <policy>', '镜像拉取策略').choices(['always', 'missing', 'never'])))
+    .action(async options => commands.up(await context(true), options));
+  program.command('down').description('停止项目，默认保留数据库和附件卷')
+    .option('-v, --volumes', '同时删除本项目数据库及附件卷').option('--timeout <seconds>', '停止等待秒数', integer, 30).option('--dry-run', '只显示操作计划，不执行停止或删除')
+    .action(async options => commands.down(await context(false), options));
+  waitOption(program.command('restart').description('重启服务，默认只重启 Odoo').argument('[services...]', 'odoo、db 或 all').option('--timeout <seconds>', '停止等待秒数', integer, 30))
+    .action(async (services, options) => commands.restart(await context(false), services || [], options));
+  program.command('status').description('查看项目容器状态，包含已停止容器').option('--json', '输出 JSON 数组').action(async options => commands.status(await context(false), options));
+  program.command('build').description('构建项目 Compose 开发镜像').option('--pull', '更新上游镜像').option('--no-cache', '不使用构建缓存').action(async options => commands.build(await context(false), options));
+
+  const logs = program.command('logs').description('默认读取最近 200 行快照；-f 才持续跟随').argument('[services...]', 'odoo、db 或 all，默认 odoo')
+    .option('-f, --follow', '持续查看，Ctrl+C 只退出查看').option('-n, --tail <lines>', '每容器行数，支持 0 或 all', '200')
+    .option('--since <time>', '起始时间，如 10m 或带时区 RFC3339').option('--until <time>', '截止时间')
+    .option('--level <level>', '最低级别：debug/info/warning/error/critical').option('--match <text>', '不区分大小写的字面筛选')
+    .option('--context <events>', '筛选结果前后事件数，默认 2').option('--json', '输出完整 JSON 快照').option('--file <path>', '保存快照，拒绝覆盖已有文件');
+  logs.addHelpText('after', '\n筛选、JSON 和文件用于有限快照，不能与 -f 同用。保留完整异常堆栈；--tail 起点仍可能截到异常中间。');
+  logs.action(async (services, options) => {
+    const parsed = parseLogOptions([...(services || []), ...argumentsFor(options, ['follow', 'tail', 'since', 'until', 'level', 'match', 'context', 'json', 'file'])]);
+    process.exitCode = await executeLogs(parsed, await context(false));
+  });
+
+  const module = program.command('module').description('查询、安装和升级模块');
+  databaseOption(module.command('list').description('列出已安装模块').option('--all', '包含未安装模块').option('--json', '输出 JSON')).action(async options => commands.listModules(await context(false), options));
+  for (const operation of ['install', 'update']) {
+    const command = databaseOption(module.command(operation).description(operation === 'install' ? '批量安装模块' : '批量升级已安装模块')
+      .argument(operation === 'install' ? '<modules...>' : '[modules...]', '用空格分隔多个模块名').option('--no-restart', '完成后保持 Odoo 停止'));
+    if (operation === 'update') command.option('--all', '升级全部已安装的项目扩展（不包含官方核心）');
+    command.action(async (names, options) => commands.maintainModules(await context(false), operation, names || [], options));
+  }
+  module.action(() => module.help());
+
+  const db = program.command('db').description('数据库查询及标准 ZIP 备份恢复');
+  db.command('list').description('列出项目 PostgreSQL 中的数据库').option('--json', '输出 JSON；current 表示当前配置的数据库').action(async options => commands.listDatabases(await context(false), options));
+  databaseOption(db.command('backup').description('导出数据库及附件 ZIP').option('--file <path>', '输出路径；默认保存到工作树之外')).action(async options => commands.backup(await context(false), options));
+  databaseOption(db.command('restore').description('恢复 ZIP，默认中和外发任务').requiredOption('--file <path>', '已有的 Odoo 20 ZIP')
+    .option('--force', '允许覆盖已有目标数据库').option('--no-restart', '恢复后保持 Odoo 停止')).action(async options => commands.restore(await context(false), options));
+  db.action(() => db.help());
+
+  const image = program.command('image').description('构建基础镜像、项目镜像和离线包');
+  image.command('build').description('默认构建本地基础镜像')
+    .option('--platform <platforms>', 'amd64、arm64 或 amd64,arm64')
+    .option('--tag <name:version>', '镜像标签；推送和 production 必填')
+    .addOption(new Option('--target <stage>', '构建阶段').choices(['base', 'production']).default('base'))
+    .option('--file <path.tar>', '导出单架构离线包').option('--push', '明确推送到镜像仓库').option('--builder <name>', '使用已有 Buildx 构建器').option('--dry-run', '仅输出 JSON 计划')
+    .action(async options => {
+      const directory = root();
+      const plan = imageBuildPlan(argumentsFor(options, ['platform', 'tag', 'target', 'file', 'push', 'builder', 'dry-run']), {root: directory, version: projectVersion(directory), mirror: readEnv(directory).APT_MIRROR_BASE});
+      if (plan.dryRun) { console.log(JSON.stringify(plan, null, 2)); return; }
+      console.log(`构建 ${plan.target}: ${plan.tag} (${plan.platforms.join(',') || '当前构建器平台'})`);
+      await executeImageBuild(plan, (argv, stdio) => runner(argv, {root: directory, env: process.env, stdio}));
+      console.log(plan.file ? '离线包已保存: ' + plan.file : plan.output === 'registry' ? '镜像已推送: ' + plan.tag : '本地镜像就绪: ' + plan.tag);
+    });
+  image.action(() => image.help());
+
+  program.command('exec').description('在运行中的 Odoo 容器里转发官方命令；本地说明用 help exec')
+    .helpOption(false).allowUnknownOption(true).passThroughOptions().argument('[args...]', '原样传给官方 Odoo CLI 的参数')
+    .addHelpText('after', '\n示例:\n  odoo exec -- --version\n  odoo exec -- --help\n  odoo exec -- shell -c /etc/odoo/odoo.conf')
+    .action(async args => commands.native(await context(false), args || []));
+  program.action(() => program.help());
+  return program;
+}

package/src/commands.mjs

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { archiveDirectory, checkModuleNames, publicSettings } from './lib/environment.mjs';
+import { databaseName, serviceNames, withLock } from './project.mjs';
+
+const start = (ctx, services = ['odoo'], timeout = 300) => ctx.run(['up', '-d', '--no-build', '--wait', '--wait-timeout', String(timeout), ...services]);
+
+export async function initialize(ctx, options) {
+  if (options.json) console.log(JSON.stringify({projectDirectory: ctx.root, ...publicSettings(ctx.values)}, null, 2));
+  else {
+    console.log('项目配置就绪: ' + ctx.values.PROJECT_NAME);
+    console.log('Odoo: http://localhost:' + ctx.values.ODOO_HTTP_PORT);
+    console.log('初始管理员密码位于本机 .env 的 ODOO_ADMIN_PASSWORD。');
+  }
+}
+
+export async function doctor(ctx, options) {
+  const result = {project: ctx.values.PROJECT_NAME, directory: ctx.root, node: process.versions.node};
+  for (const [name, argv] of [['docker', ['version', '--format', '{{.Server.Version}}']], ['compose', ['compose', 'version', '--short']], ['buildx', ['buildx', 'version']]]) result[name] = await ctx.docker(argv, {capture: true});
+  if (!fs.existsSync(path.join(ctx.root, 'odoo', 'odoo-bin'))) throw new Error('项目缺少完整 Odoo 源码: odoo/odoo-bin。');
+  if (!fs.existsSync(path.join(ctx.root, 'scripts', 'runtime.py'))) throw new Error('项目缺少容器入口 scripts/runtime.py。');
+  await ctx.run(['config', '--quiet'], {capture: true});
+  result.valid = true;
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else for (const [name, value] of Object.entries(result)) console.log(`${name}: ${value}`);
+}
+
+export function configuration(ctx) {
+  console.log(JSON.stringify({PROJECT_DIRECTORY: ctx.root, ...publicSettings(ctx.values), BACKUP_DIRECTORY: archiveDirectory(ctx.values)}, null, 2));
+}
+
+export async function up(ctx, options) {
+  await withLock(ctx, async () => {
+    const args = ['up', '-d', options.build ? '--build' : '--no-build', '--wait', '--wait-timeout', String(options.waitTimeout)];
+    if (options.pull) args.push('--pull', options.pull);
+    await ctx.run(args);
+    console.log('Odoo: http://localhost:' + ctx.values.ODOO_HTTP_PORT);
+  });
+}
+
+export async function down(ctx, options) {
+  const args = ['down', '--timeout', String(options.timeout)];
+  if (options.volumes) args.push('--volumes');
+  if (options.dryRun) {
+    console.log(JSON.stringify({project: ctx.values.PROJECT_NAME, directory: ctx.root, removeVolumes: !!options.volumes, docker: [...ctx.compose, ...args]}, null, 2));
+    return;
+  }
+  await withLock(ctx, async () => {
+    if (options.volumes) console.error('删除本项目数据库和附件卷: ' + ctx.values.PROJECT_NAME);
+    await ctx.run(args);
+  });
+}
+
+export async function restart(ctx, names, options) {
+  const services = serviceNames(names);
+  await withLock(ctx, async () => {
+    await ctx.run(['restart', '--timeout', String(options.timeout), ...services]);
+    await start(ctx, services, options.waitTimeout);
+  });
+}
+
+export async function status(ctx, options) {
+  const args = ['ps', '--all'];
+  if (options.json) {
+    const raw = await ctx.run([...args, '--format', 'json'], {capture: true});
+    let result;
+    try { result = raw ? JSON.parse(raw) : []; }
+    catch { result = raw.split('\n').filter(Boolean).map(line => JSON.parse(line)); }
+    console.log(JSON.stringify(Array.isArray(result) ? result : [result], null, 2));
+  } else await ctx.run(args);
+}
+
+export async function build(ctx, options) {
+  await withLock(ctx, () => ctx.run(['build', ...(options.pull ? ['--pull'] : []), ...(options.cache === false ? ['--no-cache'] : []), 'odoo']));
+}
+
+export async function maintainModules(ctx, operation, names, options) {
+  const modules = checkModuleNames(names);
+  if (operation === 'install' && !modules.length) throw new Error('请指定至少一个要安装的模块。');
+  if (operation === 'update' && !modules.length && !options.all) throw new Error('请指定模块名，或使用 --all 升级已安装的项目扩展。');
+  if (options.all && modules.length) throw new Error('--all 不能与模块名同时使用。');
+  if (options.database) databaseName(options.database);
+  await withLock(ctx, async () => {
+    await ctx.run(['up', '-d', '--wait', 'db']);
+    await ctx.run(['stop', 'odoo']);
+    const args = ['run', '--rm', '--no-deps', '-T'];
+    if (options.database) args.push('--env', 'PGDATABASE=' + options.database);
+    args.push('--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/runtime.py', operation === 'install' ? 'install' : 'upgrade', ...modules);
+    await ctx.run(args);
+    if (options.restart !== false) await start(ctx);
+    else console.log('模块维护完成；Odoo 保持停止，可用 odoo up 启动。');
+  });
+}
+
+async function sql(ctx, database, query) {
+  databaseName(database);
+  const result = await ctx.run(['exec', '-T', 'db', 'psql', '--no-psqlrc', '--username', ctx.values.PGUSER, '--dbname', database, '--tuples-only', '--no-align', '--command', query], {capture: true});
+  return JSON.parse(result || '[]');
+}
+
+export async function listDatabases(ctx, options) {
+  const data = await sql(ctx, 'postgres', "SELECT coalesce(json_agg(t), '[]'::json) FROM (SELECT datname AS name FROM pg_database WHERE NOT datistemplate AND datname <> 'postgres' ORDER BY datname) t");
+  const rows = data.map(row => ({...row, current: row.name === ctx.values.PGDATABASE}));
+  if (options.json) console.log(JSON.stringify(rows, null, 2));
+  else for (const row of rows) console.log((row.current ? '* ' : '  ') + row.name);
+}
+
+export async function listModules(ctx, options) {
+  const database = options.database || ctx.values.PGDATABASE;
+  const data = await sql(ctx, database, `SELECT coalesce(json_agg(t), '[]'::json) FROM (SELECT name, state, latest_version AS version FROM ir_module_module ${options.all ? '' : "WHERE state = 'installed'"} ORDER BY name) t`);
+  if (options.json) console.log(JSON.stringify(data, null, 2));
+  else for (const row of data) console.log(`${row.name.padEnd(40)} ${row.state.padEnd(14)} ${row.version || '-'}`);
+}
+
+async function validateZip(ctx, filename) {
+  const fd = fs.openSync(filename, 'r');
+  try { await ctx.run(['run', '--rm', '--no-deps', '-T', '--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/backup_utils.py', 'validate'], {stdio: [fd, 'inherit', 'inherit']}); }
+  finally { fs.closeSync(fd); }
+}
+
+export async function backup(ctx, options) {
+  const database = databaseName(options.database || ctx.values.PGDATABASE);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const target = path.resolve(options.file || path.join(archiveDirectory(ctx.values), database + '-' + stamp + '.zip'));
+  if (fs.existsSync(target)) throw new Error('存档已存在: ' + target);
+  await withLock(ctx, async () => {
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    const temporary = target + '.part';
+    let fd;
+    try {
+      fd = fs.openSync(temporary, 'wx', 0o600);
+      await ctx.run(['exec', '-T', 'odoo', 'odoo', 'db', '-c', '/etc/odoo/odoo.conf', 'dump', database, '-'], {stdio: ['ignore', fd, 'inherit']});
+      fs.closeSync(fd);
+      fd = undefined;
+      await validateZip(ctx, temporary);
+      fs.linkSync(temporary, target);
+      console.log('存档已保存: ' + target);
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+      fs.rmSync(temporary, {force: true});
+    }
+  });
+}
+
+export async function restore(ctx, options) {
+  const source = path.resolve(options.file);
+  if (!fs.statSync(source, {throwIfNoEntry: false})?.isFile()) throw new Error('请提供已有的 ZIP 存档。');
+  const database = databaseName(options.database || ctx.values.PGDATABASE);
+  await withLock(ctx, async () => {
+    await validateZip(ctx, source);
+    await ctx.run(['up', '-d', '--wait', 'db']);
+    await ctx.run(['stop', 'odoo']);
+    const args = ['run', '--rm', '--no-deps', '-T', '--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/backup_utils.py', 'restore', database];
+    if (options.force) args.push('--force');
+    const fd = fs.openSync(source, 'r');
+    try { await ctx.run(args, {stdio: [fd, 'inherit', 'inherit']}); }
+    finally { fs.closeSync(fd); }
+    if (options.restart !== false) await start(ctx);
+    console.log('已恢复并中和外发任务: ' + database);
+    if (database !== ctx.values.PGDATABASE) console.log('使用新库时，将项目 .env 中的 PGDATABASE 改为 ' + database + '。');
+  });
+}
+
+export async function native(ctx, args) {
+  if (!args.length) throw new Error('请指定官方 Odoo 参数，例如 odoo exec -- --version。');
+  await ctx.run(['exec', ...(!process.stdin.isTTY || !process.stdout.isTTY ? ['-T'] : []), 'odoo', 'odoo', ...args]);
+}

package/src/lib/environment.mjs

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { parseEnv } from 'node:util';
+
+export function readEnv(root) {
+  const filename = path.join(root, '.env');
+  return fs.existsSync(filename) ? parseEnv(fs.readFileSync(filename, 'utf8')) : {};
+}
+
+export function projectName(root) {
+  const location = fs.realpathSync(root);
+  const prefix = path.basename(location).toLowerCase().replace(/[^a-z0-9_-]/g, '_').replace(/^[_-]+/, '') || 'odoo';
+  return prefix.slice(0, 32) + '_' + crypto.createHash('sha256').update(location).digest('hex').slice(0, 10);
+}
+
+async function portFree(port) {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen({host: '127.0.0.1', port, exclusive: true}, () => server.close(() => resolve(true)));
+  });
+}
+
+export function validateEnv(values) {
+  for (const key of ['PROJECT_NAME', 'PGDATABASE', 'PGUSER', 'PGPASSWORD', 'ODOO_MASTER_PASSWORD', 'ODOO_ADMIN_PASSWORD']) {
+    if (!values[key]) throw new Error('Missing ' + key + '. Check .env or run init in a new checkout.');
+    if (/[\r\n]/.test(values[key])) throw new Error(key + ' must be a single line.');
+  }
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(values.PROJECT_NAME)) throw new Error('Invalid PROJECT_NAME.');
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(values.PGDATABASE)) throw new Error('Invalid PGDATABASE.');
+  if (!['DEV', 'TEST', 'PROD'].includes(values.ENV)) throw new Error('ENV must be DEV, TEST or PROD.');
+  const ports = ['DB_PORT', 'ODOO_HTTP_PORT', 'ODOO_GEVENT_PORT'].map(key => {
+    const value = values[key];
+    if (!/^\d+$/.test(value || '') || +value < 1 || +value > 65535) throw new Error('Invalid ' + key + '.');
+    return +value;
+  });
+  if (new Set(ports).size !== ports.length) throw new Error('Host ports must be distinct.');
+  return values;
+}
+
+export async function prepareEnv(root) {
+  const filename = path.join(root, '.env');
+  if (fs.existsSync(filename)) return validateEnv(readEnv(root));
+  let text = fs.readFileSync(path.join(root, '.env.example'), 'utf8');
+  const values = parseEnv(text);
+  const name = projectName(root);
+  const offset = parseInt(crypto.createHash('sha256').update(fs.realpathSync(root)).digest('hex').slice(0, 6), 16) % 1000;
+  let ports;
+  for (let attempt = 0; attempt < 1000; attempt++) {
+    const n = (offset + attempt) % 1000;
+    const candidate = [15432 + n, 18069 + n, 18072 + n];
+    if ((await Promise.all(candidate.map(portFree))).every(Boolean)) { ports = candidate; break; }
+  }
+  if (!ports) throw new Error('No free host port set found.');
+  Object.assign(values, {
+    PROJECT_NAME: name, DB_PORT: String(ports[0]), ODOO_HTTP_PORT: String(ports[1]), ODOO_GEVENT_PORT: String(ports[2]),
+    PGPASSWORD: crypto.randomBytes(24).toString('hex'),
+    ODOO_MASTER_PASSWORD: crypto.randomBytes(24).toString('hex'),
+    ODOO_ADMIN_PASSWORD: crypto.randomBytes(24).toString('hex'),
+  });
+  validateEnv(values);
+  for (const key of ['PROJECT_NAME', 'DB_PORT', 'ODOO_HTTP_PORT', 'ODOO_GEVENT_PORT', 'PGPASSWORD', 'ODOO_MASTER_PASSWORD', 'ODOO_ADMIN_PASSWORD']) {
+    const pattern = new RegExp('^' + key + '=.*$', 'm');
+    text = text.replace(pattern, key + '=' + values[key]);
+  }
+  try { fs.writeFileSync(filename, text, {flag: 'wx', mode: 0o600}); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  return validateEnv(readEnv(root));
+}
+
+export function archiveDirectory(values) {
+  const base = process.platform === 'win32'
+    ? (process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'))
+    : process.platform === 'darwin'
+      ? path.join(os.homedir(), 'Library', 'Application Support')
+      : (process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'));
+  return path.join(base, 'mjh-odoo', 'backups', values.PROJECT_NAME);
+}
+
+export function publicSettings(values) {
+  return Object.fromEntries(Object.entries(values).filter(([key]) => !/PASSWORD|TOKEN|SECRET|KEY/.test(key)));
+}
+
+export function checkModuleNames(names) {
+  if (names.some(name => !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))) throw new Error('Invalid module name.');
+  return [...new Set(names)];
+}

package/src/lib/image.mjs

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseArgs } from 'node:util';
+
+export function imageBuildPlan(args, {root, version, mirror = ''}) {
+  const values = parseArgs({args, options: {
+    platform: {type: 'string'}, tag: {type: 'string'}, file: {type: 'string'},
+    target: {type: 'string', default: 'base'}, builder: {type: 'string'},
+    push: {type: 'boolean', default: false}, 'dry-run': {type: 'boolean', default: false},
+  }}).values;
+  if (!['base', 'production'].includes(values.target)) throw new Error('Use --target base or production.');
+  if (values.push && !values.tag) throw new Error('--push requires an explicit --tag.');
+  if (values.target === 'production' && !values.tag) throw new Error('production requires an explicit --tag.');
+  if (values.push && values.file) throw new Error('--push and --file cannot be combined.');
+  const tag = values.tag ?? `mjh-odoo/odoo-runtime:20.0-v${version}`;
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._/:-]*$/.test(tag)) throw new Error('Invalid image tag.');
+  if (values.file !== undefined && !values.file.trim()) throw new Error('--file must name an output archive.');
+  if (values.builder !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(values.builder)) throw new Error('Invalid builder name.');
+  const platforms = [];
+  if (values.platform !== undefined) {
+    for (const value of values.platform.split(',')) {
+      const platform = value.startsWith('linux/') ? value : `linux/${value}`;
+      if (!['linux/amd64', 'linux/arm64'].includes(platform)) throw new Error('Supported platforms: amd64, arm64 (or linux/amd64, linux/arm64).');
+      if (!platforms.includes(platform)) platforms.push(platform);
+    }
+  }
+  if (platforms.length > 1 && !values.push) throw new Error('Multiple platforms require --push. Export offline archives one platform at a time.');
+  if (mirror) {
+    let url;
+    try { url = new URL(mirror); } catch { throw new Error('Invalid APT_MIRROR_BASE URL.'); }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || /[\r\n]/.test(mirror)) throw new Error('APT_MIRROR_BASE must be an HTTP(S) URL without credentials.');
+  }
+  const file = values.file ? path.resolve(values.file) : undefined;
+  const argv = ['buildx', 'build', '--file', path.join(root, 'Dockerfile'), '--target', values.target, '--tag', tag];
+  if (values.builder) argv.push('--builder', values.builder);
+  if (platforms.length) argv.push('--platform', platforms.join(','));
+  if (mirror) argv.push('--build-arg', `APT_MIRROR_BASE=${mirror}`);
+  if (file) argv.push('--output', 'type=docker,dest=-');
+  else argv.push(values.push ? '--push' : '--load');
+  argv.push(root);
+  return {target: values.target, tag, platforms, output: file ? 'archive' : values.push ? 'registry' : 'local', file, dryRun: values['dry-run'], argv};
+}
+
+export async function executeImageBuild(plan, run) {
+  if (plan.file && fs.existsSync(plan.file)) throw new Error('Archive already exists: ' + plan.file);
+  await run(['buildx', 'version']);
+  if (!plan.file) {
+    await run(plan.argv);
+    return;
+  }
+  fs.mkdirSync(path.dirname(plan.file), {recursive: true});
+  const temporary = plan.file + '.' + randomUUID() + '.part';
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx', 0o600);
+    await run(plan.argv, ['ignore', fd, 'inherit']);
+    fs.closeSync(fd);
+    fd = undefined;
+    if (!fs.statSync(temporary).size) throw new Error('Docker produced an empty archive.');
+    fs.linkSync(temporary, plan.file);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    fs.rmSync(temporary, {force: true});
+  }
+}