Bootstrapping a Project

Rescile provides commands to initialize project workspaces and synchronize starter reference data from upstream modules:

1. init command: The primary command in rescile-ce and rescile-ee to scaffold an entire project workspace with directory layout, data/module.toml, data/module.lock, and initial assets in one shot.
2. mod sync / mod add --sync: The dedicated dependency subcommands to synchronize, merge, or inspect starter asset and input files from declared module dependencies.

Workspace Initialization (init)

To scaffold a complete workspace:

# 1. Initialize an empty workspace in ./data:
rescile-ce init

# 2. Initialize and bootstrap from an upstream module:
rescile-ce init --from https://github.com/org/rescile-core-module.git

# 3. Initialize with multiple modules (primary upstream + optional add-ons):
rescile-ce init \
  --from https://github.com/org/rescile-core-module.git \
  --add-module https://github.com/org/rescile-monitoring.git \
  --add-module https://github.com/org/rescile-compliance-rules.git

# 4. Specify target directory, project name, or git tags/branches:
rescile-ce init --from https://github.com/org/rescile-core-module.git --tag v1.2.0 ./my-project

init performs the following steps:

1. Creates directory layout: data/assets/, data/input/, data/output/, data/models/.
2. Resolves and inspects the upstream module and all --add-module dependencies.
3. Generates data/module.toml with the project name and cleanly formatted dependency entries.
4. Generates data/module.lock to pin resolved commit hashes or archive checksums for reproducible builds.
5. Bootstraps starter CSV assets and JSON inputs using the selected policy (default: merge).
6. Generates .gitignore ignoring temporary files, outputs, and sync metadata (unless --no-gitignore is passed).

Dependency Key Generation and Slugs

When init registers a dependency in data/module.toml, the dependency key table header (e.g. [dependencies.<key>]) is derived as a normalized slug ([a-z0-9][a-z0-9-]*) from the module name or repository URL:

• Spaces and underscores are replaced with hyphens.
• Accents and diacritics are transliterated to ASCII, and non-alphanumeric characters are stripped.
• Trailing .git extensions and redundant suffixes (like -module) are trimmed.

For example:

rescile-ce init \
  --from https://github.com/rescile/landing-zone-module.git \
  --add-module https://github.com/rescile/aws-provider-module.git

generates:

[module]
name = "my-project"
version = "0.1.0"

[dependencies.landing-zone-module]
git = "https://github.com/rescile/landing-zone-module"

[dependencies.aws-provider-module]
git = "https://github.com/rescile/aws-provider-module"

If an upstream module declares a human-readable display name such as "Landing Zone Module", rescile derives the key slug landing-zone-module rather than generating a quoted key with spaces.

Preserving Specific Git Refs

When initializing from a specific revision, pass --branch or --tag, or specify the ref directly in the source URL:

# Explicit CLI flag
rescile-ce init --from https://github.com/org/network-module.git --tag v2.1.0

# Or shorthand syntax in the URL
rescile-ce init --from https://github.com/org/network-module.git:v2.1.0
rescile-ce init --from https://github.com/org/network-module.git#feature-v2

init writes the exact constraint (tag = "v2.1.0" or branch = "feature-v2") into module.toml before running initial resolution, ensuring that the pinned module.lock captures the exact requested revision.

Synchronizing Starter Assets (mod sync)

Once a project has been initialized or new dependencies have been added with rescile-ce mod add, use rescile-ce mod sync to copy or merge starter asset CSVs and JSON inputs from dependency modules into your local data/ directory.

Starter files are copied only when you explicitly run init, mod sync, mod add --sync, or pass --init to serve or save.

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

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

# Sync from a single module
rescile-ce mod sync --module aws-provider

Web Onboarding: Enterprise Edition (EE) vs Community Edition (CE)

• In Community Edition (rescile-ce), visiting an uninitialized workspace displays an actionable developer card with the exact CLI commands (rescile-ce init --from <module>).
• In Enterprise Edition (rescile-ee), visiting an uninitialized workspace opens an interactive web onboarding wizard (POST /api/bootstrap) allowing administrators to choose git repositories and branches directly from the browser for headless or container deployments.

What Gets Copied

A module can ship reference data in the same directory layout as a project:

my-module/
├── module.toml
├── models/
├── compliance/
├── assets/          # starter CSVs
└── input/           # starter JSON inputs

When you run bootstrap, rescile copies these files into your local data/ directory:

• my-module/assets/*.csv → data/assets/*.csv
• my-module/input/*.json → data/input/*.json

Bootstrap Policies for Assets

Asset CSVs can declare a bootstrap_policy in module.toml that controls how the workspace file is mutated on each bootstrap.

Example in module.toml:

[[assets]]
name = "servers.csv"
bootstrap_policy = "merge"

You can override the module default for all assets that do not declare their own policy by passing --bootstrap-policy:

rescile-ce --module ./standard-webapp bootstrap --bootstrap-policy append

Safe merge Behavior

The default merge policy is schema-aware and safe:

• If the local file does not exist, the module file is copied as-is.
• If the local file already exists, module rows are appended to local rows.
• Existing local rows keep all non-empty values.
• New columns from the module CSV or the asset definition are added.
• Missing or empty cells in new columns are filled from (in order): the module CSV value for that row, the column default, or the column template.
• No columns are renamed or removed.

This lets a module provide reference rows (for example, a small system.csv or team.csv) while your local files remain the authoritative source of truth, and it also lets modules evolve their schemas without losing your existing data.

Input JSON Copy Behavior

JSON input files are copied only if the local file does not already exist. Use --force to replace them.

Using the Bootstrap Command

Bootstrap from all loaded modules at once:

rescile-ce --module https://github.com/my-org/rescile-modules/standard-webapp bootstrap

Restrict the operation to one module:

rescile-ce --module ./standard-webapp --module ./core-platform bootstrap --module standard-webapp

Preview what would change without writing anything:

rescile-ce --module https://github.com/my-org/rescile-modules/standard-webapp bootstrap --diff

Overwrite existing local files:

rescile-ce --module https://github.com/my-org/rescile-modules/standard-webapp bootstrap --force

Running Bootstrap Automatically

To run the bootstrap step before another command, use --init:

rescile-ce --module ./standard-webapp serve --init
rescile-ce --module ./standard-webapp save ./graph.json --init
rescile-ce --module ./standard-webapp init
rescile-ce --module ./standard-webapp validate

This is useful in CI pipelines or when starting a fresh checkout.

You can also start a local workspace directly from a module without creating a module.toml in data/ first. The module is loaded, its starter assets and inputs are bootstrapped, and the dashboard is shown:

rescile-ce -m ./standard-webapp serve --init

Local data directories do not require a module.toml. Only modules need one.

Tracking Module Updates

Each bootstrap run records which module files were used in data/bootstrap-state.json. Unchanged module files are skipped on subsequent runs, so repeated bootstraps are fast and idempotent. The file is also ignored by the file watcher to avoid unnecessary graph rebuilds.