@penpair/marwes-ui 0.1.3 → 0.3.0

package/dist/commands.js

@@ -1,35 +1,104 @@
+import { lintThemeFamily } from "./theme-lint.js";
+import { componentsCommand } from "./components.js";
+import { runModeTrial } from "./mode-trial.js";
+import { ownershipReport, readSyncAncestor, saveSyncAncestor } from "./ownership.js";
+import { mkdir } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { parseArgs } from "node:util";
-import { loadConfig, readRawConfig } from "@penpair/core";
+import { projectTheme, parseCommandArgs, readDesignJson, atomicWriteFile, resolveProjectOutput, readJournalTarget, guardFile, resolveProjectInput, createCheckpoint, loadConfig, readRawConfig, } from "@penpair/core";
 import { readMarwesSettings } from "./config.js";
 import { familyProblems, loadInstalledMarwes } from "./marwes.js";
-import { applyPlan, compareToPenpot, describePlan, formatDrift, impactOf, planPush, readLive } from "./penpot.js";
-import { diffSnapshots, formatDiff, readSnapshot, writeSnapshot } from "./snapshot-file.js";
+import { applyPlan, compareToPenpot, describePlan, formatDrift, impactOf, planPush, readLive, } from "./penpot.js";
+import { diffSnapshots, formatDiff, tokenSnapshotSchema, migrateTokenSnapshot, readSnapshot, writeSnapshot, } from "./snapshot-file.js";
 import { loadThemeInput } from "./theme-input.js";
 import { buildSnapshot } from "./tokens.js";
+const print = (context, ...values) => (context.output?.log ?? console.log)(...values);
+const diagnostic = (context, ...values) => (context.output?.error ?? console.error)(...values);
 const adapterVersion = createRequire(import.meta.url)("../package.json").version;
 export async function computeExpectation(root, rawConfig, instance) {
     const settings = readMarwesSettings(rawConfig, instance);
-    const installed = await loadInstalledMarwes(path.resolve(root, settings.project));
-    const [light, dark] = await Promise.all([settings.themes.light, settings.themes.dark].map((reference) => (reference ? loadThemeInput(root, reference) : undefined)));
+    const installed = await loadInstalledMarwes(await resolveProjectInput(root, settings.project));
+    const [light, dark] = await Promise.all([
+        settings.themes.light,
+        settings.themes.dark,
+    ].map((reference) => (reference ? loadThemeInput(root, reference) : undefined)));
     const fresh = buildSnapshot({
         core: installed.core,
         version: installed.version,
         name: settings.name,
-        project: { ...(light ? { light: light.input } : {}), ...(dark ? { dark: dark.input } : {}) },
+        extras: settings.extras,
+        project: {
+            ...(light
+                ? {
+                    light: light.input,
+                }
+                : {}),
+            ...(dark
+                ? {
+                    dark: dark.input,
+                }
+                : {}),
+        },
         generatedBy: `@penpair/marwes-ui@${adapterVersion}`,
     });
-    return { settings, installed, fresh, problems: familyProblems(installed) };
+    return {
+        settings,
+        installed,
+        fresh,
+        problems: familyProblems(installed),
+    };
 }
 export async function checkSnapshotFor(root, rawConfig, instance) {
     const expectation = await computeExpectation(root, rawConfig, instance);
     const committed = await readSnapshot(root, expectation.settings.snapshot);
     const diff = diffSnapshots(committed, expectation.fresh);
-    const problems = [...expectation.problems];
-    if (!committed)
-        problems.push(`there is no snapshot yet at ${expectation.settings.snapshot}; run \`penpair marwes tokens snapshot --write\` and commit it`);
-    return { current: !!committed && diff.identical && committed.hash === expectation.fresh.hash && expectation.problems.length === 0, committed, diff, problems, expectation };
+    const reasons = expectation.problems.map((message) => ({
+        code: "package-mismatch",
+        message,
+    }));
+    const migration = `Preview migration with \`penpair marwes tokens migrate --from ${expectation.settings.snapshot} --ownership ownership.json\`; explicitly classify every set as adapter or project, then use --out NEW_FILE to preserve the original.`;
+    if (!committed) {
+        reasons.push({
+            code: "missing-snapshot",
+            message: `there is no snapshot yet at ${expectation.settings.snapshot}; run \`penpair marwes tokens snapshot --write\` and commit it`,
+        });
+    }
+    else {
+        if (committed.schemaVersion !== expectation.fresh.schemaVersion) {
+            reasons.push({
+                code: "schema-migration",
+                message: `Snapshot schema ${committed.schemaVersion} needs migration to ${expectation.fresh.schemaVersion}. ${migration}`,
+            });
+        }
+        if (!committed.ownership) {
+            reasons.push({
+                code: "missing-ownership",
+                message: `Legacy snapshot has no set ownership. ${migration}`,
+            });
+        }
+        if (!diff.identical) {
+            reasons.push({
+                code: "content-drift",
+                message: "Snapshot values, sets, themes or installed package version changed; review the value diff before regenerating.",
+            });
+        }
+        if (committed.hash !== expectation.fresh.hash) {
+            reasons.push({
+                code: "metadata-mismatch",
+                message: diff.identical
+                    ? "Token values are identical, but snapshot metadata/hash differs; review schema, ownership and provenance before replacing it."
+                    : "Snapshot hash differs from the current expectation.",
+            });
+        }
+    }
+    return {
+        current: reasons.length === 0,
+        committed,
+        diff,
+        reasons,
+        problems: reasons.map((reason) => reason.message),
+        expectation,
+    };
 }
 /**
  * For a project's own test suite: resolves the project's penpair.config.json and checks that the committed Marwes token snapshot
@@ -41,135 +110,426 @@ export async function checkTokenSnapshot(root) {
 }
 const summary = (snapshot) => `Marwes ${snapshot.marwesVersion}, ${snapshot.sets.length} sets, ${snapshot.sets.reduce((n, s) => n + s.tokens.length, 0)} tokens, ${snapshot.hash.slice(0, 10)}`;
 /** What the snapshot says it does not cover, so a reader is never left thinking everything Marwes provides is in Penpot. */
