triflux 10.41.0 → 10.42.0

package/cto/hygiene-actions.mjs

@@ -0,0 +1,355 @@
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
+
+const ARCHIVABLE_ACTIONS = new Set([
+  "archive_or_resume_session",
+  "prune_superseded_checkpoint",
+]);
+
+function shortHash(value) {
+  const str = String(value ?? "");
+  let h = 5381;
+  for (let i = 0; i < str.length; i += 1) {
+    h = (h * 33) ^ str.charCodeAt(i);
+  }
+  return (h >>> 0).toString(36);
+}
+
+function stewardRootHash(rootDir) {
+  return createHash("sha256")
+    .update(String(rootDir || ""))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+function hygieneKeyForRow(row) {
+  return `${row.kind}:${row.id}`;
+}
+
+function yyyymmdd(value) {
+  const date = value ? new Date(value) : new Date();
+  if (Number.isNaN(date.getTime())) return yyyymmdd(new Date().toISOString());
+  return date.toISOString().slice(0, 10).replace(/-/gu, "");
+}
+
+function safeLabel(value) {
+  return (
+    String(value || "item")
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/gu, "-")
+      .replace(/^-+|-+$/gu, "")
+      .slice(0, 80) || "item"
+  );
+}
+
+function isInside(parent, child) {
+  const rel = relative(resolve(parent), resolve(child));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function normalizeActiveSessions(active) {
+  const sessions = Array.isArray(active)
+    ? active
+    : Array.isArray(active?.sessions)
+      ? active.sessions
+      : Array.isArray(active?.live_sessions)
+        ? active.live_sessions
+        : [];
+  return sessions
+    .map((session) => ({
+      sessionId: String(session?.sessionId || session?.session_id || "").trim(),
+      phase: String(
+        session?.phase || session?.status || "active",
+      ).toLowerCase(),
+    }))
+    .filter((session) => session.sessionId);
+}
+
+function isLiveOwned(row, activeSessions) {
+  const rowSession = String(row?.session_id || row?.id || "").trim();
+  if (!rowSession) return false;
+  return activeSessions.some(
+    (session) => session.sessionId === rowSession && session.phase !== "stale",
+  );
+}
+
+function assertProjectHash(row, rootDir) {
+  if (!row?.project_root_hash) return;
+  const allowed = new Set([shortHash(rootDir), stewardRootHash(rootDir)]);
+  if (!allowed.has(String(row.project_root_hash))) {
+    throw new Error(
+      `project_root_hash mismatch for ${hygieneKeyForRow(row)}: ${row.project_root_hash}`,
+    );
+  }
+}
+
+function assertLakePath(lakeRoot, path, label) {
+  if (!isInside(lakeRoot, path)) {
+    throw new Error(`${label} must be under lakeRoot: ${path}`);
+  }
+}
+
+function sourceBytes(path) {
+  const info = statSync(path);
+  if (info.isFile()) return info.size;
+  if (!info.isDirectory()) return info.size || 0;
+  return 0;
+}
+
+function targetPathFor({ lakeRoot, row, sourcePath, now }) {
+  const archiveDir = join(lakeRoot, "archive", yyyymmdd(now));
+  const label = safeLabel(hygieneKeyForRow(row));
+  return join(archiveDir, `${label}-${basename(sourcePath)}`);
+}
+
+function hasSecondActorApproval(opts = {}) {
+  if (opts.humanAck === true || opts.humanGate === true) return true;
+  const actorSessionId = String(opts.actorSessionId || "").trim();
+  if (!actorSessionId) return false;
+  const hygieneKey = opts.hygieneKey;
+  const approvals = Array.isArray(opts.approvals) ? opts.approvals : [];
+  return approvals.some((entry) => {
+    const ref = entry?.ref && typeof entry.ref === "object" ? entry.ref : {};
+    if (ref.hygiene_key !== hygieneKey) return false;
+    const approverSession = String(ref?.actor?.session_id || "").trim();
+    return Boolean(approverSession && approverSession !== actorSessionId);
+  });
+}
+
+function movePath(sourcePath, targetPath, fsOps = {}) {
+  const ops = {
+    copyFileSync,
+    cpSync,
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    renameSync,
+    rmSync,
+    unlinkSync,
+    ...fsOps,
+  };
+  ops.mkdirSync(dirname(targetPath), { recursive: true });
+  try {
+    ops.renameSync(sourcePath, targetPath);
+    return "rename";
+  } catch (error) {
+    if (error?.code !== "EXDEV") throw error;
+    const info = ops.lstatSync(sourcePath);
+    if (info.isDirectory()) {
+      ops.cpSync(sourcePath, targetPath, { recursive: true, force: false });
+      ops.rmSync(sourcePath, { recursive: true, force: false });
+    } else {
+      ops.copyFileSync(sourcePath, targetPath);
+      ops.unlinkSync(sourcePath);
+    }
+    return "copy_unlink";
+  }
+}
+
+function digestOperations(operations) {
+  const payload = operations.map((operation) => ({
+    hygiene_key: operation.hygiene_key,
+    status: operation.status,
+    source_path: operation.source_path,
+    target_path: operation.target_path,
+    bytes: operation.bytes,
+    reason: operation.reason,
+  }));
+  return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+function rowsFromProjection(projection) {
+  return Array.isArray(projection?.rows) ? projection.rows : [];
+}
+
+export async function applyHygieneArchiveActions({
+  rootDir,
+  lakeRoot,
+  projection,
+  dryRun = true,
+  now = new Date().toISOString(),
+  applyMode = "off",
+  active = {},
+  humanAck = false,
+  humanGate = false,
+  actorSessionId = null,
+  approvals = [],
+  fsOps = {},
+} = {}) {
+  const archiveRoot = join(lakeRoot, "archive", yyyymmdd(now));
+  assertLakePath(lakeRoot, archiveRoot, "archive target");
+
+  const activeSessions = normalizeActiveSessions(active);
+  const operations = [];
+
+  for (const row of rowsFromProjection(projection)) {
+    const hygieneKey = hygieneKeyForRow(row);
+    if (row?.kind === "worktree" && row?.status === "orphaned") {
+      operations.push({
+        hygiene_key: hygieneKey,
+        kind: row.kind,
+        id: row.id,
+        action: row.action,
+        status: "blocked",
+        reason: "orphan_worktree_requires_human",
+        bytes: 0,
+      });
+      continue;
+    }
+
+    if (!ARCHIVABLE_ACTIONS.has(row?.action)) continue;
+
+    assertProjectHash(row, rootDir);
+
+    if (isLiveOwned(row, activeSessions)) {
+      operations.push({
+        hygiene_key: hygieneKey,
+        kind: row.kind,
+        id: row.id,
+        action: row.action,
+        status: "skipped",
+        reason: "live_session_owned",
+        bytes: 0,
+      });
+      continue;
+    }
+
+    const sourcePath = row.artifact_path ? resolve(row.artifact_path) : null;
+    if (!sourcePath) {
+      operations.push({
+        hygiene_key: hygieneKey,
+        kind: row.kind,
+        id: row.id,
+        action: row.action,
+        status: "skipped",
+        reason: "missing_artifact_path",
+        bytes: 0,
+      });
+      continue;
+    }
+    // lake 밖 산출물은 자동 이동 대상이 아니다 — 크래시 대신 skip으로 보고한다.
+    // (checkpoint 등 실제 산출물은 대부분 lake 밖에 있으므로 throw 하면 apply 전체가 죽는다.)
+    if (!isInside(lakeRoot, sourcePath)) {
+      operations.push({
+        hygiene_key: hygieneKey,
+        kind: row.kind,
+        id: row.id,
+        action: row.action,
+        source_path: sourcePath,
+        status: "skipped",
+        reason: "source_outside_lake",
+        bytes: 0,
+      });
+      continue;
+    }
+
+    const targetPath = targetPathFor({ lakeRoot, row, sourcePath, now });
+    assertLakePath(lakeRoot, targetPath, "archive target");
+
+    if (!existsSync(sourcePath)) {
+      operations.push({
+        hygiene_key: hygieneKey,
+        kind: row.kind,
+        id: row.id,
+        action: row.action,
+        source_path: sourcePath,
+        target_path: targetPath,
+        status: existsSync(targetPath) ? "already_archived" : "skipped",
+        reason: existsSync(targetPath) ? undefined : "source_missing",
+        bytes: 0,
+      });
+      continue;
+    }
+
+    operations.push({
+      hygiene_key: hygieneKey,
+      kind: row.kind,
+      id: row.id,
+      action: row.action,
+      source_path: sourcePath,
+      target_path: targetPath,
+      status: "planned",
+      bytes: sourceBytes(sourcePath),
+    });
+  }
+
+  if (!dryRun) {
+    for (const operation of operations) {
+      if (operation.status !== "planned") continue;
+      if (applyMode !== "archive") {
+        operation.status = "blocked";
+        operation.reason = "apply_mode_off";
+        continue;
+      }
+      if (
+        !hasSecondActorApproval({
+          humanAck,
+          humanGate,
+          actorSessionId,
+          approvals,
+          hygieneKey: operation.hygiene_key,
+        })
+      ) {
+        operation.status = "blocked";
+        operation.reason = "second_actor_ack_required";
+        continue;
+      }
+      operation.move_method = movePath(
+        operation.source_path,
+        operation.target_path,
+        fsOps,
+      );
+      operation.status = "archived";
+    }
+  }
+
+  const plannedCount = operations.filter((operation) =>
+    ["planned", "archived", "already_archived"].includes(operation.status),
+  ).length;
+  const appliedCount = operations.filter(
+    (operation) => operation.status === "archived",
+  ).length;
+  const blockedCount = operations.filter(
+    (operation) => operation.status === "blocked",
+  ).length;
+
+  return {
+    schema_version: "cto-hygiene-actions.v1",
+    dry_run: Boolean(dryRun),
+    apply_mode: applyMode,
+    archive_root: archiveRoot,
+    planned_count: plannedCount,
+    applied_count: appliedCount,
+    blocked_count: blockedCount,
+    total_bytes: operations.reduce(
+      (sum, operation) => sum + Number(operation.bytes || 0),
+      0,
+    ),
+    digest: digestOperations(operations),
+    live_safety: {
+      active_session_count: activeSessions.length,
+      skipped_live_count: operations.filter(
+        (operation) => operation.reason === "live_session_owned",
+      ).length,
+    },
+    operations,
+  };
+}

package/cto/hygiene.mjs

@@ -11,8 +11,9 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
-
+import { getCtoHygieneApplyMode } from "../hub/lib/cto-env.mjs";
 import { appendCtoEvent } from "./events.mjs";
+import { applyHygieneArchiveActions } from "./hygiene-actions.mjs";
 import { resolveLakeRootDir } from "./lake-root.mjs";
 
 const COUNT_KEYS = [
@@ -178,6 +179,18 @@ function rowFrom(kind, id, status, entry, ref, action) {
   if (entry?.summary) row.summary = String(entry.summary);
   if (action) row.action = action;
   if (action && !hasKnownOwner(ref)) row.owner = "unknown";
+  if (typeof ref?.artifact_path === "string" && ref.artifact_path.trim()) {
+    row.artifact_path = ref.artifact_path.trim();
+  }
+  if (
+    typeof ref?.project_root_hash === "string" &&
+    ref.project_root_hash.trim()
+  ) {
+    row.project_root_hash = ref.project_root_hash.trim();
+  }
+  if (typeof ref?.session_id === "string" && ref.session_id.trim()) {
+    row.session_id = ref.session_id.trim();
+  }
   return row;
 }
 
@@ -517,17 +530,52 @@ function isApplicableRow(row) {
   return Boolean(row?.action) || APPLICABLE_STATUSES.has(row?.status);
 }
 
+const ARCHIVE_ACK_STATUSES = new Set(["archived", "already_archived"]);
+
+function hygieneApplyActor(opts = {}) {
+  const actor = { cli: "tfx cto hygiene --apply" };
+  if (typeof opts.actorSessionId === "string" && opts.actorSessionId.trim()) {
+    actor.session_id = opts.actorSessionId.trim();
+  }
+  return actor;
+}
+
 async function applyHygieneRows({
   rootDir,
   lakeRoot,
   projection,
   steward,
+  active,
+  approvals,
   opts,
 }) {
   const rows = projection.rows.filter(isApplicableRow);
   const appended = [];
   const now = opts.now || new Date().toISOString();
+  const actions = await applyHygieneArchiveActions({
+    rootDir,
+    lakeRoot,
+    projection: { ...projection, rows },
+    dryRun: false,
+    now,
+    applyMode: opts.applyMode || getCtoHygieneApplyMode(),
+    active,
+    humanAck: opts.humanAck,
+    humanGate: opts.humanGate,
+    actorSessionId: opts.actorSessionId,
+    approvals,
+    fsOps: opts.fsOps,
+  });
+  const operationByKey = new Map(
+    (actions.operations || []).map((operation) => [
+      operation.hygiene_key,
+      operation,
+    ]),
+  );
   for (const row of rows) {
+    const hygieneKey = hygieneKeyForRow(row);
+    const operation = operationByKey.get(hygieneKey);
+    if (operation && !ARCHIVE_ACK_STATUSES.has(operation.status)) continue;
     const result = await appendCtoEvent(
       lakeRoot,
       {
@@ -536,12 +584,12 @@ async function applyHygieneRows({
         source: "tfx_cto_hygiene_apply",
         project_root: rootDir,
         status: row.status,
-        hygiene_key: hygieneKeyForRow(row),
+        hygiene_key: hygieneKey,
         hygiene_kind: row.kind,
         hygiene_id: row.id,
         hygiene_action: row.action || `acknowledge_${row.status}`,
         summary: `hygiene apply ${row.kind}:${row.id} ${row.status}`,
-        actor: { cli: "tfx cto hygiene --apply" },
+        actor: hygieneApplyActor(opts),
       },
       {
         stderr: opts.stderr,
@@ -559,6 +607,7 @@ async function applyHygieneRows({
     },
     applicable_count: rows.length,
     applied_count: appended.length,
+    actions,
     events: appended,
   };
 }
@@ -582,15 +631,21 @@ export async function runHygiene(args = [], opts = {}) {
     const current = existsSync(currentPath) ? readJson(currentPath) : {};
     const ledger = readJsonLines(join(lakeRoot, "ledger.jsonl"));
     const overlay = await readLiveOverlay({ ...opts, rootDir, lakeRoot });
-    return projectCtoHygiene({
-      current,
-      ledger: ledger.length > 0 ? ledger : null,
+    return {
+      ledger,
       overlay,
-    });
+      projection: projectCtoHygiene({
+        current,
+        ledger: ledger.length > 0 ? ledger : null,
+        overlay,
+      }),
+    };
   };
 
   let steward = null;
   let projection;
+  let overlay = { live_sessions: [] };
+  let ledger = [];
   let applyResult = null;
   if (apply) {
     steward = await acquireCtoHygieneStewardLock(rootDir, lakeRoot, {
@@ -600,12 +655,14 @@ export async function runHygiene(args = [], opts = {}) {
       lockPath: opts.stewardLockPath,
     });
     try {
-      projection = await buildProjection();
+      ({ projection, overlay, ledger } = await buildProjection());
       applyResult = await applyHygieneRows({
         rootDir,
         lakeRoot,
         projection,
         steward,
+        active: overlay,
+        approvals: ledger.filter((entry) => entry?.event === "hygiene_applied"),
         opts,
       });
       projection = { ...projection, dry_run: false, apply: applyResult };
@@ -613,7 +670,20 @@ export async function runHygiene(args = [], opts = {}) {
       steward.release();
     }
   } else {
-    projection = await buildProjection();
+    ({ projection, overlay } = await buildProjection());
+    projection = {
+      ...projection,
+      actions: await applyHygieneArchiveActions({
+        rootDir,
+        lakeRoot,
+        projection,
+        dryRun: true,
+        now: opts.now || new Date().toISOString(),
+        applyMode: opts.applyMode || getCtoHygieneApplyMode(),
+        active: overlay,
+        fsOps: opts.fsOps,
+      }),
+    };
   }
 
   if (jsonOut) writeJson(stdout, projection);

package/cto/index.mjs

@@ -1,4 +1,11 @@
-const SUBCOMMANDS = ["collect", "status", "dashboard", "hygiene", "event"];
+const SUBCOMMANDS = [
+  "collect",
+  "status",
+  "dashboard",
+  "hygiene",
+  "steward",
+  "event",
+];
 
 function printUsage(subcommand) {
   if (subcommand) {
@@ -6,13 +13,14 @@ function printUsage(subcommand) {
   }
   console.log(`
 Usage
-  tfx cto <collect|status|dashboard|hygiene|event> [options]
+  tfx cto <collect|status|dashboard|hygiene|steward|event> [options]
 
 Subcommands
   collect     Refresh .triflux/lake/current.json from repo-local authority sources
   status      Print the current authority summary
   dashboard   Render the CTO console dashboard, optionally with --watch
   hygiene     Project CTO hygiene counts and actionable dry-run rows
+  steward     Periodically collect and run one-shot CTO hygiene (TFX_CTO=0 disables)
   event       Append normalized wrapper lifecycle events to the CTO ledger
 `);
 }
@@ -37,6 +45,10 @@ export async function cmdCto(cmdArgs, opts = {}) {
       const { runHygiene } = await import("./hygiene.mjs");
       return runHygiene(rest, opts);
     }
+    case "steward": {
+      const { runSteward } = await import("./steward.mjs");
+      return runSteward(rest, opts);
+    }
     case "event": {
       const { runEvent } = await import("./events.mjs");
       return runEvent(rest, opts);