@ranger1/dx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ranger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# dx
+
+一个可安装的 Node.js CLI，用于管理 ai-monorepo 类项目的构建/启动/数据库/部署等流程。
+
+## 安装
+
+项目内安装（推荐）：
+
+```bash
+pnpm add -D dx
+```
+
+使用：
+
+```bash
+pnpm exec dx --help
+pnpm exec dx status
+pnpm exec dx build sdk --dev
+```
+
+也可以全局安装：
+
+```bash
+pnpm add -g dx
+dx --help
+```
+
+## 项目配置（必须）
+
+dx 会从当前目录向上查找 `dx/config/commands.json` 来定位项目根目录。
+
+你需要在项目根目录提供：
+
+```
+dx/
+  config/
+    commands.json
+    env-layers.json
+    required-env.jsonc
+    local-env-allowlist.jsonc
+    exempted-keys.jsonc
+```
+
+可选覆盖：
+
+- 环境变量：`DX_CONFIG_DIR=/abs/path/to/config`
+- 参数：`dx --config-dir /abs/path/to/config ...`
+
+## 命令
+
+dx 的命令由 `dx/config/commands.json` 驱动，并且内置了一些 internal runner（避免项目侧依赖任何 `scripts/lib/*.js`）：
+
+- `internal: sdk-build`：SDK 生成/构建
+- `internal: backend-package`：后端打包
+- `internal: start-dev`：开发环境一键启动
+
+常用示例：
+
+```bash
+dx start backend --dev
+dx start all
+dx build backend --prod
+dx build sdk --dev
+dx db generate
+dx db migrate --dev --name init
+dx db deploy --prod -Y
+dx deploy front --staging
+dx lint
+dx test e2e backend
+```
+
+## 给 Nx target 注入版本信息（可选）
+
+本包提供 `dx-with-version-env`，用于在 `nx:run-commands` 中注入版本/sha/构建时间等环境变量：
+
+```json
+{
+  "command": "../../node_modules/.bin/dx-with-version-env --app front -- next build"
+}
+```
+
+支持的 app：`backend` / `front` / `admin`。
+
+## 约束与假设
+
+当前版本面向 ai-monorepo 类结构，默认假设：
+
+- 使用 pnpm + nx
+- 项目布局包含 `apps/backend`、`apps/front`、`apps/admin-front`、`apps/sdk`
+
+## 发布到 npm（准备工作）
+
+如果你准备公开发布：
+
+1. 注意：npm 上的包名 `dx` 很可能已被占用；更稳妥的是使用 scope（例如 `@ranger1/dx`）。
+2. 发布前需要把 `package.json` 里的 `private: true` 去掉，并补全 `version` / `license` / `repository` 等字段。
+3. 发布命令（公开包）：
+
+```bash
+npm publish --access public --registry=https://registry.npmjs.org
+```
+
+提示：当前仓库包含一个 `.npmrc`，用于确保 publish 走 npm 官方 registry（避免镜像源导致发布失败）。

package/bin/dx-with-version-env.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runWithVersionEnv } from '../lib/run-with-version-env.js'
+
+runWithVersionEnv(process.argv.slice(2)).catch(error => {
+  console.error('[dx-with-version-env] failed:', error?.message || String(error))
+  process.exit(1)
+})

package/bin/dx.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs'
+import { resolve, dirname, join } from 'node:path'
+
+function parseConfigDir(argv) {
+  const envValue = process.env.DX_CONFIG_DIR
+  if (envValue) return String(envValue)
+
+  const args = Array.isArray(argv) ? argv : []
+  const idx = args.indexOf('--config-dir')
+  if (idx !== -1 && idx + 1 < args.length) return String(args[idx + 1])
+  for (const token of args) {
+    if (token.startsWith('--config-dir=')) return String(token.slice('--config-dir='.length))
+  }
+  return null
+}
+
+function stripConfigDirArgs(argv) {
+  const args = Array.isArray(argv) ? [...argv] : []
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i]
+    if (token === '--config-dir') {
+      i++
+      continue
+    }
+    if (token.startsWith('--config-dir=')) continue
+    out.push(token)
+  }
+  return out
+}
+
+function findProjectRootFrom(startDir) {
+  let current = resolve(startDir)
+  while (true) {
+    const marker = join(current, 'dx', 'config', 'commands.json')
+    if (existsSync(marker)) return current
+
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2)
+  const overrideConfigDir = parseConfigDir(rawArgs)
+  const filteredArgs = stripConfigDirArgs(rawArgs)
+
+  const startDir = process.cwd()
+  const projectRoot = findProjectRootFrom(startDir)
+  if (!projectRoot) {
+    console.error('dx: 未找到项目配置目录: dx/config/commands.json')
+    console.error('dx: 请在项目目录内执行 dx，或先创建 dx/config 并放置 commands.json')
+    console.error('dx: 也可通过 DX_CONFIG_DIR 或 --config-dir 指定配置目录')
+    process.exit(1)
+  }
+
+  process.env.DX_PROJECT_ROOT = projectRoot
+
+  const defaultConfigDir = join(projectRoot, 'dx', 'config')
+  process.env.DX_CONFIG_DIR = overrideConfigDir ? resolve(projectRoot, overrideConfigDir) : defaultConfigDir
+
+  process.chdir(projectRoot)
+
+  process.argv = [process.argv[0], process.argv[1], ...filteredArgs]
+
+  const [{ logger }, { DxCli }] = await Promise.all([
+    import('../lib/logger.js'),
+    import('../lib/cli/dx-cli.js'),
+  ])
+
+  const cli = new DxCli({ projectRoot, configDir: process.env.DX_CONFIG_DIR, invocation: 'dx' })
+  await cli.run().catch(error => {
+    logger.error('CLI启动失败')
+    logger.error(error?.message || String(error))
+    process.exit(1)
+  })
+}
+
+main().catch(error => {
+  console.error('dx: CLI启动失败')
+  console.error(error?.message || String(error))
+  process.exit(1)
+})