npm - @open-agent-toolkit/cli - Versions diffs - 0.2.5 → 0.2.7 - Mend

@open-agent-toolkit/cli 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (104) hide show

package/assets/skills/explainer-kit/templates/engineer-tour.html ADDED Viewed

@@ -0,0 +1,273 @@
+<!doctype html>
+<!--
+  Neutral production shell. Worked content: ../examples/
+  TEMPLATE CONTRACT: THEME_CSS, TITLE, DESCRIPTION, EYEBROW, NAVIGATION, CONTENT, DIAGRAM, FOOTER
+  CONTENT sections use data-active-nodes/data-active-edges and may include expandable snippets.
+  DIAGRAM contains validated inline SVG nodes and edges.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{TITLE}}</title>
+    <meta name="description" content="{{DESCRIPTION}}" />
+    <style>
+      :root {
+        --canvas: hsl(215 24% 13%);
+        --panel: hsl(215 20% 18%);
+        --panel-muted: hsl(215 18% 22%);
+        --border: hsl(215 14% 32%);
+        --ink: hsl(210 18% 92%);
+        --muted: hsl(210 10% 70%);
+        --accent: hsl(190 38% 70%);
+        --warning: hsl(38 55% 68%);
+        --sans: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+        --serif: ui-serif, Georgia, serif;
+        --mono: ui-monospace, SFMono-Regular, Consolas, monospace;
+        {{THEME_CSS}}
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html {
+        scroll-behavior: smooth;
+      }
+      body {
+        margin: 0;
+        background: var(--canvas);
+        color: var(--ink);
+        font-family: var(--sans);
+        line-height: 1.65;
+      }
+      .layout {
+        display: grid;
+        grid-template-columns: 13rem minmax(0, 1fr) 23rem;
+        gap: 2rem;
+        max-width: 86rem;
+        margin: auto;
+        padding-inline: 2rem;
+      }
+      .toc {
+        position: sticky;
+        top: 0;
+        align-self: start;
+        max-height: 100dvh;
+        overflow-y: auto;
+        padding-block: 2.5rem;
+      }
+      .toc-brand,
+      .eyebrow,
+      .section-number {
+        color: var(--muted);
+        font: 0.7rem/1.4 var(--mono);
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+      }
+      .toc a {
+        display: block;
+        border-inline-start: 2px solid transparent;
+        padding: 0.35rem 0.75rem;
+        color: var(--muted);
+        text-decoration: none;
+      }
+      .toc a.active {
+        border-inline-start-color: var(--accent);
+        color: var(--accent);
+      }
+      .tour-body {
+        min-width: 0;
+        padding-block: 3.5rem 6rem;
+      }
+      h1,
+      h2 {
+        font-family: var(--serif);
+        line-height: 1.15;
+        text-wrap: balance;
+      }
+      h1 {
+        font-size: clamp(2.3rem, 5vw, 3.8rem);
+        margin-block: 0.6rem 1rem;
+      }
+      section {
+        margin-block: 4rem;
+        scroll-margin-top: 2rem;
+      }
+      .snippet {
+        overflow: hidden;
+        border: 1px solid var(--border);
+        border-radius: 0.6rem;
+        background: var(--panel);
+      }
+      .snippet-toggle {
+        width: 100%;
+        border: 0;
+        border-block-end: 1px solid transparent;
+        background: var(--panel-muted);
+        color: var(--ink);
+        cursor: pointer;
+        padding: 0.75rem 1rem;
+        text-align: start;
+        font: 0.85rem var(--sans);
+      }
+      .snippet-toggle[aria-expanded='true'] {
+        border-block-end-color: var(--border);
+      }
+      .snippet pre {
+        max-width: 100%;
+        margin: 0;
+        overflow-x: auto;
+        padding: 1rem;
+        font-family: var(--mono);
+      }
+      .snippet:not(.open) pre {
+        display: none;
+      }
+      .diagram-rail {
+        position: sticky;
+        top: 0;
+        align-self: start;
+        height: 100dvh;
+        padding-block: 3.5rem 2rem;
+      }
+      .diagram-card {
+        border: 1px solid var(--border);
+        border-radius: 0.75rem;
+        background: var(--panel);
+        padding: 1rem;
+      }
+      .diagram-card svg {
+        display: block;
+        width: 100%;
+        height: auto;
+      }
+      .diagram-card .node,
+      .diagram-card .edge {
+        transition: opacity 180ms ease, stroke 180ms ease, fill 180ms ease;
+      }
+      .diagram-card .node:not(.active),
+      .diagram-card .edge:not(.active) {
+        opacity: 0.35;
+      }
+      footer {
+        border-block-start: 1px solid var(--border);
+        color: var(--muted);
+        padding-block-start: 1rem;
+      }
+      @media (max-width: 74rem) {
+        .layout {
+          grid-template-columns: 12rem minmax(0, 1fr);
+        }
+        .diagram-rail {
+          display: none;
+        }
+      }
+      @media (max-width: 52rem) {
+        .layout {
+          grid-template-columns: 1fr;
+          padding-inline: 1rem;
+        }
+        .toc {
+          position: sticky;
+          top: 0;
+          z-index: 2;
+          display: flex;
+          max-height: none;
+          overflow-x: auto;
+          background: var(--canvas);
+          border-block-end: 1px solid var(--border);
+          padding-block: 0.5rem;
+        }
+        .toc-brand {
+          display: none;
+        }
+        .toc a {
+          flex: none;
+        }
+        .tour-body {
+          padding-block-start: 1.5rem;
+        }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        html {
+          scroll-behavior: auto;
+        }
+        *,
+        *::before,
+        *::after {
+          transition-duration: 0.01ms !important;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="layout">
+      <nav class="toc" aria-label="Tour sections">
+        <div class="toc-brand">{{EYEBROW}}</div>
+        {{NAVIGATION}}
+      </nav>
+      <main class="tour-body">
+        <header>
+          <div class="eyebrow">{{EYEBROW}}</div>
+          <h1>{{TITLE}}</h1>
+          <p>{{DESCRIPTION}}</p>
+        </header>
+        {{CONTENT}}
+        <footer>{{FOOTER}}</footer>
+      </main>
+      <aside class="diagram-rail" aria-label="System diagram">
+        <div class="diagram-card">
+          <svg viewBox="0 0 360 540" role="img" aria-label="{{TITLE}}">
+            {{DIAGRAM}}
+          </svg>
+        </div>
+      </aside>
+    </div>
+    <script>
+      (() => {
+        document.querySelectorAll('.snippet-toggle').forEach((button) => {
+          button.setAttribute('aria-expanded', 'false');
+          button.addEventListener('click', () => {
+            const snippet = button.closest('.snippet');
+            const expanded = snippet.classList.toggle('open');
+            button.setAttribute('aria-expanded', String(expanded));
+          });
+        });
+        const sections = [...document.querySelectorAll('section[id]')];
+        const links = [...document.querySelectorAll('.toc a[data-target]')];
+        const nodes = [
+          ...document.querySelectorAll('.diagram-card [data-node]'),
+        ];
+        const edges = [
+          ...document.querySelectorAll('.diagram-card [data-edge]'),
+        ];
+        const activate = (section) => {
+          const activeNodes = new Set(
+            (section.dataset.activeNodes || '').split(',').filter(Boolean),
+          );
+          const activeEdges = new Set(
+            (section.dataset.activeEdges || '').split(',').filter(Boolean),
+          );
+          nodes.forEach((node) =>
+            node.classList.toggle('active', activeNodes.has(node.dataset.node)),
+          );
+          edges.forEach((edge) =>
+            edge.classList.toggle('active', activeEdges.has(edge.dataset.edge)),
+          );
+          links.forEach((link) =>
+            link.classList.toggle('active', link.dataset.target === section.id),
+          );
+        };
+        const observer = new IntersectionObserver(
+          (entries) => {
+            const visible = entries.find((entry) => entry.isIntersecting);
+            if (visible) activate(visible.target);
+          },
+          { rootMargin: '-15% 0px -60% 0px', threshold: [0.1, 0.4, 0.7] },
+        );
+        sections.forEach((section) => observer.observe(section));
+        if (sections[0]) activate(sections[0]);
+      })();
+    </script>
+  </body>
+</html>

package/assets/skills/explainer-kit/templates/house-style.html ADDED Viewed

@@ -0,0 +1,218 @@
+<!doctype html>
+<!--
+  Neutral production shell. Worked content: ../examples/
+  TEMPLATE CONTRACT: THEME_CSS, TITLE, DESCRIPTION, EYEBROW, NAVIGATION, CONTENT, FOOTER
+  All replacement values are validated and escaped by the renderer.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{TITLE}}</title>
+    <meta name="description" content="{{DESCRIPTION}}" />
+    <style>
+      :root {
+        --canvas: hsl(210 20% 98%);
+        --panel: hsl(0 0% 100%);
+        --panel-muted: hsl(210 16% 94%);
+        --border: hsl(210 14% 82%);
+        --ink: hsl(215 24% 16%);
+        --muted: hsl(215 12% 38%);
+        --accent: hsl(215 28% 32%);
+        --success: hsl(145 45% 28%);
+        --warning: hsl(38 70% 30%);
+        --danger: hsl(0 55% 36%);
+        --sans: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+        --serif: ui-serif, Georgia, serif;
+        --mono: ui-monospace, SFMono-Regular, Consolas, monospace;
+        --radius: 0.65rem;
+        {{THEME_CSS}}
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html {
+        color-scheme: light dark;
+        scroll-behavior: smooth;
+      }
+      body {
+        margin: 0;
+        background: var(--canvas);
+        color: var(--ink);
+        font-family: var(--sans);
+        line-height: 1.6;
+      }
+      a {
+        color: var(--accent);
+      }
+      .wrap {
+        display: grid;
+        grid-template-columns: minmax(10rem, 14rem) minmax(0, 1fr);
+        gap: 2rem;
+        max-width: 74rem;
+        margin: auto;
+        padding: 2rem;
+      }
+      .toc {
+        position: sticky;
+        top: 2rem;
+        align-self: start;
+        max-height: calc(100dvh - 4rem);
+        overflow-y: auto;
+      }
+      .toc-label,
+      .eyebrow {
+        color: var(--muted);
+        font: 0.72rem/1.4 var(--mono);
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+      }
+      .toc a {
+        display: block;
+        border-inline-start: 2px solid transparent;
+        padding: 0.3rem 0.7rem;
+        text-decoration: none;
+      }
+      .toc a.active {
+        border-inline-start-color: var(--accent);
+        font-weight: 650;
+      }
+      main {
+        min-width: 0;
+      }
+      h1,
+      h2,
+      h3 {
+        font-family: var(--serif);
+        line-height: 1.2;
+        text-wrap: balance;
+      }
+      h1 {
+        font-size: clamp(2rem, 5vw, 3.4rem);
+        margin-block: 0.5rem 1rem;
+      }
+      h2 {
+        border-block-end: 1px solid var(--border);
+        padding-block-end: 0.45rem;
+        scroll-margin-top: 1rem;
+      }
+      section {
+        margin-block: 2.5rem;
+      }
+      .cards,
+      .lanes {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(min(100%, 15rem), 1fr));
+        gap: 1rem;
+      }
+      .card,
+      .lane,
+      .callout {
+        min-width: 0;
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        background: var(--panel);
+        padding: 1rem;
+        overflow-wrap: anywhere;
+      }
+      .callout {
+        border-inline-start: 0.25rem solid var(--accent);
+      }
+      .table-scroll,
+      pre {
+        max-width: 100%;
+        overflow-x: auto;
+      }
+      table {
+        width: 100%;
+        border-collapse: collapse;
+      }
+      th,
+      td {
+        border-block-end: 1px solid var(--border);
+        padding: 0.6rem;
+        text-align: start;
+      }
+      code,
+      pre {
+        font-family: var(--mono);
+      }
+      footer {
+        border-block-start: 1px solid var(--border);
+        color: var(--muted);
+        margin-block-start: 3rem;
+        padding-block-start: 1rem;
+      }
+      @media (max-width: 46rem) {
+        .wrap {
+          grid-template-columns: 1fr;
+          padding: 1rem;
+        }
+        .toc {
+          position: sticky;
+          top: 0;
+          z-index: 2;
+          display: flex;
+          gap: 0.25rem;
+          max-height: none;
+          overflow-x: auto;
+          background: var(--canvas);
+          border-block-end: 1px solid var(--border);
+          padding-block: 0.5rem;
+        }
+        .toc-label {
+          display: none;
+        }
+        .toc a {
+          flex: none;
+          white-space: nowrap;
+        }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        html {
+          scroll-behavior: auto;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <nav class="toc" aria-label="Page sections">
+        <div class="toc-label">{{EYEBROW}}</div>
+        {{NAVIGATION}}
+      </nav>
+      <main>
+        <header>
+          <div class="eyebrow">{{EYEBROW}}</div>
+          <h1>{{TITLE}}</h1>
+          <p>{{DESCRIPTION}}</p>
+        </header>
+        {{CONTENT}}
+        <footer>{{FOOTER}}</footer>
+      </main>
+    </div>
+    <script>
+      (() => {
+        const links = [...document.querySelectorAll('.toc a[href^="#"]')];
+        const targets = links
+          .map((link) => document.querySelector(link.getAttribute('href')))
+          .filter(Boolean);
+        const observer = new IntersectionObserver(
+          (entries) => {
+            for (const entry of entries) {
+              if (!entry.isIntersecting) continue;
+              links.forEach((link) =>
+                link.classList.toggle(
+                  'active',
+                  link.getAttribute('href') === `#${entry.target.id}`,
+                ),
+              );
+            }
+          },
+          { rootMargin: '-15% 0px -70% 0px' },
+        );
+        targets.forEach((target) => observer.observe(target));
+      })();
+    </script>
+  </body>
+</html>

package/assets/skills/oat-explainer-kit/SKILL.md ADDED Viewed

@@ -0,0 +1,92 @@
+---
+name: oat-explainer-kit
+version: 1.0.0
+description: Use when building project explainers or recaps from OAT configuration, state, and lifecycle artifacts.
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+---
+# OAT Explainer Kit
+Adapt OAT project context into the versioned request consumed by the canonical
+`explainer-kit` core.
+## Responsibilities
+- Require a compatible installed `explainer-kit` core.
+- Resolve typed OAT configuration with source attribution.
+- Derive canonical project or repository output roots.
+- Bind OAT lifecycle artifacts to generic recipe source roles.
+- Resolve project explainer and recap intent before invoking the core.
+## Dependency Direction
+This adapter depends on `explainer-kit`; the core never depends on this adapter.
+Fail closed when the compatible installed core is unavailable. Do not copy core
+runtime logic into the adapter.
+Private wrappers use the core's frozen pre-resolution/request/core-run/manifest/
+post-run seam directly; they do not route presets, vaults, Google Docs, Stoa, or
+personal destinations through this adapter. For the release-candidate sequence,
+rollback, and operator-owned real-wrapper gate, use `references/migration.md`.
+Before reading OAT config or invoking the core, call
+`scripts/check-core.mjs#checkCoreCompatibility` with this installed skill
+directory and minimum core version `1.0.0`. Continue only when it returns
+`ok: true`.
+- Missing core: stop and show
+  `oat tools install utility --scope user`.
+- Incompatible core: stop and show
+  `oat tools update --pack utility --scope user`.
+- Never search a repository checkout or another noncanonical path as fallback.
+## Asset Resolution
+Resolve adapter scripts and references relative to this installed skill
+directory. Resolve the core only from its installed canonical skill path. Never
+fall back to a repository source checkout.
+## Core Invocation
+Call `scripts/run.mjs#runOatExplainer` with the repository root, project
+invocation, active project path, recipe, slug, lifecycle mode, and any explicit
+runtime overrides. The adapter:
+1. checks the user-scoped installed core at minimum version `1.0.0`;
+2. resolves only the public `explainers.*` and `workflow.explainers.*` keys;
+3. derives the canonical project output root;
+4. binds approved OAT artifacts to the recipe's single `project` source set;
+5. creates one `ExplainerRunRequestV1`;
+6. calls the installed core's `runExplainer(request, options)` export; and
+7. consumes and returns the resulting `explainer-kit.manifest/v1`.
+`project-explainer` binds `plan.md`, `design.md`, and `spec.md`.
+`project-recap` additionally binds `implementation.md` and `summary.md`.
+Missing optional artifacts are omitted, but at least one approved lifecycle
+artifact is required. An explicit supplied fact-base path bypasses artifact
+federation and is passed through as `factBase.mode: supplied`.
+Unattended project runs pass `approved-oat-artifacts` provenance to the core's
+content-approval seam and never prompt. Federated runs still require an
+explicit provider-neutral critic callback. In-process callers may supply
+`critic` (or `coreOptions.critic` for compatibility); JSON/CLI callers supply
+`criticModulePath` naming a module whose `critic` export implements the same
+provider-neutral request/result contract. Supply exactly one critic seam.
+Approval provenance does not bypass fact reconciliation. Do not read private
+presets, vault files, provider configuration, or ambient destination
+configuration.
+## Progress Indicators (User-Facing)
+For interactive runs, show a concise banner and adapter stage updates:
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ EXPLAINER KIT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+Report compatibility, config, intent, source-binding, core-run, and finalization
+stages. Lifecycle-triggered unattended runs must not prompt.

package/assets/skills/oat-explainer-kit/references/config-contract.md ADDED Viewed

@@ -0,0 +1,67 @@
+# OAT Explainer Configuration Contract
+`oat-explainer-kit` is the OAT-aware boundary around the config-blind
+`explainer-kit` core. The adapter reads each supported stored value with
+`oat config get <key> --json` and preserves its `source` metadata while
+constructing an `explainer-kit.run-request/v1`.
+## Supported keys
+| Key                                    | Stored scopes       | Built-in default |
+| -------------------------------------- | ------------------- | ---------------- |
+| `explainers.defaults.palette`          | local, shared, user | `neutral`        |
+| `explainers.defaults.visualProfile`    | local, shared, user | `clean`          |
+| `explainers.defaults.themeBundlePath`  | local, shared       | unset            |
+| `explainers.publish.provider`          | shared              | unset            |
+| `explainers.publish.s3Uri`             | shared              | unset            |
+| `explainers.publish.publicBaseUrl`     | shared              | unset            |
+| `explainers.publish.awsRegion`         | shared              | unset            |
+| `explainers.publish.awsProfile`        | local, user         | unset            |
+| `workflow.explainers.projectExplainer` | local, shared, user | `ask`            |
+| `workflow.explainers.projectRecap`     | local, shared, user | `ask`            |
+Explicit runtime inputs may override these ten keys for one invocation. They
+do not write config. Recipe, slug, fact-base path, output root, per-run art
+direction, and private wrapper lanes are invocation inputs rather than config
+keys and are rejected from the runtime config-override map.
+## Source-sensitive paths
+A shared theme bundle path is repository-relative and must remain inside the
+canonical repository root after resolving symlink ancestors. A local relative
+path follows the same repository confinement; a local absolute path may point
+outside the repository. Runtime paths follow the local rule. User config cannot
+set a theme bundle path.
+When a theme bundle path is present it replaces named palette and visual-profile
+selection and produces a warning. The adapter passes the resolved canonical
+path as `theme.suppliedBundlePath`.
+## Publish block
+No provider means build-only operation, even if unused destination fields are
+present. When `provider` is `s3-static`, `s3Uri`, `publicBaseUrl`, and
+`awsRegion` are all required. `awsProfile` is optional and uses the normal AWS
+credential chain when absent. Destination roots are normalized without trailing
+slashes. Lifecycle callers must explicitly select publish durability; config
+alone never starts publishing.
+## Canonical output roots
+- Active project: `<resolved-project-path>/explainers/`, for both shared and
+  local projects.
+- Non-project OAT run: `.oat/repo/reference/explainers/`.
+- Direct core caller: an explicit `outputRoot`; the OAT adapter does not infer
+  one.
+Derived OAT roots reject traversal and must remain inside their canonical root
+after symlink resolution. The adapter validates all config and paths before the
+core creates output.
+## Run-request translation
+The adapter emits `explainer-kit.run-request/v1` with the requested recipe,
+slug, fact-base binding, mode, derived output root, resolved theme selection,
+privacy choice, and explicit durability strategy. Publish durability adds a
+complete `explainer-kit.publish-request/v1` whose `siteRoot` and
+`manifestPath` point inside `<outputRoot>/<slug>/`.