Skip to content

feat: add gc import check for cache/materialization validation #575

@donbox

Description

@donbox

Problem

The Pack/City 0.13.6 import model assumes that normal city loads should not require live internet access once imports have been installed. Remote imports should resolve into local materialized state, with the lock file defining the desired resolved state.

That leaves a missing operational feature: users need a dedicated way to validate and repair import materialization when local cached/materialized content is missing or stale.

gc doctor is not the best home for this. This wants to live on the import surface itself.

Proposed behavior

Add a new subcommand:

gc import check

This command should validate the import installation state for the current city.

At a minimum it should:

  • read the city's declared imports plus lock file
  • verify that the required local materialized content exists
  • check local cache availability before attempting network access
  • explain clearly when an import is missing, stale, or cannot be materialized
  • provide remediation guidance

Over time it could also support repair/rematerialization behavior.

Intended import contract

This issue is also meant to lock in the intended behavior:

  • normal load should not require internet access
  • internet is required for fetch/update/rematerialization work
  • the lock file is the authoritative statement of desired installed state
  • missing materialized content should be repaired from local cache first, then remote source
  • if repair is not possible, the user should get a clear actionable error

Why this matters

  • users reasonably expect installed imports to work offline
  • docs need a precise story for local vs remote imports
  • loader, package-manager, and UX need one consistent import contract

Related docs/work

  • migration guide work in docs/guides/migrating-to-pack-vnext.md
  • import/cache/offline design note in local work products

Metadata

Metadata

Assignees

Labels

city-pack-v2City/pack v2 design and migration workkind/enhancementNew capabilityphase/post-0.13.6Explicitly after the 0.13.6 merge wavepriority/p2Medium — real problem, workaround existsstatus/acceptedConfirmed and on our radar

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions