@open-agent-toolkit/cli 0.2.72 → 0.2.74

package/assets/skills/explainer-kit/scripts/validate.mjs

@@ -1,59 +0,0 @@
-#!/usr/bin/env node
-
-import { readFile } from 'node:fs/promises';
-import { pathToFileURL } from 'node:url';
-
-import { validateContract } from './lib/contracts.mjs';
-
-export async function runValidationCli(
-  argv = process.argv.slice(2),
-  io = console,
-) {
-  const [kind, inputPath] = argv;
-  if (!kind || !inputPath) {
-    const result = {
-      valid: false,
-      errors: [
-        {
-          path: '$',
-          code: 'usage',
-          message: 'Usage: validate.mjs <contract-kind> <json-path>',
-        },
-      ],
-    };
-    io.log(JSON.stringify(result, null, 2));
-    return 1;
-  }
-
-  try {
-    const value = JSON.parse(await readFile(inputPath, 'utf8'));
-    const result = validateContract(kind, value);
-    io.log(JSON.stringify(result, null, 2));
-    return result.valid ? 0 : 1;
-  } catch (error) {
-    io.log(
-      JSON.stringify(
-        {
-          valid: false,
-          errors: [
-            {
-              path: '$',
-              code: 'input',
-              message: error instanceof Error ? error.message : String(error),
-            },
-          ],
-        },
-        null,
-        2,
-      ),
-    );
-    return 1;
-  }
-}
-
-if (
-  process.argv[1] &&
-  pathToFileURL(process.argv[1]).href === import.meta.url
-) {
-  process.exitCode = await runValidationCli();
-}

package/assets/skills/oat-explainer-kit/references/author-callback.md

@@ -1,53 +0,0 @@
-# Author callback contract
-
-Lifecycle callers own the executable author seam; the explainer core owns
-construction of each author request. In-process callers pass an `author`
-callback to `runOatExplainer`. JSON-only and official CLI callers pass
-`authorModulePath`, which must name a module with an `author` function export.
-Provide exactly one of those inputs in both interactive and unattended modes.
-The callback or module may use any provider, but its request and result remain
-provider-neutral.
-
-## Request handling
-
-The callback receives one `explainer-kit.author-request/v2` per artifact. The
-core constructs that request from recipe-owned policy:
-
-- `brief` contains the prose loaded from the floor entry or expansion profile's
-  `briefRef`; the author must treat the inlined brief as its editorial contract.
-- `visualAuthoringGuidance` contains the installed core's bundled
-  representation, hierarchy, responsive-navigation, table, diagram, and deck
-  rules. Treat it as the medium baseline; do not read ambient or home-directory
-  guidance.
-- `factBase` contains the reconciled evidence for the run. Ground claims in that
-  fact base and do not replace it with ambient project context.
-- `authoring` selects the output path. Return Markdown for `markdown` and a
-  complete HTML document for `html`.
-- `theme` is attached to every request. HTML requests also carry the
-  recipe-selected `shell`; use it as the starting canvas while following the
-  brief's license to elaborate.
-- A floor request may include `floor.requiredNarrative`, which identifies the
-  narrative coverage checked later as non-blocking guidelines.
-- `setContext` is the complete immutable planner-owned portfolio and shared
-  ledger. `plannedArtifact` is the exact entry assigned to this callback;
-  preserve its identity, sources, draft, and visual intent.
-
-Return one matching `explainer-kit.author-result/v2`: preserve `artifactId`,
-set exactly one of `content.markdown` or `content.html`, and include
-`provenance`. Do not persist provider credentials or callback configuration in
-the result.
-
-## Planner-owned expansion
-
-The set planner finalizes the complete floor and expansion portfolio before any
-author runs. Authors must not return `proposedArtifacts` or otherwise add,
-remove, replace, or reorder portfolio entries. Handle only the supplied
-`plannedArtifact`; the core rejects author-driven expansion after planning.
-
-## Lifecycle invocation
-
-Automated project-completion and implementation-tail recaps always call
-`runOatExplainer` with `mode: unattended`. They construct the author seam before
-invocation and supply it alongside the existing provider-neutral `critic` or
-validated `criticModulePath`. Interactive invocations use the same author
-contract; only the later approval behavior differs.

package/assets/skills/oat-explainer-kit/references/migration.md

