artshelf 0.4.1 → 0.6.0

package/docs/reference.html

@@ -138,18 +138,24 @@ artshelf get &lt;id&gt; --all --json</code></pre>
             <section>
               <h2>Storage</h2>
               <p>
-                Inside a git repo, Artshelf defaults to `.shelf/ledger.jsonl`. Outside a repo, it
-                defaults to `~/.shelf/ledger.jsonl`. Pass `--ledger &lt;path&gt;` for tests, demos,
+                Inside a git repo, Artshelf defaults to `.artshelf/ledger.jsonl`. Outside a repo, it
+                defaults to `~/.artshelf/ledger.jsonl`. Pass `--ledger &lt;path&gt;` for tests, demos,
                 and controlled smoke runs.
               </p>
               <p>
-                Artshelf also keeps a user-level registry at `~/.shelf/ledgers.json`. Override it
+                Artshelf also keeps a user-level registry at `~/.artshelf/ledgers.json`. Override it
                 with <code>--registry &lt;path&gt;</code> or <code>ARTSHELF_REGISTRY</code>; legacy
                 <code>SHELF_REGISTRY</code> is used only when <code>ARTSHELF_REGISTRY</code> is unset.
                 The registry is a discovery index for supported `--all` review, status, cleanup
                 dry-run, and trash-list commands; project records stay in their own repo-local ledgers.
               </p>
-              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.shelf/ledger.jsonl --name &lt;project&gt; --scope repo
+              <p>
+                Renamed installs before <code>0.5.0</code> used <code>.shelf</code> paths. Copy those
+                ledgers into <code>.artshelf</code>, rewrite registry paths, validate with
+                <code>artshelf ledgers list --json</code>, and keep the old directories until rollback
+                is no longer needed.
+              </p>
+              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
 artshelf review --all --json
 artshelf status --all --json
 artshelf cleanup --dry-run --all --json

package/docs/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/examples/artshelf-review-report.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "scope": {
+    "registryPath": "~/.artshelf/ledgers.json",
+    "ledgerCount": 3,
+    "health": "attention",
+    "registryHealth": "ok",
+    "affectedLedgers": [
+      {
+        "name": "example-project",
+        "ledgerPath": "/path/to/example-project/.artshelf/ledger.jsonl",
+        "validationStatus": "ok"
+      }
+    ]
+  },
+  "plans": [
+    {
+      "type": "cleanup",
+      "ledgerPath": "/path/to/example-project/.artshelf/ledger.jsonl",
+      "planId": "plan_20260606_120000_ab12",
+      "planPath": "/path/to/example-project/.artshelf/plans/plan_20260606_120000_ab12.json",
+      "approvalTarget": "approve artshelf cleanup ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_120000_ab12"
+    }
+  ],
+  "summary": {
+    "executable": 1,
+    "skipped": 2,
+    "refused": 0,
+    "manualReview": 1,
+    "missingPath": 1,
+    "trashed": 0
+  },
+  "decisionSummary": {
+    "readyForApproval": 2,
+    "needsReviewFirst": 1,
+    "blocked": 0
+  },
+  "decisionGroups": {
+    "readyForApproval": [
+      {
+        "label": "Clean up temp debug output",
+        "itemIds": ["shf_20260606_120000_ab12"],
+        "actionType": "cleanup",
+        "approvalTarget": "approve artshelf cleanup ledger /path/to/example-project/.artshelf/ledger.jsonl plan plan_20260606_120000_ab12",
+        "reason": "Disposable temp artifact has a reviewed cleanup plan.",
+        "nextStep": "Approve the exact cleanup plan to move the artifact into Artshelf trash."
+      },
+      {
+        "label": "Resolve missing report record",
+        "itemIds": ["shf_20260606_120500_cd34"],
+        "actionType": "resolve-missing",
+        "approvalTarget": "approve artshelf resolve missing ledger /path/to/example-project/.artshelf/ledger.jsonl ids shf_20260606_120500_cd34",
+        "reason": "The report path is already missing.",
+        "nextStep": "Approve the ledger-only resolve command after confirming the report is no longer needed."
+      }
+    ],
+    "needsReviewFirst": [
+      {
+        "label": "Inspect lifecycle smoke report",
+        "itemIds": ["shf_20260606_121000_ef56"],
+        "actionType": "inspect",
+        "approvalTarget": null,
+        "reason": "cleanup=review means the artifact should be inspected before closing.",
+        "nextStep": "Inspect the path, then choose keep, change retention, resolve, or clean up later."
+      }
+    ],
+    "blocked": []
+  },
+  "recommendation": "Approve the reviewed cleanup plan for the disposable temp directory, then resolve the missing record after confirming it is no longer needed.",
+  "items": [
+    {
+      "id": "shf_20260606_120000_ab12",
+      "path": "/tmp/example-debug-output",
+      "classification": "trash-safe",
+      "proposedAction": "execute reviewed cleanup plan",
+      "dueStatus": "due",
+      "reason": "temporary debug output retained for 3 days",
+      "note": "The path exists, cleanup=trash, and the dry-run plan moves it into Artshelf trash."
+    },
+    {
+      "id": "shf_20260606_120500_cd34",
+      "path": "/tmp/missing-report.json",
+      "classification": "resolve-candidate",
+      "proposedAction": "resolve ledger-only after confirmation",
+      "dueStatus": "missing-path",
+      "reason": "report path is already missing",
+      "note": "Resolution updates only the ledger and does not move or delete files."
+    },
+    {
+      "id": "shf_20260606_121000_ef56",
+      "path": "/tmp/lifecycle-smoke-report.json",
+      "classification": "needs-human-review",
+      "proposedAction": "inspect before choosing cleanup or retention",
+      "dueStatus": "manual-review",
+      "reason": "cleanup=review artifact retained for manual inspection",
+      "note": "No approval target is shown until the review decision is known."
+    }
+  ],
+  "alternatives": [
+    "keep the artifact and change retention",
+    "inspect the path before approving cleanup",
+    "regenerate the plan after edits",
+    "resolve missing records ledger-only"
+  ],
+  "safety": {
+    "dryRunOnly": true,
+    "executeAllRefused": true,
+    "noExecuteRan": true,
+    "noResolveRan": true,
+    "noDeleteRan": true
+  },
+  "verification": {
+    "command": "artshelf review --all --json",
+    "successCondition": "no due, manual-review, missing-path, executable, or refused entries remain unless explicitly reported"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",
@@ -28,6 +28,8 @@
   "files": [
     "dist/src",
     "docs",
+    "schemas",
+    "examples",
     "skills",
     "CHANGELOG.md",
     "LICENSE",