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

dynamics-plan.mjsskills/dynamics/scripts/

#!/usr/bin/env node
/**
 * dynamics-plan.mjs — stardust:dynamics Phase 3 (triage draft).
 *
 * Turns `_dynamics.json` into a draft inventory: one row per finding with the
 * four axes pre-filled from the catalogue (class · disposition · reproducibility
 * · status) plus pattern, phase, the owner decision it needs and `target`, the
 * delivery form (block | widget | runtime | content | embed — reference/triage.md
 * § Target): `widget` for client-compute tools, search boxes, definition-driven
 * forms with no authored copy (form-less control groups), locators and the
 * chrome's sign-in / account / cart UI. Two probes
 * sharpen the draft when a target exists:
 *   --target-origin <eds host>   GET every recorded first-party API path on the
 *                                target; 4xx / network error → `hostBound`
 *   --migrated <dir>             scan migrated HTML for the feature's evidence
 *                                tokens → `alreadyDelivered` (never rebuild what
 *                                the capture pipeline already shipped)
 *   --knowledge [dir]            a spec's knowledge (default stardust/spec/knowledge): its curated features become rows
 *                                (`source: spec`, axes as judged, decision = the linked open questions' answer or
 *                                default); with no --in file, the draft is the spec's rows alone; its search probes
 *                                become dynamic-features.generated-parity.json: one search-query check per probe with
 *                                the source's expectations (fill resultSelector, then curate it into parity.json)
 *   --chrome [file]              the header contract (default stardust/chrome/header-contract.json): one row per
 *                                control family it records (menus, drawer, search, cart, account, locale); the UI is
 *                                rebuilt per the contract and gated by chrome-compare, the data side is the row's decision
 * The run curates the draft into `stardust/dynamic-features.md` (reference/triage.md).
 *
 *   node dynamics-plan.mjs [--in stardust/current/_dynamics.json] [--out stardust/dynamics]
 *        [--target-origin https://…] [--auth-header "token …" | --token-env SITE_TOKEN] [--migrated stardust/migrated]
 *        [--martech [spec-martech dir or a spec's knowledge dir, default stardust/martech]] [--knowledge [dir]] [--chrome [file]]
 *
 * Writes (under --out, default stardust/dynamics):
 *   dynamic-features.generated-plan.json   one row per finding, the four axes pre-filled, with _provenance
 *   dynamic-features.generated-plan.md     the same rows as a table + triage counts by phase
 * With --martech only (the owner asked to carry the martech over — reference/martech.md):
 *   stardust/martech-contract.json         CMP + tag-manager routes, all disabled (martech.mjs)
 *   stardust/martech-handoff.md            how to enable, consent model, routes, rewrite sheet
 * The summary line goes to stderr. Exit 0 on completion; a missing --in file throws (exit 1).
 */
/* eslint-disable no-await-in-loop, no-restricted-syntax, max-len */
import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { arg, readJSON, writeJSON, writeText, provenance, resolveAuthHeader, probe } from './lib.mjs';
import { buildContract, readEvidence, renderHandoff } from './martech.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);
}

const IN = arg('in', 'stardust/current/_dynamics.json');
const OUT = arg('out', 'stardust/dynamics');
const TARGET = arg('target-origin');
const MIGRATED = arg('migrated');
const MARTECH = arg('martech') === true ? 'stardust/martech' : arg('martech');
const CONTRACT = 'stardust/martech-contract.json';
const KNOWLEDGE = arg('knowledge') === true ? 'stardust/spec/knowledge' : arg('knowledge');
const CHROME = arg('chrome') === true ? 'stardust/chrome/header-contract.json' : arg('chrome');
const d = (KNOWLEDGE || CHROME) && !existsSync(IN) ? { pages: {}, findings: [] } : readJSON(IN);
const probed = Object.keys(d.pages).length;