@@ -1,144 +0,0 @@
-# Private-wrapper migration
-
-This runbook migrates the externally owned private wrapper from the monolithic
-`oat-explainer-kit` 0.4.1 workflow to the frozen v1 pre/core/post seam. Keep the
-0.4.1 installation and its private configuration available until one unchanged
-release candidate passes every acceptance gate.
-
-## Prepare the private wrapper
-
-1. Back up the installed 0.4.1 skill, private presets, Stoa configuration, and
-   Google Docs settings. Confirm the backup contains `SKILL.md`, scripts,
-   references, and templates.
-2. Install the candidate `explainer-kit` at user scope and verify that the
-   wrapper resolves that installed copy, never a source checkout.
-3. Change wrapper pre-resolution to produce one
-   `explainer-kit.run-request/v1`. Keep preset selection, vault/Stoa paths,
-   Google account data, authentication choices, and personal destination
-   topology in private wrapper configuration.
-4. Invoke the core once, consume only `explainer-kit.manifest/v1` and the
-   optional `explainer-kit.publish-receipt/v2` (while retaining v1 replay),
-   then perform Stoa notes, Google Docs sync, and
-   private link maintenance as post-run work.
-
-Do not add a plugin, inject private work between core stages, or add private
-lanes to public OAT config.
-
-### Private `presets.example.json`
-
-The private wrapper's `personal-oat` example should carry the confirmed public
-root:
-
-```json
-{
-  "presets": {
-    "personal-oat": {
-      "publicBaseUrl": "https://dy4vzrzaexuy5.cloudfront.net"
-    }
-  }
-}
-```
-
-Copy `presets.example.json` to an untracked `presets.json` before adding
-accounts or authentication details.
-
-### Private Stoa configuration
-
-The eventual private Stoa configuration may use the same confirmed public root
-to create manifest-derived links:
-
-```json
-{
-  "explainerLinks": {
-    "publicBaseUrl": "https://dy4vzrzaexuy5.cloudfront.net",
-    "source": "explainer-kit.manifest/v1"
-  }
-}
-```
-
-This is private-wrapper migration/config context, not a public core default or
-neutral fixture.
-
-## Release-candidate sequence
-
-1. Build and retain the packaged RC in a dedicated builder-owned directory;
-   record its immutable RC identity:
-
-   ```bash
-   node tools/release/build-explainer-rc.mjs \
-     --output dist/explainer-kit-rc \
-     --record .oat/repo/reference/explainer-kit-acceptance/v1/rc.json
-   ```
-
-   The builder rejects repository/source roots, symlinks, and unowned existing
-   directories. Reuse only an output carrying its ownership marker.
-
-2. Run packaged direct-core and OAT-adapter build-only smoke tests.
-3. Migrate the real private wrapper against that exact RC.
-4. Run the operator-owned wrapper E2E as an executable pre/core/post sequence:
-   resolve the private preset and external request; invoke the packaged core;
-   then publish the manifest, retain its complete receipt, and perform
-   vault/Stoa, Google Docs, and personal-link work. Verify all post-run evidence
-   against the immutable core execution record.
-5. Run the live S3/CDN acceptance against the same unchanged RC.
-6. Promote only when both retained acceptance records pass and reference the
-   same RC identity.
-
-Every packaged invocation supplies the retained artifacts explicitly; there is
-no current-working-directory fallback. The wrapper core stage does not declare
-post-run receipt evidence:
-
-```bash
-node tools/release/run-explainer-rc.mjs \
-  --rc-manifest .oat/repo/reference/explainer-kit-acceptance/v1/rc.json \
-  --artifacts-dir dist/explainer-kit-rc \
-  --entry scripts/run.mjs \
-  --record .oat/repo/reference/explainer-kit-acceptance/v1/private-wrapper-execution.json \
-  -- \
-  --request /path/to/private/run-request.json
-```
-
-The packaged CLI emits exactly one complete JSON result document; pretty
-printing across lines is valid and progress text is not. After that command
-returns, the private wrapper publishes and links the core manifest. Retain
-`private-wrapper-manifest.json`,
-`private-wrapper-publish-receipt.json`, and
-`private-wrapper-result.json` beside the RC identity. Wrapper acceptance reads
-and validates the full receipt as a separate post-run stage and rejects a
-foreign run ID, sentinel, artifact set, or manifest hash even when caller-owned
-files repeat the same receipt hash.
-
-The live connector stage is a separate packaged invocation:
-
-```bash
-node tools/release/run-explainer-rc.mjs \
-  --rc-manifest .oat/repo/reference/explainer-kit-acceptance/v1/rc.json \
-  --artifacts-dir dist/explainer-kit-rc \
-  --entry scripts/publish.mjs \
-  --record .oat/repo/reference/explainer-kit-acceptance/v1/live-publish-result.json \
-  -- \
-  --request .oat/repo/reference/explainer-kit-acceptance/v1/live-publish-request.json \
-  --receipt .oat/repo/reference/explainer-kit-acceptance/v1/publish-receipt.json \
-  --confirm-publish
-```
-
-Retain the execution record produced by that command. Acceptance binds it to
-the canonical request, manifest, receipt, and core run ID and rejects stale
-cross-run evidence.
-
-The in-repository compatibility fixture is a development guard. It does not
-satisfy the operator-owned real-wrapper gate.
-
-## Rollback
-
-If migration or acceptance fails, do not promote the candidate:
-
-1. Preserve the failed candidate's sanitized diagnostics and issue a new RC
-   only after correcting the public seam or private wrapper.
-2. Restore the backed-up 0.4.1 skill and private configuration.
-3. Remove the candidate user-scope core and refresh provider views with
-   `oat sync --scope all`.
-4. Verify one known-good 0.4.1 build before resuming normal wrapper use.
-
-Do not retire the backup until the unchanged promoted RC has passed the
-operator-owned wrapper and live-publish gates.

