npm - @laitszkin/apollo-toolkit - Versions diffs - 3.9.7 → 3.11.0 - Mend

@laitszkin/apollo-toolkit 3.9.7 → 3.11.0

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

package/init-project-html/sample-demo/resources/project-architecture/features/invite-code-registration/web-register-ui.html ADDED Viewed

@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html lang="en" data-atlas-page="submodule">
+<head>
+  <meta charset="utf-8">
+  <title>Invite-code registration · web-register-ui</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="../../assets/architecture.css">
+</head>
+<body>
+  <header class="submodule-header">
+    <nav class="submodule-breadcrumb"><a href="../../index.html">← Atlas</a> · <a href="index.html">← Invite-code registration</a></nav>
+    <h1>web-register-ui <small class="submodule-kind submodule-kind--ui">UI</small></h1>
+    <p class="submodule-role">React page that captures email, password, and invite code.</p>
+  </header>
+  <main class="submodule-main">
+    <section class="sub-io" aria-label="Function I/O">
+      <h2>Function I/O</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">In</th><th scope="col">Out</th><th scope="col">Side</th><th scope="col">Purpose</th></tr></thead>
+        <tbody>
+          <tr><td>handleSubmit</td><td>FormEvent</td><td>void</td><td>io</td><td>POSTs the registration payload and routes the response.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-vars" aria-label="Variables">
+      <h2>Variables</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">Type</th><th scope="col">Scope</th><th scope="col">Purpose</th></tr></thead>
+        <tbody>
+          <tr><td>email</td><td>string</td><td>call</td><td>Identity for the new account; required.</td></tr>
+          <tr><td>inviteCode</td><td>string</td><td>call</td><td>Token from the off-platform invite hand-off.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-dataflow" aria-label="Internal data flow">
+      <h2>Internal data flow</h2>
+      <svg class="sub-dataflow__svg" viewBox="0 0 400 264" role="img" aria-label="Internal dataflow">
+  <defs><marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker></defs>
+  <g class="sub-dataflow__step">
+    <rect x="20" y="20" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="44" text-anchor="middle">Collect form fields.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="200" y1="76" x2="200" y2="104" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <rect x="20" y="104" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="128" text-anchor="middle">POST /api/register with payload.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="200" y1="160" x2="200" y2="188" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <rect x="20" y="188" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="212" text-anchor="middle">On 2xx redirect to /welcome; otherwise surface</text>
+    <text x="200" y="228" text-anchor="middle">field-level errors.</text>
+  </g>
+</svg>
+    </section>
+    <section class="sub-errors" aria-label="Errors">
+      <h2>Errors</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">When</th><th scope="col">Means</th></tr></thead>
+        <tbody>
+          <tr><td>ErrInvalidCode</td><td>API returns 422 with `invite_code` reason.</td><td>Highlight the invite-code field with the API message.</td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+</body>
+</html>

package/init-project-html/sample-demo/resources/project-architecture/index.html ADDED Viewed