// catalogue: first matching rule wins. disposition ∈ rebuild-native | index-backed | data-fed | embed-passthrough | client-only | static-snapshot | decided-out
// reproducibility ∈ self | needs-credential | needs-human-capture | needs-backend | needs-business-decision (reference/triage.md)
const RULES = [
  { when: (f) => f.class === 'S' && /site search form/.test(f.feature), pattern: 'search-index-backed', disposition: 'index-backed', repro: 'self', phase: 'search', decision: 'none (corpus = the migrated pages; second corpora stay out)' },
  { when: (f) => f.class === 'S' && /first-party API/.test(f.feature), pattern: 'off-origin-data', disposition: 'data-fed', repro: 'needs-business-decision', phase: 'off-origin data', decision: 'datasource ownership / same-origin routing on production' },
  { when: (f) => f.class === 'S', pattern: 'search-index-backed', disposition: 'index-backed', repro: 'self', phase: 'search', decision: 'replace the hosted search service?' },
  { when: (f) => f.class === 'A' && /first-party API/.test(f.feature) && /auth|session|login|shortlist|cart|basket|account/i.test(f.feature), pattern: 'decided-out', disposition: 'decided-out', repro: 'needs-backend', phase: 'register', decision: 'none (session-bound off-origin)' },
  { when: (f) => f.class === 'A' && /first-party API/.test(f.feature), pattern: 'off-origin-data', disposition: 'data-fed', repro: 'needs-business-decision', phase: 'off-origin data', decision: 'which tier for the target host; consumer on the migrated pages?' },
  { when: (f) => f.class === 'D', pattern: 'sheet-sync', disposition: 'data-fed', repro: 'self', phase: 'data', decision: 'none (sync from the source origin)' },
  { when: (f) => f.class === 'A' && /settings object/.test(f.feature), pattern: 'read-settings', disposition: 'static-snapshot', repro: 'self', phase: 'detect', decision: '— (keys name endpoints, ids, vendors)' },
  { when: (f) => f.class === 'A' && /experimentation/.test(f.feature), pattern: 'consent-gated-tags', disposition: 'embed-passthrough', repro: 'needs-business-decision', phase: 'tags', decision: 'which experiments move to the new host' },
  { when: (f) => f.class === 'A', pattern: 'inspect', disposition: 'static-snapshot', repro: 'needs-human-capture', phase: 'detect', decision: 'inspect the XHR, add a vendor row' },
  { when: (f) => f.class === 'T' && /consent/.test(f.feature), pattern: 'consent-gated-tags', disposition: 'embed-passthrough', repro: 'needs-business-decision', phase: 'tags', decision: 'CMP domain script reuse on the new host' },
  { when: (f) => f.class === 'T' && /mount/.test(f.feature), pattern: 'embed-passthrough', disposition: 'embed-passthrough', repro: 'needs-credential', phase: 'embeds', decision: 'vendor account ids stay the owner\'s' },
  { when: (f) => f.class === 'T', pattern: 'consent-gated-tags', disposition: 'embed-passthrough', repro: 'needs-business-decision', phase: 'tags', decision: 'which tags run on the new host; property ids' },
  { when: (f) => f.class === 'F' && /client-compute/.test(f.hint || ''), pattern: 'client-compute', disposition: 'client-only', repro: 'self', phase: 'client tools', decision: 'none' },
  { when: (f) => f.class === 'F' && /form backend|form protection/.test(f.feature), pattern: 'forms', disposition: 'rebuild-native', repro: 'needs-backend', phase: 'forms', decision: 'production backend (vendor form id + field mapping)' },
  { when: (f) => f.class === 'F', pattern: 'forms', disposition: 'rebuild-native', repro: 'needs-backend', phase: 'forms', decision: 'production endpoint; interim capture ships now' },
  { when: (f) => f.class === 'M' && /chrome only/.test(f.feature), pattern: 'chrome-interaction', disposition: 'rebuild-native', repro: 'self', phase: 'interactive', decision: 'none (the header contract is the spec)' },
  { when: (f) => f.class === 'M', pattern: 'modal-loader', disposition: 'rebuild-native', repro: 'self', phase: 'interactive', decision: 'none' },
  { when: (f) => f.class === 'V' && /iframe without src/.test(f.feature), pattern: 'embed-passthrough', disposition: 'embed-passthrough', repro: 'needs-human-capture', phase: 'embeds', decision: 'resolve the runtime src from a rendered capture' },
  { when: (f) => f.class === 'V', pattern: 'media-as-url', disposition: 'embed-passthrough', repro: 'self', phase: 'media', decision: 'none (player ids are public)' },
  { when: (f) => f.class === 'L', pattern: 'listing-index-backed', disposition: 'index-backed', repro: 'needs-business-decision', phase: 'listings', decision: 'index-driven or editorially curated?' },
  { when: (f) => f.class === 'X', pattern: 'decided-out', disposition: 'decided-out', repro: 'needs-backend', phase: 'register', decision: 'auth / commerce on the new host?' },
  { when: (f) => f.class === 'I18N', pattern: 'locale-tree', disposition: 'rebuild-native', repro: 'needs-business-decision', phase: 'locale wave', decision: 'scope of the locale trees' },
  { when: (f) => f.class === 'CR' && /main empty at load/.test(f.feature), pattern: 'client-rendered-page', disposition: 'static-snapshot', repro: 'needs-human-capture', phase: 'capture', decision: 'human-browser capture; never migrate blank' },
  { when: (f) => f.class === 'CR', pattern: 'settled-dom-snapshot', disposition: 'static-snapshot', repro: 'self', phase: 'capture', decision: 'inspect the consumer' },
];
const PII = /ssn|social.?security|dob|date.?of.?birth|passport|account.?number|iban|card.?number|cvv|minor|guardian|upload/i;

