Development

Production source is split across three places: the private Agent/Worker repository, the private Frontend repository, and the desensitized public repository. The public repository is generated one-way by a sanitizer script; do not edit production logic there.

Worker and Frontend

node --test tests/*.test.mjs
node --check app.js
node --check js/admin.js

Full verification before release:

bash test.sh
pnpm run build
pnpm test
pnpm run test:update
pnpm exec wrangler deploy --dry-run --outdir .wrangler-dry-run

pnpm run build prepares Worker Static Assets; never copy old Frontend copies into the build directory. Before deploying, confirm the dry-run lists the expected D1, R2, Durable Object, Assets, and Cron bindings.

Rust Agent

A stable Rust toolchain is required; cross-architecture Linux releases also need the project's Zig/target setup. Minimum checks:

cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

Running locally is not enough to ship. Agent releases must produce static Linux ELF binaries for every supported architecture, update VERSION and SHA256SUMS, and verify the installer's stepwise hash chain.

Configuration and secrets

Public config and secrets are handled separately:

• ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_PATH are required for first deployment.
• After login the admin uses the short-lived x-admin-session; clients must not persist or replay the password.
• Agents and latency nodes use per-node scoped tokens that never appear in the public API.
• DEVELOPER_API_ORIGINS only controls browser reads of /api/v1.
• NQ image-host URL and token are Worker Secrets only; they never enter D1 settings, normal backups, or the frontend.
• Custom URLs must be credential-free HTTPS and pass server-side private/redirect checks.

Use separate Cloudflare resources and test credentials for development. Do not point local previews at the production Admin API, and never accept an arbitrary API base via a URL ?api= parameter.

Changing the public API

/api/v1 is the stable compatibility line:

1. Optional fields and new endpoint capabilities may be added.
2. Within v1, existing fields cannot be silently deleted, renamed, or re-semanticized.
3. New query parameters need defaults, range limits, and normalized cache keys.
4. History endpoints must have caps; 0 or negative values never mean unlimited.
5. Public output must be sanitized for IPs, ports, URL credentials, and internal errors.
6. Browser CORS only echoes exact allowlisted Origins.
7. Update the manifest, endpoint docs, contract tests, and alternate-frontend examples.

Clients should read the /api/v1 manifest for capability discovery instead of guessing from worker_version.

Frontend rules

• Public state and Agent online state are different sources; do not merge into one boolean.
• lite=1 serves first paint; charts load when details open.
• Errors, empty data, and warnings[] must render separately.
• Render API text with textContent or a unified escape helper.
• Check 320, 375, 390, 768, 1280, and 1440 px widths for no page-level horizontal overflow.
• Modals need focus traps, Escape-to-close, background scroll locking, and opener focus restore.
• Bump the content cache key when static assets change, and pin the current entry key in tests.

Agent rules

• Root disk capacity is the system volume, not a sum of mounts; Linux IO uses one consistent accounting level to avoid double counting across partitions, LVM, and physical devices.
• Offline queue writes use restricted permissions, atomic replacement, and fsync; on failure keep dirty.
• Flush before upload ACK, exit, and update restarts.
• Input metrics need type, range, and time-window validation.
• Install, update, and rollback preserve binary ownership, exec permissions, and the SHA-256 chain.
• Fixed NQ/IP actions accept only compiled-in action enums; never extend them into arbitrary commands, URLs, arguments, or schedules.

Versioning and release

The application, Worker, documentation, and Agent share one numeric version. Stable versions increment decimally: patch 1.1.93, next minor 1.2.0; never roll over to 1.0.99.

App/Worker/docs: 1.1.93
Agent: v1.1.93
App source tag: app-v1.1.93
Agent tag/release: v1.1.93

Never overwrite a published binary of the same version or move public tags. Bump the version before release-level changes, then test, build, generate checksums, and create release assets locally. Pure documentation fixes may keep the product version but should state that runtime is unchanged.

The public repository is the only source snapshot, update manifest, and release distribution entry point for self-hosters; the private Agent/Worker and Frontend repositories are the production sources, exported one-way through the sanitizer. Public one-click builds download the release pinned by update-manifest.json; production Agents install and update from the deployed site's /bin and never query the GitHub API.

Release and deployment flow

1. Local gate: bash test.sh runs the full Worker, frontend, and installer-manifest suite; agent/build-release.sh builds the seven-architecture binaries and writes bin/VERSION plus bin/SHA256SUMS.
2. Hash chain: new digests go into setup.sh/update.sh (SHA256SUMS_SHA256), then install.sh/quick-install.sh (DEFAULT_SETUP_SHA256), and finally into the installer-manifest tests and the admin install-command template.
3. Release: commit and push the private Agent repository with tag vX.Y.Z and a GitHub Release carrying the seven build assets → commit and tag the frontend repository → export the public snapshot one-way and mirror the vX.Y.Z/app-vX.Y.Z tags plus release assets into the public repository (the one-click deploy and online update depend on them) → deploy with worker/deploy.sh → verify production with scripts/smoke-prod.mjs.
4. Self-hosted updates: one-click deployments enable the NIE-SLA Online Update workflow, which checks the official stable release every six hours; trigger one immediately with Run workflow in the deployment repository's Actions tab. If a deployment stays behind, follow the FAQ "The panel shows a new version but nothing ever updates"; without Actions, sync the repository and run npm run deploy.

Pre-commit checklist

• Working tree contains only files in scope.
• Tests, formatting, lint, dependency audit, and production build pass.
• Worker changes pass a Wrangler dry-run.
• Frontend passes desktop/mobile page checks.
• Public export passes the secret scan and is generated one-way from private sources.
• Version, manifest, tag plan, Agent VERSION, and documentation agree.
• No development logs, caches, build temp dirs, or secrets are committed.

For alternate frontends only, a full Worker fork is unnecessary; see API Integration. For visual-only changes, use Themes.