CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

inventory.mjsskills/rollout/scripts/

#!/usr/bin/env node
/**
 * rollout/inventory.mjs — build the delivery coverage from a migrated tree.
 *
 * Reads stardust/migrated/ (the platform-agnostic output of `migrate`) plus the
 * per-page _meta.json sidecars, and writes the rollout coverage:
 *   - stardust/rollout/coverage/pages.json     (one row per migrated page)
 *   - stardust/rollout/coverage/templates.json (grouping for delivery order/reuse)
 *   - stardust/rollout/rollout.json            (config + lastRun summary; created if absent)
 *
 * Idempotent + incremental: existing delivery status is preserved. When a page's
 * migrated HTML changed (sourceHash differs) after it was already deployed/verified,
 * it is re-flagged `stale` so the delivery loop re-delivers just that page — unless the row is
 * pinned (`delivery.pinned`, written by `update-coverage.mjs --gate <table> --pin` for a page replica's
 * first page first delivered on its own track): a pinned row keeps its delivery state across a
 * re-render, and the report names it.
 *
 * Phase 1 scope: pages + template grouping only. Block dedup (blocks.json) is a
 * first-class step deferred to Phase 2 — see notes/rollout/PLAN.md § 8.
 *
 * Template grouping: a page's `template` from its sidecar. An archetype (fidelityTier
 * `archetype` or renderBranch `A`) whose `template` is null — the migrate spec's form —
 * groups under its OWN slug, which its siblings name in their `template`; `type` is the
 * last resort. A template's representative is its archetype. Sidecars with an empty
 * `modules[]` are counted in the report: Phase B (blocks.mjs) dedups from them. A sidecar's
 * `widgets[] {id, href}` (code-only units, one /widgets/<path>/<name>.html link each) rides along
 * as the row's `widgets` and joins the template's block set under its id.
 *
 * Archetypes-only mode (`--state <state.json>`): the migrated tree holds only the
 * template archetypes (one per template); the full page roster lives in state.json.
 * Pages present only in state.json (not yet individually migrated) are merged in as
 * `content-pending` siblings — keyed to the archetype their `type` names, inheriting
 * that archetype's blocks, pushing no document. Block code ships from the archetypes;
 * sibling content is populated later by a separate content track.
 *
 * Rows added by `update-coverage.mjs --new` (a page built outside the migrated tree —
 * a search results page from the dynamics phase; `source.migratedHtml` carries the
 * origin marker `<origin>:<slug>` instead of a file path) are KEPT on a re-run, status
 * untouched, so the page is registered once — never re-registered after every
 * inventory run (a recorded hands-off run lost its search page from coverage, the
 * sitemap and verify this way). Such a row gives way only when the migrated tree now
 * holds a file for its slug, or a migrated page owns its path.
 *
 * Usage:
 *   node skills/rollout/scripts/inventory.mjs [--migrated <dir>] [--out <rolloutDir>] [--site-url <url>] [--state <state.json>]
 *   defaults: --migrated stardust/migrated  --out stardust/rollout
 */