// target: the delivery form per pattern (reference/triage.md § Target); widget where no authored rows remain.
const TARGET_BY_PATTERN = {
  'search-index-backed': 'widget', 'client-compute': 'widget', 'modal-loader': 'runtime', 'chrome-interaction': 'runtime', 'locale-tree': 'runtime',
  'listing-index-backed': 'block', 'off-origin-data': 'block', forms: 'block', 'media-as-url': 'content', 'sheet-sync': 'content',
  'client-rendered-page': 'content', 'settled-dom-snapshot': 'content', 'read-settings': 'content', 'consent-gated-tags': 'embed', 'embed-passthrough': 'embed',
};
const LOCATOR = /locator|store finder|dealer finder|branch finder|find a (store|branch|dealer|location)/i;
export function targetFor(pattern, f) {
  const base = TARGET_BY_PATTERN[pattern] ?? null;
  if (pattern === 'decided-out' || (base && base !== 'block')) return base; // settled by the pattern: nothing to build, or not a block
  if (LOCATOR.test(f.feature || '')) return 'widget';
  if (pattern === 'forms' && /form-less control group/.test(f.feature || '')) return 'widget'; // definition-driven, no authored copy
  return base;
}

/* ---------------------------------------------------- target-host probe -- */
const hostBound = {};
if (TARGET && TARGET !== true) {
  const auth = resolveAuthHeader();
  const apis = d.findings.filter((f) => f.api);
  const targetOrigin = new URL(TARGET).origin;
  for (const f of apis) {
    const url = `${TARGET.replace(/\/$/, '')}${f.api.path.replace(/\{[a-z]+\}/g, '1')}`;
    let onTarget = false; try { onTarget = new URL(url).origin === targetOrigin; } catch { /* malformed: not probed */ }
    if (!onTarget) continue; // a path that leaves the target origin is never sent the site secret
    const r = await probe(url, { headers: auth ? { authorization: auth } : {} });
    hostBound[f.id] = r.ok ? `served (${r.status})` : `dead on target (${r.status || r.error})`;
  }
}

