UCD.js Docs

UCDJS Scripts

Architecture notes for @ucdjs/ucdjs-scripts

@ucdjs/ucdjs-scripts packages operational scripts for manifest generation and local environment seeding.

Role

  • Provides repo-specific operational commands that are too workflow-oriented for the public CLI package.
  • Generates manifests, uploads them through task endpoints, and seeds local dev environments.
  • Encodes deployment-oriented config resolution and upload behavior in one place.

Mental Model

This package is an operations CLI with two main workflows:

  • setup-dev: spin up the real API worker locally and seed a set of versions
  • refresh-manifests: generate manifests, compare ETags, queue uploads, and wait for completion

It is not the general user CLI. It is repo automation for maintainers.

Method Flows

setup-dev

waitForUploadCompletion()uploadManifest()generateManifests()unstable_startWorker()setupDev()waitForUploadCompletion()uploadManifest()generateManifests()unstable_startWorker()setupDev()loop[each manifest]Maintainerucdjs-scripts setup-devresolve versions and monorepo pathsstart real local API workergenerate manifests for versionsupload tar to local tasks endpointworkflowIdpoll workflow completioncompleted statusdispose()local environment seededMaintainer

refresh-manifests

waitForUploadCompletion()uploadManifest()getRemoteManifestEtag()generateManifests()resolveConfig()refreshManifests()waitForUploadCompletion()uploadManifest()getRemoteManifestEtag()generateManifests()resolveConfig()refreshManifests()alt[same ETag][changed]loop[each manifest]Maintainerrefresh-manifests --env previewresolve baseUrl + taskKey + apiBaseUrlgenerate manifestsfetch remote ETagunchangedskip versionqueue upload workflowworkflowIdwait for completionsuccess or failuresummary reportMaintainer

CLI bootstrap

imported command modulecommand actioncac()imported command modulecommand actioncac()Userrun ucdjs-scripts <command>parse options and select commandapply log leveldynamic import("./commands/<name>")setupDev() or refreshManifests()logs and resultUser

Design Notes

  • Upload workflows are task-driven so large manifest refreshes do not need to complete in one request.
  • setup-dev starts the actual worker entrypoint instead of faking the tasks API.
  • ETag comparison avoids unnecessary uploads when manifests have not changed.
  • This package is intentionally operational and repo-specific, so a stable public API matters less than correct workflow behavior.

Testing Use

  • config resolution and environment overrides
  • dry-run vs upload behavior
  • ETag skip logic
  • task queue / completion polling
  • local worker bootstrap for development seeding

On this page