package/assets/skills/oat-explainer-kit/references/visual-review-callback.md

@@ -1,83 +0,0 @@
-# Browser and visual-review callbacks
-
-Unattended project recaps require two provider-neutral executable seams. Supply
-each seam either directly or through a module path, never both:
-
-| Role             | Direct input     | Module-path input          | Required export  |
-| ---------------- | ---------------- | -------------------------- | ---------------- |
-| Browser evidence | `browserSession` | `browserSessionModulePath` | `browserSession` |
-| Whole-set review | `visualCritic`   | `visualCriticModulePath`   | `visualCritic`   |
-
-Do not route these callbacks through `coreOptions`. The adapter resolves and
-validates both providers before core invocation and keeps callbacks and module
-paths out of retained requests.
-
-## Browser evidence
-
-Create the direct descriptor with the compatible core's
-`createBrowserProbeSession()`. A module-path provider exports that branded
-descriptor as `browserSession`; it does not export a bare callback or a
-caller-authored metadata object. The core derives Chromium type and version
-from the launched `Browser` instance and validates the private session brand.
-Callers remain responsible for closing the session.
-
-The descriptor's probe receives one provider-neutral request for each artifact,
-viewport, and required interaction scenario. The request includes the rendered
-artifact, exact viewport dimensions, scenario, interaction expectations, and,
-for the default scenario, an absolute `screenshotPath`. The probe writes a PNG
-to that path and returns measured browser facts:
-
-- `pageOverflowX` as a boolean;
-- `clippedX`, `viewportClipped`, and `unreadableHeadings` as arrays;
-- `reducedMotion` as a boolean;
-- `keyboard` as an object describing observed key behavior; and
-- applicable deck, theme-toggle, animation, and layout measurements.
-
-For unattended project recaps the core chooses the canonical 320, 768, and 1440
-widths. The retained PNG signature and IHDR dimensions must match the requested
-viewport. The core writes paired metrics JSON itself; callback assertions do
-not substitute for retained evidence. Those
-`explainer-kit.browser-evidence/v2` records retain the launched Chromium name,
-version, capture settings, and stable capture identity. Deterministic fixture
-sessions are explicit test-only descriptors and are rejected by unattended
-project-recap production paths.
-
-## Whole-set visual review
-
-The visual critic receives one
-`explainer-kit.visual-review-request/v1` plus a confined evidence reader. The
-request contains every rendered artifact, exact rendered-content hashes,
-viewport-matched screenshot and metrics hashes, observed cohesion claims, and
-the exact browser runtime and capture identity shared by every evidence record.
-Use the evidence reader to inspect the byte snapshot named by the request.
-
-Judge the rendered set as prose-led visual work. Cover typography, hierarchy,
-composition, density, medium leverage, template repetition, diagram semantics,
-and cross-artifact cohesion. Use the set plan and shared ledger to distinguish
-intentional variation from drift. Do not turn those judgments into numeric
-scores, geometry thresholds, or deterministic style checks.
-
-Return `explainer-kit.visual-review-result/v1` with:
-
-- a safe `reviewId`;
-- the request's exact `requestId` and `requestHash`;
-- an ISO `reviewedAt`;
-- `disposition` equal to `pass`, `correct`, or `fail`;
-- the complete reviewed `artifactIds`; and
-- structured `findings`.
-
-Return `pass` only when the full set needs no required correction. Return
-`correct` when one bounded review round can address every finding, and give
-each finding an actionable correction tied to an artifact and visible evidence.
-The result shape and its `pass`/`correct`/`fail` dispositions remain unchanged.
-
-The callback must not mutate rendered files, screenshots, or metrics. The core
-revalidates all bound bytes after the callback returns.
-
-## Correction and terminal behavior
-
-`correct` permits one correction callback and exactly one final review. There
-is never a second correction or third review. Missing evidence, invalid
-contracts, thrown callbacks, byte mutation, unresolved correction, or a `fail`
-disposition produces `built-needs-review`. Such a run retains available review
-evidence but invokes neither durability nor publication.

