@aipt/idp-deploy 0.1.3 → 0.1.5

package/README.md

@@ -1,5 +1,7 @@
 # IDP Deploy
 
+业务项目不复制本仓部署长文档。Dyyto Bootstrap 锁定本包版本和 `local-deployment` 文档 ID；`dyyto docs show --id local-deployment` 提供面向 Agent 的精简入口。
+
 `idp-deploy` 是企业内部开发者平台的轻量部署与运维控制面。它把 PostgreSQL、私有 npm Registry、Tech、Flow、Portal、SmartGo 和 Caddy 组合为可独立启停的服务片段；Dyyto、Bench、Forge 仍是按需运行的 CLI/MCP 工具，不被强制常驻。SmartGo 是显式选择的业务 Profile，不进入默认 IDP Core。
 
 Kubernetes/GitOps 已进入当前 CLI：应用通过 ComponentContract、Bench EnvironmentBinding 和 ReleaseCandidate 生成不可变 DeploymentPlan，再由同一 Kernel 完成确定性 Render、Repository Apply、Git commit、Preimage/CAS 保护和 Repository Verify。它保留历史 `kubernetes-config` 的中央期望状态与 Argo 收敛能力，但不复制跨仓 `sed`、可变 tag、明文 Secret 或宽权限。完整合同与所有权见 [`docs/features/kubernetes-gitops-deployment-backend/DESIGN.md`](docs/features/kubernetes-gitops-deployment-backend/DESIGN.md)。

package/docs/application-config-workspace.md

@@ -0,0 +1,13 @@
+# 工作区与应用 Config Dir
+
+`APP_CONFIG_DIR` 是所有业务工作区配置的外部总根，例如 `/company/config/apps`。多应用仓库以工作区接入：
+
+```bash
+export APP_CONFIG_DIR=/company/config/apps
+idpctl app config-init \
+  --project /workspace/apex/apps/server \
+  --workspace-root /workspace/apex \
+  --environment local
+```
+
+结果位于 `$APP_CONFIG_DIR/apex/apps/server/local`；项目的 `.dyyto` 元数据记录解析规则，但不保存 Secret。单应用仓库可省略 `--workspace-root`，此时项目自身作为工作区根。`--application-config-dir` 仅用于显式兼容覆盖，不是推荐的日常模式。

package/docs/command-reference.md

@@ -0,0 +1,10 @@
+# idpctl 命令入口
+
+- `idpctl --version --json`：确认版本与实际可执行文件。
+- `idpctl app config-init --project <应用绝对路径> [--workspace-root <工作区绝对路径>] --environment local`：初始化仓库外应用配置。
+- `idpctl local app plan ...`：生成不可变本地 Compose 部署 Plan。
+- `idpctl local app apply|verify|stop --plan <绝对路径>`：执行、验证或停止。
+- `idpctl local app remove --plan <绝对路径> --confirm <application-id>`：显式移除。
+- `idpctl config init|generate-secrets`：初始化 IDP 基座 Config Dir。
+
+业务应用本地部署不要求 buildx 或推送远程 OCI；生产交付仍使用锁定摘要的多架构镜像。

package/docs/config-dir-security.md

@@ -0,0 +1,3 @@
+# Config Dir 安全边界
+
+平台配置与业务配置分离：`IDP_CONFIG_DIR` 保存工程基座配置，`APP_CONFIG_DIR` 是业务 Workspace 和应用配置总根。Secret、证书与 `*_FILE` 目标位于仓库外，权限不超过 0600；项目内禁止保存真实敏感值。

package/docs/features/bench-deployment-ownership-reception/DESIGN.md