/* ------------------------------------------- reconcile against output -- */
const delivered = {};
if (MIGRATED && MIGRATED !== true && existsSync(MIGRATED)) {
  const files = []; const walk = (dir) => { for (const e of readdirSync(dir)) { const p = join(dir, e); if (statSync(p).isDirectory()) walk(p); else if (/\.html?$/.test(e)) files.push(p); } }; walk(MIGRATED);
  const corpus = files.map((f) => readFileSync(f, 'utf8'));
  for (const f of d.findings) {
    const tokens = (f.evidence || []).map((e) => String(e).replace(/^(GET|POST) /, '').split(' → ')[0]).filter((t) => t.length > 6 && !/^[\d,.]+$/.test(t));
    const hit = tokens.find((t) => corpus.some((c) => c.includes(t)));
    if (hit) delivered[f.id] = `output already carries "${hit.slice(0, 40)}"`;
  }
}

/* ------------------------------------------------- spec knowledge rows -- */
/** Rows from a spec's curated features: the axes as judged there, the decision from its open questions. */
function knowledgeRows(dir) {
  if (!dir || dir === true || !existsSync(join(dir, 'features.json'))) return [];
  const qs = Object.fromEntries(readJSON(join(dir, 'open-questions.json'), []).map((q) => [q.id, q]));
  const live = readFileSync(join(dir, 'urls.jsonl'), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)).filter((u) => u.outcome === 'page' && u.in_sitemap === 1).length;
  return readJSON(join(dir, 'features.json')).map((f) => Object.assign({
    id: `spec-${f.id}`, source: 'spec', class: f.class, feature: f.name, pages: f.reach_pages, probed: live, reach: { pages: f.reach_pages, of: live }, evidence: [f.evidence].flat().filter(Boolean).slice(0, 4),
    pattern: f.pattern || 'inspect', disposition: f.disposition, target: f.target || targetFor(f.pattern || 'inspect', { feature: f.name }), reproducibility: f.reproducibility, status: f.status || 'pending', phase: 'spec',
    decision: (f.decisions || []).map((q) => (qs[q] ? `${q}: ${qs[q].effective}${qs[q].answer ? ' (answered)' : ' (default)'}` : q)).join(' · ') || 'none',
  }, f.disposition === 'decided-out' && !(f.decisions || []).some((q) => qs[q]?.answer)
    ? { flags: ['decided-out without a recorded owner answer: confirm with the owner or pick another disposition (triage.md)'] } : {}));
}

/** search-query checks from a spec's probes, grouped by their S feature; resultSelector is the curator's to fill. */
function knowledgeParity(dir) {
  if (!dir || dir === true || !existsSync(join(dir, 'search-probes.json'))) return null;
  const probes = readJSON(join(dir, 'search-probes.json'), []).filter((p) => p.term);
  if (!probes.length) return null;
  const byFeature = {};
  for (const p of probes) {
    const id = p.feature || 'search';
    (byFeature[id] = byFeature[id] || { id, feature: id, class: 'S', status: 'pending', checks: [] }).checks.push(Object.fromEntries(Object.entries({
      type: 'search-query', path: p.path || null, param: p.param || undefined, term: p.term, resultSelector: null,
      expectCount: p.expect_count ?? undefined, expectTitles: p.expect_titles?.length ? p.expect_titles : undefined, expectIncludes: p.expect_includes ?? undefined,
    }).filter(([, v]) => v !== undefined)));
  }
  return { _provenance: provenance('plan', { knowledge: dir }), method: 'drafted from the spec\'s search probes: fill resultSelector (the rebuilt results\' item selector), check path against the rebuilt search page, then curate into parity.json', features: Object.values(byFeature) };
}

