chore: save plans

.plans/archived/trapos-create-installer-disk-plan.md

@@ -2,7 +2,7 @@
 
 ## Context
 
-Today TrapOS is installed by typing `wget run https://trapos.trapcloud.fr/install` on each
+Today TrapOS is installed by typing `wget run https://os.trapcloud.fr/install` on each
 fresh computer, then manually configuring settings (`sandbox.url`, `sandbox.password`, …) per
 machine. We want a **provisioning floppy**: run one program on a configured machine to "bake"
 an installer disk, then on any blank machine just insert the disk and boot — it installs the
@@ -50,7 +50,7 @@ in `apis/libccpm.lua`).
 --   opts.settings            (default global `settings`)    -- save() flush
 --   opts.settingsSourcePath  (default '/.settings')         -- computer config to clone
 --   opts.installerLabel      (default 'TrapOS Installer')
---   opts.installUrl          (default 'https://trapos.trapcloud.fr/install')
+--   opts.installUrl          (default 'https://os.trapcloud.fr/install')
 -- (uses real global `fs`; tests sandbox with isolated real dirs, like tests/ccpm.lua)
 ```
 
@@ -71,7 +71,7 @@ Public API:
 ```lua
 -- TrapOS installer disk autorun (generated; do not edit)
 local INSTALLER_LABEL = 'TrapOS Installer';
-local INSTALL_URL = 'https://trapos.trapcloud.fr/install';
+local INSTALL_URL = 'https://os.trapcloud.fr/install';
 
 if fs.exists('/trapos') then return; end  -- already installed: leave machine alone
 

.plans/trapos-create-disk-plan.md

