@decocms/parity 0.26.20 → 0.27.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 (3) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/dist/cli.js +222 -0
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
+ ## [0.27.0] — 2026-08-21
9
+
10
+ ### Added
11
+
12
+ * **`parity plan board` — the migration as a per-page kanban.** Every sampled page
13
+ sits in a lane (`triage` | `backlog` | `building` | `review` | `done` | `skipped`)
14
+ with the components blocking it. Lanes are **derived** from `pagePlan`, never
15
+ stored, so a page cannot read as done while a component it needs is missing —
16
+ the failure mode of the hand-typed page status. Two lists sit outside the lanes:
17
+ `shell` (global components, reported once because they block every page instead
18
+ of repeated per card) and `no page` (components the code defines that no sampled
19
+ page uses — common on `deco-fresh`, whose source inventory walks `sections/*.tsx`
20
+ with no page association; listed rather than hidden). `--json` for the
21
+ orchestrator. Plans predating page/component edges degrade to `triage` rather
22
+ than claiming false readiness.
23
+ * **`--board studio` — mirror the board into the deco Studio task board.** One card
24
+ per page in the client's org, so progress is visible without a terminal. Lanes map
25
+ onto the board's five fixed columns; `skipped` gets no card. Talks to the Studio's
26
+ `/mcp/self` endpoint with plain JSON-RPC over `fetch` (the MCP SDK would be a
27
+ dependency for one POST). The token decides the org — the task board tools take no
28
+ org parameter. Re-running does not duplicate: the sync lists first and matches on
29
+ title, then updates. **It never fails a run** — unset or unreachable Studio prints
30
+ the terminal board and exits 0.
31
+
32
+ ### Changed
33
+
34
+ * **Orchestrator + plugin integration.** `reconcile` now shows the board next to the
35
+ inventory and uses it to pick what to work on (the page furthest along that is not
36
+ done — finishing a page beats starting three); the per-page cycle refreshes the
37
+ board when a page closes and holds to one page at a time. `discovery` asks where
38
+ the board goes (`terminal`/`studio`) and **always** asks which stage the run is in
39
+ rather than silently defaulting, which is how a team building components ended up
40
+ with a queue of bundle-size and analytics issues. It also asks for `target.dir`
41
+ when it cannot resolve one. New `--stage` and `--board` arguments on
42
+ `/parity:migrate`. (`migration-orchestrator`, `commands/migrate`)
43
+
8
44
  ## [0.26.0] — 2026-08-21
9
45
 
10
46
  Fixes the failure mode found running the plugin on a mature FastStore target
package/dist/cli.js CHANGED
@@ -63880,6 +63880,54 @@ function pagePlan(plan, path, candUrl) {
63880
63880
  ready: counts.build === 0 && counts.validate === 0
63881
63881
  };
63882
63882
  }
