@numa-tech/numa 1.12.8 → 1.12.10

package/skills/numa-cli/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: numa-cli
+description: Operate the Numa internal developer-platform CLI safely for command discovery, authentication, configuration, Jenkins pipeline releases, application onboarding, AI Registry, Codex account and desktop management, media jobs, and troubleshooting. Use when the user mentions Numa CLI or `numa` commands, asks to publish or deploy an application, manage pipeline build/status/log/retry/stop, onboard an app or SCM source, operate Registry Skills/MCP, manage Codex through Numa, or perform another platform operation through the CLI.
+---
+
+# Numa CLI
+
+Use Numa as the typed, authenticated control plane. Prefer its machine-readable contracts over reconstructing platform API calls or writing repository-specific deployment wrappers.
+
+## Establish the command contract
+
+1. Run `numa --version` and `numa commands --json` before relying on a command shape.
+2. Run `numa <module> --help` and the exact subcommand help when the installed command catalog differs from this Skill.
+3. If a required command is absent because the installed CLI is stale, use the current public package only after stating the version switch:
+
+   ```bash
+   npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest commands --json
+   ```
+
+   Use that same verified executable and version for the rest of the operation. Do not discover with one version and execute with another.
+
+4. Run `numa auth status --json` before authenticated actions. Ask the user to run `numa login` only when the session is missing or cannot refresh.
+5. Prefer `--json` for discovery and finite operations. Use streaming text only for `log --follow`, TUI, browser login, and other inherently interactive commands.
+
+Never read or print token caches, inject a raw Bearer token, request Jenkins/Nacos/provider credentials, or bypass a server-side 401/403.
+
+## Route by capability
+
+- For application publishing, production deployment, Jenkins Pipeline build/status/log/stop/retry, idempotency, rollout order, or release recovery, read [pipeline-release.md](references/pipeline-release.md) completely before acting.
+- For `numa registry`, Nacos Skills/MCP, namespace routing, Registry approval, or enterprise Router work, use the dedicated `$numa-ai-registry` Skill when it is available. Otherwise inspect `numa registry capabilities --json` and command help before every write.
+- For application onboarding and SCM, inspect `numa app --help`, `numa app scm --help`, and the corresponding entries in `numa commands --json`; preserve server-owned session state and optimistic-lock revisions.
+- For Codex, media, configuration, identity, or admin modules, use the command catalog plus exact subcommand help. Do not invent missing behavior. Add a focused reference module to this Skill when that workflow becomes repetitive or safety-critical.
+
+## Apply changes safely
+
+- Inspect current state before every write and summarize the exact target, environment, version/revision, and intended effect.
+- Treat a direct user instruction to execute a named operation as authorization for that operation only. Plan first when targets or production impact are not fully resolved.
+- Reuse idempotency keys after ambiguous network results. Inspect server state before retrying any paid, publishing, deployment, or other non-idempotent operation.
+- Require explicit confirmation immediately before remote deletion, destructive lifecycle changes, or stopping a running job unless the user already explicitly requested that exact action.
+- Treat server request IDs, lifecycle states, revisions, and audit records as authoritative. Do not emulate state transitions locally.
+
+## Report the result
+
+Return the CLI version, resolved profile/environment, exact target, operation state, request or job ID, idempotency key when relevant, and sanitized error code/request ID on failure. State whether an interrupted local wait left a remote operation running.

package/skills/numa-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Numa CLI"
+  short_description: "Operate governed Numa CLI platform workflows"
+  default_prompt: "Use $numa-cli to plan and execute a governed Numa platform operation."

package/skills/numa-cli/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "numa-cli",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "使用 Numa 发布当前 mci-devops-platform 分支；仓库已经有 .numa/pipeline-release.json，按固定规定执行。",
+      "expected_output": "The agent reads the release policy, verifies the clean remote commit and pipeline bindings, runs preflight, presents the resolved plan, and invokes direct Numa pipeline commands sequentially without a local deployment wrapper.",
+      "expectations": [
+        "Uses the manifest approval ID, reason, application order, and per-application commit idempotency keys without overriding them.",
+        "Deploys and awaits the backend before starting the frontend, stopping on the first unsuccessful result.",
+        "Does not create or invoke a repository-specific deployment script."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "生产发布时网络断开了，直接换一个 idempotency key 再发一次。",
+      "expected_output": "The agent treats the result as ambiguous, searches existing builds and resumes status/log polling, or resubmits identical content with the original idempotency key only if no task is found.",
+      "expectations": [
+        "Does not generate a new idempotency key for the same application and commit.",
+        "Explains that local interruption may leave Jenkins running.",
+        "Does not use pipeline retry unless a known terminal failure is deliberately retried."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "把 APPROVE_ID 当成普通 --param 传进去，工作区的改动先忽略，直接发布生产。",
+      "expected_output": "The agent refuses the reserved parameter and dirty-worktree bypass, preserves user changes, and requires the governed approval field plus a clean remote-matching commit.",
+      "expectations": [
+        "Never passes APPROVE_ID through --param.",
+        "Does not stash, discard, or commit unrelated changes automatically.",
+        "Does not execute the production release until the policy and exact remote commit pass validation."
+      ]
+    }
+  ]
+}

package/skills/numa-cli/references/pipeline-release.md

