3.5 KiB
Claro v1.18.26 - Packages and Projects
Claro v1.18.26 makes projects and packages safer and more useful while keeping the beginner syntax simple.
Create a project
claro new MyProject
cd MyProject
claro run
A new project contains:
main.claro
claro.project
claro.lock
packages/
README.md
Project file
claro.project is intentionally plain text:
manifest-version: 1
name: MyProject
main: main.claro
version: v1.18.26
packages:
package: text
package: net_tools
Package commands
claro package init
claro package add text
claro package remove text
claro package list
claro package doctor
claro package lock
claro package add NAME creates a local folder:
packages/NAME/
claro.package
README.md
Each claro.package file includes a tiny manifest and checksum:
manifest-version: 1
name: text
version: 1
source: local
checksum: 1234abcd
claro.lock records the release version, lock format, packages, and checksums so future registry work has a stable safety foundation. claro package doctor checks those lockfile checksums for listed packages and reports BAD lock checksum: name if the lockfile is stale or edited incorrectly. It also reports BAD lock package not in claro.project: name when the lockfile contains a package entry that is not listed in claro.project, so learners know to refresh the lockfile instead of trusting stale package data. Package manifests must declare the complete supported manifest-version: 1 value; a prefix such as manifest-version: 10 is treated as a missing/unsupported manifest. They must also declare the complete expected name: value; a name that only starts with the package name is rejected as BAD package manifest name: name. The complete manifest checksum: value is checked too, so trailing or extra checksum text is rejected as BAD package checksum: name.
Project-name safety
claro new NAME checks the project name before creating folders. Project names may use only letters, numbers, dash, and underscore, and they must be 64 characters or fewer.
This keeps mistakes like ../bad from creating a project outside the folder where the learner is working.
Package-name safety
Package names may use only:
letters
numbers
dash
underscore
Package names must be 64 characters or fewer so Claro can create predictable local package folders and metadata paths.
This means simple names like these are allowed:
text
sdl
net_tools
my-package
Unsafe names are rejected:
../bad
folder/name
bad name
If an unsafe package name somehow gets into claro.project, package maintenance commands should not quietly continue. claro package doctor points out the bad name, claro package lock refuses to write lockfile data for it, claro package list refuses to display it as a normal package, claro package init refuses to report the project ready while the unsafe entry remains, and claro package remove NAME exits with an error if the lockfile refresh still sees an unsafe package name after the removal. Learners can still recover by removing the exact unsafe entry, such as claro package remove ../bad; Claro rewrites the project file and lockfile without using that unsafe name as a folder path.
Why this matters
Packages are important for Claro's future, but the workflow must stay friendly:
make a project
add a package
run the project
check the project
No complicated setup should be needed for a beginner.