@@ -0,0 +1,234 @@
+<!DOCTYPE html>
+<html lang="en" data-atlas-page="macro">
+<head>
+  <meta charset="utf-8">
+  <title>Acme App — sample atlas</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="assets/architecture.css">
+</head>
+<body>
+  <header class="atlas-header">
+    <h1>Acme App — sample atlas</h1>
+    <p class="atlas-summary">Two end-to-end feature modules — minting invite codes and consuming them during account registration — produced by `apltk architecture` from a declarative YAML source. The macro diagram surfaces both feature clusters and every sub-module they own, plus the cross-feature data-row that carries an `invite_codes` row between them.</p>
+  </header>
+  <main class="atlas-main">
+    <section class="atlas-canvas" aria-label="Macro architecture diagram">
+      <div class="atlas-canvas__toolbar" role="toolbar" aria-label="Diagram controls">
+        <button type="button" data-pan-zoom="zoom-in" aria-label="Zoom in">+</button>
+        <button type="button" data-pan-zoom="zoom-out" aria-label="Zoom out">−</button>
+        <button type="button" data-pan-zoom="fit" aria-label="Reset view">Fit</button>
+      </div>
+      <div class="atlas-canvas__viewport" data-pan-zoom-viewport>
+<svg class="atlas-svg" viewBox="0 0 3989 453" role="img" aria-label="Project architecture atlas" data-atlas-svg="macro">
+  <defs>
+    <marker id="arrow-call" class="m-arrow m-arrow--call" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+    <marker id="arrow-return" class="m-arrow m-arrow--return" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+    <marker id="arrow-data-row" class="m-arrow m-arrow--data-row" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+    <marker id="arrow-failure" class="m-arrow m-arrow--failure" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+  </defs>
+  <g transform="translate(24,24)">
+    <g class="m-cluster" data-feature="get-invite-codes">
+      <rect class="m-cluster__bg" x="40.00" y="40.00" width="1650.00" height="325.00" rx="14" ry="14" />
+      <text class="m-cluster__title" x="865.00" y="66.00" text-anchor="middle">Get invite codes</text>
+    </g>
+    <g class="m-cluster" data-feature="invite-code-registration">
+      <rect class="m-cluster__bg" x="2091.00" y="100.00" width="1810.00" height="253.27" rx="14" ry="14" />
+      <text class="m-cluster__title" x="2996.00" y="126.00" text-anchor="middle">Invite-code registration</text>
+    </g>
+    <a class="m-node m-node--ui" href="features/get-invite-codes/web-get-invite-ui.html" data-feature="get-invite-codes" data-submodule="web-get-invite-ui">
+      <rect x="64.00" y="226.80" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="184.00" y="254.80" text-anchor="middle">web-get-invite-ui</text>
+      <text class="m-node__kind" x="184.00" y="278.80" text-anchor="middle">UI</text>
+      <text class="m-node__role" x="184.00" y="304.80" text-anchor="middle">React page that lets a signed-in mem…</text>
+    </a>
+    <a class="m-node m-node--api" href="features/get-invite-codes/public-api.html" data-feature="get-invite-codes" data-submodule="public-api">
+      <rect x="511.00" y="226.80" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="631.00" y="254.80" text-anchor="middle">public-api</text>
+      <text class="m-node__kind" x="631.00" y="278.80" text-anchor="middle">API</text>
+      <text class="m-node__role" x="631.00" y="304.80" text-anchor="middle">HTTP boundary for `/api/invites` POS…</text>
+    </a>
+    <a class="m-node m-node--service" href="features/get-invite-codes/invite-issuance-service.html" data-feature="get-invite-codes" data-submodule="invite-issuance-service">
+      <rect x="965.00" y="226.80" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="1085.00" y="254.80" text-anchor="middle">invite-issuance-service</text>
+      <text class="m-node__kind" x="1085.00" y="278.80" text-anchor="middle">Service</text>
+      <text class="m-node__role" x="1085.00" y="304.80" text-anchor="middle">Domain service that mints and persis…</text>
+    </a>
+    <a class="m-node m-node--pure-fn" href="features/get-invite-codes/invite-code-generator.html" data-feature="get-invite-codes" data-submodule="invite-code-generator">
+      <rect x="1426.00" y="129.00" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="1546.00" y="157.00" text-anchor="middle">invite-code-generator</text>
+      <text class="m-node__kind" x="1546.00" y="181.00" text-anchor="middle">Pure fn</text>
+      <text class="m-node__role" x="1546.00" y="207.00" text-anchor="middle">Pure helper that turns random bytes …</text>
+    </a>
+    <a class="m-node m-node--db" href="features/get-invite-codes/postgresql.html" data-feature="get-invite-codes" data-submodule="postgresql">
+      <rect x="1426.00" y="245.00" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="1546.00" y="273.00" text-anchor="middle">postgresql</text>
+      <text class="m-node__kind" x="1546.00" y="297.00" text-anchor="middle">DB</text>
+      <text class="m-node__role" x="1546.00" y="323.00" text-anchor="middle">Owns the `invite_codes` table (produ…</text>
+    </a>
+    <a class="m-node m-node--ui" href="features/invite-code-registration/web-register-ui.html" data-feature="invite-code-registration" data-submodule="web-register-ui">
+      <rect x="2115.00" y="189.00" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="2235.00" y="217.00" text-anchor="middle">web-register-ui</text>
+      <text class="m-node__kind" x="2235.00" y="241.00" text-anchor="middle">UI</text>
+      <text class="m-node__role" x="2235.00" y="267.00" text-anchor="middle">React page that captures email, pass…</text>
+    </a>
+    <a class="m-node m-node--api" href="features/invite-code-registration/public-api.html" data-feature="invite-code-registration" data-submodule="public-api">
+      <rect x="2569.00" y="189.00" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="2689.00" y="217.00" text-anchor="middle">public-api</text>
+      <text class="m-node__kind" x="2689.00" y="241.00" text-anchor="middle">API</text>
+      <text class="m-node__role" x="2689.00" y="267.00" text-anchor="middle">HTTP boundary for `/api/register` PO…</text>
+    </a>
+    <a class="m-node m-node--service" href="features/invite-code-registration/registration-service.html" data-feature="invite-code-registration" data-submodule="registration-service">
+      <rect x="3101.00" y="229.67" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="3221.00" y="257.67" text-anchor="middle">registration-service</text>
+      <text class="m-node__kind" x="3221.00" y="281.67" text-anchor="middle">Service</text>
+      <text class="m-node__role" x="3221.00" y="307.67" text-anchor="middle">Owns the registration transaction (c…</text>
+    </a>
+    <a class="m-node m-node--db" href="features/invite-code-registration/postgresql.html" data-feature="invite-code-registration" data-submodule="postgresql">
+      <rect x="3637.00" y="216.07" width="240.00" height="92.00" rx="10" ry="10" />
+      <text class="m-node__title" x="3757.00" y="244.07" text-anchor="middle">postgresql</text>
+      <text class="m-node__kind" x="3757.00" y="268.07" text-anchor="middle">DB</text>
+      <text class="m-node__role" x="3757.00" y="294.07" text-anchor="middle">Stores `users` rows and applies invi…</text>
+    </a>
+    <g class="m-edge m-edge--data-row" data-edge="cross-issuance-to-postgres-codes">
+      <path d="M1165.00,260.40 L1175.00,260.40 L1175.00,274.00 L1386.00,274.00" fill="none" marker-end="url(#arrow-data-row)" />
+      <text class="m-edge__label" x="1275.50" y="290.00" text-anchor="middle">INSERT invite_codes</text>
+    </g>
+    <g class="m-edge m-edge--data-row" data-edge="cross-postgres-codes-to-registration">
+      <path d="M1666.00,291.00 L3101.00,291.00" fill="none" marker-end="url(#arrow-data-row)" />
+      <text class="m-edge__label" x="1890.50" y="307.00" text-anchor="middle">read/consume invite_codes</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-ui-api">
+      <path d="M304.00,272.80 L511.00,272.80" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="407.50" y="288.80" text-anchor="middle">POST /api/invites</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-api-svc">
+      <path d="M751.00,272.80 L965.00,272.80" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="858.00" y="288.80" text-anchor="middle">Issue(ctx, userId)</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-svc-gen">
+      <path d="M1205.00,245.20 L1215.00,245.20 L1215.00,175.00 L1426.00,175.00" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="1315.50" y="191.00" text-anchor="middle">encode(rand)</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-svc-db">
+      <path d="M1205.00,282.00 L1400.00,282.00 L1400.00,291.00 L1426.00,291.00" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="1315.50" y="298.00" text-anchor="middle">INSERT invite_codes</text>
+    </g>
+    <g class="m-edge m-edge--return" data-edge="e-db-svc-return">
+      <path d="M1426.00,268.00 L1400.00,268.00 L1400.00,250.00 L1225.00,250.00 L1225.00,263.60 L1205.00,263.60" fill="none" marker-end="url(#arrow-return)" />
+      <text class="m-edge__label" x="1315.50" y="266.00" text-anchor="middle">rowid</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-ui-api">
+      <path d="M2355.00,235.00 L2569.00,235.00" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="2462.00" y="227.00" text-anchor="middle">POST /api/register</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-api-svc">
+      <path d="M2809.00,235.00 L3075.00,235.00 L3075.00,260.33 L3101.00,260.33" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="2955.00" y="227.00" text-anchor="middle">RegisterWithInvite(ctx, RegisterInput)</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-svc-db-select">
+      <path d="M3341.00,266.47 L3361.00,266.47 L3361.00,239.27 L3611.00,239.27 L3611.00,252.87 L3637.00,252.87" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="3491.00" y="255.27" text-anchor="middle">SELECT invite_codes FOR UPDATE</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-svc-db-insert">
+      <path d="M3341.00,284.87 L3371.00,284.87 L3371.00,271.27 L3637.00,271.27" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="3491.00" y="287.27" text-anchor="middle">INSERT users</text>
+    </g>
+    <g class="m-edge m-edge--call" data-edge="e-svc-db-update">
+      <path d="M3341.00,303.27 L3611.00,303.27 L3611.00,289.67 L3637.00,289.67" fill="none" marker-end="url(#arrow-call)" />
+      <text class="m-edge__label" x="3491.00" y="319.27" text-anchor="middle">UPDATE invite_codes.consumed_at</text>
+    </g>
+    <g class="m-edge m-edge--return" data-edge="e-db-svc-return">
+      <path d="M3637.00,234.47 L3621.00,234.47 L3621.00,207.27 L3351.00,207.27 L3351.00,248.07 L3341.00,248.07" fill="none" marker-end="url(#arrow-return)" />
+      <text class="m-edge__label" x="3491.00" y="223.27" text-anchor="middle">row | rows_affected</text>
+    </g>
+  </g>
+</svg>
+      </div>
+      <ol class="atlas-legend" aria-label="Edge legend">
+        <li><span class="legend-swatch legend-swatch--call"></span>call</li>
+        <li><span class="legend-swatch legend-swatch--return"></span>return</li>
+        <li><span class="legend-swatch legend-swatch--data-row"></span>data-row</li>
+        <li><span class="legend-swatch legend-swatch--failure"></span>failure</li>
+      </ol>
+    </section>
+    <section class="atlas-index" aria-label="Submodule index">
+      <h2>Submodule index</h2>
+      <ul class="atlas-submodule-index">
+        <li class="atlas-submodule-index__item">
+          <a href="features/get-invite-codes/web-get-invite-ui.html">
+            <span class="atlas-submodule-index__feature">Get invite codes</span>
+            <span class="atlas-submodule-index__sub">web-get-invite-ui</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--ui">UI</span>
+          </a>
+          <p class="atlas-submodule-index__role">React page that lets a signed-in member request a new invite code.</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/get-invite-codes/public-api.html">
+            <span class="atlas-submodule-index__feature">Get invite codes</span>
+            <span class="atlas-submodule-index__sub">public-api</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--api">API</span>
+          </a>
+          <p class="atlas-submodule-index__role">HTTP boundary for `/api/invites` POST requests.</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/get-invite-codes/invite-issuance-service.html">
+            <span class="atlas-submodule-index__feature">Get invite codes</span>
+            <span class="atlas-submodule-index__sub">invite-issuance-service</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--service">Service</span>
+          </a>
+          <p class="atlas-submodule-index__role">Domain service that mints and persists a single invite row per request.</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/get-invite-codes/invite-code-generator.html">
+            <span class="atlas-submodule-index__feature">Get invite codes</span>
+            <span class="atlas-submodule-index__sub">invite-code-generator</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--pure-fn">Pure fn</span>
+          </a>
+          <p class="atlas-submodule-index__role">Pure helper that turns random bytes into a printable invite code.</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/get-invite-codes/postgresql.html">
+            <span class="atlas-submodule-index__feature">Get invite codes</span>
+            <span class="atlas-submodule-index__sub">postgresql</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--db">DB</span>
+          </a>
+          <p class="atlas-submodule-index__role">Owns the `invite_codes` table (producer side of the cross-feature data row).</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/invite-code-registration/web-register-ui.html">
+            <span class="atlas-submodule-index__feature">Invite-code registration</span>
+            <span class="atlas-submodule-index__sub">web-register-ui</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--ui">UI</span>
+          </a>
+          <p class="atlas-submodule-index__role">React page that captures email, password, and invite code.</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/invite-code-registration/public-api.html">
+            <span class="atlas-submodule-index__feature">Invite-code registration</span>
+            <span class="atlas-submodule-index__sub">public-api</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--api">API</span>
+          </a>
+          <p class="atlas-submodule-index__role">HTTP boundary for `/api/register` POST requests.</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/invite-code-registration/registration-service.html">
+            <span class="atlas-submodule-index__feature">Invite-code registration</span>
+            <span class="atlas-submodule-index__sub">registration-service</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--service">Service</span>
+          </a>
+          <p class="atlas-submodule-index__role">Owns the registration transaction (consumer side of the invite_codes data row).</p>
+        </li>
+        <li class="atlas-submodule-index__item">
+          <a href="features/invite-code-registration/postgresql.html">
+            <span class="atlas-submodule-index__feature">Invite-code registration</span>
+            <span class="atlas-submodule-index__sub">postgresql</span>
+            <span class="atlas-submodule-index__kind atlas-submodule-index__kind--db">DB</span>
+          </a>
+          <p class="atlas-submodule-index__role">Stores `users` rows and applies invite-code state transitions inside the registration tx.</p>
+        </li>
+      </ul>
+    </section>
+  </main>
+  <script src="assets/viewer.client.js" defer></script>
+</body>
+</html>

package/init-project-html/scripts/architecture.js ADDED Viewed

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// architecture.js — thin shim over lib/atlas/cli.js.
+//
+// Backward-compatible legacy entrypoint:
+//   architecture.js                                # same as `open`
+//   architecture.js open  [--project <root>] [--no-open]
+//   architecture.js diff  [--project <root>] [--out <dir>] [--no-open]
+//
+// All new declarative verbs (feature add, submodule add, function add,
+// variable add, dataflow add|remove|reorder, error add, edge add, meta
+// set, actor add, render, validate, undo) are routed through
+// lib/atlas/cli.js, which owns layout, no-overlap, DOM, CSS, and pan/zoom.
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const newCli = require('../lib/atlas/cli');
+const ATLAS_REL = path.join('resources', 'project-architecture', 'index.html');
+const RESOURCES_REL = path.join('resources', 'project-architecture');
+const PLANS_REL = path.join('docs', 'plans');
+const DIFF_DIRNAME = 'architecture_diff';
+const REMOVED_FILE = '_removed.txt';
+const ATLAS_DIRNAME = 'atlas';
+const DEFAULT_OUT_REL = path.join('.apollo-toolkit', 'architecture-diff');
+const LEGACY_VERBS = new Set(['open', 'diff']);
+const USAGE = `apltk architecture — declarative atlas CLI.
+Usage:
+  apltk architecture                          Open resources/project-architecture/index.html
+  apltk architecture open                     Same as above
+  apltk architecture diff                     Render every architecture_diff/ as one paginated viewer
+  apltk architecture render                   Regenerate atlas HTML from current YAML state
+  apltk architecture validate                 Run schema + referential checks
+  apltk architecture feature add|set|remove   Manage feature modules
+  apltk architecture submodule add|set|remove Manage sub-modules
+  apltk architecture function|variable|dataflow|error|edge add|remove
+                                              Manage component rows and edges
+  apltk architecture meta set                 Update meta.title / meta.summary
+  apltk architecture actor add|remove         Manage top-level actors
+  apltk architecture undo                     Revert the most recent mutation
+  apltk architecture --help                   Show this help
+Global flags:
+  --project <root>   Project root (default: nearest ancestor with resources/project-architecture/)
+  --spec <spec_dir>  Mutations write to <spec_dir>/architecture_diff/atlas/
+  --no-render        Skip auto-render after a mutation
+  --no-open          For open/diff: skip launching the browser
+  --out <dir>        For diff: override viewer output directory
+  -h, --help         Show this help`;
+function parseArgs(argv) {
+  const args = [...argv];
+  const result = {
+    subcommand: 'open',
+    projectRoot: null,
+    out: null,
+    open: true,
+    help: false,
+  };
+  if (args.length > 0 && !args[0].startsWith('-')) {
+    const candidate = args[0];
+    if (candidate === 'open' || candidate === 'diff') {
+      result.subcommand = candidate;
+      args.shift();
+    }
+  }
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === '--help' || arg === '-h') {
+      result.help = true;
+    } else if (arg === '--project') {
+      const value = args.shift();
+      if (!value) throw new Error('Missing value for --project');
+      result.projectRoot = path.resolve(value);
+    } else if (arg === '--out') {
+      const value = args.shift();
+      if (!value) throw new Error('Missing value for --out');
+      result.out = path.resolve(value);
+    } else if (arg === '--no-open') {
+      result.open = false;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+  return result;
+}
+function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    if (fs.existsSync(path.join(dir, ATLAS_REL))) return dir;
+    if (fs.existsSync(path.join(dir, RESOURCES_REL, ATLAS_DIRNAME, 'atlas.index.yaml'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function openInBrowser(filePath) {
+  const platform = process.platform;
+  let command;
+  let args;
+  if (platform === 'darwin') { command = 'open'; args = [filePath]; }
+  else if (platform === 'win32') { command = 'cmd'; args = ['/c', 'start', '""', filePath]; }
+  else { command = 'xdg-open'; args = [filePath]; }
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch (_e) { /* best effort */ }
+}
+function walkArchitectureDiffDirs(plansRoot) {
+  const result = [];
+  if (!fs.existsSync(plansRoot)) return result;
+  function recurse(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.name === DIFF_DIRNAME) { result.push(full); continue; }
+      recurse(full);
+    }
+  }
+  recurse(plansRoot);
+  return result;
+}
+function walkAfterStateHtml(diffDir) {
+  const out = [];
+  function recurse(dir, relParts) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+    for (const entry of entries) {
+      if (entry.name === 'assets') continue;
+      if (entry.name === ATLAS_DIRNAME) continue;
+      if (entry.name === REMOVED_FILE) continue;
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      const nextRel = [...relParts, entry.name];
+      if (entry.isDirectory()) recurse(full, nextRel);
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith('.html')) {
+        out.push({ abs: full, rel: nextRel.join('/') });
+      }
+    }
+  }
+  recurse(diffDir, []);
+  return out;
+}
+function readRemovedManifest(diffDir) {
+  const manifestPath = path.join(diffDir, REMOVED_FILE);
+  if (!fs.existsSync(manifestPath)) return [];
+  return fs.readFileSync(manifestPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'));
+}
+function collectChanges(projectRoot) {
+  const resourcesRoot = path.join(projectRoot, RESOURCES_REL);
+  const plansRoot = path.join(projectRoot, PLANS_REL);
+  const diffDirs = walkArchitectureDiffDirs(plansRoot);
+  const changes = [];
+  for (const diffDir of diffDirs) {
+    const specDir = path.dirname(diffDir);
+    const specLabel = path.relative(projectRoot, specDir);
+    for (const after of walkAfterStateHtml(diffDir)) {
+      const beforeAbs = path.join(resourcesRoot, after.rel);
+      const beforeExists = fs.existsSync(beforeAbs);
+      changes.push({
+        kind: beforeExists ? 'modified' : 'added',
+        rel: after.rel,
+        spec: specLabel,
+        beforePath: beforeExists ? path.relative(projectRoot, beforeAbs) : null,
+        afterPath: path.relative(projectRoot, after.abs),
+      });
+    }
+    for (const removedRel of readRemovedManifest(diffDir)) {
+      const beforeAbs = path.join(resourcesRoot, removedRel);
+      if (!fs.existsSync(beforeAbs)) continue;
+      changes.push({
+        kind: 'removed',
+        rel: removedRel,
+        spec: specLabel,
+        beforePath: path.relative(projectRoot, beforeAbs),
+        afterPath: null,
+      });
+    }
+  }
+  changes.sort((a, b) => {
+    if (a.spec !== b.spec) return a.spec.localeCompare(b.spec);
+    if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
+    return a.rel.localeCompare(b.rel);
+  });
+  return changes;
+}
+function toViewerRel(outDir, projectRoot, projectRelPath) {
+  if (!projectRelPath) return null;
+  const absolute = path.resolve(projectRoot, projectRelPath);
+  const rel = path.relative(outDir, absolute);
+  return rel.split(path.sep).join('/');
+}
+function renderViewer({ changes, projectRoot, outDir }) {
+  return newCli.renderDiffViewer({ changes, projectRoot, outDir });
+}
+function runOpen(opts, io) {
+  const projectRoot = opts.projectRoot || findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    io.stderr.write(
+      `Could not find resources/project-architecture/index.html. Pass --project <root> or generate the atlas via the init-project-html skill.\n`,
+    );
+    return 1;
+  }
+  const atlas = path.join(projectRoot, ATLAS_REL);
+  if (!fs.existsSync(atlas)) {
+    io.stderr.write(`Atlas not found: ${atlas}\n`);
+    return 1;
+  }
+  io.stdout.write(`${atlas}\n`);
+  if (opts.open) openInBrowser(atlas);
+  return 0;
+}
+function runDiff(opts, io) {
+  const projectRoot = opts.projectRoot || findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    io.stderr.write(
+      `Could not find resources/project-architecture/index.html. Pass --project <root> or generate the atlas via the init-project-html skill.\n`,
+    );
+    return 1;
+  }
+  const outDir = opts.out || path.join(projectRoot, DEFAULT_OUT_REL);
+  fs.mkdirSync(outDir, { recursive: true });
+  const changes = collectChanges(projectRoot);
+  const html = renderViewer({ changes, projectRoot, outDir });
+  const indexPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(indexPath, html, 'utf8');
+  io.stdout.write(`${indexPath}\n`);
+  io.stdout.write(
+    `Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`,
+  );
+  if (opts.open) openInBrowser(indexPath);
+  return 0;
+}
+// main(argv, io) is sync and supports the legacy verbs `open` and
+// `diff` only. Tests rely on the sync return-code contract. All other
+// verbs go through dispatchAsync().
+function main(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (error) {
+    io.stderr.write(`${error.message}\n\n${USAGE}\n`);
+    return 1;
+  }
+  if (opts.help) {
+    io.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (opts.subcommand === 'open') return runOpen(opts, io);
+  if (opts.subcommand === 'diff') return runDiff(opts, io);
+  io.stderr.write(`Unknown subcommand: ${opts.subcommand}\n\n${USAGE}\n`);
+  return 1;
+}
+async function dispatchAsync(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+  return newCli.dispatch(argv, io);
+}
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const verb = argv[0];
+  if (!verb || verb.startsWith('-') || LEGACY_VERBS.has(verb)) {
+    process.exit(main(argv));
+  } else {
+    dispatchAsync(argv).then((code) => process.exit(code)).catch((err) => {
+      process.stderr.write(`${err && err.stack ? err.stack : err}\n`);
+      process.exit(1);
+    });
+  }
+}
+module.exports = {
+  parseArgs,
+  findProjectRoot,
+  collectChanges,
+  renderViewer,
+  toViewerRel,
+  walkArchitectureDiffDirs,
+  walkAfterStateHtml,
+  readRemovedManifest,
+  main,
+  dispatchAsync,
+};

package/katex/scripts/__pycache__/render_katex.cpython-312.pyc CHANGED Viewed

Binary file

package/lib/cli.js CHANGED Viewed

@@ -158,6 +158,8 @@ function buildHelpText({ version, colorEnabled }) {
     '  apltk all',
     '  apltk filter-logs app.log --start 2026-03-24T10:00:00Z',
     '  apltk create-specs "Membership upgrade flow" --change-name membership-upgrade-flow',
+    '  apltk architecture                       # open resources/project-architecture/index.html',
+    '  apltk architecture diff                  # paginated before/after view of all docs/plans/.../architecture_diff/',
     '  apltk tools',
     '  apollo-toolkit all',
     '',

package/lib/tool-runner.js CHANGED Viewed

@@ -3,6 +3,13 @@ const path = require('node:path');
 const { spawn } = require('node:child_process');
 const TOOL_COMMANDS = [
+  {
+    name: 'architecture',
+    skill: 'init-project-html',
+    script: 'init-project-html/scripts/architecture.js',
+    runner: 'node',
+    description: 'Open the project HTML architecture atlas, or render a paginated diff (`architecture diff`).',
+  },
   {
     name: 'filter-logs',
     skill: 'analyse-app-logs',