npm - plexus-agent-config - Versions diffs - 0.0.1 - Mend

plexus-agent-config 0.0.1

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 (351) hide show

package/node_modules/plexus-agent-config-web/public/architecture/config-sharing-map.html ADDED Viewed

@@ -0,0 +1,887 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Plexus Config Sharing Map</title>
+    <style>
+      :root {
+        --ink: #1b1a17;
+        --muted: #716c61;
+        --paper: #f6f3ea;
+        --panel: #fffdf8;
+        --line: #ddd7c8;
+        --line-strong: #c9bea9;
+        --accent: #ba613f;
+        --accent-2: #d3896f;
+        --green: #547c58;
+        --blue: #526f93;
+        --amber: #a97a35;
+        --rose: #a95445;
+        --shadow: 0 24px 80px rgba(72, 55, 32, 0.14);
+      }
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          linear-gradient(120deg, rgba(186, 97, 63, 0.08), transparent 38%),
+          radial-gradient(circle at 82% 18%, rgba(82, 111, 147, 0.10), transparent 34%),
+          var(--paper);
+        color: var(--ink);
+        font-family:
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Segoe UI",
+          sans-serif;
+      }
+      .page {
+        width: min(1440px, calc(100vw - 48px));
+        margin: 0 auto;
+        padding: 44px 0 56px;
+      }
+      .hero {
+        display: grid;
+        grid-template-columns: minmax(0, 1.15fr) minmax(280px, 0.85fr);
+        gap: 24px;
+        align-items: end;
+        margin-bottom: 24px;
+      }
+      .eyebrow {
+        margin: 0 0 12px;
+        color: var(--accent);
+        font-size: 12px;
+        font-weight: 700;
+        letter-spacing: 0.16em;
+        text-transform: uppercase;
+      }
+      h1 {
+        margin: 0;
+        max-width: 820px;
+        font-size: clamp(40px, 7vw, 88px);
+        line-height: 0.92;
+        letter-spacing: -0.045em;
+      }
+      .lead {
+        margin: 18px 0 0;
+        max-width: 680px;
+        color: var(--muted);
+        font-size: 18px;
+        line-height: 1.55;
+      }
+      .decision {
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: rgba(255, 253, 248, 0.78);
+        box-shadow: var(--shadow);
+        padding: 18px;
+      }
+      .decision strong {
+        display: block;
+        margin-bottom: 10px;
+        font-size: 14px;
+      }
+      .decision p {
+        margin: 0;
+        color: var(--muted);
+        font-size: 13px;
+        line-height: 1.55;
+      }
+      .canvas {
+        position: relative;
+        overflow: hidden;
+        min-height: 820px;
+        border: 1px solid var(--line);
+        border-radius: 24px;
+        background:
+          linear-gradient(rgba(27, 26, 23, 0.035) 1px, transparent 1px),
+          linear-gradient(90deg, rgba(27, 26, 23, 0.035) 1px, transparent 1px),
+          rgba(255, 253, 248, 0.76);
+        background-size: 28px 28px;
+        box-shadow: var(--shadow);
+      }
+      .grid {
+        position: relative;
+        z-index: 2;
+        display: grid;
+        grid-template-columns: 300px minmax(390px, 1fr) 360px;
+        gap: 28px;
+        height: 100%;
+        min-height: 820px;
+        padding: 28px;
+      }
+      .lane {
+        display: flex;
+        flex-direction: column;
+        gap: 14px;
+      }
+      .lane-title {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        height: 34px;
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+      }
+      .pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        border-radius: 999px;
+        background: rgba(186, 97, 63, 0.10);
+        color: var(--accent);
+        padding: 5px 9px;
+        font-size: 11px;
+        letter-spacing: 0;
+        text-transform: none;
+      }
+      .dot {
+        width: 7px;
+        height: 7px;
+        border-radius: 999px;
+        background: currentColor;
+      }
+      .card {
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: rgba(255, 253, 248, 0.92);
+        box-shadow: 0 12px 30px rgba(72, 55, 32, 0.08);
+      }
+      .card-head {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 12px;
+        border-bottom: 1px solid var(--line);
+        padding: 14px 15px;
+      }
+      .card-title {
+        margin: 0;
+        font-size: 17px;
+        font-weight: 760;
+        letter-spacing: -0.02em;
+      }
+      .tag {
+        border-radius: 7px;
+        background: #eee8da;
+        color: var(--muted);
+        padding: 4px 7px;
+        white-space: nowrap;
+        font-family:
+          ui-monospace,
+          SFMono-Regular,
+          Menlo,
+          Consolas,
+          monospace;
+        font-size: 11px;
+      }
+      .card-body {
+        padding: 14px 15px 16px;
+      }
+      .path {
+        display: block;
+        overflow-wrap: anywhere;
+        border-radius: 10px;
+        background: #f0eadf;
+        padding: 9px 10px;
+        color: #4b453b;
+        font-family:
+          ui-monospace,
+          SFMono-Regular,
+          Menlo,
+          Consolas,
+          monospace;
+        font-size: 12px;
+        line-height: 1.45;
+      }
+      .note {
+        margin: 11px 0 0;
+        color: var(--muted);
+        font-size: 12px;
+        line-height: 1.5;
+      }
+      .store {
+        position: relative;
+        margin-top: 22px;
+        border: 1px solid rgba(186, 97, 63, 0.38);
+        border-radius: 22px;
+        background:
+          linear-gradient(180deg, rgba(255, 253, 248, 0.94), rgba(248, 241, 229, 0.94)),
+          var(--panel);
+        box-shadow:
+          0 30px 90px rgba(186, 97, 63, 0.13),
+          inset 0 0 0 1px rgba(255, 255, 255, 0.50);
+        padding: 22px;
+      }
+      .store-top {
+        display: flex;
+        align-items: start;
+        justify-content: space-between;
+        gap: 18px;
+        margin-bottom: 18px;
+      }
+      .store h2 {
+        margin: 0;
+        font-size: 32px;
+        letter-spacing: -0.04em;
+      }
+      .store p {
+        margin: 8px 0 0;
+        color: var(--muted);
+        font-size: 13px;
+        line-height: 1.55;
+      }
+      .layers {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 12px;
+        margin-bottom: 16px;
+      }
+      .layer {
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: rgba(255, 253, 248, 0.84);
+        padding: 14px;
+      }
+      .layer h3 {
+        margin: 0 0 9px;
+        font-size: 15px;
+      }
+      .layer ul,
+      .mechanism ul {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+      }
+      .layer li,
+      .mechanism li {
+        display: flex;
+        align-items: start;
+        gap: 8px;
+        color: var(--muted);
+        font-size: 12px;
+        line-height: 1.5;
+      }
+      .layer li + li,
+      .mechanism li + li {
+        margin-top: 6px;
+      }
+      .bullet {
+        margin-top: 7px;
+        width: 6px;
+        height: 6px;
+        flex: 0 0 6px;
+        border-radius: 99px;
+        background: var(--accent);
+      }
+      .mechanisms {
+        display: grid;
+        grid-template-columns: repeat(3, 1fr);
+        gap: 12px;
+      }
+      .mechanism {
+        min-height: 182px;
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: rgba(255, 253, 248, 0.78);
+        padding: 14px;
+      }
+      .mechanism h3 {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin: 0 0 10px;
+        font-size: 15px;
+      }
+      .chip {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 28px;
+        height: 22px;
+        border-radius: 7px;
+        color: white;
+        font-size: 11px;
+        font-weight: 800;
+      }
+      .chip.rules {
+        background: var(--green);
+      }
+      .chip.skills {
+        background: var(--blue);
+      }
+      .chip.mcp {
+        background: var(--accent);
+      }
+      .agents {
+        display: grid;
+        gap: 10px;
+        margin-top: 22px;
+      }
+      .agent {
+        display: grid;
+        grid-template-columns: 112px 1fr;
+        gap: 10px;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 13px;
+        background: rgba(255, 253, 248, 0.84);
+        padding: 10px;
+      }
+      .agent strong {
+        font-size: 13px;
+      }
+      .agent code {
+        display: block;
+        color: var(--muted);
+        font-size: 11px;
+        line-height: 1.45;
+        white-space: normal;
+      }
+      .backup {
+        margin-top: auto;
+        border-color: rgba(169, 122, 53, 0.38);
+      }
+      .backup .card-title {
+        color: var(--amber);
+      }
+      .flow-strip {
+        position: relative;
+        z-index: 2;
+        display: grid;
+        grid-template-columns: 1fr 46px 1.25fr 46px 1fr;
+        gap: 10px;
+        align-items: center;
+        padding: 24px 28px 0;
+      }
+      .flow-node {
+        display: flex;
+        min-height: 56px;
+        align-items: center;
+        justify-content: center;
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: rgba(255, 253, 248, 0.86);
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 760;
+        letter-spacing: 0.11em;
+        text-align: center;
+        text-transform: uppercase;
+      }
+      .flow-node.primary {
+        border-color: rgba(186, 97, 63, 0.42);
+        background: rgba(186, 97, 63, 0.08);
+        color: var(--accent);
+      }
+      .flow-arrow {
+        position: relative;
+        height: 2px;
+        border-radius: 999px;
+        background: var(--line-strong);
+      }
+      .flow-arrow::after {
+        position: absolute;
+        top: 50%;
+        right: -2px;
+        width: 9px;
+        height: 9px;
+        border-top: 2px solid var(--line-strong);
+        border-right: 2px solid var(--line-strong);
+        content: "";
+        transform: translateY(-50%) rotate(45deg);
+      }
+      .channel-map {
+        margin-top: 16px;
+        display: grid;
+        gap: 10px;
+      }
+      .channel-row {
+        display: grid;
+        grid-template-columns: 92px minmax(120px, 1fr) minmax(154px, 0.85fr);
+        gap: 10px;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 13px;
+        background: rgba(255, 253, 248, 0.78);
+        padding: 10px;
+      }
+      .channel-name {
+        display: inline-flex;
+        align-items: center;
+        gap: 7px;
+        font-size: 13px;
+        font-weight: 760;
+      }
+      .channel-dot {
+        width: 9px;
+        height: 9px;
+        border-radius: 999px;
+        background: currentColor;
+      }
+      .channel-line {
+        position: relative;
+        min-height: 30px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        color: var(--muted);
+        font-family:
+          ui-monospace,
+          SFMono-Regular,
+          Menlo,
+          Consolas,
+          monospace;
+        font-size: 11px;
+        text-align: center;
+      }
+      .channel-line::before {
+        position: absolute;
+        top: 50%;
+        right: 0;
+        left: 0;
+        z-index: 0;
+        height: 2px;
+        border-radius: 999px;
+        background: currentColor;
+        content: "";
+        opacity: 0.34;
+      }
+      .channel-line::after {
+        position: absolute;
+        top: 50%;
+        right: 0;
+        width: 8px;
+        height: 8px;
+        border-top: 2px solid currentColor;
+        border-right: 2px solid currentColor;
+        content: "";
+        opacity: 0.60;
+        transform: translateY(-50%) rotate(45deg);
+      }
+      .channel-line span {
+        position: relative;
+        z-index: 1;
+        border: 1px solid var(--line);
+        border-radius: 999px;
+        background: var(--panel);
+        padding: 4px 8px;
+      }
+      .channel-target {
+        border-radius: 10px;
+        background: #f0eadf;
+        padding: 8px 9px;
+        color: #4b453b;
+        font-family:
+          ui-monospace,
+          SFMono-Regular,
+          Menlo,
+          Consolas,
+          monospace;
+        font-size: 11px;
+        line-height: 1.35;
+      }
+      .channel-row.rules {
+        color: var(--green);
+      }
+      .channel-row.skills {
+        color: var(--blue);
+      }
+      .channel-row.mcp {
+        color: var(--accent);
+      }
+      .legend {
+        display: grid;
+        grid-template-columns: repeat(4, 1fr);
+        gap: 12px;
+        margin-top: 18px;
+      }
+      .legend-item {
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        background: rgba(255, 253, 248, 0.78);
+        padding: 12px;
+      }
+      .legend-item strong {
+        display: block;
+        margin-bottom: 4px;
+        font-size: 13px;
+      }
+      .legend-item span {
+        color: var(--muted);
+        font-size: 12px;
+        line-height: 1.45;
+      }
+      @media (max-width: 1100px) {
+        .hero,
+        .grid,
+        .mechanisms,
+        .legend {
+          grid-template-columns: 1fr;
+        }
+        .canvas {
+          min-height: 0;
+        }
+        .grid {
+          min-height: 0;
+        }
+        .flow-strip,
+        .channel-row {
+          grid-template-columns: 1fr;
+        }
+        .flow-arrow {
+          height: 24px;
+          width: 2px;
+          justify-self: center;
+        }
+        .flow-arrow::after {
+          top: auto;
+          right: 50%;
+          bottom: -2px;
+          transform: translateX(50%) rotate(135deg);
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main class="page">
+      <section class="hero">
+        <div>
+          <p class="eyebrow">Plexus architecture</p>
+          <h1>One local source, native files everywhere.</h1>
+          <p class="lead">
+            Plexus keeps rules, skills, and MCP servers in a canonical store, then projects them
+            into each AI agent using the least invasive reversible mechanism for that file type.
+          </p>
+        </div>
+        <aside class="decision">
+          <strong>Is this the optimal solution?</strong>
+          <p>
+            For a local-first, multi-agent workstation: yes as a default. It uses symlinks for
+            single-purpose assets, partial writes for shared agent files, and backups before native
+            paths are touched.
+          </p>
+        </aside>
+      </section>
+      <section class="canvas" aria-label="Plexus config sharing diagram">
+        <div class="flow-strip" aria-label="High level flow">
+          <div class="flow-node">Native import</div>
+          <div class="flow-arrow" aria-hidden="true"></div>
+          <div class="flow-node primary">Merge in ~/.config/plexus</div>
+          <div class="flow-arrow" aria-hidden="true"></div>
+          <div class="flow-node">Native projection</div>
+        </div>
+        <div class="grid">
+          <section class="lane">
+            <div class="lane-title">
+              Native import
+              <span class="pill"><span class="dot"></span> optional</span>
+            </div>
+            <article class="card">
+              <div class="card-head">
+                <h2 class="card-title">Existing agent files</h2>
+                <span class="tag">read</span>
+              </div>
+              <div class="card-body">
+                <code class="path">~/.claude/CLAUDE.md<br />~/.codex/config.toml<br />~/.cursor/mcp.json</code>
+                <p class="note">
+                  Share config everywhere can import native rules, skills, and MCPs before applying
+                  the merged baseline back to enabled agents.
+                </p>
+              </div>
+            </article>
+            <article class="card">
+              <div class="card-head">
+                <h2 class="card-title">Conflict resolver</h2>
+                <span class="tag">primary</span>
+              </div>
+              <div class="card-body">
+                <code class="path">preferred agent wins identical IDs with different bodies</code>
+                <p class="note">
+                  If Codex and Claude Code both define the same skill or MCP differently, Plexus
+                  uses the selected primary source for one-click mode.
+                </p>
+              </div>
+            </article>
+            <article class="card backup">
+              <div class="card-head">
+                <h2 class="card-title">Backup rail</h2>
+                <span class="tag">revert</span>
+              </div>
+              <div class="card-body">
+                <code class="path">~/.config/plexus/backups/</code>
+                <p class="note">
+                  Native files are snapshotted before writes. Real directories that block symlinks
+                  are quarantined under _collisions instead of overwritten in place.
+                </p>
+              </div>
+            </article>
+          </section>
+          <section class="lane">
+            <div class="lane-title">
+              Canonical store
+              <span class="pill"><span class="dot"></span> source of truth</span>
+            </div>
+            <div class="store">
+              <div class="store-top">
+                <div>
+                  <h2>~/.config/plexus</h2>
+                  <p>
+                    Team and personal layers are merged into one effective view. Personal overrides
+                    team when the same ID exists in both layers.
+                  </p>
+                </div>
+                <span class="tag">local-first</span>
+              </div>
+              <div class="layers">
+                <div class="layer">
+                  <h3>Team layer</h3>
+                  <ul>
+                    <li><span class="bullet"></span><span>Subscribed config repository</span></li>
+                    <li><span class="bullet"></span><span>Shared skills and MCP baselines</span></li>
+                    <li><span class="bullet"></span><span>Optional organization rules</span></li>
+                  </ul>
+                </div>
+                <div class="layer">
+                  <h3>Personal layer</h3>
+                  <ul>
+                    <li><span class="bullet"></span><span>User overrides and local additions</span></li>
+                    <li><span class="bullet"></span><span>Imported native agent config</span></li>
+                    <li><span class="bullet"></span><span>Wins over team for duplicate IDs</span></li>
+                  </ul>
+                </div>
+              </div>
+              <div class="mechanisms">
+                <article class="mechanism">
+                  <h3><span class="chip rules">R</span>Rules</h3>
+                  <ul>
+                    <li><span class="bullet"></span><span>Canonical file: rules/global.md</span></li>
+                    <li><span class="bullet"></span><span>Applied to CLAUDE.md, AGENTS.md, GEMINI.md</span></li>
+                    <li><span class="bullet"></span><span>Symlink first, copy fallback</span></li>
+                  </ul>
+                </article>
+                <article class="mechanism">
+                  <h3><span class="chip skills">S</span>Skills</h3>
+                  <ul>
+                    <li><span class="bullet"></span><span>Canonical folder: skills/&lt;id&gt;/SKILL.md</span></li>
+                    <li><span class="bullet"></span><span>Per-agent enablement from frontmatter</span></li>
+                    <li><span class="bullet"></span><span>Directory symlink first, copy fallback</span></li>
+                  </ul>
+                </article>
+                <article class="mechanism">
+                  <h3><span class="chip mcp">M</span>MCP</h3>
+                  <ul>
+                    <li><span class="bullet"></span><span>Canonical YAML: mcp/servers.yaml</span></li>
+                    <li><span class="bullet"></span><span>Shared native files get partial writes</span></li>
+                    <li><span class="bullet"></span><span>Exclusive native files become cache symlinks</span></li>
+                  </ul>
+                </article>
+              </div>
+              <div class="channel-map" aria-label="Sync channels">
+                <div class="channel-row rules">
+                  <div class="channel-name"><span class="channel-dot"></span>Rules</div>
+                  <div class="channel-line"><span>file symlink</span></div>
+                  <div class="channel-target">CLAUDE.md<br />AGENTS.md<br />GEMINI.md</div>
+                </div>
+                <div class="channel-row skills">
+                  <div class="channel-name"><span class="channel-dot"></span>Skills</div>
+                  <div class="channel-line"><span>directory symlink</span></div>
+                  <div class="channel-target">skills/&lt;id&gt;<br />commands/&lt;id&gt;</div>
+                </div>
+                <div class="channel-row mcp">
+                  <div class="channel-name"><span class="channel-dot"></span>MCP</div>
+                  <div class="channel-line"><span>partial-write / cache link</span></div>
+                  <div class="channel-target">mcpServers<br />mcp_servers<br />.cache/mcp</div>
+                </div>
+              </div>
+            </div>
+          </section>
+          <section class="lane">
+            <div class="lane-title">
+              Native projection
+              <span class="pill"><span class="dot"></span> agent-readable</span>
+            </div>
+            <article class="card">
+              <div class="card-head">
+                <h2 class="card-title">Rules targets</h2>
+                <span class="tag">symlink</span>
+              </div>
+              <div class="card-body">
+                <code class="path">~/.claude/CLAUDE.md -> rules/global.md<br />~/.codex/AGENTS.md -> rules/global.md</code>
+                <p class="note">
+                  Agents keep reading their official instruction filename, but that path points to
+                  the same Plexus-managed baseline.
+                </p>
+              </div>
+            </article>
+            <article class="card">
+              <div class="card-head">
+                <h2 class="card-title">Skill targets</h2>
+                <span class="tag">dir link</span>
+              </div>
+              <div class="card-body">
+                <code class="path">~/.codex/skills/&lt;id&gt; -> skills/&lt;id&gt;<br />~/.claude/skills/&lt;id&gt; -> skills/&lt;id&gt;</code>
+                <p class="note">
+                  This is the cleanest part of the system: one folder, many native locations, no
+                  format translation.
+                </p>
+              </div>
+            </article>
+            <article class="card">
+              <div class="card-head">
+                <h2 class="card-title">MCP targets</h2>
+                <span class="tag">hybrid</span>
+              </div>
+              <div class="card-body">
+                <code class="path">shared: rewrite only mcpServers / mcp_servers<br />exclusive: native file -> .cache/mcp/&lt;agent&gt;.json</code>
+                <p class="note">
+                  Claude Code, Codex, Gemini, and Qwen keep their private config. Cursor and Factory
+                  can safely point to Plexus-owned cache files.
+                </p>
+              </div>
+            </article>
+            <div class="agents">
+              <div class="agent">
+                <strong>Claude Code</strong>
+                <code>shared MCP, rule symlink, skill dir symlinks</code>
+              </div>
+              <div class="agent">
+                <strong>Cursor</strong>
+                <code>exclusive MCP symlink, command dir symlinks</code>
+              </div>
+              <div class="agent">
+                <strong>Codex</strong>
+                <code>TOML partial-write, AGENTS.md, skills</code>
+              </div>
+              <div class="agent">
+                <strong>Gemini / Qwen</strong>
+                <code>JSON partial-write, native instruction file, skills</code>
+              </div>
+              <div class="agent">
+                <strong>Factory Droid</strong>
+                <code>exclusive MCP symlink, skills</code>
+              </div>
+            </div>
+          </section>
+        </div>
+      </section>
+      <section class="legend" aria-label="sync mechanism legend">
+        <div class="legend-item">
+          <strong>Symlink-first</strong>
+          <span>Best for rules and skills because each native path can point to one canonical file or folder.</span>
+        </div>
+        <div class="legend-item">
+          <strong>Partial-write</strong>
+          <span>Best for shared MCP files because auth, profiles, and app state must remain untouched.</span>
+        </div>
+        <div class="legend-item">
+          <strong>Cache symlink</strong>
+          <span>Best for exclusive MCP files because Plexus can own the whole file safely.</span>
+        </div>
+        <div class="legend-item">
+          <strong>Backup first</strong>
+          <span>Every native write is reversible from snapshots or collision quarantine.</span>
+        </div>
+      </section>
+    </main>
+  </body>
+</html>