@@ -0,0 +1,63 @@
+# Bench 部署所有权接收 DESIGN
+
+- 状态：approved
+- 批次：idp-deploy.bench-deployment-ownership-reception@1
+- 批准依据：用户于 2026-08-31 明确授权按最终 IDP 架构直接完成迁移。
+- 范围：只修改 idp-deploy；不写 Bench dirty worktree，不读取或接入 Aura。
+
+## 目标
+
+idp-deploy 成为 IDP 唯一的部署编排、外部配置、安全投影、备份恢复和运维证据所有者。Bench 继续拥有基础设施 Catalog、Offering、Binding 与 Probe 事实，不再拥有另一套部署执行面。
+
+本批次接收的是经过筛选的能力，不是把 Bench 的 `docker-compose.yml`、`local/`、`gitops/` 与 `infra/terraform/` 整体复制过来。
+
+## 接收决策
+
+| Bench 资产 | 决策 | idp-deploy 结果 |
+| --- | --- | --- |
+| `packages/ops` | 接收语义 | 统一 Kernel 提供 Profile、Preimage、Lease、Apply、Verify、Backup、Restore、Rollback 与 Receipt；不兼容旧任意 shell 动作模型 |
+| `scripts/ops-agent.mjs` | 替代 | 不接收 Unix Socket shell 代理；CLI/AI 调用同一受控 Kernel，Portal 保持只读 |
+| `docker-compose.yml` | 选择性接收 | 重建为每服务独立 Compose 片段和最小 Profile，只保留有真实 IDP 消费者的 PostgreSQL、Verdaccio、Tech、Flow、Portal、Caddy |
+| `local/cnpmcore-*` | 替代 | 使用轻量 Verdaccio；Scope、防上游泄漏、认证发布与外部 npmrc 由 idp-deploy 管理 |
+| `local/postgresql-init` | 接收语义 | 非 root 一次性 Bootstrap 幂等收敛角色、Owner 和 Schema 权限 |
+| 其余 `local/` 实验服务 | 延后 | 没有有效 Bench Binding、容量/恢复边界和独立部署需求前不进入默认 Profile |
+| `gitops/` | 延后 | 没有获批 Kubernetes/GitOps 目标环境前不创建空 Argo CD 资源 |
+| `infra/terraform/` | 延后 | 没有获批 Provider、状态后端和真实账户前不创建或应用远程资源 |
+
+## 安全与配置不变量
+
+- 所有真实变量、Secret、证书、信任、数据、日志、备份与恢复材料只存在于仓库外的绝对 `IDP_CONFIG_DIR` 或其声明的互斥数据根。
+- 仓库只保存无 Secret 模板、Compose 片段、JSON Schema 与生命周期回执。
+- `.env` 不允许密码、Token、私钥、API Key 或 Access Key；敏感项必须使用相对 `*_FILE`。
+- 所有运行时组件只挂载内容寻址的最小只读投影，不挂载整个宿主配置根。
+- 生产镜像使用 OCI digest 并同时证明 `linux/amd64` 与 `linux/arm64`。
+- 新常驻服务只有在存在独立 Compose、最小 Profile、健康检查、备份/恢复边界、真实 Binding 与自动验收后才能加入。
+
+## 本地 CLI 体验
+
+idp-deploy 不是常驻 App。确定性本地入口为：
+
+```bash
+node bin/idpctl.mjs help
+npm run lifecycle:check
+npm run smoke:local
+```
+
+`smoke:local` 在临时仓库外 Config Dir 中走真实 CLI `config init` 与 `doctor registry`，校验权限和生命周期清单后清理，不写仓库。
+
+## 失败、恢复与物理归档
+
+- 生命周期清单机器校验所有来源资产、接收决策、目标证据与剩余门禁；摘要不匹配即失败。
+- 当前不移动 Bench 文件：Bench 有并发修改，且 GitOps/Terraform/剩余本地服务尚无批准目标。
+- Bench 物理归档前必须分别生成 source preimage 与 `ARCHIVE.json`；已接收项还需证明消费者切换，延后项需证明当前部署不依赖。
+- 任何接收失败只删除本批次新增的目标证据；不回写、不覆盖 Bench。
+
+## 验收
+
+```bash
+npm run lifecycle:check
+npm run smoke:local
+npm run check
+```
+
+Docker 集成验收继续使用 `npm run test:integration`，不以静态 Compose 解析代替真实容器验证。

package/docs/features/bench-deployment-ownership-reception/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,35 @@
+# 实施 Plan：idp-deploy.bench-deployment-ownership-reception@1
+
+- 状态：approved
+- 不可变：true
+- 批准日期：2026-08-31
+
+## 固定写集
+
+- `docs/features/bench-deployment-ownership-reception/**`
+- `archive/README.md`
+- `contracts/asset-lifecycle.schema.json`
+- `governance/asset-lifecycle.v1.json`
+- `src/lifecycle.mjs`
+- `tests/lifecycle.test.mjs`
+- `scripts/smoke-local.mjs`
+- `src/cli.mjs`
+- `package.json`
+- `README.md`
+
+## 原子步骤
+
+1. 保存 idp-deploy 当前 dirty preimage，新增文件与现有发布修复分离。
+2. 将 Bench 部署资产逐项标记为 accepted、replaced、selectively-received 或 deferred。
+3. 绑定每个已接收项到现有 idp-deploy 目标实现和验证证据。
+4. 添加机器生命周期校验与无配置依赖的 `idpctl lifecycle check`。
+5. 添加使用临时外部 Config Dir 的 CLI smoke。
+6. 执行语法、单元、配置安全和 smoke 验收。
+
+## 明确禁止
+
+- 不整体复制 Bench Compose、实验中间件、GitOps 或 Terraform；
+- 不在无目标环境时创建远程资源、空模块或常驻服务；
+- 不把 Portal 改为运维 shell 代理；
+- 不在仓库生成 `.env`、`.npmrc`、Secret、证书或运行数据；
+- 不修改 Bench 或 Aura。

