residual/.agent

Watch

Fork 0

Create `repository` APK repo #8

New issue

Open

opened 2026-07-19 02:31:30 +00:00 by agent · 0 comments

agent commented

2026-07-19 02:31:30 +00:00

Member

Plan: Create `repository` repo (residual APK package build scripts)

Status: APPROVED — implementation pending. See the Handoff section below for concrete, ordered implementation steps.

Goal

Stand up a new, separate repository git repo at the workspace root that holds APKBUILD package-build recipes only (no source code). It produces the res-core and res-extra apk repositories, published to Forgejo's Alpine package registry and later consumed by os as additional repos. Stock Alpine stays untouched; os remains the image builder.

Decisions locked (from planning discussion)

Target layout confirmed (see handoff).
Built APKs are hosted in Forgejo's Alpine package registry:
- Publish: curl --user {owner}:{token} --upload-file pkg.apk https://{host}/api/packages/{owner}/alpine/{branch}/{repository}
- Consume: add https://{host}/api/packages/{owner}/alpine/{branch}/{repository} to /etc/apk/repositories, fetch signing key from https://{host}/api/packages/{owner}/alpine/key into /etc/apk/keys/, then apk update.
res-edit (editor/) and res-os (os/cmd/res-os) packaging are out of scope (separate effort).
.aports stays physically for reference; added to root .gitignore (never committed). repository is built fresh using aports patterns, not as a fork.

Design

repository/ is a fresh git repo. aports is reference only.
res-core/ ← core/ source; res-extra/ ← extra/ source. Each package is one subdir containing an APKBUILD stub.
os/residual/ (the placeholder package tree) moves into repository/; os becomes image-build only.
APKBUILD style docs (CODINGSTYLE.md, COMMITSTYLE.md) move from os/ to repository/.
Forgejo CI: lint.yml (advisory shellcheck + apkbuild-lint) and build.yml (build changed packages → publish to Forgejo). Rebuilt from aports' GitLab CI approach, not its GitLab syntax.
The workspace harness already uses dynamic discover_repos() (.agent/tools/common.sh), so repository is auto-discovered — no edits to the REPOS arrays needed. build-all.sh/test-all.sh filter by go.mod, so repository (no go.mod) is correctly skipped. Root .gitignore gains /repository/ and /.aports/.
Docs (AGENTS.md, docs/architecture.md, docs/os/os.md) updated for the new repo and the moved package tree.

Out of scope

Actual APKBUILD content / real package builds — stubs only this pass.
res-edit / res-os packaging.
os ISO --repository wiring (documented as future; not changed now).

Verification

cd repository && git status shows res-core/, res-extra/, .forgejo/, READMEs, and style docs; no go.mod.
bash .agent/tools/status-all.sh lists repository; sync-repos.sh discovers it; .aports and repository are git-ignored at the root.
os still builds an ISO unchanged — no regression from moving os/residual/.
AGENTS.md / docs/architecture.md / docs/os/os.md are consistent; os/residual/ is no longer described as the package tree.

Handoff (ordered, concrete steps for the build agent)

Run from the workspace root /workspace/git.merith.xyz/residual unless noted. Replace forgejo.example.com / residual (owner) / branch v3.24 with the real Forgejo values when known; confirm the Forgejo host + owner before authoring build.yml's publish step.

Phase 0 — Pre-flight

Confirm the repository remote: git.merith.xyz/residual/repository (adjust if the real remote differs).
Confirm Forgejo host, owner, and the alpine branch used for the registry (e.g. v3.24). These feed build.yml and the future os --repository URL.
Confirm a Forgejo personal access token with package-write scope exists as a repo secret FORGEJO_TOKEN (used by build.yml).

Phase 1 — Initialize the repo

mkdir -p /workspace/git.merith.xyz/residual/repository
cd /workspace/git.merith.xyz/residual/repository
git init -q
git remote add origin git.merith.xyz/residual/repository   # adjust if different

Phase 2 — Directory skeleton

mkdir -p res-core res-extra .forgejo/workflows
for p in res res-init res-console res-sh res-login; do mkdir -p "res-core/$p"; done
mkdir -p res-extra/res-calc

Phase 3 — Move APKBUILD style docs out of `os/`

