@dev-loops/core 0.9.0 → 1.0.0-rc.1

package/src/loop/ui-review-teardown.mjs

@@ -2,7 +2,7 @@
  * Teardown + side-effect ledger orchestrator for the ui_review route (Stage 5).
  *
  * Terminal cleanup for a running-app review: stop the app booted in Stage 1,
- * drop the dev-DB rows the Stage-2 drive created, and remove the provisioned
+ * drop the dev-DB rows the Stage-2 drive tagged, and remove the provisioned
  * worktree. The core safety property of this stage is that a side-effect ledger
  * is ALWAYS emitted — enumerating every migration applied, row created/dropped,
  * the worktree path, and any process left running — so nothing the loop touched
@@ -28,11 +28,12 @@
  */
 
 /**
- * The honest row-drop reality: Stage 2 does NOT tag the dev-DB rows it creates
- * with a session id or row manifest. So unless an explicit row manifest is
- * handed in (and confirmed), this stage CANNOT know which rows to drop and MUST
- * NOT guess. When the drive ran mutating flows without a manifest, the ledger
- * reports rows "may remain (untagged)" rather than dropping anything.
+ * Row-drop model: Stage 2 stamps each mutating step with a drive-session id and
+ * emits a session-tagged row manifest. Given that manifest (and confirmation),
+ * this stage drops exactly the rows tagged with that session. Only the fallback
+ * case — a drive that mutated but handed in no manifest — CANNOT know which rows
+ * to drop and MUST NOT guess: the ledger reports rows "may remain (untagged)"
+ * rather than dropping anything.
  */
 
 const ROW_STATUS = Object.freeze({
@@ -60,6 +61,13 @@ const PROCESS_STATUS = Object.freeze({
   SKIPPED: "skipped",
 });
 
+const GIST_STATUS = Object.freeze({
+  DELETED: "deleted",
+  DELETE_FAILED: "delete-failed",
+  SKIPPED_UNCONFIRMED: "skipped-unconfirmed",
+  NONE: "none",
+});
+
 /**
  * Did the Stage-2 drive potentially create dev-DB rows? Without row tagging this
  * is a coarse but honest signal: a drive that actually walked steps exercised
@@ -82,8 +90,12 @@ function driveMayHaveCreatedRows(driveResult) {
  *   signal (whether the drive walked mutating steps). Null when no drive ran.
  * @param {Array<object>|null} [input.rowManifest] - Explicit rows to drop, when
  *   a session tag/manifest is available. Absent/empty => untagged fallback.
+ * @param {{id?:string|null,url?:string|null}|null} [input.gist] - The Stage-4
+ *   GitHub-native hosting artifact (a secret gist) to prune, when one was
+ *   published off-Claude. Absent => nothing to prune.
  * @param {boolean} [input.confirm] - Explicit authorization for the destructive
- *   steps (row drop, worktree removal). Fail-safe: absent means NOT confirmed.
+ *   steps (row drop, worktree removal, gist deletion). Fail-safe: absent means
+ *   NOT confirmed.
  * @param {boolean} [input.stopApp] - Stop the Stage-1 app (default true). This is
  *   a clean shutdown, NOT gated on confirmation.
  * @param {object} seams
@@ -92,12 +104,14 @@ function driveMayHaveCreatedRows(driveResult) {
  *   signalling is unsupported) — mapped to MAY_BE_RUNNING (non-fatal), not KILL_FAILED.
  * @param {(a:{rows:Array<object>})=>Promise<{ok:boolean,dropped:number,detail:string}>} seams.dropRows
  * @param {(a:{worktreePath:string})=>Promise<{removed:string|null,ok:boolean,detail:string}>} seams.removeWorktree
+ * @param {(a:{id:string})=>Promise<{ok:boolean,detail:string}>} [seams.deleteGist] - Prune the
+ *   Stage-4 hosting gist. Only invoked when a gist id is present AND confirmed.
  * @param {(msg:string)=>void} [seams.log]
  * @returns {Promise<{ok:boolean,confirmed:boolean,ledger:object,errors:string[],logs:string[]}>}
  */
 export async function teardown(
-  { provisionResult, driveResult = null, rowManifest = null, confirm = false, stopApp = true },
-  { killProcess, dropRows, removeWorktree, log = () => {} } = {},
+  { provisionResult, driveResult = null, rowManifest = null, gist = null, confirm = false, stopApp = true },
+  { killProcess, dropRows, removeWorktree, deleteGist, log = () => {} } = {},
 ) {
   const logs = [];
   const errors = [];
@@ -229,6 +243,33 @@ export async function teardown(
     }
   }
 
+  // 4. Prune the Stage-4 hosting gist — DESTRUCTIVE, confirmation-gated. A gist
+  //    accretes one secret entry per run; deleting it keeps the hosting target
+  //    from piling up. Only ever acts on an explicit gist id from the report
+  //    result; a missing id is NONE (nothing published, or Claude-hosted).
+  const gistId = typeof gist?.id === "string" && gist.id.trim().length > 0 ? gist.id.trim() : null;
+  let gistLedger;
+  if (!gistId) {
+    gistLedger = { id: null, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.NONE, detail: "no hosting gist to prune" };
+  } else if (!confirm) {
+    gistLedger = { id: gistId, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.SKIPPED_UNCONFIRMED, detail: "hosting gist retained: teardown not confirmed" };
+    record(`gist prune skipped (not confirmed): ${gistId} retained`);
+  } else {
+    try {
+      const del = await deleteGist({ id: gistId });
+      if (del.ok) {
+        gistLedger = { id: gistId, url: gist?.url ?? null, deleted: true, status: GIST_STATUS.DELETED, detail: del.detail };
+        record(`hosting gist deleted: ${gistId} (${del.detail})`);
+      } else {
+        gistLedger = { id: gistId, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.DELETE_FAILED, detail: del.detail };
+        fail(`hosting gist delete FAILED: ${gistId} (${del.detail})`);
+      }
+    } catch (err) {
+      gistLedger = { id: gistId, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.DELETE_FAILED, detail: `deleteGist seam threw: ${err?.message ?? err}` };
+      fail(`hosting gist delete FAILED: ${gistId} (deleteGist seam threw: ${err?.message ?? err})`);
+    }
+  }
+
   // The ledger is ALWAYS emitted (every case), enumerating every known side
   // effect. Migrations are recorded as applied-not-reverted by design.
   const ledger = {
@@ -241,10 +282,11 @@ export async function teardown(
     },
     rows: rowsLedger,
     worktree: worktreeLedger,
+    gist: gistLedger,
     process: processLedger,
   };
 
   return { ok: errors.length === 0, confirmed: confirm, ledger, errors, logs };
 }
 
-export { ROW_STATUS, WORKTREE_STATUS, PROCESS_STATUS };
+export { ROW_STATUS, WORKTREE_STATUS, PROCESS_STATUS, GIST_STATUS };