Skip to main content

just_core_cli 0.2.0 copy "just_core_cli: ^0.2.0" to clipboard
just_core_cli: ^0.2.0 copied to clipboard

The core of `just` (also `ju`), the Just ecosystem's command-line tool: projects, plugins and hooks, version sets, safe pubspec edits, transactions and downloads.

Just Core Cli #

The core of just (also ju), the Just ecosystem's command-line tool. It knows no product of its own: it makes projects, keeps their tools on versions that work together, checks their setup, links them to local checkouts, changes them all or nothing, and runs the commands and hooks plugins add. Everything a product needs — its template, its packages' versions, its checks, its file migrations — comes from its plugin.

The first product built on it is the Just Game Engine: every game has the just_game_engine_cli plugin, which adds just game run|build|scene… and fills in the hooks below; the Asset Store adds just store, add and remove. Your own plugin builds on the same framework.

ju is the same tool under a second name, for machines where just is another program (such as the just command runner).

Install #

dart pub global activate just_core_cli

Or download just and ju for Windows, macOS or Linux from the releases (the install scripts in tool/ do it for you, and never put our just in front of another). just doctor checks the rest.

Use #

just create my_game                 # a new project of a kind (--kind game, the default)
cd my_game
just check                          # every installed plugin's checks
just doctor                         # Flutter, the tools, links, then each plugin's checks
just upgrade                        # the tools, each plugin's packages, then its migrations
just dev link ../packages ../plugins  # point the project at local checkouts
just dev unlink
just flutter pub add http           # the Flutter the project pins (just dart … too)
just sdk list                       # the Flutter SDKs just installed, and the others
just sdk install                    # the Flutter the project pins
just version
just help game run                  # a plugin command's own help

create <folder> takes --kind, --template, --title, --org, --platforms, --local <folder> (once for each folder of checkouts) and --source <catalog>. It runs flutter create, writes just.json, adds just_core_cli and the kind's plugin to the dev dependencies as pub.dev versions (with --local, pubspec_overrides.yaml also points every just_* package in those folders at its checkout; a package checked out in two of them is refused), fetches the packages, and hands the project to the plugin's create hook. On a failure the folder is deleted when create made it, or emptied when it was there already, empty; anything that can't be deleted (a file in use) is named.

Every command takes --json (one JSON document on stdout, messages on stderr), --yes (go ahead without asking, for scripts and CI), --verbose, --no-color and --project <folder> (a folder without a pubspec.yaml is no project), before or after its name but before a --. just flutter and just dart are the exception: everything after their name is Flutter's or Dart's, so just's own options go before it (just --yes flutter build web).

At a terminal that shows colours, just marks what it found with ✓ ! ✗, shows each step as it runs and how long it took — keeping the programs' own output out of sight unless a step fails (--verbose shows it as it comes) — and draws a progress bar for downloads. Pipes, scripts, --json, --no-color, NO_COLOR and JUST_CORE_CLI_COLOR=never get plain text.

Exit codes:

  • 0 done, or nothing to do.
  • 1 failed. A change that fails is rolled back first; if even that fails (a file in use), the message names what is left, and the next run that changes the project finishes the rollback. Two steps come after the change is kept, and a failure there exits 1 too while keeping it: a plugin's migrations at the end of upgrade, and a plugin's link hook after dev link or dev unlink. The message says which.
  • 2 called wrongly: an unknown command, a missing argument, a bad option.
  • A plugin's command, and a run handed to the project's pinned just, exit with that process's code; a process ended by a signal gives 128 + the signal's number, as a shell does.

Plugins' commands hand the terminal to the plugin, which prints its own document.

