Module Dependencies & Lockfiles

Reproducible Builds with Pinned Dependencies

A module can depend on other modules. These dependencies are recursively resolved and fetched by rescile before building the graph. To ensure reproducible builds, rescile supports a module.lock file which pins dependencies to exact commit hashes or checksums.

Declaring Dependencies

Dependencies are declared in the [dependencies] section of module.toml (see the module.toml Reference for full schema details). Three formats are supported:

[dependencies]
# Simple string: Git URL with optional tag (colon-separated)
base-security = "https://github.com/my-org/rescile-modules/base-security:v1.0.0"

# Detailed Git dependency with explicit tag
other-module = { git = "https://github.com/my-org/rescile-modules/other.git", tag = "v1.0.0" }

# Semver constraint matching available Git release tags
shared-lib = { git = "https://github.com/my-org/rescile-modules/shared-lib.git", version = "^1.2.0" }

# Release archive with a version template
packaged-module = { url = "https://github.com/my-org/rescile-modules/releases/download/{version}/module.zip", version = "v1.2.0" }

Dependency Keys, Aliases, and Slugs

Dependency keys in [dependencies.<key>] are parent-scoped aliases:

• Valid keys use lowercase ASCII characters, numbers, and hyphens ([a-z0-9][a-z0-9-]*).
• Slug Matching Warning: Rescile derives a normalized slug from the resolved module’s declared [module].name. When a dependency key differs from that generated slug, Rescile emits a warning:

  WARN: Dependency key 'my-sec' in '/path/to/module.toml' resolves to module 'base-security' whose generated slug is 'base-security'. This alias remains allowed, but may conflict with another dependency.
  

• Custom aliases remain allowed to support parent-scoped aliasing and disambiguation, but matching the target module slug avoids unexpected collisions across the dependency tree.

Repository Identity and Semver Solving

• Canonical Git Source: Git URLs with or without a .git suffix, or with trailing slashes, are normalized to the same canonical package identity (https://github.com/org/repo.git == https://github.com/org/repo). They are cloned once and share cache entries.
• Semver Solving: When multiple modules depend on the same package via semver constraints (e.g. ^1.0 and >=1.2, <2.0), Rescile queries the remote tags and selects the highest common version satisfying all constraints across the entire graph. If constraints cannot be satisfied simultaneously, resolution fails fast with an explicit error.
• Exact Ref Conflicts: If different modules require conflicting exact branches or tags (e.g. branch = "v1" vs branch = "v2"), resolution fails immediately rather than silently picking one.

The mod Subcommands

The rescile-ce mod subcommand provides utilities for managing dependencies, lockfiles, and starter asset synchronization.

rescile-ce mod add <NAME> <URL>

Adds a new dependency entry to data/module.toml, resolves the graph, and updates data/module.lock. Supports --tag, --branch, --commit, and --version pins. Pass --sync to automatically copy or merge the module’s starter assets and inputs immediately upon adding:

# Add and pin a dependency
rescile-ce mod add landing-zone https://github.com/rescile/landing-zone-module.git --tag v1.2.0

# Add and immediately pull starter CSVs and JSON inputs
rescile-ce mod add aws-provider https://github.com/rescile/aws-provider-module.git --sync

rescile-ce mod sync

Copies or merges starter asset and input files from locked dependency modules into the local data/ directory using the configured bootstrap_policy (default: merge).

This is the primary command to update or backfill starter CSV columns and reference data when dependency modules evolve, replacing the legacy top-level bootstrap command.

# Sync starter assets from all dependencies
rescile-ce mod sync

# Preview changes without modifying local files
rescile-ce mod sync --diff

# Restrict synchronization to one dependency
rescile-ce mod sync --module aws-provider

# Overwrite existing files
rescile-ce mod sync --force

rescile-ce mod lock

Resolves the full dependency tree based on the current module.toml and generates or heals the module.lock file. Run this after adding or changing a dependency declaration.

rescile-ce mod lock

rescile-ce mod check

Compares the module.lock against remote repositories to report whether any updates are available — for example, new commits on a tracked branch or a newer semver tag matching your constraint.

rescile-ce mod check

rescile-ce mod update

Updates the module.lock file to the latest available versions according to the remote repositories. Pass an optional module name to update a single dependency rather than all of them.

rescile-ce mod update                  # update all
rescile-ce mod update base-security    # update one

rescile-ce mod fetch

Resolves the dependency tree and downloads all remote modules into the persistent local registry without starting the server. Useful for pre-seeding a CI environment or an air-gapped build cache.

rescile-ce mod fetch

Explicit --module overrides

When you pass a module explicitly with --module <path-or-url>, it always takes precedence over any entry with the same name in module.lock. This lets you temporarily override a pinned dependency with a local checkout or a different URL. A startup warning is shown when the lockfile entry is ignored.

For guidance on authoring and publishing your own modules, see the Module Packaging Guide.