os/CODINGSTYLE.md and os/COMMITSTYLE.md are aports-derived APKBUILD/aports commit conventions — they belong in the package repo. Copy to ./CODINGSTYLE.md / ./COMMITSTYLE.md; in os/ (separate commit): git rm CODINGSTYLE.md COMMITSTYLE.md, edit os/README.md to state os is image-build only.

Phase 4 — `repository/README.md` (see plan for full content)

Documents APKBUILD-only recipes, res-core/res-extra repos, publishing to Forgejo Alpine registry, consuming via /etc/apk/repositories + signing key.

Phase 5 — `repository/.gitignore`

# abuild build artifacts
pkg/
src/
APKINDEX*
*.apk
# abuild keys
*.rsa
*.rsa.pub
# editor droppings
*.swp

Phase 6 — APKBUILD stubs

One APKBUILD per package (placeholders; source=/builddir=/pkgver finalized when actually built). Template for res-core/res-console/APKBUILD:

# Maintainer: residual <maintainer@residual>
pkgname=res-console
pkgver=0.0.0
pkgrel=0
pkgdesc="residual PTY-based console multiplexer"
url="https://git.merith.xyz/residual/core"
arch="all"
license="MIT"
makedepends="go"
subpackages="$pkgname-doc"
source="$pkgname-$pkgver.tar.gz::https://git.merith.xyz/residual/core/archive/refs/tags/$pkgname-v$pkgver.tar.gz"
builddir="$srcdir/core-$pkgname-v$pkgver"
build() { go build -o "$pkgname" ./cmd/"$pkgname"; }
package() { install -Dm755 "$pkgname" "$pkgdir"/usr/bin/"$pkgname"; }

Create analogous files for: res-core/res, res-core/res-init, res-core/res-sh, res-core/res-login, and res-extra/res-calc (pkgname/cmd path adjusted; res-calc source is extra/).

Phase 7 — Forgejo workflows

.forgejo/workflows/lint.yml (advisory): alpine:3.24 container; shellcheck + apkbuild-lint (continue-on-error: true).
.forgejo/workflows/build.yml (build + publish): on push to main with APKBUILD path changes; abuild -r changed packages; curl --user "${FORGEJO_OWNER}:${FORGEJO_TOKEN}" --upload-file to https://${FORGEJO_HOST}/api/packages/${FORGEJO_OWNER}/alpine/${BRANCH}/${repo}. Uses FORGEJO_HOST/FORGEJO_OWNER/FORGEJO_TOKEN/BRANCH env (TODO: real values).

Phase 8 — Root `.gitignore`

Add to the "Each subdirectory is an independent git repository" block:

/repository/
/.aports/

Phase 9 — Harness (no edits required)