package/docs/features/cli-package-distribution/DESIGN.md

@@ -0,0 +1,6 @@
+# idpctl 双 Registry 包发布设计
+
+- 状态：approved
+- 批准依据：用户明确要求将 `idpctl`、`idp`、`dyyto` 等工程 CLI 发布到私有与公开 npm Registry。
+
+`@aipt/idp-deploy` 发布部署 CLI 运行所需的 `bin/src/compose/contracts/release/governance` 与运维文档，不包含 Config Dir、Secret、运行数据、备份或 node_modules。发布前运行语法与契约测试并审计 tarball；发布后从两个 Registry 回读并在仓库外临时目录执行 `idpctl --help`。远端版本不可覆盖。

package/docs/features/developer-delivery-environment-model/ACCEPTANCE.md

@@ -0,0 +1,48 @@
+# 无集群交付闭环验收
+
+本批次不要求 Docker、Kubernetes 或云资源。正式 fixture consumer 固定写入 `.examples/no-cluster-delivery`，并调用生产代码中的 Delivery 与 GitOps Kernel。
+
+## 一键验收
+
+```bash
+npm run example:no-cluster
+```
+
+预期终端结果：`status` 为“通过”、`kubernetesInvoked` 为 `false`；检查、Workflow、Build Plan、人工触发单、GitOps Apply 和 Verify 均返回独立 Evidence。
+
+## 分步人工检查
+
+```bash
+node bin/idpctl.mjs app inspect \
+  --component-contract "$PWD/fixtures/gitops-app/component-contract.yaml"
+
+node bin/idpctl.mjs workflow verify \
+  --file "$PWD/.examples/no-cluster-delivery/.github/workflows/idp-delivery.yml"
+
+node bin/idpctl.mjs build status \
+  --trigger "$PWD/.examples/no-cluster-delivery/build-trigger.json"
+```
+
+没有 EnvironmentBinding 时，`app inspect` 必须显示开发和构建动作可用、`releaseApply` 被阻塞。人工 Provider 的构建状态必须保持 `waiting-manual`，不得伪造成功。
+
+检查以下产物：
+
+- `.github/workflows/idp-delivery.yml`：最小权限、OIDC、push 与手工触发入口。
+- `build-plan.json`：源码 commit、双架构目标、Component 摘要和整体不可变摘要。
+- `build-trigger.json`：人工触发状态和 Plan 摘要。
+- `idp-gitops/applications/foundation-demo`：由正式 GitOps Renderer 生成。
+- `config/gitops-preimages`：Apply 前状态与恢复证据。
+
+## 清理
+
+```bash
+npm run example:no-cluster -- --clean
+```
+
+## 自动证据
+
+```bash
+npm run check
+```
+
+覆盖：输出覆盖冲突、Component 输入漂移、外部 Provider 未绑定、Workflow 内联长期凭据、GitOps HEAD/Preimage 冲突、Apply 失败恢复、更新和移除。

package/docs/features/developer-delivery-environment-model/DESIGN.md