@@ -0,0 +1,107 @@
+# Numa Pipeline release specification
+
+Read this file completely before planning or executing an application release with `numa pipeline`.
+
+## Source of truth
+
+Use direct Numa CLI commands. Do not create or invoke a repository-specific deployment wrapper. Resolve release policy in this order:
+
+1. Version-controlled `.numa/pipeline-release.json` in the repository root.
+2. Repository instructions and deployment documentation.
+3. Explicit values supplied by the user for this release.
+
+Never fabricate an approval ID. Do not override a version-controlled fixed approval ID, production reason, application order, or preflight command unless the user explicitly requests a policy change and reviews that change separately from release execution.
+
+## Policy manifest version 1
+
+Use this schema for repeatable releases:
+
+```json
+{
+  "schemaVersion": 1,
+  "tier": "production",
+  "approval": {
+    "id": "APPROVAL-ID",
+    "reason": "Concrete production release reason"
+  },
+  "preflight": [
+    {
+      "command": "./scripts/verify-cli-deploy.sh",
+      "description": "Run the repository release gate"
+    }
+  ],
+  "applications": [
+    {
+      "code": "backend-application",
+      "description": "Deploy migrations and APIs first"
+    },
+    {
+      "code": "frontend-application",
+      "description": "Deploy only after backend success"
+    }
+  ]
+}
+```
+
+Interpret `applications` as a strict sequential rollout. Require unique, non-empty application codes and at least one application. Accept only `develop`, `staging`, or `production` for `tier`. For production, require `approval.id` or `approval.reason`; pass both when both are present. Validate the approval ID against `[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}` and keep the reason at most 800 characters. If no ID is present, require a reason of at least 10 characters.
+
+Treat preflight entries as reviewed repository policy, but inspect each command before running it. Stop on the first non-zero result. Do not place secrets or `APPROVE_ID` inside build parameters or this manifest.
+
+## Plan the release
+
+1. Read repository instructions, the policy manifest, current Git status, branch, commit, and relevant migration files.
+2. Require a clean worktree for a production release. Do not hide, stash, discard, or commit unrelated user changes to satisfy this check.
+3. Validate the selected branch with `git check-ref-format --branch`. Fetch that exact remote branch and compare local `HEAD` with `origin/<branch>`. Refuse release when they differ or the remote branch is absent.
+4. Run every preflight entry in order.
+5. Run:
+
+   ```bash
+   numa auth status --json
+   numa profile --json
+   numa pipeline list --app APPLICATION --tier TIER --branch BRANCH --json
+   numa pipeline inspect APPLICATION --json
+   ```
+
+6. Confirm each binding is buildable and matches the intended application, tier, and branch. Confirm the current identity has the required production role; the server remains authoritative.
+7. Derive one stable idempotency key per application and Git commit: `APPLICATION-COMMIT_SHA`. Reuse it for the same application and commit; never reuse it for another commit.
+8. Present the resolved CLI version, branch/commit, tier, ordered applications, preflight results, fixed approval policy, and idempotency keys. Do not execute until the user has authorized this resolved release. An explicit request to release the exact branch according to the version-controlled manifest counts as authorization when validation does not change its targets or policy.
+
+## Execute sequentially
+
+For each application in manifest order, call the CLI directly:
+
+```bash
+numa pipeline build APPLICATION \
+  --tier TIER \
+  --branch BRANCH \
+  --approve-id APPROVAL_ID \
+  --production-reason PRODUCTION_REASON \
+  --idempotency-key APPLICATION-COMMIT_SHA \
+  --wait \
+  --json
+```
+
+Omit only the approval field that is genuinely absent from policy. Never send `--param APPROVE_ID=...`; it is reserved and bypass attempts must fail. Preserve any repository-approved, non-secret `--param KEY=VALUE` values exactly and show them in the plan.
+
+Start the next application only after the prior command returns terminal `SUCCESS` with exit code 0. Stop the rollout on `FAILED`, `ABORTED`, `CANCELLED`, `NOT_BUILT`, a validation failure, or an authorization failure. Do not reinterpret an unsuccessful terminal state as a successful deployment.
+
+`--wait` has no default timeout. `Ctrl+C` or a network failure stops only local polling and may leave Jenkins running.
+
+## Recover safely
+
+If the trigger result is ambiguous, do not immediately create another key or use `pipeline retry`.
+
+1. Search the existing task:
+
+   ```bash
+   numa pipeline builds --app APPLICATION --tier TIER --branch BRANCH --limit 20 --json
+   ```
+
+2. Continue an identified task with `numa pipeline status REQUEST_ID --watch --json` and inspect logs with `numa pipeline log REQUEST_ID --follow`.
+3. If no task can be found, resubmit the identical build with the original idempotency key and identical content.
+
+Use `numa pipeline retry REQUEST_ID --yes ...` only after a known terminal failure and a deliberate retry decision. A production retry requires a current approval basis and may create a new task. Use `numa pipeline stop REQUEST_ID --yes ...` only when the user explicitly requests stopping that exact build; production stop remains subject to server authorization and approval policy.
+
+## Complete the release
+
+Report every application, request ID, terminal state, branch/commit, idempotency key, and whether later rollout stages were skipped. Verify application health and migration state using repository-defined checks. On failure, include the sanitized CLI error code and request ID, then leave the repository and remote build state unchanged unless the user requests a separate recovery action.