honua-migrate

Command transition: honua-migrate assess is now the primary assessment surface. The honua-esri-assess command, module invocation, Python imports, and artifact contracts remain compatible through the documented transition window, with removal no earlier than honua-migrate 1.2. See the assessment transition policy.

An Apache-2.0 migration command-line suite whose read-only assessment surface inventories an organization's Esri footprint — ArcGIS Online, ArcGIS Server / Enterprise, and FileGDB workspaces — and produces a versioned EsriFootprint.json artifact plus human-readable Markdown reports: a readiness report, a per-shop-profile migratability verdict, and a crosswalk from that footprint to Honua capability keys. It exists so GIS teams can size a migration to Honua (or simply audit their own estate) before committing to anything. The suite is Apache-2.0 by design so your security team can audit every line before pointing it at production.

Assessment is read-only and no-phone-home, verifiably

The assessment surface is built for skeptical review. The guarantees below are enforced in code and by tests in this repository — not just promised:

• Strictly read-only assessment. Every request against an Esri system is an HTTP GET. The HTTP wrappers expose no write helpers; no POST/PUT/DELETE/ PATCH is ever issued.
• No network telemetry. No usage pings, crash uploads, or update checks — there is not even an opt-in sink. The only hosts ever contacted are the --target you supply to scan, or the crosswalk URL you explicitly pass to caps --crosswalk (never fetched by default — see Capability crosswalk below). Enforced by tests/test_no_telemetry.py and tests/smoke/test_no_network.py, which fail CI if outbound traffic appears.
• It mints no credentials. You run it anonymously or hand it a pre-existing token via --token-env VAR (an environment variable name). There is deliberately no --token flag, no username/password input, and no generateToken call.
• Secrets never leak into outputs. Tokens, query strings, and URL userinfo are redacted from logs and are never written into artifacts or diagnostics.
• It never opens your databases. Storage information comes from documented ArcGIS REST metadata only — no ArcSDE/DBMS connections, no GDB internals.
• Everything stays on your machine. Artifacts are written to local files (or stdout). Nothing is uploaded anywhere.

Before running against production, see Prerequisites & least-privilege access for the exact endpoints read at each access tier and the minimum privileges to grant. An anonymous "Tier 1" scan needs no credentials at all.

Status

Alpha, pre-1.0 (current source version 0.7.x — see the CHANGELOG). The EsriFootprint.json schema is at v0.2 and unstable until v1.0: breaking changes are permitted between v0.x minors, per the versioning policy. An installed command's --version output is the authoritative application version.

Quick start

Requires Python 3.11+.

Install the application in an isolated environment:

pipx install honua-migrate
honua-migrate assess --help
honua-esri-assess --help  # supported compatibility command

For development against an unreleased source checkout:

git clone https://github.com/honua-io/honua-migrate
cd honua-migrate
python3 -m pip install .

Scan an ArcGIS Online org (anonymous scans work too — just omit the token):

export AGOL_TOKEN="..."   # optional, pre-existing token
honua-migrate assess scan agol \
  --target https://yourorg.maps.arcgis.com/sharing/rest \
  --token-env AGOL_TOKEN \
  --output EsriFootprint.json \
  --validate

Then render the human-readable companions:

honua-migrate assess report  --input EsriFootprint.json --output readiness-report.md
honua-migrate assess verdict --input EsriFootprint.json
honua-migrate assess caps    --input EsriFootprint.json

Inspect or validate against the bundled schema at any time:

honua-migrate assess schema show
honua-migrate assess schema validate EsriFootprint.json

Commands

Run honua-migrate --help for the complete migration command tree, or honua-migrate assess --help for assessment options. The compatibility forms honua-esri-assess --help and python -m honua_esri_assess --help remain available. Every assessment scan subcommand is read-only against the target.

Common scan options: --output (default ./EsriFootprint.json; existing files are not overwritten unless you pass --force), --token-env VAR, --validate, --timeout, --max-retries, --user-agent, --log-format text|json, --log-level. report, verdict, and caps accept --input - / --output - for stdin/stdout and --strict to fail on schema-invalid input instead of rendering warnings.