@@ -0,0 +1,110 @@
+# 开发者交付与三环境模型 DESIGN
+
+- 状态：approved
+- Feature：`idp.developer-delivery-environment-model/v1`
+- 批准依据：用户于 2026-09-01 确认总体方案并要求按推荐方案先落实文档。
+- 范围：定义本地开发、Mac 测试机、阿里云生产环境，以及 `idp`、Dyyto、`idp-deploy` 的稳定边界。
+
+## 1. 目标与非目标
+
+本 Feature 让开发者在没有 Kubernetes 和云资源时完成创建工程、采用工程能力、本地测试、生成交付计划、生成或触发构建、检查制品与渲染 GitOps 变更。环境资源只在执行对应部署动作时成为门禁。
+
+本 Feature 不自研 CI、OCI Registry、Kubernetes、GitOps 控制器、Secret Store、日志或监控系统，也不把本地 kind 当作开发前置条件。
+
+## 2. 三环境
+
+| 环境 | 目的 | 默认执行位置 | Kubernetes | 云服务 |
+| --- | --- | --- | --- | --- |
+| `development` | 编码、脚手架、单元/契约测试、交付预演 | 开发者当前电脑 | 不需要 | 不需要 |
+| `test` | ARM64 构建、集成、GitOps、灰度、回滚验收 | 独立 Mac M4 测试机 | 自动引导的 kind | 不依赖阿里云 |
+| `production` | 正式业务运行 | 阿里云 `cn-shanghai` | ACK | ACR、RRSA；KMS/SLS/ARMS/DNS 按生产门禁启用 |
+
+环境不是单一红绿状态，而是一组带证据的 Capability Binding。资源状态固定为：`not-required`、`deferred`、`missing`、`initializing`、`ready`、`failed`、`offline`。
+
+## 3. CLI 所有权
+
+### 3.1 Dyyto Kernel / CLI
+
+Dyyto 只负责项目内工程能力采用：Catalog、不可变 Plan、Preimage、Apply、Verifier、Renderer、升级、冲突、恢复与移除。它可以修改消费者工程代码，但不构建镜像、不触发发布、不写 GitOps 状态、不操作环境。
+
+### 3.2 `idp-deploy` Kernel / CLI
+
+`idp-deploy` 只负责交付与环境边界：Component Contract、EnvironmentBinding、构建计划、Provider Workflow、OCI digest、GitOps desired state、Release Plan、Evidence、环境验证、部署与恢复。`plan`、`render`、`verify` 必须在没有 Kubernetes 时工作；只有 `release apply` 检查目标环境的部署能力。
+
+### 3.3 `idp` 开发者 CLI
+
+`idp` 是待补齐的薄门面，不建立第三套 Kernel。它负责中文交互、工作区发现和跨 Kernel 编排：
+
+```text
+idp app create       -> 工程模板 + Dyyto 初始化 + idp-deploy 交付合同 + Catalog 描述
+idp capability ...   -> Dyyto Kernel
+idp delivery ...     -> idp-deploy Kernel
+idp environment ...  -> idp-deploy Environment Provider
+```
+
+CLI、AI 和 Portal 后续写入口必须调用相同 Kernel，不得各自重写 Plan/Apply 规则。
+
+## 4. 开发者主链路
+
+```text
+Flow 需求/任务
+  -> Portal 找项目、工作台和环境状态
+  -> idp app create|inspect
+  -> Dyyto plan/apply/verify 工程能力
+  -> 本地 dev/test
+  -> idp-deploy build/release plan
+  -> 人工检查不可变 Plan
+  -> GitHub Workflow 或本地 Builder 构建
+  -> OCI 制品与 Evidence
+  -> GitOps render/verify
+  -> 目标环境未就绪：停在“制品已就绪”
+  -> 目标环境已就绪：提交 GitOps 变更并部署
+```
+
+人工和 AI 只在需求领取、代码产生和 Review 参与者上不同；构建、证据、测试、发布和部署链路完全相同，AI 没有旁路写权限。
+
+## 5. 按动作门禁
+
+| 动作 | Kubernetes | 云资源 | Git Provider |
+| --- | --- | --- | --- |
+| 创建工程、采用能力、本地测试 | 否 | 否 | 可选 |
+| 生成 Workflow、Build Plan、GitOps desired state | 否 | 否 | 否 |
+| 触发/查询 GitHub 构建、提交 GitOps PR | 否 | 否 | 是 |
+| 部署 `test` | Mac 测试集群 | 否 | 是或受管本地源 |
+| 部署 `production` | ACK | 生产 Binding 声明的资源 | 是 |
+
+缺失后置能力时，CLI 必须保留已经完成的 Evidence，输出缺失项和唯一下一步，不得把前面成功的开发/构建阶段标为失败。
+
+## 6. Mac 测试环境 Provider
+
+测试机采用成熟组件：Docker Desktop 或 Colima、kind、本地 OCI Registry、Argo CD、Argo Rollouts、Ingress、cert-manager、metrics-server、PostgreSQL、MinIO 和可选 GitHub Self-hosted Runner。所有镜像必须证明 `linux/arm64`。
+
+Bootstrap 仍遵守 `inspect -> immutable plan -> apply -> verify -> evidence`，并提供 start、stop、remove 和失败恢复。它是测试 Provider，不进入开发者当前电脑的默认 Compose Profile。
+
+## 7. 阿里云生产 Provider
+
+生产 Provider 采用 ACK、ACR、RRSA、KMS/External Secrets、SLS、ARMS、DNS 和正式 TLS。Portal 只显示资源用途、费用提示、初始化入口、Plan 与 Evidence；真实创建由成熟 IaC Provider 完成。未明确预算和不可变 Plan 时不得创建计费资源。
+
+## 8. 安全与事实源
+
+- Manifest、Lock、Repository State 和 Evidence 保持独立。
+- Secret 明文不得进入应用仓库或 GitOps 仓库。
+- Workflow 只描述构建与交付，不拥有运行环境事实。
+- `idp-gitops` 只保存审批后的 Kubernetes desired state。
+- EnvironmentBinding 只声明外部能力引用，不复制 Secret 或云控制台状态。
+- 用户修改、环境漂移和前置条件失败不得被静默覆盖。
+
+## 9. 脚手架与人工验收
+
+正式脚手架必须能够在 `.examples/` 生成一个不依赖 Kubernetes 的应用示例，并给出：固定命令、生成目录、本地页面/终端预期、Build Plan、Workflow、GitOps 渲染结果、人工检查步骤和清理命令。
+
+Mac 测试 Provider 在后续批次提供第二层验收：把同一示例部署到 kind，证明同步、灰度、失败和回滚。生产 Provider 只做 Plan/Verifier，直到真实资源获得授权。
+
+## 10. 完成门禁
+
+1. 三个 CLI 的公共入口均有契约测试，且没有重复 Kernel。
+2. 无 Kubernetes 时可以完成示例的 create、capability、test、build plan、workflow verify 和 gitops render/verify。
+3. 缺失测试/生产资源时返回稳定中文错误码和初始化建议。
+4. Mac 测试 Bootstrap 可重复执行、停止、恢复和移除。
+5. Portal 消费版本化环境就绪快照，不自行推断或执行 shell。
+