Flutter is found through FLUTTER_ROOT first — set it to the SDK's folder, and that SDK is used — then the SDK that last fetched the project's packages, then flutter on the PATH. When flutter there is a launcher outside the SDK (a snap, a version manager's shim), just asks it where its SDK is (flutter --version --machine, stopped after 20 seconds). A project that pins a Flutter version gets that version first (see below).

How it works #

  • Projects pin their own just. A project lists just_core_cli in its dev dependencies; a global just run inside it hands over to that version (all but upgrade, which moves the pin itself), so a team runs the same tool whatever each person installed. The pinned version is code the project chose, so it gets the run under the plugins' trust rule (below): from pub.dev, github.com/just-unknown-dev or a local checkout of yours, at once; from anywhere else — a folder of the repository you cloned, a git repository of someone else's — only once you allowed just_core_cli (asked once in a terminal, kept in just.json); until then your own just runs the command and says so. A fresh clone's packages are fetched first, except for just help; when that pub get fails, your just runs the command.
  • Projects pin their Flutter. "flutter": "3.47.9" in just.json is the Flutter a project is built with: the kind's plugin sets it (just: flutter: in its own pubspec, which pub.dev serves, so just create reads it before the plugin is fetched), and just upgrade moves it with the plugin. Every command that runs Flutter uses that version, found anywhere on the machine — the SDKs just installed (~/.just/flutter/<version>, or JUST_CORE_CLI_FLUTTER_DIR), FLUTTER_ROOT, the SDK that last ran pub, flutter on the PATH, fvm's SDKs (only read) — or, when it isn't there, installed from Flutter's own downloads once you say so: asked once (always stops asking; n warns and carries on with another Flutter, and isn't asked again until just sdk install). --yes installs it; with no terminal and no --yes, just warns and carries on. The download is checked against Flutter's SHA-256, resumes when cut short, and the SDK isn't used until its first run passes. Plain flutter and an editor may still use another version: just flutter … doesn't, just doctor says when they differ, and a new project's .vscode/settings.json points VS Code at just sdk path.
  • Versions travel in sets. The core carries one set, the tool set (ToolSet): just_core_cli itself and the plugin of each kind of project (game → just_game_engine_cli). Its id is just.json's set. Each plugin carries the versions of its own packages and moves them through its upgrade hook — the game plugin's GameSet holds the engine's, and the Flutter and Dart it needs.
  • Packages add commands. A package with a just_plugin.json and a bin/just_plugin.dart adds commands; just runs them with dart run, at the version the project resolved, or from a package installed with dart pub global activate. The ecosystem's own packages (PluginTrust.official) run without asking when they come from a local checkout or github.com/just-unknown-dev, and from pub.dev only under the names the ecosystem publishes there (PluginTrust.onPubDev: just_core_cli; just_game_engine_cli, published right after 0.1.0; and just_asset_store, right after 0.1.1 — a name is added in the release that goes out with its first publication, as until then anyone could take it). A local checkout (PluginTrust.isCheckout) is a git repository of its own, or a folder outside the repository the project is in: never the project itself, and never a folder that came with it — a cloned repository can name any folder just_game_engine_cli. An item the Asset Store installed is official when the store's lockfile says so. Any other asks once in a terminal, and the answer is kept in the project's just.json, or in plugins.json in your user settings — for a global one, and for every project. --yes never allows one. (A project's just.json is the project's own say: a repository you clone can allow its own plugins there, as it can pin its own just. Read it before you run just in a project you don't trust.)
  • Changes are all or nothing. Every change to a project is journalled and backed up first; a failure puts every file the change wrote back byte for byte, permissions included (a symbolic link stays a link, and the file it points to is the one written — only inside the project: a link that leads out of it is refused), and a crash is rolled back the next time. A change that runs pub get backs up everything pub and Flutter write in the project (ResolutionFiles: the lock, .dart_tool/package_config.json, Flutter's plugin lists, each platform's plugin registrant), and a rollback after it fetches the old packages again from the cache (pub get --offline), which also brings back what a pub workspace's root holds. Journals, backups and the lock live in .just_changes/ — not in .dart_tool/, so a flutter clean after a crash can't take them; the folder ignores itself in git. A journal just_core_cli 0.1 left in .dart_tool/just_core_cli/ is still recovered. One change runs at a time: a project lock says who holds it, and is taken over once its holder stops renewing it, or at once when that holder was a process on this machine, in this system (not WSL beside Windows, not a Flatpak sandbox beside its host), that is no longer running. What a change replaces or removes goes to the trash — .just_trash/<tool>/ unless the tool keeps its own (the game's commands and the Asset Store use the editor's .editor_trash/).
  • Pubspecs keep every other byte. A tool edits only its own marked block of a pubspec (ManagedBlock; every edit names one), never another tool's, and leaves comments, order and line endings as they were.
  • The core names no product. Two pieces of data are the exception: the ecosystem's own package names (PluginTrust.official, the trust policy: which plugins run without asking) and the tool set (ToolSet.current: just_core_cli, the plugin of each kind of project, and the kind map). Everything a product needs comes from its plugin.

Hooks #

A manifest's hooks name the plugin's commands for six moments. They run under the same trust rule as the plugin's commands (one that isn't trusted is asked about in a terminal, or skipped with a warning — never silently), get --json and --verbose when the run had them, and with --json their own documents go into the run's result under the plugin's name. upgrade hooks are the exception: they always get --json, because just reads what they would move from their document. Every option just passes comes before a --, and one with a value as a single --name=value argument.

