fritzkit 0.0.0-stage → 0.1.0

package/dist/core/export/install.js

@@ -0,0 +1,183 @@
+/**
+ * Install a part the way Fritzing's own .fzpz import lays it out:
+ *
+ *   <userPartsDir>/<moduleId>/<moduleId>.fzp           (the "part." prefix stripped)
+ *   <userPartsDir>/<moduleId>/<view>/<base>_<view>.svg  (the "svg.<view>." prefix stripped)
+ *
+ * plus an instance in Documents/Fritzing/bins/my_parts.fzb (updateBin, default on).
+ * Verified on Fritzing 1.0.7b: the My Parts bin shows only what my_parts.fzb lists (it is
+ * not rebuilt from local_parts/user), and an instance whose path is the absolute fzp path
+ * makes the part appear there after a restart. Fritzing must be closed: it reads
+ * my_parts.fzb and local_parts only at startup and rewrites the bin file on exit.
+ */
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { isFritzingRunning, fritzingPaths } from "../fritzing.js";
+import { MODULE_ID_RE } from "../identity.js";
+import { VIEWS } from "../compile/types.js";
+import { addBinInstance, readBin, writeBin, writeFileAtomic } from "./bin.js";
+import { parseFzpInfo, readFzpz } from "./fzpz.js";
+export class FritzingRunningError extends Error {
+    constructor(action = "install") {
+        super(`Fritzing is running; ${action} needs Fritzing closed. Fritzing reads my_parts.fzb ` +
+            `and local_parts only at startup (it would not see the change) and rewrites the bin ` +
+            `file on exit (it would overwrite the my_parts.fzb edit). Close Fritzing and retry, ` +
+            `or pass force to do it anyway.`);
+        this.name = "FritzingRunningError";
+    }
+}
+/** Windows device names, which stay devices even with an extension (e.g. NUL.abcdef). */
+const WINDOWS_DEVICE_RE = /^(con|prn|aux|nul|com\d|lpt\d)(\..*)?$/i;
+/**
+ * Throw unless moduleId is a safe single path segment (checked before any fs call). A
+ * trailing "." is refused because Windows strips it, so "x-12345678." would alias the
+ * folder "x-12345678".
+ */
+export function assertSafeModuleId(moduleId) {
+    if (typeof moduleId !== "string" ||
+        !MODULE_ID_RE.test(moduleId) ||
+        /^\.+$/.test(moduleId) ||
+        moduleId.endsWith(".") ||
+        WINDOWS_DEVICE_RE.test(moduleId)) {
+        throw new Error(`unsafe moduleId "${moduleId}": only letters, digits, "-", "_" and "." are allowed ` +
+            `(no trailing ".", no Windows device name)`);
+    }
+}
+/** Absolute dir of a part inside userPartsDir; throws if it would escape the folder. */
+export function partDirFor(userPartsDir, moduleId) {
+    assertSafeModuleId(moduleId);
+    const root = resolve(userPartsDir);
+    const dir = resolve(root, moduleId);
+    if (!dir.startsWith(root + sep) || dir.slice(root.length + 1) !== moduleId) {
+        throw new Error(`moduleId "${moduleId}" resolves outside ${root}`);
+    }
+    return dir;
+}
+/**
+ * Entry names are single file names. Third-party parts use spaces, parentheses and "+"
+ * (e.g. "Adafruit 4980 NeoKey 1x4 QT I2C"), so only what Windows forbids or what could
+ * escape the folder is rejected: / \ : * ? " < > |, control chars, empty dot segments
+ * (".." included) and a trailing dot or space.
+ */
+// eslint-disable-next-line no-control-regex
+const UNSAFE_NAME_CHARS = /[/\\:*?"<>|\x00-\x1f\x7f]/;
+export function isSafeEntryName(name) {
+    return (name !== "" &&
+        !UNSAFE_NAME_CHARS.test(name) &&
+        !name.split(".").some((s) => s === "") &&
+        !/[. ]$/.test(name));
+}
+function fzpOf(entries) {
+    const fzps = entries.filter((e) => /\.fzp$/i.test(e.name));
+    if (fzps.length !== 1)
+        throw new Error(`expected exactly one .fzp entry, got ${fzps.length}`);
+    return fzps[0];
+}
+/**
+ * Pure: where every entry goes. The folder name is the moduleId read from the fzp
+ * content; entry names map `part.X.fzp` -> `X.fzp` and `svg.<view>.Y.svg` -> `<view>/Y.svg`.
+ * Rejects any entry name with a path separator, `..` or other unsafe characters (a sign
+ * of a hostile archive). Other entries (readme, unknown view) are listed in `ignored` and
+ * not written: Fritzing's importer (moveToPartsFolder) likewise only copies part.* and
+ * the svg.* files the fzp references, and silently skips the rest.
+ */
+export function plannedInstallLayout(entries, paths) {
+    const fzpEntry = fzpOf(entries);
+    const { moduleId } = parseFzpInfo(new TextDecoder().decode(fzpEntry.data));
+    const dir = partDirFor(paths.userPartsDir, moduleId);
+    const files = {};
+    const ignored = [];
+    let fzpPath = "";
+    for (const e of entries) {
+        if (!isSafeEntryName(e.name)) {
+            throw new Error(`unsafe .fzpz entry name "${e.name}"`);
+        }
+        let target;
+        const svg = /^svg\.([a-z]+)\.(.+\.svg)$/i.exec(e.name);
+        if (e === fzpEntry) {
+            target = resolve(dir, e.name.replace(/^part\./, ""));
+            fzpPath = target;
+        }
+        else if (svg) {
+            const view = svg[1];
+            if (!VIEWS.includes(view)) {
+                ignored.push(e.name);
+                continue;
+            }
+            target = resolve(dir, view, svg[2]);
+        }
+        else {
+            ignored.push(e.name);
+            continue;
+        }
+        if (!target.startsWith(dir + sep))
+            throw new Error(`entry "${e.name}" escapes ${dir}`);
+        if (Object.values(files).includes(target)) {
+            throw new Error(`two entries install to ${target}`);
+        }
+        files[e.name] = target;
+    }
+    return { moduleId, dir, fzpPath, files, ignored };
+}
+/**
+ * The `path` attribute written into the bin instance. Default: the absolute installed
+ * fzp path with forward slashes, verified on Fritzing 1.0.7b to make the part appear in
+ * My Parts after a restart. (search.fzb/core.fzb use the bare file name for core parts.)
+ */
+export function binInstancePath(fzpAbs, _moduleId) {
+    return fzpAbs.replace(/\\/g, "/");
+}
+export async function installPart(source, opts = {}) {
+    const paths = opts.paths ?? fritzingPaths();
+    const entries = typeof source === "string" ? (await readFzpz(source)).entries : source.entries;
+    const layout = plannedInstallLayout(entries, paths);
+    // Every image the fzp points at must be one of the files we install.
+    const info = parseFzpInfo(new TextDecoder().decode(fzpOf(entries).data));
+    const targets = new Set(Object.values(layout.files));
+    for (const [view, image] of Object.entries(info.images)) {
+        if (!targets.has(resolve(layout.dir, image))) {
+            throw new Error(`fzp ${view}View image "${image}" is not among the .fzpz entries`);
+        }
+    }
+    const alreadyInstalled = existsSync(layout.fzpPath);
+    const binPath = paths.myPartsBin;
+    let newXml;
+    if (opts.updateBin !== false) {
+        const bin = await readBin(binPath);
+        const instancePath = (opts.instancePath ?? binInstancePath)(layout.fzpPath, layout.moduleId);
+        const xml = addBinInstance(bin.xml, { moduleIdRef: layout.moduleId, path: instancePath });
+        if (xml !== bin.xml || !existsSync(binPath))
+            newXml = xml;
+    }
+    const binUpdated = newXml !== undefined;
+    const result = {
+        moduleId: layout.moduleId,
+        installedDir: layout.dir,
+        files: Object.values(layout.files),
+        binPath,
+        alreadyInstalled,
+        binUpdated,
+        ignoredEntries: layout.ignored,
+        warnings: layout.ignored.map((n) => `ignored .fzpz entry "${n}" (not part.*.fzp or svg.<view>.*.svg; Fritzing skips it too)`),
+    };
+    if (opts.dryRun)
+        return { ...result, skipped: "dry run" };
+    if (!opts.force && (await (opts.isRunning ?? isFritzingRunning)())) {
+        throw new FritzingRunningError("install");
+    }
+    for (const e of entries) {
+        const target = layout.files[e.name];
+        if (target !== undefined)
+            await writeFileAtomic(target, e.data);
+    }
+    if (newXml !== undefined) {
+        const bak = await writeBin(binPath, newXml, {
+            backup: opts.backupBin !== false,
+            now: opts.now,
+        });
+        if (bak)
+            result.binBackupPath = bak;
+    }
+    return result;
+}
+//# sourceMappingURL=install.js.map

package/dist/core/export/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../src/core/export/install.ts"],"names":[],"mappings":"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"}

package/dist/core/export/prune.d.ts

@@ -0,0 +1,72 @@
+import { type FritzingPaths } from "../fritzing.js";
+export interface InstalledPart {
+    moduleId: string;
+    /** Absolute folder under userPartsDir. */
+    dir: string;
+    fzpPath: string;
+    family?: string;
+    variant?: string;
+    title?: string;
+    /** `<version>` of the fzp, when numeric. */
+    version?: number;
+}
+/**
+ * Scan userPartsDir: one entry per folder holding an fzp. Uses `<dir>/<dir>.fzp`, else the
+ * single *.fzp in the folder. Folders without an fzp (aborted imports), with several
+ * candidate fzps, or with an unparsable fzp are skipped. Sorted by folder name.
+ */
+export declare function listInstalledParts(paths?: Pick<FritzingPaths, "userPartsDir">): Promise<InstalledPart[]>;
+export interface PrunePlanOptions {
+    family: string;
+    /** moduleId(s) to keep. Default: keep only the newest member of the family. */
+    keep?: string | string[];
+    /** Only ever remove moduleIds starting with "fritzkit-" (default true). */
+    onlyFritzkit?: boolean;
+}
+export interface PrunePlan {
+    remove: InstalledPart[];
+    keep: InstalledPart[];
+}
+/**
+ * Pure: split the installed members of a family into remove / keep. "Newest" is decided
+ * from the fzp content only (`<version>`, then the variant string), never file mtimes,
+ * so the plan is deterministic. Parts outside the "fritzkit-" namespace are always kept
+ * when onlyFritzkit is on. Parts of other families are ignored. Throws when a keep id
+ * is not an installed member of the family.
+ */
+export declare function prunePlan(installed: readonly InstalledPart[], opts: PrunePlanOptions): PrunePlan;
+export interface PruneOptions {
+    /** Actually delete; without it prune is a dry run. */
+    yes: boolean;
+    paths?: FritzingPaths;
+    /** Prune even while Fritzing is running. */
+    force?: boolean;
+    /** Remove the pruned parts' instances from my_parts.fzb (default true, see install.ts). */
+    updateBin?: boolean;
+    /** Back the bin up before writing it (default true). */
+    backupBin?: boolean;
+    isRunning?: () => Promise<boolean>;
+    now?: () => Date;
+    /** Injected for tests; defaults to a recursive rm. */
+    removeDir?: (dir: string) => Promise<void>;
+}
+export interface PruneResult {
+    /** Folders removed (or that would be removed on a dry run). */
+    removedDirs: string[];
+    /** moduleIds whose bin instances were removed (or would be); empty with updateBin: false. */
+    removedBinEntries: string[];
+    dryRun: boolean;
+    binBackupPath?: string;
+    /** Folders that could not be removed; their bin instances are kept. */
+    failed: {
+        dir: string;
+        moduleId: string;
+        error: string;
+    }[];
+}
+/**
+ * Execute a plan. Dry run unless opts.yes. Only deletes a folder whose resolved path is
+ * directly under userPartsDir and whose name equals the moduleId being pruned; every
+ * check runs for every part before the first deletion.
+ */
+export declare function prune(plan: PrunePlan, opts: PruneOptions): Promise<PruneResult>;

package/dist/core/export/prune.js

@@ -0,0 +1,165 @@
+/**
+ * List and prune installed parts. Every export gets a new moduleId (identity D12), so a
+ * part iterated N times leaves N folders in local_parts/user; prune removes the old ones
+ * of one family together with their my_parts.fzb instances (updateBin, default on).
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile, rm, stat } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { isFritzingRunning, fritzingPaths } from "../fritzing.js";
+import { readBin, removeBinInstances, writeBin } from "./bin.js";
+import { parseFzpInfo } from "./fzpz.js";
+import { assertSafeModuleId, FritzingRunningError, partDirFor } from "./install.js";
+/**
+ * Scan userPartsDir: one entry per folder holding an fzp. Uses `<dir>/<dir>.fzp`, else the
+ * single *.fzp in the folder. Folders without an fzp (aborted imports), with several
+ * candidate fzps, or with an unparsable fzp are skipped. Sorted by folder name.
+ */
+export async function listInstalledParts(paths = fritzingPaths()) {
+    const root = resolve(paths.userPartsDir);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    const dirents = await readdir(root, { withFileTypes: true });
+    for (const d of dirents.filter((x) => x.isDirectory()).sort((a, b) => cmp(a.name, b.name))) {
+        const dir = join(root, d.name);
+        const fzps = (await readdir(dir)).filter((f) => /\.fzp$/i.test(f));
+        const name = fzps.includes(`${d.name}.fzp`)
+            ? `${d.name}.fzp`
+            : fzps.length === 1
+                ? fzps[0]
+                : undefined;
+        if (!name)
+            continue;
+        const fzpPath = join(dir, name);
+        try {
+            if (!(await stat(fzpPath)).isFile())
+                continue;
+            const info = parseFzpInfo(await readFile(fzpPath, "utf8"));
+            const part = { moduleId: info.moduleId, dir, fzpPath };
+            if (info.family !== undefined)
+                part.family = info.family;
+            if (info.variant !== undefined)
+                part.variant = info.variant;
+            if (info.title !== undefined)
+                part.title = info.title;
+            const v = Number(info.version);
+            if (info.version !== undefined && Number.isFinite(v))
+                part.version = v;
+            out.push(part);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Version number of a part: `<version>`, else the N of a "vN ..." variant, else 0. */
+function versionOf(p) {
+    if (p.version !== undefined)
+        return p.version;
+    const m = /^v(\d+(?:\.\d+)?)\b/.exec(p.variant ?? "");
+    return m ? Number(m[1]) : 0;
+}
+/** Newest first: higher version, then variant string, then moduleId (descending). */
+function newerFirst(a, b) {
+    return (versionOf(b) - versionOf(a) ||
+        cmp(b.variant ?? "", a.variant ?? "") ||
+        cmp(b.moduleId, a.moduleId));
+}
+/**
+ * Pure: split the installed members of a family into remove / keep. "Newest" is decided
+ * from the fzp content only (`<version>`, then the variant string), never file mtimes,
+ * so the plan is deterministic. Parts outside the "fritzkit-" namespace are always kept
+ * when onlyFritzkit is on. Parts of other families are ignored. Throws when a keep id
+ * is not an installed member of the family.
+ */
+export function prunePlan(installed, opts) {
+    const onlyFritzkit = opts.onlyFritzkit !== false;
+    const members = installed.filter((p) => p.family === opts.family).sort(newerFirst);
+    const protectedParts = onlyFritzkit
+        ? members.filter((p) => !p.moduleId.startsWith("fritzkit-"))
+        : [];
+    const candidates = members.filter((p) => !protectedParts.includes(p));
+    let keepIds;
+    if (opts.keep !== undefined) {
+        keepIds = new Set(Array.isArray(opts.keep) ? opts.keep : [opts.keep]);
+        // A mistyped keep id would otherwise silently plan the removal of every version.
+        const unknown = [...keepIds].filter((id) => !members.some((p) => p.moduleId === id));
+        if (unknown.length > 0) {
+            throw new Error(`keep: ${unknown.map((id) => `"${id}"`).join(", ")} is not an installed member of ` +
+                `family "${opts.family}"`);
+        }
+    }
+    else {
+        keepIds = new Set(candidates.slice(0, 1).map((p) => p.moduleId));
+    }
+    return {
+        remove: candidates.filter((p) => !keepIds.has(p.moduleId)),
+        keep: members.filter((p) => keepIds.has(p.moduleId) || protectedParts.includes(p)),
+    };
+}
+/**
+ * Execute a plan. Dry run unless opts.yes. Only deletes a folder whose resolved path is
+ * directly under userPartsDir and whose name equals the moduleId being pruned; every
+ * check runs for every part before the first deletion.
+ */
+export async function prune(plan, opts) {
+    const paths = opts.paths ?? fritzingPaths();
+    const root = resolve(paths.userPartsDir);
+    const targets = [];
+    for (const p of plan.remove) {
+        assertSafeModuleId(p.moduleId);
+        const dir = partDirFor(root, p.moduleId);
+        if (resolve(p.dir) !== dir || !dir.startsWith(root + sep)) {
+            throw new Error(`refusing to prune ${p.dir}: it is not ${dir} (folder name must equal moduleId)`);
+        }
+        targets.push({ dir, moduleId: p.moduleId });
+    }
+    const bin = opts.updateBin !== false ? await readBin(paths.myPartsBin) : undefined;
+    const inBin = (ids) => bin
+        ? [...new Set(bin.instances.filter((i) => ids.has(i.moduleIdRef)).map((i) => i.moduleIdRef))]
+        : [];
+    const existing = targets.filter((t) => existsSync(t.dir));
+    if (!opts.yes) {
+        return {
+            removedDirs: existing.map((t) => t.dir),
+            removedBinEntries: inBin(new Set(targets.map((t) => t.moduleId))),
+            dryRun: true,
+            failed: [],
+        };
+    }
+    if (!opts.force && (await (opts.isRunning ?? isFritzingRunning)())) {
+        throw new FritzingRunningError("prune");
+    }
+    // Folders first; only ids whose folder is really gone leave the bin, so a failed rm
+    // never leaves a bin that disagrees with the parts folder.
+    const removeDir = opts.removeDir ?? ((dir) => rm(dir, { recursive: true, force: true }));
+    const result = { removedDirs: [], removedBinEntries: [], dryRun: false, failed: [] };
+    const gone = new Set(targets.filter((t) => !existsSync(t.dir)).map((t) => t.moduleId));
+    for (const t of existing) {
+        try {
+            await removeDir(t.dir);
+            result.removedDirs.push(t.dir);
+            gone.add(t.moduleId);
+        }
+        catch (e) {
+            result.failed.push({ ...t, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    result.removedBinEntries = inBin(gone);
+    if (bin && result.removedBinEntries.length > 0) {
+        const xml = removeBinInstances(bin.xml, (i) => gone.has(i.moduleIdRef));
+        const bak = await writeBin(paths.myPartsBin, xml, {
+            backup: opts.backupBin !== false,
+            now: opts.now,
+        });
+        if (bak)
+            result.binBackupPath = bak;
+    }
+    return result;
+}
+//# sourceMappingURL=prune.js.map

package/dist/core/export/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../../src/core/export/prune.ts"],"names":[],"mappings":"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"}

package/dist/core/fritzing.d.ts

@@ -0,0 +1,22 @@
+export interface FritzingPaths {
+    /** Fritzing executable, or undefined when not found. */
+    exe?: string;
+    /** Folder holding fzp_checker.py and core/, or undefined. */
+    partsLibrary?: string;
+    /** %APPDATA%/Fritzing/Fritzing/local_parts/user - where imported parts live. */
+    userPartsDir: string;
+    /** ~/Documents/Fritzing/bins/my_parts.fzb - the My Parts bin. */
+    myPartsBin: string;
+    binsDir: string;
+}
+export declare function fritzingPaths(env?: NodeJS.ProcessEnv): FritzingPaths;
+export type FritzingRunState = "running" | "stopped" | "unknown";
+/** Whether a Fritzing process is running; "unknown" when the process list cannot be read. */
+export declare function fritzingRunState(): Promise<FritzingRunState>;
+/**
+ * True unless Fritzing is known to be stopped. Fails CLOSED: install and prune must not
+ * touch Fritzing's user folders when the process list cannot be read.
+ */
+export declare function isFritzingRunning(): Promise<boolean>;
+/** File version of Fritzing.exe (Windows), e.g. "1.0.7.0"; undefined elsewhere. */
+export declare function fritzingVersion(exe: string | undefined): Promise<string | undefined>;

package/dist/core/fritzing.js

@@ -0,0 +1,77 @@
+/**
+ * Where Fritzing lives on this machine and whether it is running. Shared by install,
+ * prune, doctor and the e2e harness. Windows first (the only tested platform);
+ * macOS/Linux paths are best-effort guesses that doctor reports as unverified.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+export function fritzingPaths(env = process.env) {
+    const home = env.USERPROFILE ?? homedir();
+    const appData = env.APPDATA ?? join(home, "AppData", "Roaming");
+    const candidates = process.platform === "win32"
+        ? [
+            join(env.ProgramFiles ?? "C:\\Program Files", "Fritzing", "Fritzing.exe"),
+            join(env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)", "Fritzing", "Fritzing.exe"),
+            join(env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "Programs", "Fritzing", "Fritzing.exe"),
+        ]
+        : process.platform === "darwin"
+            ? ["/Applications/Fritzing.app/Contents/MacOS/Fritzing"]
+            : ["/usr/bin/Fritzing", "/usr/local/bin/Fritzing", "/opt/fritzing/Fritzing"];
+    const exe = env.FRITZKIT_FRITZING_EXE ?? candidates.find((c) => existsSync(c));
+    const partsLibrary = exe
+        ? [join(exe, "..", "fritzing-parts"), join(exe, "..", "..", "fritzing-parts")].find((p) => existsSync(join(p, "fzp_checker.py")))
+        : undefined;
+    const userPartsDir = process.platform === "win32"
+        ? join(appData, "Fritzing", "Fritzing", "local_parts", "user")
+        : process.platform === "darwin"
+            ? join(home, "Library", "Application Support", "Fritzing", "Fritzing", "local_parts", "user")
+            : join(home, ".local", "share", "Fritzing", "Fritzing", "local_parts", "user");
+    const binsDir = join(home, "Documents", "Fritzing", "bins");
+    return { exe, partsLibrary, userPartsDir, binsDir, myPartsBin: join(binsDir, "my_parts.fzb") };
+}
+/** Whether a Fritzing process is running; "unknown" when the process list cannot be read. */
+export async function fritzingRunState() {
+    try {
+        if (process.platform === "win32") {
+            const { stdout } = await execFileP("tasklist", ["/FI", "IMAGENAME eq Fritzing.exe", "/NH"]);
+            return /Fritzing\.exe/i.test(stdout) ? "running" : "stopped";
+        }
+        const { stdout } = await execFileP("pgrep", ["-ix", "fritzing"]);
+        return stdout.trim().length > 0 ? "running" : "stopped";
+    }
+    catch (err) {
+        // pgrep exits 1 when nothing matches; anything else means we could not tell.
+        const code = err.code;
+        if (process.platform !== "win32" && code === 1)
+            return "stopped";
+        return "unknown";
+    }
+}
+/**
+ * True unless Fritzing is known to be stopped. Fails CLOSED: install and prune must not
+ * touch Fritzing's user folders when the process list cannot be read.
+ */
+export async function isFritzingRunning() {
+    return (await fritzingRunState()) !== "stopped";
+}
+/** File version of Fritzing.exe (Windows), e.g. "1.0.7.0"; undefined elsewhere. */
+export async function fritzingVersion(exe) {
+    if (!exe || process.platform !== "win32")
+        return undefined;
+    try {
+        const { stdout } = await execFileP("powershell", [
+            "-NoProfile",
+            "-Command",
+            `(Get-Item '${exe.replace(/'/g, "''")}').VersionInfo.ProductVersion`,
+        ]);
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=fritzing.js.map

package/dist/core/fritzing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fritzing.js","sourceRoot":"","sources":["../../src/core/fritzing.ts"],"names":[],"mappings":"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"}

package/dist/core/identity.d.ts

@@ -0,0 +1,29 @@
+import type { PartSpec } from "./schema/part.js";
+export declare const MODULE_ID_RE: RegExp;
+export interface Asset {
+    /** Path relative to the part folder, forward slashes, e.g. "assets/top.png". */
+    name: string;
+    data: Uint8Array;
+}
+export interface PartIdentity {
+    moduleId: string;
+    family: string;
+    variant: string;
+    hash8: string;
+    /** Base file name used for every SVG and the fzp inside the .fzpz. */
+    baseName: string;
+}
+/** JSON with recursively sorted object keys; arrays keep their order. */
+export declare function canonicalJson(value: unknown): string;
+export declare function contentHash(spec: PartSpec, assets?: Asset[]): string;
+export declare function identityFor(spec: PartSpec, assets?: Asset[]): PartIdentity;
+/** Zip entry names inside a .fzpz for a given identity (flat, no folders). */
+export declare function fzpzEntryNames(id: PartIdentity): {
+    readonly fzp: `part.${string}.fzp`;
+    readonly breadboard: `svg.breadboard.${string}_breadboard.svg`;
+    readonly schematic: `svg.schematic.${string}_schematic.svg`;
+    readonly pcb: `svg.pcb.${string}_pcb.svg`;
+    readonly icon: `svg.icon.${string}_icon.svg`;
+};
+/** The <layers image="..."> value for a view; must match the zip entry after Fritzing's rewrite. */
+export declare function layerImage(id: PartIdentity, view: "breadboard" | "schematic" | "pcb" | "icon"): string;

package/dist/core/identity.js

@@ -0,0 +1,70 @@
+/**
+ * Part identity (decisions D12 / D12a).
+ *
+ * moduleId = fritzkit-<slug>-<hash8>   unique per exported content; Fritzing refuses a
+ *                                       duplicate moduleId, so every change gets a new one
+ * family   = spec.family ?? slug        stable across versions (Inspector swap group)
+ * variant  = v<version> <hash8>         unique per export, differs between family members
+ *
+ * hash8 = first 8 hex chars of sha256 over the canonical spec JSON (sorted keys,
+ * $schema dropped) followed by every asset file (name + bytes, sorted by name).
+ */
+import { createHash } from "node:crypto";
+export const MODULE_ID_RE = /^[A-Za-z0-9_.-]{8,}$/;
+/** JSON with recursively sorted object keys; arrays keep their order. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const val = v[k];
+            if (val !== undefined)
+                out[k] = sortKeys(val);
+        }
+        return out;
+    }
+    return v;
+}
+export function contentHash(spec, assets = []) {
+    const h = createHash("sha256");
+    const { $schema: _schema, ...rest } = spec;
+    h.update(canonicalJson(rest));
+    for (const a of [...assets].sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))) {
+        h.update("\0" + a.name + "\0");
+        h.update(a.data);
+    }
+    return h.digest("hex");
+}
+export function identityFor(spec, assets = []) {
+    const hash8 = contentHash(spec, assets).slice(0, 8);
+    const moduleId = `fritzkit-${spec.slug}-${hash8}`;
+    if (!MODULE_ID_RE.test(moduleId)) {
+        throw new Error(`moduleId "${moduleId}" is not filename-safe`);
+    }
+    return {
+        moduleId,
+        family: spec.family ?? spec.slug,
+        variant: `v${spec.version} ${hash8}`,
+        hash8,
+        baseName: moduleId,
+    };
+}
+/** Zip entry names inside a .fzpz for a given identity (flat, no folders). */
+export function fzpzEntryNames(id) {
+    return {
+        fzp: `part.${id.moduleId}.fzp`,
+        breadboard: `svg.breadboard.${id.baseName}_breadboard.svg`,
+        schematic: `svg.schematic.${id.baseName}_schematic.svg`,
+        pcb: `svg.pcb.${id.baseName}_pcb.svg`,
+        icon: `svg.icon.${id.baseName}_icon.svg`,
+    };
+}
+/** The <layers image="..."> value for a view; must match the zip entry after Fritzing's rewrite. */
+export function layerImage(id, view) {
+    return `${view}/${id.baseName}_${view}.svg`;
+}
+//# sourceMappingURL=identity.js.map