project library
The project toolkit just and its plugins share: finding a project,
editing its pubspecs without disturbing them, changing it all or nothing,
running pub, and reading what pub resolved.
- JustProject: a project folder, and writeTextAtomic for its files;
JustProjectFile: its
just.json, read and saved with JustProject.readProjectFile and JustProject.writeProjectFile; ProjectPaths: the names of its files and folders. - PubspecEditor: edits inside one tool's ManagedBlock, keeping every other line, comment and line ending as it was.
- OverridesTarget: which file pub reads
dependency_overridesfrom. - ProjectLock and ProjectTransaction: one change at a time, journalled
so a failure or a crash is undone — in JustProject.changesDir, which
flutter cleanleaves alone. - SdkLocator, PubRunner: the Flutter SDK, and
pub get; ResolutionFiles: whatpub getwrites, for a change to back up. - PackageConfig, PackageGraph: what pub resolved.
- PackageSet and SetPackage: package versions that work together;
ToolSet: the tools
justkeeps a project on, and the kinds of projectjust createmakes; DevLinks: overrides to local checkouts. - ProjectNames, TemplateRenderer and GitIgnores: a new project's
names, its template filled in, and its
.gitignore. - Version, VersionConstraint, JsonFields, PackageNames, PubspecFields, Sha256, UserPaths, and paths: normalPath, resolveDots, resolvePath, samePath.
Classes
- CancelToken
- A request to stop a download or an install, checked between steps.
- Checkout
- A local checkout of one of the ecosystem's packages.
- DependencySpec
- A dependency as a tool writes it into a pubspec.
- DevLinks
-
Path overrides from a project to local checkouts, in
just dev link's own block ofpubspec_overrides.yaml— neverpubspec.yaml, because the paths are this machine's. - FlutterSdk
- A Flutter SDK on this machine.
- GitHubRepo
-
A GitHub repository, as
https://github.com/<owner>/<repo>names it. - GitIgnores
-
A project's
.gitignore, added to without disturbing it. - GraphNode
- One package in PackageGraph.
- HostedDependency
-
name: ^1.2.0, from pub.dev (or url's repository). - JsonFields
- A JSON object read field by field, each read naming its path when it fails. Unknown fields are ignored, so newer files still read.
- JustProject
-
A Dart or Flutter project: the folder holding its
pubspec.yaml. - JustProjectFile
-
A project's
just.json. - ManagedBlock
-
Whose block a PubspecEditor edits: the markers around the entries one
tool owns. Each tool edits only its own block, so several tools — a
plugin that installs packages,
just dev link— can manage overrides in the same file. Each tool defines its own block, and keeps its markers as projects already hold them. - OtherDependency
- A dependency written in a form a tool doesn't write itself (git, sdk, flow maps with several keys…). Kept as text.
- OverridesTarget
-
Where a tool writes
dependency_overrides. - PackageConfig
-
.dart_tool/package_config.json: every package in the resolution and its folder, plus the Flutter SDK that resolved it. - PackageGraph
-
.dart_tool/package_graph.json: who depends on whom, and at which version — what a tool checks constraints against, since overrides skip pub's own checks. - PackageNames
- Rules for package names (pub's) and the names written into generated code.
- PackageSet
- Packages, at versions that work together, under a name (id).
- PathDependency
-
name: {path: ...}, written as a block. - PluginManifest
-
A package's
just_plugin.json: the commands it adds tojust. - ProcessPubRunner
-
Runs the SDK's own
dart pub get, which needs no Flutter tool lock — so it works whileflutter runholds one — and falls back toflutter pub get. - ProjectLock
- One change at a time per project: an install, an edit, an upgrade.
- ProjectNames
- What a new project is called, and how its files name it.
- ProjectPaths
-
Where things are in a project, relative to its root, with
/between parts — the names alone, so code on any platform (the web included) can use them.JustProject(inpackage:just_core_cli/project.dart) finds them on disk. - ProjectTransaction
- One change to a project, journalled so it can be undone.
- PubResult
-
What a
pub getrun printed, and whether it worked. - PubRunner
-
Runs
pub getfor a project. Tests use a fake. - PubspecConstraints
-
Edits the constraint of an entry written on one line —
name: ^1.2.3— in a top-level section, leaving every other byte as it was: comments, order, line endings, the section's indent. Entries written as blocks or flow collections (path:,git:,{path: ..}) and entries inside a tool's managed block are left alone. - PubspecEditor
-
A
pubspec.yamlorpubspec_overrides.yamlheld as lines, edited only inside one tool's marked block (marker) — heremy_tool's, made withManagedBlock('my_tool', hint: 'my_tool add'): - PubspecFields
-
Reads a pubspec's own top-level
name:andversion:. - ResolutionFiles
-
The files
pub get(andflutter pub get) writes in a project: what a change that runs it backs up first, so a rollback puts the old resolution back whole — the lock, the package config and graph, Flutter's plugin lists, and each platform's generated plugin registrant — and the next build doesn't link plugins the restored packages don't have. - ResolvedPackage
- A package pub resolved, and where it is on disk.
- SdkLocator
- Finds the Flutter SDK a project uses.
- SdkSettings
-
The user's answers to "Download Flutter X?", kept in
sdks.jsonin their settings folder (UserPaths.configDir) for every project: - SetPackage
- One package of a set.
- Sha256
- A running SHA-256 hash: add the data in pieces, then close.
- TemplateRenderer
- Fills a template's placeholders for one project.
- ToolSet
-
The tools
justkeeps a project on: just_core_cli itself, and the plugin of each kind of projectjust createmakes (kinds). - UserPaths
-
Per-user folders shared by the
justtool and what builds on it, outside any project: caches and settings. - Version
-
A semantic version (semver 2.0):
1.2.3,1.2.3-dev.4,1.2.3+5. - VersionConstraint
-
Which versions are acceptable, written the way pubspecs write it:
any,1.2.3,^1.2.3,>=1.0.0 <2.0.0.
Enums
- PackageSource
- Where a package in a set comes from.
Constants
- justCoreCliVersion → const String
-
The version of just_core_cli — kept equal to
pubspec.yaml's by a test.
Functions
-
canonicalJson(
Object? value, {bool pretty = true}) → String -
valueas the ecosystem's tools write every JSON file: keys sorted, two-space indents, LF line endings and a final newline. The same data always gives the same bytes, so files diff cleanly and hash stably. -
compactJson(
Map< String, Object?> map) → Map<String, Object?> -
Drops null values and empty lists or maps from
map, so files only carry what is set. -
copyAtomic(
File from, File file) → void -
Replaces
filewith a copy offrom, as writeBytesAtomic writes: never seen half-written, through a symbolic link, and withfrom's permissions on macOS and Linux. -
isSha256Hex(
String text) → bool -
Whether
textis a SHA-256 digest written as 64 lowercase hex digits. -
normalPath(
String path) → String -
pathwith/between parts and no trailing/(a drive root such asC:/keeps its own). -
pathRoot(
String path) → String -
The part of
path(with/) no..climbs above: a drive (C:/), a network share (//server/share/) or/; empty for a relative path. -
resolveDots(
String path) → String -
pathwith/between parts and its.and..parts resolved:C:/app/./lib/../assetsisC:/app/assets. A drive, a network share or/keeps its own form, and..never climbs above it. -
resolvePath(
String base, String path, {required bool windows}) → String -
pathas an absolute path, from the folderbase(absolute) when it is relative:/between parts, its.and..resolved. -
retryOnLock<
T> (T action(), {int attempts = 6}) → T -
Runs
action, retrying a few times with growing pauses when Windows says a file is in use (an antivirus scan, an indexer, the analyzer). -
samePath(
String a, String b) → bool -
Whether
aandbname the same path on this system: ignoring case on Windows and macOS. -
writeBytesAtomic(
File file, List< int> bytes) → void - writeTextAtomic for bytes.
-
writeTextAtomic(
File file, String text) → void -
Writes
texttofileso that it is never seen half-written: into a temporary.savingfile beside it — named for this write alone, so two writers never share one — then renamed over it. The temporary file is removed when anything fails.
Typedefs
- ByteProgress = void Function(int received, int? total)
-
Reports bytes received so far, out of
totalwhen known.
Exceptions / Errors
- CancelledException
- Work stopped because a CancelToken was cancelled.
- DevLinkClash
- The same package checked out in more than one of the folders given to DevLinks.scanAll.
- JsonFormatException
- A JSON file that is not valid: wrong JSON shape, a missing field, a value out of range.
- ProjectBusyException
- Another tool is changing the project right now.
- PubspecEditException
- A pubspec a tool can't edit safely, or an edit that would clash with lines it doesn't own.