import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, statSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { join, dirname, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
// the path rules (sidecar name, a file's key path, a roster URL's key path, the slug) are the shared library's (lib/paths.mjs),
// each pinned by skills/stardust/scripts/test/contracts-characterize.test.mjs under this script's name
import { pageWidgets, scopeOf, scopeLine, sidecarName as sidecarFor, treePath as deliveredPath, rosterPath as urlToDeliveredPath, pathSlug as pathToSlug } from './lib.mjs';

// --help prints this file's usage header, so an agent never reads the source to learn the flags.
if (process.argv.includes('--help') || process.argv.includes('-h')) {
  const src = readFileSync(new URL(import.meta.url), 'utf8');
  const header = src.match(/\/\*\*[\s\S]*?\*\//);
  console.log(header ? header[0].replace(/^\/\*\*\s*|\s*\*\/$/g, '').replace(/^\s*\* ?/gm, '').trim() : 'no usage header');
  process.exit(0);
}

function arg(name, fallback) {
  const i = process.argv.indexOf(`--${name}`);
  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
}

const MIGRATED = arg('migrated', 'stardust/migrated');
const OUT = arg('out', 'stardust/rollout');
const SITE_URL = arg('site-url', null);
const STATE = arg('state', null);

const STARDUST_VERSION = (() => {
  try {
    const here = dirname(fileURLToPath(import.meta.url));
    const pj = JSON.parse(readFileSync(join(here, '..', '..', '..', '.claude-plugin', 'plugin.json'), 'utf8'));
    return pj.version || '0.0.0';
  } catch { return '0.0.0'; }
})();

function sha256(buf) { return `sha256:${createHash('sha256').update(buf).digest('hex')}`; }

/** Recursively collect *.html under dir, skipping the assets/ bundle. */
function walkHtml(dir, root = dir, acc = []) {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    if (entry.name.startsWith('.')) continue;
    const full = join(dir, entry.name);
    if (entry.isDirectory()) {
      if (entry.name === 'assets') continue;
      walkHtml(full, root, acc);
    } else if (entry.name.endsWith('.html')) {
      acc.push(relative(root, full));
    }
  }
  return acc;
}

function readJSON(path, fallback = null) {
  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
}

/** The page that IS the template: migrate's Path A (fidelityTier `archetype`, renderBranch `A`). */
const isArchetype = (meta) => meta.fidelityTier === 'archetype' || meta.renderBranch === 'A';

if (!existsSync(MIGRATED)) {
  console.error(`rollout inventory: migrated tree not found at "${MIGRATED}". Run \`stardust migrate\` first.`);
  process.exit(1);
}

// --- Load prior coverage to preserve delivery state ----------------------------
const coverageDir = join(OUT, 'coverage');
const pagesPath = join(coverageDir, 'pages.json');
const templatesPath = join(coverageDir, 'templates.json');
const configPath = join(OUT, 'rollout.json');

const priorPages = readJSON(pagesPath, { pages: [] });
const priorBySlug = new Map((priorPages.pages || []).map((p) => [p.slug, p]));

// --- Inventory the migrated tree -----------------------------------------------
const htmlFiles = walkHtml(MIGRATED).sort();
// the source URL of each page (the join key with a spec's knowledge): the sidecar's, else state.json's by slug
const stateFile = STATE || (existsSync('stardust/state.json') ? 'stardust/state.json' : null);
const stateDoc = stateFile ? readJSON(stateFile, { pages: [] }) : { pages: [] };
const stateUrls = new Map((stateDoc.pages || []).filter((p) => p && p.slug && p.url).map((p) => [p.slug, p.url]));
const pages = [];
const pinnedChanged = []; // pinned rows whose migrated HTML changed: kept, not re-flagged stale

for (const relHtml of htmlFiles) {
  const absHtml = join(MIGRATED, relHtml);
  const sourceHash = sha256(readFileSync(absHtml));
  const sidecarRel = sidecarFor(relHtml);
  const meta = readJSON(join(MIGRATED, sidecarRel), {});
  const path = deliveredPath(relHtml);
  const slug = meta.slug || (path === '/' ? 'home' : path.replace(/^\//, ''));

  const prior = priorBySlug.get(slug);
  let delivery;
  if (prior && prior.delivery) {
    const changed = prior.source && prior.source.sourceHash !== sourceHash;
    if (changed && prior.delivery.pinned) {
      delivery = prior.delivery;
      pinnedChanged.push(slug);
    } else if (changed && ['deployed', 'verified'].includes(prior.delivery.status)) {
      delivery = { ...prior.delivery, status: 'stale' };
    } else {
      delivery = prior.delivery;
    }
  } else {
    delivery = { status: 'pending', deployedUrl: null, deployedAt: null, verifiedAt: null, error: null };
  }

  pages.push({
    slug,
    path,
    title: (meta.metadata && meta.metadata.title) || meta.slug || slug,
    templateId: meta.template || (isArchetype(meta) ? slug : null) || meta.type || null,
    source: {
      migratedHtml: join(MIGRATED, relHtml),
      metaJson: existsSync(join(MIGRATED, sidecarRel)) ? join(MIGRATED, sidecarRel) : null,
      sourceHash,
      sourceUrl: (meta.source && meta.source.url) || meta.sourceUrl || stateUrls.get(slug) || null,
    },
    blocks: Array.isArray(meta.modules) ? meta.modules : [],
    widgets: pageWidgets(meta),
    delivery,
  });
}

// --- Archetypes-only mode: merge content-pending siblings from state.json -------
// In --state mode each migrated archetype is keyed by its own fine slug (the
// archetypes are genuinely distinct templates that share only chrome). A roster
// page's `type` names the archetype slug it clones; it joins that archetype's
// template group as a `content-pending` sibling, inheriting the archetype's blocks
// and pushing no document of its own.
if (STATE) {
  for (const p of pages) p.templateId = p.slug;
  const archetypeBySlug = new Map(pages.map((p) => [p.slug, p]));
  const coveredPaths = new Set(pages.map((p) => p.path));
  const usedSlugs = new Set(pages.map((p) => p.slug));
  const state = readJSON(STATE, { pages: [] });
  for (const sp of (state.pages || [])) {
    if (!sp || !sp.url) continue;
    const path = urlToDeliveredPath(sp.url);
    if (coveredPaths.has(path)) continue; // the archetype itself — already inventoried
    // A roster sibling names the archetype it clones via `representative` (preferred)
    // or its `type`; that archetype supplies the template grouping + block set.
    const rep = archetypeBySlug.get(sp.representative) || archetypeBySlug.get(sp.type) || null;
    let slug = sp.slug && !usedSlugs.has(sp.slug) ? sp.slug : pathToSlug(path);
    while (usedSlugs.has(slug)) slug = `${slug}-x`;
    usedSlugs.add(slug);
    const csPath = sp.currentStatePath && existsSync(sp.currentStatePath) ? sp.currentStatePath : null;
    const sourceHash = csPath ? sha256(readFileSync(csPath)) : sha256(Buffer.from(String(sp.url)));
    const prior = priorBySlug.get(slug);
    const delivery = (prior && prior.delivery)
      ? prior.delivery
      : { status: 'content-pending', deployedUrl: null, deployedAt: null, verifiedAt: null, error: null };
    pages.push({
      slug,
      path,
      title: sp.title || slug,
      templateId: rep ? rep.slug : (sp.type || 'untyped'),
      representative: rep ? rep.slug : null,
      source: { migratedHtml: null, metaJson: null, sourceHash, currentStatePath: csPath, sourceUrl: sp.url },
      blocks: rep ? rep.blocks.slice() : [],
      widgets: rep ? rep.widgets.map((w) => ({ ...w })) : [],
      delivery,
    });
    coveredPaths.add(path);
  }
}

// --- Keep the rows update-coverage.mjs --new added (pages built outside the migrated tree) ---
// The origin marker in source.migratedHtml (`<origin>:<slug>`, never a path with a slash) identifies
// them. A prior row with the marker whose slug has no migrated file — and whose path no migrated page
// owns — is carried over untouched (status included); otherwise the migrated row wins.
const isOriginMarker = (s) => typeof s === 'string' && /^[a-z][a-z0-9-]*:[^/]+$/.test(s);
const migratedSlugs = new Set(pages.map((p) => p.slug));
const migratedPaths = new Set(pages.map((p) => p.path));
const kept = [];
for (const prior of (priorPages.pages || [])) {
  if (!prior || !prior.source || !isOriginMarker(prior.source.migratedHtml)) continue;
  if (migratedSlugs.has(prior.slug) || migratedPaths.has(prior.path)) continue;
  pages.push(prior);
  kept.push(prior.slug);
  migratedSlugs.add(prior.slug);
  migratedPaths.add(prior.path);
}

pages.sort((a, b) => a.slug.localeCompare(b.slug));

// --- Derive the template grouping ----------------------------------------------
const tmap = new Map();
for (const p of pages) {
  const id = p.templateId || 'untyped';
  if (!tmap.has(id)) tmap.set(id, { id, pages: [], blocks: new Set() });
  const t = tmap.get(id);
  t.pages.push(p.slug);
  p.blocks.forEach((b) => t.blocks.add(b));
  (p.widgets || []).forEach((w) => t.blocks.add(w.id));
}
const templates = [...tmap.values()].map((t) => {
  const tp = pages.filter((p) => t.pages.includes(p.slug));
  const count = (s) => tp.filter((p) => p.delivery.status === s).length;
  // The representative is the migrated archetype that converts the blocks — never a
  // content-pending sibling (which pushes no document).
  const rep = tp.find((p) => p.slug === t.id) || tp.find((p) => p.delivery.status !== 'content-pending') || tp[0];
  return {
    id: t.id,
    representativeSlug: (rep && rep.slug) || null,
    pages: t.pages.sort(),
    pageCount: t.pages.length,
    blocks: [...t.blocks].sort(),
    delivery: {
      verified: count('verified'),
      deployed: count('deployed'),
      contentPending: count('content-pending'),
      pending: t.pages.length - count('verified') - count('deployed') - count('content-pending'),
    },
  };
}).sort((a, b) => a.id.localeCompare(b.id));

// --- Counts summary ------------------------------------------------------------
const status = (s) => pages.filter((p) => p.delivery.status === s).length;
const counts = {
  total: pages.length,
  verified: status('verified'),
  deployed: status('deployed'),
  pending: status('pending'),
  contentPending: status('content-pending'),
  stale: status('stale'),
  failed: status('failed'),
};

// --- Write ---------------------------------------------------------------------
const now = new Date().toISOString();
mkdirSync(coverageDir, { recursive: true });

const prov = (writtenBy) => ({
  writtenBy, writtenAt: now, readArtifacts: STATE ? [MIGRATED, STATE] : [MIGRATED], stardustVersion: STARDUST_VERSION,
});

writeFileSync(pagesPath, `${JSON.stringify({ _provenance: prov('stardust:rollout/inventory'), generatedAt: now, pages }, null, 2)}\n`);
writeFileSync(templatesPath, `${JSON.stringify({ _provenance: prov('stardust:rollout/inventory'), generatedAt: now, templates }, null, 2)}\n`);

const priorConfig = readJSON(configPath, null);
const config = {
  _provenance: { writtenBy: 'stardust:rollout/inventory', writtenAt: now, stardustVersion: STARDUST_VERSION },
  target: 'aem-eds',
  site: {
    sourceUrl: SITE_URL || (priorConfig && priorConfig.site && priorConfig.site.sourceUrl) || 'about:blank',
    da: (priorConfig && priorConfig.site && priorConfig.site.da) || { org: '', site: '', ref: 'main' },
    liveHost: (priorConfig && priorConfig.site && priorConfig.site.liveHost) || null,
  },
  // the roster against the site: a capped roster is never reported as the site (stardust SKILL.md § Hands-off defaults)
  scope: scopeOf(counts.total, stateDoc.site),
  lastRun: { at: now, pages: counts, blocks: { total: 0, converted: 0, pending: 0 }, verifyFailures: 0 },
};
writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);

// --- Report --------------------------------------------------------------------
console.log(`rollout inventory → ${OUT}`);
console.log('='.repeat(60));
console.log(`Pages       ${counts.total} total · ${counts.verified} verified · ${counts.deployed} deployed · ${counts.pending} pending · ${counts.contentPending} content-pending · ${counts.stale} stale`);
if (config.scope) console.log(`Scope       ${scopeLine(config.scope)}`);
console.log(`Templates   ${templates.length} (${templates.map((t) => `${t.id}:${t.pageCount}`).join(', ')})`);
if (pinnedChanged.length) console.log(`Pinned      ${pinnedChanged.length} row(s) whose migrated HTML changed kept their delivery (delivered on their own track; \`update-coverage.mjs <slug> --status stale\` re-delivers): ${pinnedChanged.join(', ')}`);
if (kept.length) console.log(`Kept        ${kept.length} row(s) built outside the migrated tree (update-coverage.mjs --new), status untouched: ${kept.join(', ')}`);
const blockless = pages.filter((p) => p.source.metaJson && !p.blocks.length).length;
if (blockless) console.log(`Blocks      modules[] empty on ${blockless}/${pages.length} sidecars — Phase B (blocks.mjs) dedups from them: fill each page's block ids (composite sections; title, text, image, button, separator are default content) and re-run the inventory`);
const widgetIds = new Set(pages.flatMap((p) => (p.widgets || []).map((w) => w.id)));
if (widgetIds.size) console.log(`Widgets     ${widgetIds.size} distinct (${[...widgetIds].sort().join(', ')}) on ${pages.filter((p) => (p.widgets || []).length).length} pages — code only, one /widgets/ link per page`);
const todo = pages.filter((p) => ['pending', 'stale', 'failed'].includes(p.delivery.status));
if (todo.length) console.log(`To deliver  ${todo.length}: ${todo.slice(0, 8).map((p) => p.slug).join(', ')}${todo.length > 8 ? ' …' : ''}`);
else console.log('To deliver  0 — all pages delivered.');

skills

README.md

tile.json