/* ---------------------------------------------------- header contract -- */
const CHROME_ROWS = {
  menu: { class: 'M', pattern: 'chrome-interaction', disposition: 'rebuild-native', target: 'runtime', repro: 'self', decision: 'none (the header contract is the spec)' },
  drawer: { class: 'M', pattern: 'chrome-interaction', disposition: 'rebuild-native', target: 'runtime', repro: 'self', decision: 'none (the header contract is the spec)' },
  search: { class: 'S', pattern: 'search-index-backed', disposition: 'index-backed', target: 'widget', repro: 'self', decision: 'none (results from the query index; overlay and typeahead per the contract)' },
  cart: { class: 'X', pattern: 'chrome-interaction', disposition: 'rebuild-native', target: 'widget', repro: 'needs-backend', decision: 'the commerce backend on the new host (the drawer ships per the contract either way)' },
  account: { class: 'X', pattern: 'chrome-interaction', disposition: 'rebuild-native', target: 'widget', repro: 'needs-backend', decision: 'sign-in on the new host (the menu ships per the contract either way)' },
  locale: { class: 'I18N', pattern: 'locale-tree', disposition: 'rebuild-native', target: 'runtime', repro: 'needs-business-decision', decision: 'which locales the switcher lists' },
};
/** One row per control family of the header contract, with what it opens at each width. */
function chromeRows(contract) {
  const fam = {};
  for (const [w, wd] of Object.entries(contract.widths || {})) {
    for (const c of wd.controls || []) {
      const opens = ['hover', 'click', 'key'].filter((a) => c.actions && c.actions[a] && c.actions[a].opened);
      if (!CHROME_ROWS[c.kind] || (!opens.length && !c.search && !(c.children || []).some((x) => x.search))) continue;
      const f = (fam[c.kind] = fam[c.kind] || { names: new Set(), at: new Set() });
      f.names.add(c.name || c.kind); f.at.add(`${w} ${opens.join('/') || 'type'}`);
    }
  }
  return Object.entries(fam).map(([kind, f]) => {
    const r = CHROME_ROWS[kind];
    return { id: `chrome-${kind}`, source: 'header-contract', class: r.class, feature: `header ${kind}: ${[...f.names].join(', ')} (chrome only)`, pages: 1, probed: 1, reach: null, evidence: [...f.at],
      pattern: r.pattern, disposition: r.disposition, target: r.target, reproducibility: r.repro, status: 'pending', phase: 'interactive', decision: r.decision };
  });
}

/* ---------------------------------------------------------------- rows -- */
const rows = d.findings.map((f) => {
  const rule = RULES.find((r) => r.when(f)) || { pattern: 'inspect', disposition: 'static-snapshot', repro: 'needs-human-capture', phase: 'detect', decision: 'inspect' };
  const pii = f.class === 'F' && PII.test((f.signature || []).join(' ') + (f.evidence || []).join(' '));
  const row = {
    id: f.id, class: f.class, feature: f.feature, pages: f.pages.length, probed, reach: f.reach || null, evidence: (f.evidence || []).slice(0, 4),
    pattern: rule.pattern, disposition: rule.disposition, target: targetFor(rule.pattern, f), reproducibility: pii ? 'needs-business-decision' : rule.repro, status: 'pending', phase: rule.phase, decision: rule.decision,
  };
  if (pii) row.flags = ['regulated-pii: never auto-wire; submission blocked until a human configures the secured endpoint'];
  if (hostBound[f.id]) { row.hostBound = hostBound[f.id]; if (/dead/.test(row.hostBound)) row.disposition = 'data-fed'; }
  if (delivered[f.id]) { row.alreadyDelivered = delivered[f.id]; row.status = 'delivered-by-capture'; }
  return row;
});
rows.push(...knowledgeRows(KNOWLEDGE));
if (CHROME && existsSync(CHROME)) rows.push(...chromeRows(readJSON(CHROME)));
const parityDraft = knowledgeParity(KNOWLEDGE);
if (parityDraft) writeJSON(join(OUT, 'dynamic-features.generated-parity.json'), parityDraft);
const draft = { _provenance: provenance('plan', { input: IN, target: TARGET || null, migrated: MIGRATED || null, knowledge: KNOWLEDGE || null, chrome: CHROME || null }), rows };
writeJSON(join(OUT, 'dynamic-features.generated-plan.json'), draft);

