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

da-source-api.mdskills/deploy/reference/

stardust:deploy: deploying through the DA Source API

The text of this part of skills/deploy/SKILL.md, which keeps the heading and points here. "Above" and "below" refer to the order of the sections in that file.

Deploy (DA Source API, from a local agent)

Steps 1–9 are the conversion methodology; deploy is the one transport-specific step. From a local agent (Claude Code / CLI), each converted page deploys headlessly:

StageHow
Codegit push the branch → AEM Code Sync builds it
Localize linksskills/deploy/scripts/localize-links.mjs --source-host <live-host> [--redirects stardust/redirects.tsv] — after EVERY generator, before EVERY write, over the WHOLE tree (below)
Sanitiseskills/deploy/scripts/sanitise.js — run it before the write (DA corrupts raw UTF-8)
Content writeDA Source API: PUT admin.da.live/source/<org>/<repo>/<path>.html (multipart, field name data, type=text/html)
Make livePOST admin.hlx.page/preview/<org>/<repo>/<branch>/<path> (then optionally /live/...)
AuthIMS token (DA_TOKEN) — see the da-content / da-auth skills

The content payload is a body fragment (see Step 9). The deploy needs the code branch pushed to GitHub so the branch preview (<branch>--<repo>--<org>.aem.page) renders with your blocks. See da-deploy-protocol.md for the full curl contract.