Capability crosswalk (caps)

caps maps the same deterministic capability detection the verdict engine uses (honua_esri_assess.verdict.registry — portal item types, server serviceTypes, and per-service capability tokens already in EsriFootprint.json) onto Honua capability keys, via a versioned crosswalk document:

honua-migrate assess caps --input EsriFootprint.json
# writes ./honua-caps.json, prints a Markdown summary + the shareable URL

honua-migrate assess caps \
  --input EsriFootprint.json \
  --json honua-caps.json \
  --output caps-summary.md

It emits:

1. honua-caps.json (--json, default ./honua-caps.json): schemaVersion, generatedAt, the source footprint reference, per-capability entries (Honua capability key, contributing assess key(s), matched inventory count, tier), an unmapped list, diagnostics, a serving-unit estimate (unitsEstimate), and the shareable url.
2. A Markdown summary (--output, default stdout), styled like the report/verdict output.
3. The shareable catalog URL — https://honua.io/capabilities.html?caps=<keys>&units=<estimate> — always printed to stdout in addition to the JSON. units is derived from the footprint's server facet (federated server / host count) when available, and omitted entirely (never units=0) otherwise.

Nothing in the footprint's detected inventory is dropped. Every assess-registry capability the footprint triggers ends up in honua-caps.json one of two ways: mapped into capabilities, or listed in unmapped with a reason of "unmapped" (known capability, no capability-key mapping yet) or "not-supported" (a hard Esri lock-in such as Utility Network, Parcel Fabric, or LRS — there is no Honua equivalent, by design).

Draft crosswalk (temporary)

