@open-agent-toolkit/cli 0.2.5 → 0.2.7

package/assets/skills/explainer-kit/schemas/publish-receipt.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.publish-receipt/v1",
+  "title": "PublishReceiptV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "publishedAt",
+    "roots",
+    "sentinel",
+    "artifacts"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.publish-receipt/v1" },
+    "provider": { "const": "s3-static" },
+    "publishedAt": { "type": "string", "format": "date-time" },
+    "roots": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["s3Uri", "publicBaseUrl"],
+      "properties": {
+        "s3Uri": {
+          "type": "string",
+          "pattern": "^s3://[^/\\s]+(?:/[^\\s]*)?$"
+        },
+        "publicBaseUrl": {
+          "type": "string",
+          "pattern": "^https://[^\\s]+$"
+        }
+      }
+    },
+    "sentinel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "relativePath",
+        "uploadVerified",
+        "publicVerified",
+        "deleted"
+      ],
+      "properties": {
+        "relativePath": { "$ref": "#/$defs/safeRelativePath" },
+        "uploadVerified": { "type": "boolean" },
+        "publicVerified": { "type": "boolean" },
+        "deleted": { "type": "boolean" }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artifact" },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "relativePath",
+        "hash",
+        "s3Uri",
+        "publicUrl",
+        "httpStatus",
+        "contentType"
+      ],
+      "properties": {
+        "relativePath": { "$ref": "#/$defs/safeRelativePath" },
+        "hash": { "$ref": "#/$defs/hash" },
+        "s3Uri": {
+          "type": "string",
+          "pattern": "^s3://[^/\\s]+/.+$"
+        },
+        "publicUrl": {
+          "type": "string",
+          "pattern": "^https://[^\\s]+$"
+        },
+        "httpStatus": {
+          "type": "integer",
+          "minimum": 200,
+          "maximum": 299
+        },
+        "contentType": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/publish-request.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.publish-request/v1",
+  "title": "S3StaticPublishRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "s3Uri",
+    "publicBaseUrl",
+    "awsRegion",
+    "siteRoot",
+    "manifestPath"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.publish-request/v1" },
+    "provider": { "const": "s3-static" },
+    "s3Uri": {
+      "type": "string",
+      "pattern": "^s3://[^/\\s]+(?:/[^\\s]*)?$"
+    },
+    "publicBaseUrl": {
+      "type": "string",
+      "pattern": "^https://[^\\s]+$"
+    },
+    "awsRegion": { "type": "string", "minLength": 1 },
+    "awsProfile": { "type": "string", "minLength": 1 },
+    "siteRoot": { "type": "string", "minLength": 1 },
+    "manifestPath": { "type": "string", "minLength": 1 }
+  }
+}

