How-to guides › Use the Arche Store

How-to guides

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
}
Diagram: Blinker
What archec draws from this code: Blinker
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 approve has 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:

  1. --store <where>;
  2. ARCHE_STORE;
  3. 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 trust says which:
    • trust verified takes only verified publishers (board vendors, known projects);
    • trust reviewed also 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 sigstore in its trust (trust reviewed, sigstore) takes only packages whose bundle cosign verified.

If a check fails, nothing is written. Otherwise archec:

  1. unpacks the package into .arche/store/<name>@<version>/;
  2. writes uses <name> "^1.2" in the project block;
  3. records the store id, version, fingerprint and signing key in arche.lock;
  4. 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 .ts file or a ```ts block is TypeScript;
  • a .py file or a ```python block is Python;
  • bodies all in ```arche are 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: , and says whether the store verified it.

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, license or export-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 diagram draws it;
  • The board: the picture archec board picture draws, for a kind board package (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:

  1. It runs the importer into the new folder. For Capella, this is archec capella (a .capella, its .aird, its folder or a zip; --prefix, --layers and --no-diagrams are passed on). For Polarion, the work items become requirements.arche. They come from a JSON export (with --config polarion.yaml for its field map), or are pulled from the server polarion.yaml names, with POLARION_TOKEN set.
  2. 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 is 0.1.0 unless you pass --version. The kind is architecture for Capella and spec for Polarion (--kind sets another). --label, --description and --keywords are optional.
  3. It writes a README that says where the model came from and how to take it.
  4. It checks the package as archec store publish --dry-run does, 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:

  • base is the theme it starts from, dark or light;
  • 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_ID and GITHUB_CLIENT_SECRET are 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/downloads and packages.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:

  1. 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.

  2. 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.

  3. Copy the Client ID. Click Generate a new client secret and copy the secret: GitHub shows it only once.

  4. On the server, put the two values in /etc/arche-store.env. This is the EnvironmentFile of the arche-store.service systemd unit (ops/arche-store.service in the server repository). ops/provision.sh creates it empty, owned by root, mode 600. Add these two lines:

    GITHUB_CLIENT_ID=Iv1.0123456789abcdef
    GITHUB_CLIENT_SECRET=0123456789abcdef0123456789abcdef01234567

    archec calls no one it is not allowed to, so the store also needs ARCHE_ALLOW=github in 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-store
  5. Check 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 login prints the login and the organisations.

What to know:

  • Without the two variables, /auth/github answers 501. Tokens made with archec store token keep 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 example https://github.example.com) and ARCHE_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 reads https://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 new starts from, as kind template;
  • the collections starter and plants. plants holds 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 .arche files. Bodies in ```arche are fine;
  • it uses other store packages;
  • its .arche files 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 (hal and chip for 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.