package/assets/skills/oat-explainer-kit/scripts/derive-destination.mjs

@@ -1,91 +0,0 @@
-const INVOCATIONS = new Set(['project', 'repo', 'direct']);
-
-export function deriveExplainerDestination({
-  invocation,
-  projectSlug,
-  s3Uri,
-  publicBaseUrl,
-}) {
-  if (!INVOCATIONS.has(invocation)) {
-    throw new Error(`Unsupported explainer invocation: ${invocation}`);
-  }
-  const roots = {
-    s3Uri: normalizeRoot(s3Uri, 's3Uri', 's3:'),
-    publicBaseUrl: normalizeRoot(publicBaseUrl, 'publicBaseUrl', 'https:'),
-  };
-  if (invocation !== 'project') {
-    return roots;
-  }
-
-  const encodedSlug = encodeProjectSlug(projectSlug);
-  return {
-    s3Uri: `${roots.s3Uri}/projects/${encodedSlug}`,
-    publicBaseUrl: `${roots.publicBaseUrl}/projects/${encodedSlug}`,
-  };
-}
-
-function encodeProjectSlug(projectSlug) {
-  if (
-    typeof projectSlug !== 'string' ||
-    !projectSlug.trim() ||
-    projectSlug === '.' ||
-    projectSlug === '..' ||
-    projectSlug.includes('/') ||
-    projectSlug.includes('\\') ||
-    projectSlug.includes('\0')
-  ) {
-    throw new Error(
-      'Project slug must be a non-empty, safe path segment without traversal or separators.',
-    );
-  }
-  return encodeURIComponent(projectSlug);
-}
-
-function normalizeRoot(value, label, protocol) {
-  if (typeof value !== 'string') {
-    throw new Error(`${label} must be a valid destination root.`);
-  }
-  const root = value.trim();
-  const authorityStart = `${protocol}//`;
-  if (
-    !root.startsWith(authorityStart) ||
-    /\s|\\/.test(root) ||
-    root.includes('?') ||
-    root.includes('#')
-  ) {
-    throw new Error(`${label} must be a valid destination root.`);
-  }
-
-  let parsed;
-  try {
-    parsed = new URL(root);
-  } catch {
-    throw new Error(`${label} must be a valid destination root.`);
-  }
-  const authority = root.slice(authorityStart.length).split('/', 1)[0];
-  if (
-    parsed.protocol !== protocol ||
-    !isValidRawAuthority(authority, protocol) ||
-    !parsed.hostname ||
-    parsed.username ||
-    parsed.password ||
-    parsed.search ||
-    parsed.hash
-  ) {
-    throw new Error(`${label} must be a valid destination root.`);
-  }
-  return root.replace(/\/+$/, '');
-}
-
-function isValidRawAuthority(authority, protocol) {
-  if (!authority || authority.includes('@')) {
-    return false;
-  }
-  if (protocol === 's3:') {
-    return /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/.test(authority);
-  }
-  if (authority.startsWith('[')) {
-    return /^\[[^\]]+\](?::\d+)?$/.test(authority);
-  }
-  return /^[^:]+(?::\d+)?$/.test(authority);
-}