The Arche Store
The Arche Store is a place to share what you write in arche-lang. A project takes a package from it with one command, and archec checks the package before it writes anything. You can also publish your own packages, or run a store of your own.
Before writing a type, a unit, a board or a controller yourself, look on the
shelves: archec shelf lists what is ready to take.
A first package#
A store can be a plain folder. Make one, publish a small library to it, and add the library to a project.
lib/library.arche says what the store needs to know:
library blinker "LED blinker" {
description "A component that blinks an LED."
kind driver
owner demo
version "0.1.0"
license "Apache-2.0"
export-control none
}
component Blinker "Blinker" {
var on: bool = false
}archec store init store
archec store publish lib --store store
! no `archec` range: say which archec versions read it (`archec ">=0.10"`)
! no `edition`: archec reads it as the oldest; `edition "0.12"` says which spellings it uses
! no README.md: the card shows only what archec reads from the model
a signing key for demo was made: ~/.arche/keys/demo.pem — keep it, it is how the store knows you
publisher demo registered with key d9ded01eb8928734
✓ demo/blinker 0.1.0 → store
Then, in a project folder whose main.arche has a project "…" { … } block:
archec add main.arche demo/blinker --store ../store
✓ demo/blinker 0.1.0 (community) → .arche/store/blinker@0.1.0
no code: model only
wrote: uses blinker "^0.1"
✓ arche.lock updated
now `include "blinker/…"` the files you need
The project block now has uses blinker "^0.1", and arche.lock records the
version, its fingerprint and the key that signed it.
What a package can be#
- architectures: whole models to reuse or extend;
- drivers: a component and its code;
- specifications: requirements, interfaces, ICDs;
- boards;
- templates: projects to start from;
- UI kits: a theme for the product's screens (see below);
- libraries of parts and types;
- generators: code generators of your own (see generators.md).
A script or a command that a generator brings runs only after
archec generator approvehas recorded it. - plugins: generators, importers and exporters together (see plugins.md).
archec new my-project --from owner/name copies a package into a new project
instead. The copy is yours to change, and derived-from says where it came from
(see new.md).
Taking a package#
archec store search can fd --kind driver
archec add main.arche acme/can-fd@^1.2
The store is the hosted one, https://store.arche-lang.xyz, unless you name another. archec looks, in this order, at:
--store <where>;ARCHE_STORE;- what
archec store use <folder | git URL | https URL>wrote in~/.arche/config.json.
ARCHE_STORE= (set, but empty) keeps archec off the hosted store.
archec add takes the newest version in the range that this archec can read. Then
it checks that:
- the archive is the one the store published (its hash);
- its publisher signed it, with a key the store lists for that owner (Ed25519);
- its files are the ones signed (their fingerprint);
- the project accepts its publisher. The project's
trustsays which:trust verifiedtakes only verified publishers (board vendors, known projects);trust reviewedalso takes packages that a store reviewer has read;trust community(the default) takes any.
- when the version has a Sigstore bundle, that the bundle
is for this archive and names the identity the store recorded; with cosign
installed, that cosign verifies it. A project with
sigstorein itstrust(trust reviewed, sigstore) takes only packages whose bundle cosign verified.
If a check fails, nothing is written. Otherwise archec:
- unpacks the package into
.arche/store/<name>@<version>/; - writes
uses <name> "^1.2"in the project block; - records the store id, version, fingerprint and signing key in
arche.lock; - lists the code the package brings. That code reaches firmware through
archec gen, so read it.
Commit arche.lock, not .arche/. On a fresh checkout, archec store fetch main.arche takes the locked versions again and checks them against the lock.
archec audit main.arche # every piece of code, by where it came from
archec store outdated main.arche # newer versions, and yanks
archec store diff acme/can-fd 1.2.0 1.3.0 # what the model gained, lost or changed
Each package page shows the same diff, newest version against the one before
(and a picker for earlier pairs), what the package uses and what uses it, and
warns when it uses a package the store lacks or a range whose versions are all
yanked. archec store deps <index> checks that across the whole store. Each
owner has a page (u/<owner>.html) with their packages and collections.
Generated files say where their code came from:
/* … Its model and code: from store package acme/can-fd 1.2.0 (sha256-…, community). */.
Publishing#
A package is a library folder. Its library.arche says what the store needs:
library can-fd "CAN-FD driver for STM32G4" {
description "FDCAN frames: classic CAN and CAN FD, bit timing from the clock."
version "1.2.0"
owner acme
kind driver
license "Apache-2.0"
export-control none
archec ">=0.10"
edition "0.12"
keywords can, stm32, automotive
derived-from "arche/nucleo-g474re@^0.1"
}
archec store check . # what would be refused, warned about, or held
archec store card . -o card.html
archec store publish .
archec store check on the first example prints:
! no `archec` range: say which archec versions read it (`archec ">=0.10"`)
! no `edition`: archec reads it as the oldest; `edition "0.12"` says which spellings it uses
! no README.md: the card shows only what archec reads from the model
✓ demo/blinker 0.1.0: 1 file(s), 0.2 KiB — ready to publish
--dry-run packs the package and compiles it as the store's validator does, and
sends nothing. The package is unpacked on its own, and what it uses is taken from
the folder's .arche/store/.
Some files are never part of a package: dot files, and what archec builds at the
top of a folder (generated/ and arche-out/). So a project can be its own
package (archec new --kind library).
The first publish makes your signing key in ~/.arche/keys/<owner>.pem, and
registers the owner with it. Keep that file: it is how the store knows you.
A published version never changes. To withdraw one, run
archec store yank acme/can-fd@1.2.0 --reason "…". After that, archec add no
longer takes it, and archec store outdated tells the projects that have it.
The handler language#
archec store check also says the package's handler language
(see handlers.md). It is the project's handlers property.
Without one, archec looks at the code:
- a
.tsfile or a```tsblock is TypeScript; - a
.pyfile or a```pythonblock is Python; - bodies all in
```archeare the action language, which Arche runs as TypeScript.
The store records the language. The package card shows it (Handlers), and the package list shows it beside the kind.
The validator reads the TypeScript itself: it blanks out the types, so nothing
needs installing. It gives the package a badge, typescript: pass, or the first
line that does not read. It gives Python packages a badge in the same way.
The Try it page runs TypeScript in the visitor's browser, as it runs the action language. Nothing is loaded for it: no Pyodide, no compiler.
Badges#
The validator compiles each package as a project that uses it would. That is
the archec badge. Once the package compiles, it adds these badges. Each one is
pass, fail, or skip with the reason. A tool that is not installed where the
check runs gives a skip, never a pass.
| Badge | What it checks | Skipped when |
|---|---|---|
own tests (tests) |
The package's own test cases, run on the browser simulator in node (as archec test --sim web), and its formal requirements when NuSMV or nuXmv is installed. A case the browser simulator cannot run (a Python step) is counted apart, not as a failure. |
the package has no test case and no formal requirement |
style (vet) (vet) |
The findings archec vet reports on the package's own files. It fails with their count. |
never |
MISRA C (misra) |
cppcheck's MISRA C:2012 addon (cppcheck --addon=misra) on the package's C files, and on the C that archec gen --target c writes when the package has behaviour. |
cppcheck or its addon is not installed. There is no badge when the package has no C at all. |
clippy (clippy) |
cargo clippy --offline on the package's own crate (a Cargo.toml), or else on the crate that archec gen --target embassy writes for its deployment. A warning fails it. |
cargo or clippy is not installed, or cargo cannot build the crate offline (a dependency is not in its cache, a target is not installed). There is no badge when there is no Rust. |
The hosted store computes the badges when a version is published.
archec store test <index> --write computes them again for every package.
Every tool runs with a time limit: ARCHEC_STORE_TIMEOUT seconds, 120 by
default. A tool that runs out of time is stopped, and its badge is a skip that
says so. The test cases stop being run when that much time has passed. The cargo
build cache is shared between checks: ARCHEC_STORE_CARGO_TARGET, by default
arche-store-cargo-target in the temporary folder.
The package page shows the badges in English and in French. The reason or the first findings show when you hover over a badge.
Sigstore provenance#
Your key in ~/.arche/keys signs every package. A package can also carry
Sigstore provenance. This is a bundle that cosign sign-blob makes over the
.archepkg. It says who signed the package: a GitHub Actions workflow, or an
e-mail address. That identity is in the certificate Fulcio issued, and the
signature is logged in Rekor.
archec store pack . -o out/
cosign sign-blob --bundle can-fd.sigstore.json out/acme-can-fd-1.2.0.archepkg
archec store publish . --sigstore can-fd.sigstore.json
Sign the archive that archec store pack writes: the same folder always packs
to the same bytes. If the bundle signs other bytes, the publish is refused.
The store keeps the bundle beside the archive
(archives/<owner>/<name>/<version>.archepkg.sigstore.json). It records the
certificate's identity and issuer:
- the identity is the URI or the e-mail address in the certificate's subjectAltName;
- the issuer is the OIDC issuer from Fulcio's extension 1.3.6.1.4.1.57264.1.8, or from the older 1.3.6.1.4.1.57264.1.1.
When cosign is on the PATH, the store runs cosign verify-blob --bundle … --certificate-identity <identity> --certificate-oidc-issuer <issuer>. If cosign
does not verify the bundle, the publish is refused. Without cosign, the store
keeps the bundle and marks it as not verified. The package page shows
Sigstore:
archec add checks the bundle in the same way. To require Sigstore in a
project, add sigstore to its trust:
project App {
trust reviewed, sigstore
}
That project then takes only packages that have a bundle cosign verified on the
machine that ran archec add. archec check reports library-sigstore for a
package that was taken without one. archec store verify-index also checks
every bundle against its archive.
archec reads the bundle with node's crypto only: there is no Sigstore library to
install. It reads both formats: the Sigstore bundle (cosign sign-blob --new-bundle-format, the default from cosign 3) and cosign's older one. archec
itself checks only that the bundle is for this archive and the identity it
names. The signature, the certificate chain up to Fulcio and the Rekor entry are
checked by cosign. Without cosign, the identity shown is what the bundle claims,
and nothing more. A bundle signed with a key (cosign sign-blob --key) is
refused: it names no identity.
What publishing refuses#
- a package with no
owner,licenseorexport-control; - anything that could run on install: scripts, binaries, files marked executable, links;
- a file that does not parse;
- a package of more than 20 MB.
Export control#
export-control is your statement as publisher: none, ear99, or a control
number. Publishing controlled technical data is itself an export.
A package whose text reads like defence technology (radar, seeker, guidance, missile, fire control…) is held until a store reviewer releases it, whatever it declares. Technology under ITAR, or that needs an export licence, is not accepted. This is not legal advice.
What a package page shows#
archec store site draws each package from its own files. Above the README, the
page shows what the package is:
- Architecture: the block diagram of its system, as
archec diagramdraws it; - The board: the picture
archec board picturedraws, for akind boardpackage (four at most, then "and N more"); - Hardware: the boards and devices of its system, wired, when it has some;
- Animations: its
animations (six at most), played as a slide plays them.
The README's ```arche blocks and the package's .arche files (under
Files) are coloured as the editor colours them, light or dark.
A package whose model has bodies and joints gets a 3D button and its own page,
p/<owner>/<name>.3d.html, in English and in French. The page draws the bodies,
with the joints on sliders. It loads MuJoCo to run the model's controllers against
the bodies. MuJoCo comes from $ARCHE_MUJOCO_URL, else from mujocoUrl in the
store's store.json (its mujoco.js, or the folder it is in), else from
https://arche-lang.xyz/playground/mujoco/. Set it to none to leave MuJoCo out;
the page then shows the model and its sliders only. If MuJoCo is on another site,
that site must allow cross-origin requests. archec store serve lets that origin,
and WebAssembly, into the 3D pages' content security policy, and only those pages.
A model with errors, or one that cannot be drawn, shows none of this. The page is built without it.
Publishing a Capella model or Polarion requirements#
archec store package turns an import into a package in one step:
archec store package drone-arch --from capella "Demo drone.aird" \
--owner acme --license Apache-2.0 --export-control none
archec store package system-reqs --from polarion polarion.yaml \
--owner acme --license Apache-2.0 --export-control none --version 1.0.0
It works in four steps:
- It runs the importer into the new folder. For Capella, this is
archec capella(a.capella, its.aird, its folder or a zip;--prefix,--layersand--no-diagramsare passed on). For Polarion, the work items becomerequirements.arche. They come from a JSON export (with--config polarion.yamlfor its field map), or are pulled from the serverpolarion.yamlnames, withPOLARION_TOKENset. - It writes
library.arche. The owner, license and export classification come from the flags, and nothing is imported without them. The name is the folder's name unless you pass--name, and the version is0.1.0unless you pass--version. The kind isarchitecturefor Capella andspecfor Polarion (--kindsets another).--label,--descriptionand--keywordsare optional. - It writes a README that says where the model came from and how to take it.
- It checks the package as
archec store publish --dry-rundoes, against an empty index: the package must compile as a project using it compiles it.
Nothing is published. Read the folder, then run archec store publish <folder>.
The Polarion documents that polarion.yaml maps to deliverables are declared in
the package, because no project around it declares them.
UI kits#
A package of kind ui-kit holds a theme for a ui { }: the colors its
screens are drawn in. It can also ship elements its
screens use. The theme is a constant record in the kit's theme.arche:
baseis the theme it starts from,darkorlight;- the other keys are the colors it changes.
// library.arche: library automotive-dark "Automotive dark" { kind ui-kit; owner acme; version "1.0.0"; … }
// theme.arche
/// Dark and high contrast, for a car's cluster.
const AUTOMOTIVE_DARK = { base: "dark", background: "#0b0f14", surface: "#1a2029", primary: "#4fc3f7", onPrimary: "#00131f", warning: "#ffc400" }
A project takes a kit like any package: archec add main.arche acme/automotive-dark writes its uses. Then a ui names it:
ui {
theme "acme/automotive-dark" // the kit's theme, by the package's name
colors { primary "#00e5ff" } // and changed further, as any theme
…
}
With the kit's theme.arche included, theme AUTOMOTIVE_DARK names the same
constant. A project can declare a theme of its own the same way.
An element at the top of any of the kit's .arche files is for the projects
that use the kit. They use it in their screens like their own
(Tyre("Front", bus.TPMS.front)), with no include:
// elements.arche, in the kit
/// A tyre and its pressure.
element Tyre(title: string, p: float32) {
column {
label { text title; size small }
gauge { value p; range 0..4; unit bar }
}
}
- archec checks the theme's contrast, as for any theme (
ui-a11y). - The UI model says where its theme came from (
theme.from). - The previews and generators draw it (
--target ui-qml). - The card of a kit shows each theme with its colors. The card of any package lists the screens of the uis in it.
Limits of UI kits#
- A kit's card shows its themes. It does not list its elements yet.
Editions and archec releases#
A package states the archec versions it works with (archec ">=0.10") and its
edition. Every later archec reads old editions. archec fmt --edition moves a
package to a newer one.
Before a release, archec store test <index> --breaks builds every package with
the new archec. It fails on any package that passed with an earlier one. The
badges show the archec versions each package works with.
Running a store#
A store is an index folder. On GitHub, it is a repository:
archec store init arche-store # store.json, README, .github/workflows/store.yml
archec store seed arche-store --license Apache-2.0
cd arche-store && git init && git add . && git commit -m "Arche Store"
archec store init prints the files it makes, and the next step:
✓ arche-store/store.json
✓ arche-store/README.md
✓ arche-store/.github/workflows/store.yml
✓ arche-store/.gitignore
✓ arche-store/publishers/.gitkeep
✓ arche-store/packages/.gitkeep
✓ arche-store/archives/.gitkeep
✓ arche-store/collections/.gitkeep
next: `archec store seed arche-store`, then `git init` it and push; `archec store use arche-store` to use it here
Publishing is then a pull request that adds a package
(archec store publish <folder> --store <your clone>). The workflow verifies the
signatures and builds the package with archec. On the main branch, it writes the
badges and publishes the pages (archec store site) to GitHub Pages.
The hosted store needs no pull request:
archec store serve arche-store --port 8080
archec store token arche-store acme --org kria-team
archec store token arche-store alice --reviewer
The hosted store adds:
- accounts: tokens, or GitHub sign-in when
GITHUB_CLIENT_IDandGITHUB_CLIENT_SECRETare set; - private packages for an organisation (
archec store publish --private); - review of held packages;
- stars, discussions on each package page, and requests for missing boards or drivers.
- download counts, per package and version (
<index>/downloads.json, in/api/packages,/api/downloadsandpackages.json), and a list sorted by stars, downloads or last update.
Signing in with GitHub#
People sign in at /auth/github. The store sends them to GitHub, which asks
them to let the store read their login and their organisations (scope
read:org). GitHub sends them back to /auth/github/callback. The page there
shows a store token once, and the archec store login … line to run. The
account is the GitHub login, in lowercase. Its organisations are the GitHub
organisations it belongs to, so it can publish as each of them.
To set it up on store.arche-lang.xyz, the store's owner does this once:
On GitHub, open Settings › Developer settings › OAuth Apps › New OAuth App. For an app owned by an organisation, open the organisation's Settings › Developer settings › OAuth Apps instead.
Fill in the form:
- Application name:
Arche Store - Homepage URL:
https://store.arche-lang.xyz - Authorization callback URL:
https://store.arche-lang.xyz/auth/github/callback - Leave Enable Device Flow unticked.
Then click Register application.
- Application name:
Copy the Client ID. Click Generate a new client secret and copy the secret: GitHub shows it only once.
On the server, put the two values in
/etc/arche-store.env. This is theEnvironmentFileof thearche-store.servicesystemd unit (ops/arche-store.servicein the server repository).ops/provision.shcreates it empty, owned by root, mode 600. Add these two lines:GITHUB_CLIENT_ID=Iv1.0123456789abcdef GITHUB_CLIENT_SECRET=0123456789abcdef0123456789abcdef01234567archec calls no one it is not allowed to, so the store also needs
ARCHE_ALLOW=githubin its environment; without it, sign-in answers 503. arche-lang.xyz's unit sets it; another server adds it to this file (What each command sends, and where).Then restart the store:
sudo systemctl restart arche-storeCheck it. Open https://store.arche-lang.xyz/auth/github, accept on GitHub's page, and run the
archec store login https://store.arche-lang.xyz --token …line the page shows.archec store loginprints the login and the organisations.
What to know:
- Without the two variables,
/auth/githubanswers 501. Tokens made witharchec store tokenkeep working. - If an organisation restricts OAuth App access, it is missing from the account until an owner of that organisation approves the app (the organisation's Settings › Third-party access). People can request this approval on GitHub's authorization page.
- Signing in again gives a new token and revokes the account's previous one. The
organisations are read again from GitHub each time. A reviewer or admin made
with
archec store token … --reviewer(or--admin) stays one when they sign in with GitHub. - The state GitHub sends back must match the one the store gave, in the same browser (a cookie), within ten minutes, and it can be used once. Otherwise the store refuses the sign-in and the person starts again.
- For GitHub Enterprise Server, set
ARCHE_GITHUB_URL(for examplehttps://github.example.com) andARCHE_GITHUB_API(https://github.example.com/api/v3). Without them the store uses github.com and api.github.com. - Behind Caddy, the login line uses the scheme and host Caddy forwards
(
X-Forwarded-Proto,X-Forwarded-Host), so it readshttps://store.arche-lang.xyz.
archec store seed publishes what archec ships, under arche, a verified
publisher:
- the board store, and each board on its own;
- the standard library;
- TheAlgorithms/Python's functions translated to the action language
(
lib/algorithms-*, one package per folder, MIT as upstream: see algorithms); - the examples, as architectures (among them ts-handlers, whose behaviour is in TypeScript);
- the templates
archec newstarts from, askind template; - the collections
starterandplants.plantsholds a two-link arm, a cart-pole, a rover and a quadrotor. Each is a MuJoCo plant with its controller, and a test plan run against it (see Plants).
A project started with archec new --from (or --template) says so in its project
block: derived-from "arche/rover-esp32@0.1.0". When it is published, its library
carries that line on, unless its own library.arche has one. The package page
draws the family tree.
A template's page starts with Use this template: the archec new my-project --template owner/name line, with a copy button. The list page has a
Templates button that shows only templates (or open index.html#templates).
Each package page also has Open in playground. The link carries the
package's .arche files in its hash, so it works on a static site. Its project
file becomes main.arche; a package with no project gets a main.arche that
includes its root files. The playground has the standard library and the board
store, so include "std/…" and uses arche-hw-store work there. The button is
left out when the files would not compile there:
- the package needs handler files (
.py,.ts): the playground loads only.archefiles. Bodies in```archeare fine; - it uses other store packages;
- its
.archefiles are in folders; - the link would be longer than 60 kB.
The link opens arche-lang.xyz's playground, /fr/playground/ on the French
pages. A private store sets its own with "playground": "https://…/playground/"
in store.json, or with ARCHE_PLAYGROUND_URL. off removes the button.
archec store import-zephyr <zephyr>/boards -o zephyr-boards writes a board
collection from Zephyr's board files (Apache-2.0). Each board gets:
- its processor (
halandchipfor STM32, nRF, RP2040 and ESP32); - its RAM;
- its UART, CAN, SPI and I2C ports, with the pins its DTS sets.
Add an owner and publish it as a package.
Every command is in commands.md.