4.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 rejects duplicate package: entries with DUPLICATE lock package: name, so one package cannot have ambiguous lock data. 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. The project file must declare the complete supported manifest-version: 1 value; a prefix such as manifest-version: 10 is rejected as BAD project manifest version: expected 1. 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 exactly one expected name: value; duplicate or prefix-matching names are rejected as BAD package manifest name: name. The manifest must contain exactly one checksum field with the expected complete value; duplicate, trailing, or extra checksum text is rejected as BAD package checksum: name. Package manifests must also declare exactly one version: 1 field; duplicate or prefix-matching versions such as version: 10 are rejected as BAD package version: name. Package manifests must also declare the complete supported local source: local value. Prefixes such as source: local-extra are rejected as BAD package source: name rather than being accepted as valid local manifests.
If package doctor reports BAD package source: math-tools, open packages/math-tools/claro.package and keep exactly one source: local line. Duplicate source: lines are rejected even when both say local, or when a valid line appears before or after an unsupported source. The doctor leaves the file unchanged so you can review and repair it yourself.
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.