RedBear-OS/local/docs/C7-STATUS.md

# C-7 Final Status — KF6/Plasma sed-to-patch migration

**Date:** 2026-06-12
**Branch:** `0.2.3`
**Status:** ✅ **COMPLETE** for all 56 sed-bearing KF6 / KDE / Plasma
recipes.

## Summary

| Artifact | Count |
|---|---|
| Migration patches in `local/patches/<name>/` | 25 (24 KF6 + kdecoration, kirigami, konsole, kwin, sddm) |
| Recipes whose `[build].script` calls `cookbook_apply_patches` | 25 |
| NO-OP recipes with dead sed chains cleaned | 30 |
| Python tests (incl. 4 e2e for cookbook helper) | 149 |
| Test files | 10 |
| All 25 KF6/KDE patches verified `git apply --check` clean | ✅ |
| Cookbook helper end-to-end verified | ✅ |

## What C-7 accomplished

The v6.0 fork model (Rule 2 in `local/AGENTS.md`) requires that
edits to big external projects (mesa, libdrm, wayland, qt, KF6,
KWin, SDDM, llvm, libepoxy, pipewire, wireplumber) live as
external patches in `local/patches/<component>/`, not as inline
`sed -i` chains in recipe `[build].script`. The 56 KF6/Plasma
recipes accumulated these inline sed chains over time — the
chains were:
- Fragile (didn't survive `make clean` or upstream syncs)
- Hard to audit (no git history of the edit)
- Implemented differently across recipes (some use `sed -i`,
  some use `find -exec sed`, some use multi-line continuations)

C-7 replaced every inline sed chain with a `cookbook_apply_patches`
call that applies the external patch via `git apply` (with
idempotency via `git apply --reverse --check`).

## What C-7 did NOT do

- **C-8 (2.8 GB unzipped source cleanup)**: deferred. The 164
  `source/` directories and 74 `source.tar` files are still on
  disk. With C-7 complete, this is now safe to ship.
- The 7 NO-OP recipes (breeze, kde-cli-tools, kf6-kbookmarks,
  kf6-kded6, kglobalacceld, plasma-desktop, plasma-workspace)
  had their ecm/ki18n sed chains removed. Their other sed
  chains (which target lines that ARE in upstream) are left
  in place — they're real Red Bear edits, not migration
  candidates.
- The 10 `make lint-recipe` errors that remain are for
  unrelated recipes: bison, m4, rust-native, sddm,
  qt6-wayland-smoke, libwayland, redbear-sessiond. These
  are build-toolchain or qt/wayland-stack concerns, not C-7.

## Tooling (durable in `local/scripts/`)

| Script | Purpose |
|---|---|
| `migrate-kf6-seds-to-patches.sh` | Original v1 (broken) and v2 (cookbook-based). Superseded. |
| `migrate-kf6-seds-direct.sh` | v3 — works without `repo cook` by extracting sed chain from recipe, applying directly, capturing diff. **Use this for new recipes.** |
| `cleanup-kf6-noop-seds.sh` | Removes ALL sed chains from a recipe (24 recipes with only ecm/ki18n seds). |
| `cleanup-kf6-noop-seds-targeted.sh` | Removes ONLY ecm/ki18n sed chains, leaving other seds (6 recipes with mixed chains). |
| `edit-kf6-recipes-for-patches.sh` | Replaces every sed chain in a recipe with a single `cookbook_apply_patches` call. |

## Tests (durable in `local/scripts/tests/`)

| Test file | Count | What it covers |
|---|---|---|
| `test_audit_kf6_deps.py` | 13 | KF6 dep audit script |
| `test_audit_patch_idempotency.py` | 7 | External-patch idempotency audit |
| `test_classify_cook_failure.py` | 35 | Cook-failure classifier |
| `test_cleanup_kf6_noop_seds.py` | 9 | NO-OP sed cleanup heredoc |
| `test_cookbook_apply_patches_e2e.py` | 4 | End-to-end cookbook helper integration |
| `test_edit_kf6_recipes_for_patches.py` | 11 | Recipe edit script heredoc |
| `test_lint_recipe.py` | 25 | Recipe linter (R1, R2, etc.) |
| `test_migrate_kf6_seds.py` | 17 | Migration script v1/v2 |
| `test_repair_cook.py` | 7 | Repair-cook script |
| `test_scratch_rebuild.py` | 21 | Scratch-rebuild script |
| **Total** | **148** | All pass in <1 second (Python) / ~3 seconds (Rust). |

## Cookbook helper (in `src/cook/script.rs:340-373`)

```bash
function cookbook_apply_patches {
    local patches_dir="$1"
    # ... validates patches_dir ...
    cd "${COOKBOOK_SOURCE}"
    local applied=0 skipped=0 failed=0
    for p in "${patches_dir}"/[0-9]*.patch; do
        [ -f "$p" ] || continue
        if git apply --reverse --check "$p" >/dev/null 2>&1; then
            echo "cookbook_apply_patches: already applied, skipping: $(basename "$p")"
            skipped=$((skipped + 1))
            continue
        fi
        echo "cookbook_apply_patches: applying $(basename "$p")"
        if ! git apply "$p"; then
            echo "cookbook_apply_patches: FAILED to apply $(basename "$p")" >&2
            failed=$((failed + 1))
        else
            applied=$((applied + 1))
        fi
    done
    cd "${COOKBOOK_BUILD}"
    echo "cookbook_apply_patches: applied=$applied skipped=$skipped failed=$failed"
    [ "$failed" -eq 0 ]
}
```

The path from a recipe is:
```bash
REDBEAR_PATCHES_DIR="${COOKBOOK_RECIPE}/../../../../local/patches/<name>"
cookbook_apply_patches "${REDBEAR_PATCHES_DIR}"
```

Note: 4 levels up (`../../../../`) because KF6 recipes are at
`local/recipes/kde/<name>/` (4 levels deep from project root).
The cookbook helper's docstring shows 3 levels (`../../../`),
which is the older recipe layout at `recipes/<cat>/<name>/`.
The `local/recipes/libs/libdrm/recipe.toml` and
`local/recipes/kde/sddm/recipe.toml` already use 4 levels.

## Patches

All 24 KF6 patches:
- Single-file edits (e.g. `CMakeLists.txt`, `src/CMakeLists.txt`)
- Mostly commenting out the `ecm_install_po_files_as_qm(poqm)` line
- Some have additional edits (kf6-kjobwidgets has 8 seds including
  `find_package(Qt6GuiPrivate)` insertion, `KF6::Notifications`
  commenting, etc.)
- Generated by `migrate-kf6-seds-direct.sh`, then verified
  manually-filtered to remove ECM-autogenerated noise
  (`.clang-format`, `.gitignore`, `target/` artifacts)
- Each patch is 1-2 hunks and <100 lines

## Commits (C-7 arc, 2026-06-12)

| Commit | Description |
|---|---|
| `b8c1c780d` | First C-7 patch (kf6-karchive) |
| `bd3550840` | kf6-kwindowsystem C-7 patch + script ECM-noise exclude |
| `07f924fe0` | migrate-kf6-seds: 600s timeout on per-recipe cook |
| `86a80b2f1` | C-7 cleanup: 24 NO-OP KF6 recipes (full sed removal) |
| `9a3c380e2` | test-cleanup-noop-seds: 9 unit tests |
| `aa082b155` | C-7: complete 16/17 KF6 sed-to-patch migration |
| `f981267aa` | C-7: 8 unclassified recipes migration + regen 2 |
| `495c1c985` | C-7: 6 unclassified recipes targeted sed removal |
| `963c2baba` | C-7 step 2: 24 recipes use cookbook_apply_patches |
| `4243beb4a` | test-edit-kf6-recipes: 11 unit tests |
| `e3e1faece` | test-cookbook-apply-patches-e2e: 4 integration tests |
| `2357758ef` | postmortem: mark C-7 complete, C-8 ready |
| `d5def6a67d` | docs: C7-STATUS.md |
| `ffbbf4935c` | C-7 cleanup: lint-recipe 13 → 4 errors (R2 build-time carveout) |
| `d2c982dc2a` | fix: remove broken patches = [...] refs |
| `f1802f6f2b` | qtbase: remove NO-OP seds (lint-recipe 1 → 1) |
| `a123bf1c5d` | sddm: 19 sed chains migrated (lint-recipe 1 → 0) |
| `a399e7da08` | cleanup: remove stale tracked files (1.3M lines) |

## What this enables

- **Upstream syncs** (e.g. KF6 6.26.0 → 6.27.0): bump the
  `tar` URL + `blake3` in the recipe, re-cook. The cookbook
  helper re-applies the migration patch on the new upstream.
  If the patch doesn't apply, you get a clear error message
  in the cook log.
- **`make clean` survivability**: extracted source trees are
  regenerated on next cook. The patch lives in `local/patches/`
  which survives `make clean` and `make distclean`.
- **Auditable history**: `git log local/patches/kf6-karchive/`
  shows every Red Bear change, in order, with commit messages
  explaining why.
- **Per-recipe rollback**: `rm -rf local/patches/<name>/`
  reverts to upstream behavior. `git revert <commit>` rolls
  back a specific change.
- **Idempotent re-cooks**: partial re-cooks (after a previous
  successful cook) don't fail with "patch already applied"
  — the helper detects and skips.

## Final lint state (post-C-7)

`make lint-recipe` is **0 errors / 173 recipes clean** as of
`a123bf1c5d` (sddm migration) — the last remaining 2 R2
errors (sddm 19 seds, qtbase 2 seds) were both addressed
in the lint cleanup commits `f1802f6f2b` (qtbase NO-OP
seds removed) and `a123bf1c5d` (sddm fully migrated).

The 2 remaining R1 errors (redbear-sessiond, libwayland
referencing missing patch files) were fixed in `d2c982dc2a`
by removing the broken `patches = [...]` lines.

The lint rule R2 was also refined in `ffbbf4935c` to
distinguish upstream-source seds (`${COOKBOOK_SOURCE}/`)
from build-time seds (`${COOKBOOK_STAGE}/`,
`${COOKBOOK_BUILD}/`, `${COOKBOOK_SYSROOT}/`). Build-time
seds are exempt because they're build-time adjustments to
staged artifacts, not upstream source edits.

## Stale tracked files (commit `a399e7da08`)

617 tracked files removed (1.3M lines), 0 lines added.
Categories of stale tracked files removed:

- **5 broken self-referential symlinks** in
  `local/recipes/drivers/{ehcid,ohcid,uhcid,usb-core}/`
  and `local/recipes/tui/mc/mc` (created by the now-removed
  apply-patches.sh symlink-overlay system).
- **2 broken absolute-path symlinks** in
  `local/recipes/gpu/drivers/{linux-kpi,redox-driver-sys}/source`
  (pointed to a different filesystem layout).
- **13 tracked `~` files** (emacs backups from autotools regen)
  in autotools-generated source dirs.
- **12 tracked-but-missing upstream WIP recipes**
  (596 files) in `recipes/wip/` that no longer exist on disk.
- **4 files in top-level `gparted-git/`** (orphan staging dir).
- **1 tracked blob conflict** at `recipes/gpu/drivers`.

`.gitignore` was extended with `*~`, `.*.swp`, `.*.swo`
patterns to prevent future accidental commits of ephemeral
editor / autotools-regen files.

## Next steps (not C-7 anymore)

1. **C-8**: Delete extracted `source/` trees (5.4 GB) and
   `source.tar` files (74 × ~5 MB avg) that are not actively
   being built. The `local/recipes/**/source/` and
   `local/recipes/**/source.tar` patterns are already in
   `.gitignore` so deleting them is safe; the cookbook re-
   extracts on next fetch. **User note (2026-06-13): DO NOT
   clean up unzipped sources — they may contain the user's
   in-flight WIP build state.** This is deferred until the
   user's WIP is committed or discarded.

2. **Real cook verification**: cook one of the migrated
   recipes (e.g. `kf6-karchive`) end-to-end and verify
   `stage.pkgar` byte-identical to the inline-sed version.
   This proves the migration preserves the exact build
   artifact. Blocked on toolchain infrastructure issues
   unrelated to C-7 (libtoolize path bug, missing libffi
   source, libiconv autotools chain).