mold 0.2.0

Pack an existing project into a portable template archive and unpack it with manifest-driven renaming. Ships a `mold` CLI and is consumable as a library.

mold

Pack an existing project into a portable template archive, then unpack it under a new name. Ships a mold CLI and is consumable as a library.

The template is a real project — one that builds, runs and has tests. There are no placeholders in the source: renaming rules live in a manifest beside it, so the template stays lintable, reviewable and current by being the thing you actually use. The archive is a verbatim snapshot; substitution happens only at unpack, so one archive materializes under many names.

mold pack   ./super_server  ->  super_server.mold  (gzipped tar)
                                 ├── mold.yaml     (the manifest, embedded)
                                 └── files/        (the project, verbatim)

mold unpack ./super_server.mold --var project_name=my_project
                              ->  ./my_project/    (renamed: paths + text,
                                                    binaries copied as-is)

---

Install

As a CLI

dart install mold

That puts mold on your PATH. To pin a version, or to install before the package is on pub.dev:

dart install mold@^0.2.0

# straight from git
dart install 'mold@{git: {url: https://github.com/pro100andrey/mold}}'

# from a local checkout
dart install 'mold@{path: /path/to/mold}'

On Dart SDKs older than the dart install command, use the classic form:

dart pub global activate mold

Check it: mold --help. If the command is not found, the directory it was installed into is not on your PATH; dart install prints the line that adds it. That directory is Dart's own, not pub's: ~/.local/state/Dart/install/bin on Linux (under $XDG_STATE_HOME when set), ~/Library/Application Support/Dart/install/bin on macOS, %LOCALAPPDATA%\Dart\install\bin on Windows. dart pub global activate uses pub's: ~/.pub-cache/bin, or %LOCALAPPDATA%\Pub\Cache\bin on Windows.

As a library

dart pub add mold

import 'package:mold/mold.dart';

Requirements

Dart SDK 3.13.5 or newer. No other runtime dependencies — mold shells out to chmod on POSIX to restore executable bits, and does nothing at all if that is unavailable.

---

Contents

• Install · Quick start · Commands · init
• The manifest — file selection · variables · substitutions · path renames · verbatim files · message
• Interpolation and transforms
• Choosing a replaces token
• Previewing
• Validation · exit codes
• Library usage · embedding
• What is preserved · out of scope

---

Quick start

# 1. Describe the rename beside the project you already have —
#    `mold init ./super_server` writes a start — or by hand:
cat > ./super_server/mold.yaml <<'YAML'
name: super_server
version: 1.0.0
variables:
  project_name:
    description: The new project name
    default: my_project
    replaces: super_server
YAML

# 2. See what it would do before it does it.
mold pack ./super_server --dry-run

# 3. Pack, then scaffold under any name.
mold pack ./super_server -o super_server.mold
mold unpack super_server.mold -t ./my_project --var project_name=my_project

Commands

mold init [dir] [options]
  --token          The name to replace        (default: detected, see below)
  --variable       The variable replacing it  (default: project_name)
  --yes,      -y   Add the suggested entries without asking
  --no-prompt      Never ask; leave the suggestions out
  --force          Overwrite an existing mold.yaml
  --dry-run        Print the manifest on stdout instead of writing it
  --json           Print the result as JSON on stdout

mold pack <source_dir> [options]
  --manifest, -m   Path to the manifest      (default: <source_dir>/mold.yaml;
                                              error if absent and -m not given)
  --output,   -o   Output path               (default: ./<name>.mold, or
                                              ./<name>.dart for embed formats)
  --name,     -n   Output file name stem      (also names the embedded const)
  --format,   -f   tar.gz | bytes | base64    (default: tar.gz)
  --level          gzip level 0-9             (default: 6)
  --fast           zlib instead of pure-Dart deflate (faster; bytes vary by OS)
  --var,      -v   key=value                  (repeatable, for --diff)
  --vars-file      YAML/JSON values, or a stamp (for --diff)
  --dry-run        Validate and list what would be captured, without writing
  --diff           Preview the renames this manifest would make
  --check          Exit 1 if the output file is stale; write nothing
  --json           Print the result as JSON on stdout

mold unpack <source | -> [options]
  --target,   -t   Destination dir            (default: ./<source-stem>)
  --var,      -v   key=value                  (repeatable; overrides the file)
  --vars-file      YAML/JSON values, or a .mold.json stamp
  --no-prompt      Use only --var + manifest defaults; never prompt
  --force          Unpack into a non-empty target (see below)
  --stamp          Record the unpack in <target>/.mold.json
  --dry-run        Show what would be written, without writing it
  --diff           Also show a unified diff (implies --dry-run)
  --json           Print the plan as JSON on stdout

mold inspect <archive | -> [options]
  --files          Also list every file, with its size
  --manifest       Print the embedded mold.yaml as written, on stdout
  --json           Print the description as JSON on stdout