-const coverage = (snapshot) => ((snapshot.unmapped ?? []).length > 0 ? `${snapshot.unmapped.length} Marwes variable(s) are not tokens: ${snapshot.unmapped.slice(0, 6).join(", ")}${snapshot.unmapped.length > 6 ? ", ..." : ""}` : undefined);
-const flags = (args) => parseArgs({ args, allowPositionals: true, options: { write: { type: "boolean" }, apply: { type: "boolean" }, prune: { type: "boolean" }, json: { type: "boolean" } } });
+const coverage = (snapshot) => (snapshot.unmapped ?? []).length > 0
+    ? `${snapshot.unmapped.length} Marwes variable(s) are not tokens: ${snapshot.unmapped.slice(0, 6).join(", ")}${snapshot.unmapped.length > 6 ? ", ..." : ""}`
+    : undefined;
+const flags = (args) => parseCommandArgs({
+    args,
+    allowPositionals: true,
+    options: {
+        from: {
+            type: "string",
+        },
+        ownership: {
+            type: "string",
+        },
+        theme: {
+            type: "string",
+        },
+        resolved: {
+            type: "boolean",
+        },
+        page: {
+            type: "string",
+        },
+        out: {
+            type: "string",
+        },
+        overwrite: {
+            type: "boolean",
+        },
+        adopt: {
+            type: "string",
+        },
+        write: {
+            type: "boolean",
+        },
+        apply: {
+            type: "boolean",
+        },
+        prune: {
+            type: "boolean",
+        },
+        json: {
+            type: "boolean",
+        },
+        resume: {
+            type: "string",
+        },
+        checkpoint: {
+            type: "boolean",
+        },
+        "force-lock": {
+            type: "boolean",
+        },
+        trace: {
+            type: "boolean",
+        },
+    },
+});
 const staleAdvice = "Run `penpair marwes tokens snapshot --write`, review the change in git, and commit it.";
 async function snapshotCommand(context, args) {
     const { values } = flags(args);
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     const fresh = check.expectation.fresh;
-    if (values.json)
-        console.log(JSON.stringify({ current: check.current, summary: summary(fresh), diff: check.diff, problems: check.problems }, null, 2));
+    if (values.json) {
+        print(context, JSON.stringify({
+            current: check.current,
+            summary: summary(fresh),
+            diff: check.diff,
+            reasons: check.reasons,
+            problems: check.problems,
+        }, null, 2));
+    }
     else {
-        console.log(`Expected from the installed ${summary(fresh)}`);
-        for (const line of formatDiff(check.diff))
-            console.log(`  ${line}`);
-        if (coverage(fresh))
-            console.log(`note ${coverage(fresh)}`);
-        for (const problem of check.problems.filter((p) => !p.startsWith("there is no snapshot")))
-            console.log(`FAIL ${problem}`);
-    }
-    if (check.expectation.problems.length > 0)
+        print(context, `Expected from the installed ${summary(fresh)}`);
+        for (const line of formatDiff(check.diff)) {
+            print(context, `  ${line}`);
+        }
+        if (coverage(fresh)) {
+            print(context, `note ${coverage(fresh)}`);
+        }
+        for (const problem of check.problems.filter((p) => !p.startsWith("there is no snapshot"))) {
+            print(context, `FAIL ${problem}`);
+        }
+    }
+    if (check.expectation.problems.length > 0) {
         return 1;
+    }
     if (check.current) {
-        if (!values.json)
-            console.log(`ok   ${check.expectation.settings.snapshot} is current`);
+        if (!values.json) {
+            print(context, `ok   ${check.expectation.settings.snapshot} is current`);
+        }
         return 0;
     }
     if (!values.write) {
-        if (!values.json)
-            console.log(`${check.committed ? "The committed snapshot is stale." : "There is no snapshot yet."} Run again with --write to save ${check.expectation.settings.snapshot}.`);
+        if (!values.json) {
+            print(context, `${check.committed ? "The committed snapshot is stale." : "There is no snapshot yet."} Run again with --write to save ${check.expectation.settings.snapshot}.`);
+        }
         return 2;
     }
     await writeSnapshot(context.root, check.expectation.settings.snapshot, fresh);