package/docs/features/developer-delivery-environment-model/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,46 @@
+# 开发者交付与三环境模型实施计划
+
+- 状态：approved
+- 对应 DESIGN：`idp.developer-delivery-environment-model/v1`
+- 原则：先证明无集群主链路，再增加测试 Provider，最后接入生产 Provider。
+
+## 批次 1：合同与无集群交付内核
+
+1. 盘点 `idp-deploy` 已有 app、binding、release、workflow、GitOps 命令并建立公共命令矩阵。
+2. 补齐纯计算的 inspect、build plan/status contract、gitops render/verify 和稳定错误码。
+3. 将 Kubernetes/云资源检查下沉到对应 `apply`，解除 plan/render/verify 的环境依赖。
+4. 为失败、冲突、恢复、重复执行和用户修改建立 fixture consumer。
+
+## 批次 2：`idp` 薄门面
+
+1. 在所有权确认的位置建立 `idp` CLI，不复制 Dyyto 或 `idp-deploy` Kernel。
+2. 实现 `doctor`、`app create|inspect`、`capability` 委托、`delivery` 委托和统一 Evidence 摘要。
+3. 用正式脚手架在 `.examples/` 生成可运行应用并完成无集群人工验收。
+
+## 批次 3：Portal 开发者入口
+
+1. 补齐工作台、CLI、API、无界面、未启动和未实现六类入口语义。
+2. 增加 development/test/production 环境切换与按能力就绪状态。
+3. 增加缺失资源初始化说明；不在 Portal 中执行 shell 或直接创建付费资源。
+4. 接收 Bench 旧 services/ops 的有效只读能力和受控动作入口，具体矩阵以 Portal Feature DESIGN 为准。
+
+## 批次 4：Mac 测试 Provider
+
+1. 实现机器 inspect、资源预算、端口和 ARM64 前置检查。
+2. 生成不可变 kind 基座 Plan，并完成 apply、verify、stop、start、remove、recovery。
+3. 接入 Registry、Argo CD、Argo Rollouts、Ingress、证书和测试数据服务。
+4. 将 Environment Snapshot 与 Evidence 投影给 Portal。
+
+## 批次 5：阿里云生产 Provider
+
+1. 只读发现现有 ACR、DNS、ACK 和身份状态。
+2. 生成带费用提示的 IaC Plan；未授权时保持 deferred。
+3. 分别验证 ACK/ACR/RRSA、KMS/External Secrets、SLS/ARMS、DNS/TLS。
+4. 生产发布必须通过 digest、Secret、审计、回滚与备份恢复门禁。
+
+## 每批统一验证
+
+- 自动：合同测试、负向 fixture、类型/格式检查、重复执行、CAS 冲突、恢复和移除。
+- 人工：固定脚手架命令、预期中文输出、生成文件检查、页面入口检查和清理。
+- Evidence：记录 Plan digest、输入摘要、执行者、Provider、结果与剩余风险，不记录 Secret。
+