Harness Data npm installer

Prerequisites

• Node.js 18+
• Git (on PATH)
• tar (on PATH; retained for historical .tar.gz Release fallback, and bundled with Git for Windows on Windows)
• unzip (on PATH on every supported platform; not bundled with Git for Windows by default. Install via MSYS2 (pacman -S unzip) or copy from an MSYS2 installation into a PATH directory. The installer checks for unzip and will stop with missing required command: unzip if it is absent.)
• Windows only — additional requirements:
  • Agent selection — Windows defaults to Codex and also supports explicit WorkBuddy; other Agents are not available on Windows.
  • Authorization required — Every install enables authorization. WorkBuddy auth is supported on macOS and Windows; use another Agent on unsupported platforms.
  • Windows x64 + ARM64 are both supported.

Install a Harness Data runtime in the current directory:

npx @lumi-ai-lab/harness-data install

Install into an explicit runtime directory:

npx @lumi-ai-lab/harness-data install --dir /path/to/runtime

Recommended latest install from Gitee (Linux/macOS):

npx -y @lumi-ai-lab/harness-data@latest install \
  --release-source gitee \
  --dir ~/qdm-harness-data/harness-data-runtime \
  --agent codex \
  --auth-blob 'qdm1enc...' \
  --auth-user-id 'your-user-id' \
  --yes

PowerShell:

npx -y @lumi-ai-lab/harness-data@latest install `
  --release-source gitee `
  --dir "D:\qdm-harness-data\harness-data-runtime" `
  --agent codex `
  --auth-blob "qdm1enc..." `
  --auth-user-id "your-user-id" `
  --yes

Development administrator install (do not combine --dev with auth Blob flags):

npx -y @lumi-ai-lab/harness-data@latest install \
  --release-source gitee \
  --dir ~/qdm-harness-data/harness-data-runtime \
  --agent codex \
  --dev \
  --dev-password 'PASSWORD' \
  --yes

Release ZIP password is built into the installer. install and update do not prompt for it and do not require HARNESS_RELEASE_PASSWORD. There is intentionally no --release-password option. During extraction the installer invokes unzip with a redacted sensitive argument; the password is never written to installer state, configuration, logs, or errors. Releases use traditional password ZIP encryption as an access barrier only; it is not strong confidentiality against a determined recipient.

Release downloads default to auto: the installer first checks the mirrored Gitee Release for the exact required uploaded ZIP, then falls back to GitHub only when the Gitee Release is unavailable or missing that asset. Choose a provider explicitly with --release-source auto|gitee|github or HARNESS_RELEASE_SOURCE:

npx @lumi-ai-lab/harness-data install --release-source gitee
HARNESS_RELEASE_SOURCE=github npx @lumi-ai-lab/harness-data update

Gitee mirrors data-harness-cli, the runtime, and harness-data-wikis-<tag>.zip from git_pengmd/harness-release, and qdm-metric-cli from git_pengmd/harness-metric-release. Only normal Release attachments with the exact expected filename are selected; source archives are never used.

Use a GitHub token for private GitHub Release assets:

npx @lumi-ai-lab/harness-data install --github-token ...

or:

GITHUB_TOKEN=... npx @lumi-ai-lab/harness-data install

Metric data-auth is enabled by default. Interactive install prompts for the encrypted Blob and dev_user_id:

npx @lumi-ai-lab/harness-data install

For non-interactive installs, pass flags or environment variables:

npx @lumi-ai-lab/harness-data install \
  --auth-blob 'qdm1enc...' --auth-user-id 'your-user-id' --yes

HARNESS_AUTH_BLOB='qdm1enc...' HARNESS_AUTH_USER_ID='your-user-id' \
npx @lumi-ai-lab/harness-data install --yes

Register the development administrator through qdm-metric-cli dev:

npx @lumi-ai-lab/harness-data install --dev
npx @lumi-ai-lab/harness-data install --dev --dev-password 'PASSWORD' --yes

Use the built-in fixture for development and testing:

npx @lumi-ai-lab/harness-data install --data-auth

The same auth parameters support --agent workbuddy on macOS and Windows. WorkBuddy auth is rejected on other platforms; use another Agent there. User-provided Blobs and the fixture working copy are stored at config/dev-auth.blob with mode 0600.

The shipped config/fixtures/local-test-auth.blob is used as local fallback (dev_user_id: local-test-user). For the Codex App or terminal scenario, admins can distribute a real encrypted blob file to each user outside the workspace and users bind it with HARNESS_AUTH_BLOB_FILE + HARNESS_AUTH_USER_ID; keep authz.allow_local_blob: true for this mode. Codex uses PreToolUse hook to inject auth; the hook reads the local blob and rewrites gated qdm-metric-cli commands directly. When authz.mode=on, ordinary Codex Bash commands are rewritten by the hook to unset auth source env (HARNESS_AUTH_BLOB, HARNESS_AUTH_BLOB_FILE, HARNESS_AUTH_USER_ID, LUMI_REQUESTER_CONTEXT_DIR) before execution. LUMI_REQUESTER_CONTEXT_DIR is no longer read but is still scrubbed for legacy safety. When authz is off, the hook passes every Bash command through unchanged.

With auto or gitee, the runtime, Wikis, and both CLI tools can be installed from a complete Gitee mirror without a GitHub token or a local harness-data-wikis copy. With --release-source github, the existing private GitHub restriction remains: the installer asks for a local qdm-metric-cli path when GitHub auth is unavailable. Data queries use only qdm-metric-cli (qdm-cmr-cli / qdm-indicators-cli / qdm-sql-cli / cas-cli are no longer installed).

Update an existing runtime interactively:

npx @lumi-ai-lab/harness-data update

Diagnose a runtime:

npx @lumi-ai-lab/harness-data doctor

The runtime is assembled from the harness-data runtime bundle, platform-specific CLI Release assets (data-harness-cli, qdm-metric-cli), the version-matched harness-data-wikis Release ZIP, generated local config, selected Agent symlinks, and the WorkBuddy plugin package.

Supported Release platforms are Windows x64, Windows ARM64, Linux x64, and Apple Silicon macOS. Intel macOS (darwin-amd64) is no longer supported.

--agent supports claude, codex, pi, openclaw, hermes, workbuddy, both, and all. both remains Claude + Codex. Until the project-owned WorkBuddy desktop E2E matrix passes, all keeps its existing Claude + Codex + Pi + OpenClaw + Hermes semantics; choose --agent workbuddy explicitly. On Windows, only codex is available and is auto-selected.

WorkBuddy auth requires Desktop 5.3.11+ with embedded CodeBuddy CLI 2.115.0+. The installer prepares a local Marketplace at agents/.codebuddy-plugin/marketplace.json whose qdm-harness plugin source is agents/workbuddy; it does not edit WorkBuddy settings or Marketplace registration. In WorkBuddy's plugin manager, choose Add Marketplace, select the runtime's agents directory, install and enable qdm-harness@lumi-harness-data, reload plugins, and start a new conversation in the Harness runtime workspace. Marketplace/package presence, plugin enablement, runtime versions, and auth source are reported separately by doctor.

On macOS and Windows, authz.mode=on is enforced by a fail-closed PreToolUse hook. For managed macOS credentials, set HARNESS_AUTH_BLOB_FILE and HARNESS_AUTH_USER_ID with launchctl, keep the Blob outside the workspace with mode 0600, restart WorkBuddy, and run doctor. Windows QDM data commands must use Bash; gated PowerShell commands are denied before credentials are read. Direct injection places the encrypted Blob in updatedInput.command, so this mode is limited to local validation or controlled pilots until a credential-isolated integration is available.