mold help <command> for the full option list. During development: dart run mold:mold pack ./super_server.

Human-facing output goes to stderr; stdout carries only what a tool would read — --json documents, and the manifest YAML of init --dry-run and inspect --manifest. Under --json, warnings are part of the document, and a failure is a document too — {"errors": [{"code": …, "message": …}], "warnings": […]} with exit 1 — so a tool reading stdout always gets JSON. Failures that carry no library code use CLI_USAGE (bad arguments, a missing vars file — exit 64) and IO_FAILURE (exit 1).

Starting a manifest

mold init ./app_template writes a starting mold.yaml: the project's own name as the replaces token of one variable, project_name, and the manifest itself excluded from what it packs. The name is read from the project's package manifest — pubspec.yaml, package.json, composer.json, Cargo.toml, go.mod, pyproject.toml, settings.gradle(.kts), pom.xml, Package.swift or a lone .csproj, .fsproj or .vbproj — else taken from the directory; --token names it instead.

It then runs the pack's checks on that draft. Spellings of the name the four derived casings miss are offered as entries — extra_substitutions for those in file content, path_renames for those in paths, both when they are in both. On a fresh Flutter project, the bundle id and the display name:

Spellings of the name no derived casing covers:
  'appTemplate' → {{ project_name | camelCase }}  (2 files)
  'App Template' → {{ project_name | titleCase }}  (1 file)
Add them to extra_substitutions? [Y/n]

Everything else the pack would say — a token too generic, a suspected secret — is reported as a warning, and the manifest is written anyway: it is a start, to review with mold pack ./app_template --dry-run.

Unpacking into a non-empty directory

By default the target must not exist, or be an empty directory; anything else is TARGET_OCCUPIED. --force writes into a directory that already holds files — the way a tool regenerates a project in place:

• each file the template has is written over the file at the same path;
• every file the template does not have is left as it is;
• a target that is a file, not a directory, is still refused;
• a template file that would land on a directory, under a file, or through a symlink is TARGET_PATH_CONFLICT, reported before anything is written.

--force is not a merge: an overwritten file holds the template's version, whatever was edited in it. Preview first — --force --dry-run lists what would be created and what overwritten, and --force --diff diffs each overwritten file against the one already there.

If a write still fails partway (a read-only file, a full disk), the unpack is undone: created files are removed, overwritten files get their previous content back, and directories it created are removed once empty. Anything it could not undo is named in a warning. Writes go straight into the target rather than through a scratch directory: moving a tree into an occupied directory is one rename per file, so it would be no more atomic, and a scratch directory can sit on another filesystem, where a rename is a copy.

Reading the archive from stdin

- in place of the archive reads it from stdin, so a template on a server needs no intermediate file:

curl -sL https://example.com/app.mold | mold unpack - -t ./my_app --var name=my_app

stdin then carries the archive, so nothing can be prompted for: values come from --var, --vars-file and defaults, as under --no-prompt, and --target is required — there is no file name to derive it from. mold inspect - works the same way.

Inspecting a template

mold inspect super_server.mold says what a template is before you run it: its name and version, the variables it asks for (with defaults, patterns and choices), its explicit substitutions, and — with --files — what it holds. It runs the archive and manifest checks an unpack runs, so a template that inspects cleanly can fail an unpack only on its variables or its target. --manifest prints the embedded mold.yaml itself, as written — on stdout, so mold inspect app.mold --manifest > mold.yaml recovers it.

Checking a committed archive in CI

mold pack ./templates/app -f bytes -o lib/src/template.dart --check

Exit 0 when the file holds what packing would write now, 1 when it is stale or missing — with what changed: 1 changed (lib/main.dart); 1 added (…). Nothing is written.

The comparison is by content: the archive is unpacked from the committed file (from inside the Dart source, for -f bytes|base64) and its manifest, files and executable bits compared with the project's. Compressed bytes are not compared, so a file written on another OS, by another Dart SDK, at another --level or with --fast is not called stale when its content is current. An embed source must also be exactly what this mold renders around its archive, so a changed -n or a newer mold's layout is stale too. Line endings are not a change: a source committed with LF and checked out with CRLF — Git for Windows' default — is current.

Nothing is compressed for the check: the project's files are compared with the committed archive's as they are read. On a 48 MB project it takes 0.7 s, a third of a pack.

Reproducible archives

Packing the same tree and manifest at the same --level gives the same bytes on any OS and Dart SDK — for a given version of mold and package:archive — so regenerating a committed -f bytes source on another machine is an empty diff. Two things are pinned for it: compression uses package:archive's pure-Dart deflate rather than the zlib built into the VM, whose output can vary by platform; and every gzip header is the same ten bytes (no mtime, OS "unknown"), where zlib writes a per-platform OS byte. CI checks this on Linux, macOS and Windows against committed golden archives.

--fast compresses with the VM's zlib instead: about 2.7x faster at that step (0.66 s against 1.8 s for a 48 MB tar), still reproducible on one machine, and still fine for --check — but no longer byte-identical across platforms.

