{
  "markdown": "# Rocci\n\nA `.rocci` template language, `.rocdown` content format, and desktop runtime.\nAuthor HTML components in `.rocci` or Markdown-first pages in `.rocdown`,\ncompile them to ordinary [Roc](https://www.roc-lang.org/), and serve them over\nHTTP with Datastar. `rocci run` opens the app in a\n[tao](https://github.com/tauri-apps/tao) / [wry](https://github.com/tauri-apps/wry)\npreview window.\n\nRocci is an independent open-source project. It is built on Roc and is not an\nofficial Roc language project.\n\nThe workspace is organized into focused packages with strictly enforced one-way boundaries:\n- **Base Rocci:** `rocci-template` (`.rocci` parse/lower), `rocci-core` (configuration and runtime contracts), `rocci-desktop` (windowing and webview runtime), `rocci-cli` (`rocci` binary), `rocci-ui` (domain-neutral view records and presentation components), `rocci-platform` (in-tree Roc `pf` for generated and custom HTTP apps).\n- **Rocdown:** `rocci-rocdown` (format parser, static catalog, article rendering, site generator), `rocci-rocdown-cli` (`rocdown` binary), `rocci-theme` (document CSS theme resolver).\n- **Open Knowledge Format:** inert `knowledge/` bundle in this repo; parse, check, inspect, search, build, and preview with [okmate](https://github.com/koliyo/okmate).\n- **Tooling:** `rocci-lsp` (generic language-server core and Rocci analyzer), `rocci-rocdown-lsp` (shipped `rocci-language-server` for `.rocci` and `.rocdown`), `rocci-highlight` (pinned Tree-sitter highlighter library).\n\n## Run an example\n\nInstall the platform prerequisites required by Wry, plus `roc` and `cargo` on\n`PATH`. Then from the repository root:\n\n```sh\ncargo run -q -p rocci-cli -- run examples/rocci/standalone/counter\ncargo run -q -p rocci-cli -- run examples/rocci/standalone/styling\ncargo run -q -p rocci-cli -- run examples/rocci/custom/snake\ncargo run -q -p rocci-cli -- run examples/rocci/custom/datastar\ncargo run -q -p rocci-rocdown-cli -- run examples/rocdown/pages/Guide.rocdown\ncargo run -q -p rocci-rocdown-cli -- run examples/rocdown/errors/ErrorDemo.rocdown\n```\n\n[`examples/rocci/standalone/counter`](examples/rocci/standalone/counter) is the starting app: SQLite and a\nDatastar fragment. [`examples/rocci/standalone/styling`](examples/rocci/standalone/styling) is the same template\nlanguage with file-level and component `@css`.\n[`examples/rocdown/pages`](examples/rocdown/pages) is a Markdown page with explicit `@roc`,\n`@component`, and `@render` islands; see [`crates/rocci-rocdown`](crates/rocci-rocdown)\nfor the format. [`examples/rocdown/errors`](examples/rocdown/errors) is the 404 and parse-error\npreview: a working `/error-demo/` page plus a broken file that still opens in the window.\n\n`rocci run path/to/app` is a standalone app directory: resolve a unique\nentry, generate an HTTP dispatcher from `@context` / `@init` /\n`@method:role` routes, and start it. Generated apps pin the in-tree\nRocci platform path when `crates/rocci-platform/platform/main.roc` exists\n(a git checkout). A PATH `rocci` from a GitHub CLI archive falls back to\n\n`https://github.com/koliyo/rocci/releases/download/<tag>/rocci-platform.tar.zst`\n\n(`dev` or `v*`, same tag as that binary). That archive currently links\nApple Silicon macOS and x64 Linux only. It is not the default pin for\ndeveloper checkouts. `rocci run path/to/App.rocci` names the entry file and still loads\nsibling modules. At most one process `@init` is allowed. `rocci run` on\na directory that contains `main.roc` compiles sibling `.rocci` modules\nand starts the authored Roc app. Datastar JS is staged under `assets/`\n(downloaded into `~/.rocci/cache` on first use). The preview window\nlistens on a free local TCP port and prints the URL so you (or an agent)\ncan inspect the same HTTP server. Pass `--no-window` to serve on port\n8000 without a preview window. Override the port with `--port` or\n`ROC_BASIC_WEBSERVER_PORT`. `--http-module` and `--host wasm` are not this\nplatform.\n\nOn Linux, Wry requires WebKitGTK development packages. macOS and Windows use\nthe operating system webview. Datastar evaluates declarative expressions using\nJavaScript's `Function` constructor, so the script policy permits\n`unsafe-eval`; script sources remain restricted to self-hosted assets.\n\n## Package a desktop app\n\n`rocci bundle` compiles the Roc app, builds the `rocci` host, and assembles an\nad-hoc signed macOS `.app`. The bundled app does not need `roc` on `PATH` at\nruntime. From the repository root, with `roc` and `cargo` on `PATH`:\n\n```sh\nuv run rocci-ops package macos\nopen \"target/release/bundle/macos/Datastar.app\"\n```\n\nOr:\n\n```sh\ncargo run -p rocci-cli -- bundle --config rocci.toml\n```\n\nThe root [`rocci.toml`](rocci.toml) points at [`examples/rocci/custom/datastar`](examples/rocci/custom/datastar),\nthe custom-`main.roc` gallery. That example also has its own\n`examples/rocci/custom/datastar/rocci.toml` (`bundle.app = \".\"`) so you can package from the\napp directory the same way.\n\nOpening the `.app` starts the host with no arguments. It finds\n`Contents/Resources/rocci.toml`, launches the compiled Roc server, and opens\nthe preview window.\n\nPackaging is currently macOS-only.\n\n## CLI\n\n### Rocci\n\n```sh\ncargo run -p rocci-cli -- validate\ncargo run -p rocci-cli -- bundle --config rocci.toml\ncargo run -p rocci-cli -- build path/to/file.rocci\ncargo run -p rocci-cli -- run examples/rocci/standalone/counter/Counter.rocci\ncargo run -p rocci-cli -- view examples/rocci/standalone/counter/Counter.rocci --component CounterCard --arg count=3\ncargo run -p rocci-cli -- browse examples\ncargo run -p rocci-cli -- inspect --ast examples/rocci/standalone/counter/Counter.rocci\ncargo run -p rocci-cli -- datastar pin 1.0.2 --app examples/rocci/custom/datastar\ncargo run -p rocci-cli -- datastar update --app examples/rocci/custom/datastar\n```\n\nTo install the release `rocci` and `rocdown` binaries into\n`~/.local/bin`, run `uv run rocci-ops install cli`.\n\n### Rocdown\n\n```sh\ncargo run -p rocci-docs -- --catalog examples/rocci/apps.toml --output dist/example-docs\ncargo run -p rocci-rocdown-cli -- run examples/rocdown/pages/Guide.rocdown\ncargo run -p rocci-rocdown-cli -- build examples/rocdown/site --output dist\ncargo run -p rocci-rocdown-cli -- check site\ncargo run -p rocci-rocdown-cli -- check docs\ncargo run -p rocci-rocdown-cli -- test docs\ncargo run -p rocci-rocdown-cli -- inspect ast test/AllSyntax.rocdown\n```\n\nRocdown discovers `.rocdown` files, resolves routes in Rust, renders article HTML\nfrom the Markdown AST, and wraps each page in [`RocdownTheme.rocci`](crates/rocci-rocdown/templates/RocdownTheme.rocci).\nContent edits do not recompile Markdown as Roc.\n\n### Knowledge (OKF)\n\nThe `knowledge/` tree stays in this repository. Check, inspect, search, build,\nand preview it with [okmate](https://github.com/koliyo/okmate):\n\n```sh\nokmate check knowledge --profile base\nokmate inspect concept architecture/system-overview knowledge\nokmate inspect graph knowledge\nokmate search \"rendering\" knowledge\nokmate benchmark knowledge/retrieval-benchmark.toml knowledge\nokmate view knowledge\nokmate view knowledge/plans/shared/cli-entry-points.md\nokmate build knowledge --output dist/knowledge\n```\n\nFrom a sibling checkout, `cargo run -q --no-default-features --manifest-path\n../okmate/Cargo.toml -p okmate --` is the same CLI. Knowledge CI downloads the\npinned GitHub Release Linux binary (`.github/okmate-version`) and runs those\nbundle commands; engine tests run in the okmate repo.\n\nRetrieval questions are measured by `okmate benchmark`; the command reports hit\nrate and mean reciprocal rank and fails when the checked-in threshold is missed.\n\nThe public `rocci.dev` tree is [`site`](site), configured by\n[`site/rocdown.toml`](site/rocdown.toml) and written to `dist/rocci.dev`.\n[`docs`](docs) remains the mounted documentation catalog and a standalone\n`check docs` / `test docs` target. With `roc` and `cargo` on `PATH`, package\nthe complete local site with:\n\n```sh\nuv run rocci-ops site\n```\n\nThat repository-level command stages generated example documentation, checks\nlinks and catalog policy, runs documented examples, and builds\n`dist/rocci.dev`. The focused `rocci-rocdown-cli` commands remain available.\nTo package the hybrid site (CDN archive plus musl `islands` binary), use:\n\n```sh\nuv run rocci-ops package site --target x64musl\n```\n\nThis stages example docs, builds live example servers, and packages the hybrid\nsite. Site packaging currently uses Roc's `dev` backend for every live server\nbecause the pinned nightly can recurse in its optimized backend. These\nartifacts are functional but are not production-performance builds: they may\nbe larger and slower. Use `rocci build --release --opt speed` when an optimized\nbinary is required. `rocci-docs` and `rocci-rocdown` remain separate crates;\n`rocci-rocdown` does not import `rocci-docs`.\n\nThat writes `dist/rocci.dev`, `dist/site.tgz`, `dist/islands`, and\n`publish.json`. GitHub Actions workflow `site.yml` packages on linux/amd64\nand, on `staging` or `production` only, scps those artifacts to the origin\nusing the matching GitHub Environment. Land work on `main`; promote to\n`staging` to publish behind Access, then to `production` for the public\nhostname. Pull requests never deploy.\n\nTo promote the current `main` revision to staging locally, run\n`uv run rocci-ops promote staging`. This rebases `staging` onto `main`,\npushes `staging` to `origin`, and restores the branch that was active when it\nstarted. After a signed-out staging smoke,\n`uv run rocci-ops promote production` pushes `origin/staging` to\n`origin/production` (creates the branch on first use). That push runs hosted CI\nand Knowledge, then the site package/deploy job. Do not promote production\nuntil staging has been smoked.\n\nTo publish a GitHub release from `origin/main`, run\n`uv run --no-dev rocci-ops release patch` (or `minor`, `major`, or `vX.Y.Z`,\noptionally `--from BRANCH`). That is the only operator path that creates an\nimmutable `v*` tag. It writes the workspace version to `Cargo.toml` and\n`Cargo.lock`, pushes that commit to the target branch, waits for hosted lint\nand Test Workspace checks, then pushes the tag so `release.yml` can package\narchives. `--dry-run` prints the resolved tag and whether those files already\nmatch. Pass `--force` only to move an existing `v*`.\n`uv run --no-dev rocci-ops release dev` force-moves the rolling `dev`\nprerelease tag (no version rewrite). The same cut can run from\n**Actions → Cut release** (`workflow_dispatch` on `cut-release.yml`; not\nattached to the `release`, `staging`, or `production` environments).\n`promote tag` is gone; `promote` is only `staging` and `production`.\nA later `git pull` then reports `! [rejected] dev -> dev (would clobber\nexisting tag)` unless this repo force-updates that tag on fetch:\n\n```sh\ngit config --local --add remote.origin.fetch '+refs/tags/dev:refs/tags/dev'\n```\n\nDo not force-fetch all tags; `v*` releases stay immutable. To replace local\n`dev` once without changing config, run `git fetch origin tag dev --force`.\n\nTo test a pull request in this worktree when an agent already has the PR\nbranch checked out, run `uv run rocci-ops pr-checkout 39`. With no argument,\nthat lists open PRs via `gh`. Quote `#39` in the shell, or pass a GitHub PR\nURL or branch. That fetches the tip and switches this checkout to a local\n`pr/<branch>` branch.\n\n`rocci.toml` describes windows, HTTP, security, assets, development, and bundle\nprofiles. `[http] redirect_trailing_slash` (default `true`) sends GET `/page` to\n`/page/` or the reverse with **308**, matching the registered `@page` route;\nset it `false` to 404 with a hint instead. Custom `main.roc` apps own their\nrouting. `[assets] datastar` pins the Datastar JS version the CLI copies into\nthe app; `rocci datastar update` bumps that pin. The CLI does not auto-upgrade\non `run`.\n\n## Tests\n\n```sh\ncargo test --workspace\nuv run rocci-ops ci\n```\n\n`cargo test --workspace` is the offline crate suite. Roc on `PATH` does not enable generated-app builds; set `ROCCI_REQUIRE_ROC=1` for that lane. `uv run rocci-ops ci` runs the GitHub Actions validation jobs on this OS (lint, tests, fixtures-and-docs, editors, knowledge, and Linux `roc`). It does not run the ubuntu/macos matrix or release cross-platform builds. Pass job names to run a subset, for example `uv run rocci-ops ci lint test`.\n\nGitHub Actions CI, Knowledge, Site, and Release run on GitHub-hosted runners (`ubuntu-latest` / `macos-latest`). CI and Knowledge run automatically on push to `main`, `staging`, and `production`. They do not run on every pull request. A reviewer comments `/ci` or `/CI` (conversation, review body, or inline review comment) to queue hosted CI for that PR head. Owners, members, and collaborators may do this, including on forks. Dependabot PRs need `/ci` the same way. `/ci-local` and `/cl-local` are accepted but queue the same hosted jobs. Site package and deploy use `ubuntu-latest`; deploy secrets stay on the `staging` and `production` GitHub Environments; CI and Knowledge jobs cannot read them.\n\n## Contributing\n\nThis preview does not accept pull requests; that may change later.\n[CONTRIBUTING.md](CONTRIBUTING.md) is the current contract, including crate\nownership and `/ci`. Conduct, security, support, and\ngovernance live beside it at the repository root.\n\n## License\n\nCopyright 2026 Nils Hjelte.\n\nRocci is licensed under the [Apache License, Version 2.0](LICENSE).\n`crates/rocci-platform` also contains a UPL-1.0 snapshot of\n[basic-webserver](https://github.com/roc-lang/basic-webserver); see\n[`LICENSE-UPL`](crates/rocci-platform/LICENSE-UPL) in that crate.\nThird-party components retain their own licenses; see\n[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).\n",
  "bytes": 13691,
  "sha": "818c8aca0c53ce2c7ffae1e6609add6fab0f6b17c47106795fe5988f9973dc1c",
  "repo_slug": "koliyo/rocci",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_koliyo_rocci_knowledge_index_md_c20c24f7/readme"
}