The crosswalk caps ships with today (src/honua_esri_assess/data/honua-crosswalk.fixture.json) is a draft placeholder, not the canonical mapping. The canonical capability-keys.v1.json artifact — with the reconciled esri-assess-registry → capability crosswalk — is produced by honua-server (honua-io/honua-server#2893) and will replace it. Every caps run stamps the crosswalk's own source string into honua-caps.json ("crosswalk.source") so output generated against the draft is never mistaken for the reconciled mapping.

Air-gapped usage

caps makes no network call by default — the bundled draft fixture is read from the installed package. Use --crosswalk <path> to point at a local file (e.g. a copy of the published artifact carried into an air-gapped network) with zero network access:

honua-migrate assess caps --input EsriFootprint.json --crosswalk ./capability-keys.v1.json

--crosswalk also accepts an http(s):// URL once the canonical artifact is published — this is the one deliberate, explicit exception to the tool's no-network posture, and it only runs when you pass a URL yourself:

honua-migrate assess caps --input EsriFootprint.json \
  --crosswalk https://example.com/capability-keys.v1.json

The crosswalk document is validated at load: an esri-assess-registry key that does not exist in honua_esri_assess.verdict.registry.CAPABILITY_REGISTRY fails loudly (report.crosswalk.invalid, exit code 5) rather than silently mapping nothing.

Supported sources

Transient upstream failures (429, 502, 503, 504) are retried with capped exponential backoff honoring Retry-After; per-endpoint failures (403, unreachable host, unsupported item type) are downgraded to typed diagnostics inside the artifact rather than aborting the scan.

Artifacts and schemas

EsriFootprint.json is the sole machine-readable handoff into the closed Honua migration product; EsriAccessFootprint.json is its documented sibling for identity/RBAC posture. Both are published JSON Schemas (draft 2020-12) in this repository. Pass --validate on scan to check the artifact against the packaged schema copy before it is written, or run schema validate <file> on any artifact after the fact.

• Canonical sample footprint: docs/samples/esri-footprint.sample.json
• Sample readiness report: docs/samples/readiness-report.sample.md
• honua-caps.json is produced by caps (see Capability crosswalk); it is not yet a published JSON Schema since its crosswalk input is a draft fixture pending honua-io/honua-server#2893.
• Readiness report guide (exit codes, sections, heuristics): docs/readiness-report.md
• Versioning & deprecation policy: docs/schemas/versioning.md
• Prospect-facing handoff contract: docs/schemas/handoff-contract.md

Artifact diagnostics[].code is a locked enum (rate-limited, partial-coverage, missing-permission, unresolved-reference, unsupported-item-type, redacted-field) so reviewers can audit exactly what a diagnostic may say; see the diagnostic code catalog.

Resuming service imports

honua-migrate services arcgis resume JOB_ID --output result.json polls an existing job with GET requests; it never requeues an import. Both numeric and named GeoServices import statuses are supported using the 2026.1 status contract (recorded in response.statusContract). This is distinct from file-import enums: GeoServices 8 means Completed and 9 means NeedsReview.

The saved response includes outcome, normalizedStatus, terminal, timedOut, successful, fidelityVerified, elapsed time and the sanitized server status with its fidelity findings. Exit 10 means review required, failed/cancelled, unknown status, or timeout; the receipt is written before exiting. A legacy Completed response without fidelity metadata may exit zero but has fidelityVerified=false. Do not treat process success alone as proof of full migration fidelity.

Positive --max-wait values set a monotonic polling deadline shared by network timeouts, retries and sleeps. Requests' connect/read timeouts are capped by the remaining budget; scheduling delays and response-body delivery can still cause wall time to exceed that budget, and a late observation does not count as success. --max-wait 0 takes one status snapshot, bounded by --timeout-seconds, without waiting for a future terminal state. Unknown statuses stop with an explicit unknown-status outcome instead of being guessed or polled indefinitely.

Exit codes and failure surface

The CLI never prints Python tracebacks; failures surface as typed, prospect-safe diagnostics on stderr with deterministic exit codes:

Local stderr logs can be formatted as text or JSON with --log-format; both stay on the machine running the command. Crash dumps are off by default — setting HONUA_ESRI_ASSESS_CRASH_DUMPS=1 allows a local, redacted diagnostic file under ~/.cache/honua-esri-assess/crashes/ after an internal error. --no-network-telemetry-confirm is an audit-friendly acknowledgement flag; it is not an opt-in and changes no behavior.

Development

python3 -m pip install -e ".[dev]"
pytest                    # full suite
pytest tests/smoke -v     # fixture-backed end-to-end pipeline, no live Esri system
ruff check && mypy

The smoke suite exercises the full scan → EsriFootprint.json → report pipeline against checked-in HTTP fixtures and runs as a separate CI job; the dedicated no-network tests block outbound sockets while scans run. See tests/smoke/fixtures/README.md for the fixture layout and refresh protocol. Additional developer docs: scan handler interface and the read-only entitlement enumeration library (honua_esri_assess.entitlements).

Esri IP & licensing posture (clean-room formats via GDAL/community readers, no rehosting of licensed data, no embedded proprietary assets) is documented in docs/compliance/esri-ip-and-licensing-guardrails.md.

Migration implementation ownership, retained SDK/server API boundaries, release provenance, licensing, and legacy-entry removal gates are defined in the ownership and deprecation policy. The temporary honua-sdk 0.x launcher collision and its fail-closed isolated invocation path are documented in the honua-migrate console-script ownership policy.

Related Honua projects

• honua-server — the flagship multi-protocol geospatial server (GeoServices REST, OGC API, WMS/WFS/WMTS/WCS, STAC, vector tiles, and more) with protocol-level compatibility for selected, operation-scoped Esri client workflows, bounded by its published compatibility matrix and certified client envelope; the migration target this tool sizes.
• honua-console — unified web console (Studio, Catalog, Operate, Share).
• honua-helm — Helm chart, the Kubernetes deploy path.
• geobench — open, vendor-neutral benchmark suite for geospatial servers.

Hosted platform docs: https://honua.gitbook.io/honuaio/

Contributing

Issues and PRs are welcome. Commits follow Conventional Commits (enforced by commitlint in CI); CI also runs the unit and smoke suites on Python 3.11–3.13 plus ruff, mypy, and a dependency license guard. Releases go through release-please and PyPI Trusted Publishing — see RELEASE.md.

Security

Report vulnerabilities to security@honua.io. See the org security policy.

Documentation

• Full documentation index — every published page, generated from the documentation bundle so it cannot drift.

License

Apache-2.0.