just_asset_store 0.2.1

The core of the Just Asset Store: reads catalogs, checks item archives and installs items into Flutter projects as packages, with the `just store` commands.

Changelog

0.2.1

• The official catalog moved to https://asset.justunknown.com/index.json (SourceConfig.official), and with it the store website the editor links to (an item's page, reporting it, publishing).

0.2.0

A catalog in pieces, and what a store backend needs to check a release before downloading it.

• Catalog format 2. A published catalog is a small index.json naming pieces, catalog/<sha256>.json, each holding the items of one bucket (32 by default; an item's bucket is a hash of its id, so it stays put). An editor that read the catalog before asks for index.json again (an ETag makes that one small request) and fetches only the pieces it doesn't have: one new version changes one piece. Pieces are checked against their size and SHA-256, cached under it, and never change; offline, the last whole catalog is read from the cache, and a catalog that can't be read whole never replaces it. CatalogFiles.of writes one (the same items give the same bytes), CatalogRoot and CatalogPiece read one, and just store index build writes one. A catalog may still list its items in index.json itself (formats 1 and 2), which every source reads too. next pages and StoreSource.withPages are gone.
• Takedowns. A catalog's removed list names items the store took down and why; the planner warns about installed ones in every plan, just store info says so, and the editor's Problems dock shows an error. Only the catalog an item came from, or one that may vouch for items, can take it down.
• Checking before downloading. PackageCheck.checkLayout holds every package rule, on a package's paths and its two small files; PackageCheck.layoutOf builds that from a ZipDirectory (an archive's directory, read from its end with HTTP ranges), reading only those two files, so a backend gets the installer's verdict for a few kilobytes. PackageCheck.check runs the same rules before unpacking anything; PackageCheck.verify also unpacks and checks every file, one at a time, without keeping them. A just_store.json may be at most 256 KiB.
• The store page's fields in the package. just_store.json may carry summary, description, tags and author, which an unlisted install shows; just store pack warns when summary is missing. Code items declare permissions (network, files, processes, native), refused for content.
• Pictures. previews are at most 8 .png, .jpg or .webp files inside the package, each with a plain file name no other has. just store pack copies them beside the archive, so they go up as release files: where the store's backend and an unlisted install (whose previews are now those release files' links, not package paths) find them.
• Featured. A catalog may name the items its makers show first: featured in index.json (StoreIndex.featured, CatalogRoot.featured), in order; StoreIndex.featuredItems gives those it lists.
• Why a catalog failed, for people. SourceStatus.problem says why a catalog could not be read in a sentence (the network's own message, not an exception's name).
• Build hook settings. A package's pubspec may carry hooks: user_defines: for its own tests (pub reads them from the project alone, so installed they do nothing); anything else under hooks: is refused.
• Claim codes. claimCode(githubId) and isClaimCode; just_release.json carries one (JustRelease.claim), written by just store pack --claim. The item template's release workflow passes the repository variable JUST_STORE_CLAIM, and publishes its release only once every file is attached, as release immutability needs.

Safe with anyone's items:

• Pubspecs read as pub reads them. PubspecFacts parses with package:yaml, the parser pub uses, so a key spelled with YAML escapes ("dependencie\x73") or written as an explicit ? key is the key pub sees. Top-level fields are allow-listed; a dependency is a pub.dev version or an SDK, never a path, git or another server; and a code item's packages from pub.dev must be the ones the catalog shows (pubDependencies, which just store pack writes).
• Trust is never assumed. An item a catalog says nothing about is a community item (it used to be official), and the lockfile records official for the store's own (rebuilding one from the lockfile checks it as such). Only an official item may be part of the editor (system), so a community item can always be uninstalled. A folder catalog vouches for its items only on this machine, never on another machine's share. just store pack checks a package as a community item unless told otherwise (trust:); vendor checks your own linked checkout as official.
• Names. just, just_… and the Flutter SDK's packages are official items' alone (ReservedNames). A community item is not added to a project pub never resolved (the store couldn't tell whether the project already gets a package of that name), and no item in a plan may take the place of a package another one gets from pub.dev.
• Permissions in the catalog. A version lists what its manifest declares (StoreItemVersion.permissions), which must agree, and native code — the catalog's nativePlugins, or the item being a Flutter plugin itself — must be declared native. Every install shows what an item declares (ItemPermission.describe), as do just store info and the editor. just store pack lists the native plugins a package's resolved dependencies bring (NativeScan: Flutter plugins and packages with build hooks), leaving out what the project has anyway through requires and the store items it needs, and warns when the folder isn't resolved.
• Addresses. Catalog pictures are https (or beside the catalog); a catalog on the web never makes the store fetch from this machine or its network — archives, pictures, redirects (StoreSource.leadsInside, StoreSource.isPrivateHost, which also knows bare-number IPv4 forms and IPv4 inside IPv6). Catalog text — publisher, source id, licence, links, nativePlugins and the package names in requires and pubDependencies — is plain text or a package name.
• Size. No archive over 512 MiB (StoreArchive.maxSize) is planned, downloaded or restored, whatever a catalog says.

Tags:

• Stages. A version says how finished it is in its just_store.json: stage is stable, beta, experimental or deprecated (ItemStage), and a deprecated one may name what replaces it (replacedBy). Every plugin (editor tool or kit) names one: the package check refuses one without, and one whose catalog entry says otherwise. just store pack writes it into the catalog's version file; StoreItem.stage and replacedBy read the newest version's. Installing an experimental or deprecated version warns first, naming the replacement.
• Sources. ItemSource says where an item comes from — Official, Third Party, Unlisted (a GitHub release no catalog lists) or Local (a linked checkout) — from what the project recorded and the catalog, never from what the item says. just store search, info and list show both tags (Official · Beta; a stable item shows no stage).

0.1.1

Plugins get a folder of their own. Editor extensions and kits are code that comes only through the store, published on GitHub and never on pub.dev, so they now install into plugins/{category}/{name}/, apart from the content that stays in packages/{category}/{name}/. Templates still lay their files over the project.

• Where items go: ItemKind.isPlugin and ItemKind.installFolder say which folder a kind installs into; StoreProject.pluginsDir names the new one, StoreProject.itemRoots both, and StoreProject.itemPath(kind, category, id) replaces packagePath. Installs, updates, restore and vendor all use it, and the store's pubspec blocks point a plugin at plugins/….
• Checks: the lockfile accepts a vendored item only in its kind's folder, so a kit recorded under packages/ (or content under plugins/) is refused with the folder it should be in. The planner looks for existing folders in both, and refuses an install when either already holds the item's {category}/{name} folder, in any letter case where the file system ignores it: a second copy of the package that pub could take instead.
• Asset keys don't change: an item's assets are still packages/<name>/….

0.1.0

The first release of the Just Asset Store's core. It reads store catalogs, downloads and verifies items, and installs them into Just Game Engine projects as packages. It has no command-line tool of its own: its commands are a plugin of just (just_core_cli).

• Every platform. package:just_asset_store/just_asset_store.dart runs wherever Dart does, the web included, compiled to JavaScript or WebAssembly: catalogs (StoreIndex), item manifests (ItemManifest), the package checks, run on an archive in memory (PackageCheck), the lockfile (StoreLock), the generated registries' text (StoreCodegen), the store's pubspec block (storeBlock), and just_core_cli's versions, JSON fields, names, SHA-256 and ZIP archives. Where dart:io is (Windows, macOS, Linux, Android, iOS), the library also holds the store on disk: AssetStore with its sources, planner and installer, restoring, linking, the creator tools and the commands.
• Commands: just store install|update|uninstall|list|search|info|restore|generate|link|unlink|vendor|sources|cache|template, and for creators pack, validate and index build|check|codeowners. just add and just remove are shortcuts for install and uninstall; just check and just doctor run store generate --check. Each command has its own help and takes --json, --yes, --verbose and --project; arguments are checked before any catalog is read.
• Catalogs: index.json and just_store.json models, with strict validation that names the failing field: display text without control characters, pictures only on the web or beside the catalog, libraries in generated code only as plain paths of the item's own package. An item of a kind this version doesn't know is left out, not a reason to refuse the catalog; a catalog split into pages (next) is read whole. Fields are reserved for community publishers (trust, stats, takedowns) and paid items (pricing, entitled access, download brokers).
• Sources: folders; https catalogs with ETag caching, an offline fallback, redirects and polite retries; unlisted items straight from a GitHub release (just store install https://github.com/<owner>/<repo>[@<tag>], read from its just_release.json; code from one is installed with --yes only together with --unlisted). Only the official catalog says which items the store vouches for: every other catalog's items are community items. A project's sources keep the order they were added in, the official catalog first. Downloads are kept in a per-user cache keyed by SHA-256.
• The planner: the newest versions that fit together, going back on a choice when it leads nowhere; updates never go to an older version; versions the project's Dart, Flutter, engine and editor can run come first; items that depend on a changed item, name and folder clashes (in any letter case where the file system ignores it), and developer checkouts; installing an item already there as a dependency makes it one of the project's own; uninstall checks for code and scenes that still use the item, or a dependency that would go with it; versions taken down by their catalog are named in every plan.
• Installs: every archive is checked against its pin (size and SHA-256), read as an untrusted ZIP, and checked as a package — file types, no build hooks or platform folders in any case, dependencies only by version from pub.dev or on an SDK, every registered library present, the manifest's dependencies equal to the catalog's — before the project is touched. Then all or nothing: a journal, backups, rollback, crash recovery, and the project lock just uses, which every command that changes the project holds. What an install replaces goes to the editor's trash, .editor_trash/store/.
• Project files: edits only the store's marked blocks of pubspec.yaml and pubspec_overrides.yaml, keeping every other byte; writes to the file pub reads, and mirrors into pubspec.yaml when the overrides file is ignored by git. Generates lib/editor/store_modules.g.dart and lib/game/store_extensions.g.dart where the project can compile them, records just_store.lock.json, and restore rebuilds missing folders from it.
• Templates: just store template lays a project template's files over a project — never into git's, pub's or the tools' own files — and installs what it needs, in one change.
• Creator tools: pack writes a reproducible archive (text files in LF), the catalog's version file and just_release.json; validate checks a folder or an archive with the installer's own rules; index build|check|codeowners builds and checks a catalog repository (codeowners --file writes it as UTF-8; publishers' files are the maintainers' alone).