63883
+ function pageColumn(page) {
63884
+ if (page.status === "skipped")
63885
+ return "skipped";
63886
+ if (page.status === "done")
63887
+ return "done";
63888
+ if (page.tasks === null || page.tasks.length === 0)
63889
+ return "triage";
63890
+ if (page.ready)
63891
+ return "review";
63892
+ const started = page.counts.settled + page.counts.validate + page.counts["as-is"] + page.counts.upgrade;
63893
+ return started > 0 ? "building" : "backlog";
63894
+ }
63895
+ function planBoard(plan, candUrl) {
63896
+ const columns = {
63897
+ triage: [],
63898
+ backlog: [],
63899
+ building: [],
63900
+ review: [],
63901
+ done: [],
63902
+ skipped: []
63903
+ };
63904
+ for (const p of plan.pages) {
63905
+ const page = pagePlan(plan, p.path, candUrl);
63906
+ if (!page)
63907
+ continue;
63908
+ const column = pageColumn(page);
63909
+ columns[column].push({
63910
+ path: page.path,
63911
+ kind: page.kind,
63912
+ column,
63913
+ blockers: (page.tasks ?? []).filter((t) => t.disposition === "build" && t.scope !== "global").map((t) => t.name),
63914
+ counts: page.counts,
63915
+ ready: page.ready
63916
+ });
63917
+ }
63918
+ const onAnyPage = new Set(plan.pages.flatMap((p) => (p.components ?? []).map(key)));
63919
+ const shell = [];
63920
+ const unassigned = [];
63921
+ for (const c of plan.components) {
63922
+ if (c.scope === "global") {
63923
+ if (disposition(c) === "build")
63924
+ shell.push(c.name);
63925
+ } else if (!onAnyPage.has(key(c.name))) {
63926
+ unassigned.push(c.name);
63927
+ }
63928
+ }
63929
+ return { url: plan.url, columns, shell, unassigned, sampled: plan.pages.length };
63930
+ }
63883
63931
  function setComponentVerified(plan, name, verdict2, at, note) {
63884
63932
  const k = key(name);
63885
63933
  const component = plan.components.find((c) => key(c.name) === k);
@@ -65174,6 +65222,104 @@ function sleep2(ms) {
65174
65222
 
65175
65223
  // src/commands/plan.ts
65176
65224
  import chalk18 from "chalk";
65225
+
65226
+ // src/board/studio.ts
65227
+ var LANE_TO_STUDIO = {
65228
+ triage: "triage",
65229
+ backlog: "todo",
65230
+ building: "in_progress",
65231
+ review: "in_review",
65232
+ done: "done",
65233
+ skipped: null
65234
+ };
65235
+ function studioConfigFromEnv(env = process.env) {
65236
+ const url = env.PARITY_STUDIO_URL;
65237
+ const token = env.PARITY_STUDIO_TOKEN;
65238
+ if (!url || !token)
65239
+ return null;
65240
+ return { url: url.replace(/\/+$/, ""), token };
65241
+ }
65242
+ function cardTitle(host, path) {
65243
+ return `[${host}] ${path}`;
65244
+ }
65245
+ function cardDescription(card) {
65246
+ const lines = [`kind: ${card.kind}`, `lane: ${card.column}`];
65247
+ if (card.blockers.length)
65248
+ lines.push(`blocked by: ${card.blockers.join(", ")}`);
65249
+ else if (card.column === "triage") {
65250
+ lines.push("scope not confirmed — no page/component edges yet");
65251
+ }
65252
+ return lines.join(`
65253
+ `);
65254
+ }
65255
+ function parseRpcBody(body) {
65256
+ const trimmed = body.trim();
65257
+ if (!trimmed.startsWith("event:") && !trimmed.startsWith("data:")) {
65258
+ return JSON.parse(trimmed);
65259
+ }
65260
+ const data2 = trimmed.split(`
65261
+ `).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).filter(Boolean);
65262
+ const last2 = data2[data2.length - 1];
65263
+ if (!last2)
65264
+ throw new Error("empty SSE response");
65265
+ return JSON.parse(last2);
65266
+ }
65267
+ var callTool2 = async (cfg, name, args) => {
65268
+ const res = await fetch(`${cfg.url}/mcp/self`, {
65269
+ method: "POST",
65270
+ headers: {
65271
+ "content-type": "application/json",
65272
+ accept: "application/json, text/event-stream",
65273
+ authorization: `Bearer ${cfg.token}`
65274
+ },
65275
+ body: JSON.stringify({
65276
+ jsonrpc: "2.0",
65277
+ id: 1,
65278
+ method: "tools/call",
65279
+ params: { name, arguments: args }
65280
+ })
65281
+ });
65282
+ if (!res.ok) {
65283
+ throw new Error(`${name}: HTTP ${res.status} ${await res.text().catch(() => "")}`);
65284
+ }
65285
+ const payload = parseRpcBody(await res.text());
65286
+ if (payload.error)
65287
+ throw new Error(`${name}: ${payload.error.message ?? "unknown error"}`);
65288
+ const result = payload.result;
65289
+ if (result?.isError) {
65290
+ const text3 = result.content?.map((c) => c.text).join(" ") ?? "tool reported an error";
65291
+ throw new Error(`${name}: ${text3}`);
65292
+ }
65293
+ return result?.structuredContent ?? {};
65294
+ };
65295
+ async function syncBoardToStudio(board, cfg, call = callTool2) {
65296
+ const host = new URL(board.url).host;
65297
+ const existing = await call(cfg, "TASK_BOARD_ITEM_LIST", {});
65298
+ const byTitle = new Map((existing.items ?? []).map((i) => [i.title, i]));
65299
+ const result = { created: 0, updated: 0, skipped: 0 };
65300
+ for (const cards of Object.values(board.columns)) {
65301
+ for (const card of cards) {
65302
+ const status = LANE_TO_STUDIO[card.column];
65303
+ if (!status) {
65304
+ result.skipped += 1;
65305
+ continue;
65306
+ }
65307
+ const title = cardTitle(host, card.path);
65308
+ const description = cardDescription(card);
65309
+ const found = byTitle.get(title);
65310
+ if (found) {
65311
+ await call(cfg, "TASK_BOARD_ITEM_UPDATE", { id: found.id, status, description });
65312
+ result.updated += 1;
65313
+ } else {
65314
+ await call(cfg, "TASK_BOARD_ITEM_CREATE", { title, description, status });
65315
+ result.created += 1;
65316
+ }
65317
+ }
65318
+ }
65319
+ return result;
65320
+ }
65321
+
65322
+ // src/commands/plan.ts
65177
65323
  var STATUSES = ["pending", "partial", "done", "as-is", "upgrade", "skipped"];
65178
65324
  var PAGE_STATUSES = ["pending", "code", "done", "skipped"];
65179
65325
  function planSetStatusCommand(dir, name, status) {
@@ -65376,6 +65522,76 @@ ${chalk18.bold("Pages")} (${pg.total}): ` + `${chalk18.green(`${pg.byStatus.done
65376
65522
  console.log("");
65377
65523
  return 0;
65378
65524
  }
65525
+ var COLUMN_ORDER = ["triage", "backlog", "building", "review", "done"];
65526
+ var COLUMN_STYLE = {
65527
+ triage: chalk18.magenta,
65528
+ backlog: chalk18.red,
65529
+ building: chalk18.yellow,
65530
+ review: chalk18.cyan,
65531
+ done: chalk18.green,
65532
+ skipped: chalk18.gray
65533
+ };
65534
+ async function planBoardCommand(dir, opts) {
65535
+ const plan = loadPlan(dir);
65536
+ if (!plan) {
65537
+ console.error(chalk18.red(`No migration-plan.json found in ${dir}`));
65538
+ console.error(chalk18.yellow("Run `parity migrate --url <prod>` first — no plan, no board."));
65539
+ return 1;
65540
+ }
65541
+ const board = planBoard(plan, opts.cand);
65542
+ if (opts.json) {
65543
+ console.log(JSON.stringify(board, null, 2));
65544
+ return 0;
65545
+ }
65546
+ console.log(chalk18.bold(`
65547
+ Board — ${board.url}`));
65548
+ console.log(chalk18.gray(`${board.sampled} sampled page(s) — the capture's sample, not every URL on the site.`));
65549
+ if (board.shell.length) {
65550
+ console.log(`
65551
+ ${chalk18.bold("shell")} ${chalk18.gray("(global — blocks every page)")}: ${chalk18.yellow(board.shell.join(", "))}`);
65552
+ }
65553
+ for (const column of COLUMN_ORDER) {
65554
+ const cards = board.columns[column];
65555
+ if (!cards.length)
65556
+ continue;
65557
+ console.log(`
65558
+ ${COLUMN_STYLE[column](chalk18.bold(column))} (${cards.length})`);
65559
+ for (const card of cards) {
65560
+ console.log(` ${card.path} ${chalk18.gray(`(${card.kind})`)}`);
65561
+ if (card.blockers.length) {
65562
+ console.log(chalk18.gray(` blocked by: ${card.blockers.join(", ")}`));
65563
+ }
65564
+ }
65565
+ }
65566
+ const skipped = board.columns.skipped;
65567
+ if (skipped.length) {
65568
+ console.log(`
65569
+ ${chalk18.gray(`skipped (${skipped.length}): ${skipped.map((c) => c.path).join(", ")}`)}`);
65570
+ }
65571
+ if (board.unassigned.length) {
65572
+ console.log(`
65573
+ ${chalk18.bold("no page")} ${chalk18.gray("(in the code, not seen on any sampled page)")}
65574
+ ${chalk18.gray(board.unassigned.join(", "))}`);
65575
+ }
65576
+ console.log("");
65577
+ if (opts.board === "studio") {
65578
+ const cfg = studioConfigFromEnv();
65579
+ if (!cfg) {
65580
+ console.log(chalk18.yellow(`Studio board skipped — set PARITY_STUDIO_URL and PARITY_STUDIO_TOKEN. Showing the terminal board instead.
65581
+ `));
65582
+ return 0;
65583
+ }
65584
+ try {
65585
+ const synced = await syncBoardToStudio(board, cfg);
65586
+ console.log(chalk18.green(`Studio board synced — ${synced.created} created, ${synced.updated} updated, ${synced.skipped} skipped.
65587
+ `));
65588
+ } catch (err) {
65589
+ console.log(chalk18.yellow(`Studio board unavailable (${err instanceof Error ? err.message : String(err)}). Showing the terminal board instead.
65590
+ `));
65591
+ }
65592
+ }
65593
+ return 0;
65594
+ }
65379
65595
 
65380
65596
  // src/commands/pr.ts
65381
65597
  import { existsSync as existsSync19, readFileSync as readFileSync23, writeFileSync as writeFileSync25 } from "node:fs";
@@ -68797,6 +69013,12 @@ program.command("plan").description("Inspect/update the migration-plan.json comp
68797
69013
  process.exit(planStatusCommand(opts.dir, Boolean(opts.json)));
68798
69014
  })).addCommand(new Command("page").description("Per-page worksheet: every component the capture saw on this page, what to do about it (build | validate | upgrade | as-is | settled), and a runnable `parity section` command for the checkable ones. The unit of work a migration closes is a page, not a global queue.").argument("<path>", "Page path, e.g. / or /refrigeracion").option("--dir <path>", "Directory holding migration-plan.json (default: the target repo's .parity/)", ".parity").option("--cand <url>", "Candidate base URL — required for runnable validation commands").option("--json", "Emit structured JSON instead of human-readable text", false).action((path, opts) => {
68799
69015
  process.exit(planPageCommand(opts.dir, path, { cand: opts.cand, json: Boolean(opts.json) }));
69016
+ })).addCommand(new Command("board").description("Per-page kanban: every sampled page in a derived lane (triage | backlog | building | review | done) with what blocks it. Lanes come from each page's components, so a page cannot read as done while a component it needs is missing.").option("--dir <path>", "Directory holding migration-plan.json (default: the target repo's .parity/)", ".parity").option("--cand <url>", "Candidate base URL — enriches cards with validation state").option("--board <where>", "terminal (default) | studio — push one card per page to the deco Studio task board (needs PARITY_STUDIO_URL + PARITY_STUDIO_TOKEN; falls back to terminal when unset or unreachable)", "terminal").option("--json", "Emit structured JSON instead of human-readable text", false).action(async (opts) => {
69017
+ process.exit(await planBoardCommand(opts.dir, {
69018
+ cand: opts.cand,
69019
+ json: Boolean(opts.json),
69020
+ board: opts.board
69021
+ }));
68800
69022
  })).addCommand(new Command("set-reference").description("Point a component's comparison at something other than prod (a site the better component came from), and record WHY it diverges. Without this, an intentional improvement is reported as a defect on every run.").argument("<name>", "Component name (case- and separator-insensitive)").requiredOption("--note <why>", "Why this component diverges — required, not decoration").option("--url <url>", "Reference site base URL (default: the plan's prod URL)").option("--selector <sel>", "Selector on the reference site, when it differs").option("--dir <path>", "Directory holding migration-plan.json (default: the target repo's .parity/)", ".parity").action((name, opts) => {
68801
69023
  process.exit(planSetReferenceCommand(opts.dir, name, {
68802
69024
  url: opts.url,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/parity",
3
- "version": "0.26.20",
3
+ "version": "0.27.0",
4
4
  "description": "E2E parity validator for site migrations. Compares prod vs cand and reports UI, functional, SEO, visual, and Web Vitals deltas with an LLM-ranked HTML report.",
5
5
  "type": "module",
6
6
  "license": "MIT",