@@ -0,0 +1,161 @@
+# Plan: `trapos-create-disk` + ccpm prune/autoprune
+
+## Context
+
+Today `programs/trapos-create-installer-disk.lua` only builds an **install** floppy disk
+(its `startup.lua` installs TrapOS on a _blank_ computer). We want one disk-creation tool
+that can also produce **reinstall** and **uninstall** disks, and we want a real "remove
+TrapOS" path. ComputerCraft's `ccpm uninstall trapos` alone is insufficient: it only deletes
+the `trapos` meta-package's own files and its dependency guard blocks cascading removal.
+
+The fix is two-sided:
+
+1. Teach `ccpm` to remove orphaned dependencies (`prune`), auto-pruned on `uninstall`, so
+   `ccpm uninstall trapos` cleanly wipes the whole tree and the `/trapos` state dir.
+2. Rename/generalize the disk creator to emit install / reinstall / uninstall disks whose
+   `startup.lua` performs the matching action on the booted target.
+
+## Decisions (settled with user)
+
+- Program rename: `programs/trapos-create-installer-disk.lua` → **`programs/trapos-create-disk.lua`**.
+  Bare command prints help. Flags select the disk variant: `--install`, `--reinstall`,
+  `--uninstall`. Keep `version` and `help`.
+- **No** separate `trapos-uninstall.lua`. Everything routes through `ccpm uninstall trapos`.
+- `ccpm` gains a new **`explicit`** flag per lock entry, a **`prune`** command, **autoprune
+  on uninstall** (`--no-prune` to disable), interactive **y/N confirm** with **`--yes`/`-y`**,
+  and **state-dir deletion when empty**. `ccpm` never auto-reboots — the disk `startup.lua`
+  owns reboot/eject.
+
+---
+
+## Part A — ccpm changes
+
+### A1. `explicit` flag (`apis/libccpm.lua`, `api.install` ~L397)
+
+When writing a lock entry, set `explicit = (item.name == pkg)`. Deps pulled in get
+`explicit = false`. Preserve an existing `true` (re-installing a dep that was previously
+explicit must not demote it). **Legacy/migration:** a lock entry with no `explicit` field is
+treated as `explicit = true` (never auto-prune pre-existing installs).
+
+### A2. `api.prune(opts)` (new, `apis/libccpm.lua`)
+
+- Compute the set of packages **reachable** from every explicit root by walking
+  `dependencies` (reuse the traversal idea from `api.resolve`, L314).
+- Orphans = installed packages not in the reachable set.
+- Remove the **whole orphan set atomically**: delete each orphan's `files`, drop all their
+  lock entries in one pass, then `writeLock` + `writeOsState`. This deliberately bypasses the
+  per-package dependents guard in `api.uninstall` (orphans depend on each other but none are
+  reachable from a root). Return the list of pruned names.
+
+### A3. Autoprune in `api.uninstall` (`apis/libccpm.lua` L439)
+
+- Add `opts.prune` (default behavior = prune). After removing `pkg` (existing logic L463-469),
+  if pruning is enabled call `api.prune` and merge its removed list into the result/log.
+- `libccpm.uninstall` stays **non-interactive** (CLI owns the prompt) so `tests/ccpm.lua`
+  keep working.
+
+### A4. State-dir cleanup when empty (`apis/libccpm.lua`)
+
+- After any uninstall/prune that leaves `lock.packages` empty, delete the entire state dir
+  (`stateDir`, default `/trapos`) so the machine is blank and the reinstall guard
+  `fs.exists('/trapos')` passes. Also remove now-empty generated dirs created by the installer
+  (`/programs`, `/apis`, `/servers`, `/startup`) if empty. Guard the path so a custom test
+  `stateDir` is still removed safely.
+
+### A5. CLI wiring (`programs/ccpm.lua`)
+
+- `uninstall|remove|rm` handler (L102): parse `--no-prune` and `--yes`/`-y` from args. Unless
+  `--yes`, print what will be removed (`pkg` + a dry-run prune list) and read a y/N line via a
+  small local `confirm()` helper (no read() helper exists in the repo — add one using
+  `read()`/`io.read`). Pass `{ prune = not noPrune, log = logLine }` to `ccpm.uninstall`.
+- Add `prune` command → `ccpm.prune({ log = logLine })`, printing pruned packages or
+  "nothing to prune".
+- Update `printUsage()` to list `prune`, `uninstall [--yes] [--no-prune]`.
+
+---
+
+## Part B — disk creator
+
+### B1. Generalize `apis/libinstallerdisk.lua`
+
+- `create(opts)` takes `opts.mode = 'install' | 'reinstall' | 'uninstall'` (default `install`).
+- `buildAutorun(mode)` emits the variant `startup.lua`. Reuse `findTargetDrive`, labeling,
+  and `DEFAULT_INSTALL_URL` (`https://os.trapcloud.fr/install`). Rename disk label to
+  **"TrapOS Disk"**.
+- **install** mode: current behavior unchanged — clone `/.settings` onto the disk, autorun
+  guards `if fs.exists('/trapos') then return`, restores settings, `wget run INSTALL_URL`.
+  Only this mode clones settings.
+- **uninstall** mode autorun:
+
+  ```lua
+  if not fs.exists('/trapos') then print('TrapOS already removed.') else
+    shell.run('ccpm','uninstall','trapos','--yes')
+  end
+  print('TrapOS removed. Eject the disk to finish.')
+  os.pullEvent('disk_eject'); os.reboot()
+  ```
+
+- **reinstall** mode autorun (marker breaks the post-install loop, since `install-trapos`
+  reboots with the disk still inserted):
+
+  ```lua
+  local MARKER = '<diskMount>/.trapos-reinstalled'
+  if fs.exists(MARKER) then
+    print('Reinstall complete. Eject the disk.')
+    os.pullEvent('disk_eject'); os.reboot(); return
+  end
+  -- write MARKER
+  if fs.exists('/trapos') then shell.run('ccpm','uninstall','trapos','--yes') end
+  shell.run('wget','run', INSTALL_URL)  -- installer reboots
+  ```
+
+  `/.settings` is left untouched by uninstall, so the machine keeps its own config — no clone.
+
+### B2. Rewrite `programs/trapos-create-disk.lua`
+
+- Replace positional command parsing with flag parsing (pattern from `programs/ai.lua` L4-26).
+- Bare invocation (or `help`) → `printUsage()` documenting `--install/--reinstall/--uninstall`.
+- Keep `version` via `require('/apis/libversion')().forSelf()` and the local `printColored`.
+- Map flag → `createInstallerDisk().create({ mode = ... })`; reuse existing success/warning
+  output (label, settingsCopied/Warning, insert-and-reboot hint), adjusting copy per mode.
+
+---
+
+## Part C — packaging / metadata
+
+- `packages/trapos-core/ccpm.json`: rename `programs/trapos-create-installer-disk.lua` →
+  `programs/trapos-create-disk.lua` in `files`; bump `version`.
+- `packages/index.json`: bump `trapos-core` version to match.
+- Delete the old `programs/trapos-create-installer-disk.lua` file (currently uncommitted/new).
+
+---
+
+## Files to modify
+
+- `apis/libccpm.lua` — `explicit` flag, `api.prune`, autoprune in `api.uninstall`, empty-state cleanup.
+- `programs/ccpm.lua` — `prune` command, uninstall `--yes`/`--no-prune` + confirm helper, usage.
+- `apis/libinstallerdisk.lua` — mode-parameterized `create`/`buildAutorun`, label rename.
+- `programs/trapos-create-disk.lua` — new (renamed from `trapos-create-installer-disk.lua`).
+- `packages/trapos-core/ccpm.json`, `packages/index.json` — file rename + version bump.
+
+## Tests (repo uses `apis/libtest`, `__TRAPOS_TEST_OK__` on pass)
+
+- `tests/ccpm.lua` — add:
+  - install marks target `explicit=true`, deps `explicit=false`.
+  - `prune` removes orphans not reachable from explicit roots; keeps reachable ones.
+  - `uninstall trapos` (with deps) autoprunes the whole tree; `--no-prune`/`{prune=false}`
+    removes only the target.
+  - uninstalling the last package deletes the (test) state dir.
+  - legacy entry without `explicit` is not pruned.
+- Rename `tests/installer-disk.lua` → `tests/create-disk.lua`; add `buildAutorun` assertions
+  per mode: install contains settings-copy-before-`wget`; uninstall contains `ccpm uninstall
+trapos --yes` + `disk_eject` and no `wget`; reinstall contains marker check + `uninstall
+--yes` + `wget run`.
+
+## Verification
+
+1. Run the suite: `tests/ccpm.lua` and `tests/create-disk.lua` (look for `__TRAPOS_TEST_OK__`).
+2. Manually inspect generated `startup.lua` for each mode via the new `buildAutorun` tests.
+3. In-world (if available): build an install disk on a blank computer (unchanged path), then a
+   reinstall disk and an uninstall disk on an installed computer; confirm uninstall wipes
+   `/trapos` and waits for eject, and reinstall completes then waits for eject.