@hollware/core 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -439,7 +439,7 @@ export declare const DEFAULT_MAX_MARKDOWN_BYTES = 524288;
  */
 export declare const MAX_MARKDOWN_BYTES_CEILING = 786432;
 declare namespace schemas_d_exports {
-  export { acknowledgedWarning, collectionDescription, collectionName, componentDescription, conflict, contractDescription, document, entry, entryId, entryStatus, entrySummary, format, locale, markdown, phase, publication, review, reviewId, reviewStatus, revisionId, searchMode, severity, siteDescription, slug, verdict, version, violation };
+  export { acknowledgedWarning, collectionDescription, collectionName, componentDescription, conflict, contractDescription, document, entry, entryId, entryStatus, entrySummary, format, locale, markdown, phase, publication, review, reviewComment, reviewId, reviewStatus, revisionId, searchMode, severity, siteDescription, slug, verdict, version, violation };
 }
 /**
  * The pieces the operation schemas share. Their descriptions become the JSON Schema that agents
@@ -694,6 +694,15 @@ declare const review: z.ZodObject<{
   decidedAt: z.ZodNullable<z.ZodString>;
   note: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/** A comment on a review (v0.6), by a person or by the agent of one. */
+declare const reviewComment: z.ZodObject<{
+  id: z.ZodString;
+  author: z.ZodString;
+  authorName: z.ZodNullable<z.ZodString>;
+  client: z.ZodNullable<z.ZodString>;
+  body: z.ZodString;
+  at: z.ZodString;
+}, z.core.$strip>;
 declare const conflict: z.ZodObject<{
   currentVersion: z.ZodNumber;
   headRevision: z.ZodString;
@@ -1064,6 +1073,7 @@ export declare const ID_PREFIXES: {
   readonly revision: 'rev';
   readonly revisionTag: 'tag';
   readonly review: 'rvw';
+  readonly reviewComment: 'rvc';
   readonly schedule: 'sch';
   readonly session: 'ses';
   readonly token: 'tok';
@@ -1772,6 +1782,14 @@ export declare const listReviews: OperationSpec<"list_reviews", z.ZodObject<{
       publishedAt: z.ZodNullable<z.ZodString>;
       updatedAt: z.ZodString;
     }, z.core.$strip>;
+    comments: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      author: z.ZodString;
+      authorName: z.ZodNullable<z.ZodString>;
+      client: z.ZodNullable<z.ZodString>;
+      body: z.ZodString;
+      at: z.ZodString;
+    }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
 export declare const approveReview: OperationSpec<"approve_review", z.ZodObject<{
@@ -1854,6 +1872,109 @@ export declare const approveReview: OperationSpec<"approve_review", z.ZodObject<
     contractsHash: z.ZodString;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
+export declare const requestReview: OperationSpec<"request_review", z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodNumber;
+  acknowledgeWarnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    contract: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    blocked: "blocked";
+    conflict: "conflict";
+    needs_acknowledgement: "needs_acknowledgement";
+    not_found: "not_found";
+    pending_review: "pending_review";
+  }>;
+  entry: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>;
+  verdict: z.ZodOptional<z.ZodObject<{
+    ok: z.ZodBoolean;
+    phase: z.ZodEnum<{
+      publish: "publish";
+      write: "write";
+    }>;
+    errors: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contractsHash: z.ZodString;
+  }, z.core.$strip>>;
+  conflict: z.ZodOptional<z.ZodObject<{
+    currentVersion: z.ZodNumber;
+    headRevision: z.ZodString;
+  }, z.core.$strip>>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const commentReview: OperationSpec<"comment_review", z.ZodObject<{
+  id: z.ZodString;
+  body: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    commented: "commented";
+    not_found: "not_found";
+    not_pending: "not_pending";
+  }>;
+  comment: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    author: z.ZodString;
+    authorName: z.ZodNullable<z.ZodString>;
+    client: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+    at: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
 export declare const requestChanges: OperationSpec<"request_changes", z.ZodObject<{
   id: z.ZodString;
   note: z.ZodString;
@@ -1993,6 +2114,23 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     }, z.core.$strip>>;
     contractsHash: z.ZodString;
   }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"comment_review", z.ZodObject<{
+  id: z.ZodString;
+  body: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    commented: "commented";
+    not_found: "not_found";
+    not_pending: "not_pending";
+  }>;
+  comment: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    author: z.ZodString;
+    authorName: z.ZodNullable<z.ZodString>;
+    client: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+    at: z.ZodString;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"content_stats", z.ZodObject<{
   days: z.ZodDefault<z.ZodNumber>;
   limit: z.ZodDefault<z.ZodNumber>;
@@ -2354,6 +2492,14 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
       publishedAt: z.ZodNullable<z.ZodString>;
       updatedAt: z.ZodString;
     }, z.core.$strip>;
