Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
#!/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.');.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference