Hermes Agent
d555071406
Unify beginner syntax while preserving compatibility, repair ownership and parser guards, add verified distribution tooling and VC6 Windows 98 build inputs, and clarify documentation and release status. Preserve DOS build-input line endings and exclude generated binaries/caches.
138 lines
6.2 KiB
Markdown
138 lines
6.2 KiB
Markdown
# Claro v2026.10.20.223203 - Packages and Projects
|
|
|
|
Claro v2026.10.20.223203 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: v2026.10.20.223203
|
|
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 exactly one complete supported `manifest-version: 1` value. Missing, blank, unsupported (such as `10`), or duplicate format fields report `BAD package manifest version` with the package name, the manifest path, and a hint to keep exactly one `manifest-version: 1` line. The doctor leaves the file unchanged for you to repair; an absent manifest file still reports `MISSING package 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 lockfile must also contain exactly one current release line, `version: v2026.10.20.223203`. A missing, stale, blank, or duplicate release line fails with:
|
|
|
|
```text
|
|
BAD lock release version: expected exactly one version: v2026.10.20.223203 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 values and capitalization of the lock-format 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.
|