artshelf 0.5.0 → 0.7.0

package/skills/artshelf/schemas/artshelf-review-report.schema.json

@@ -0,0 +1,315 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://calvinnwq.github.io/artshelf/schemas/artshelf-review-report.schema.json",
+  "title": "ArtshelfReviewReport",
+  "description": "Machine-readable decision packet for rendering an Artshelf review report.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "scope",
+    "decisionSummary",
+    "decisionGroups",
+    "summary",
+    "recommendation",
+    "items",
+    "alternatives",
+    "safety",
+    "verification"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["registryPath", "ledgerCount", "health", "registryHealth"],
+      "properties": {
+        "registryPath": { "type": "string" },
+        "ledgerCount": { "type": "integer", "minimum": 0 },
+        "health": { "type": "string", "enum": ["ok", "attention"] },
+        "registryHealth": { "type": "string", "enum": ["ok", "attention"] },
+        "affectedLedgers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["ledgerPath"],
+            "properties": {
+              "name": { "type": "string" },
+              "ledgerPath": { "type": "string" },
+              "validationStatus": {
+                "type": "string",
+                "enum": ["ok", "missing", "invalid"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "plans": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/plan" },
+      "default": []
+    },
+    "decisionSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["readyForApproval", "needsReviewFirst", "blocked"],
+      "properties": {
+        "readyForApproval": { "type": "integer", "minimum": 0 },
+        "needsReviewFirst": { "type": "integer", "minimum": 0 },
+        "blocked": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "decisionGroups": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["readyForApproval", "needsReviewFirst", "blocked"],
+      "properties": {
+        "readyForApproval": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/approvalDecision" }
+        },
+        "needsReviewFirst": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/nonApprovalDecision" }
+        },
+        "blocked": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/nonApprovalDecision" }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "executable",
+        "skipped",
+        "refused",
+        "manualReview",
+        "missingPath",
+        "trashed"
+      ],
+      "properties": {
+        "executable": { "type": "integer", "minimum": 0 },
+        "skipped": { "type": "integer", "minimum": 0 },
+        "refused": { "type": "integer", "minimum": 0 },
+        "manualReview": { "type": "integer", "minimum": 0 },
+        "missingPath": { "type": "integer", "minimum": 0 },
+        "trashed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "recommendation": { "type": "string", "minLength": 1 },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/item" }
+    },
+    "alternatives": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "safety": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "dryRunOnly",
+        "executeAllRefused",
+        "noExecuteRan",
+        "noResolveRan",
+        "noDeleteRan"
+      ],
+      "properties": {
+        "dryRunOnly": { "type": "boolean" },
+        "executeAllRefused": { "type": "boolean" },
+        "noExecuteRan": { "type": "boolean" },
+        "noResolveRan": { "type": "boolean" },
+        "noDeleteRan": { "type": "boolean" }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "successCondition"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "successCondition": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "$defs": {
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "ledgerPath", "planId", "approvalTarget"],
+      "properties": {
+        "type": { "type": "string", "enum": ["cleanup", "trash-purge"] },
+        "ledgerPath": { "type": "string" },
+        "planId": { "type": "string" },
+        "planPath": { "type": ["string", "null"] },
+        "approvalTarget": { "type": "string" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "cleanup" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf cleanup ledger .+ plan .+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "trash-purge" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf trash purge ledger .+ plan .+$"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "classification",
+        "proposedAction",
+        "dueStatus",
+        "reason",
+        "note"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "classification": {
+          "type": "string",
+          "enum": [
+            "trash-safe",
+            "needs-human-review",
+            "resolve-candidate",
+            "registry-problem"
+          ]
+        },
+        "proposedAction": { "type": "string", "minLength": 1 },
+        "dueStatus": {
+          "type": "string",
+          "enum": ["kept", "due", "manual-review", "missing-path", "trashed"]
+        },
+        "reason": { "type": "string", "minLength": 1 },
+        "note": { "type": "string", "minLength": 1 }
+      },
+      "anyOf": [
+        { "required": ["id"] },
+        { "required": ["path"] }
+      ]
+    },
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "actionType", "reason", "nextStep"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "itemIds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": []
+        },
+        "actionType": {
+          "type": "string",
+          "enum": [
+            "cleanup",
+            "trash-purge",
+            "resolve-missing",
+            "inspect",
+            "fix-registry",
+            "keep-or-snooze",
+            "change-retention"
+          ]
+        },
+        "approvalTarget": { "type": ["string", "null"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "nextStep": { "type": "string", "minLength": 1 }
+      }
+    },
+    "approvalDecision": {
+      "allOf": [
+        { "$ref": "#/$defs/decision" },
+        {
+          "required": ["approvalTarget"],
+          "properties": {
+            "actionType": {
+              "enum": ["cleanup", "trash-purge", "resolve-missing"]
+            },
+            "approvalTarget": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "if": {
+            "properties": { "actionType": { "const": "cleanup" } },
+            "required": ["actionType"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf cleanup ledger .+ plan .+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "actionType": { "const": "trash-purge" } },
+            "required": ["actionType"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf trash purge ledger .+ plan .+$"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "actionType": { "const": "resolve-missing" } },
+            "required": ["actionType"]
+          },
+          "then": {
+            "properties": {
+              "approvalTarget": {
+                "pattern": "^approve artshelf resolve missing ledger .+ ids .+$"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "nonApprovalDecision": {
+      "allOf": [
+        { "$ref": "#/$defs/decision" },
+        {
+          "properties": {
+            "actionType": {
+              "enum": ["inspect", "fix-registry", "keep-or-snooze", "change-retention"]
+            },
+            "approvalTarget": { "type": "null" }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/artshelf/scripts/render-review-report.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const APPROVAL_ACTIONS = new Set(["cleanup", "trash-purge", "resolve-missing"]);
+const NON_APPROVAL_ACTIONS = new Set(["inspect", "fix-registry", "keep-or-snooze", "change-retention"]);
+const APPROVAL_TARGET_PATTERNS = {
+  cleanup: /^approve artshelf cleanup ledger .+ plan .+$/,
+  "trash-purge": /^approve artshelf trash purge ledger .+ plan .+$/,
+  "resolve-missing": /^approve artshelf resolve missing ledger .+ ids .+$/
+};
+
+function readInput() {
+  const path = process.argv[2];
+  if (path && path !== "-") {
+    return readFileSync(path, "utf8");
+  }
+  return readFileSync(0, "utf8");
+}
+
+function lineForEmpty(value) {
+  return value.length === 0 ? "<none>" : null;
+}
+
+function formatApprovalDecision(decision, index) {
+  const lines = [
+    `${index + 1}. ${decision.label}`,
+    `   Why: ${decision.reason}`,
+    `   Action: ${decision.nextStep}`,
+    `   ${decision.approvalTarget}`
+  ];
+  return lines.join("\n");
+}
+
+function formatNonApprovalDecision(decision, index) {
+  return [
+    `${index + 1}. ${decision.label}`,
+    `   Why: ${decision.reason}`,
+    `   Suggested next step: ${decision.nextStep}`
+  ].join("\n");
+}
+
+function formatGroup(title, decisions, formatter) {
+  const empty = lineForEmpty(decisions);
+  return [
+    title,
+    empty ?? decisions.map((decision, index) => formatter(decision, index)).join("\n\n")
+  ].join("\n");
+}
+
+function requireBoolean(report, path) {
+  const value = path.reduce((current, key) => current?.[key], report);
+  if (typeof value !== "boolean") {
+    throw new Error(`missing boolean ${path.join(".")}`);
+  }
+  return value;
+}
+
+function requireArray(report, path) {
+  const value = path.reduce((current, key) => current?.[key], report);
+  if (!Array.isArray(value)) {
+    throw new Error(`missing array ${path.join(".")}`);
+  }
+  return value;
+}
+
+function requireString(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`missing string ${path}`);
+  }
+  return value;
+}
+
+function requireActionType(value, allowed, path) {
+  const actionType = requireString(value, path);
+  if (!allowed.has(actionType)) {
+    throw new Error(`unsupported actionType ${path}`);
+  }
+  return actionType;
+}
+
+function validateDecision(decision, path, allowedActions) {
+  if (!decision || typeof decision !== "object" || Array.isArray(decision)) {
+    throw new Error(`missing object ${path}`);
+  }
+  requireString(decision.label, `${path}.label`);
+  requireActionType(decision.actionType, allowedActions, `${path}.actionType`);
+  requireString(decision.reason, `${path}.reason`);
+  requireString(decision.nextStep, `${path}.nextStep`);
+  return decision;
+}
+
+function validateApprovalDecision(decision, index) {
+  const path = `decisionGroups.readyForApproval.${index}`;
+  validateDecision(decision, path, APPROVAL_ACTIONS);
+  const approvalTarget = requireString(decision.approvalTarget, `${path}.approvalTarget`);
+  if (!APPROVAL_TARGET_PATTERNS[decision.actionType].test(approvalTarget)) {
+    throw new Error(`invalid approvalTarget ${path}.approvalTarget`);
+  }
+  return decision;
+}
+
+function validateNonApprovalDecision(group, decision, index) {
+  return validateDecision(decision, `decisionGroups.${group}.${index}`, NON_APPROVAL_ACTIONS);
+}
+
+export function renderReviewReport(report) {
+  if (report?.schemaVersion !== 1) {
+    throw new Error("unsupported ArtshelfReviewReport schemaVersion");
+  }
+
+  const scope = report.scope ?? {};
+  const ready = requireArray(report, ["decisionGroups", "readyForApproval"]).map(validateApprovalDecision);
+  const needsReview = requireArray(report, ["decisionGroups", "needsReviewFirst"])
+    .map((decision, index) => validateNonApprovalDecision("needsReviewFirst", decision, index));
+  const blocked = requireArray(report, ["decisionGroups", "blocked"])
+    .map((decision, index) => validateNonApprovalDecision("blocked", decision, index));
+  const recommendation = requireString(report.recommendation, "recommendation");
+
+  const dryRunOnly = requireBoolean(report, ["safety", "dryRunOnly"]);
+  const executeAllRefused = requireBoolean(report, ["safety", "executeAllRefused"]);
+  const noExecuteRan = requireBoolean(report, ["safety", "noExecuteRan"]);
+  const noResolveRan = requireBoolean(report, ["safety", "noResolveRan"]);
+  const noDeleteRan = requireBoolean(report, ["safety", "noDeleteRan"]);
+  const safetyLine = dryRunOnly && executeAllRefused && noExecuteRan && noResolveRan && noDeleteRan
+    ? "Dry-run only. No execute, resolve, or delete ran."
+    : "Attention: safety flags show a mutation may have run.";
+
+  return [
+    "Artshelf daily review",
+    `Status: ${scope.health ?? "attention"}; registry ${scope.registryHealth ?? "attention"}`,
+    "",
+    `Ready for approval: ${ready.length}`,
+    `Needs review first: ${needsReview.length}`,
+    `Blocked: ${blocked.length}`,
+    "",
+    "Recommended action",
+    recommendation,
+    "",
+    formatGroup("Ready for approval", ready, formatApprovalDecision),
+    "",
+    formatGroup("Needs review first", needsReview, formatNonApprovalDecision),
+    "",
+    formatGroup("Blocked", blocked, formatNonApprovalDecision),
+    "",
+    "Safety",
+    safetyLine
+  ].join("\n");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const report = JSON.parse(readInput());
+    process.stdout.write(`${renderReviewReport(report)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/docs/theme.js

@@ -1,42 +0,0 @@
-(function () {
-  const storageKey = "artshelf-docs-theme";
-  const root = document.documentElement;
-  const systemDark = window.matchMedia("(prefers-color-scheme: dark)");
-  const toggleIcon = `
-    <svg class="theme-icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"></path></svg>
-    <svg class="theme-icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"></circle><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"></line><line x1="10" y1="16" x2="10" y2="18"></line><line x1="2" y1="10" x2="4" y2="10"></line><line x1="16" y1="10" x2="18" y2="10"></line><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"></line><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"></line><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"></line><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"></line></g></svg>
-  `;
-
-  function preferredTheme() {
-    const saved = window.localStorage.getItem(storageKey);
-    if (saved === "light" || saved === "dark") return saved;
-    return systemDark.matches ? "dark" : "light";
-  }
-
-  function applyTheme(theme) {
-    root.dataset.theme = theme;
-    root.style.colorScheme = theme;
-    document.querySelectorAll("[data-theme-toggle]").forEach((button) => {
-      button.setAttribute("aria-pressed", theme === "dark" ? "true" : "false");
-      button.setAttribute("title", theme === "dark" ? "Switch to light mode" : "Switch to dark mode");
-      if (button.innerHTML !== toggleIcon) button.innerHTML = toggleIcon;
-    });
-  }
-
-  applyTheme(preferredTheme());
-
-  window.addEventListener("DOMContentLoaded", () => {
-    applyTheme(preferredTheme());
-    document.querySelectorAll("[data-theme-toggle]").forEach((button) => {
-      button.addEventListener("click", () => {
-        const nextTheme = root.dataset.theme === "dark" ? "light" : "dark";
-        window.localStorage.setItem(storageKey, nextTheme);
-        applyTheme(nextTheme);
-      });
-    });
-  });
-
-  systemDark.addEventListener("change", () => {
-    if (!window.localStorage.getItem(storageKey)) applyTheme(preferredTheme());
-  });
-})();