For more than a few pages, use the bundled driver instead of a hand-rolled loop (#4). node skills/deploy/scripts/deploy-batch.mjs --org <org> --repo <repo> --branch <branch> --content content [--concurrency 4] [--no-publish] runs PUT → preview → live across a content tree with bounded concurrency, a persistent ledger (content/.deploy-ledger.json) so a re-run skips pages already live and only re-drives FAILs, capped-backoff retries on 000/429/5xx (and on a 401 — the DA_TOKEN lifecycle rule below: a 401 that persists halts the batch with exit 3 and the exact re-run command, never a per-page FAIL), an append-only log (survives a restart), and a delivered-.plain.html check before flipping a page to live (admin 200 ≠ delivered). It's idempotent — safe to Ctrl-C and re-run, which is the documented recovery for a transient-blip half-deploy. A serial hand-rolled bash loop that truncates its own log on restart is the anti-pattern this replaces.

Per-page atomic delivery contract. A page is deployed only when the full chain passes, in order: localize-links.mjs run over the content tree (then --check exit 0 — no source-host href left whose target exists locally) → davids-model-lint.mjs exit 0 (0 🔴 — the content-structure gate) → sanitise-wrapped file (scripts/sanitise.js) → PUT (multipart field data, type=text/html) → POST /preview/ → POST /live/ → GET the rendered .plain.html and assert: HTTP 200, the <body> wrapper intact, exactly one <h1>, zero about:error, no /img/ srcs — plus, when key facts are declared for the site (#86 — DESIGN.json.extensions.metadata.keyFacts[], written by direct; skip the gate and note the skip when the field is absent), grep the RAW full-page HTML (not the rendered DOM) for each fact string on the pages that carry them. → AI-readability gate (#100): node skills/deploy/scripts/ai-readability.mjs --origin <live> <paths> — the checker score (served words ÷ rendered-DOM words, landmarks ignored) with fragments credited must be ≥ 98 on the published page; record the strict score and the per-block served gap in the gate report (reference/ai-readability.md). Only then flip the page's ledger entry to deployed — never on the POST codes (admin 200 ≠ delivered).

Link localization is a pipeline stage, not an afterthought. Generators carry captured hrefs as fully-qualified source-domain URLs (the D4 "opaque tokens" rule), which sends visitors back to the live site for pages that exist on the new origin. D4 is a capture-fidelity rule for media and external targets; it is never a delivery rule for internal links. The pipeline owns a URL map (every served path in the content tree + stardust/redirects.tsv entries) and localize-links.mjs rewrites, idempotently, every source-host <a href> whose path resolves in the map to the root-relative URL EDS serves (eds-path.mjs: no .html; a folder index at /x/, a leaf at /x/y), query and fragment preserved — and normalizes root-relative internal hrefs the same way. Everything else stays absolute: genuinely external targets and not-yet-migrated pages are the honest integration boundary, and the tool lists them. Re-run it over the WHOLE tree after every wave: earlier waves' pages gain newly valid internal targets only when a later wave ships them. davids-model-lint.mjs --source-host <live-host> flags any remaining localizable link as a 🟡 LOCALIZE advisory (advisory in this release; the fix is the stage, never a hand edit).

A .plain.html pass is NOT a layout pass — add one computed-style assertion (#the silent-failure guard). The text-level asserts above are all satisfied while the page renders as a single stacked column, because a block-CSS scoping mistake (a selector keyed to a wrapper class the target runtime doesn't emit — see blockWrapperClass in the runtime contract) makes every grid fall back to display: block with the typography still correct. This shipped green on a real e2e site. So the contract's final gate is a headless computed-style check on the delivered live URL (not .plain.html): load the page in a headless browser and assert, for the first page of each template, that every block whose CSS declares a grid/flex layout computes display: grid/flex (not block), main .section count > 0, blocks are decorated (data-block-name present), zero pageerror, zero broken images — and every visible loaded image renders non-zero: clientWidth > 0 (#122). Loaded ≠ rendered: an <img> with naturalWidth > 0 can still render 0×0 (recorded: a flex item whose width derives from the image while the image's max-width: 100% derives from the item — circular sizing collapses to zero), and both the .plain.html checks and a naturalWidth === 0 broken-image probe miss it. A block that should grid but computes block fails the page — do not flip it to deployed. This is the assertion blockWrapperClass in the runtime contract calls for; the atomic contract is where it must actually run, once per template. Two field-decodes worth pinning: a burst of PUT 400s is a malformed path, not rate limiting — lowercase every segment, never a double slash (content//… 400s the PUT while preview/live still 200), no trailing -/_ on a segment; and write long loops to a bash script file with absolute binary paths (/usr/bin/curl, the full node path) — zsh drops PATH inside while/for in some contexts, and the resulting command not found burst mimics a transport failure.

Token hygiene (#16). The IMS token typically lives in repo .env as DA_TOKEN. Before the first commit, make sure .gitignore excludes .env and .env.* on the branch you'll branch tests from — otherwise every test subbranch re-exposes the token (the master skill's Setup step 6 writes the managed block; the local harness and pre-renders live under stardust/.work/, which stardust/.gitignore already excludes). Dev tokens last ~24h; a 401 with an empty body means expired → refresh and retry (the write is idempotent).

DA_TOKEN lifecycle — preflight and re-check, never fail pages on it. At setup, preflight the token: decode the JWT exp claim when present (base64-decode the middle segment) and smoke-test ONE authenticated DA call before any batch. Re-check before each long batch — a token fresh at setup can expire mid-run. On a 401 mid-batch, do not read the first one as expiry — a valid token can be answered 401 under a concurrent burst (recorded: the whole first burst of a media batch got 401 on a token with hours of validity left, and a lone sequential PUT went straight through). Both shipped drivers apply the rule themselves — da-media-upload.mjs (media) and deploy-batch.mjs (pages): a JWT past its exp exits 3 before any request; a 401 from the admin API (the media PUT; the page PUT, preview and live) retries like a 429 — the uploader's first upload additionally runs alone to prove the token; a 401 that still persists through its retries on ANY file or page halts the batch with exit 3 — ledger checkpointed, in-flight work finished, the rest not attempted, one actionable stderr line with the exact re-run command (HALT <path> 401 after <n> attempts — refresh DA_TOKEN and re-run: …; the same command resumes from the ledger). A 401 is never a per-file or per-page FAIL: an expired token once left an 894-row batch failing file by file for 5.5 hours. Token source per driver: both drivers take both flags — --token-env <NAME> (the environment variable holding the token, default DA_TOKEN) or --token-file <path> (read once at start, trimmed; never both — for a harness that hands the token over as a file rather than a variable; a recorded hands-off run had the token in a file while the uploader read DA_TOKEN only); the value is never printed, never in the re-run command and never written to a ledger or log, and every expiry or halt line names the variable or file to refresh (in file mode the re-run command carries no <var>=<fresh token> prefix). A hand-rolled loop (never for more than a few pages — above) follows the same shape: checkpoint the ledger, retry the 401 like a 429, and halt with a single actionable instruction only once a lone sequential request still gets 401. Token expiry is the one credential failure the agent cannot self-recover; it is a legitimate hard stop even in a hands-off run.

skills

README.md

tile.json