package/assets/skills/explainer-kit/schemas/run-request.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.run-request/v1",
+  "title": "ExplainerRunRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "recipe",
+    "slug",
+    "outputRoot",
+    "factBase",
+    "mode"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.run-request/v1"
+    },
+    "recipe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "outputRoot": { "$ref": "#/$defs/relativeOrAbsolutePath" },
+    "factBase": { "$ref": "#/$defs/factBaseBinding" },
+    "theme": { "$ref": "#/$defs/themeSelection" },
+    "publicBaseUrl": { "type": "string", "format": "uri" },
+    "durability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategy"],
+      "properties": {
+        "strategy": {
+          "enum": ["none", "commit", "publish"]
+        },
+        "publish": {
+          "$ref": "explainer-kit.publish-request/v1"
+        }
+      }
+    },
+    "privacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["retainRawArtDirection"],
+      "properties": {
+        "retainRawArtDirection": { "type": "boolean" }
+      }
+    },
+    "mode": { "enum": ["interactive", "unattended"] }
+  },
+  "$defs": {
+    "relativeOrAbsolutePath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "sourceBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "locator", "role", "sourceSetId"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": {
+          "enum": ["file", "directory", "git", "github", "session", "other"]
+        },
+        "locator": { "type": "string", "minLength": 1 },
+        "role": { "type": "string", "minLength": 1 },
+        "sourceSetId": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 },
+        "authoritativeFor": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      }
+    },
+    "factBaseBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "freshnessPolicy"],
+      "properties": {
+        "mode": { "enum": ["supplied", "federated"] },
+        "path": { "$ref": "#/$defs/relativeOrAbsolutePath" },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/sourceBinding" },
+          "minItems": 1
+        },
+        "freshnessPolicy": { "const": "live-wins" }
+      },
+      "oneOf": [
+        {
+          "required": ["path"],
+          "properties": { "mode": { "const": "supplied" } }
+        },
+        {
+          "required": ["sources"],
+          "properties": { "mode": { "const": "federated" } }
+        }
+      ]
+    },
+    "themeSelection": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "palette": { "type": "string", "minLength": 1 },
+        "visualProfile": { "type": "string", "minLength": 1 },
+        "suppliedBundlePath": {
+          "$ref": "#/$defs/relativeOrAbsolutePath"
+        },
+        "artDirection": { "type": "string", "minLength": 1 },
+        "defaultMode": { "enum": ["light", "dark"] },
+        "renderStrategy": {
+          "enum": ["default-only", "user-switchable"],
+          "default": "default-only"
+        }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/theme.schema.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.theme/v1",
+  "title": "ResolvedThemeV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "name",
+    "defaultMode",
+    "modes",
+    "provenance",
+    "typography",
+    "spacing",
+    "geometry",
+    "elevation",
+    "density",
+    "motion",
+    "diagrams",
+    "bundleHash"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.theme/v1" },
+    "name": { "type": "string", "minLength": 1 },
+    "defaultMode": { "enum": ["light", "dark"] },
+    "modes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["light", "dark"],
+      "properties": {
+        "light": { "$ref": "#/$defs/colors" },
+        "dark": { "$ref": "#/$defs/colors" }
+      }
+    },
+    "provenance": { "$ref": "#/$defs/provenance" },
+    "typography": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sans", "serif", "mono", "scale", "lineHeight"],
+      "properties": {
+        "sans": { "$ref": "#/$defs/fontList" },
+        "serif": { "$ref": "#/$defs/fontList" },
+        "mono": { "$ref": "#/$defs/fontList" },
+        "scale": { "$ref": "#/$defs/stringMap" },
+        "lineHeight": { "$ref": "#/$defs/positiveNumberMap" }
+      }
+    },
+    "spacing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unit", "scale"],
+      "properties": {
+        "unit": { "type": "number", "exclusiveMinimum": 0, "maximum": 64 },
+        "scale": { "$ref": "#/$defs/positiveNumberMap" }
+      }
+    },
+    "geometry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["radius", "borderWidth"],
+      "properties": {
+        "radius": { "$ref": "#/$defs/nonNegativeNumberMap" },
+        "borderWidth": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 16
+        }
+      }
+    },
+    "elevation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["shadows"],
+      "properties": {
+        "shadows": { "$ref": "#/$defs/stringMap" }
+      }
+    },
+    "density": { "enum": ["compact", "comfortable", "spacious"] },
+    "motion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "durationMs", "easing", "reducedMotion"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "durationMs": { "$ref": "#/$defs/nonNegativeNumberMap" },
+        "easing": { "$ref": "#/$defs/stringMap" },
+        "reducedMotion": { "const": "disable-nonessential" }
+      }
+    },
+    "diagrams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lineWidth", "nodeGap", "arrowStyle", "labelTreatment"],
+      "properties": {
+        "lineWidth": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 16
+        },
+        "nodeGap": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 512
+        },
+        "arrowStyle": { "enum": ["straight", "curved"] },
+        "labelTreatment": { "enum": ["inline", "boxed"] }
+      }
+    },
+    "bundleHash": {
+      "$ref": "#/$defs/hash",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "color": {
+      "type": "string",
+      "pattern": "^#[0-9a-fA-F]{6}$"
+    },
+    "colors": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["surface", "ink", "accent", "status", "diagramSeries"],
+      "properties": {
+        "surface": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["canvas", "panel", "elevated"],
+          "properties": {
+            "canvas": { "$ref": "#/$defs/color" },
+            "panel": { "$ref": "#/$defs/color" },
+            "elevated": { "$ref": "#/$defs/color" }
+          }
+        },
+        "ink": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["primary", "muted", "inverse"],
+          "properties": {
+            "primary": { "$ref": "#/$defs/color" },
+            "muted": { "$ref": "#/$defs/color" },
+            "inverse": { "$ref": "#/$defs/color" }
+          }
+        },
+        "accent": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["primary", "secondary"],
+          "properties": {
+            "primary": { "$ref": "#/$defs/color" },
+            "secondary": { "$ref": "#/$defs/color" }
+          }
+        },
+        "status": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["success", "warning", "danger", "info"],
+          "properties": {
+            "success": { "$ref": "#/$defs/color" },
+            "warning": { "$ref": "#/$defs/color" },
+            "danger": { "$ref": "#/$defs/color" },
+            "info": { "$ref": "#/$defs/color" }
+          }
+        },
+        "diagramSeries": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/color" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["derived"],
+      "properties": {
+        "palette": { "type": "string", "minLength": 1 },
+        "visualProfile": { "type": "string", "minLength": 1 },
+        "derived": { "type": "boolean" },
+        "instructionHash": { "$ref": "#/$defs/hash" },
+        "suppliedBundleHash": { "$ref": "#/$defs/hash" }
+      }
+    },
+    "fontList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    },
+    "stringMap": {
+      "type": "object",
+      "propertyNames": { "minLength": 1 },
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "positiveNumberMap": {
+      "type": "object",
+      "propertyNames": { "minLength": 1 },
+      "additionalProperties": {
+        "type": "number",
+        "exclusiveMinimum": 0,
+        "maximum": 1024
+      }
+    },
+    "nonNegativeNumberMap": {
+      "type": "object",
+      "propertyNames": { "minLength": 1 },
+      "additionalProperties": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 10000
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/scripts/lib/content-approval.mjs

@@ -0,0 +1,180 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { writeJsonAtomic } from './fs-safe.mjs';
+
+const APPROVAL_PATH = 'source/content-approval.json';
+const MODES = new Set(['interactive', 'unattended']);
+const DECISIONS = new Map([
+  ['approve', 'approved'],
+  ['approved', 'approved'],
+  ['reject', 'rejected'],
+  ['rejected', 'rejected'],
+]);
+
+export async function resolveContentApproval(run, mode, reviewedSource) {
+  assertRun(run);
+  if (!MODES.has(mode)) {
+    throw new Error('Content approval mode must be interactive or unattended.');
+  }
+
+  const previous = await readPrevious(run);
+  let record;
+  if (mode === 'unattended') {
+    const provenance =
+      reviewedSource ?? approvedSourceProvenance(run.request.factBase);
+    assertProvenance(provenance);
+    record = {
+      schemaVersion: 'explainer-kit.content-approval/v1',
+      runId: run.runId,
+      mode,
+      status: 'approved',
+      reviewedSource: structuredClone(provenance),
+      attempts: previous?.attempts ?? [],
+    };
+  } else if (reviewedSource === undefined) {
+    record = previous ?? {
+      schemaVersion: 'explainer-kit.content-approval/v1',
+      runId: run.runId,
+      mode,
+      status: 'pending',
+      attempts: [],
+    };
+  } else {
+    const decision = normalizeDecision(reviewedSource.decision);
+    const attempt = interactiveAttempt(reviewedSource, decision);
+    record = {
+      schemaVersion: 'explainer-kit.content-approval/v1',
+      runId: run.runId,
+      mode,
+      status: decision,
+      attempts: [...(previous?.attempts ?? []), attempt],
+      ...(decision === 'approved' && {
+        reviewedSource: structuredClone(
+          reviewedSource.source ?? {
+            kind: 'human-review',
+            locator: 'source/content',
+          },
+        ),
+      }),
+    };
+    if (record.reviewedSource) {
+      assertProvenance(record.reviewedSource);
+    }
+  }
+
+  await writeJsonAtomic(run.runRoot, APPROVAL_PATH, record);
+  return {
+    status: record.status,
+    canResume: record.status === 'approved',
+    path: APPROVAL_PATH,
+    record,
+  };
+}
+
+async function readPrevious(run) {
+  try {
+    const previous = JSON.parse(
+      await readFile(join(run.runRoot, APPROVAL_PATH), 'utf8'),
+    );
+    if (
+      previous.schemaVersion !== 'explainer-kit.content-approval/v1' ||
+      previous.runId !== run.runId
+    ) {
+      throw new Error('Content approval record does not belong to this run.');
+    }
+    return previous;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function interactiveAttempt(source, status) {
+  if (!isObject(source)) {
+    throw new TypeError('Interactive approval requires a review decision.');
+  }
+  if (
+    typeof source.reviewedAt !== 'string' ||
+    Number.isNaN(Date.parse(source.reviewedAt))
+  ) {
+    throw new Error('Interactive approval requires a valid reviewedAt value.');
+  }
+  if (
+    source.reviewer !== undefined &&
+    (typeof source.reviewer !== 'string' || source.reviewer.length === 0)
+  ) {
+    throw new Error(
+      'Interactive approval reviewer must be a non-empty string.',
+    );
+  }
+  const corrections = source.corrections ?? [];
+  if (
+    !Array.isArray(corrections) ||
+    corrections.some(
+      (correction) =>
+        typeof correction !== 'string' || correction.trim().length === 0,
+    )
+  ) {
+    throw new Error('Approval corrections must be non-empty strings.');
+  }
+  if (status === 'rejected' && corrections.length === 0) {
+    throw new Error('Rejected content approval requires corrections.');
+  }
+  return {
+    decision: status === 'approved' ? 'approve' : 'reject',
+    reviewedAt: source.reviewedAt,
+    ...(source.reviewer && { reviewer: source.reviewer }),
+    corrections: [...corrections],
+  };
+}
+
+function normalizeDecision(decision) {
+  const normalized = DECISIONS.get(decision);
+  if (!normalized) {
+    throw new Error('Review decision must be approve or reject.');
+  }
+  return normalized;
+}
+
+function approvedSourceProvenance(factBase) {
+  if (factBase?.mode === 'supplied') {
+    return {
+      kind: 'approved-fact-base',
+      locator: factBase.path,
+    };
+  }
+  return {
+    kind: 'approved-source-set',
+    locator: `federated:${factBase?.sources?.length ?? 0}`,
+  };
+}
+
+function assertProvenance(value) {
+  if (
+    !isObject(value) ||
+    typeof value.kind !== 'string' ||
+    value.kind.length === 0 ||
+    typeof value.locator !== 'string' ||
+    value.locator.length === 0
+  ) {
+    throw new Error(
+      'Reviewed source provenance requires non-empty kind and locator values.',
+    );
+  }
+}
+
+function assertRun(run) {
+  if (
+    !isObject(run) ||
+    typeof run.runId !== 'string' ||
+    typeof run.runRoot !== 'string' ||
+    !isObject(run.request)
+  ) {
+    throw new TypeError('Run must be returned by initializeRun().');
+  }
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}