.agent/tools/*.sh already use discover_repos(); repository/ is discovered automatically. build-all.sh/test-all.sh filter by go.mod, so repository (no go.mod) is correctly skipped.

Phase 10 — Docs

AGENTS.md: add repository to workspace-layout tree + separate-repos list; note it is a package-build repo producing res-core/res-extra apk repos; keep os as image builder.
docs/architecture.md: add repository to repo-layout table.
docs/os/os.md: update stale "repository structure (planned)"; note os/residual/ moved to repository; ISO will later consume res-core/res-extra from Forgejo (future wiring).

Phase 11 — Commit & verify

cd /workspace/git.merith.xyz/residual/repository
git add -A
git commit -m "feat: scaffold residual package repository (res-core/res-extra)"

Verify: git status clean; tree has res-core/, res-extra/, .forgejo/, READMEs, style docs; no go.mod. From root: bash .agent/tools/status-all.sh lists repository; os still builds an ISO unchanged; root .gitignore ignores /repository/ and /.aports/.

Future (not in this handoff)

os/entrypoint.sh and os/.forgejo/workflows/build-iso.yml add --repository URLs for res-core/res-extra from Forgejo.
Real APKBUILD content + package builds (replace stubs).
res-edit / res-os packaging in separate efforts.

# Plan: Create `repository` repo (residual APK package build scripts) Status: APPROVED — implementation pending. See the **Handoff** section below for concrete, ordered implementation steps. ## Goal Stand up a new, separate `repository` git repo at the workspace root that holds **APKBUILD package-build recipes only** (no source code). It produces the `res-core` and `res-extra` apk repositories, published to Forgejo's Alpine package registry and later consumed by `os` as additional repos. Stock Alpine stays untouched; `os` remains the image builder. ## Decisions locked (from planning discussion) - Target layout confirmed (see handoff). - Built APKs are hosted in **Forgejo's Alpine package registry**: - Publish: `curl --user {owner}:{token} --upload-file pkg.apk https://{host}/api/packages/{owner}/alpine/{branch}/{repository}` - Consume: add `https://{host}/api/packages/{owner}/alpine/{branch}/{repository}` to `/etc/apk/repositories`, fetch signing key from `https://{host}/api/packages/{owner}/alpine/key` into `/etc/apk/keys/`, then `apk update`. - `res-edit` (`editor/`) and `res-os` (`os/cmd/res-os`) packaging are **out of scope** (separate effort). - `.aports` stays physically for reference; added to root `.gitignore` (never committed). `repository` is built fresh using aports *patterns*, not as a fork. ## Design - `repository/` is a fresh git repo. aports is reference only. - `res-core/` ← `core/` source; `res-extra/` ← `extra/` source. Each package is one subdir containing an `APKBUILD` stub. - `os/residual/` (the placeholder package tree) moves into `repository/`; `os` becomes image-build only. - APKBUILD style docs (`CODINGSTYLE.md`, `COMMITSTYLE.md`) move from `os/` to `repository/`. - Forgejo CI: `lint.yml` (advisory shellcheck + apkbuild-lint) and `build.yml` (build changed packages → publish to Forgejo). Rebuilt from aports' GitLab CI *approach*, not its GitLab syntax. - The workspace harness already uses dynamic `discover_repos()` (`.agent/tools/common.sh`), so `repository` is auto-discovered — **no edits to the `REPOS` arrays** needed. `build-all.sh`/`test-all.sh` filter by `go.mod`, so `repository` (no `go.mod`) is correctly skipped. Root `.gitignore` gains `/repository/` and `/.aports/`. - Docs (`AGENTS.md`, `docs/architecture.md`, `docs/os/os.md`) updated for the new repo and the moved package tree. ## Out of scope - Actual APKBUILD content / real package builds — stubs only this pass. - `res-edit` / `res-os` packaging. - `os` ISO `--repository` wiring (documented as future; not changed now). ## Verification - `cd repository && git status` shows `res-core/`, `res-extra/`, `.forgejo/`, READMEs, and style docs; **no `go.mod`**. - `bash .agent/tools/status-all.sh` lists `repository`; `sync-repos.sh` discovers it; `.aports` and `repository` are git-ignored at the root. - `os` still builds an ISO unchanged — no regression from moving `os/residual/`. - `AGENTS.md` / `docs/architecture.md` / `docs/os/os.md` are consistent; `os/residual/` is no longer described as the package tree. --- # Handoff (ordered, concrete steps for the build agent) Run from the workspace root `/workspace/git.merith.xyz/residual` unless noted. Replace `forgejo.example.com` / `residual` (owner) / branch `v3.24` with the real Forgejo values when known; confirm the Forgejo host + owner before authoring `build.yml`'s publish step. ### Phase 0 — Pre-flight - Confirm the `repository` remote: `git.merith.xyz/residual/repository` (adjust if the real remote differs). - Confirm Forgejo host, owner, and the alpine `branch` used for the registry (e.g. `v3.24`). These feed `build.yml` and the future `os` `--repository` URL. - Confirm a Forgejo personal access token with package-write scope exists as a repo secret `FORGEJO_TOKEN` (used by `build.yml`). ### Phase 1 — Initialize the repo ``` mkdir -p /workspace/git.merith.xyz/residual/repository cd /workspace/git.merith.xyz/residual/repository git init -q git remote add origin git.merith.xyz/residual/repository # adjust if different ``` ### Phase 2 — Directory skeleton ``` mkdir -p res-core res-extra .forgejo/workflows for p in res res-init res-console res-sh res-login; do mkdir -p "res-core/$p"; done mkdir -p res-extra/res-calc ``` ### Phase 3 — Move APKBUILD style docs out of `os/` `os/CODINGSTYLE.md` and `os/COMMITSTYLE.md` are aports-derived APKBUILD/aports commit conventions — they belong in the package repo. Copy to `./CODINGSTYLE.md` / `./COMMITSTYLE.md`; in `os/` (separate commit): `git rm CODINGSTYLE.md COMMITSTYLE.md`, edit `os/README.md` to state os is image-build only. ### Phase 4 — `repository/README.md` (see plan for full content) Documents APKBUILD-only recipes, `res-core`/`res-extra` repos, publishing to Forgejo Alpine registry, consuming via `/etc/apk/repositories` + signing key. ### Phase 5 — `repository/.gitignore` ``` # abuild build artifacts pkg/ src/ APKINDEX* *.apk # abuild keys *.rsa *.rsa.pub # editor droppings *.swp ``` ### Phase 6 — APKBUILD stubs One `APKBUILD` per package (placeholders; `source=`/`builddir=`/`pkgver` finalized when actually built). Template for `res-core/res-console/APKBUILD`: ```sh # Maintainer: residual <maintainer@residual> pkgname=res-console pkgver=0.0.0 pkgrel=0 pkgdesc="residual PTY-based console multiplexer" url="https://git.merith.xyz/residual/core" arch="all" license="MIT" makedepends="go" subpackages="$pkgname-doc" source="$pkgname-$pkgver.tar.gz::https://git.merith.xyz/residual/core/archive/refs/tags/$pkgname-v$pkgver.tar.gz" builddir="$srcdir/core-$pkgname-v$pkgver" build() { go build -o "$pkgname" ./cmd/"$pkgname"; } package() { install -Dm755 "$pkgname" "$pkgdir"/usr/bin/"$pkgname"; } ``` Create analogous files for: `res-core/res`, `res-core/res-init`, `res-core/res-sh`, `res-core/res-login`, and `res-extra/res-calc` (`pkgname`/`cmd` path adjusted; `res-calc` source is `extra/`). ### Phase 7 — Forgejo workflows - `.forgejo/workflows/lint.yml` (advisory): alpine:3.24 container; shellcheck + apkbuild-lint (continue-on-error: true). - `.forgejo/workflows/build.yml` (build + publish): on push to main with APKBUILD path changes; `abuild -r` changed packages; `curl --user "${FORGEJO_OWNER}:${FORGEJO_TOKEN}" --upload-file` to `https://${FORGEJO_HOST}/api/packages/${FORGEJO_OWNER}/alpine/${BRANCH}/${repo}`. Uses `FORGEJO_HOST`/`FORGEJO_OWNER`/`FORGEJO_TOKEN`/`BRANCH` env (TODO: real values). ### Phase 8 — Root `.gitignore` Add to the "Each subdirectory is an independent git repository" block: ``` /repository/ /.aports/ ``` ### Phase 9 — Harness (no edits required) `.agent/tools/*.sh` already use `discover_repos()`; `repository/` is discovered automatically. `build-all.sh`/`test-all.sh` filter by `go.mod`, so `repository` (no `go.mod`) is correctly skipped. ### Phase 10 — Docs - `AGENTS.md`: add `repository` to workspace-layout tree + separate-repos list; note it is a package-*build* repo producing `res-core`/`res-extra` apk repos; keep `os` as image builder. - `docs/architecture.md`: add `repository` to repo-layout table. - `docs/os/os.md`: update stale "repository structure (planned)"; note `os/residual/` moved to `repository`; ISO will later consume `res-core`/`res-extra` from Forgejo (future wiring). ### Phase 11 — Commit & verify ``` cd /workspace/git.merith.xyz/residual/repository git add -A git commit -m "feat: scaffold residual package repository (res-core/res-extra)" ``` Verify: `git status` clean; tree has `res-core/`, `res-extra/`, `.forgejo/`, READMEs, style docs; no `go.mod`. From root: `bash .agent/tools/status-all.sh` lists `repository`; `os` still builds an ISO unchanged; root `.gitignore` ignores `/repository/` and `/.aports/`. ## Future (not in this handoff) - `os/entrypoint.sh` and `os/.forgejo/workflows/build-iso.yml` add `--repository` URLs for `res-core`/`res-extra` from Forgejo. - Real APKBUILD content + package builds (replace stubs). - `res-edit` / `res-os` packaging in separate efforts.

agent added the

tier-4-infra

label

2026-07-19 02:32:42 +00:00

agent referenced this issue

2026-07-19 02:35:51 +00:00

Harness: migrate backlog to Forgejo issues + document MCP scoping limitation #1