const contract = MARTECH && buildContract({
  dynamics: d, martech: readEvidence(MARTECH), provenance: provenance('plan', { input: IN, martech: MARTECH }), previous: readJSON(CONTRACT, null),
});
if (contract) {
  writeJSON(CONTRACT, contract);
  writeText('stardust/martech-handoff.md', renderHandoff(contract));
}

const byPhase = {}; for (const r of rows) byPhase[r.phase] = (byPhase[r.phase] || 0) + 1;
const self = rows.filter((r) => r.reproducibility === 'self' && r.status === 'pending');
const batch = rows.filter((r) => r.reproducibility !== 'self' && r.status === 'pending' && r.disposition !== 'decided-out');
const md = [
  `<!-- stardust provenance: skill=stardust:dynamics · phase=plan draft · ${draft._provenance.writtenAt} · input ${IN} (${probed} pages, ${rows.length} findings)${TARGET ? ` · target probe ${TARGET}` : ''}${MIGRATED ? ` · reconciled against ${MIGRATED}` : ''}${KNOWLEDGE ? ` · spec knowledge ${KNOWLEDGE}` : ''} -->`,
  '# Dynamic features — draft inventory (curate into `stardust/dynamic-features.md`)', '',
  'One row per detected finding. Merge duplicates, drop noise, keep every axis honest. Columns: disposition = what we do · target = the delivery form (widget where no authored rows remain) · reproducibility = what it needs · status = where it stands (reference/triage.md).', '',
  '| # | id | class | feature | pages | disposition | target | reproducibility | status | pattern | decision needed | notes |', '|---|---|---|---|---|---|---|---|---|---|---|---|',
  ...rows.map((r, i) => `| ${i + 1} | ${r.id} | ${r.class} | ${r.feature.replace(/\|/g, '/')} | ${r.pages}/${r.probed}${r.reach ? ` (reach ${r.reach.pages}/${r.reach.of})` : ''} | ${r.disposition} | ${r.target || '—'} | ${r.reproducibility} | ${r.status} | ${r.pattern} | ${r.decision} | ${[r.hostBound && `**${r.hostBound}**`, r.alreadyDelivered, ...(r.flags || [])].filter(Boolean).join('; ')} |`),
  '', '## Triage', '',
  `- **Ships autonomously (reproducibility \`self\`):** ${self.length} row(s) — ${[...new Set(self.map((r) => r.pattern))].join(', ') || 'none'}.`,
  `- **One owner decision batch:** ${batch.length} row(s) — ${[...new Set(batch.map((r) => r.decision))].slice(0, 6).join(' · ') || 'none'}.`,
  `- **Already delivered by the capture pipeline:** ${rows.filter((r) => r.alreadyDelivered).length} row(s) — no work.`,
  `- **Host-bound on the target:** ${rows.filter((r) => /dead/.test(r.hostBound || '')).length} of ${Object.keys(hostBound).length} probed API paths — the off-origin data work.`,
  ...(contract ? [`- **Martech:** ${contract.consent.cmp?.vendor || 'no CMP'} · ${contract.routes.filter((r) => r.enabled).length}/${contract.routes.length} route(s) enabled by the owner — \`stardust/martech-handoff.md\`.`] : []),
  '', '## Phases', '', ...Object.entries(byPhase).sort((a, b) => b[1] - a[1]).map(([k, n]) => `- **${k}** — ${n}`),
];
writeText(join(OUT, 'dynamic-features.generated-plan.md'), md.join('\n'));
console.error(`[dynamics] ${rows.length} rows → ${OUT}/dynamic-features.generated-plan.md · self ${self.length} · owner batch ${batch.length} · delivered ${Object.keys(delivered).length} · host-bound ${Object.values(hostBound).filter((v) => /dead/.test(v)).length}/${Object.keys(hostBound).length}`);

skills

README.md

tile.json