132 lines
5.7 KiB
Markdown
132 lines
5.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
claro new MyProject
|
|
cd MyProject
|
|
claro run
|
|
```
|
|
|
|
A new project contains:
|
|
|
|
```text
|
|
main.claro
|
|
claro.project
|
|
claro.lock
|
|
packages/
|
|
README.md
|
|
```
|
|
|
|
## Project file
|
|
|
|
`claro.project` is intentionally plain text:
|
|
|
|
```text
|
|
manifest-version: 1
|
|
name: MyProject
|
|
main: main.claro
|
|
version: v1.18.26
|
|
packages:
|
|
package: text
|
|
package: net_tools
|
|
```
|
|
|
|
## Package commands
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
packages/NAME/
|
|
claro.package
|
|
README.md
|
|
```
|
|
|
|
Each `claro.package` file includes a tiny manifest and checksum:
|
|
|
|
```text
|
|
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.
|
|
|
|
If `package doctor` reports `BAD lock checksum: math-tools`, check the `math-tools` entry in `claro.lock`. Each package must have exactly one matching `checksum:` line. Duplicate checksums are rejected even when they agree, or when a correct checksum appears before or after an incorrect one. The doctor leaves the file unchanged. After reviewing your project and package manifests, run `claro package lock` to regenerate the lockfile, then run `claro package doctor` again.
|
|
|
|
## Lock format safety
|
|
|
|
`claro package doctor` requires exactly one `lock-version: 1` line in `claro.lock`. Missing, empty, unsupported (such as `10`), or duplicate format versions now fail with:
|
|
|
|
```text
|
|
BAD lock version: expected exactly one lock-version: 1 line
|
|
```
|
|
|
|
The doctor leaves your files unchanged. After reviewing your project and package manifests, run `claro package lock` to regenerate the lockfile, then run `claro package doctor` again. Spaces around the value and capitalization of the field name are accepted, as with other lockfile fields. Valid generated lockfiles continue to work unchanged; this check does not add registry downloads or verify package content hashes.
|
|
|
|
## 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:
|
|
|
|
```text
|
|
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
|
|
text
|
|
sdl
|
|
net_tools
|
|
my-package
|
|
```
|
|
|
|
Unsafe names are rejected:
|
|
|
|
```text
|
|
../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:
|
|
|
|
```text
|
|
make a project
|
|
add a package
|
|
run the project
|
|
check the project
|
|
```
|
|
|
|
No complicated setup should be needed for a beginner.
|