@tutti-os/nexight-devops 0.5.0

package/README.md

@@ -0,0 +1,237 @@
+# @tutti-os/nexight-devops
+
+`nexight-devops` is a TypeScript CLI for Nexight DevOps workflows.
+
+## Install
+
+```bash
+npm install -g @tutti-os/nexight-devops
+```
+
+## Commands
+
+```bash
+nexight-devops --help
+nexight-devops --version
+nexight-devops doctor
+nexight-devops onboard
+nexight-devops onboard --set-mode aws
+nexight-devops onboard --set-mode gh
+nexight-devops onboard --set-mode locale
+nexight-devops onboard --set-mode admin
+nexight-devops onboard --set-mode datafinder
+nexight-devops update-version
+nexight-devops admin auth login
+nexight-devops admin auth whoami
+nexight-devops admin system health
+nexight-devops admin app list --brand nextop --query design
+nexight-devops admin app detail --brand nextop --app-id vibe-design --include latest,versions
+nexight-devops admin computer list --connection online --query <name>
+nexight-devops admin computer list --connection online --owner-query <username-or-email>
+nexight-devops admin computer detail --computer-id <computer-id>
+nexight-devops admin computer logs <computer-name-or-id> --range 1h
+nexight-devops admin computer logs --owner-query <username-or-email> --range 1h
+nexight-devops admin computer logs <computer-name-or-id> --from <timestamp> --to <timestamp>
+nexight-devops admin computer log-recall list --computer-id <computer-id>
+nexight-devops admin computer log-recall download --computer-id <computer-id> --task-id <task-id>
+nexight-devops datafinder auth check
+nexight-devops datafinder dashboard export --count 100
+nexight-devops datafinder query shared-agent-summary --count 100
+nexight-devops datafinder query p2p-health --count 100
+nexight-devops datafinder query exec ./query.mjs -- arg1 arg2
+nexight-devops diagnose shared-agent --room-id <room-id> --at '2026-08-12T12:00:00+08:00'
+nexight-devops diagnose shared-agent --room-id <room-id> --at '2026-08-12T12:00:00+08:00' --json
+nexight-devops ppe-lane deploy
+nexight-devops ppe-lane destroy
+nexight-devops ppe-lane status
+nexight-devops ppe-lane status --all
+nexight-devops release prepare
+nexight-devops release hotfix
+nexight-devops release approve
+nexight-devops release rollback tutti-server
+```
+
+### Function overview
+
+- `doctor` checks that the CLI can start.
+- `onboard` installs or configures Homebrew, GitHub CLI authentication, AWS SSO, management backend login, DataFinder OpenAPI, and the CLI locale. Use `--set-mode <mode>` to configure only one integration.
+- `update-version` checks npm for a newer CLI version and upgrades it with the detected package manager.
+- `admin auth` logs into, logs out of, and inspects the management backend token.
+- `admin system health` checks management backend health.
+- `admin app list/detail` queries App Center applications and optionally their versions.
+- `admin computer list/detail` finds Tutti Computers and reports their current connection state.
+- `admin computer logs` resolves an online Computer and bundles recall, polling, and temporary download into one Agent-friendly workflow.
+- `admin computer log-recall` exposes the lower-level task operations for troubleshooting and recovery.
+- `datafinder` validates access, reads dashboards/reports, runs trusted local JavaScript queries, and exposes fixed reliability queries.
+- `diagnose shared-agent` runs a bounded, read-only CloudWatch playbook that correlates room descriptor results, Owner lease observations, client version, and HTTP failures. It verifies the production AWS account before querying and supports stable `--json` output.
+- `ppe-lane deploy` deploys selected backend repositories and the optional `zk-web/canvas` staging artifact to a PPE lane.
+- `ppe-lane destroy` checks existing lane instances and triggers destroy workflows after a lane-name confirmation.
+- `ppe-lane status` queries AWS Cloud Map for one lane, or all lanes with `--all`.
+- `release prepare`, `release hotfix`, and `release approve` run the controlled release lifecycle through GitHub Actions and approval issues.
+- `release rollback tutti-server` lists the current production image and recent successful Helm deployments (up to ten entries), then restores a selected image through GitHub Actions and waits for health checks. Use `--revision <number> --yes` for scripted selection and confirmation.
+
+## Controlled Release
+
+```bash
+nexight-devops release prepare
+nexight-devops release hotfix
+nexight-devops release approve
+```
+
+- `release prepare` starts a controlled release for a target repo and creates the approval issue.
+- `release hotfix` starts a controlled hotfix flow and supports an explicit override when release-branch patches have not yet been absorbed by `main`.
+- `release approve` posts the approval command to the pending release issue and advances the release.
+
+## Management Backend
+
+`admin auth login` stores the verified token in the CLI config with `0600` permissions. The API origin defaults to `https://tutti.sh`; an `admin.tutti.sh` page URL is normalized automatically. For CI or temporary access, use `NEXIGHT_ADMIN_TOKEN` or `TUTTI_ADMIN_TOKEN`, and optionally `NEXIGHT_ADMIN_URL` or `TUTTI_ADMIN_URL`.
+
+Read-only query commands accept `--json` for undecorated JSON output.
+
+### Tutti Computer runtime logs
+
+The recommended command takes an exact Computer name or ID, or an owner username/email query, and an optional suspicious interval. An owner query must resolve to exactly one online Computer before recall starts. The command resolves the unique online Computer, selects the smallest backend range that covers the interval, creates the recall, waits for the device, downloads the result to a unique `/tmp` directory, and returns the artifact path:
+
+```bash
+nexight-devops admin computer logs "liyingdeMacBook-Pro.local" \
+  --from "2026-09-01T10:30:00+08:00" \
+  --to "2026-09-01T11:00:00+08:00" \
+  --json
+```
+
+For a user-owned Computer, use the server-supported owner directory query:
+
+```bash
+nexight-devops admin computer logs \
+  --owner-query "rv4no" \
+  --from "2026-09-01T10:30:00+08:00" \
+  --to "2026-09-01T11:00:00+08:00" \
+  --json
+```
+
+`--from` and `--to` require an explicit timezone offset or `Z`; `--to` defaults to now. The backend supports fixed trailing ranges (`1h`, `3h`, `1d`, `3d`, and `14d`), so the downloaded archive can include additional logs between the suspicious interval and the current time. When no interval is available, use `--range`, which defaults to `1h`:
+
+```bash
+nexight-devops admin computer logs <computer-name-or-id> --range 3h
+```
+
+The command writes elapsed-time progress lines to stderr while resolving the Computer, creating the task, waiting for device state changes, and downloading. `--json` keeps the final structured result on stdout, so Agents can observe progress without corrupting machine-readable output. The result never exposes the pre-signed storage URL or internal object key.
+
+Use the lower-level task commands only when a recall needs to be created asynchronously, inspected, resumed, or downloaded to a specific path:
+
+```bash
+nexight-devops admin computer log-recall create --computer-id <computer-id> --range 1h
+nexight-devops admin computer log-recall list --computer-id <computer-id>
+nexight-devops admin computer log-recall get --computer-id <computer-id> --task-id <task-id>
+nexight-devops admin computer log-recall download --computer-id <computer-id> --task-id <task-id>
+```
+
+## Shared Agent diagnosis
+
+```bash
+nexight-devops diagnose shared-agent \
+  --room-id <room-id> \
+  --at '2026-08-12T12:00:00+08:00' \
+  --shared-agent-id <shared-agent-id>
+```
+
+The default query window is 30 minutes centered on `--at`, capped at the current time. Use `--window-minutes` to change it; the command rejects windows over 24 hours. When an issued descriptor exposes the Owner device, the playbook derives the same pseudonymous reference as `tsh-server` and joins sampled Owner lease evidence without requiring an Owner diagnostics bundle. `--owner-device-id` or `--authority-id` can provide the join key when it is already known.
+
+The command is read-only. It returns partial results and explicit missing-evidence reasons when a secondary query fails or the Owner identity cannot be derived. Raw log lines are not included in the result.
+
+## Development
+
+- Node.js 20+
+- `pnpm install`
+- `pnpm lint`
+- `pnpm typecheck`
+- `pnpm dev -- --help`
+- `pnpm test`
+- `pnpm build`
+
+## CLI publishing
+
+The [Publish CLI](.github/workflows/publish-cli.yml) workflow checks pull requests and publishes `@tutti-os/nexight-devops` to npm after a successful push to `main` (including a merged pull request). It runs lint, type checking, tests, build, and CLI smoke checks before publishing. The publish job is serialized so two merges cannot choose the same npm version.
+
+For the first publish, an npm user with write access to the `@tutti-os` scope must add a GitHub Actions repository secret named `NPM_TOKEN`. The token must allow direct publishing to that scope and unattended publishing when npm requires 2FA. The package is currently configured as public. Once the first version exists, the package owner can configure an npm trusted publisher for the `tutti-lab/nexight-devops` repository and `publish-cli.yml` workflow; the workflow already grants OIDC permission, so the token can then be removed.
+
+`package.json` supplies the minimum release version. The first publish uses that version; later merges publish the next patch version above npm's current `latest`. To intentionally bump the minor or major version, raise `package.json` above the published version in the pull request. Re-running a workflow for a commit already published by this workflow skips publishing it again.
+
+## DataFinder OpenAPI
+
+Run focused onboarding once. The CLI validates the credentials against the
+selected dashboard before saving them to the existing CLI config file, which is
+written with `0600` permissions.
+
+```bash
+nexight-devops onboard --set-mode datafinder
+nexight-devops datafinder auth check
+```
+
+For temporary or CI use, these environment variables override stored values:
+`DATAFINDER_AK`, `DATAFINDER_SK`, `DATAFINDER_PROJECT_ID`,
+`DATAFINDER_APP_ID`, `DATAFINDER_DASHBOARD_ID`, `DATAFINDER_BASE_URL`, and
+`DATAFINDER_TIMEZONE`. `DATAFINDER_PATH_MODE` accepts `project` or `app`.
+
+The default `project` path mode targets SaaS cloud-native projects. Select
+`app` during onboarding for legacy SaaS or private deployments that expose
+app-ID paths. The API origin must be a plain HTTPS origin without credentials,
+paths, query parameters, or fragments.
+
+### Dashboard and report queries
+
+```bash
+nexight-devops datafinder dashboard get
+nexight-devops datafinder dashboard export --count 100 --output dashboard.json
+nexight-devops datafinder report list
+nexight-devops datafinder report get <report-id> --count 100
+```
+
+The two initial fixed internal queries resolve the default dashboard by stable
+report ID, with exact-name fallback for copied dashboards, and return the saved
+DataFinder query results:
+
+```bash
+nexight-devops datafinder query shared-agent-summary --count 100
+nexight-devops datafinder query p2p-health --count 100
+```
+
+### Generic JavaScript queries
+
+`query exec` loads a local `.js`, `.mjs`, or `.cjs` module. The module must
+default-export a function and receives `{ client, config, args }`. `config`
+contains only non-secret connection metadata. The client exposes
+`getDashboard`, `listDashboardReports`, `getReportData`, `exportDashboard`,
+`analysis`, and the lower-level `request` method.
+
+```js
+export default async function query({ args, client, config }) {
+  const [reportId, count = '1000'] = args;
+  return {
+    projectId: config.projectId,
+    data: await client.getReportData(reportId, Number(count)),
+  };
+}
+```
+
+```bash
+nexight-devops datafinder query exec ./query.mjs -- <report-id> 100
+```
+
+Query modules execute as trusted local Node.js code; this command is not a
+sandbox. Review generated modules before running them. Use `--output <path>` to
+write JSON with `0600` permissions instead of printing it.
+
+### Development demo
+
+The standalone development demo reuses the production DataFinder client and
+exports the configured dashboard. Its defaults point to the `Shared Agent 可靠性`
+dashboard.
+
+```bash
+pnpm demo:datafinder -- --credentials /path/to/AccessKey.txt
+```
+
+The credentials file must contain `AccessKeyId` and `SecretAccessKey`. You can
+instead set `DATAFINDER_AK` and `DATAFINDER_SK`. Run the demo with `--help` to
+override the project, app, dashboard, API origin, or per-report result limit.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,10 @@
+# Third-party notices
+
+This project uses `@datafinder/openapisdk` from
+[`volcengine/datafinder-sdk-openapi-js`](https://github.com/volcengine/datafinder-sdk-openapi-js),
+pinned to commit `1e8aef76cd1fc29d73bce99e1470253ed898ed0b`.
+
+Copyright 2020 Beijing Volcano Engine Technology Co., Ltd.
+
+Licensed under the Apache License, Version 2.0. A copy of the license is
+available at <https://www.apache.org/licenses/LICENSE-2.0>.

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+
+declare const createProgram: () => Command;
+declare const main: (argv?: string[]) => Promise<void>;
+
+export { createProgram, main };