chainlesschain 0.165.3 → 0.165.5

package/src/commands/artifacts.js

@@ -5,10 +5,10 @@
  * `~/.chainlesschain/artifacts/`; this command is the user-facing surface:
  *
  *   cc artifacts list [--session <id>] [--kind <k>] [--json]
- *   cc artifacts show <id> [--json]        metadata + stored path
- *   cc artifacts open <id>                 print the stored path (pipe/open)
- *   cc artifacts remove <id>
- *   cc artifacts clean [--json]            drop expired artifacts (TTL)
+ *   cc artifacts show <id> [--json]        public metadata + integrity
+ *   cc artifacts open <id>                 audit access, then print local path
+ *   cc artifacts remove <id>               settle managed-copy removal
+ *   cc artifacts clean [--cleanup-id <id>] settle expired-artifact batch
  */
 
 import chalk from "chalk";
@@ -18,6 +18,28 @@ import {
   ArtifactStore,
   publicArtifactMetadata,
 } from "../lib/artifact-store.js";
+import {
+  ARTIFACT_ACCESS_ACTIONS,
+  ARTIFACT_ACCESS_CLIENTS,
+  authorizeArtifactContentAccess,
+  readArtifactAccessLedger,
+} from "../lib/artifact-access-ledger.js";
+import {
+  ARTIFACT_DELETION_CLIENTS,
+  readArtifactDeletionLedger,
+  settleArtifactDeletion,
+} from "../lib/artifact-deletion-ledger.js";
+import {
+  readArtifactCleanupLedger,
+  settleArtifactCleanup,
+} from "../lib/artifact-cleanup-ledger.js";
+import {
+  ARTIFACT_RECOVERY_DECISIONS,
+  adjudicateArtifactRecovery,
+  buildArtifactRecoveryPlan,
+  readArtifactOrphanGcLedger,
+} from "../lib/artifact-recovery.js";
+import { buildArtifactWorkbenchProjection } from "../lib/artifact-workbench-projection.js";
 import {
   assessDeliveryEvidence,
   createDeliveryEvidenceRecord,
@@ -58,7 +80,7 @@ export function registerArtifactsCommand(program) {
 
   cmd
     .command("show <id>")
-    .description("Show one artifact's metadata + stored path")
+    .description("Show one artifact's public metadata and integrity")
     .option("--json", "Machine-readable JSON output")
     .action((id, options) => {
       process.exitCode = runArtifactsShow(id, options);
@@ -66,28 +88,142 @@ export function registerArtifactsCommand(program) {
 
   cmd
     .command("open <id>")
-    .description("Print the artifact's stored file path (for piping/opening)")
+    .description("Authorize local content access and print the stored path")
     .action((id) => {
       process.exitCode = runArtifactsOpen(id);
     });
 
+  cmd
+    .command("access <id>")
+    .description(
+      "Authorize one official client action and record content-free access lineage",
+    )
+    .requiredOption(
+      "--client <client>",
+      `Declared client (${ARTIFACT_ACCESS_CLIENTS.join("|")})`,
+    )
+    .requiredOption(
+      "--action <action>",
+      `Requested action (${ARTIFACT_ACCESS_ACTIONS.join("|")})`,
+    )
+    .option("--access-id <id>", "Stable id for response-loss retry")
+    .option("--json", "Machine-readable authorization and local path")
+    .action((id, options) => {
+      process.exitCode = runArtifactsAccess(id, options);
+    });
+
+  cmd
+    .command("access-log")
+    .description("Verify and display the content-free artifact access ledger")
+    .option("--artifact <id>", "Only events for one artifact id")
+    .option("--json", "Machine-readable verified ledger projection")
+    .action((options) => {
+      process.exitCode = runArtifactsAccessLog(options);
+    });
+
   cmd
     .command("remove <id>")
     .alias("rm")
-    .description("Remove one artifact (stored copy + metadata)")
+    .description("Settle and audit removal of one managed artifact copy")
+    .option(
+      "--client <client>",
+      `Declared client (${ARTIFACT_DELETION_CLIENTS.join("|")})`,
+      "cli",
+    )
+    .option("--deletion-id <id>", "Stable id for response-loss recovery")
     .option("--json", "Machine-readable JSON output")
     .action((id, options) => {
       process.exitCode = runArtifactsRemove(id, options);
     });
 
+  cmd
+    .command("deletion-log")
+    .description(
+      "Verify and display the content-free deletion settlement ledger",
+    )
+    .option("--artifact <id>", "Only events for one artifact id")
+    .option("--deletion <id>", "Only events for one deletion id")
+    .option("--json", "Machine-readable verified ledger projection")
+    .action((options) => {
+      process.exitCode = runArtifactsDeletionLog(options);
+    });
+
   cmd
     .command("clean")
-    .description("Remove expired artifacts (past their TTL)")
+    .description("Settle and audit one frozen batch of expired artifacts")
+    .option(
+      "--client <client>",
+      `Declared client (${ARTIFACT_DELETION_CLIENTS.join("|")})`,
+      "cli",
+    )
+    .option("--cleanup-id <id>", "Stable batch id for response-loss recovery")
     .option("--json", "Machine-readable JSON output")
     .action((options) => {
       process.exitCode = runArtifactsClean(options);
     });
 
+  cmd
+    .command("cleanup-log")
+    .description(
+      "Verify and display the content-free cleanup settlement ledger",
+    )
+    .option("--cleanup <id>", "Only events for one cleanup id")
+    .option("--artifact <id>", "Only batches containing one artifact id")
+    .option("--json", "Machine-readable verified ledger projection")
+    .action((options) => {
+      process.exitCode = runArtifactsCleanupLog(options);
+    });
+
+  cmd
+    .command("recovery-plan")
+    .description(
+      "Inventory pending settlements and orphaned managed copies without mutating them",
+    )
+    .option(
+      "--timeout-ms <ms>",
+      "Age after which a pending settlement is reported as timed out",
+    )
+    .option("--json", "Machine-readable content-free recovery plan")
+    .action((options) => {
+      process.exitCode = runArtifactsRecoveryPlan(options);
+    });
+
+  cmd
+    .command("workbench")
+    .description(
+      "Project artifacts, returned-result lineage, history, and recovery risk for product clients",
+    )
+    .option("--json", "Machine-readable canonical workbench projection")
+    .action((options) => {
+      process.exitCode = runArtifactsWorkbench(options);
+    });
+
+  cmd
+    .command("recovery-adjudicate <item>")
+    .description(
+      "Apply one explicit, plan-bound administrator recovery decision",
+    )
+    .requiredOption("--plan-digest <digest>", "Exact recovery plan digest")
+    .requiredOption(
+      "--decision <decision>",
+      `Decision (${ARTIFACT_RECOVERY_DECISIONS.join("|")})`,
+    )
+    .option("--adjudication-id <id>", "Stable id for response-loss recovery")
+    .option("--approve", "Confirm the reviewed recovery mutation")
+    .option("--json", "Machine-readable adjudication receipt")
+    .action((item, options) => {
+      process.exitCode = runArtifactsRecoveryAdjudicate(item, options);
+    });
+
+  cmd
+    .command("orphan-gc-log")
+    .description("Verify and display the content-free orphan GC ledger")
+    .option("--adjudication <id>", "Only events for one adjudication id")
+    .option("--json", "Machine-readable verified ledger projection")
+    .action((options) => {
+      process.exitCode = runArtifactsOrphanGcLog(options);
+    });
+
   cmd
     .command("select-gates <input>")
     .description(
@@ -193,7 +329,13 @@ export function runArtifactsList(options = {}, deps = {}) {
     entries = entries.filter((e) => e.kind === String(options.kind));
   }
   if (options.json) {
-    console.log(JSON.stringify({ artifacts: entries }, null, 2));
+    console.log(
+      JSON.stringify(
+        { artifacts: entries.map(publicArtifactMetadata) },
+        null,
+        2,
+      ),
+    );
     return 0;
   }
   if (entries.length === 0) {
@@ -227,8 +369,7 @@ export function runArtifactsShow(id, options = {}, deps = {}) {
     return 1;
   }
   const payload = {
-    ...entry,
-    storedPath: store.storedPath(entry),
+    ...publicArtifactMetadata(entry),
     integrity: store.verifyIntegrity(entry),
   };
   if (options.json) {
@@ -242,44 +383,468 @@ export function runArtifactsShow(id, options = {}, deps = {}) {
 }
 
 export function runArtifactsOpen(id, deps = {}) {
+  return runArtifactsAccess(id, { client: "cli", action: "open" }, deps);
+}
+
+export function runArtifactsAccess(id, options = {}, deps = {}) {
   const store = deps.store || new ArtifactStore();
-  const entry = store.get(id);
-  if (!entry) {
-    console.error(chalk.red(`No artifact with id "${id}".`));
+  try {
+    const authorization = (
+      deps.authorizeArtifactContentAccess || authorizeArtifactContentAccess
+    )(
+      store,
+      {
+        artifactId: id,
+        client: options.client,
+        action: options.action,
+        accessId: options.accessId,
+      },
+      deps.accessOptions || {},
+    );
+    const payload = {
+      schema: "cc-artifact-content-access-authorization/v1",
+      access: authorization.access,
+      recorded: authorization.recorded,
+      storedPath: authorization.storedPath,
+      integrity: authorization.integrity,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(authorization.storedPath);
+    }
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-content-access-authorization-error/v1",
+          authorized: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(chalk.red(`Artifact access failed: ${error.message}`));
+    }
+    return 1;
+  }
+}
+
+export function runArtifactsAccessLog(options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    const ledger = (deps.readArtifactAccessLedger || readArtifactAccessLedger)(
+      store,
+      deps.accessOptions || {},
+    );
+    const events = options.artifact
+      ? ledger.events.filter(
+          (event) => event.artifactId === String(options.artifact),
+        )
+      : ledger.events;
+    const projection = {
+      ...ledger,
+      filtered: Boolean(options.artifact),
+      matchedEventCount: events.length,
+      events,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+    } else if (events.length === 0) {
+      console.log(chalk.dim("No artifact content access events."));
+    } else {
+      for (const event of events) {
+        console.log(
+          `${chalk.cyan(event.sequence)}  ${event.artifactId}  ${event.client}/${event.action}  ${event.authorizedAt}  ${event.eventDigest}`,
+        );
+      }
+    }
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-content-access-ledger-error/v1",
+          verified: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(chalk.red(`Artifact access log failed: ${error.message}`));
+    }
     return 1;
   }
-  console.log(store.storedPath(entry));
-  return 0;
 }
 
 export function runArtifactsRemove(id, options = {}, deps = {}) {
   const store = deps.store || new ArtifactStore();
-  const found = store.remove(id);
-  if (options.json) {
-    console.log(JSON.stringify({ removed: found ? id : null, found }));
-    return found ? 0 : 1;
+  const deletionId = String(
+    options.deletionId || `delete_${randomUUID().replaceAll("-", "")}`,
+  );
+  try {
+    const result = (deps.settleArtifactDeletion || settleArtifactDeletion)(
+      store,
+      {
+        deletionId,
+        artifactId: id,
+        reason: "explicit",
+        client: options.client || "cli",
+      },
+      deps.deletionOptions || {},
+    );
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return result.found ? 0 : 1;
+    }
+    if (!result.found) {
+      console.error(chalk.red(`No artifact with id "${id}".`));
+      return 1;
+    }
+    console.log(
+      chalk.green(`Removed managed copy ${id} (deletion ${deletionId}).`),
+    );
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-deletion-error/v1",
+          deletionId: error.deletionId || deletionId,
+          artifactId: String(id),
+          settled: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(
+          `Artifact removal ${error.deletionId || deletionId} is not settled: ${error.message}`,
+        ),
+      );
+    }
+    return 1;
   }
-  if (!found) {
-    console.error(chalk.red(`No artifact with id "${id}".`));
+}
+
+export function runArtifactsDeletionLog(options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    const ledger = (
+      deps.readArtifactDeletionLedger || readArtifactDeletionLedger
+    )(store, deps.deletionOptions || {});
+    const events = ledger.events.filter(
+      (event) =>
+        (!options.artifact || event.artifactId === String(options.artifact)) &&
+        (!options.deletion || event.deletionId === String(options.deletion)),
+    );
+    const projection = {
+      ...ledger,
+      filtered: Boolean(options.artifact || options.deletion),
+      matchedEventCount: events.length,
+      events,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+    } else if (events.length === 0) {
+      console.log(chalk.dim("No artifact deletion settlement events."));
+    } else {
+      for (const event of events) {
+        console.log(
+          `${event.sequence}\t${event.phase}\t${event.artifactId}\t${event.deletionId}\t${event.eventDigest}`,
+        );
+      }
+    }
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-deletion-ledger-error/v1",
+          verified: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(`Artifact deletion log failed: ${error.message}`),
+      );
+    }
     return 1;
   }
-  console.log(chalk.green(`Removed ${id}.`));
-  return 0;
 }
 
 export function runArtifactsClean(options = {}, deps = {}) {
   const store = deps.store || new ArtifactStore();
-  const { removed } = store.cleanupExpired();
-  if (options.json) {
-    console.log(JSON.stringify({ removed }));
+  const cleanupId = String(
+    options.cleanupId || `cleanup_${randomUUID().replaceAll("-", "")}`,
+  );
+  try {
+    const result = (deps.settleArtifactCleanup || settleArtifactCleanup)(
+      store,
+      {
+        cleanupId,
+        client: options.client || "cli",
+      },
+      deps.cleanupOptions || {},
+    );
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    console.log(
+      result.removed > 0
+        ? chalk.green(
+            `Settled cleanup ${cleanupId}: removed ${result.removed} expired artifact(s).`,
+          )
+        : chalk.dim(`Settled cleanup ${cleanupId}: nothing expired.`),
+    );
     return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-cleanup-error/v1",
+          cleanupId: error.cleanupId || cleanupId,
+          settled: false,
+          ...(error.cleanup ? { cleanup: error.cleanup } : {}),
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(
+          `Artifact cleanup ${error.cleanupId || cleanupId} is not settled: ${error.message}`,
+        ),
+      );
+    }
+    return 1;
+  }
+}
+
+export function runArtifactsCleanupLog(options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    const ledger = (
+      deps.readArtifactCleanupLedger || readArtifactCleanupLedger
+    )(store, deps.cleanupOptions || {});
+    const events = ledger.events.filter(
+      (event) =>
+        (!options.cleanup || event.cleanupId === String(options.cleanup)) &&
+        (!options.artifact ||
+          event.items.some(
+            (item) => item.artifactId === String(options.artifact),
+          )),
+    );
+    const projection = {
+      ...ledger,
+      filtered: Boolean(options.cleanup || options.artifact),
+      matchedEventCount: events.length,
+      events,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+    } else if (events.length === 0) {
+      console.log(chalk.dim("No artifact cleanup settlement events."));
+    } else {
+      for (const event of events) {
+        console.log(
+          `${event.sequence}\t${event.phase}\t${event.itemCount}\t${event.cleanupId}\t${event.eventDigest}`,
+        );
+      }
+    }
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-cleanup-ledger-error/v1",
+          verified: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(chalk.red(`Artifact cleanup log failed: ${error.message}`));
+    }
+    return 1;
+  }
+}
+
+export function runArtifactsRecoveryPlan(options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    const parsedTimeout =
+      options.timeoutMs == null ? undefined : Number(options.timeoutMs);
+    const plan = (deps.buildArtifactRecoveryPlan || buildArtifactRecoveryPlan)(
+      store,
+      {
+        ...(parsedTimeout == null ? {} : { timeoutMs: parsedTimeout }),
+        ...(deps.recoveryOptions || {}),
+      },
+    );
+    if (options.json) {
+      console.log(JSON.stringify(plan, null, 2));
+    } else if (plan.items.length === 0) {
+      console.log(
+        chalk.dim(`Artifact recovery is clear (${plan.planDigest}).`),
+      );
+    } else {
+      console.log(
+        chalk.yellow(
+          `Artifact recovery requires review: ${plan.summary.itemCount} item(s), ${plan.summary.criticalCount} critical (${plan.planDigest}).`,
+        ),
+      );
+      for (const item of plan.items) {
+        console.log(
+          `${item.severity}\t${item.kind}\t${item.recommendedDecision}\t${item.itemId}`,
+        );
+      }
+    }
+    return plan.summary.itemCount > 0 ? 2 : 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-recovery-plan-error/v1",
+          verified: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(`Artifact recovery inventory failed: ${error.message}`),
+      );
+    }
+    return 1;
+  }
+}
+
+export function runArtifactsWorkbench(options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    const projection = (
+      deps.buildArtifactWorkbenchProjection || buildArtifactWorkbenchProjection
+    )(store, deps.workbenchOptions || {});
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+    } else {
+      console.log(
+        `${projection.artifacts.length} artifact(s); ${projection.recovery.summary.itemCount} recovery item(s); ${projection.history.totalEventCount} history event(s).`,
+      );
+      console.log(chalk.dim(projection.recovery.planDigest));
+    }
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-workbench-error/v1",
+          verified: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(`Artifact workbench projection failed: ${error.message}`),
+      );
+    }
+    return 1;
+  }
+}
+
+export function runArtifactsRecoveryAdjudicate(item, options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    if (options.decision !== "defer" && options.approve !== true) {
+      throw new Error("recovery mutation requires explicit --approve");
+    }
+    const result = (
+      deps.adjudicateArtifactRecovery || adjudicateArtifactRecovery
+    )(
+      store,
+      {
+        itemId: item,
+        planDigest: options.planDigest,
+        decision: options.decision,
+        adjudicationId: options.adjudicationId,
+      },
+      deps.recoveryOptions || {},
+    );
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(
+        result.settled
+          ? chalk.green(
+              `Artifact recovery adjudication ${result.adjudicationId || options.adjudicationId || ""} settled.`,
+            )
+          : chalk.dim("Artifact recovery item was deferred without mutation."),
+      );
+    }
+    return result.settled || options.decision === "defer" ? 0 : 1;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-recovery-adjudication-error/v1",
+          itemId: String(item),
+          settled: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(`Artifact recovery adjudication failed: ${error.message}`),
+      );
+    }
+    return 1;
+  }
+}
+
+export function runArtifactsOrphanGcLog(options = {}, deps = {}) {
+  const store = deps.store || new ArtifactStore();
+  try {
+    const ledger = (
+      deps.readArtifactOrphanGcLedger || readArtifactOrphanGcLedger
+    )(store, deps.recoveryOptions || {});
+    const events = ledger.events.filter(
+      (event) =>
+        !options.adjudication ||
+        event.adjudicationId === String(options.adjudication),
+    );
+    const projection = {
+      ...ledger,
+      filtered: Boolean(options.adjudication),
+      matchedEventCount: events.length,
+      events,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+    } else if (events.length === 0) {
+      console.log(chalk.dim("No artifact orphan GC settlement events."));
+    } else {
+      for (const event of events) {
+        console.log(
+          `${event.sequence}\t${event.phase}\t${event.outcome}\t${event.adjudicationId}\t${event.eventDigest}`,
+        );
+      }
+    }
+    return 0;
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          schema: "cc-artifact-orphan-gc-ledger-error/v1",
+          verified: false,
+          error: error.message,
+        }),
+      );
+    } else {
+      console.error(
+        chalk.red(`Artifact orphan GC log failed: ${error.message}`),
+      );
+    }
+    return 1;
   }
-  console.log(
-    removed > 0
-      ? chalk.green(`Removed ${removed} expired artifact(s).`)
-      : chalk.dim("Nothing expired."),
-  );
-  return 0;
 }
 
 function readJsonFile(inputPath, deps = {}) {