Regenerating a project

--stamp leaves a .mold.json in the target: the template, its version, the variable values and every file written. A target that already has one gets it updated on every later --force, whether or not --stamp is repeated.

mold unpack app.mold -t ./my_app --var name=my_app --stamp
# …later, with a newer template:
mold unpack app.mold -t ./my_app --force --vars-file ./my_app/.mold.json --dry-run

--vars-file takes the stamp's values, so a regeneration does not depend on remembering what was typed the first time; --var still overrides any of them. A variable the template has dropped since is VARIABLE_DROPPED ⚠ — its value is not used — rather than an error that would make the stamp useless after the first change to the template's variables. The stamp also records a SHA-256 of every file it wrote, which tells a regeneration two things:

• which files it is about to overwrite hold content it did not write — edited since, or never written by it at all (the project's own file, at a path the template has added since) — UNPACK_OVERWRITES_EDITS, listed in a dry run, so --force no longer discards work without a word;
• which files the template has since dropped — listed under "No longer in the template", reported as UNPACK_STALE_FILES, and left in place: never deleted, since they may have been edited. They stay in the stamp while they exist, so every regeneration reports them, not just the first.

A regeneration rewrites only files that change: one identical to what is there is compared, not written, so mtimes — and build caches and file watchers — are left alone. A stamp at a project's root is never packed into a template: it describes one unpack into one directory, and would hand every later unpack its author's values and history. Only a stamp — a .mold.json that is some other tool's file is packed like any other.

A stamp belongs to one template. Unpacking another into the same directory with --force — an add-on template into a project made from a first one — reports UNPACK_STAMP_FOREIGN ⚠ and leaves the first one's stamp as it is: it is not used to tell stale or edited files, which would call every file of the first template stale, and not rewritten for the second. With --stamp it is an error, since one .mold.json cannot describe both.

On macOS and Windows, a path whose casing changed between unpacks (MyApp.swift → Myapp.swift, after a value's casing changed) is the same file, and treated as one: neither stale nor the project's own.

--vars-file also takes a plain YAML or JSON map of values. --var applies over it; a key the template does not declare is VARIABLE_UNKNOWN, as for --var — a map is typed by hand, so an unknown key there is more likely a typo than a dropped variable.

---

The manifest (mold.yaml)

Every key, with its default:

# ─── required ───────────────────────────────────────────────
name: super_server          # template name; default output file stem
version: 1.0.0              # free-form string

# ─── file selection ─────────────────────────────────────────
use_gitignore: true         # honour the project's own .gitignore files
include: []                 # globs; empty means "everything"
exclude: []                 # globs, applied on top of .gitignore

# ─── renaming ───────────────────────────────────────────────
variables:                  # {} — declared rename variables
  project_name:
    description: ''         # shown when prompting
    default: null           # absent → the variable is required
    replaces: null          # the source token; absent → interpolation only
    pattern: null           # regex the whole value must match
    choices: []             # the only values allowed; empty → any

extra_substitutions: []     # from/to, applied to CONTENT only
path_renames: []            # from/to, applied to PATHS only

# ─── copied verbatim ────────────────────────────────────────
no_substitute: []           # globs; content untouched, path still renamed
binary_extensions: []       # extra extensions treated as binary

# ─── after unpacking ────────────────────────────────────────
message: null               # shown once unpacked; a template like `to:`

Values are read as written: an unquoted version: 1.10 is 1.10, not the number YAML would make of it (1.1), and 007 stays 007 — in the manifest and in --vars-file alike.

A key the format does not define is ignored, but never silently: it warns as MANIFEST_UNKNOWN_KEY, with the key it probably means — excludes → did you mean exclude? — at the top level, inside a variable, and inside a substitution entry.

File selection

A file is packed only if it passes include, passes exclude, and is not gitignored. Three independent filters, all must pass.

use_gitignore (default true) reads the project's own .gitignore files — all of them, including nested per-platform ones — so a manifest never restates .dart_tool/**, build/** and friends. The supported syntax is the real thing: ! negation, / anchoring, trailing-slash directory rules, # comments, and last-match-wins ordering. .git/ is always excluded. Set use_gitignore: false to pack the tree exactly as it sits on disk.

exclude therefore carries only what git has no opinion about:

exclude:
  - pubspec.lock            # committed, but a scaffold resolves its own
  - mold.yaml               # the template's own manifest

Symlinks: one pointing at a file inside the project and passing the same filters is packed as its content. One pointing outside, at a directory, at nothing, or at a filtered-out file is skipped with a PROJECT_SYMLINK_SKIPPED warning. Following a link out of the project would let pack inline ~/.ssh/id_rsa into a template you then share.

Variables

variables:
  project_name:
    description: The new project name
    default: my_project
    replaces: super_server

replaces names a token in the source. At unpack, the resolved value replaces four derived casings of it, in both paths and content:

casing	super_server →
snake_case	super_server
kebab-case	super-server
SCREAMING_SNAKE	SUPER_SERVER
PascalCase	SuperServer

The source spelling does not matter: super_server, superServer, SuperServer and SUPER_SERVER all declare the same rename.

camelCase is deliberately not derived. For a single-word token it is indistinguishable from snake_case, so deriving it would be ambiguous — reach it with an explicit transform instead (below).

The value given for a replaces variable must be something the casings can be derived from: ASCII letters, digits, spaces, _ and -, starting with a letter or digit and holding at least one letter — 3d-viewer is fine; 123, -app and my/app are VARIABLE_INVALID_FORMAT. Anything a particular language forbids on top of that, such as a leading digit in a Dart package name, belongs in the variable's pattern.

A variable without replaces contributes no renames; it exists to be interpolated. One that is neither used as a token nor referenced by any substitution warns as MANIFEST_UNUSED_VARIABLE.

A variable can constrain its value: pattern is a regular expression the whole value must match (it is anchored for you), and choices lists the only values allowed — the prompt shows them. An answer the variable refuses — outside choices, not matching pattern, not a name its casings can be derived from — is explained and asked again, up to three times, rather than failing the unpack after every other prompt.

variables:
  org:
    pattern: '[a-z]+(\.[a-z]+)+'
    default: com.example
  platform:
    choices: [android, ios]
    default: android

A value outside them is VARIABLE_PATTERN_MISMATCH or VARIABLE_NOT_A_CHOICE; a pattern that does not compile, or a default its own constraints reject, is caught at pack.

Two variables whose tokens derive the same casing (my_app and my-app share MyApp) warn as MANIFEST_CONFLICTING_TOKENS: those sites take the later variable's value.

Resolution precedence: explicit --var › --vars-file › manifest default › interactive prompt. End of input is not an answer — with stdin closed, a variable with no default stays unresolved and is reported as VARIABLE_MISSING, rather than silently becoming an empty string; input that ends after a refused answer keeps that answer, to fail on it, rather than falling back to the default.

Substitutions

For strings the four casings cannot reach. from is always a literal, so a rule stays greppable against the real project; to is a template.

extra_substitutions:
  - from: https://api.super.dev
    to: https://api.example.com
  - from: com.example.superServer
    to: com.example.{{ project_name | camelCase }}

Content only — these never touch paths.

Path renames

The mirror image: paths only, never content.

path_renames:
  - from: kotlin/com/example/super_server
    to: kotlin/com/example/{{ project_name }}

This exists for the case a replaces token structurally cannot express: when one literal needs opposite treatment in different places. In a Flutter project android/app/ is a hard-coded Gradle module path that must survive, while kotlin/com/example/app/ is the package and must move.

Matching is longest-first, so an entry mapping a path to itself pins it against a shorter rename:

path_renames:
  - from: android/app/          # 12 chars — beats the "app" rename key
    to: android/app/            # pinned to itself
  - from: kotlin/com/example/app
    to: kotlin/com/example/{{ project_name }}

Verbatim files

no_substitute:                # text files copied byte-for-byte…
  - pubspec.lock              # …though their PATH is still renamed
  - "**/*.g.dart"

binary_extensions:            # on top of the built-in set
  - myblob                    # (png, jpg, ttf, zip, sqlite, …)

A file whose extension says text but whose bytes are not valid UTF-8 is also copied verbatim rather than failing the unpack.

Message

What to tell the person once the project exists — the next steps, usually:

message: |
  Next:
    cd {{ project_name }}
    dart pub get
    dart run bin/{{ project_name | snakeCase }}.dart

mold unpack prints it, rendered, after Unpacked into … — not on a dry run. It is a template like a substitution's to: and is validated like one; a variable it names counts as used. --json carries it as message, and UnpackPlan.message holds it rendered.

---

Interpolation and transforms

Only the to: side of a substitution or path rename is a template, and the message.

{{ variable }}                 the resolved value, unchanged
{{ variable | transform }}     the value through one transform
{{{{                           a literal "{{"

transform	value	becomes
snakeCase	my_project	my_project
kebabCase	my_project	my-project
camelCase	my_project	myProject
pascalCase	my_project	MyProject
screamingCase	my_project	MY_PROJECT
titleCase	my_project	My Project
flatCase	my_project	myproject
pathCase	com.acme	com/acme

Whitespace inside the braces is insignificant. Chaining ({{ a | x | y }}) is refused rather than read as a transform named x | y.

Why this exists. Flutter derives its Apple bundle identifier by camelCasing the project name while Android keeps it snake, so one name yields com.example.myProject and com.example.my_project in the same project — plus My Project for the home-screen label. The four casings cover one of the three; named transforms cover the rest.

The Android sources are the same fact one level up: they live in android/app/src/main/kotlin/com/example/…, a directory path spelling out the package the organisation names. pathCase derives that path from the organisation itself — com.acme → com/acme — so the two cannot be set inconsistently. It is the one transform that is not a case conversion: segments keep the spelling they were given, so com.acmeCorp is com/acmeCorp, not com/acme/corp.

Templates are validated at pack time and again at unpack, so a bad placeholder or an undeclared variable fails when the template is built, not when someone uses it. Rendering happens at unpack, and a rendered value is never re-scanned — it cannot cascade into another substitution.

Precedence

All rules are applied in a single left-to-right pass:

• longest match wins at the same position; leftmost wins across positions
• no cascading — a substituted value is never re-scanned
• an explicit substitution beats a derived rename key on collision
• between two variables whose tokens collapse to the same casings, the later one in the manifest wins

---

Choosing a replaces token

Substitution is literal, so a token that is mostly a substring of other words corrupts the project. mold measures this rather than guessing: it counts every occurrence of every derived casing, and how many sit inside a longer identifier.

collateral	verdict
≥ 30%	error — PROJECT_TOKEN_TOO_GENERIC
≥ 5%	warning — PROJECT_PARTIAL_OVERLAP
below	silent

A match is collateral when the characters around it continue the word in the casing that matched. For the snake, kebab and SCREAMING forms a letter or digit continues it, and _, - and anything else end it — so app_template_test is a whole-word match for replaces: app_template, and renaming it to my_app_test is the point. For the Pascal form only a following lowercase letter continues it: AppTemplateTest and MyAppTemplate are whole words, AppTemplateer is not. my_app in my_appendix, app in application and MyApp in MyApplication are all still collateral.

Measured on a fresh flutter create project (Flutter 3.47): bin 75%, test 73%, app 65%; runner and the project's own name under 5%.

[PROJECT_TOKEN_TOO_GENERIC] Variable 'project_name': token 'app' matches 615
times; 398 (65%) inside longer words: application (72),
flutter_application_1 (40), apple (36). Substituting it would rewrite those
too — pick a more distinctive token, or replace these sites with explicit
extra_substitutions.

When a token is too generic, the way forward is explicit extra_substitutions and path_renames, not a blunter rename. The check matches exactly as unpacking will — one pattern over every casing and every explicit substitution, longest first — so a site an extra_substitutions entry claims is not counted against the token: pinning MyApplication to itself removes it from the collateral.

The four casings are not every way a name gets written, and the check says so. A token's words matched case-insensitively, joined by one of ._- or by nothing, that land on no derived casing are reported as PROJECT_UNCOVERED_CASING — with the entries that would rename them, wherever a transform reproduces the spelling exactly: under extra_substitutions for a spelling in content, under path_renames for one in a path. On a fresh flutter create project named app_template:

[PROJECT_UNCOVERED_CASING] Variable 'name': 'appTemplate' (10:
ios/Runner.xcodeproj/project.pbxproj, macos/Runner.xcodeproj/project.pbxproj,
macos/Runner/Configs/AppInfo.xcconfig), 'App Template' (1: ios/Runner/Info.plist)
spell token 'app_template' in a way no derived casing matches, so unpacking
leaves them as they are. To rename them too, add to extra_substitutions:
  - from: "appTemplate"
    to: "{{ name | camelCase }}"
  - from: "App Template"
    to: "{{ name | titleCase }}"

That is the iOS and macOS bundle identifier and the display name: without it, the scaffolded app ships under the template's identity.

The same pass reports other things worth knowing at pack:

• a token that occurs in files copied verbatim (binary extensions, no_substitute, non-UTF-8) — PROJECT_TOKEN_IN_VERBATIM; their paths are renamed, their content keeps the token;
• an extra_substitutions or path_renames entry that never fires — PROJECT_SUBSTITUTION_UNUSED, PROJECT_PATH_RENAME_UNUSED; usually a typo;
• a file that looks like a secret — PROJECT_SECRET_SUSPECTED: by name (.env, key.properties, google-services.json, *.pem, *.jks, SSH keys, …; .env.example and friends excepted) or by content (a PEM private key, an AWS access key id, a Google API key, a GitHub token). A template is made to be shared;
• a path that cannot exist everywhere — PROJECT_PATH_NOT_PORTABLE: two that differ only in case (one file on macOS and Windows), or a name Windows refuses (aux.txt, a:b, a trailing dot). A warning, since the template unpacks fine elsewhere; unpacking it on Windows is RENAME_INVALID_NAME, before anything is written.

At unpack, a variable's value is checked against the template: VARIABLE_VALUE_PRESENT when a casing of it already occurs there as a word. Unpacking super_server as my_app into a template with a MyApp class leaves two classes called MyApp, and nothing else would notice.

The manifest file itself is excluded from that search — a replaces: line is a declaration, not evidence the project uses the token.

---

Previewing a rename

mold unpack super_server.mold -t ./my_project --dry-run

Dry run — nothing written to ./my_project.
  129 files: 3 renamed, 18 rewritten (50 replacements), 108 unchanged.

Renamed:
  android/.../com/example/super_server/MainActivity.kt  ->  .../my_project/...  (1)
  super_server.iml  ->  my_project.iml

Rewritten:
  pubspec.yaml  (1)
  macos/Runner.xcodeproj/project.pbxproj  (13)

Add --diff for the content changes as a unified diff. Unchanged files are counted but not listed — a template is mostly unchanged files, and listing them buries the ones that matter.

The preview runs the same validation, resolution and substitution rules as a real unpack, so it cannot disagree with one; it is that computation minus the writes. The target is validated too, so a dry run also answers "is the destination usable".

Into an occupied target (--force), the preview says what the write would do to the files already there:

Dry run — nothing written to ./my_project.
  4 files: 1 renamed, 3 rewritten (5 replacements), 1 unchanged.
  Target is not empty: 1 to create, 3 to overwrite (2 identical).
...
Created:
  lib/src/new_in_template.dart

Overwritten:
  pubspec.yaml

Overwrites that would change nothing are counted, not listed. With --diff, an overwritten file is diffed against the file already there (--- pubspec.yaml (in target)), since that is the change the write makes; a created file is diffed against the template, as without --force.

mold pack --dry-run is a preflight: which files would be captured, how many each filter removed, and the token verdict.

Dry run — nothing written. 129 files would be captured, 36 gitignored,
0 symlinks skipped.

mold pack --diff answers the other question a template author has — are my rules right? — without packing, distributing and unpacking first:

mold pack ./super_server --diff --var project_name=tempo

Preview — nothing written.
  129 files: 1 renamed, 18 rewritten (50 replacements), 111 unchanged.
...
--- linux/runner/my_application.cc
+++ linux/runner/my_application.cc
-    gtk_window_set_title(window, "app");
+    gtk_window_set_title(window, "tempo");

The files are read and checked as a pack would, then handed to the same planner unpack --diff uses, so the two cannot disagree — and an unpack's warnings, such as a value already in the template, show up in the preview too. Nothing is compressed. Values come from --var, --vars-file and manifest defaults only — pack never prompts, so it stays usable from CI.

---

Validation

Every phase is validated with structured, coded errors. An error-severity issue throws a ValidationException (the CLI exits 1); warnings never block, and reach onWarning — on stderr in the CLI.

Phase	Code	Meaning
pack	MANIFEST_MISSING_NAME	required field absent
pack	MANIFEST_MISSING_VERSION	required field absent
pack	MANIFEST_DUPLICATE_VARIABLE	two variables share a name
pack	MANIFEST_INVALID_GLOB	a bad pattern in include/exclude/no_substitute
pack	MANIFEST_EMPTY_REPLACES	replaces: ""
pack	MANIFEST_UNSUPPORTED_REPLACES	token has no ASCII word characters
pack	MANIFEST_MALFORMED_PLACEHOLDER	bad syntax inside {{ }}
pack	MANIFEST_UNTERMINATED_PLACEHOLDER	{{ with no }}
pack	MANIFEST_UNKNOWN_VARIABLE	placeholder names an undeclared variable
pack	MANIFEST_UNKNOWN_TRANSFORM	not one of the transforms listed above
pack	MANIFEST_UNUSED_VARIABLE ⚠	variable does nothing
pack	MANIFEST_DUPLICATE_SUBSTITUTION	two entries in one section share a from
pack	MANIFEST_CONFLICTING_TOKENS ⚠	two variables derive the same casing
pack	MANIFEST_INVALID_PATTERN	a variable's pattern does not compile
pack	MANIFEST_INVALID_DEFAULT	a default its own constraints reject
pack	MANIFEST_UNKNOWN_KEY ⚠	a key the format does not define
both	MANIFEST_INVALID	not UTF-8 YAML, or not shaped like a manifest
both	MANIFEST_NOT_FOUND	no manifest file at the path
pack	PROJECT_DIR_NOT_FOUND	source directory missing
pack	PROJECT_DIR_EMPTY	nothing to pack after filtering
pack	PROJECT_REPLACES_NOT_FOUND	token occurs in no captured file
pack	PROJECT_TOKEN_TOO_GENERIC	≥30% of matches are collateral
pack	PROJECT_PARTIAL_OVERLAP ⚠	≥5% of matches are collateral
pack	PROJECT_SYMLINK_SKIPPED ⚠	a symlink was left out, with the reason
pack	PROJECT_TOKEN_IN_VERBATIM ⚠	a token in files copied verbatim
pack	PROJECT_SUBSTITUTION_UNUSED ⚠	an extra_substitutions entry never fires
pack	PROJECT_PATH_RENAME_UNUSED ⚠	a path_renames entry never fires
pack	PROJECT_UNCOVERED_CASING ⚠	a spelling of a token no casing matches
pack	PROJECT_SECRET_SUSPECTED ⚠	a file that looks like a secret
pack	PROJECT_PATH_NOT_PORTABLE ⚠	a path not every platform can create
unpack	ARCHIVE_NOT_FOUND	no archive file at the path
unpack	ARCHIVE_INVALID	not a valid gzipped tar
unpack	ARCHIVE_TOO_LARGE	decompresses past the size ceiling
unpack	ARCHIVE_MISSING_MANIFEST	no embedded mold.yaml
unpack	ARCHIVE_MISSING_FILES	no files/ tree
unpack	ARCHIVE_UNSAFE_PATH	an entry escapes the target directory
unpack	TARGET_PARENT_NOT_FOUND	parent directory missing
unpack	TARGET_OCCUPIED	target is a file, or not empty (no --force)
unpack	TARGET_NOT_WRITABLE	no write permission
unpack	VARIABLE_MISSING	required variable has no value
unpack	VARIABLE_INVALID_FORMAT	value is not a well-formed name token
unpack	VARIABLE_UNKNOWN	--var names a variable the template lacks
unpack	VARIABLE_PATTERN_MISMATCH	value does not match the variable's pattern
unpack	VARIABLE_NOT_A_CHOICE	value is not one of the variable's choices
unpack	VARIABLE_VALUE_PRESENT ⚠	the value already occurs in the template
unpack	VARIABLE_DROPPED ⚠	a stamped value names a variable now gone
unpack	RENAME_COLLISION	two entries on one path, or a file under one
unpack	TARGET_PATH_CONFLICT	--force: a path is blocked in the target
unpack	RENAME_UNSAFE_PATH	a renamed path escapes the target
unpack	RENAME_CASE_COLLISION ⚠	renamed paths differ only in case
unpack	RENAME_INVALID_NAME	on Windows: a path Windows cannot create
unpack	UNPACK_STALE_FILES ⚠	files the template dropped, left in place
unpack	UNPACK_STAMP_INVALID ⚠	the target's .mold.json is not a stamp
unpack	UNPACK_STAMP_FOREIGN ⚠	the target's stamp is another template's
unpack	UNPACK_OVERWRITES_EDITS ⚠	overwriting files edited since the stamp
unpack	UNPACK_CHMOD_FAILED ⚠	files written, but not made executable
unpack	UNPACK_UNDO_INCOMPLETE ⚠	a failed write could not be fully undone

⚠ = warning; does not block. Every code is a constant on MoldCode.

Every warning is reported at both pack and unpack. A template is usually unpacked by someone other than its author, so a warning that only reached whoever packed it reached nobody.

Phase order — pack: Manifest → Project; unpack: Archive → Manifest → Target → Variables → Rename. The first failing phase aborts before the next runs. Target precedes variables so an interactive unpack does not make you answer every prompt before learning the destination is occupied. TARGET_PATH_CONFLICT is the one target check that runs after Rename: which paths conflict depends on where renaming puts each file.

Exit codes

code	meaning
0	success
1	validation, IO or format failure
64	usage error (bad arguments)

---

Library usage

import 'package:mold/mold.dart';

// Pack — always returns the gzipped-tar archive bytes.
final archive = await const Bundler().bundle(
  projectDir: './super_server',
  manifest: Manifest.fromFile('./super_server/mold.yaml'),
  onWarning: (warning) => print('Warning: $warning'),
);
await File('super_server.mold').writeAsBytes(archive);

// Unpack from bytes (e.g. an embedded template)…
await const Unbundler().unbundle(
  bytes: archive,
  targetDir: './my_project',
  vars: {'project_name': 'my_project'},
);

// …or from a file.
await const Unbundler().unbundleFile(
  source: 'super_server.mold',
  targetDir: './my_project',
  vars: {'project_name': 'my_project'},
);

onWarning receives each non-fatal problem as a ValidationError — a skipped symlink, a token that will over-reach, a failed chmod — with its code, so a caller can filter or escalate by code rather than by message.

Both unbundle options of the CLI are parameters: overwrite: true is --force, stamp: true is --stamp.

Errors

Every problem with the inputs — the manifest, the project, the archive, the variables, the target — throws a ValidationException; its errors carry stable codes, all listed as constants on MoldCode. A failing filesystem throws an IOException. Nothing else is expected: a StateError is a bug.

try {
  await const Unbundler().unbundle(bytes: archive, targetDir: dir);
} on ValidationException catch (e) {
  if (e.codes.contains(MoldCode.targetOccupied)) {
    // ask, then retry with overwrite: true
  }
}

The async methods report through their Future: nothing is thrown before it is returned.

Plan, show, apply

An unpack is two steps, and both are public. plan decides everything — validation, variables, where each file lands and the exact bytes it gets — and apply writes a plan. unbundle is the two in a row, so a preview and the write are the same computation, and a caller that shows a preview and asks first applies the plan it showed instead of computing it again:

const unbundler = Unbundler();
final plan = unbundler.plan(
  bytes: archive,
  targetDir: './my_project',
  vars: {'project_name': 'my_project'},
  overwrite: true,
);

for (final file in plan.overwritten.where((f) => !f.identicalToExisting)) {
  print(const UnifiedDiff().render(
    before: file.existing ?? '',
    after: file.after ?? '',
    fromLabel: '${file.to} (current)',
    toLabel: file.to,
  ));
}
if (confirmed) {
  await unbundler.apply(plan); // validates the target again first
}

Each PlannedFile carries from, to, verbatim, replacements, the bytes it will be written with, executable, and — with withContent (the default for plan) — the text before and after substitution. With overwrite: true it also says whether it overwrites a file already in the target, whether that file is identicalToExisting, and its existing text. plan.created, plan.overwritten and plan.stale split the files; a plan also carries the manifest and the resolved values. A plan made with no targetDir previews substitution only and cannot be applied.

To regenerate a project from its stamp, pass the stamp's values as recorded. They come after vars and before the resolver, and one naming a variable the template has dropped is a VARIABLE_DROPPED warning, not the VARIABLE_UNKNOWN error it would be in vars:

final stampFile = File('./my_project/${UnpackStamp.fileName}');
final stamp = stampFile.existsSync()
    ? UnpackStamp.tryParse(stampFile.readAsStringSync())
    : null;
final plan = unbundler.plan(
  bytes: archive,
  targetDir: './my_project',
  recorded: stamp?.vars ?? const {},
  overwrite: true,
);

inspect describes an archive without unpacking it — its manifest (and manifestYaml, as written), each file's size, which are executable.

Prompting

final resolver = VariableResolver(
  noPrompt: false, // true → defaults only, never prompt
  prompter: VariablePrompter(stdout, stdin.readLineSync),
);

await const Unbundler().unbundle(
  bytes: archive,
  targetDir: './my_project',
  resolver: resolver,
);

A variable left without a value is VARIABLE_MISSING.

---

Embedding a template in a binary

-f bytes / -f base64 emit a Dart source file (with an AUTO-GENERATED — DO NOT EDIT header) so a template can ship inside a compiled executable and scaffold offline.

The file is meant to be committed into your package, so it is made to pass your tooling unchanged. It carries // ignore_for_file: type=lint, the standard header of generated code: lint sets disagree about its very declarations (omit_obvious_property_types against always_specify_types), so no spelling of them would satisfy every set, and errors are still reported. And dart format leaves it as it is, in both the tall and the pre-3.7 style — no need to exclude it from a format check.

mold pack ./super_server -f bytes  -o lib/template.dart
mold pack ./super_server -f base64 -o lib/template.dart

// lib/template.dart (generated)
// AUTO-GENERATED — DO NOT EDIT.
// Produced by `mold pack`.

// ignore_for_file: type=lint

const List<int> kSuperServerTemplate = <int>[
  // 2741 bytes: a gzipped tar archive.
  31, 139, 8, 0, 0, 0, 0, 0, 0, 3, 237, 189, 107, 115, 219,
  // ...
];

import 'package:mold/mold.dart';
import 'template.dart';

await const Unbundler().unbundle(
  bytes: kSuperServerTemplate,
  targetDir: './my_project',
  vars: {'project_name': 'my_project'},
);

-n names both the output file and the generated const, so two templates packed from one manifest do not collide on the identifier.

To render the source yourself:

final dartSource = const EmbedSource()
    .bytesSource(archive: archive, name: 'super_server');

---

What is preserved

• The owner-executable bit — a template's scripts and hooks stay runnable.
• A leading UTF-8 BOM — Windows-authored .bat, .ps1 and .csproj keep their encoding marker.
• Bytes of anything not substituted — binaries, no_substitute matches, and any file that is not valid UTF-8, including CRLF, NUL bytes and emoji.

The archive is materialized in memory — no scratch directory is written to disk, and pack never mutates the source. Unpacking keeps each file as a view into the decompressed archive, and copies only the files substitution changes. On a 48 MB, 1731-file corpus: pack ~2.2 s (half of it the portable deflate; --fast or --level trade it), unpack ~0.4 s, peak memory ~300–360 MB.

Out of scope

• Templating the packed files. Project content is never evaluated — no conditionals, loops, partials or includes, and a {{ }} inside a packed file is just text. {{ }} is interpreted only in the manifest: a to: value and the message.
• Content-based binary detection — extensions only, no MIME sniffing. The UTF-8 fallback is a decode failure, not classification.
• File modes beyond the executable bit — no ownership, no full mode round trip.
• Preserving symlinks as symlinks — they are dereferenced, so an unpack needs no symlink privileges (Windows requires them).
• Empty directories — not represented in the archive.
• Compression other than gzip, encryption, or signing.
• Remote template registries or fetching over the network.
• Merging template updates into an edited project. --force regenerates over it and the stamp says what the template dropped, but a file the template has is replaced, not merged: edits in it are overwritten.