-    if (!values.json)
-        console.log(`wrote ${check.expectation.settings.snapshot}. Review the change in git and commit it; then \`penpair marwes tokens diff\` shows what Penpot needs.`);
+    context.output?.result({
+        current: true,
+        snapshot: check.expectation.settings.snapshot,
+        hash: fresh.hash,
+        written: true,
+    });
+    if (!values.json) {
+        print(context, `wrote ${check.expectation.settings.snapshot}. Review the change in git and commit it; then \`penpair marwes tokens diff\` shows what Penpot needs.`);
+    }
     return 0;
 }
 async function checkCommand(context, args) {
     const { values } = flags(args);
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     if (values.json) {
-        console.log(JSON.stringify({ current: check.current, installed: check.expectation.installed.versions, diff: check.diff, problems: check.problems }, null, 2));
+        print(context, JSON.stringify({
+            current: check.current,
+            installed: check.expectation.installed.versions,
+            diff: check.diff,
+            reasons: check.reasons,
+            problems: check.problems,
+        }, null, 2));
         return check.current ? 0 : check.expectation.problems.length > 0 ? 1 : 2;
     }
     if (check.current) {
-        console.log(`ok   ${check.expectation.settings.snapshot} is current (${summary(check.expectation.fresh)})`);
+        print(context, `ok   ${check.expectation.settings.snapshot} is current (${summary(check.expectation.fresh)})`);
         return 0;
     }
-    for (const line of formatDiff(check.diff))
-        console.log(`  ${line}`);
-    for (const problem of check.problems)
-        console.log(`FAIL ${problem}`);
-    if (check.committed && check.expectation.problems.length === 0) {
-        const cause = check.committed.marwesVersion !== check.expectation.installed.version ? `it was made from Marwes ${check.committed.marwesVersion} and the installed Marwes is ${check.expectation.installed.version}` : "the installed Marwes or the project's theme has changed since it was made";
-        console.log(`FAIL the committed snapshot is stale: ${cause}. ${staleAdvice}`);
+    for (const line of formatDiff(check.diff)) {
+        print(context, `  ${line}`);
+    }
+    for (const problem of check.problems) {
+        print(context, `FAIL ${problem}`);
+    }
+    if (check.committed &&
+        check.expectation.problems.length === 0 &&
+        !check.reasons.some((reason) => reason.code === "schema-migration")) {
+        const cause = check.committed.marwesVersion !== check.expectation.installed.version
+            ? `it was made from Marwes ${check.committed.marwesVersion} and the installed Marwes is ${check.expectation.installed.version}`
+            : "the installed Marwes or the project's theme has changed since it was made";
+        print(context, `FAIL the committed snapshot is stale: ${cause}. ${staleAdvice}`);
     }
     return check.expectation.problems.length > 0 ? 1 : 2;
 }
 async function readPenpot(context, committed, wantImpact) {
     return context.withPenpot(async (client) => {
-        const live = await readLive(client);
-        const drift = compareToPenpot(committed, live);
-        return { live, drift, ...(wantImpact && !drift.inSync ? { impact: await impactOf(client).catch(() => undefined) } : {}) };
+        const target = await readJournalTarget(client);
+        const pinned = guardFile(client, {
+            id: target.fileId,
+        });
+        const live = await readLive(pinned);
+        const after = await readJournalTarget(pinned);
+        if (after.fileId !== target.fileId || after.revision !== target.revision) {
+            throw new Error("File changed during token inspection; inspect again");
+        }
+        const ancestor = await readSyncAncestor(context.root, target.fileId);
+        const drift = compareToPenpot(committed, live, {
+            ancestor,
+        });
+        return {
+            target,
+            live,
+            drift,
+            ...(wantImpact && !drift.inSync
+                ? {
+                    impact: await impactOf(pinned).catch(() => undefined),
+                }
+                : {}),
+        };
     });
 }
 async function diffCommand(context, args) {
     const { values } = flags(args);
+    if (values.resolved) {
+        return modeCommand(context, args);
+    }
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     if (!check.committed) {
-        console.error(`FAIL ${check.problems.join("; ")}`);
+        diagnostic(context, `FAIL ${check.problems.join("; ")}`);
         return 1;
     }
     const { drift, impact } = await readPenpot(context, check.committed, true);
     if (values.json) {
-        console.log(JSON.stringify({ snapshotCurrent: check.current, drift, impact }, null, 2));
+        print(context, JSON.stringify({
+            snapshotCurrent: check.current,
+            drift,
+            impact,
+        }, null, 2));
         return drift.inSync ? 0 : 2;
     }
-    if (!check.current)
-        console.log(`note: the committed snapshot is stale against the installed Marwes (${staleAdvice}); the comparison below is against the committed one.`);
+    if (!check.current) {
+        print(context, `note: the committed snapshot is stale against the installed Marwes (${staleAdvice}); the comparison below is against the committed one.`);
+    }
     if (drift.inSync) {
-        console.log(`ok   Penpot matches ${summary(check.committed)}`);
+        for (const line of formatDrift(drift, impact)) {
+            print(context, `note preserved: ${line}`);
+        }
+        print(context, `ok   Penpot matches ${summary(check.committed)}`);
         return 0;
     }
-    console.log(`Penpot differs from ${summary(check.committed)}:`);
-    for (const line of formatDrift(drift, impact))
-        console.log(`  ${line}`);
-    console.log("`penpair marwes tokens push --apply` brings Penpot to the snapshot (Marwes is authoritative: a value changed by hand in Penpot is put back).");
+    print(context, values.resume
+        ? `Resuming run ${values.resume}; current snapshot: ${summary(check.committed)}`
+        : `Penpot differs from ${summary(check.committed)}:`);
+    for (const line of formatDrift(drift, impact)) {
+        print(context, `  ${line}`);
+    }
+    print(context, "`penpair marwes tokens push --apply` brings Penpot to the snapshot (designer edits require explicit adoption or overwrite).");
     return 2;
 }
+async function modeCommand(context, args, frameId) {
+    const { values } = flags(args);
+    if ((values.resume || values.checkpoint || values["force-lock"] || values.trace) &&
+        !values.apply) {
+        throw new Error("Mode resume/checkpoint/force-lock require --apply");
+    }
+    if (frameId && (!values.page || !values.out)) {
+        throw new Error("verify-modes requires one frame ID, --page and --out");
+    }
+    if (values.out) {
+        await resolveProjectOutput(context.root, values.out);
+    }
+    const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
+    if (!check.committed || !check.current) {
+        diagnostic(context, "Mode verification requires a current committed snapshot. " + staleAdvice);
+        return 2;
+    }
+    const report = await context.withPenpot((client) => runModeTrial(client, check.committed, {
+        root: context.root,
+        apply: values.apply === true,
+        resume: values.resume,
+        forceLock: values["force-lock"] === true,
+        redact: context.redact,
+        onStep: context.log,
+        requireCheckpoint: values.checkpoint === true,
+        ...(values.checkpoint
+            ? {
+                checkpoint: (runId) => createCheckpoint(client, {
+                    label: "mode trial",
+                    runId,
+                }, {
+                    apply: true,
+                }),
+            }
+            : {}),
+        ...(frameId
+            ? {
+                frame: {
+                    id: frameId,
+                    page: values.page,
+                    out: values.out,
+                },
+            }
+            : {}),
+    }));
+    context.output?.result(report);
+    print(context, JSON.stringify(report, null, 2));
+    if (!values.apply) {
+        diagnostic(context, "Mode checks temporarily change active selection. Inspect planned states, then use --apply; the full original selection will be restored and verified separately.");
+        return 0;
+    }
+    return report.uncertain
+        ? 4
+        : !report.restoration.verified
+            ? 1
+            : !report.complete
+                ? 3
+                : report.verified
+                    ? 0
+                    : 2;
+}
 async function pushCommand(context, args) {
     const { values } = flags(args);
+    if ((values.resume || values.checkpoint || values["force-lock"] || values.trace) &&
+        !values.apply) {
+        throw new Error("Resume/checkpoint require --apply; inspect the journal and current design first");
+    }
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     if (!check.committed) {
-        console.error(`FAIL ${check.problems.join("; ")}`);
+        diagnostic(context, `FAIL ${check.problems.join("; ")}`);
         return 1;
     }
     if (!check.current) {
-        for (const line of formatDiff(check.diff))
-            console.log(`  ${line}`);
-        console.error(`STOP the committed snapshot is stale against the installed Marwes or the theme, and the repository's record must lead. ${staleAdvice} Then push.`);
+        for (const line of formatDiff(check.diff)) {
+            print(context, `  ${line}`);
+        }
+        diagnostic(context, `STOP the committed snapshot is stale against the installed Marwes or the theme, and the repository's record must lead. ${staleAdvice} Then push.`);
         return 2;
     }
-    const { drift, impact, live } = await readPenpot(context, check.committed, true);
-    const plan = planPush(check.committed, live, { prune: values.prune === true });
-    if (drift.inSync && plan.length === 0) {
-        console.log(`ok   Penpot already matches ${summary(check.committed)}; nothing to write`);
+    const { drift, impact, live, target } = await readPenpot(context, check.committed, true);
+    if (values.adopt && (values.apply || values.overwrite || values.resume)) {
+        throw new Error("--adopt writes a local review proposal and cannot be combined with apply/overwrite/resume");
+    }
+    const ancestor = await readSyncAncestor(context.root, target.fileId);
+    const ownership = ownershipReport(check.committed, live, ancestor);
+    if (values.adopt) {
+        const proposal = JSON.stringify({
+            schemaVersion: 1,
+            kind: "token-adoption-proposal",
+            fileId: target.fileId,
+            snapshotHash: check.committed.hash,
+            ownership,
+            live,
+            instructions: "Review live values and declare intentional changes in project themes/extras; regenerate the snapshot. This proposal changes no design or ownership ancestor.",
+        }, null, 2) + "\n";
+        if (context.redact && context.redact(proposal) !== proposal) {
+            throw new Error("Adoption evidence requires credential redaction; no proposal was published");
+        }
+        const out = await resolveProjectOutput(context.root, values.adopt);
+        await mkdir(path.dirname(out), {
+            recursive: true,
+        });
+        await atomicWriteFile(out, proposal);
+        context.output?.result({
+            phase: "adoption-proposed",
+            file: values.adopt,
+            ownership,
+            complete: false,
+        });
+        print(context, "Saved adoption proposal. Review declarations and regenerate the snapshot before pushing; no Penpot write or ancestor update occurred.");
+        return 3;
+    }
+    const plan = planPush(check.committed, live, {
+        prune: values.prune === true,
+        ancestor,
+    });
+    if (ownership.blockers.length && !values.overwrite && !values.resume) {
+        context.output?.result({
+            phase: "conflict",
+            ownership,
+            plan,
+            verified: false,
+        });
+        diagnostic(context, `STOP ${ownership.blockers.length} designer/conflicting/untracked token properties need a decision. Use --adopt <new-file.json> for a local review proposal, or inspect --overwrite and explicitly apply it.`);
+        return 2;
+    }
+    if (drift.inSync && plan.length === 0 && !values.resume) {
+        const evidence = JSON.stringify(check.committed);
+        if (context.redact && context.redact(evidence) !== evidence) {
+            throw new Error("Sync evidence requires credential redaction");
+        }
+        if (values.apply) {
+            await saveSyncAncestor(context.root, target.fileId, check.committed, ancestor);
+        }
+        context.output?.result({
+            verified: true,
+            unchanged: true,
+            drift,
+            ownership,
+        });
+        print(context, `ok   Penpot already matches ${summary(check.committed)}; nothing to write`);
         return 0;
     }
-    console.log(`Penpot differs from ${summary(check.committed)}:`);
-    for (const line of formatDrift(drift, impact))
-        console.log(`  ${line}`);
-    console.log("Plan:");
-    for (const line of describePlan(plan))
-        console.log(`  ${line}`);
+    print(context, values.resume
+        ? `Resuming run ${values.resume}; current snapshot: ${summary(check.committed)}`
+        : `Penpot differs from ${summary(check.committed)}:`);
+    for (const line of formatDrift(drift, impact)) {
+        print(context, `  ${line}`);
+    }
+    print(context, "Plan:");
+    for (const line of describePlan(plan)) {
+        print(context, `  ${line}`);
+    }
     if (!values.apply) {
-        console.log("Nothing was written. Run again with --apply to do it.");
-        if (!values.prune && drift.sets.some((s) => s.tokens.some((t) => t.kind === "extra")))
-            console.log("Tokens added by hand are kept unless you add --prune.");
+        context.output?.result({
+            phase: "inspected",
+            ownership,
+            plan,
+            drift,
+            snapshotCurrent: check.current,
+            verified: false,
+        });
+        print(context, "Nothing was written. Run again with --apply to do it.");
+        if (!values.prune && drift.sets.some((s) => s.tokens.some((t) => t.kind === "extra"))) {
+            print(context, "Tokens without a verified ownership ancestor are preserved, including with --prune.");
+        }
         return 0;
     }
-    const report = await context.withPenpot((client) => applyPlan(client, check.committed, plan, (message) => context.log(message)));
-    for (const step of report.steps)
-        console.log(`done ${step}`);
+    const report = await context.withPenpot((client) => applyPlan(client, check.committed, plan, (message) => context.log(message), {
+        prune: values.prune === true,
+        ancestor,
+        expectedFileId: target.fileId,
+        expectedLive: live,
+        journal: {
+            root: context.root,
+            trace: values.trace === true,
+            forceLock: values["force-lock"] === true,
+            runId: values.resume,
+            resume: Boolean(values.resume),
+            redact: context.redact,
+            requireCheckpoint: values.checkpoint === true,
+            ...(values.checkpoint
+                ? {
+                    checkpoint: (runId) => createCheckpoint(client, {
+                        label: "token push",
+                        runId,
+                    }, {
+                        apply: true,
+                    }),
+                }
+                : {}),
+        },
+    }));
+    context.output?.result(report);
+    for (const step of report.steps) {
+        print(context, `done ${step}`);
+    }
     if (report.verified) {
-        console.log(`ok   verified: Penpot now matches the snapshot and no shape moved or was rebound (${report.structureAfter.count} shapes unchanged)`);
+        const evidence = JSON.stringify(check.committed);
+        if (context.redact && context.redact(evidence) !== evidence) {
+            throw new Error("Sync evidence requires credential redaction");
+        }
+        await saveSyncAncestor(context.root, target.fileId, check.committed, ancestor);
+        print(context, `ok   verified: Penpot now matches the snapshot and no shape moved or was rebound (${report.structureAfter.count} shapes unchanged)`);
         return 0;
     }
-    if (!report.structureUnchanged)
-        console.error(`FAIL the shapes changed while pushing tokens (${report.structureBefore.hash} -> ${report.structureAfter.hash}); look at the file before going on`);
-    for (const line of formatDrift(report.drift))
-        console.error(`FAIL still different: ${line}`);
+    if (!report.structureUnchanged) {
+        diagnostic(context, `FAIL the shapes changed while pushing tokens (${report.structureBefore.hash} -> ${report.structureAfter.hash}); look at the file before going on`);
+    }
+    for (const line of formatDrift(report.drift)) {
+        diagnostic(context, `FAIL still different: ${line}`);
+    }
     return 1;
 }
 async function statusCommand(context, args) {
@@ -177,56 +537,237 @@ async function statusCommand(context, args) {
     const check = await checkSnapshotFor(context.root, context.rawConfig, context.config.instance);
     const lines = [];
     let code = 0;
-    lines.push(`Marwes installed: ${Object.entries(check.expectation.installed.versions).map(([n, v]) => `${n} ${v}`).join(", ")}`);
+    lines.push(`Marwes installed: ${Object.entries(check.expectation.installed.versions)
+        .map(([n, v]) => `${n} ${v}`)
+        .join(", ")}`);
     for (const problem of check.expectation.problems) {
         lines.push(`FAIL ${problem}`);
         code = 1;
     }
-    lines.push(check.committed ? `Snapshot (${check.expectation.settings.snapshot}): ${summary(check.committed)}` : `Snapshot: none yet (${check.expectation.settings.snapshot})`);
-    lines.push(check.current ? "ok   the snapshot is current against the installed Marwes and the theme" : `FAIL the snapshot is stale or missing. ${staleAdvice}`);
-    if (!check.current && code === 0)
+    lines.push(check.committed
+        ? `Snapshot (${check.expectation.settings.snapshot}): ${summary(check.committed)}`
+        : `Snapshot: none yet (${check.expectation.settings.snapshot})`);
+    lines.push(check.current
+        ? "ok   the snapshot is current against the installed Marwes and the theme"
+        : `FAIL the snapshot is stale or missing. ${staleAdvice}`);
+    if (!check.current && code === 0) {
         code = 2;
+    }
     let drift;
     if (check.committed) {
         try {
             drift = (await readPenpot(context, check.committed, false)).drift;
-            lines.push(drift.inSync ? "ok   Penpot matches the snapshot" : `FAIL Penpot differs from the snapshot (${drift.sets.reduce((n, s) => n + s.tokens.length, 0)} token(s), ${drift.themes.length} theme(s)); see \`penpair marwes tokens diff\``);
-            if (!drift.inSync && code === 0)
+            lines.push(drift.inSync
+                ? "ok   Penpot matches the snapshot"
+                : `FAIL Penpot differs from the snapshot (${drift.sets.reduce((n, s) => n + s.tokens.length, 0)} token(s), ${drift.themes.length} theme(s)); see \`penpair marwes tokens diff\``);
+            if (!drift.inSync && code === 0) {
                 code = 2;
+            }
         }
         catch (error) {
+            if (code === 0) {
+                code = 3;
+            }
             lines.push(`skip Penpot: not checked (${String(error.message).split("\n")[0]})`);
         }
     }
-    if (values.json)
-        console.log(JSON.stringify({ installed: check.expectation.installed.versions, snapshotCurrent: check.current, penpotInSync: drift?.inSync ?? null, exit: code }, null, 2));
-    else
-        for (const line of lines)
-            console.log(line);
+    if (values.json) {
+        print(context, JSON.stringify({
+            installed: check.expectation.installed.versions,
+            snapshotCurrent: check.current,
+            penpotInSync: drift?.inSync ?? null,
+            complete: Boolean(drift),
+            exit: code,
+        }, null, 2));
+    }
+    else {
+        for (const line of lines) {
+            print(context, line);
+        }
+    }
     return code;
 }
 export const marwesCommand = {
     name: "marwes",
     summary: "Marwes tokens in Penpot, and drift from the installed Marwes",
     usage: [
+        "penpair marwes theme lint [--json]              advisory family/default hue gaps; no design writes",
+        "penpair marwes tokens schema | migrate --from FILE --ownership FILE [--out NEW_FILE]   schema and explicit legacy migration",
         "penpair marwes tokens snapshot [--write]       build the expected Penpot tokens from the installed Marwes and your theme; --write saves the snapshot",
+        "penpair marwes tokens preview --from SNAPSHOT --theme NAME [--out FILE]  offline projected values; no native bindings or live selection changes",
+        "penpair marwes tokens migrate --from LEGACY --ownership MAP [--out NEW_FILE]  explicit offline ownership upgrade",
         "penpair marwes tokens check [--json]           offline, for CI: is the committed snapshot current? (exit 2 when stale)",
         "penpair marwes tokens diff [--json]            Penpot against the snapshot: missing, changed, added by hand, and what each change reaches",
-        "penpair marwes tokens push [--apply] [--prune] bring Penpot to the snapshot (looks first; --apply writes; --prune also removes what is not expected)",
+        "penpair marwes tokens push [--apply] [--prune] inspect reconciliation; --apply writes, --overwrite resolves value conflicts, --prune removes owned retired tokens; --adopt FILE proposes local declarations",
+        "penpair marwes tokens diff --resolved [--apply] verify actual values in isolated themes and restore the complete original selection",
+        "penpair marwes tokens verify-modes ID --page PAGE --out DIR [--apply] capture stable per-mode PNG evidence and restore selection",
+        "penpair marwes components snapshot [--write] | check [--measure] | diff — explicit three-component measurement pilot; native generation gated",
         "penpair marwes tokens status                   one screen: installed Marwes, snapshot, Penpot",
     ],
     async run(context, args) {
         const [area, sub, ...rest] = args;
+        if (area === "theme" && sub === "lint") {
+            if (rest.some((value) => value !== "--json")) {
+                throw new Error("theme lint accepts only --json");
+            }
+            const expected = await computeExpectation(context.root, context.rawConfig, context.config.instance);
+            if (expected.problems.length) {
+                throw new Error(expected.problems.join("; "));
+            }
+            const defaults = buildSnapshot({
+                core: expected.installed.core,
+                version: expected.installed.version,
+                name: expected.settings.name,
+                generatedBy: `@penpair/marwes-ui@${adapterVersion}`,
+            });
+            const report = lintThemeFamily(defaults, expected.fresh, expected.settings.themeLint);
+            context.output?.result(report);
+            print(context, JSON.stringify(report, null, 2));
+            return 0;
+        }
+        if (area === "components") {
+            return componentsCommand(context, args.slice(1));
+        }
         if (area !== "tokens" || !sub) {
-            console.error(`usage:\n  ${marwesCommand.usage.join("\n  ")}`);
+            diagnostic(context, `usage:\n  ${marwesCommand.usage.join("\n  ")}`);
             return 1;
         }
-        const commands = { snapshot: snapshotCommand, check: checkCommand, diff: diffCommand, push: pushCommand, status: statusCommand };
+        if (sub === "schema") {
+            if (rest.some((value) => value !== "--json")) {
+                throw new Error("tokens schema accepts only --json");
+            }
+            context.output?.result(tokenSnapshotSchema);
+            print(context, JSON.stringify(tokenSnapshotSchema, null, 2));
+            return 0;
+        }
+        if (sub === "preview") {
+            const { values, positionals } = flags(rest);
+            if (positionals.length ||
+                !values.from ||
+                !values.theme ||
+                Object.keys(values).some((key) => ![
+                    "from",
+                    "theme",
+                    "out",
+                    "json",
+                ].includes(key))) {
+                throw new Error("tokens preview --from SNAPSHOT --theme NAME [--out FILE]");
+            }
+            const snapshot = await readSnapshot(context.root, values.from);
+            if (!snapshot) {
+                throw new Error("Preview source snapshot does not exist");
+            }
+            const preview = {
+                ...projectTheme(snapshot, values.theme),
+                sourceSnapshotHash: snapshot.hash,
+            };
+            if (values.out) {
+                const target = await resolveProjectOutput(context.root, values.out);
+                if (target === (await resolveProjectInput(context.root, values.from))) {
+                    throw new Error("Preview cannot overwrite its source snapshot");
+                }
+                await mkdir(path.dirname(target), {
+                    recursive: true,
+                });
+                await atomicWriteFile(target, JSON.stringify(preview, null, 2) + "\n");
+            }
+            context.output?.result(preview);
+            print(context, JSON.stringify(preview, null, 2));
+            return preview.complete ? 0 : 3;
+        }
+        if (sub === "migrate") {
+            const { values, positionals } = flags(rest);
+            if (positionals.length ||
+                !values.from ||
+                !values.ownership ||
+                Object.keys(values).some((k) => ![
+                    "from",
+                    "ownership",
+                    "out",
+                    "json",
+                ].includes(k))) {
+                throw new Error("tokens migrate --from LEGACY_JSON --ownership SET_OWNERS_JSON [--out NEW_FILE]");
+            }
+            const migrated = migrateTokenSnapshot(await readDesignJson(context.root, values.from), (await readDesignJson(context.root, values.ownership)));
+            if (values.out) {
+                const target = await resolveProjectOutput(context.root, values.out);
+                await mkdir(path.dirname(target), {
+                    recursive: true,
+                });
+                await atomicWriteFile(target, JSON.stringify(migrated, null, 2) + "\n");
+            }
+            context.output?.result(migrated);
+            print(context, JSON.stringify(migrated, null, 2));
+            return 0;
+        }
+        const commands = {
+            snapshot: snapshotCommand,
+            check: checkCommand,
+            diff: diffCommand,
+            push: pushCommand,
+            status: statusCommand,
+            "verify-modes": (context, args) => modeCommand(context, args, flags(args).positionals[0]),
+        };
         const run = commands[sub];
         if (!run) {
-            console.error(`unknown: penpair marwes tokens ${sub}\nusage:\n  ${marwesCommand.usage.join("\n  ")}`);
+            diagnostic(context, `unknown: penpair marwes tokens ${sub}\nusage:\n  ${marwesCommand.usage.join("\n  ")}`);
             return 1;
         }
+        const parsed = flags(rest);
+        const allowed = new Set([
+            "json",
+            ...(sub === "snapshot"
+                ? [
+                    "write",
+                ]
+                : sub === "push"
+                    ? [
+                        "apply",
+                        "prune",
+                        "resume",
+                        "checkpoint",
+                        "force-lock",
+                        "trace",
+                        "overwrite",
+                        "adopt",
+                    ]
+                    : sub === "diff"
+                        ? [
+                            "resolved",
+                            "apply",
+                            "resume",
+                            "checkpoint",
+                            "force-lock",
+                        ]
+                        : sub === "verify-modes"
+                            ? [
+                                "page",
+                                "out",
+                                "apply",
+                                "resume",
+                                "checkpoint",
+                                "force-lock",
+                            ]
+                            : []),
+        ]);
+        if (sub === "verify-modes" ? parsed.positionals.length !== 1 : parsed.positionals.length) {
+            throw new Error("Unexpected positional arguments after the token subcommand");
+        }
+        for (const key of Object.keys(parsed.values)) {
+            if (!allowed.has(key)) {
+                throw new Error(`--${key} is not supported by tokens ${sub}`);
+            }
+        }
+        if (sub === "diff" &&
+            !parsed.values.resolved &&
+            [
+                parsed.values.apply,
+                parsed.values.resume,
+                parsed.values.checkpoint,
+                parsed.values["force-lock"],
+            ].some(Boolean)) {
+            throw new Error("Mode write flags require diff --resolved");
+        }
         return run(context, rest);
     },
 };