@camstack/system 1.2.15 → 1.2.16

package/dist/kernel/addon-installer.d.ts

@@ -33,6 +33,13 @@ export interface AddonInstallerConfig {
     readonly installSource?: InstallSource;
 }
 export type { InstalledPackage };
+/** Outcome of {@link AddonInstaller.sweepBackups}. Absolute paths. */
+export interface BackupSweepResult {
+    /** Backup dirs reclaimed by the sweep. */
+    readonly removed: readonly string[];
+    /** Backup dirs deliberately retained (rollback target / last copy). */
+    readonly kept: readonly string[];
+}
 export declare class AddonInstaller {
     readonly addonsDir: string;
     private readonly registry;
@@ -222,10 +229,14 @@ export declare class AddonInstaller {
      *   1. Rename current install dir → {addonsDir}/.backups/{name}/{ts}/
      *   2. Run a fresh install (npm or local depending on installSource)
      *   3. Record `lastBackupDir` in the manifest entry
+     *   4. Prune every OTHER backup of this addon — the previous one just
+     *      lost its only pointer and would otherwise be orphaned forever.
      *
-     * The post-install caller (kernel.restartAddon + health-check) is
-     * responsible for verifying the new version actually works and for
-     * triggering `rollbackAddon()` if the health check fails.
+     * The post-install caller (restart + health-check) is responsible for
+     * verifying the new version actually works, and for calling either
+     * `clearBackup()` on success or `rollbackAddon()` on failure. This
+     * method must NOT delete the backup itself: at this point the new
+     * version has not been proven to work.
      *
      * Throws if there is no installed version to update — caller should
      * prefer plain `install()` for first-time installs.
@@ -263,12 +274,80 @@ export declare class AddonInstaller {
      * backup to roll back to.
      */
     rollbackAddon(packageName: string): Promise<string | null>;
+    /** Root of the pre-update rollback copies: `{addonsDir}/.backups`. */
+    private get backupsRoot();
+    /**
+     * True only when `target` resolves to something strictly INSIDE
+     * `{addonsDir}/.backups/`.
+     *
+     * Every deletion in this section funnels through here. `lastBackupDir`
+     * is read back from a manifest file on disk — an operator edit, a
+     * restored manifest from another host, or a `..` in the recorded path
+     * must never turn "reclaim a backup" into "delete the live install".
+     */
+    private isInsideBackups;
+    /**
+     * Best-effort removal of one path under `.backups/`.
+     *
+     * Never throws: an undeleted backup is a disk-space problem, whereas a
+     * throw on the post-update success path would turn a working update into
+     * a reported outage. Returns true only when the path is gone.
+     */
+    private removeBackupPath;
+    /** List the timestamped backup dirs recorded for one package. */
+    private listBackupsFor;
+    /**
+     * Keep at most ONE backup per addon: drop every backup dir for
+     * `packageName` except `keepDir`.
+     *
+     * Called right after a new backup is recorded. Without this, a second
+     * update overwrites `lastBackupDir` and the previous backup becomes
+     * unreachable — no pointer, so neither `rollbackAddon` nor `clearBackup`
+     * can ever see it again. That is how the live hub accumulated two 398 MiB
+     * copies of one addon. Never throws.
+     */
+    private pruneBackups;
+    /** Drop `.backups/{pkg}` (and its `@scope` parent) once they are empty. */
+    private removeEmptyBackupDirs;
+    /**
+     * Drop the recorded backup for an addon — call once the post-update
+     * health check confirms the new version actually works.
+     *
+     * Never throws and never rejects. The manifest pointer is cleared even
+     * when the bytes could not be removed: a pointer at a half-deleted tree
+     * would make `rollbackAddon` restore a gutted install, and the boot sweep
+     * reclaims the residue on the next start.
+     */
+    clearBackup(packageName: string): Promise<void>;
+    /**
+     * Boot-time retention sweep over `{addonsDir}/.backups/`.
+     *
+     * RULE: for each addon, the ONLY backup that survives is the one the
+     * manifest's `lastBackupDir` points at — everything else is unreachable
+     * by construction (no pointer ⇒ neither `rollbackAddon` nor `clearBackup`
+     * can ever reach it). One exception: when the addon's LIVE install dir is
+     * missing, the newest backup is the only surviving copy of that addon (a
+     * crash between the rename-aside and the manifest write in `applyUpdate`),
+     * so it is kept instead of reclaimed.
+     *
+     * Why not "delete everything once the addon is healthy": this installer
+     * has no health signal, and the pointed-at backup is precisely the one a
+     * failed update left for the operator's Rollback button. Bounding to one
+     * per addon is enough — the observed 814 MiB was duplicate copies, not a
+     * single retained rollback target.
+     *
+     * Never throws. Safe to run on every boot; runs before any update can be
+     * in flight.
+     */
+    sweepBackups(): Promise<BackupSweepResult>;
     /**
-     * Drop the recorded backup for an addon (e.g. after a successful
-     * post-update health check confirms the new version is healthy).
-     * Frees disk space without affecting the running install.
+     * Which backup of `packageName` survives the sweep: the manifest's
+     * rollback target, or — when the live install is gone — the newest copy,
+     * which is then the only one that exists. `null` means "reclaim them all".
      */
-    clearBackup(packageName: string): void;
+    private resolveBackupToKeep;
+    /** Package names that have a `.backups/{pkg}` directory, scoped or not. */
+    private listBackedUpPackages;
     uninstall(packageName: string): Promise<void>;
     listInstalled(): InstalledPackage[];
     isInstalled(packageName: string): boolean;

package/dist/kernel/fs-utils.d.ts

@@ -15,11 +15,24 @@ export declare function ensureDir(dirPath: string): void;
  */
 export declare function copyDirRecursive(src: string, dest: string): Promise<void>;
 /**
- * Runtime natives that must stay installable even when an addon forgets to
- * declare them: the mirror of the build preset's `COMMON_NATIVE_DEPS`
- * (tools/build/vite-lib.preset.ts — build tooling, not loadable at runtime).
- * These are the ONLY packages a self-contained dist genuinely `require()`s
- * from node_modules; everything else is already inlined by the bundle.
+ * Runtime deps a stripped addon package.json must KEEP so the installer still
+ * `npm install`s them into the addon dir.
+ *
+ * Empty by design: every native an addon can import is now HOST-EXTERNAL
+ * (node-av, sharp, node-pty — resolved from the framework closure via the
+ * resolver hook, see host-externals.ts), and every pure-JS lib (ssh2, werift,
+ * @simplewebauthn, mqtt, aws-sdk, …) is inlined by the self-contained vite
+ * bundle. So a self-contained dist requires NOTHING from a local node_modules —
+ * `addons/` stays node_modules-free, which is what lets the backup tar the whole
+ * folder with no exclusion list (see ADR-0027). An addon that genuinely needs an
+ * un-bundleable runtime dep declares it explicitly in
+ * `camstack.runtimeDependencies`; the debug escape hatch
+ * `CAMSTACK_INSTALL_FULL_DEPS=1` restores the legacy install-everything path.
+ *
+ * (Historically this mirrored the build preset's COMMON_NATIVE_DEPS and
+ * per-addon-installed node-av/sharp/onnxruntime-node/ssh2/werift/systeminformation
+ * — 74k files / 1.34 GB of redundant node_modules on the live hub. That redundancy
+ * is removed: the natives come from the framework, the pure-JS from the bundle.)
  */
 export declare const RUNTIME_NATIVE_KEEP: readonly string[];
 /**