--- name: silen-infra description: "Work in silen's infrastructure: Twig (self-hosted Git and pull requests), Ino (release and Once deployment), and Info (Infomaniak DNS for silenlocatelli.ch and hodis.ch)." --- # silen infra This is the working map of the self-hosted stack. Read the section for the task you are doing, then follow the repository's own `AGENTS.md` and `mise.toml` when they are stricter. The `any` CLI installs this file at `.opencode/skills/silen-infra/SKILL.md`. ## The map | Thing | Location | What it is | | --- | --- | --- | | Twig server | | Self-hosted Git server with a web UI and pull requests | | Twig source | `https://twig.silenlocatelli.ch/twig/twig` | Rust/Actix-web server; repo for Twig itself | | Ino source | `https://twig.silenlocatelli.ch/twig/ino` | Zig CLI for versions, releases, and Once deployments | | Info | `https://twig.silenlocatelli.ch/silen/info` | OpenTofu/Terraform config for Infomaniak DNS | | Any | `https://twig.silenlocatelli.ch/silen/any` | Small CLI that installs this skill into a repo | | Deployment proxy | `proxy.silenlocatelli.ch` | Once/Kamal proxy in front of deployed apps | | Ino deployment server | `https://ino.silenlocatelli.ch` | Once-compatible server Ino releases deploy to | Repository paths on Twig are `{namespace}/{repo}`, for example `silen/info` or `twig/ino`. HTTPS clones accept an optional `.git` suffix: `https://twig.silenlocatelli.ch/silen/info.git`. ## Preferred project setup When starting a project or reshaping an existing one, default to this shape: - **Server-rendered UI first.** If the project has a server, render HTML on the server and use **HTMX 4** for interaction. Add small vanilla JavaScript only for what HTMX cannot do cleanly. - **Vendor every asset.** CSS, HTMX, fonts, and any JavaScript library are checked into the repository and served by the app itself. No CDNs, no remote imports, and no runtime downloads. - **A self-served pure JavaScript frontend is acceptable** when the app is genuinely client-side. Serve the JS and CSS from the repository, and vendor only libraries that are sensible for the task. - **No unused vendor code.** Vendor only the files and features actually used; remove dead JavaScript and unused library files. Do not ship a whole library for one helper. - **Keep vendored code intact.** Keep each library's license file next to it and do not rewrite vendored sources; adapt your own code around them. - **Degrade gracefully.** Prefer progressive enhancement: core reading and navigation should still work if JavaScript fails. ## Twig: branches, pull requests, CI **Prefer committing directly to `main`.** Push small, reviewed changes straight to `main` instead of opening a pull request. Use a pull request only when the user asks for one, when the change is large or risky, or when review is genuinely useful. Twig does not require a PR (there are no required status checks), so a PR is a collaboration choice, not a gate. The workflow below is for the cases where a PR is wanted. ### Authenticate once Create a personal access token in Twig under **Settings → Access tokens**. Grant `view_namespace` for reading and `push_changes` for pushing, opening pull requests, reviewing, and merging. For the Forgejo-compatible CLI: ```sh fj --host https://twig.silenlocatelli.ch auth add-token ``` Twig also accepts the token directly: ```sh export TWIG_TOKEN=... # never commit it curl -fsS -H "Authorization: token $TWIG_TOKEN" \ https://twig.silenlocatelli.ch/api/v1/me ``` Git writes use HTTP Basic Auth. Use your Twig username and password, or the token as the password. A credential helper keeps it out of the remote URL. ### Commit and push For a normal small change, work on `main`: ```sh git switch main git pull # edit, test, then: git add -A git commit -m "feat: add a subdomain for books" git push ``` When a pull request is actually needed, branch from `main`: ```sh git switch -c t3/ ``` Use `t3/` for work started from a T3 Code thread; `feat/`, `fix/`, or `docs/` are fine too. Keep one topic per branch. Twig pull requests can only merge a branch from the **same repository** — forks are not supported. ### Commit style Use conventional commits; Ino reads them to choose a version bump. ```text feat: add a subdomain for books fix: reject stale branch heads perf: cache rendered markdown docs: explain Once labels refactor: split the release parser test: cover duplicate pull requests chore: bump the Zig toolchain feat!: drop the old config key ``` `!` or a `BREAKING CHANGE:` footer marks a breaking change. `feat` and `perf` bump the minor version; everything else defaults to a patch. ### If you open a pull request Only do this when a PR is preferred or requested. Push the branch first, then create the request against `main`: ```sh git push -u origin t3/ fj --host https://twig.silenlocatelli.ch pr create \ --base main \ --head t3/ \ --title "feat: add books subdomain" \ --body "Adds the CNAME and the deployment label. Verified with: mise run validate" ``` `fj pr create -A` fills the title and body from the commits. `--web` opens the web form instead. Add `-r owner/repo` when the remote does not identify the repository. Without `fj`, use the Forgejo-compatible API: ```sh curl -fsS -X POST \ "https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls" \ -H "Authorization: token $TWIG_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n \ --arg base main \ --arg head t3/ \ --arg title 'feat: add books subdomain' \ --arg body 'Adds the CNAME and the deployment label.' \ '{base:$base, head:$head, title:$title, body:$body}')" ``` The response contains `number` and `html_url`. Open requests also appear in the web UI under the repository's **Pull requests** tab. Every request has a read-only ref `refs/pull/{number}/head`; do not push to `refs/pull/*`. ### Review and merge ```sh fj --host https://twig.silenlocatelli.ch pr status --wait fj --host https://twig.silenlocatelli.ch pr view fj --host https://twig.silenlocatelli.ch pr checkout ``` Approve or request changes through the review API (the `fj` build may only list and request reviewers): ```sh curl -fsS -X POST \ "https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls//reviews" \ -H "Authorization: token $TWIG_TOKEN" \ -H "Content-Type: application/json" \ -d '{"event":"APPROVED","body":"Checks pass."}' ``` `event` is `APPROVED`, `REQUEST_CHANGES`, or `COMMENT`. Merge with one of Twig's three styles: ```sh fj --host https://twig.silenlocatelli.ch pr merge \ --method squash --delete ``` Twig also accepts `--method merge` and `--method rebase`. Updating a branch from its base supports merge only; rebase updates are not offered. ### CI A repository opts into Twig CI by committing `.twig/mise.toml`: ```toml [tools] rust = { version = "nightly-2026-10-31" } "cargo-binstall" = "latest" "cargo:cargo-nextest" = "latest" [tasks.ci] dir = ".." run = ['cargo fmt --check', 'cargo clippy --all-targets', 'cargo nextest run'] ``` Only `.twig/mise.toml` is used; a root `mise.toml` is not merged into a run. Tasks execute from `.twig/` unless `dir = ".."`. A push queues one run per moved branch; pull requests show the head commit's combined `ci` status. Statuses are reported but **do not gate a merge**, so a green check is a convention, not a server guarantee. CI must be enabled by the server operator (`TWIG_CI=1`) and runs with the server user's filesystem access — treat it as trusted code. Read runs and logs with `fj actions tasks` or `GET /api/v1/repos/{owner}/{repo}/actions/tasks`. Dispatch manually with `fj actions dispatch ci `. ### Twig repository config `.twig.toml` at the repository root controls visibility and views: ```toml private = true deleteable = false ignore_for_view = [".opencode/", "AGENTS.md", "docs/plans/"] [scripts.install] name = "Install" scripts = [ { name = "Install CLI", path = "scripts/install.sh", shell = "bash" }, ] ``` `private = true` requires authentication even for reads. `deleteable = true` is required before the UI/API can delete the repository. Keep secrets out of this file and out of the repository. ### Twig limits worth remembering - Pull requests are same-repository only; no forks. - No labels, milestones, issues, projects, or thread resolution. - No required status checks. - No rebase updates for pull requests. - Creating a private repository through the API is not supported; set `private = true` in `.twig.toml`. - Content writes are limited to 1 MiB; Git pushes and binary uploads to 512 MiB. - API reads always require a token, even for public repositories. ## Ino: release and deploy Ino is the Zig CLI that versions a project, pushes a Docker image, and asks the Ino server to deploy it through Once. ### Install ```sh git clone https://twig.silenlocatelli.ch/twig/ino cd ino mise run install # installs to ~/.local/bin, or $INO_PREFIX/bin ``` The install task removes a stale cargo-installed `ino` instead of shadowing it. ### Release ```sh ino # same as `ino auto`: pick the bump from conventional commits ino patch ino minor ino major ``` The release flow: 1. Reads the current version from `build.zig.zon` `.version` (preferred) or `Cargo.toml` `[package].version`; if both exist, Zig wins. 2. Picks a bump: breaking → major, `feat`/`perf` → minor, else patch. 3. Updates `Cargo.toml` and the workspace `Cargo.lock` for Rust (the lockfile is intentionally left out of the release commit), or `build.zig.zon` for Zig. 4. If a root `Dockerfile` exists, builds and pushes the versioned image and `latest` with Docker Buildx. The Dockerfile must declare `LABEL remote="owner/image"` and the registry login must already exist. 5. Commits and pushes the release. The branch needs a usable Git remote. 6. If both deployment labels are present, calls the Ino server and waits for the app to report the requested image as running. Use `ino new` to print all derived versions, and `ino exec ` to run a command with version environment variables injected (`INO_*` and `VERSION_*`). ### Container contract for a deployable app The image must: - Serve HTTP on `0.0.0.0:80`. - Return a successful unauthenticated `GET /up`. - Persist durable data under `/storage` (configure the app's real database and upload paths to use it). - Run the server as the foreground process (PID 1 behaviour), not a detached background process. Add both labels to the root `Dockerfile`; they must appear together: ```dockerfile LABEL remote="silenloc/myapp" \ ino.deploy.server="https://ino.silenlocatelli.ch" \ ino.deploy.host="myapp.silenlocatelli.ch" ``` - `remote` is the actual registry repository. - `ino.deploy.server` is the Ino server origin. - `ino.deploy.host` is the public hostname. It must have a DNS record in the Info repo (normally a CNAME to `proxy.silenlocatelli.ch`). - Never put `INO_API_KEY`, registry passwords, or app secrets in labels. The local release environment needs Docker Buildx, registry authentication, Git push access, and a non-empty `INO_API_KEY`. The key is read from the local environment only; it is not baked into the image. ### First deployment and day-two operations For a brand-new app, release and create it with: ```sh ino once remote create ``` For an app that already exists on the server, the normal `ino` release updates it. Other Once operations: ```sh ino once list ino once deploy ghcr.io/owner/app:latest --host app.silenlocatelli.ch ino once start app.silenlocatelli.ch ino once stop app.silenlocatelli.ch ino once exec app.silenlocatelli.ch sh ino once update app.silenlocatelli.ch --image ghcr.io/owner/app:v2 ino once backup app.silenlocatelli.ch ./app-backup.tar.gz ino once restore ./app-backup.tar.gz ino once remove app.silenlocatelli.ch # keeps the data volume ino once remove app.silenlocatelli.ch --remove-data ino once keys reset app.silenlocatelli.ch --secret-key-base ``` Use `--registry-password-stdin` rather than putting a registry password in shell history. `ino once` drives the local Docker daemon; it does not need the upstream `once` executable. ### Deployment checks Before calling a deployment done: ```sh curl -fsS https:///up curl -fsS https:/// ``` Confirm the image tag the server reports matches the released version, and that data written before a redeploy survives. A successful image build is not a deployment. ## Info: DNS and subdomains Info is an OpenTofu configuration for the Infomaniak DNS zones `silenlocatelli.ch` and `hodis.ch`. The provider is `Infomaniak/infomaniak` `~> 1.4.1`; the toolchain is `opentofu 1.13.0`. ```sh git clone https://twig.silenlocatelli.ch/silen/info cd info mise install mise run init mise run plan mise run apply # runs plan first mise run fmt mise run validate ``` `infomaniak_token` is a sensitive variable. Provide it through `TF_VAR_infomaniak_token` or a local untracked file, and never commit a token. Do not edit `infomaniak_api_*.json` by hand — it is a downloaded snapshot, not the source of truth. ### Add a subdomain Append a record to `records-silenlocatelli.tf` (or `records-hodis.tf` for `hodis.ch`). New app subdomains normally point at the Once proxy: ```hcl resource "infomaniak_record" "silenlocatelli_myapp_cname" { zone_fqdn = infomaniak_zone.silenlocatelli.fqdn source = "myapp" type = "CNAME" ttl = 3600 target = "proxy.silenlocatelli.ch" } ``` Then: ```sh mise run fmt mise run plan # inspect the add mise run apply dig +short myapp.silenlocatelli.ch ``` Naming and address facts: - `source` is relative to the zone: `myapp`, not `myapp.silenlocatelli.ch`. - `silenlocatelli.ch` app subdomains normally CNAME to `proxy.silenlocatelli.ch`. - `proxy.silenlocatelli.ch` resolves to `83.228.212.88` (A) and `2001:1600:18:102::17e` (AAAA). - The `silenlocatelli.ch` apex is managed by Infomaniak nameservers and carries mail/SPF/DMARC records; do not repoint it casually. - `hodis.ch` currently has apex A/AAAA records pointing directly at the proxy. - `fig.silenlocatelli.ch` has its own A/AAAA records, and `auth` points at Auth0. Treat existing non-proxy records as intentional. - Add an `import` block only when adopting a record that already exists in Infomaniak; a newly created record needs none. ## Code quality before committing Run the repository's own task first. It is the contract: ```sh mise run verify ``` Then check the language-specific baseline below. A change that skips the repo's formatter, linter, or tests is not ready to push. ### Rust The Rust projects (Twig, Tree, Personal Page) pin a toolchain and use the same verify shape: ```sh cargo fmt --check cargo clippy --all-targets cargo nextest run ``` - Keep the pinned `rust-toolchain.toml` channel; bump it deliberately in its own commit. - Treat Clippy warnings as defects. Fix the code; do not add a blanket `#[allow(...)]`. - Use `Result` and `?` for fallible paths. Keep `unwrap`/`expect` out of request handlers and startup paths; tests may use them. - Prefer clear ownership and borrowing over cloning to silence the borrow checker. - Keep `Cargo.lock` committed for binary projects. - Twig-specific: do not eagerly connect to the SQLite file; follow the existing lazy connection pattern. - Run tests that touch HTTP, Git, or database code against the real `mise run verify` task, not only `cargo check`. ### Zig The Zig projects (Ino, Any) use: ```sh zig fmt --check build.zig src zig build test zig build -Doptimize=ReleaseSafe ``` - Use only the Zig standard library unless the project already vendored an approved dependency; do not add packages casually. - Let the test allocator catch leaks. Free or arena-allocate every allocation, and use `errdefer`/`defer` on error paths. - Return errors for bad input; do not use `catch unreachable` or `unreachable` on user-controlled data. - Keep `@embedFile` payloads and build options declared in `build.zig` so tests compile with the same inputs. - Tests live beside the code in `test` blocks, and pure parsing/composition logic is preferred over tests that depend on the process cwd. - Formatting is `zig fmt`; do not hand-align code against it. ### JavaScript The web assets in Twig are deliberately dependency-free browser JavaScript: no bundler, no npm build step, and vendored libraries are left untouched. - Put new browser code in its own file under `assets/` and wrap it in an IIFE with `"use strict"`; do not leak globals. - Match the surrounding style (`var`/`function` in older files, semicolons, the file's indentation). Do not reformat a whole file for a small change. - Guard browser APIs that can throw or be unavailable, especially `localStorage` and `sessionStorage`, with `try`/`catch`. - Use `textContent` for untrusted text and sanitize rendered HTML; Twig vendors DOMPurify for this. Never interpolate untrusted values into `innerHTML`. - Use event delegation for repeated controls and clean up listeners with the element's lifecycle. - Handle rejected promises; do not leave a floating async call without a `catch`. - If a repository does have `package.json`, run its own formatter, linter, typecheck, and tests (`mise run verify` first), and ask before adding a dependency. - Use **Bun**, not Node, for JavaScript tooling: `bun install`, `bun run`, and `bun test`. Do not use `node` or `npm` to run or check project code. - With no tooling, at minimum run `bun build --no-bundle ` for syntax and exercise the page in a browser. ### Universal change hygiene - Keep the diff focused; split unrelated refactors into their own commit or PR. - Update docs, `.twig.toml`, `mise.toml`, and deployment labels when behaviour changes. - Do not commit `.env`, tokens, registry passwords, DNS credentials, or build outputs. - Re-read `git diff` before pushing, and say what was verified in the commit message or PR description. - If a check cannot run, say so explicitly instead of claiming success.