Hook When Contract
create just create, in the new project Fill it in. Gets --title=…, --org=…, --platforms=…, --template=…, --source=…, --local=… (one for each folder) as given, --yes only when the user gave it. Must keep just_core_cli and itself in dev_dependencies, one line each, so upgrade can move them.
check just check Exit 0 when all is well. just check fails when nothing was checked.
doctor just doctor The plugin's own checks.
upgrade just upgrade, in its transaction Move the plugin's own packages: one-line constraint bumps in pubspec.yaml, no pub get, no other file, no lock. --check changes nothing; its document lists packages: {name: {from, to}}.
migrate just upgrade, before and after the move Bring the plugin's files up to date. --yes only once the user said yes; without it, ask before rewriting. Its result's migrated lists what it rewrote.
link just dev link, just dev unlink After a link, <name>=<path> for every checkout; before an unlink, --unlink --check (non-zero keeps the links); after it, --unlink.

--check. Wherever just calls a hook with --check, the hook must change nothing and exit non-zero, saying why, when what it would do could not be done. One that can't check exits with a usage error (2, or 64): just warns and goes on.

just upgrade moves the tools; when they stay, it asks each upgrade hook with --check what it would move, and says "up to date" when nothing would. Before anything changes it asks each migrate hook with --check. Then, in one transaction: the tools, pub get, each upgrade hook, pub get again when the pubspec changed, each migrate --check again with the new packages, just.json — any failure rolls it all back. Then the migrations run. Anything after -- goes to every migrate hook: just upgrade -- --engine-only.

Platforms #

  • The just tool runs on Windows, macOS and Linux, where Flutter does.
  • The toolkit in package:just_core_cli/just_core_cli.dart runs on every platform Dart does: Windows, macOS, Linux, Android, iOS, and the web, compiled to JavaScript or WebAssembly. On the web that library holds only the toolkit; everywhere else it holds the command framework too.
  • package:just_core_cli/project.dart and package:just_core_cli/fetch.dart work on files and the network, so they need dart:io: every platform but the web.

As a library #

  • package:just_core_cli/just_core_cli.dart, on every platform: JSON fields, names and versions (JsonFields, PackageNames, Version, VersionConstraint), Sha256, ZIP files read and written in memory (ZipArchive, ZipWriter, SafePaths), pubspec edits that keep every other byte (PubspecEditor, ManagedBlock, PubspecConstraints), templates (TemplateRenderer, ProjectNames, GitIgnores), version sets (PackageSet, ToolSet), just.json (JustProjectFile), plugin manifests (PluginManifest, and its hook contract), Finding, ExitCodes, ProjectPaths, PubspecFields, CancelToken, GitHubRepo, and paths as text (normalPath, resolveDots, resolvePath). Off the web it also holds the command framework plugins build on: JustCommand, runJustPlugin, Output, Launcher, the plugins and their trust rule, and runTrustedPlugin to call another plugin.
  • package:just_core_cli/project.dart: the project on disk — JustProject (with readProjectFile/writeProjectFile for just.json), transactions and the project lock, pub and the Flutter SDK (PackageConfig, PackageGraph, ResolutionFiles), DevLinks, and the toolkit above.
  • package:just_core_cli/fetch.dart: HTTPS downloads pinned by size and SHA-256 — with a hook that checks every redirect before anything is sent there (allowRedirect), for a caller with rules of its own about where a download may go — the download cache, and the ZIP toolkit.

The example is a plugin that adds just hello; just_game_engine_cli is a complete one.

1
likes
160
points
731
downloads

Documentation

API reference

Publisher

verified publisherjustunknown.com

Weekly Downloads

The core of `just` (also `ju`), the Just ecosystem's command-line tool: projects, plugins and hooks, version sets, safe pubspec edits, transactions and downloads.

Repository (GitHub)
View/report issues
Contributing

Topics

#cli #gamedev #game-engine #flutter

License

BSD-3-Clause (license)

Dependencies

args, just_deflate, meta

More

Packages that depend on just_core_cli