@penpair/marwes-ui 0.1.3 → 0.3.0

package/dist/ownership.js

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteFile, ensureGitignoreEntry, resolveProjectInput, resolveProjectOutput, } from "@penpair/core";
+import { canonical, normalizeValue } from "./tokens.js";
+const tokenMap = (sets) => new Map(sets.map((set) => [
+    set.name,
+    new Map(set.tokens.map((token) => [
+        token.name,
+        token,
+    ])),
+]));
+const values = (token) => token
+    ? {
+        type: token.type,
+        value: normalizeValue(token.type, token.value),
+        description: token.description || "",
+    }
+    : {
+        type: null,
+        value: null,
+        description: null,
+    };
+/** Report each changed property against a verified ancestor; never guess a rename. */
+export function ownershipReport(desired, live, ancestor) {
+    const wanted = tokenMap(desired.sets);
+    const actual = tokenMap(live.sets);
+    const old = tokenMap(ancestor?.sets ?? []);
+    const changes = [];
+    const unmanagedSets = live.sets
+        .filter((set) => !wanted.has(set.name) && !old.has(set.name))
+        .map((set) => set.name);
+    const unmanagedTokens = [];
+    for (const setName of new Set([
+        ...wanted.keys(),
+        ...old.keys(),
+    ])) {
+        for (const name of new Set([
+            ...(wanted.get(setName)?.keys() ?? []),
+            ...(old.get(setName)?.keys() ?? []),
+        ])) {
+            const a = values(old.get(setName)?.get(name));
+            const d = values(wanted.get(setName)?.get(name));
+            const l = values(actual.get(setName)?.get(name));
+            for (const property of [
+                "type",
+                "value",
+                "description",
+            ]) {
+                const same = (x, y) => canonical(x) === canonical(y);
+                if (same(d[property], l[property])) {
+                    continue;
+                }
+                let kind;
+                if (!ancestor || !old.get(setName)?.has(name)) {
+                    kind = !actual.get(setName)?.has(name) ? "upstream" : "untracked";
+                }
+                else {
+                    const upstream = !same(d[property], a[property]);
+                    const designer = !same(l[property], a[property]);
+                    kind = upstream && designer ? "conflict" : designer ? "designer" : "upstream";
+                }
+                changes.push({
+                    set: setName,
+                    name,
+                    property,
+                    kind,
+                    ancestor: a[property],
+                    desired: d[property],
+                    live: l[property],
+                });
+            }
+        }
+        for (const name of actual.get(setName)?.keys() ?? []) {
+            if (!wanted.get(setName)?.has(name) && !old.get(setName)?.has(name)) {
+                unmanagedTokens.push({
+                    set: setName,
+                    name,
+                });
+            }
+        }
+    }
+    const key = (theme) => canonical([
+        theme.group,
+        theme.name,
+    ]);
+    const previousThemes = new Map((ancestor?.themes ?? []).map((theme) => [
+        key(theme),
+        theme,
+    ]));
+    for (const theme of desired.themes) {
+        const current = live.themes.find((t) => key(t) === key(theme));
+        const previous = previousThemes.get(key(theme));
+        const managed = new Set([
+            ...desired.sets,
+            ...(ancestor?.sets ?? []),
+        ].map((set) => set.name));
+        const orderedMembership = (sets) => sets === undefined ? null : sets.filter((name) => managed.has(name)).sort();
+        const a = orderedMembership(previous?.sets);
+        const d = orderedMembership(theme.sets);
+        const l = orderedMembership(current?.sets);
+        if (canonical(d) === canonical(l)) {
+            continue;
+        }
+        const kind = !previous
+            ? !current
+                ? "upstream"
+                : "untracked"
+            : canonical(l) === canonical(a)
+                ? "upstream"
+                : canonical(d) === canonical(a)
+                    ? "designer"
+                    : "conflict";
+        changes.push({
+            set: "@themes",
+            name: key(theme),
+            property: "membership",
+            kind,
+            ancestor: a,
+            desired: d,
+            live: l,
+        });
+    }
+    return {
+        changes,
+        blockers: changes.filter((change) => change.kind !== "upstream"),
+        unmanagedSets,
+        unmanagedTokens,
+    };
+}
+/** Destruction is conservative across all sets, including those outside adapter ownership. */
+export function assertSafeDestruction(actions, live, bindingCounts = {}) {
+    for (const action of actions) {
+        const names = action.kind === "removeTokens"
+            ? action.names
+            : action.kind === "replaceTokens"
+                ? action.tokens
+                    .filter((token) => live.sets
+                    .find((set) => set.name === action.set)
+                    ?.tokens.find((old) => old.name === token.name)?.type !== token.type)
+                    .map((token) => token.name)
+                : [];
+        for (const name of names) {
+            if ((bindingCounts[name] ?? 0) > 0) {
+                throw new Error(`Cannot remove or change type of ${name}: bound to ${bindingCounts[name]} retained shape(s)`);
+            }
+            for (const set of live.sets) {
+                for (const token of set.tokens) {
+                    if (set.name ===
+                        action.set &&
+                        token.name === name) {
+                        continue;
+                    }
+                    if (JSON.stringify(token.value).includes("{" + name + "}")) {
+                        throw new Error(`Cannot remove or change type of ${name}: referenced by ${set.name}/${token.name}`);
+                    }
+                }
+            }
+        }
+    }
+}
+const ledgerPath = (fileId) => `.penpair/token-sync/${createHash("sha256").update(fileId).digest("hex")}.json`;
+export async function readSyncAncestor(root, fileId) {
+    try {
+        const record = JSON.parse(await readFile(await resolveProjectInput(root, ledgerPath(fileId)), "utf8"));
+        if (record.schemaVersion !== 1 ||
+            record.fileId !== fileId ||
+            record.sha256 !== createHash("sha256").update(canonical(record.snapshot)).digest("hex") ||
+            ![
+                1,
+                2,
+            ].includes(record.snapshot?.schemaVersion) ||
+            !Array.isArray(record.snapshot?.sets) ||
+            !Array.isArray(record.snapshot?.themes)) {
+            throw new Error("Invalid token-sync ancestor; inspect it before replacing it");
+        }
+        return record.snapshot;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function saveSyncAncestor(root, fileId, snapshot, expectedAncestor) {
+    await ensureGitignoreEntry(root, ".penpair", {
+        directory: true,
+        comment: "penpair: private token synchronization evidence",
+    });
+    const destination = await resolveProjectOutput(root, ledgerPath(fileId));
+    await mkdir(path.dirname(destination), {
+        recursive: true,
+        mode: 0o700,
+    });
+    const lockPath = destination + ".lock";
+    const lock = await open(lockPath, "wx", 0o600).catch(() => {
+        throw new Error("Token ancestor is locked; inspect any interrupted local sync before retrying");
+    });
+    try {
+        const current = await readSyncAncestor(root, fileId);
+        if (current &&
+            canonical(current) !== canonical(snapshot) &&
+            canonical(current) !== canonical(expectedAncestor)) {
+            throw new Error("Token ancestor advanced concurrently; newer sync evidence was preserved");
+        }
+        await atomicWriteFile(destination, JSON.stringify({
+            schemaVersion: 1,
+            fileId,
+            savedAt: new Date().toISOString(),
+            sha256: createHash("sha256").update(canonical(snapshot)).digest("hex"),
+            snapshot,
+        }, null, 2) + "\n", {
+            replace: true,
+            mode: 0o600,
+        });
+    }
+    finally {
+        await lock.close();
+        await unlink(lockPath);
+    }
+}

package/dist/penpot.d.ts

@@ -1,4 +1,4 @@
-import { type PenpotToolClient, type Snippet } from "@penpair/core";
+import { type LayoutOptions, type LayoutResult, type JournalOptions, type PenpotToolClient, type Snippet } from "@penpair/core";
 import { canonical, type PenpotToken, type TokenSnapshot } from "./tokens.js";
 /** What the Penpot file holds today. */
 export interface LiveTokens {
@@ -66,7 +66,9 @@ export interface Drift {
     unexpectedSets: string[];
 }
 /** Compares the committed expectation with what the file holds. Only the sets the expectation names are judged; other sets are the project's own. */
-export declare function compareToPenpot(expected: TokenSnapshot, live: LiveTokens): Drift;
+export declare function compareToPenpot(expected: TokenSnapshot, live: LiveTokens, options?: {
+    ancestor?: TokenSnapshot;
+}): Drift;
 export declare function formatDrift(drift: Drift, impact?: Record<string, number>, limit?: number): string[];
 export type Action = {
     kind: "createSet";
@@ -106,12 +108,21 @@ export type Action = {
 export interface PlanOptions {
     /** Also remove what Penpot has but the expectation does not (tokens added by hand, sets no longer expected, extra sets in a theme). */
     prune?: boolean;
+    /** Only tokens in a verified ancestor can be pruned. */
+    ancestor?: TokenSnapshot;
 }
 /** The writes that bring the file to the expectation. Nothing in a set the expectation does not name is ever touched. */
 export declare function planPush(expected: TokenSnapshot, live: LiveTokens, options?: PlanOptions): Action[];
 /** Splits a long token list into batches that stay well under the request limit. */
 export declare function inBatches(tokens: PenpotToken[]): PenpotToken[][];
 export interface ApplyReport {
+    redacted?: boolean;
+    complete?: boolean;
+    layout?: LayoutResult;
+    journal?: {
+        runId: string;
+        state: string;
+    };
     steps: string[];
     structureBefore: {
         count: number;
@@ -131,7 +142,14 @@ export declare function readLive(client: PenpotToolClient): Promise<LiveTokens>;
  * Carries out the plan one write at a time, stopping at the first anomaly, then reads everything back: the file must now match the
  * expectation, and no shape may have moved or been rebound.
  */
-export declare function applyPlan(client: PenpotToolClient, expected: TokenSnapshot, actions: Action[], onStep?: (message: string) => void): Promise<ApplyReport>;
+export declare function applyPlan(client: PenpotToolClient, expected: TokenSnapshot, actions: Action[], onStep?: (message: string) => void, options?: {
+    layout?: false | LayoutOptions;
+    expectedFileId?: string;
+    ancestor?: TokenSnapshot;
+    prune?: boolean;
+    expectedLive?: LiveTokens;
+    journal?: Omit<JournalOptions, "input" | "operation" | "payload" | "target">;
+}): Promise<ApplyReport>;
 /** The use count of every token a drift would change, so a bump can be judged by what it reaches. */
 export declare function impactOf(client: PenpotToolClient): Promise<Record<string, number>>;
 export { canonical };