+    comments: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      author: z.ZodString;
+      authorName: z.ZodNullable<z.ZodString>;
+      client: z.ZodNullable<z.ZodString>;
+      body: z.ZodString;
+      at: z.ZodString;
+    }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"publish", z.ZodObject<{
   id: z.ZodString;
@@ -2473,6 +2619,90 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     decidedAt: z.ZodNullable<z.ZodString>;
     note: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"request_review", z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodNumber;
+  acknowledgeWarnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    contract: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    blocked: "blocked";
+    conflict: "conflict";
+    needs_acknowledgement: "needs_acknowledgement";
+    not_found: "not_found";
+    pending_review: "pending_review";
+  }>;
+  entry: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>;
+  verdict: z.ZodOptional<z.ZodObject<{
+    ok: z.ZodBoolean;
+    phase: z.ZodEnum<{
+      publish: "publish";
+      write: "write";
+    }>;
+    errors: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contractsHash: z.ZodString;
+  }, z.core.$strip>>;
+  conflict: z.ZodOptional<z.ZodObject<{
+    currentVersion: z.ZodNumber;
+    headRevision: z.ZodString;
+  }, z.core.$strip>>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"search", z.ZodObject<{
   query: z.ZodString;
   collection: z.ZodOptional<z.ZodString>;

package/dist/index.mjs

@@ -1712,6 +1712,7 @@ const ID_PREFIXES = {
 	revision: "rev",
 	revisionTag: "tag",
 	review: "rvw",
+	reviewComment: "rvc",
 	schedule: "sch",
 	session: "ses",
 	token: "tok",
@@ -3050,6 +3051,7 @@ var schemas_exports = /* @__PURE__ */ __exportAll({
 	phase: () => phase,
 	publication: () => publication,
 	review: () => review,
+	reviewComment: () => reviewComment,
 	reviewId: () => reviewId,
 	reviewStatus: () => reviewStatus,
 	revisionId: () => revisionId,
@@ -3155,6 +3157,15 @@ const review = z.object({
 	decidedAt: z.string().nullable(),
 	note: z.string().nullable().describe("What the reviewer asked to change, or null.")
 });
+/** A comment on a review (v0.6), by a person or by the agent of one. */
+const reviewComment = z.object({
+	id: z.string(),
+	author: z.string().describe("The user who wrote it, or whose token their agent used."),
+	authorName: z.string().nullable(),
+	client: z.string().nullable().describe("The name the client gave, such as hollware-agents for the agents; null for none."),
+	body: z.string(),
+	at: z.string()
+});
 const conflict = z.object({
 	currentVersion: z.number().int().min(1),
 	headRevision: revisionId
@@ -3454,7 +3465,10 @@ const listReviews = defineOperation({
 	}),
 	output: z.object({
 		outcome: z.enum(["ok"]),
-		reviews: z.array(review.extend({ entry: entrySummary }))
+		reviews: z.array(review.extend({
+			entry: entrySummary,
+			comments: z.array(reviewComment).describe("What was said about it, oldest first.")
+		}))
 	}),
 	scopes: ["content:read"],
 	effect: "read",
@@ -3490,6 +3504,62 @@ const approveReview = defineOperation({
 		not_found: { isError: true }
 	}
 });
+const requestReview = defineOperation({
+	name: "request_review",
+	title: "Ask for a review",
+	description: "Asks a person who may publish to review the latest revision of an entry, after the same checks publish makes, if the entry is still at the version you read. It never publishes, whatever your scopes: the answer is pending_review, or why not (blocked by the contracts, warnings to acknowledge, a conflict). A new revision of the entry cancels the request.",
+	input: z.strictObject({
+		id: entryId,
+		version,
+		acknowledgeWarnings: z.array(acknowledgedWarning).default([]).describe("The warnings you accept, as needs_acknowledgement listed them.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"pending_review",
+			"blocked",
+			"needs_acknowledgement",
+			"conflict",
+			"not_found"
+		]),
+		entry: entrySummary.optional(),
+		verdict: verdict.optional(),
+		conflict: conflict.optional(),
+		review: review.optional().describe("With pending_review: the request, as list_reviews shows it.")
+	}),
+	scopes: ["content:write"],
+	effect: "write",
+	outcomes: {
+		pending_review: { isError: false },
+		blocked: { isError: true },
+		needs_acknowledgement: { isError: false },
+		conflict: { isError: true },
+		not_found: { isError: true }
+	}
+});
+const commentReview = defineOperation({
+	name: "comment_review",
+	title: "Comment on a review",
+	description: "Adds a comment to a pending review, for the person who decides it and for the author: what to change, what reads well, what the contracts cannot check. It neither approves nor closes the review.",
+	input: z.strictObject({
+		id: reviewId,
+		body: z.string().trim().min(1).max(4e3).describe("The comment, in Markdown.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"commented",
+			"not_pending",
+			"not_found"
+		]),
+		comment: reviewComment.optional()
+	}),
+	scopes: ["content:write"],
+	effect: "write",
+	outcomes: {
+		commented: { isError: false },
+		not_pending: { isError: true },
+		not_found: { isError: true }
+	}
+});
 const requestChanges = defineOperation({
 	name: "request_changes",
 	title: "Ask for changes",
@@ -3541,6 +3611,7 @@ const contentStats = defineOperation({
 /** Every operation, sorted by name: the order of `tools/list`. */
 const OPERATIONS = [
 	approveReview,
+	commentReview,
 	contentStats,
 	createDraft,
 	describeSite,
@@ -3550,6 +3621,7 @@ const OPERATIONS = [
 	listReviews,
 	publish,
 	requestChanges,
+	requestReview,
 	search,
 	unpublish,
 	updateDraft,
@@ -3745,4 +3817,4 @@ function chunksOf(entry) {
 //#region src/index.ts
 const name = "@hollware/core";
 //#endregion
-export { BUILT_IN_CONTRACT_IDS, CHUNKER_VERSION, CHUNK_LIMITS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, approveReview, chunksOf, contentStats, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, name, newId, processMarkdown, publish, renderHtml, requestChanges, resolveConfig, runContracts, schemas_exports as schemas, search, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };
+export { BUILT_IN_CONTRACT_IDS, CHUNKER_VERSION, CHUNK_LIMITS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, approveReview, chunksOf, commentReview, contentStats, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, name, newId, processMarkdown, publish, renderHtml, requestChanges, requestReview, resolveConfig, runContracts, schemas_exports as schemas, search, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {